Patient & eMR 信息架构、字段取数与前台业务流转 PRD

日常业务与测试阅读请使用患者、预约、到诊与护理业务 PRD。本页保留工程细节、历史变更与取数参考；已知冲突见实现记录。

配套审查：ui_review_evidence.md#patient-emr-audit 记录当前实机问题、优先级和验收口径。下文截图为 2026-08-18 当前原型证据，不等同于目标验收稿。

1. 问题陈述

现有 Patient & eMR 页面混用了患者主档、预约备注、Visit、Consultation、处方、药房履约和迁移附件等不同粒度的数据，导致同一字段在多个页面语义不一致：例如把内部 Visit ID 显示为 Chit Number、把签署时间当作就诊日期、把历史自定义 HTML Note 拆成 SOAP、把处方与药房订单合并成同一种 Medication、以及把仅保留元数据的附件呈现为可预览文件。

本 PRD 以“患者主档是患者级事实、Visit 是一次到诊、Consultation 是一次临床记录、订单/附件必须保留来源关系”为基础，定义前台业务流转、页面职责、元素取数及 fallback 规则，使开发、迁移、测试和 UAT 使用同一语义。

2. 目标

1. 患者在 Patient & eMR、预约新增/编辑等入口使用同一套患者主档字段和校验规则。
2. Patient No.、MRN、Visit ID、Chit Number 各自只在有真实来源时按正确名称展示。
3. Consultation History 能正确呈现本地 SOAP 和迁移的 Custom/HTML Note，并保留日期、医生、诊所、来源与签署信息。
4. Medication History 明确区分医生处方与药房履约，不在临床历史页面展示价格。
5. Attachment 明确区分 Available、Metadata only 和 Unavailable；无文件或 OCR 时不提供虚假预览入口。
6. Vital Trends 覆盖现有结构化生命体征并保留 Visit、诊所、医生、记录人和来源上下文。
7. 所有已实现的患者队列以同一姓名链接进入对应 Patient & eMR，并保留 Patient、Visit、Clinic 和返回来源。

3. 非目标

• 不新增患者、疫苗、保险或通信数据库表；缺少 canonical source 的功能只保留入口或空状态。
• 不把 Appointment remark、Visit reason、Consultation complaint 合并为同一字段。
• 不建设外部 Lab / Imaging 承接工作台；内部执行属于 Line C。
• 不在 Patient & eMR 中编辑历史 Consultation、Medication、Vitals 或 Attachment。
• 不把 clinic_patient_operating_unit_links 中任意一条定义为 Primary Clinic；Phase 0 没有该业务概念。 新注册患者自动归属当前注册诊所；旧无归属患者经有维护权限的护士明确“接收登记”后可编辑，预约独立进行，规则见 组织、数据权限与授权方案。
• 不以预览 Mock 的完整度宣称生产数据已迁移、联调或 UAT 完成。

4. 用户与核心任务

• 前台：同集团按角色权限查找患者，按诊所资格新建、修改及确认基础信息，创建／确认预约；不维护医疗／安全或保险计划，不签到。护士：按诊所资格维护获授权资料与计划，在同 Clinic／Provider 服务范围内处理预约、签到、问诊前准备、本次附件及 Cashier。
• 医生：从 Consultation Queue 进入问诊，在临床工作台查看患者安全信息和纵向历史，完成诊疗记录、处方及订单。
• 药房/执行部门：承接处方或内部 Lab / Imaging 订单并回写履约状态。
• 患者资料管理员：在有权限和变更原因的情况下修正患者主档、诊所关系和安全信息，并保留版本记录。

5. 端到端业务流转

flowchart LR
    A["Search patient"] --> B{"Existing patient found?"}
    B -- Yes --> C["Select patient master"]
    B -- No --> D["Create patient: name + phone + ID required"]
    D --> E["Duplicate check"]
    E --> C
    C --> F["Create appointment"]
    F --> G{"Appointment confirmed?"}
    G -- No --> H["Calendar only; listed after confirmed appointments"]
    G -- Yes, same day --> I["Registration Queue: Awaiting check-in"]
    I --> J["Check in"]
    J --> K["Continue to preparation"]
    K --> L["Ready for consultation"]
    L --> M["Consultation Queue"]
    M --> N["In consultation"]
    N --> O["Ready for cashier"]
    O --> P["Checkout completed"]
    P --> Q["Financial completed: payment / receivable arrangement recorded"]
    Q --> R["Closed at first clinical signature +24h when no blocker"]

5.1 允许的回退

5.2 浏览器本地预览旅程

为便于在没有可用临床 API 的本地预览中验证页面衔接，/preview/ 路由允许同一合成患者按以下顺序跨 App 流转：

1. Appointment Calendar 建立或选择明确标记为 Preview only 的 Appointment。
2. Reception / Registration 读取同一 Appointment；Check-in 时建立浏览器本地 Preview Visit，并保留 Patient、Appointment、Visit 和来源关系。
3. Visit 经 Preparation 进入 Ready for consultation 后，Consultation Queue 才显示该患者。
4. Consultation 开始时只更新浏览器本地 Preview Visit，不调用真实临床写入 API；Reset demo 清除整条本地旅程。

该能力仅是源代码中的本地预览基础，不是生产持久化、部署、端到端联调或 UAT 证据。普通桌面路由不得读取或写入这套合成旅程；专用预览路由不得混入不可用开发 API 的错误横幅或真实队列数据。Reception 仍通过用户显式 Apply filters 刷新，不以旧版自动日期监听替代已确认的 STG 交互。

5.3 Appointment 与 Registration 的关系

