临床文档模板编辑体验设计

1. 文档信息

2. 目标

医生应当像编辑一份常用文书一样建立模板，不需要输入 {{doctor_name}}、AI 区域 Key 或其他技术协议。系统负责插入权威资料和调用 AI；医生负责复核并编辑最终 Clinical Document Draft。

本设计不改变现有模板归属模型：默认模板初始化到每位医生名下，医生可以修改自己的所有默认模板和个人模板。新建模板仍沿用现有入口和通用起始内容，不增加复制模板或 AI 生成模板流程。

3. 内容模型

模板编辑器只呈现三种内容：

系统不建立结构化“文档填写项”。医生需要在每份文档中补写 Reason:、日期范围或其他个别内容时，直接在 Document content 中输入，不经过额外表单、字段类型或必填配置。

4. 模板编辑器

4.1 基本资料

保留以下模板资料：

• Template name：医生识别模板的名称。
• Template Description：表达整份模板的用途、语气和共同要求；不自动复制到本次 AI 要求输入框，执行全文改写时作为独立文档说明发送。
• Document group：沿用现有文档分组。
• Page size：沿用 A4、A5。
• Reusable content：模板富文本正文。

4.2 插入合并字段

富文本工具栏最右侧提供独立的 Insert field 图标按钮，与正文格式工具以分隔线区分；按钮采用紫蓝渐变底和单一“资料库自动导入”白色图标，不使用分离角标。悬停或键盘聚焦时在按钮右侧方向显示白色磨砂半透明说明框，内容为 Add information that the system fills in automatically.；点击后向右打开紧凑浮层：

1. 顶部提供字段搜索。
2. 字段按 Patient、Visit、Clinician 分组。
3. 每个选择项使用与插入结果相同的稳定标签颜色；点击字段后，在当前光标位置插入彩色标签，例如 Doctor name。
4. 标签可以随正文移动或删除；医生不直接修改标签内部名称。
5. 标签不显示底层 Token、数据库字段或资料路径，不另设字段配置页面。

标签从一组可读性足够的颜色中分配。颜色不表达分类或临床语义；系统根据字段稳定标识确定颜色，使不同字段呈现多彩效果，同时保证同一个字段跨模板、跨会话保持同色。标签除颜色外始终显示文字，不能只依靠颜色识别。

4.3 字段目录

字段目录由系统维护。每个字段必须具有稳定标识、医生可见名称、分组、权威资料来源和格式化规则；医生选择字段，但不能自行定义一个声称可以自动取值的新字段。

Visit 表示当前患者与本次问诊锁定上下文，包含该次问诊形成的临床资料；Clinician 同时包含负责医生与当前诊所资料。

第一版目标字段为：

收件机构继续由文档建立流程中的 Recipient 选择器负责，不归入上述三组，也不作为第一版模板合并字段。

4.4 插入 AI 可编辑区域

富文本工具栏最右侧提供独立的 Insert AI area 图标按钮，与 Insert field 组成模板结构工具组；按钮采用蓝青渐变底和单一魔法编辑白色图标，不使用分离角标。悬停或键盘聚焦时在按钮右侧方向显示白色磨砂半透明说明框；点击后立即在当前光标位置插入区域，不打开名称或 guidance 浮层。系统同时生成稳定且唯一的内部 Key，不要求医生查看或维护 Key。

AI 区域沿用蓝色虚线边框和现有 AI editable area 视觉语言，但框标题统一显示为 AI- 加对应框名，例如：

• AI-Referral reason
• AI-Clinical summary
• AI-Treatment history

新区域标题先显示 AI-，其后名称位置保持空白并立即获得文本光标，不显示“待填写”或其他占位名称。医生直接输入区域名称；点击既有区域名称时同样进入原位修改，不再打开配置框。一个模板可以包含多个 AI 区域；模板草稿中的名称可以暂时为空或重名，但保存前必须全部填写且不区分大小写唯一。

AI- 前缀固定且不可编辑。Enter 或 Tab 完成名称编辑并把光标移入区域 guidance；点击区域外同样完成编辑；Escape 退出名称编辑但保留当前值。空名称仍可保留在模板草稿中，但不得保存模板。

AI guidance 不在编辑器下方集中显示，也不使用独立配置框。模板编辑态的蓝色虚线区域正文就是 guidance 编辑位置；未填写时显示灰色英文占位：AI has access to the relevant information from this consultation. What would you like AI to write here? Tell it here!。占位不属于实际 guidance，也不写入模板正文。医生输入的区域正文以纯文本同步保存为对应区域的独立 guidance 元数据，允许换行但不接受粗体、列表、链接或其他富文本格式；guidance 可以为空且不阻止模板保存。光标位于 guidance 时，富文本格式按钮不作用于该区域。

