Clinical Documents 内嵌页签工作台重构 PRD

1. 文档信息

2. 目标

Clinical Documents 进入模块后直接呈现当前问诊的 Document content 编辑工作台。医生以接近桌面浏览器的页签方式同时处理多份文档，通过默认打开文档集减少重复选择，以自动保存取代手动 Save，并在当前编辑位置直接使用 AI、打印及模板设置。

本次重构遵循以下责任边界：系统负责患者与 Encounter 绑定、权限、版本、审计、安全 HTML、活动编辑权和可靠持久化；文档正文、Recipient 完整度、披露范围和临床事实由医生负责。内容不完整只提示，不阻断 AI、Print 或 Review & Complete。

3. 范围边界

3.1 本次包含

• Consultation Workspace 内嵌 Clinical Documents 的浏览器式多文档页签。
• 医生级、跨设备、可排序且最多六项的默认打开文档集。
• + 文档选择器，以及集成默认设置、新增模板和编辑模板的 Settings。
• 新文档 AI 区域自动生成、工具栏左侧全文 AI 改写入口、编辑区左侧 AI 卡片和工具栏右侧 Print。
• 多页签浏览器草稿、自动保存队列、Document ID 延迟建立和不可变后继版本。
• 已保存 Draft 的软删除、活动编辑工作台控制和异常恢复。

3.2 本次不包含

• 独立 Clinical Document App 的页面布局重构；它继续使用现有界面和显式保存交互。
• Signed、Issued、Voided、Reissued 生命周期的新增实现。
• 多人富文本合并、同时编辑或让医生处理版本冲突。
• Attachment Management、OCR 或外来文件编辑。
• 诊所级、专科级、管理员级或 Consultation Type 级默认文档集。

内嵌模块与独立 App 继续复用模板目录、文档、版本、AI 和打印服务；只有页面呈现与保存触发方式不同。

4. 规范领域语言

• 默认打开文档集（Default Open Document Set）：医生进入新 Encounter 的 Clinical Documents 时预先打开的模板集合；不是默认临床文档模板，也不会仅因显示页签立即建库。
• 文档页签（Document Tab）：当前 Encounter 中一份独立 Clinical Document Draft 的工作入口；同一模板可以建立多个文档页签。
• 活动临床文档工作台（Active Clinical Document Workspace）：当前 Encounter 唯一获准修改临床文档草稿的工作台。

文档页签以独立客户端 Key 标识，建立数据库聚合后再绑定 Document ID；不得再以 Template ID 作为草稿唯一键。

5. 页面结构

页面从上到下依次为：

1. 浏览器式文档页签栏。
2. 当前文档的紧凑资料条，只在适用时显示 Recipient 等资料。
3. Document content 富文本工具栏。
4. 可切换的左侧 AI 卡片与 Document content 编辑区。

内嵌工作台及其下方剩余空间统一使用同一浅灰背景并铺满问诊内容区，不得在编辑器结束后切换为另一层灰白底色。

移除现有 Document Family、Template 和 Saved Document 左侧选择栏，以及 Document content 区域外独立的 Save/Print 操作区。进入模块时不得先展示选择步骤或欢迎页；有默认或既有文档时直接选择第一项，没有文档时显示空编辑区和新增引导。

6. 浏览器式文档页签

6.1 视觉结构

• 活动页签使用白色或低透明浅色面，与下方编辑区连续连接。
• 非活动页签使用浅灰磨砂面，页签之间以细分隔线区分，不使用彩色胶囊按钮。
• 页签顶部使用浏览器式圆角，保留项目现有色彩、字体、阴影和焦点规范，不复制 Microsoft Edge 品牌色。
• 每个页签从左到右显示 Document Type 的 Iconify 图标、单行标题和右侧 X。
• 初始标题使用模板名称；选择 Recipient 后优先显示 模板名称 · Recipient；相同模板和 Recipient 重复时追加 （2） 等序号。
• 标题空间不足时单行省略，完整标题通过共享 Tooltip 展示。

6.2 宽度与溢出

• 页签目标宽度为 180–220px，可随空间收缩至约 120px。
• 超出可用宽度后使用横向滚动，并保证活动页签进入可视范围。
• 横向滚动条出现时页签栏按滚动条实际高度向下扩展，滚动条位于页签下方，不得覆盖页签内容；右侧固定工具继续与页签顶部对齐。
• + 紧随最右侧文档页签并与页签一同横向滚动；Print 和 Settings 固定在整条页签栏最右侧。
• + 和 Settings 必须提供 Tooltip、aria-label、键盘焦点和可见的 focus-visible。