1. 只有当天且已确认的 Appointment 进入 Registration Queue。
2. 未确认预约继续保留在 Appointment Calendar，并在当日已确认记录后展示。
3. 在 Reception 新增 Appointment 时，成功保存后进入 Awaiting check-in，但不会自动创建 Visit 或自动 Check-in。
4. Appointment 新增与编辑至少要求选择已保存且具有稳定 patient_id 的患者、Assigned Provider、预约日期、有效时间和 Service Type。仅输入姓名或保留上一位患者的显示字段不得保存；切换/清除患者时必须同时清除旧 patient_id。前端在提交前逐字段提示，后端重复校验；缺少医生、时间或稳定患者关联不得保存 Booked / Confirmed Appointment。
5. Patient identity、payer/insurance 等已在患者主档或预约阶段完成的字段由系统读取状态，不要求护士再次手工勾选“已确认”。
6. 已有 patient_id 的患者打开 Check-in 时，系统必须重新读取当前 Patient & eMR 主档，并以主档中的姓名、Patient No.、主手机号、HKID / passport 和证件类型作为表单默认值；Appointment 快照仅在主档对应字段为空或主档读取失败时作为 fallback，不得用空白、旧值或脱敏值覆盖主档。
7. Check-in 以本次加载的 Patient 主档值作为编辑基线。值未发生实质变化（忽略大小写、空格、连字符和括号等格式差异）时不得再次执行新患者 duplicate verification；仅当用户确实补充或更正身份字段时，才检查是否与另一患者主档冲突并记录版本与审计。
8. Check-in 表单须显式提交实际编辑过的身份字段。Appointment 快照中未经用户修改的旧值、组合姓名、脱敏值或格式差异不得覆盖已完整的 Patient 主档，也不得触发 duplicate verification；未标记为已编辑的预约快照值只可用于补全患者主档的空字段。
9. Appointment 已明确选择 Self-pay 或有效保险快照时，Check-in 必须继承该 payer / coverage 状态；只有 Appointment 未记录 payer 或用户确实需要改正时才要求重新选择。异步加载 Patient 主档不得替换表单响应式对象或令已继承字段在输入控件中变为空白。
10. Registration 的主操作依次为：Check in → Continue to preparation → Ready for consultation。

5.4 队列顺序、人工调整与排队中取消

1. Reception / Registration Queue 默认按实际到达时间从早到晚展示；尚未到店、只有 Appointment 的记录才以预约时间作为 fallback。In consultation 与 Ready for cashier 是追踪状态，固定排在仍可由 Reception 操作的记录之后。
2. Reception 可以在列表最左侧使用上移 / 下移按钮调整同一运营分组内的患者先后顺序；不得把下游追踪状态混入当前叫号顺序。当前实现保留本次已加载队列的人工顺序；跨终端共享和持久化 queue rank 仍需独立后端字段与并发规则。
3. Modify appointment 内提供 Cancel appointment，仅适用于仍在 Reception 可控范围内的 Appointment / Visit。取消必须填写原因，Appointment 保留为 Cancelled，不得物理删除。
4. Appointment 已产生活动 Visit 时，取消通过同一服务端事务把关联 Visit 更新为 Cancelled，并分别写入 Appointment / Visit 状态事件和审计；任一更新失败则整体回滚。已进入只读临床完成状态的 Visit 不允许从 Reception 取消。
5. 已经 Ready for consultation 的患者必须先用 Previous stage 回到 Preparation 并记录回退原因，才允许修改或取消 Appointment；已经 In consultation 的患者走临床中止 / 回退流程，不复用前台取消预约。

5.5 Financial Completed、Closed 与未结应收

1. Encounter 关闭与保险公司实际回款时间分离。临床已签署、Checkout 与付款 / 应收安排已记录、Pharmacy / V-Lab 等即时 Handoff 已接收，且不存在未处理的患者安全或收费阻断时，Encounter 具备关闭条件。
2. 系统以第一次 Review & Complete 临床签署时间为基准；满足关闭条件后，在该时间满 24 小时自动进入不可逆 Closed。付款或 Checkout 不重新起算 24 小时。
3. 保险未回款或患者欠款进入独立 Accounts Receivable / Outstanding Payment，不阻止 Encounter Closed。长期等待的 Lab / Imaging 结果可在 Closed 后以关联 Result Event 回传并要求 Doctor Acknowledgement。
4. Closed 后不得恢复原 Encounter；后续退款、冲正、保险回款分配和临床更正必须创建与原记录关联的财务或临床事件，并保留原事实。

6. 全局数据语义

6.1 标识符

6.2 日期

6.3 空值与迁移数据

• 空值保持 Not recorded、Status not recorded 或隐藏可选板块；不得自动推断临床含义。
• 缺失 Allergy certainty 不自动变为 Certain；缺失 severity 不自动变为 Alert。
• template_type=custom 的 history 标记为 Legacy consultation note，清理脚本、事件属性、链接和外部资源后保留段落/列表结构。
• template_type=soap 才按 Subjective、Objective、Assessment、Plan 展示。
• 只有真实结构化 clinic_consultation_diagnoses 才展示 ICD-10 标签；自由文本 diagnosis 不伪装成 ICD-10。
• storage_status=metadata_only 表示历史文件元数据存在，但文件内容不可用；不提供点击预览。

7. 页面规格与取数

7.1 Patient Directory

页面职责

查找患者、创建患者、选择患者并在右侧同一工作区切换患者级 Tab；不得跳转到脱离当前上下文的新页面。

元素与取数

Patient & eMR 的身份查询、资料维护及病历读取采用 Frontoffice §2 与 Platform 数据分类 的现行规则：同集团具角色查询权限者可检索／查看基础信息，敏感字段默认隐藏并经独立申请查看及审计；修改／确认另查诊所资格，公共医疗信息另查角色授权，受限问诊正文及历史附件另查医生授权。原仅Active Operating Unit active link的搜索限制已被取代；初始未搜索、无匹配和接口失败仍分别呈现。

Appointment Calendar 的新增 / 编辑预约患者选择属于不同业务任务：在用户输入统一患者查询后，可在获授权的 Medical Group 患者主档中查找已有患者，当前诊所患者优先展示，跨诊所结果明确标识。返回跨诊所候选的检索须记录操作者、当前诊所、工作流目的、结果数量和请求上下文，但不得在明文审计字段中保存 HKID、电话或原始搜索词。用户确认身份并保存预约时，后端再建立或恢复 Patient + Active Operating Unit 关系，记录操作者、来源、原因、前后状态和请求上下文；此后该患者才能出现在 Patient & eMR 的本诊所目录中。取消患者选择或未保存预约不得提前建立诊所关系。