名称暂时为空或与同一模板中的其他区域重名时，区域就地显示错误但不强行恢复旧名称，并阻止最终保存模板。鼠标悬停 AI 区域时，虚线框内部右上角显示叉号；点击后立即删除整个区域及其 guidance，不显示确认提示。

4.5 预览与保存

• 弹窗正文上方不显示 Reusable content 标题、说明或模板类型行。
• 底部不提供 Cancel；个人模板的红色 Delete、黄色 Preview 和绿色 Save 依次排列，Save 不显示对号。三者保留语义色，但通过克制的同色深浅渐变、细描边、内高光和柔和阴影呈现质感，不使用廉价的纯色块。Preview 使用固定虚构资料替换彩色标签，并按所选 A4/A5 展示排版，不读取真实患者。
• 只有一个 Save 主操作，不要求医生先执行独立验证。
• 系统在后台自动执行安全 HTML、合并字段及 AI 区域结构检查。失败时在对应位置显示医生可理解的错误，不展示 HTML、Token 或 Key。
• 保存成功后关闭编辑弹窗并选中已保存模板，不在模板列表前额外显示绿色保存版本标签。

5. Document content 编辑器

选择患者、Visit 和模板后，服务端以权威上下文把合并字段替换为初始文字，再建立 Clinical Document Draft。此后 Document content 是真实文档正文：

• 医生可以编辑或删除任何普通文字。
• 医生可以编辑或删除合并字段产生的文字，包括姓名、日期、诊断和医生资料。
• 医生可以编辑、清空或删除 AI 生成的内容。
• 模板选择后的首次自动生成只写入命名 AI 区域；全文 Improve draft with AI 产生整份候选稿，算法失败不得覆盖当前编辑内容。
• 保存继续产生可追溯的 Clinical Document Version，并保留所用模板快照和版本。

模板引用的权威资料没有值时，编辑器在对应位置显示橙色、可直接覆盖的占位，例如 Patient address — missing，并提供非阻断提示。医生可以输入替代文字、删除占位或继续操作；系统不因缺失值阻止保存或打印。

5.1 模板选择后的 AI 区域生成

• 只有医生明确选择模板建立全新临床文档草稿时，在服务端完成合并字段初始化后自动调用一次现有区域算法；默认打开文档集、页签切换及重开已保存文档不自动生成。
• 模板编辑态正文保存为 guidance；实例化患者文档后不显示 guidance，区域改为显示生成状态及结果。
• 一个请求继续携带 Template Description、全部区域的稳定 Key、名称、guidance 和当前内容，并保留区域级部分成功、HTML 安全检查及迟到响应防覆盖。Template Description 只作为整体文档说明发送，不复制到 AI 卡片输入框。
• 等待完整区域响应时，区域上方显示 AI is generating，下方显示持续旋转的刷新图标；响应后以逐步呈现的视觉效果填入内容。生成中的区域不可编辑，右下角显示 Cancel generation；医生取消后才能手工编辑该区域。区域外正文与其他已完成区域仍可编辑。
• 单区取消立即恢复该区域生成前内容并忽略迟到结果，其他区域继续；全部区域取消时中断浏览器请求，但不承诺终止算法服务计算。
• 失败区域保留生成前内容，上方显示 Generation failed，并把右下角操作改为 Try again；重试只请求该区域，不重复生成已经成功的区域。
• 同一文档的全部区域完成、失败或取消前禁用全文 Improve；不同文档页签的区域生成可以并行。切换页签不停止生成，并在后台页签显示克制的生成标记；关闭页签时取消该页签的前端生成状态并忽略迟到响应。

5.2 Improve draft with AI