6.3 切换与关闭

• 切换页签先把当前页签草稿写入按 Encounter 和页签隔离的 sessionStorage，不因此创建服务端版本。
• X 表示从本次问诊移除文档，不只是关闭视图。
• 未建立 Document ID 的页签直接移除；已保存未签署 Draft 经确认后软删除，保留版本和审计。
• Signed、Issued 和 Completed Consultation 不显示 X。
• 删除活动页签后优先选择右侧相邻页签；没有右侧时选择左侧。
• 最后一项删除后显示空编辑区，保留 + 和 Settings，不自动恢复默认文档。
• 当前 Encounter 已关闭的默认页签在离开模块并重新进入后不得复生；下一个新 Encounter 重新应用默认打开文档集。

页签不显示未同步琥珀点、保存动画或成功状态。只有自动保存最终失败或工作台失去编辑权时显示红点和 Tooltip，并保留一次克制 Toast。

7. 默认打开文档集

• 设置按不可变 Doctor User / Provider ID 保存并跨设备同步，不按诊所或 Consultation Type 分叉。
• 每位医生最多选择六个不重复模板，并保留明确排序。
• 新 Encounter 首次进入 Clinical Documents 时按顺序建立前端工作页签，尚不建立 Document ID。
• 默认打开文档集建立页签时不自动调用 AI 区域生成；自动生成只发生在医生明确选择模板建立新草稿时。
• 首次离开模块时，仍存在的全部页签都进入自动保存，包括医生没有修改的模板初始正文。
• 已保存过且内容、Recipient、页面尺寸、Letterhead、模板快照等均无变化的页签，不重复产生版本。
• 修改默认打开文档集不改变当前 Encounter 的页签；从下一个 Encounter 生效。
• 默认项对应的模板被停用、删除或医生失去权限时跳过该项并显示一次非阻断提示，不以失效模板建立文档。

8. 新增文档选择器

点击 + 后在按钮下方向下挂靠一个大型选择面板：

• 顶部提供模板名称、Document Type 和关键词搜索。
• 内容按 Document Family / Type 分组罗列全部当前可用模板。
• 停用、无权限或已删除模板不展示为可创建项。
• 真正执行创建的是模板；Document Type 只用于分组和筛选。
• 需要空白正文的类型使用受治理的 Blank Template，不允许绕过模板直接建立无来源文档。
• 同一模板可以多次选择并产生彼此独立的文档页签。
• 选择后关闭面板、把新页签加入最后一个文档右侧并立即激活；服务端完成合并字段初始化后，自动调用一次该模板的 AI 区域生成。

9. Settings

Settings 打开一个大型设置窗口：

1. 顶部展示默认打开文档集，支持拖拽排序、移除和从模板库加入，最多六项。
2. 下方展示可搜索、按 Document Family 分组的模板库。
3. 模板行提供 Edit；右上角提供 New template。
4. Edit/New 在同一窗口进入现有模板编辑体验，不依赖当前患者或 Encounter。
5. 默认模板编辑底部为 Restore / Preview / Save；个人模板编辑底部为 Delete / Preview / Save。

底部按钮保留可见文字与 Delete、Preview、Save 的语义色，同时统一采用 Consultation Note T、Clear 与 Review & Complete 的玻璃材质、圆角、阴影、Hover、Focus 和 Disabled 反馈。

10. Document content 工具栏

• AI 是工具栏最左侧的醒目文字按钮，使用艺术化 AI 字样，不额外叠加图标。
• AI 按钮复用 Consultation Note T、Clear 和 Review & Complete 的玻璃按钮样式。
• AI 按钮对所有可编辑 Clinical Document Draft 可用，不要求模板包含 AI 可编辑区域；它只负责打开全文改写卡片。
• 保留现有富文本格式工具。
• 编辑器不显示独立的 Document content 标题栏或系统字段缺值提示。
• Page size 单独靠齐工具栏最右且前方不显示竖向分隔线；Print 保留原工具位置。模板编辑器的 Field insert 与 AI area 继续紧随格式工具，不受 Page size 对齐规则影响。
• Document content 不提供 Save 按钮、Save 快捷键或其他手动保存入口。
• Print 使用 Iconify 图标、共享 Tooltip、aria-label、键盘焦点及明确禁用原因，不在按钮上显示文字。
• Document 模块不在页签栏上方或编辑器下方渲染临时错误、成功或 AI 结果提示卡片；操作反馈统一沿用现有弹窗或 Toast，活动编辑权等持续安全状态提示除外。