预约中的 duplicate verification 只属于“创建新患者”路径。用户从普通搜索结果或 duplicate candidate 中选择已有患者时，系统必须退出新增患者模式，只保留该记录的 patient_id 并调用 Appointment 保存接口；不得再次调用 Patient create/upsert，也不得把同一患者命中为自身 duplicate。新增患者成功保存后同样先取得稳定 patient_id，再作为预约患者继续。

Appointment 页面不承担已有患者主档维护。选择已有患者后只展示姓名、Patient No.、电话、DOB、性别和 Alert 等只读摘要，并提供 Open Patient & eMR；姓名、电话、证件、保险卡等新增或修改必须在 Patient & eMR 完成。Appointment 仅可从已保存的患者保险卡中选择本次预约使用的卡，并维护本次预约专属的 Case No.、eligibility 和 insurance notes。只有 Register new patient 分支可在预约流程中填写患者建档信息和初始保险卡。

Patient Directory 不提供通用 Excel / CSV 模板、导入、导出或无明确业务日期的范围导出。患者批量迁移或治理属于权限受控的后台任务，必须另行定义对象范围、重复合并规则、校验预览、审计和失败回滚，不能复用前线目录工具栏临时暴露。

跨队列 Patient & eMR 导航

• Reception、Consultation（包括问诊台左侧队列）、Checkout、Dispensing 和 Tasks & Follow-up 中的患者姓名，在存在稳定 patient_id 时使用同一 PatientEmrLink 打开 Patient & eMR Overview。
• 导航上下文必须携带 patientId、可用的 visitId、Active Clinic、来源 Queue 和 returnContext；重复打开已存在的 Patient & eMR 窗口时切换到新患者，而不是保留上一位患者。
• Patient & eMR 优先按 patientId 读取获授权的权威患者主档；队列中的姓名 / MRN Snapshot 只用于加载期间及接口失败时的明确降级，不得覆盖权威主档。
• 点击患者姓名只执行患者档案导航，不得同时触发行选择、开始问诊、选择收费 Visit 或选择配药订单。键盘焦点、可访问名称和“打开 eMR”图标必须可见或可感知。
• 未完成建档、没有稳定 patient_id 的 Walk-in 姓名保持不可点击，并提示需要先保存患者档案；不得按姓名猜测或路由到模糊搜索结果。
• Patient & eMR 顶部返回动作优先使用 returnContext 回到原 Queue；没有来源上下文时才返回 Patient Directory 搜索。
• 桌面应用打开事件记录来源 App、Patient、Visit、Clinic 和返回 App 标识；不得把 HKID、电话或原始搜索词写入导航审计上下文。

患者创建

• 新建患者必填 name、主手机号 mobile 和 hkid（HKID / passport document number）。三项必须齐全才执行保存及重复核验。
• Patient No. 由现有编号逻辑生成；表单只展示，不允许一般用户手工改号。
• 保存前执行重复校验：证件号完全一致直接视为重复；证件号不同但规范化姓名与主手机号同时一致也视为重复。电话单项或姓名单项一致只作为候选线索，不单独阻止创建；预览用“陈大文”覆盖冲突场景。
• 扫码入口只负责展示二维码、复制链接/二维码到其他平台；本期不承诺患者端真实提交接口。
• 从预约入口创建患者时复用 PatientInformationForm 和 PatientInsuranceCardsEditor，预约弹窗不复制完整患者字段。

7.2 Patient Overview

页面职责

患者主档的权威查看和编辑入口；任何业务节点触发的患者资料修正最终写回同一主档并产生版本记录。

Insurance authority 与 Visit eligibility

1. Benefit Contracts 模块是权益规则权威入口：Benefit Contract / Plan / Rule 管适用服务、折扣、额度和有效期；同模块下的 policy_card 是可选择 Card Programme / 官方卡图的共享后端目录。Insurance Card Master 中，Insurance 类型可关联 Policy；企业合作计划必须关联 Benefit Contract，且只允许 corporate_membership 或 staff_benefit 两类。Patient & eMR 不保存第二套规则或前端硬编码目录。
2. Patient & eMR 只维护患者实际持卡实例：card_programme_id 引用、Member / Policy Number、有效期、主卡和备注，并保存选择当时的 programme/provider/plan 快照供历史解释。Finance / Benefits Admin 维护卡目录和卡图；目录失效不删除历史持卡记录，但不可用于新选择。
3. Registration 在 Check-in 时记录本次 Visit 的 eligibility 结果、核验方式、人员、证据和时间。Cashier 在 Invoice Post 前对过期、变更或未确认记录进行最终复核。
4. Phase 0 允许人工核验，不把页面结果描述成保险公司实时 API 响应。已 Post 的 Invoice 保存当时适用的 Plan / Rule / Eligibility Snapshot，不随主档后来修改。

Clinic affiliation 规则

1. 首次创建/匹配患者时，按操作人员 Active Operating Unit 自动建立第一条关系。
2. 患者在其他诊所创建并确认 Appointment / Visit 时，系统 upsert 对应 Patient + Operating Unit 关系。
3. 手工新增/停用属于患者资料管理能力，必须校验同一 Medical Group、权限、变更原因和审计；当前生产 API 尚未完全支持任意关系维护。
4. 页面不展示或维护 Primary Clinic；“常看医生”由近期完成的 Consultation 汇总，不是静态患者字段。

7.3 Consultation History

信息层级

1. 顶部横向缩略轴：就诊日期、医生、真实 Chit 或 Visit reference、状态。
2. 详情头部：Visit type（标题）、Visit reason / booking remark（辅助）、医生、诊所、状态、签署时间、来源。
3. 临床内容：SOAP 或 Legacy custom note、结构化 ICD-10、Vitals、Medication、Orders & procedures、Attachments。

7.4 Medication History

Medication History 是跨 Consultation 的检索视图，但每条记录始终保留所属 Visit、医生和诊所。

