feat(签署文书): 统一签署态文书样式并精简演示种子为单份麻精同意书

clinical-web/src/utils/signing-document.ts

@@ -53,18 +53,58 @@ const FIELD_LABEL_ATTR = 'data-sign-label'
 const FIELD_REQUIRED_ATTR = 'data-sign-required'
 const FIELD_RISK_ATTR = 'data-sign-risk'
 /**
- * 多选组的标记。渲染时由这里打上，回读取值时靠它区分
- * 「一组多选 checkbox」与「单个勾选框」——两者 DOM 里都是 input[type=checkbox]。
+ * 选项组的标记，渲染时由这里**总是**打上（true / false）。
+ *
+ * 为什么要显式写 false 而不是「有才写」：回读取值时要区分三种形态——
+ * 一组多选、一组单选、以及没有选项的单个勾选框；后两者都可能是
+ * 「没有这个属性 + kind=checkbox」，光看属性在不在分不出来。
+ * 显式落成 true / false 后，「有没有这个属性」就等于「是不是一组选项」。
  */
 const FIELD_MULTI_ATTR = 'data-sign-multi'
 /** 需要宿主接管交互的填写项（目前只有「点击采集签名」），值是动作名 */
 const FIELD_ACTION_ATTR = 'data-sign-action'
 /** 签名位的采集动作名 */
 const SIGNATURE_ACTION = 'signature'
-/** 已采集签名图的类名，readAnswersFromRoot 与写入端都按它找 */
-const SIGNATURE_IMAGE_CLASS = 'sign-doc-signature'
 /** 可点击采集的签名位类名，样式与摘除入口时都要用同一个 */
 const ACTIONABLE_CLASS = 'sign-field--actionable'
+/** 填写项宿主节点类名（原型 .docfld：虚线胶囊 → 填充后去边框） */
+const FIELD_HOST_CLASS = 'docfld'
+/** 已填充标记：去掉"待填写"的视觉暗示 */
+const FIELD_FILLED_CLASS = 'filled'
+/** 空值下划线 */
+const BLANK_CLASS = 'docfld-blank'
+/**
+ * 文本 / 日期填写项的可输入控件类名。
+ *
+ * 原型里这类项是**只读**的：值全部来自 HIS 与患者就诊快照，取不到就留一条下划线。
+ * 但本仓库还有「与患者关系」「受托人姓名」这类没有系统取值来源、必须现场手填的
+ * 自定义文本项（见 utils/signing-fields 的 createCustomField），做成只读等于把
+ * 代理人签署这条路堵死。折中办法是保留输入框、但把外观压成原型那条下划线：
+ * 空着是一条线、填好了是正文，视觉上与原型一致，又没丢能力。
+ */
+const INPUT_CLASS = 'docfld-input'
+/** 签名图类名，readAnswersFromRoot 与写入端都按它找 */
+const SIGNATURE_IMAGE_CLASS = 'docfld-signature'
+/** 单个选项的类名（原型 .docopt） */
+const OPTION_CLASS = 'docopt'
+/** 可点击选项的附加类名（原型 .docopt.tick） */
+const OPTION_TICK_CLASS = 'tick'
+/** 已勾选标记（原型 .docopt.on） */
+const OPTION_ON_CLASS = 'on'
+/** 选项取值的载体属性；表格勾选列与行内方框也用同一个，回读时只认它 */
+const OPTION_VALUE_ATTR = 'data-sign-item'
+/**
+ * 行内方框转换出来的选项所属的组名。
+ * 这些选项散落在正文的文本节点里、没有共同的宿主节点，
+ * 互斥只能靠这个属性在整篇文书里找同组兄弟（见 toggleOptionAt）。
+ */
+const GROUP_ATTR = 'data-sign-group'
+/**
+ * 选项的显示名。与取值标识（data-sign-item）分开存：
+ * 表格勾选列的取值标识是项目名，但那一格显示的是「待患者勾选」。
+ * 切换勾选状态时要按显示名重建文案，所以它必须落成属性，不能从取值推。
+ */
+const OPTION_TEXT_ATTR = 'data-sign-text'
 
 /**
  * 可点击采集签名的填写项宿主节点选择器。
@@ -72,6 +112,13 @@ const ACTIONABLE_CLASS = 'sign-field--actionable'
  */
 export const SIGNATURE_ACTION_SELECTOR = `[${FIELD_ACTION_ATTR}="${SIGNATURE_ACTION}"]`
 