• Improve draft with AI 对当前整篇文档提出替换候选，不再限定为 AI 区域润色，也不要求模板存在 AI 区域或当前正文非空；即使正文、Template Description 和本次要求均为空，也可以依据 Template name、Document type 和问诊上下文生成整份候选。
• 模板配置显示 Template Description。AI 卡片保留一个无字段标题、默认空白且可选的本次要求输入框，不自动载入 Template Description。
• 请求通过内部通用模型接口发送当前安全 HTML、Template name、Document type、该文档绑定的模板版本快照中的 Template Description、医生本次要求、收件机构和服务端聚合的最小必要结构化问诊上下文；不读取模板库后来修改的说明，也不把 Template name 或 Document type 伪装成医生指令。任何情况下都不发送问诊转录、HKID、联系方式、地址、历史问诊、附件、保险或财务资料。
• 模型返回整份受限 HTML fragment；后端完成容量和安全 HTML 清理后才交给前端。无效、超限或危险内容使整次操作失败并完整保留原文。
• 内部通用模型固定使用 messages：system 消息约束不得创造事实且只返回受限 HTML，user 消息携带 Template Description、本次要求、当前 HTML、Recipient 和结构化问诊上下文；temperature 固定为 0，不发送 max_tokens，使用算法服务默认上限。
• 从请求发出到视觉输出结束，整篇正文不可编辑；医生必须先使用撤回才能恢复编辑。响应到达后以逐步呈现的视觉效果展示候选稿，该效果不表示内部模型接口提供 token 流。
• 区域生成期间锁定 Recipient；全文 Improve 期间锁定正文、Recipient 和本次要求输入框。Page size 等未发送给模型的界面配置仍可修改，取消或撤回后恢复输入。
• 候选稿以整篇虚线框标识，左上角提供确认与撤回；撤回在等待和逐步呈现期间始终可用，确认直到安全内容完整展示后才启用。撤回恢复原文、停止前端展示并忽略迟到响应，但不承诺终止模型计算。
• 完整展示后的候选稿允许医生继续编辑；确认接受 AI 候选及医生对候选的修改，并将内容扁平化为普通安全 HTML，不保留 AI 区域 Key 或区域框。确认只更新当前浏览器草稿并标记为已修改，不立即建立版本；撤回仍恢复发起 Improve 前的正文。
• 未确认候选稿按文档页签隔离，不自动保存、不打印、不签署，也不写入刷新恢复数据。普通页签切换保留候选稿；页面刷新只恢复改写前正文。
• 离开 Clinical Documents、Print 或 Review & Complete 时，以 Confirm AI changes、Discard AI changes、Stay here 要求医生处理候选。Print 只处理当前页签；离开模块及 Review & Complete 必须处理全部存在候选的页签。
• 审计记录 request ID、输入摘要哈希、耗时、结果状态、操作者、Visit/Document 及确认或撤回动作，不记录 Template Description、本次要求、临床上下文、原文或模型正文；确认后的版本只关联 request ID 与 AI 来源类型。
• 全文确认和撤回以图标按钮放在虚线候选框左上角，Tooltip 分别为 Confirm AI changes 和 Undo AI changes。生成及逐步呈现期间确认禁用、撤回可用；同一文档同时只允许一个全文 Improve。
• 安全 HTML 的结构从视觉输出开始即完整存在，只逐步揭示文本节点和段落，不逐字符拼接标签。短内容约 1 秒、普通内容约 2–3 秒、长内容最长 4 秒展示完成。
• 422、502、504、网络错误、超时、空响应或不安全 HTML 均恢复改写前正文并解除锁定，保留医生输入的本次要求，通过 Toast 说明失败；系统不自动重试。
• 调用前计算完整 messages 内容长度；超过 100,000 字符时不发送且不静默截断，提示医生缩短正文或本次要求。
• 不同文档页签可以并行执行区域生成或全文 Improve，但每个页签同时最多一个 AI 操作；状态不得使用跨页签的单一全局 busy。多个成功区域并行揭示，各自在最多 4 秒内完成。
• 区域生成未结束时离开 Clinical Documents、Print 或 Review & Complete，提供 Wait for AI、Cancel generation and continue、Stay here；等待完成后自动继续原操作，取消则恢复生成前内容后继续。
• 独立 Clinical Document App 与问诊台共用模板插入、区域生成及全文 Improve 交互；独立 App 继续显式 Save，问诊台继续自动保存。
• 确认后的专用候选框和 Undo AI changes 消失，但编辑器标准 Undo / Ctrl+Z 可以撤销整次全文替换，直到普通编辑历史被清除；它不创建或回滚服务端版本。

6. 交互示例

医生建立转介信模板时：

1. 输入模板名称并选择文档分组和纸张尺寸。
2. 在正文输入固定开场文字。
3. 通过 Insert field → Patient 插入 Patient name 和 MRN 标签。
4. 通过 Insert field → Clinician 插入 Doctor name 和 Registration number 标签。
5. 点击插入 AI 区域后，界面立即显示 AI- 并把光标放在其后的空白名称位置；医生输入 Referral reason。
6. 医生直接在虚线区域正文中填写可选 AI guidance，例如“只总结本次问诊中由医生确认的转介原因”。
7. 使用虚构资料预览排版并保存模板。
8. 建立患者文档后，所有标签变为真实文字；医生在 Document content 中自由修改全文并保存版本。

7. 约束与非目标

• 不改变默认模板和个人模板均归医生所有的现有模型。
• 不增加诊所级、专科级或管理员级模板层级。
• 不增加结构化文档填写项、条件逻辑、公式、必填字段或复杂表单设计器。
• 不锁定模板普通正文、法定文字或合并后的值；医生对最终文档负责。
• 不改变 Clinical Document 的签署、签发、作废和重发生命周期范围。
• 不允许浏览器决定首次合并值；首次合并仍必须来自服务端绑定的 Patient、Visit、Clinician 权威上下文。
• 模板选择后的首次 AI 区域生成不得修改区域外内容；医生主动发起全文 Improve 时可以产生整份替换候选，但必须由医生确认。