Doctor prescriptions

• 数据：clinic_prescriptions + clinic_drug_master。
• 展示：medication name、sig、quantity/unit、safety note、source。
• 不展示：unit price、total amount。

Pharmacy fulfilment

• 数据：clinic_medication_orders + clinic_drug_master。
• 展示：drug code、display/generic/brand name、sig、quantity/unit、status、ordered_by、reviewed_by、label language/preview、labelled/packed/dispensed time、safety note。
• 处方和药房履约可以同药重复出现，因为它们代表两个不同业务事实；通过小标题区分，不用颜色暗示它们相同。

7.5 Vital Trends

该页面只读，不创建第二份 Vital。时间范围和指标切换只影响展示，不修改源数据。

7.6 Attachments

预览弹窗统一命名为 Attachment details；不再把所有附件都称为 OCR result。

7.7 Vaccine 与 Communication

• Vaccine History 只展示已有 encounter service 数据；当前没有 canonical vaccine registry 时，不新增 dose、route/site、manufacturer 或 lot/batch。
• Communication History 保留 Tab 和简洁空状态；本期不构造虚假通信记录和筛选字段。

7.8 当前界面展示与页面结构

7.8.1 Patient Directory / Overview

页面采用左侧 Patient Directory、右侧患者详情的同一工作区结构。患者姓名、诊所归属和常看医生固定在详情头部，Overview 与各类历史通过右侧 Tab 切换，不跳转到新的患者页面。

当前证据：Overview 内容区因运行错误空白，且新增患者弹窗关闭后重复校验错误仍残留。该截图是 P0 缺陷证据，不是目标布局。

目标布局顺序：

1. Identity & contact；
2. Clinic affiliations 与常看医生；
3. Insurance 与 Panel / Company；
4. Allergy / ADR / Alert；
5. Caregiver、Messaging、External/eHealth 等低频信息。

Overview 默认只读，提供单一明确的 Edit。编辑使用统一 Save / Cancel、版本冲突和变更原因，不为每个卡片创造独立保存机制。

7.8.2 New Patient、二维码与重复校验

界面规则：

• 姓名、主手机号、HKID / passport document number 为新建患者必填项；三项同时用于 duplicate verification。
• Patient No. 为只读系统值，不使用可编辑输入框外观。
• Document type/country、language、messaging、安全信息等可选字段默认必须为空或 Not recorded；不得把常用值自动保存为患者事实。
• Patient self-entry 统一使用同一套二维码生成机制与 H5 流程，不区分现场与预约两套产品入口；但二维码不能是所有患者共用的静态图片。护士先输入姓名、主手机号及 HKID / passport document number，系统建立待登记 Intake Draft，再签发绑定该 Draft 的患者专属 48 小时令牌。超过服务端签发时间 48 小时后不得继续打开、保存或提交，二维码与 URL 不得直接携带姓名、电话、证件号码或其他患者资料；H5 必须通过令牌向服务端读取 Draft。
• H5 不使用手机 OTP。患者提交只形成 Patient Self-entry Submission 待审核记录，不直接建立 Patient ID，也不得直接覆盖已有 Patient Master；2026-09-07 更新：集团级匹配前移到患者填写后的核对环节，患者确认一致后保留对应既有 Patient 的关联结果；字段修正和最终主档写入仍由获授权护士审核。正常审核页不再重复弹出同一患者的匹配提示。
• H5 打开后直接展示护士已输入的姓名、主手机号、证件类型及 HKID / passport document number，患者以“核对”为默认动作；发现错误时可以修改，系统须保留原值、患者修改值与变更标记供护士审核。出生日期和性别仍由患者补齐，连同上述字段构成提交前必填的基础资料。中文姓名、Email、地址、紧急联系人、首选语言及协助需要为额外资料，可逐项填写或整体跳过。
• 保险 / 企业保障是独立的可跳过 H5 步骤，不使用自由文本让患者手工输入保险公司。患者按 payer / sponsor、Card Programme 或 Plan 名称搜索，先在 Insurance card、Corporate / staff plan 类型中选择一个主要保障，再填写卡上的会员 / 员工编号及可选的保单 / 企业计划编号。卡面只可展示后台已配置的官方图片；未选择不影响提交，且选择结果只作为待护士核验资料，不代表已完成 eligibility 或保险公司实时确认。
• H5 使用繁体中文 / English 单列移动表单，按欢迎、基础资料、额外资料、保险及企业计划、核对及同意、提交成功推进。Consent 必须与可选通讯同意分开；主按钮使用 Submit for clinic review，不得称为完成注册。成功页只显示提交编号、诊所与护士核验提示，不完整回显敏感资料。
• Patient & eMR 首页以高亮待办提示显示待处理自助登记数量，并进入双栏审核工作区。审核工作区区分 Awaiting review、Needs clarification、Approved、Rejected；关联结果独立为 Linked patient 或 New patient，（旧状态由下述 2026-09-07 新规则取代）。审核支持已确认关联摘要、完整资料、带原因修正、批准／待澄清／拒绝和历史。
• 当前仓库已实现 H5、诊所预填身份摘要、可编辑基础字段、独立保障计划选择步骤、48 小时前端到期展示、二维码入口、首页待办提示和审核工作区的前端版本；当前令牌换取 Draft、审核数据与操作仍为 preview。生产仍需要 Intake Draft 持久化、服务端签发 / 撤销令牌、按令牌读取预填资料、按令牌读取已启用的脱敏 Card Programme / Benefit Contract 目录、限流、权限、Consent 版本、重复匹配、原值 / 修改值审计、字段级写入与审计 API，前端到期参数不构成生产安全控制。
• 重复匹配需展示命中依据，允许打开已有患者或返回修正；关闭弹窗必须清空本次错误和草稿状态。

7.8.3 Insurance card selector