Save 的移除只适用于内嵌临床文档实例；Settings 中模板编辑器的 Save 继续保留。

11. AI 生成与改写

11.1 AI 区域自动生成

• 医生通过 + 明确选择模板建立新草稿时，在合并字段初始化后自动生成一次全部 AI 区域；默认打开文档集、页签切换及重开已保存文档不触发。
• 区域生成请求同时使用文档绑定的 Template Description、区域名称与可选 guidance，以及问诊上下文；Template Description 不复制到 AI 卡片输入框。
• 测试阶段既有模板的旧 AI 区域正文直接丢弃，不再进入新患者文档；只读取独立 guidance，不执行数据迁移或旧格式兼容。既有患者文档版本不变。
• 每个生成中区域的上方显示 AI is generating，下方显示持续旋转的刷新图标，右下角显示 Cancel generation。
• 生成期间只锁定对应区域；取消后恢复生成前内容并允许医生编辑，区域外正文及其他已完成区域仍可编辑。取消一个区域不影响其他区域，全部取消时中断浏览器请求，但不承诺停止算法服务计算。
• 完整响应到达后，以逐步呈现的视觉效果填入各成功区域。失败区域保留原内容，上方显示 Generation failed，右下角显示 Try again；重试只请求该区域。
• 同一文档的区域生成全部完成、失败或取消前，全文 Improve 保持禁用；不同文档页签可并行生成。切换页签时后台继续，页签显示克制状态；关闭页签取消本页签前端生成并忽略迟到响应。
• 区域生成期间锁定 Recipient。离开 Clinical Documents、Print 或 Review & Complete 时提供 Wait for AI、Cancel generation and continue、Stay here；等待完成后自动继续原操作，取消则恢复生成前内容再继续。

11.2 全文改写卡片

• 点击工具栏 AI 后，在编辑区左侧以内联卡片打开 Drafting Instructions；桌面空间不足时改为覆盖浮层，不产生水平不可达内容。
• 卡片打开状态由当前工作台共享；本次 AI 要求、请求状态、改写前正文和未确认候选稿按文档页签隔离。
• 切换页签时，卡片若保持打开则展示目标页签自己的 AI 内容。
• 卡片输入框不显示 Drafting instruction 或其他字段标题，默认保持空白，也不自动载入 Template Description；医生可以选择性输入本次全文改写要求。
• 卡片内 Improve draft with AI 保留原动作名称，但改用 Review & Complete 同款玻璃按钮视觉，不得把 AI 动作命名为 Review & Complete。
• Improve draft with AI 通过内部通用模型对当前整篇文档生成受限 HTML 候选，发送当前安全 HTML、Template name、Document type、文档绑定模板版本快照中的 Template Description、可选本次要求、Recipient 和服务端聚合的最小必要结构化问诊上下文。即使正文、Template Description 和本次要求均为空也允许使用，由模板身份与问诊上下文生成整份候选。
• 问诊上下文继续排除问诊转录、HKID、联系方式、地址、历史问诊、附件、保险及财务资料。AI 区域空白 guidance 的英文占位为 AI has access to the relevant information from this consultation. What would you like AI to write here? Tell it here!，占位本身不发送。
• 上游返回完整内容前显示 AI 生成状态；完整响应通过安全清理后在前端逐步呈现，形成视觉流式，不宣称内部模型提供 token 流。
• 内部通用模型固定使用 messages：system 消息约束不得创造事实且只返回受限 HTML，user 消息携带 Template Description、本次要求、当前 HTML、Recipient 和结构化问诊上下文；temperature 为 0，不发送 max_tokens。
• 从请求发出到视觉输出结束，整篇正文锁定；医生必须先撤回生成才能编辑。整篇候选以虚线框标识，左上角使用图标按钮，Tooltip 分别为 Confirm AI changes 和 Undo AI changes；撤回在等待与输出期间始终可用，确认直到完整展示后才启用。
• 全文 Improve 期间同时锁定 Recipient 和本次要求输入框；Page size 等未发送给模型的配置仍可修改。取消或撤回后恢复输入。
• 完整展示后的候选允许医生编辑。确认接受修改后的候选并扁平化为普通安全 HTML，不保留 AI 区域标记；确认只更新浏览器草稿并等待既有自动保存触发点，不立即建立版本。撤回恢复改写前内容并忽略迟到响应，不承诺终止内部模型计算。
• 视觉输出保持 HTML 结构始终完整，只逐步揭示文本节点和段落；短内容约 1 秒、普通内容约 2–3 秒、长内容最长 4 秒完成。
• 未确认候选稿不进入自动保存、打印、临床签署或刷新恢复数据。普通文档页签切换保留对应候选，页面刷新恢复改写前正文。
• 离开 Clinical Documents、Print 或 Review & Complete 时提供 Confirm AI changes、Discard AI changes、Stay here；Print 只要求处理当前页签，离开模块或 Review & Complete 要求处理全部候选页签。
• AI 请求、结果、取消、确认与撤回只记录 request ID、输入摘要哈希、耗时、状态、操作者和 Visit/Document，不记录完整输入或输出正文；确认后的版本关联 request ID 与 AI 来源类型。
• 调用失败、超时、空响应或不安全 HTML 时恢复原文并解除锁定，保留本次要求，通过 Toast 提示且不自动重试。完整 messages 超过 100,000 字符时不发送、不截断，并提示医生缩短正文或本次要求。
• 每个文档页签同时最多运行一个区域生成或全文 Improve，不同页签可以并行；多个区域成功结果并行揭示。确认后的专用撤回按钮消失，但编辑器标准 Undo / Ctrl+Z 可以撤销整次全文替换，直到普通编辑历史被清除。
• Recipient、合并字段或正文不完整只显示非阻断提醒；AI 请求允许 Recipient 为 null/未指定，不得补造收件机构。
• 缺少 Patient/Encounter/Doctor 安全上下文、没有权限或工作台不是活动编辑者时，AI 被系统阻断；模板没有 AI 区域不阻断全文 Improve。