+/**
+ * 可点击切换的选项选择器。
+ * 导出给签署端做事件委托：渲染端决定"哪些选项可点"（.tick），
+ * 签署端只负责把点击转成 toggleOptionAt，两边不能各写一份选择器。
+ */
+export const OPTION_TICK_SELECTOR = `.${OPTION_CLASS}.${OPTION_TICK_CLASS}`
+
 /**
  * 科室手打的复选框符号见 SIGNING_OPTION_MARKERS（utils/signing-fields）：
  * 编辑器标记与这里识别必须用同一份字符集，故不再本地声明。
@@ -179,6 +226,83 @@ function isMultiOptionGroup(field: SigningFieldDef): boolean {
   return isOptionGroupField(field) && (field.multi ?? field.kind === 'checkbox')
 }
 
+/**
+ * 选项的显示文案（原型 fillDocHtml / tickDocOpt 的同一口径）：
+ * 勾选态用 ☑、未勾选用 ☐，空一格后跟选项名。
+ *
+ * 没有选项名的单个勾选框（占位符只写了 kind=checkbox 却没配选项）用固定文案
+ * 说明它的语义——原型就是这么写的，也让科室一眼看出这一处是"待勾"而不是漏了内容。
+ */
+function optionDisplay(value: string, on: boolean): string {
+  const mark = on ? '☑' : '☐'
+
+  if (value) {
+    return `${mark} ${value}`
+  }
+
+  return on ? `${mark} 已勾选（结果固化归档）` : `${mark} 待患者勾选`
+}
+
+/**
+ * 一个选项。
+ *
+ * 刻意用文本而不是 `<input>`：原型的签署态文书里没有任何表单控件，
+ * 选项就是 ☑ / ☐ 两个字符，点击切换类名与文字。这样导出的 HTML
+ * 与纸质文书的观感一致，也不会因为表单控件的默认样式在各浏览器下跑版。
+ * 交互由签署端的事件委托完成（见 toggleOptionAt），所以这里只落一个 .tick 标记。
+ *
+ * displayValue 与 itemValue 分开：表格勾选列的项目名要写进 data-sign-item 当取值标识，
+ * 但那一格显示的是「待患者勾选」——项目名在左边那一列已经写过了，重复一遍反而挤。
+ */
+function buildOptionItem(
+  doc: Document,
+  itemValue: string,
+  on: boolean,
+  interactive: boolean,
+  displayValue: string = itemValue,
+): HTMLElement {
+  const item = doc.createElement('span')
+  item.className = [
+    OPTION_CLASS,
+    on ? OPTION_ON_CLASS : '',
+    interactive ? OPTION_TICK_CLASS : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+  item.setAttribute(OPTION_VALUE_ATTR, itemValue)
+  item.setAttribute(OPTION_TEXT_ATTR, displayValue)
+  item.textContent = optionDisplay(displayValue, on)
+
+  return item
+}
+
+/** 切换一个选项的勾选态（改类名 + 重建 ☑ / ☐ 文案），返回切换后的状态 */
+function setOptionState(item: HTMLElement, on: boolean): boolean {
+  item.classList.toggle(OPTION_ON_CLASS, on)
+  item.textContent = optionDisplay(item.getAttribute(OPTION_TEXT_ATTR) ?? '', on)
+
+  return on
+}
+
+/**
+ * 空值占位：一条下划线。
+ *
+ * 原型只给下划线、不给标签，因为它的填写项几乎都由 HIS 预填，
+ * 空值属于"系统没取到值"的少数情况。这里补一个 title，
+ * 让鼠标停在下划线上能看出这一处该填什么——外观一行没动。
+ */
+function buildBlank(doc: Document, label: string): HTMLElement {
+  const blank = doc.createElement('span')
+  blank.className = BLANK_CLASS
+  blank.innerHTML = '&nbsp;'
+
+  if (label) {
+    blank.title = `待填写：${label}`
+  }
+
+  return blank
+}
+
 function buildFieldWidget(
   doc: Document,
   field: SigningFieldDef,
@@ -189,17 +313,30 @@ function buildFieldWidget(
   const value = answers[field.id]
   const abnormal = hitsRisk(value, field.risk)
   const multi = isMultiOptionGroup(field)
+  const empty = isEmptyFieldValue(value)
 
   const host = doc.createElement('span')
-  host.className = `sign-field sign-field--${field.kind}${abnormal ? ' sign-field--abnormal' : ''}`
+  // 原型口径：渲染出来的填写项**一律**带 .filled —— 签署态文书不再有"待填写"的
+  // 虚线胶囊，填空处是下划线、填好的地方就是正文；.filled 表达的是"已渲染为签署态"，
+  // 不是"已填值"。未填的必填项靠下面的 sign-field--missing 补一条提示色。
+  host.className = [
+    FIELD_HOST_CLASS,
+    `k-${field.kind}`,
+    FIELD_FILLED_CLASS,
+    abnormal ? 'sign-field--abnormal' : '',
+    interactive && empty ? 'sign-field--missing' : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
   host.setAttribute(FIELD_ATTR, field.id)
   host.setAttribute(FIELD_KIND_ATTR, field.kind)
   host.setAttribute(FIELD_LABEL_ATTR, field.label)
   host.setAttribute(FIELD_REQUIRED_ATTR, field.required ? 'true' : 'false')
 
-  // 回读取值时靠它区分「一组多选」与「单个勾选框」：两者 DOM 里都是 checkbox
-  if (multi) {
-    host.setAttribute(FIELD_MULTI_ATTR, 'true')
+  // 选项组显式落成 true / false：回读取值时靠"有没有这个属性"区分
+  // 「一组选项」与「没有选项的单个勾选框」，两者 DOM 里都是一串 .docopt
+  if (isOptionGroupField(field)) {
+    host.setAttribute(FIELD_MULTI_ATTR, multi ? 'true' : 'false')
   }
 
   if (field.risk) {
@@ -216,144 +353,72 @@ function buildFieldWidget(
     host.setAttribute('role', 'button')
     host.setAttribute('tabindex', '0')
     host.setAttribute('title', `点击采集「${field.label}」`)
+  } else if (field.label) {
+    host.title = field.required ? `${field.label}（必填）` : field.label
   }
 
-  const label = doc.createElement('span')
-  label.className = 'sign-field__label'
-  label.textContent = field.label
+  if (field.kind === 'signature') {
+    const text = toTextValue(value)
 
-  if (field.required) {
-    const mark = doc.createElement('span')
-    mark.className = 'sign-field__required'
-    mark.textContent = '*'
-    label.appendChild(mark)
+    if (text) {
+      const image = doc.createElement('img')
+      image.className = SIGNATURE_IMAGE_CLASS
+      image.src = text
+      image.alt = field.label
+      host.appendChild(image)
+    } else {
+      const pending = doc.createElement('span')
+      pending.className = 'docfld-empty'
+      pending.textContent = '未签署'
+      host.appendChild(pending)
+    }
+
+    return host
   }
 
-  host.appendChild(label)
+  // 声明了选项就渲染成一组 ☑ / ☐；没给选项的 choice 会落到下面的文本分支，
+  // 否则科室拿到的是一个点不动的空控件
+  if (isOptionGroupField(field)) {
+    const selected = toSelectedValues(value)
 
-  const control = doc.createElement('span')
-  control.className = 'sign-field__control'
-  control.appendChild(buildFieldControl(doc, field, value, interactive, signaturePending, multi))
-  host.appendChild(control)
+    field.options.forEach((option) => {
+      host.appendChild(buildOptionItem(doc, option, selected.includes(option), interactive))
+    })
 
-  if (abnormal) {
-    const badge = doc.createElement('span')
-    badge.className = 'sign-field__badge'
-    badge.textContent = '异常项'
-    host.appendChild(badge)
+    return host
+  }
+
+  // 没有选项的单个勾选框：一个 ☑ / ☐，取值是布尔
+  if (field.kind === 'checkbox') {
+    host.appendChild(buildOptionItem(doc, '', value === true, interactive))
+    return host
+  }
+
+  const text = toTextValue(value)
+
+  // 可交互（签署页）：给一个压成下划线外观的输入框，现场可补录
+  if (interactive) {
+    const input = doc.createElement('input')
+    input.className = INPUT_CLASS
+    input.type = 'text'
+    input.value = text
+    // value 属性同理：只设 property 的话序列化出来是空值
+    input.setAttribute('value', text)
+    host.appendChild(input)
+
+    return host
+  }
+
+  // 只读（预览 / 已签署查看）：原型口径——有值就是正文，没值留一条下划线
+  if (text) {
+    host.textContent = text
+  } else {
+    host.appendChild(buildBlank(doc, field.label))
   }
 
   return host
 }
 
-/**
- * 一组选项：单选渲染成一组 radio（互斥），多选渲染成一组 checkbox（各勾各的）。
- */
-function buildOptionGroup(
-  doc: Document,
-  field: SigningFieldDef,
-  value: SigningFieldValue | undefined,
-  interactive: boolean,
-  multi: boolean,
-): HTMLElement {
-  const group = doc.createElement('span')
-  group.className = `sign-field__choices${multi ? ' sign-field__choices--multi' : ''}`
-  const selected = toSelectedValues(value)
-
-  field.options.forEach((option) => {
-    const wrapper = doc.createElement('label')
-    wrapper.className = 'sign-doc-option'
-
-    const input = doc.createElement('input')
-    input.className = multi ? 'sign-field__checkbox' : 'sign-field__radio'
-    input.type = multi ? 'checkbox' : 'radio'
-    // 同名：单选靠它互斥，多选靠它被 readAnswersFromRoot 一起取回
-    input.name = `sign-field-${field.id}`
-    input.value = option
-    input.disabled = !interactive
-
-    // 必须同时落成 attribute：innerHTML 只序列化 HTML 属性，
-    // 只设 .checked 这个 property 会在生成 HTML 时被丢掉
-    if (selected.includes(option)) {
-      input.checked = true
-      input.setAttribute('checked', '')
-    }
-
-    wrapper.appendChild(input)
-    wrapper.appendChild(doc.createTextNode(option))
-    group.appendChild(wrapper)
-  })
-
-  return group
-}
-
-function buildFieldControl(
-  doc: Document,
-  field: SigningFieldDef,
-  value: SigningFieldValue | undefined,
-  interactive: boolean,
-  signaturePending: boolean,
-  multi: boolean,
-): Node {
-  const textValue = toTextValue(value)
-
-  if (field.kind === 'signature') {
-    if (textValue) {
-      const image = doc.createElement('img')
-      image.className = SIGNATURE_IMAGE_CLASS
-      image.src = textValue
-      image.alt = field.label
-      return image
-    }
-
-    // 签名位只写「待签名」：宿主胶囊上已经写着「医师签名」了，
-    // 这里再写一遍「待医师签名」是重复信息
-    const empty = doc.createElement('span')
-    empty.className = 'sign-field__signature-empty'
-    empty.textContent = signaturePending ? '✍ 点击签名' : '待签名'
-    return empty
-  }
-
-  // 声明了选项就渲染成一组控件；没给选项的 choice 会落到下面的文本框分支，
-  // 否则科室拿到的是一个点不动的空控件
-  if (isOptionGroupField(field)) {
-    return buildOptionGroup(doc, field, value, interactive, multi)
-  }
-
-  if (field.kind === 'checkbox') {
-    const wrapper = doc.createElement('label')
-    wrapper.className = 'sign-doc-option'
-
-    const input = doc.createElement('input')
-    input.className = 'sign-field__checkbox'
-    input.type = 'checkbox'
-    input.disabled = !interactive
-
-    if (value === true) {
-      input.checked = true
-      input.setAttribute('checked', '')
-    }
-
-    wrapper.appendChild(input)
-    wrapper.appendChild(doc.createTextNode(field.label))
-    return wrapper
-  }
-
-  const input = doc.createElement('input')
-  input.className = 'sign-field__input'
-  input.type = field.kind === 'date' ? 'date' : 'text'
-  input.value = textValue
-  // value 属性同理：只设 property 的话序列化出来是空值
-  input.setAttribute('value', textValue)
-  input.readOnly = !interactive
-  input.disabled = !interactive
-  if (interactive) {
-    input.placeholder = '请填写'
-  }
-
-  return input
-}
-
 /**
  * 占位符渲染：把 ｛患者姓名｝ 就地替换成填写项控件，保留同一文本节点内的前后文字。
  * 模板未收录的占位符按自定义文本项处理，仍可在文书上填写，
@@ -439,7 +504,19 @@ function renderStructuredFields(
   })
 }
 
-function convertCheckboxes(root: Element, interactive: boolean, selected: Set<string>) {
+/**
+ * 存量兼容①：表头含「勾选」列的表格，逐行把勾选列转成可点击的 ☑ / ☐。
+ *
+ * 为什么不是 `<input type=checkbox>`：原型的口径是"勾选列 → 占位符 → ☑ 文本"
+ * （见其 docCheckboxize + fillDocHtml），签署态文书里没有表单控件。
+ * 两种外观混在一篇文书里，会让人以为有一处没生效。
+ *
+ * 项目名仍写在 data-sign-item 上：它是这项勾选的**取值标识**，
+ * 显示成「待患者勾选」只是因为它左边那一列已经写着项目名了。
+ */
+function convertCheckboxTables(root: Element, interactive: boolean, selected: Set<string>) {
+  const doc = root.ownerDocument
+
   root.querySelectorAll('table').forEach((table) => {
     // 不能只认 <thead>：WangEditor 的表格节点是 <table><tbody><tr>，它导出时不会生成
     // thead，粘贴带 thead 的表格时其 preParseHtml 也把 thead 拆掉；.docx 经 mammoth
@@ -476,33 +553,36 @@ function convertCheckboxes(root: Element, interactive: boolean, selected: Set<st
         const nameCell = cells[nameIndex > -1 ? nameIndex : fallbackIndex]
         const itemName = (nameCell?.textContent ?? '').trim()
 
-        const checkbox = document.createElement('input')
-        checkbox.type = 'checkbox'
-        checkbox.className = 'sign-doc-checkbox'
-        checkbox.setAttribute('data-sign-item', itemName)
-        checkbox.disabled = !interactive
-
-        // 必须写成 attribute：innerHTML 只序列化 HTML 属性，只设 .checked 这个
-        // property 会在生成 HTML 时被丢掉，渲染回来就成了未勾选
-        if (selected.has(itemName)) {
-          checkbox.checked = true
-          checkbox.setAttribute('checked', '')
-        }
-
-        checkCell.textContent = ''
-        checkCell.appendChild(checkbox)
+        checkCell.replaceChildren(
+          buildOptionItem(doc, itemName, selected.has(itemName), interactive, ''),
+        )
       })
   })
 }
 
-/** 收集所有含方框符号的文本节点 */
+/**
+ * 已经渲染成控件的区域：结构化占位符宿主（含它内部的选项）与已经生成的选项本身。
+ * 这两个区域里的方框符号是**我们自己的输出**（☑/☐ 文本），不能再当"科室手打的方框"识别。
+ */
+const RENDERED_OPTION_SELECTOR = `.${OPTION_CLASS}, [${FIELD_ATTR}]`
+
+/**
+ * 收集所有含方框符号的文本节点。
+ *
+ * 必须排除已渲染区域，否则会自我套娃：选项的文本就是 `☐ 选项`，而 `☐` 恰好是
+ * SIGNING_OPTION_MARKERS 里的字符，扫描器会把它当成科室手打的方框再转一次，
+ * 于是在 `.docopt` 里再嵌一个 `.docopt` —— 患者看到的是「☐ 患者本人 ☐ 患者本人」，
+ * 且内层用「选项名到标点为止」的规则截断，长选项名会被切掉后半截。
+ */
 function collectOptionTextNodes(root: Element): Text[] {
   const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT)
   const targets: Text[] = []
   let node = walker.nextNode()
 
   while (node) {
-    if (OPTION_TEST_PATTERN.test(node.textContent ?? '')) {
+    const text = node.textContent ?? ''
+
+    if (OPTION_TEST_PATTERN.test(text) && !isInsideRenderedOption(node as Text)) {
       targets.push(node as Text)
     }
 
@@ -512,9 +592,17 @@ function collectOptionTextNodes(root: Element): Text[] {
   return targets
 }
 
+function isInsideRenderedOption(node: Text): boolean {
+  return Boolean(node.parentElement?.closest(RENDERED_OPTION_SELECTOR))
+}
+
 /**
- * 把一个文本节点里的方框换成可交互控件：方框 + 紧随其后的文字算一个选项，
- * 例如「□否 □是」→ 两个 radio，选项名分别是「否」「是」。
+ * 把一个文本节点里的方框换成可点击的 ☑ / ☐ 选项：方框 + 紧随其后的文字算一个选项，
+ * 例如「□否 □是」→ 两个选项，取值分别是「否」「是」。
+ *
+ * 同组标记（data-sign-group）落在选项自己身上，而不是包一层容器：
+ * 这些方框散落在正文的文本节点里，跨节点包容器会改掉文书结构。
+ * 单选组还会带上 data-sign-multi="false"，签署端据此做互斥。
  */
 function replaceOptionMarkers(
   textNode: Text,
@@ -523,15 +611,16 @@ function replaceOptionMarkers(
   interactive: boolean,
   selected: Set<string>,
 ) {
+  const doc = textNode.ownerDocument
   const parts = (textNode.textContent ?? '').split(OPTION_SPLIT_PATTERN)
-  const fragment = textNode.ownerDocument.createDocumentFragment()
+  const fragment = doc.createDocumentFragment()
 
   for (let index = 0; index < parts.length; index += 1) {
     const part = parts[index] ?? ''
 
     if (!OPTION_TEST_PATTERN.test(part)) {
       if (part) {
-        fragment.appendChild(textNode.ownerDocument.createTextNode(part))
+        fragment.appendChild(doc.createTextNode(part))
       }
 
       continue
@@ -542,32 +631,17 @@ function replaceOptionMarkers(
     const label = labelMatch?.[1] ?? ''
     const tail = labelMatch?.[2] ?? ''
 
-    const input = textNode.ownerDocument.createElement('input')
-    input.type = type
-    input.className = 'sign-doc-checkbox'
-    input.disabled = !interactive
-    input.setAttribute('data-sign-item', label)
-
-    // 同表格勾选：只设 property 不会出现在生成的 HTML 里，必须落成属性
-    if (label !== '' && selected.has(label)) {
-      input.checked = true
-      input.setAttribute('checked', '')
-    }
+    const item = buildOptionItem(doc, label, label !== '' && selected.has(label), interactive)
+    item.setAttribute(GROUP_ATTR, groupName)
 
     if (type === 'radio') {
-      input.name = groupName
-      input.value = label
+      item.setAttribute(FIELD_MULTI_ATTR, 'false')
     }
 
-    const wrapper = textNode.ownerDocument.createElement('label')
-    wrapper.className = 'sign-doc-option'
-    wrapper.appendChild(input)
-    wrapper.appendChild(textNode.ownerDocument.createTextNode(label))
-
-    fragment.appendChild(wrapper)
+    fragment.appendChild(item)
 
     if (tail) {
-      fragment.appendChild(textNode.ownerDocument.createTextNode(tail))
+      fragment.appendChild(doc.createTextNode(tail))
     }
 
     // 选项名已随方框一起消费，跳过它对应的片段
@@ -708,7 +782,7 @@ export function buildSigningDocumentHtml(
   renderTokenFields(root, answers, interactive, signatureActionable, claimed)
 
   const selected = new Set(data.selectedItems ?? [])
-  convertCheckboxes(root, interactive, selected)
+  convertCheckboxTables(root, interactive, selected)
   convertInlineOptions(root, interactive, selected)
 
   // 页眉最后插入：保证 HIS 取值不会被当成文书内容参与占位符/方框识别
@@ -719,7 +793,11 @@ export function buildSigningDocumentHtml(
 
 /**
  * 从渲染后的文书 DOM 里读回填写项取值。
- * 签名读的是签名图，其余按控件类型读，返回结果直接可作为签署证据的一部分固化。
+ * 签名读的是签名图，其余按控件形态读，返回结果直接可作为签署证据的一部分固化。
+ *
+ * 三条读取路径与 buildFieldWidget 的三种形态一一对应，判据只看宿主上的属性，
+ * 不再猜 DOM：带 data-sign-multi 的是一组选项，kind=checkbox 的是单个勾选框，
+ * 其余按文本读。
  */
 export function readAnswersFromRoot(root: HTMLElement): SigningAnswers {
   const answers: SigningAnswers = {}
@@ -738,73 +816,174 @@ export function readAnswersFromRoot(root: HTMLElement): SigningAnswers {
       return
     }
 
-    // 多选组：一组 checkbox，取值是字符串数组（勾了几个就是几个）。
-    // 必须先于下面的 checkbox 分支判断——两者 DOM 里都是 input[type=checkbox]，
-    // 只有渲染时打上的 data-sign-multi 能区分「一组多选」与「单个勾选框」
-    if (host.getAttribute(FIELD_MULTI_ATTR) === 'true') {
-      answers[id] = Array.from(
-        host.querySelectorAll<HTMLInputElement>('input[type="checkbox"]:checked'),
-      ).map((input) => input.value)
-      return
-    }
-
-    if (kind === 'choice') {
-      const checked = host.querySelector<HTMLInputElement>('input[type="radio"]:checked')
-      answers[id] = checked?.value ?? ''
+    const multiAttr = host.getAttribute(FIELD_MULTI_ATTR)
+
+    // 一组选项：勾中的项取 data-sign-item。
+    // 单选返回字符串、多选返回数组——与 SigningFieldValue 的约定一致
+    if (multiAttr !== null) {
+      const picked = collectCheckedItems(host)
+
+      answers[id] = multiAttr === 'true' ? picked : (picked[0] ?? '')
       return
     }
 
+    // 没有选项的单个勾选框：取值是布尔。
+    // 找不到勾选节点时按「未勾选」处理——`?.classList.contains()` 会返回 undefined，
+    // 直接落库会在证据里留下一个 undefined 而不是 false
     if (kind === 'checkbox') {
-      const box = host.querySelector<HTMLInputElement>('input[type="checkbox"]')
-      answers[id] = Boolean(box?.checked)
+      answers[id] =
+        host
+          .querySelector<HTMLElement>(`.${OPTION_CLASS}`)
+          ?.classList.contains(OPTION_ON_CLASS) ?? false
       return
     }
 
-    answers[id] = host.querySelector<HTMLInputElement>('input')?.value ?? ''
+    answers[id] = readHostText(host)
   })
 
   return answers
 }
 
+/** 某个宿主下已勾选的选项取值（按文档顺序） */
+function collectCheckedItems(host: HTMLElement): string[] {
+  return Array.from(host.querySelectorAll<HTMLElement>(`.${OPTION_CLASS}.${OPTION_ON_CLASS}`)).map(
+    (item) => item.getAttribute(OPTION_VALUE_ATTR) ?? '',
+  )
+}
+
 /**
- * 把一个已固化的取值写回填写项的控件（签署端重新打开文书时还原状态）。
+ * 读填写项的文本取值。
  *
- * 与 readAnswersFromRoot 是一对：那边按控件类型读、这边按同一套判据写，
+ * 两种载体都要认：签署页是输入框（取 value），预览与已签署查看是正文文字。
+ * 只读态的空值占位（.docfld-blank）里是 `&nbsp;`，直接取 textContent 会得到一个
+ * 不换行空格——那会让「已填 / 未填」的判据全部失效（空值看起来像有值），
+ * 所以把占位节点先摘掉再读。
+ */
+function readHostText(host: HTMLElement): string {
+  const input = host.querySelector<HTMLInputElement>(`.${INPUT_CLASS}`)
+
+  if (input) {
+    return input.value.trim()
+  }
+
+  const clone = host.cloneNode(true) as HTMLElement
+
+  clone.querySelectorAll(`.${BLANK_CLASS}`).forEach((blank) => blank.remove())
+
+  return (clone.textContent ?? '').trim()
+}
+
+/**
+ * 把一个已固化的取值写回填写项（签署端重新打开文书时还原状态）。
+ *
+ * 与 readAnswersFromRoot 是一对：那边按宿主属性读、这边按同一套判据写，
  * 两者都放在本文件里，属性名与判据只有一份——签署端不该自己写 data-sign-* 选择器。
  */
 export function applyAnswerToFieldHost(host: HTMLElement, value: SigningFieldValue): void {
-  // 多选组：一组 checkbox，取值是字符串数组。
-  // 必须先判它，否则会落到下面的布尔分支，把数组当成「勾上了」全部勾选
-  if (host.getAttribute(FIELD_MULTI_ATTR) === 'true') {
-    const picked = new Set(Array.isArray(value) ? value : [])
+  const items = Array.from(host.querySelectorAll<HTMLElement>(`.${OPTION_CLASS}`))
+  const multiAttr = host.getAttribute(FIELD_MULTI_ATTR)
 
-    host.querySelectorAll<HTMLInputElement>('input[type="checkbox"]').forEach((box) => {
-      box.checked = picked.has(box.value)
+  // 一组选项：多选取数组、单选取字符串。两种都先把整组清干净再按取值点亮，
+  // 否则「从「是」改成「否」」会留下两个勾
+  if (multiAttr !== null && items.length) {
+    const picked = new Set(
+      multiAttr === 'true' ? toSelectedValues(value) : [toTextValue(value)].filter(Boolean),
+    )
+
+    items.forEach((item) => {
+      setOptionState(item, picked.has(item.getAttribute(OPTION_VALUE_ATTR) ?? ''))
     })
-    return
-  }
-
-  if (typeof value === 'boolean') {
-    const checkbox = host.querySelector<HTMLInputElement>('input[type="checkbox"]')
-
-    if (checkbox) {
-      checkbox.checked = value
-    }
 
     return
   }
 
-  const text = Array.isArray(value) ? '' : value
-  const input = host.querySelector<HTMLInputElement>(
-    'input:not([type="radio"]):not([type="checkbox"])',
-  )
+  // 没有选项的单个勾选框：取值是布尔
+  if (items.length === 1) {
+    setOptionState(items[0] as HTMLElement, value === true)
+    return
+  }
+
+  // 文本项只认字符串：数组（选项组）与布尔（勾选框）都在这条分支之前被处理掉了，
+  // 真落到这里说明取值类型与控件形态对不上，按空值处理而不是硬塞一个值进去
+  const text = typeof value === 'string' ? value : ''
+  const input = host.querySelector<HTMLInputElement>(`.${INPUT_CLASS}`)
 
   if (input) {
     input.value = text
+    input.setAttribute('value', text)
+    return
   }
 
-  host.querySelectorAll<HTMLInputElement>('input[type="radio"]').forEach((radio) => {
-    radio.checked = radio.value === text
+  if (text) {
+    host.textContent = text
+    return
+  }
+
+  // 清空要还原成下划线占位，不能留一个空壳（空壳看起来像"这一项被删了"）
+  host.replaceChildren(buildBlank(host.ownerDocument, host.getAttribute(FIELD_LABEL_ATTR) ?? ''))
+}
+
+/**
+ * 切换点击到的那个选项，返回是否真的发生了变化。
+ *
+ * 三种形态在这里统一处理：
+ * - 结构化占位符与存量勾选表的选项：宿主带 data-sign-multi，互斥范围就是这个宿主；
+ * - 行内方框转出来的选项：散在正文里、没有共同宿主，靠 data-sign-group 找同组兄弟。
+ *
+ * root 是整篇文书的容器：只有它才能把"同组兄弟"找全（见上）。
+ * 这一层逻辑放在本文件而不是签署端组件里，是为了和渲染端共用
+ * 「什么算同组」这一条判据——组件里再推一遍迟早和渲染漂移。
+ */
+export function toggleOptionAt(root: HTMLElement, item: HTMLElement): boolean {
+  if (!item.classList.contains(OPTION_TICK_CLASS) || !root.contains(item)) {
+    return false
+  }
+
+  const host = item.closest<HTMLElement>(`[${FIELD_ATTR}]`)
+  const groupName = item.getAttribute(GROUP_ATTR)
+  const multiAttr = host?.getAttribute(FIELD_MULTI_ATTR) ?? item.getAttribute(FIELD_MULTI_ATTR)
+  // 缺省按多选：只有明确声明过互斥的组才做单选
+  const multi = multiAttr !== 'false'
+  const on = item.classList.contains(OPTION_ON_CLASS)
+
+  if (multi) {
+    setOptionState(item, !on)
+    return true
+  }
+
+  const siblings = groupName
+    ? Array.from(root.querySelectorAll<HTMLElement>(`[${GROUP_ATTR}="${groupName}"]`))
+    : Array.from(host?.querySelectorAll<HTMLElement>(`.${OPTION_CLASS}`) ?? [item])
+
+  // 单选：再点一次已选中的项等于取消，与原型 tickDocOpt 的口径一致
+  siblings.forEach((sibling) => setOptionState(sibling, !on && sibling === item))
+
+  return true
+}
+
+/**
+ * 收集"散装"选项里已勾选的项（存量勾选表 + 行内方框），即 SigningTaskRecord.selectedItems。
+ *
+ * 刻意排除落在 `[data-sign-field]` 宿主里的选项：结构化填写项的取值走 fieldAnswers，
+ * 两边都收会让同一份勾选在任务上存两份、且口径可能不一致。
+ */
+export function collectSelectedItemsFromRoot(root: HTMLElement): string[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(`.${OPTION_CLASS}.${OPTION_ON_CLASS}`))
+    .filter((item) => !item.closest(`[${FIELD_ATTR}]`))
+    .map((item) => item.getAttribute(OPTION_VALUE_ATTR) ?? '')
+    .filter(Boolean)
+}
+
+/** 按已固化的勾选清单还原"散装"选项的状态（与 collectSelectedItemsFromRoot 对称） */
+export function applySelectedItemsToRoot(root: HTMLElement, items: string[]): void {
+  const selected = new Set(items)
+
+  root.querySelectorAll<HTMLElement>(`.${OPTION_CLASS}`).forEach((item) => {
+    if (item.closest(`[${FIELD_ATTR}]`)) {
+      return
+    }
+
+    setOptionState(item, selected.has(item.getAttribute(OPTION_VALUE_ATTR) ?? ''))
   })
 }
 
@@ -824,14 +1003,13 @@ export function applySignatureToRoot(root: HTMLElement, fieldId: string, dataUrl
   }
 
   const host = root.querySelector<HTMLElement>(`[${FIELD_ATTR}="${fieldId}"]`)
-  const control = host?.querySelector('.sign-field__control')
 
-  if (!host || !control) {
+  if (!host) {
     return false
   }
 
   // 同一张图重复写入没有意义，返回 false 也让调用方少跑一轮回读
-  if (control.querySelector(`img.${SIGNATURE_IMAGE_CLASS}`)?.getAttribute('src') === dataUrl) {
+  if (host.querySelector(`img.${SIGNATURE_IMAGE_CLASS}`)?.getAttribute('src') === dataUrl) {
     return false
   }
 
@@ -839,14 +1017,15 @@ export function applySignatureToRoot(root: HTMLElement, fieldId: string, dataUrl
   image.className = SIGNATURE_IMAGE_CLASS
   image.src = dataUrl
   image.alt = host.getAttribute(FIELD_LABEL_ATTR) ?? fieldId
-  control.replaceChildren(image)
+  // 签名位填充后只剩签名图：原型不保留「未签署」提示，也不再有点击提示
+  host.replaceChildren(image)
+  host.title = host.getAttribute(FIELD_LABEL_ATTR) ?? ''
 
   // 采集入口用完即摘：留着会让「还能再点一次」的观感落空
-  host.classList.remove(ACTIONABLE_CLASS)
+  host.classList.remove(ACTIONABLE_CLASS, 'sign-field--missing')
   host.removeAttribute(FIELD_ACTION_ATTR)
   host.removeAttribute('role')
   host.removeAttribute('tabindex')
-  host.removeAttribute('title')
 
   return true
 }