桌面 Patient & eMR 的保险 / 企业合作卡先从共享后端 Card Programme 目录选择，再带出 programme type、payer / sponsor、plan 及来源快照并填写患者卡号、保单号和有效期。Insurance 类型的来源为 Policy；Corporate membership / Staff benefit 的来源为对应类型 Benefit Contract。H5 的企业 / 合作机构计划从共享 Benefit Contract 中状态及有效期合格的 corporate_membership / staff_benefit Plan 选择；不在 Patient 主档中建第二份前端名单。H5 必须通过当前 Intake Draft 的有效令牌调用专用的脱敏公共目录端点，只返回当前诊所可选的 ID、类型、payer / sponsor、programme / plan 名称和官方卡面；公网 H5 不得直接使用需要 benefits.read 的内部管理 API。目录为空时显示可跳过的治理空状态，不展示内置名单或生成卡面。桌面端目标交互使用可搜索 combobox/弹层、常用卡优先和虚拟滚动；图片仅使用后台配置的官方 URL。当前 H5 preview 使用明确标记的示例目录证明交互，不能作为生产目录或已完成联调的验收证据；此前截图也不能继续作为当前验收证据，待目标环境部署后重拍。

7.8.4 Consultation 与 Medication

Consultation 横向轴只负责定位日期、医生、Visit/Chit 与状态；详情承载 SOAP、结构化 ICD-10、Vitals、Medication、Orders 和 Attachments。Medication 专题页按 Doctor prescriptions 与 Pharmacy fulfilment 分区，汇总必须分别计数，不得把药房订单称为 Rx。

7.8.5 Vaccine 与 Vital Trends

Vaccine 只展示现有 service 数据；缺少 canonical registry 时不新增批号等字段。Vital 的指标切换、趋势图和明细共用同一源数据；指标栏和宽表必须在 1280px 下有清楚的滚动/折行提示，并覆盖 RR、Height、BMI、BSA、Visit 和来源。

7.8.6 Attachments 与识别结果

附件跨 Visit 检索并逐条校验来源授权，每个文件保留所属 Visit/Chit。本次关联护士可上传、查看、删除；历史记录须有效医生授权，前台不得管理附件。目标弹窗采用 Original / Extracted fields / Full text 分区或 Tab；Metadata only 使用明显的不可点击样式并解释原因。

7.8.7 Communication History

正式业务模式下，本期空状态应紧凑说明“不支持/无 canonical source”，不构造虚假记录，也不增加无功能筛选。无记录不能被解释为患者从未与诊所沟通。独立 Preview 模式可以使用明确标记为 Preview data 的本地合成通讯记录，以验证 channel、purpose、outcome、operator 与 time 的布局；该 fixture 不调用写 API，也不得与真实患者记录混合。

7.8.8 Appointment Calendar

Calendar 采用工作周与选中日 50/50 布局；状态与 Consultation Type 分开筛选。两个并列 Grid 必须共用同一个起始小时、固定 30 分钟刻度和滚动位置；Appointment 与 Block-out 按真实持续时间计算高度，同一 clock time 在两侧映射到同一时间轴位置。选中日 Grid 不能因为卡片内容较多而撑高一个 slot，否则后续时间会整体错位；详细字段由 List 或详情弹窗承接。

预览必须提供稳定 fixture，覆盖患者最低识别信息、Unconfirmed、Confirmed、Cancelled、Block-out、Non-consultation、Prescription-only、Treatment/Procedure 与 Day Procedure，以便验证时间、颜色、操作和回退。同一位本地合成患者还应贯通 Patient & eMR 的 Overview、Consultation、Medication、Vaccine、Vital、Attachment 与 Communication 页签，并始终明确标记 Preview 边界。

新增 Appointment 只能选择 Booked 或 Confirmed。Arrived、Checked-in、Completed 和 Cancelled 属于下游工作流状态，不得通过新增或普通编辑表单直接写入；进入下游阶段后，状态字段只读，由对应业务动作推进。取消 Appointment 是独立的不可逆状态动作，必须二次确认、要求填写原因并把原因写入可审计记录；关闭或取消弹窗不得产生状态变化。

7.8.9 Registration Queue、Check-in 与 Preparation

Registration 的界面顺序为 Queue → Check-in → Preparation → Ready for consultation。Patient information、payer 和 consent 必须区分 Automatic、User confirmed 与 Missing，并展示取数来源；Preparation 的 chief complaint、Vitals、pre-check 和附件写入 Visit intake，不覆盖医生 Consultation SOAP。

Check-in 必须核对并补齐姓名、主手机号和 HKID / passport。用户在 Check-in 中修正或补录的三项信息先写回同一 clinic_patients 主档，并生成 Patient version 与 audit，再创建 / 复用 Visit；任何一项缺失都不得进入 Preparation、Ready for consultation 或后续 Encounter 状态。服务端状态转换必须重复执行该门禁，不能只依赖前端禁用。

队列页不常驻展示成功消息或“请先补齐资料”一类预期流程提示。字段缺失、payer 未选择等可由当前操作解决的校验只在对应 Check-in / Preparation 弹窗内展示并在关闭后清除；真实的队列加载、Patient 主档读取或写入 API 异常仍须在受影响区域提供错误和重试信息。

Visit attachment 使用统一文件注册与 clinic_document_attachments 关联，不保存仅存在浏览器内存的文件名。入口在 Checked in、Preparation 和 In consultation 均保持可见；上传后刷新 Registration Queue 或 Patient Documents 仍可读取。状态标签使用内嵌边框 / ring，表格行裁切时不得缺失上下边线；患者资料表单同一区块的输入控件在桌面端使用一致列宽，图标必须解析为明确语义图标而不是通用占位。

从 Preparation 回退 Check-in、或从 Ready 回退 Preparation 都必须填写原因；原因未填写或提交进行中时，确认按钮保持禁用。筛选、Tab 和列表切换不改变 Visit 状态，不应使用不可逆操作的确认样式。

7.9 全局界面状态与响应式要求

本节补充 Patient & eMR、Appointment 与 Registration 场景要求；共享圆角、字号、控件尺寸、颜色、阴影、图标、Tooltip、焦点态和桌面验收规则统一遵循 desktop_ui_design_system.md。

每个页面/弹窗必须定义以下状态，不能只给正常有数据截图：