12. 自动保存、Document ID 与版本

12.1 触发点

• 切换 Clinical Documents 到其他问诊模块。
• 切换 Patient / Encounter。
• 返回 Consultation Queue。
• 离开当前 Consultation 路由。
• 打印当前页签。

普通文档页签切换不触发服务端保存。关闭浏览器或标签页只承诺 sessionStorage 恢复，不承诺异步服务端请求必然完成。

12.2 保存范围

• 离开模块、Encounter、Queue 或路由时，串行保存当前工作台仍存在的全部页签。
• Print 只保存并打印当前页签，不顺带保存其他页签。
• 页签存在未确认全文候选时，自动保存继续以改写前权威正文为准；Print、离开 Clinical Documents 或 Review & Complete 必须先解决候选状态。
• 首次成功自动保存或打印时建立 Document ID 和 Version 1。
• 已存在文档有变化时追加不可变后继版本并更新当前版本指针；不得原位覆盖历史版本。
• 客户端呈现当前活动工作台内容直接胜出，不向医生展示版本选择、合并或冲突处理。
• 相同内容的重试复用幂等操作标识，不产生重复 Document、Version 或审计事件。

12.3 浏览器保护与失败

• 每次编辑及页签切换都把草稿写入以 Doctor、Clinic、Encounter 和页签 Key 隔离的 sessionStorage。
• 暂态错误按 ADR-0013 的错误分类退避重试三次。
• 最终失败允许导航继续，保留本地草稿、在对应页签显示红点并只提示一次 Toast。
• 自动保存恢复成功后清理错误状态并提示一次，不显示常态保存成功提示。
• 任一当前文档尚未成功持久化时，Review & Complete 检查清单仍可打开，但不能确认完成。

13. 单一活动编辑工作台

• 服务端按 Encounter 维护一个活动 Clinical Documents 编辑租约，覆盖所有获授权临床人员，而不只限定同一账号。
• 后打开并成功取得租约的工作台成为唯一写入者，先前工作台自动转为只读并显示简短提示，不要求医生选择或合并。
• 写请求必须携带活动工作台标识；旧工作台、无权限工作台或过期租约写入由服务端拒绝。
• 活动工作台对未签署 Draft 的内容是当前权威来源；服务端在最新版本后追加其内容作为后继版本。
• Signed、Issued、Voided、Completed Consultation 或其他不可编辑状态不因取得活动租约而重新开放。