8. 现有实现差距

• 本次不迁移或改写任何既有模板数据和既有 Clinical Document Version。测试阶段的旧模板 AI 区域正文在新实现中直接丢弃且不再进入新患者文档；只读取原有 ai_regions[].guidance，为空时显示新的英文灰色占位。医生以后主动保存模板时才按新格式持久化，不提供旧格式双模式兼容。
• 当前问诊台模板编辑器把七个 Token 以技术文本列在编辑器下方，需要改为彩色标签选择器。
• 当前个人模板固定只有一个 clinical_body AI 区域，需要支持多个命名区域及各自 guidance。
• 当前服务端只提供患者姓名、MRN、HKID、问诊日期、医生姓名、诊断和建议七个合并字段，需要按字段目录扩充权威取值。
• 当前服务端要求 Document content 的固定正文、顺序和合并值与模板骨架保持一致，需要按 ADR-0008 改为允许医生编辑全文，同时保留安全清理、版本和审计。
• 当前 Improve 仍复用区域算法并只替换 AI 区域，需要新增内部通用模型适配器、整份候选稿及确认/撤回状态；区域首次生成继续保留现有区域契约。
• 当前缺少虚构资料 Preview 和缺失合并值的可编辑占位提示。

9. 验收基线

1. 医生无需看到或输入 {{...}}、可见标签花括号、data-ai-region 或区域 Key，即可完成模板创建和编辑。
2. Insert field 以紫蓝渐变底的单一白色图标位于富文本工具栏最右侧，悬停或聚焦通过向右展开的磨砂半透明提示显示 Add information that the system fills in automatically.；选择器向右展开，支持搜索及 Patient、Visit、Clinician 分组，并以与插入结果相同的稳定颜色显示各字段，点击后在光标处插入不带花括号的人类可读彩色标签。
3. 同一合并字段的标签颜色稳定，不同字段可呈现不同颜色，标签始终带文字。
4. Insert AI area 以蓝青渐变底的单一白色图标位于富文本工具栏最右侧。点击后立即在光标处插入蓝色虚线区域，标题显示不可编辑的 AI-，名称位置为空并立即获得文本光标；点击既有名称直接原位编辑，不打开配置浮层。Enter、Tab 或点击外部完成名称编辑，前两者把光标移入 guidance。区域正文直接编辑可选 guidance，空白时显示英文灰色占位。区域悬停时内部右上角显示叉号，点击后无确认删除整个区域；空名称或名称不唯一阻止模板保存。
5. Preview 只使用虚构资料，不读取或记录真实患者内容。
6. 字段缺值显示可直接覆盖的橙色占位，不阻止医生保存或打印。
7. 模板保存不要求独立验证步骤，技术错误不向医生暴露 Token、Key 或 HTML。
8. 建立 Clinical Document Draft 后，医生可以修改或删除 Document content 的任何部分，包括合并后的文字。
9. 医生明确选择模板建立新草稿时，系统在合并字段初始化后只自动生成一次全部 AI 区域；默认打开、页签切换和重开文档不触发。区域生成发送 Template Description、稳定 Key、可选 guidance 和问诊上下文，并保留部分成功和迟到冲突保护。
10. Improve draft with AI 通过内部通用模型生成整份受限 HTML 候选。Template Description 与默认空白的本次要求分别发送，并携带最小必要结构化问诊上下文；不发送问诊转录及范围外敏感资料。
11. AI 区域生成期间只锁定对应区域，取消后才可编辑；单区取消不影响其他区域，失败区域可以单独重试。区域上方使用 AI is generating 或 Generation failed，右下角使用 Cancel generation 或 Try again。
12. 全文 Improve 允许所有自由文本输入为空，并以 Template name、Document type 和问诊上下文生成；请求及视觉输出期间锁定正文及模型输入，撤回始终可用。完整候选允许编辑，确认后扁平化为普通安全 HTML 并等待既有自动保存，撤回恢复原文。
13. 未确认候选不得自动保存、打印、签署或跨刷新恢复；离开模块、Print 和 Review & Complete 必须通过确认、丢弃或留在当前页面明确处理。
14. 每次成功保存仍形成可追溯版本并保留模板快照、Patient、Visit、Clinician、操作者及已确认 AI 来源，但不保存完整模型输入上下文或算法输出正文。
15. 生成失败恢复原文并允许主动重试；输入总长度超过 100,000 字符时不发送且不截断。不同页签可并行，但单页签同时只有一个 AI 操作。
16. 独立 Clinical Document App 复用相同 AI 体验并继续显式 Save；问诊台继续自动保存。本次不迁移既有模板或既有 Clinical Document Version；旧模板 AI 区域正文直接丢弃，只保留独立 guidance。