视觉与响应式基线：

• 1280px 为桌面验收基准；不得无提示截断当前 Tab、关键字段或主操作。
• 数据录入字段与普通表单控件统一使用 36px 语义令牌；搜索、筛选和紧凑工具栏使用 32px；主流程确认操作使用 40px。Input、Select、Date Picker 和 Number Input 使用相同的 Element Plus 外层高度、标签基线、帮助文字位置和 4px 间距节奏；Textarea 只允许内容高度不同，同行顶部、标签和底部间距仍须对齐。
• 正文和关键元数据不低于 12px；9–10px 只用于短标签。
• 蓝色用于主操作/选中；绿色用于完成；橙色用于待处理；红色用于错误/风险。状态不能只靠颜色表达。
• 独立图标按钮必须有可访问名称和可见 tooltip；关键动作使用文字按钮。
• 重复标题、说明 Banner、同一诊所/来源等信息应按上下文去重。

8. API 与后端影响

本轮允许的只读响应扩展

_visit_summary 的 medication_orders 增加：

• ordered_by, reviewed_by
• notes, metadata
• labelled_at, packed_at, dispensed_at, updated_at
• Drug master 的 strength, dosage_form, dispense_unit, pack_unit

保留既有价格字段以避免破坏 Cashier/其他消费者，但 Patient & eMR 不展示它们。

不改表结构

• 所有字段已存在于 clinic_medication_orders、clinic_drug_master、clinic_patient_allergies、clinic_visit_vitals、clinic_document_attachments 等现有表。
• Safety response 不再为缺失 certainty/severity 自动生成临床结论。
• Attachment API 继续不向历史页面暴露未经签名的原始文件路径/URL。

9. 优先级

P0 — 本轮

• 修复 Overview 运行错误和弹窗错误状态残留；全部 Patient Tab 不允许产生 console error。
• 新建患者可选字段保持 Not recorded，不自动写入 ID Card、国家、语言或安全结论。
• 诊断 Primary 只根据真实结构化字段展示，不以第一条自动推断。
• Patient No./MRN、Visit/Chit、日期与来源语义修正。
• Overview 按资料类别和角色权限展示诊所关系、保险／Benefit Programme、过敏源及安全重点信息；基础查询不自动开放其他类别，敏感字段先隐藏，申请查看时提示审计并独立授权，详见 Platform §3。
• Custom Note、Doctor prescription / Pharmacy fulfilment、Metadata-only attachment 正确展示。
• Vital Trends 加入 RR、Height、Visit/source 上下文。
• 共享患者信息表单同步到预约新建患者入口。
• 将保险权威来源、Visit eligibility、Cashier 复核和 Invoice Snapshot 作为 Phase 0 产品契约；生产持久化 / 接口实现状态必须另行标注。
• 将 Financial Completed、24 小时自动 Closed 和独立 AR / Outstanding Payment 作为 Phase 0 目标状态；当前页面或后端路径存在不等于已联调或 UAT。

P1 — 后续

• 任意同集团 Clinic affiliation 新增/停用 API、权限和审计。
• Patient Overview 外部/eHealth 授权与来源展示。
• 跨 Consultation 的 Medication 高级筛选和当前用药摘要。

P2 — 预留

• 结构化 Vaccine registry。
• Communication History canonical source。
• 外部 Lab / Imaging 结果与 eHealth 数据的来源融合。

10. 验收标准

标识与日期

• 给定患者同时存在 virtus_patient_no 和不同 mrn，页面显示 Patient No.，并把 MRN 标为 legacy reference。
• 给定 Visit 只有内部 id，页面显示 Visit #id，不得显示 Chit id。
• 给定 Visit Date 早于 Signed At，时间轴以 Visit Date 排序，Signed At 仅在详情显示。

Patient Overview

• 新建患者必须填写姓名、主手机号和 HKID / passport；缺少任一项不能保存，消息偏好默认 Not recorded。
• Duplicate verification 对证件号完全一致或“规范化姓名 + 主手机号”同时一致给出已有患者阻断；姓名或电话单项命中不误判为重复。
• 新建患者的 Document type/country、language、安全信息和 medical condition 状态不因 UI 默认值被保存为事实。
• 选择患者后 Overview 正常渲染；打开所有 Tab 和弹窗后浏览器控制台无 error。
• 取消或关闭患者表单后，duplicate/save error、保险草稿和安全草稿不残留。
• Clinic affiliations 展示 unit、registration source 和 linked date，不出现 Primary Clinic。
• 保险卡不存在时不从最近 Visit 复制保险摘要到 Overview。
• Overview 直接展示保险和过敏源；保险卡查看生成患者资料审计事件。
• Patient 卡以 card_programme_id 引用 Benefit Contracts 模块的共享 policy_card 目录并保留 programme type、Policy / Benefit Contract 来源及选择时快照，不在患者主档重复编辑 Benefit Rule；失效目录保留历史且新 Encounter 不可选择。
• Reception / Nurse 的真实有效角色上下文按角色维护动作及诊所资格写入，前台仅新增／维护／确认基础字段，护士按获授权字段范围维护；载入保险卡目录不得因权限初始化顺序而产生误导性的整页 Permission denied。
• Check-in 保存 Visit eligibility 的结果、方式、证据、人员和时间；Cashier 对过期 / 变更 / 未确认资格执行最终复核，Invoice 保留规则快照。
• Check-in 缺少姓名、主手机号或 HKID / passport 时不能继续；在 Check-in 补录的值写回 Patient Overview 并可在版本 / 审计记录中追踪。
• 已有患者在 Check-in 未修改身份字段时，即使 Appointment 快照与当前主档存在旧值、组合显示或脱敏差异，也不得触发 duplicate verification 或覆盖 Patient 主档；只有明确编辑的字段或主档空字段才可进入版本化回填。
• 已有患者打开 Check-in 时自动显示当前 Patient & eMR 的姓名、Patient No.、主手机号、HKID / passport 和证件类型；Appointment 快照为空、过期或脱敏时不导致表单空白，也不被误记为人工编辑。
• Check-in 继承 Appointment 已保存的 Self-pay / insurance 状态，主档异步加载后身份与 payer 输入控件仍显示同一值，不要求无意义的重复确认。
• 缺失 allergy certainty/severity 时 UI 不显示自动推断值。