租约续期、过期和连接恢复必须避免两个工作台同时成功写入；具体心跳间隔属于实现参数，不在产品界面暴露。

14. Recipient 与非阻断内容提醒

Recipient 可以为 null/未指定 并进入 Document Version 快照。系统合并字段缺少权威值时直接在正文中留空，不显示 missing 标识，也不显示独立缺值提示。缺少 Recipient、正文为空或 AI 区域为空时：

• 页面显示克制的非阻断提醒；
• 允许自动保存；
• 允许 AI；
• 允许 Print，并按当前正文原样输出；
• 允许 Review & Complete 签署当前版本；
• 审计记录当时存在对应非阻断提醒；
• 系统不得自动补造 Recipient、临床事实或缺失正文。

以下情况仍必须阻断，因为它们属于身份、安全、持久化或不可变性边界，而不是医生对内容负责：

• Patient、Encounter、Clinic 或 Doctor 上下文不匹配；
• 使用者没有读写权限或工作台不是活动编辑者；
• 文档已 Signed、Issued、Voided，或 Consultation 已 Completed；
• 内容无法通过安全 HTML 清理或容量限制；
• 自动保存最终失败，当前内容尚未可靠进入数据库；
• 打印无法建立 Document ID、持久化当前版本或记录披露审计。

15. Completed Consultation

• 文档页签与 Print 保留，Document content 全文只读。
• 隐藏 X、+ 和 AI。
• Settings 继续可用，因为模板管理是医生个人配置，不修改已完成问诊。
• Print 不改变 Signed、Issued 或其他文档状态。

16. 验收基线

1. Consultation 内嵌 Clinical Documents 进入后直接显示浏览器式页签和 Document content，不出现原有选择栏；独立 App 界面保持原状。
2. 页签具有左侧文档图标、截断标题、右侧 X、活动页签与编辑区连接、非活动浅灰面、横向溢出；+ 与 Settings 固定可达。
3. 默认打开文档集按医生跨设备保存、最多六项且有序；只影响新 Encounter，当前 Encounter 不因设置变化被增删页签。
4. 同一模板可以创建多个独立页签，内容、Recipient、AI 状态、Document ID、版本和浏览器草稿互不覆盖。
5. 关闭未入库页签不调用删除 API；关闭已保存 Draft 只做软删除；Signed、Issued 和 Completed 不提供 X。
6. 工具栏最左侧是玻璃样式 AI，Clear formatting 右侧分隔后只有图标 Print，Document content 不存在 Save。
7. 医生通过 + 明确选择模板建立新草稿时，系统在合并字段初始化后自动生成一次 AI 区域；默认打开文档集、页签切换和重开已保存文档均不触发自动生成。
8. AI 卡片从编辑区左侧打开；无标题输入框默认空白且不复制 Template Description。Improve 使用模板身份、文档模板版本快照与 messages 调用内部通用模型，即使正文和自由文本输入均为空也可生成整篇受限 HTML 候选，并以视觉流式、虚线框及确认/撤回呈现。
9. 全文请求和视觉输出期间整篇正文不可编辑，除非医生先撤回；完整候选允许继续编辑，确认后扁平化为普通安全 HTML。
10. 未确认全文候选按页签暂存但不自动保存、打印、签署或跨刷新恢复；普通页签切换保留候选，离开模块、Print 和 Review & Complete 前必须通过确认、丢弃或停留明确处理。区域仍在生成时则提供等待、取消并继续或停留。
11. 离开模块保存所有剩余页签；Print 只保存当前页签；首次成功持久化建立 Document ID，内容无变化不产生重复版本。
12. 自动保存失败不锁住导航，但保留浏览器草稿、显示一次错误并阻断最终 Review & Complete；恢复后不覆盖新的 Patient、Encounter 或页签。
13. 同一 Encounter 只有一个活动编辑工作台；新工作台取得编辑权后旧工作台自动只读，医生不处理版本冲突。
14. Recipient、正文或合并值缺失只提示，不阻断自动保存、AI、Print 或 Review & Complete；身份、权限、安全 HTML、持久化失败和不可变状态继续硬阻断。
15. Settings 同时支持默认集排序、模板搜索、新增和编辑；模板编辑底部按钮使用统一玻璃材质并保留语义文字与颜色。