Consultation / Medication

• template_type=custom 的历史 HTML 显示为 Legacy consultation note，脚本、事件属性和外链被清除。
• SOAP 记录按临床字段展示；只有结构化诊断显示 ICD-10 code。
• 缺少 is_primary/role 时不自动把第一条 ICD-10 诊断标为 Primary。
• 医生处方和药房履约分区展示，同一药品可保留两条业务记录。
• Medication 汇总分别显示 prescription 和 pharmacy order 数量，不把两者合并称为 Rx。
• 临床 Medication History 不显示 unit price 或 total amount。

Attachments / Vitals

• metadata_only 且无 OCR 的附件显示 Metadata only，并不可点击。
• 有 OCR 的附件使用统一 Attachment details 弹窗，显示来源 Visit 和上传信息。
• Registration Queue 在 In consultation 状态仍可上传 Visit attachment；保存后刷新页面附件仍存在并可从 Patient Documents 读取。
• Vital Trends 可切换 Respiratory rate，明细表显示 RR、Height、Visit/source。
• Registration 状态标签上下边线完整，Patient 表单同一区块输入宽度一致，电话 / Walk-in / Vitals 图标不显示为错误语义或通用占位。

流程

• Patient & eMR 集团基础查询、诊所修改／确认资格、敏感字段申请查看、公共摘要角色授权和受限正文分别按现行 Platform 分类校验；普通预约不自动开放维护或病历。初始状态、无匹配和接口失败使用不同文案，失败后不存在可继续操作的陈旧选择。
• Appointment 缺少患者、Assigned Provider、日期、有效时间或 Service Type 时不能保存；前端显示明确缺失项，直接调用 API 也被后端拒绝。
• Appointment 患者选择先显示当前诊所结果，再显示获授权的 Medical Group 跨诊所结果；只有用户确认身份并成功保存预约后才建立或恢复诊所关系，取消或保存失败不产生关系。
• 从搜索结果或 duplicate candidate 选择已有患者并保存 Appointment 时，只提交稳定 patient_id 与预约字段，不调用 Patient create/upsert，不显示“已有患者重复”异常；清除患者后旧 patient_id 不得残留。
• Appointment 中已有患者资料为只读，并可跳转 Patient & eMR；预约内不得新增/修改已有患者的身份或保险卡主档，只可选择已保存保险卡并维护本次预约字段。
• 新建或恢复 Patient + Operating Unit 关系时记录 actor、source、reason、before/after 和 request context，重复保存不产生重复 active link。
• 未确认 Appointment 不进入 Registration Queue；确认后可以回退为未确认。
• 新建 Appointment 只能保存为 Booked 或 Confirmed；Arrived、Checked-in、Completed、Cancelled 不能通过普通编辑直接写入。
• 取消 Appointment 必须通过独立确认弹窗填写并记录原因；关闭弹窗不改变状态。
• Reception 新增 Appointment 保存后为 Awaiting check-in，不自动 Check-in。
• Ready for consultation 状态下预约信息只读；回退 Preparation 后才可编辑。
• Registration 的所有回退动作在原因为空或提交中时不可确认，成功后保留原因审计记录。
• Check-in 的 Patient/Payer/Consent 明确显示 Automatic、User confirmed 或 Missing 及来源；未记录 Consent 不自动显示 Confirmed。
• Reception、Consultation、Checkout、Dispensing 和 Tasks 队列的已建档患者姓名可打开同一 Patient & eMR；未建档 Walk-in 不产生模糊跳转。
• 从 Queue 打开的 Patient & eMR 显示对应患者，并可通过返回动作回到原 Queue；点击姓名不触发队列行的主操作。
• 满足临床签署、Checkout、财务安排、即时 Handoff 接收和无阻断异常后，系统在首次临床签署满 24 小时进入 Closed；保险 / 患者未结余额继续存在于 AR，不阻止 Closed。
• Closed 后的 Result、Clinical Correction、Refund、Reversal 或 Remittance Allocation 都以关联事件记录，不恢复或覆盖原 Encounter。

界面与状态

• Patient Directory 不显示未定义权限、范围、重复策略和权威日期语义的通用导入、导出或模板下载控件。
• 1280px 下患者 Tab、Vital 指标、宽表和主操作不发生无提示截断。
• 所有图标按钮有可见 tooltip 与可访问名称；关键动作保留文字。
• Loading、empty、error、permission、read-only、metadata-only 和 version conflict 使用统一状态组件。
• Registration Queue 不常驻展示操作成功或可在弹窗内解决的流程校验 Banner；预期校验关闭弹窗后不残留，真实 API / 加载错误仍可见。
• 管理员角色测试明确显示 functional 或 read-only 模式；只读模拟的写入失败不得被描述为目标角色本身缺少权限。
• Patient 信息维护、Appointment 和 Registration 中的数据录入、紧凑筛选和主确认动作分别采用 36px / 32px / 40px 语义控件令牌；同一表单同行的标签、控件和帮助文字基线一致，样式不污染其他桌面 App。
• PRD 截图与当前目标页面结构一致；界面结构变更时同步更新截图版本。

11. 成功指标

• UAT 字段语义缺陷（Chit/Visit、Date、Prescription/Order、Attachment availability）为 0 个 P0。
• 护士在 Patient Overview 查找患者诊所归属、保险或消息偏好时无需进入第二个患者页面。
• 100% 的迁移 Custom Note 保留可读段落结构且不执行不安全 HTML。
• 100% Metadata-only attachment 不产生失效预览请求。

12. 未决问题

1. [Engineering / Data，阻塞 Phase 0 实现] 按已确认 authority contract 落地患者持卡实例、Visit eligibility 与 Invoice Snapshot 的生产表 / API；技术 Schema 不得改变 Benefit Contracts 为规则权威源的产品决定。
2. [Business / Data Governance，阻塞 P1] 哪些角色可以手工新增或停用同集团 Clinic affiliation，审批和变更原因格式是什么？
3. [Clinical，非阻塞] Custom legacy note 是否需要后续拆分/映射成 SOAP，还是永久只读保留原貌？
4. [Compliance / Product，阻塞 UAT] Registration 的 Privacy、eHealth、AI scribe consent 各自 canonical source、版本、有效期和确认责任是什么？

13. 实现文件索引

• varclip_vue/src/components/desktop/apps/PatientDirectoryWorkspace.vue
• varclip_vue/src/components/desktop/apps/PatientProfileWorkspace.vue
• varclip_vue/src/components/desktop/apps/PatientInformationForm.vue
• varclip_vue/src/components/desktop/apps/PatientDataEditModal.vue
• varclip_vue/src/components/desktop/apps/PatientEmrHistoryWorkspace.vue
• varclip_vue/src/components/desktop/apps/PatientVitalTrendsWorkspace.vue
• varclip_vue/src/utils/vitalTrends.mjs
• varclip_vue/src/views/PatientEmrPreviewPage.vue
• varclip_flask/src/services/clinic_workflow.py

14. PRD 变更与发布治理

1. 任何改变用户可见行为、业务规则、流程 / 状态转换、字段语义、权限、安全控制或验收标准的实现，必须在同一轮工作中更新本 PRD 或其对应的 canonical PRD；PRD 未同步时不得把该项视为完整交付。
2. 纯内部重构、测试输出、构建信息和部署元数据继续记录在技术文档或 change log；只有当它们改变产品契约时才进入 PRD，避免把 PRD 写成代码流水账。
3. PRD 必须区分 已有代码路径、本地验证通过、目标环境已部署 和 UAT 已接受，不得用页面可见或静态预览替代后端联调与验收证据。
4. 本 PRD、配套 backlog 或截图资产变化后，必须重建并发布到既有 Vercel PRD 站点，验证稳定 URL 可访问；PRD 站点发布不代表 AI-CLIP 应用已发布。

2026-09-07 患者自填审核、保障资料与护士修正

用户来源：本轮 Patient & eMR 截图反馈四项要求；本节取代 §7.8.2 中提交后常规 Possible Match／护士再次关联的旧设计。完整业务契约见 frontoffice_business_prd.md §3。

1. 审核容器填满 App 可用宽高，按容器而非浏览器媒体查询响应；审核时收起患者搜索栏与重复待办横幅。列表＋详情在窄窗口改为上下结构，不缩小正文或裁剪主要动作。
2. 重复防范保留在提交前：服务端按令牌限定的 Intake Draft 匹配，经患者明确确认本人后绑定对应 Patient，或者确认新患者；提交携带不透明确认凭据。普通审核只显示结果，不重复比较同一患者。关联不代表获准覆盖主档、创建 Clinic affiliation 或完成就诊身份核验。
3. H5 和审核完整显示共享 Card Programme 名称／类型、保险公司或企业、Plan、个人卡号／Member／Employee No.、Policy／Scheme No.、生效和到期日期。无保障可跳过，选卡后个人编号必填；患者填写不会自动完成 Eligibility。
4. 获授权 Nurse／Reception 可修正自填的身份、联系方式、额外资料及保障。复用 PatientInformationForm 的 self-entry 视图及 PatientInsuranceCardsEditor，不复制第二套主档／卡种表单；患者 Consent 和关联 ID 不可在此直接修改。
5. 每次保存真实修正必须有原因，保留不可覆盖的原始提交和逐次操作者／角色、诊所、时间、字段前后值。批准、拒绝、待澄清亦记录事件，后两者必须有原因。已处理记录仍可在 Reviewed 查看原始信息和历史；编辑未保存关闭须确认丢弃。
6. 姓名／手机／DOB／性别／证件类型或号码发生实质修正后，原确认失效，由护士核实身份并记录依据后才可批准（2026-09-14 用户确认，取代要求病人重填）；格式化空格、括号等变化不重复要求。不会在护士审核页直接改关联或强制新建，服务器最终写入仍须检查匹配、权限、版本及并发。
7. 当前实现为受控前端预览：合成数据和历史保存在页面会话，刷新重置；真实路由不显示合成审核待办。H5 POST /:token/identity-check 目标返回 matched | new-patient | needs-clinic-help，可确认结果带 confirmation_token 和最小脱敏 candidate；提交增加 identity_confirmation: { confirmation_token, patient_confirmed: true }。正式服务端必须校验绑定的 Draft、患者、身份版本、有效期与一次性使用，不能信任客户端状态。端点及跨端持久化／审计／主档写入仍待开发。

2026-09-07 预约付款安排与患者持有计划边界

policy_card 是保险／企业／员工计划共用目录，clinic_patient_insurance_cards 是患者持有实例；Policy 与 Benefit Contract 来源保持各自类型。Appointment／Registration 使用一个 Insurance & Benefit Programme 入口选择已持有计划。本次选择、资格与备注属于预约／Visit，不改变患者默认计划。完整规则见 Frontoffice §4.3。

2026-09-07 用户追加确认：Patient & eMR 的 Insurance card 维护界面亦需对齐。编辑页签、共享编辑器和 Overview 统一为 Insurance & Benefit Programmes，三类计划共用入口、字段按类型显示，Primary 改 Patient default。换计划清旧个人资料、同计划保留；类型与来源不可在读回或维护时降为 insurance。完整契约见 Frontoffice §4.4；公开合成编辑仅页面会话，真实版本审计与 UAT 分别验证。

2026-09-07 人工计划审核边界

患者主档维护保险／企业／员工计划资料，不能将患者默认、卡面有效或主档资格字段视为本次已获保障。Appointment／Check-in 使用人工审核确认按钮，记录计划／变化／有效期核对、资格及预先申请结果；保存后由服务器记录审核人和时间。计划或就诊日期变更需重新审核，主档变化不自动覆盖历史 Visit Snapshot。输入和准备门禁以 Frontoffice §4.4 为准。