diff --git a/docs/demos/2026-10-09-storage-cert-qc-info-demo.html b/docs/demos/2026-10-09-storage-cert-qc-info-demo.html new file mode 100644 index 00000000..abffec99 --- /dev/null +++ b/docs/demos/2026-10-09-storage-cert-qc-info-demo.html @@ -0,0 +1,855 @@ + + + + + + 储存证质检信息 · 填写 / 查看 Demo + + + + + + +
+
+

储存证质检信息 · Demo

+

+ 质检在「细胞存储质检」工单卡片上填写储存证质检信息（字段对齐 Excel 两个 sheet）； + 市场在「样本信息管理 · 细胞存储」上查看同一份数据，用于誊写到储存证。 +

+
+ Excel：围产期造血干细胞 + Excel：脐带间充质干细胞 + 质检工单 / 我的质检任务 + 样本信息管理 +
+
+ +
+
+
+

业务链路（示意）

+

当前 Demo 不改业务逻辑，只对齐交互与字段分组

+
+
+
+ 质检完成检测 + → + 填写储存证质检信息 + → + 市场「样本信息」查看 + → + 誊写 / 办理储存证 +
+
+ +
+ + + + + +
+ + +
+
+ 两个 sheet 共用「身份键 + 母亲血检」骨架，检测报告区字段按样本类型分叉；右侧收尾字段也略有差异。 +
+
+
+

围产期造血干细胞（约 34 列）

+
    +
  • 身份：序号、实验室流转编码、协议编码、母亲姓名
    • +
  • 采集运输：采集时间、运输温度
    • +
  • 造血干细胞检测报告：接收/处理/冻存时间、重量、冻存体积、TNC、CD34+、CD34+CD45dim、活性、细菌、HBsAg/HCV/TP/HIV、CMV-IgM
    • +
  • 母亲血液检测报告：HBsAg、HBV DNA、抗HCV、HCV RNA、抗TP、CMV IgM、抗HIV、HIV-1RNA
    • +
  • 收尾：HLA 分型、储存日期、储存年限、检测结果评论、报告发出日期
    • +
+
+
+

脐带间充质干细胞（约 34 列）

+
    +
  • 额外：是否邮寄
    • +
  • 身份：序号、实验室流转编码、协议编码、母亲姓名
    • +
  • 采集运输：脐带采集时间、运输温度
    • +
  • 脐带间充质检测报告：接收/处理/冻存时间、储存总量(管)、可提供细胞类型/数量/存活率、内毒素/细菌/真菌/支原体、形态、免疫表型
    • +
  • 母亲血液检测报告：与造血 sheet 同一组 8 项
    • +
  • 收尾：检测结果评判、报告发出日期、储存日期(P2)、冷冻方式、储存温度、储存年限
    • +
+
+
+
+
+
+

Demo 建议排除出「质检填写」的列

+

这些更像列表管理列 / 市场侧信息，可在澄清时确认

+
+
+

+ 建议默认只读预填、不让质检手填：序号、协议编码、母亲姓名（从样本/协议带出）。 + 「是否邮寄」偏市场物流，是否纳入质检表待确认。 + 「实验室流转编码」是否等于系统样本编码 / 入库编码，待确认。 +

+
+
+ + +
+
+
+
+

质检工单 / 我的质检任务 · 细胞存储质检

+

在工单卡片操作区新增「填写储存证质检信息」（示意高亮）

+
+
+
入口放在工单卡片（非任务子卡「填写结果」），因为储存证信息是样本级整表，不是单项检测任务结果。
+ +
+ 协议：ZKZX34000852 + 客户：高居巧 + 来源：细胞存储 +
+
+ B0000002 · 围产期造血干细胞 + B0000002-MSC · 脐带间充质（示意） +
+
+
+
+
入库质检工单 WO-2026-1008-012
+
+ 已完成 + 结论：通过 +
+
+
样本类型 → 决定弹窗字段模板
+
+
+ + + + +
+
+ +
+
+
+
+
入库质检工单 WO-2026-1009-003
+
+ 进行中 +
+
+
+
+ + +
+
+
+
+ + +
+
+
+
+

填写弹窗 · 围产期造血干细胞

+

分组 = Excel 合并表头；三列栅格；长文本（HLA / 评论）跨列

+
+ +
+

+ 字段按 Excel sheet「围产期造血干细胞」展开：造血检测报告 15 项 + 母亲血检 8 项 + HLA/储存/评论/报告日。 +

+
+
+ + +
+
+
+
+

填写弹窗 · 脐带间充质干细胞

+

与造血模板共用母亲血检区块；检测报告与收尾字段不同

+
+ +
+

+ 含「是否邮寄」、储存总量(管)、可提供细胞*、内毒素/真菌/支原体、冷冻方式、储存温度等。 +

+
+
+ + +
+
+
+
+

样本信息管理 · 细胞存储 Tab

+

行操作增加「查看储存证的质检信息」；无数据时按钮可禁用或提示未填写

+
+
+
+ 已选 0 项 + + + +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
样本编码协议编码母亲姓名样本类型质检储存证操作
B0000002ZKZX34000852高居巧围产期造血干细胞已完成未办理 +
+ + +
+
BC0000003ZKQD34000831牛晨晨脐带间充质干细胞已完成已办理 +
+ + +
+
B0000099ZKZX34000999示例未填围产期造血干细胞进行中— +
+ + +
+
+
+
+
+
+ + +
+ +
+ + +
+ +
+ + + + diff --git a/docs/superpowers/specs/2026-10-09-storage-cert-qc-info-design.md b/docs/superpowers/specs/2026-10-09-storage-cert-qc-info-design.md new file mode 100644 index 00000000..766a5b0e --- /dev/null +++ b/docs/superpowers/specs/2026-10-09-storage-cert-qc-info-design.md @@ -0,0 +1,284 @@ +# 储存证质检信息 — 实现设计（方案 A） + +> 日期：2026-10-09 +> 状态：已确认（2026-10-09） +> 关联：质检工单 / 我的质检任务「细胞存储质检」；样本信息管理「细胞存储」；Excel《干细胞储存证数据》 +> Demo：`docs/demos/2026-10-09-storage-cert-qc-info-demo.html` + +--- + +## 1. 背景 + +市场办理储存证时，质检数据目前来自 Excel 手工表（两个 sheet）： + +| Sheet | 样本类型 | +|-------|----------| +| 围产期造血干细胞 | 围产期造血干细胞 | +| 脐带间充质干细胞 | 脐带间充质干细胞 | + +流程为：质检部门填表 → 市场部门誊写到储存证。系统内已有入库质检工单与样本信息管理，但**没有**与储存证誊写对齐的结构化质检信息落库与查看入口。 + +现有 `biz_protocol_storage_cert` 为**协议级**办理状态（办理时间、附件等），不承载上述检测明细。 + +--- + +## 2. 目标与非目标 + +### 2.1 目标 + +- 质检在「质检工单」「我的质检任务」的「细胞存储质检」**工单卡片**上，可「填写储存证质检信息」（按整份样本一张表）。 +- 字段分组与 Excel 对应 sheet 业务列一致；按样本类型切换两套模板。 +- 市场在「样本信息管理 · 细胞存储」行操作可「查看储存证的质检信息」（只读）；未填时提示「质检尚未填写」。 +- 数据按**样本级**持久化，可反复编辑覆盖；允许部分填写即保存。 + +### 2.2 非目标 + +- 不自动生成 / 打印储存证 PDF。 +- 不改「登记储存证」办理流，不扩展 `biz_protocol_storage_cert` 明细列。 +- 不从接收单 / 质检任务结果自动回填检测数值（本期全部手填）。 +- 不做 Excel 批量导入。 +- 不为其它样本类型（如胎盘亚全能）做模板；其它类型不显示填写/查看按钮。 +- 不做必填校验、不做乐观锁。 + +--- + +## 3. 已确认产品决策 + +| 决策点 | 结论 | +|--------|------| +| 填写入口 | 工单卡片（与查看 / 配置检测同级），非整条子任务「填写结果」 | +| 粒度 | 整份样本一张表 | +| 查看可用性 | 始终可点；未填弹窗提示「质检尚未填写」 | +| 样本类型范围 | 仅围产期造血干细胞、脐带间充质干细胞 | +| 再次编辑 | 可反复打开保存，覆盖上次 | +| 数值来源 | 全部手填；系统只带出身份信息 | +| 校验 | 允许部分填写即保存（草稿式） | +| 存储方案 | 方案 A：样本级新表 + JSON `payload` | + +--- + +## 4. 数据模型 + +### 4.1 表 `biz_sample_storage_cert_qc` + +| 字段 | 类型（示意） | 说明 | +|------|--------------|------| +| `id` | VARCHAR(64) | UUID PK | +| `sample_code` | VARCHAR(64) | 样本编码；跨表关联键之一 | +| `collection_protocol_id` | VARCHAR(64) | 冗余协议 id，便于权限/展示；**非**唯一键 | +| `qc_work_order_id` | VARCHAR(64) NULL | 可选，最近一次从哪张工单填写 | +| `sample_type_key` | VARCHAR(32) | 模板键：`perinatal_hsc` / `uc_msc` | +| `payload` | JSON / TEXT | 业务字段对象（见 §5） | +| `filled_flag` | CHAR(1) | `0`/`1`；任意一次成功保存后为 `1` | +| 公共字段 | | `tenant_no` … `del_flag`（对齐 database-conventions） | + +**唯一性**：`tenant_no + sample_code` 在 `del_flag=0` 下唯一；写入走 upsert。 + +**关联键**：读写与列表关联一律用 `tenant_no + sample_code`（对齐细胞存储样本跨表约定），不用 `collection_protocol_id` 作唯一匹配。 + +### 4.2 模板键映射 + +与现网名称常量对齐（`SAMPLE_TYPE_PERINATAL_HSC` / `SAMPLE_TYPE_UC_MSC`）： + +| 样本类型名称 | `sample_type_key` | +|--------------|-------------------| +| 围产期造血干细胞 | `perinatal_hsc` | +| 脐带间充质干细胞 | `uc_msc` | + +服务端根据样本当前类型解析 `sample_type_key`，**不信任**客户端随意改模板。非以上类型 → 拒绝写入。 + +### 4.3 身份信息（不进 payload） + +弹窗顶部只读展示（从协议 / 样本主数据带出）： + +- 实验室流转编码：本期约定展示 **`sample_code`**（与系统样本编码一致） +- 协议编码 +- 母亲姓名 +- 样本类型名称 + +排除 Excel「序号」列（列表管理用，不入库）。 + +--- + +## 5. Payload 字段（对齐 Excel） + +键名用稳定英文 snake_case；界面 label 用中文（与 Excel 表头一致）。值为字符串或数字均可，空字段可省略或存 `null`/`""`。阴阳性常见值：`阴` / `阳` / `/`。 + +### 5.1 `perinatal_hsc`（围产期造血干细胞） + +**采集与运输** + +| key | 中文 | +|-----|------| +| `collection_time` | 造血干细胞采集时间 | +| `transport_temp_c` | 运输温度 /℃ | + +**造血干细胞检测报告** + +| key | 中文 | +|-----|------| +| `receive_time` | 造血干细胞接收时间 | +| `process_time` | 处理时间 | +| `cryo_time` | 冻存时间 | +| `weight_g` | 造血干细胞重量/g | +| `cryo_volume_ml` | 造血干细胞冻存体积/mL | +| `tnc_1e8` | 有核细胞数 TNC / *10E8 | +| `cd34_count_1e6` | CD34+ 细胞计数 / *10E6 | +| `cd34_cd45dim_1e5` | CD34+ CD45dim 细胞计数 / *10E5 | +| `viability_pct` | 细胞活性/% | +| `bacteria_test` | 细菌检测 | +| `hbsag` | 乙型肝炎病毒表面抗原(HBsAg) | +| `anti_hcv` | 丙型肝炎病毒抗体(抗HCV) | +| `anti_tp` | 梅毒螺旋体特异性抗体(抗TP) | +| `anti_hiv` | 人类免疫缺陷病毒抗体(抗HIV-1/2) | +| `cmv_igm` | 巨细胞病毒 IgM 抗体 (CMV-IgM) | + +**母亲血液检测报告** + +| key | 中文 | +|-----|------| +| `mother_hbsag` | 乙型肝炎病毒表面抗原(HBsAg) | +| `mother_hbv_dna` | 乙型肝炎病毒核酸(HBV DNA) | +| `mother_anti_hcv` | 丙型肝炎病毒抗体(抗HCV) | +| `mother_hcv_rna` | 丙型肝炎病毒核酸(HCV RNA) | +| `mother_anti_tp` | 梅毒螺旋体特异性抗体(抗TP) | +| `mother_cmv_igm` | 巨细胞病毒 IgM 抗体 (CMV IgM) | +| `mother_anti_hiv` | 人类免疫缺陷病毒抗体(抗HIV-1/2) | +| `mother_hiv1_rna` | 人类免疫缺陷病毒核酸(1型) (HIV-1RNA) | + +**储存证收尾** + +| key | 中文 | +|-----|------| +| `hla_typing` | HLA 分型 | +| `storage_date` | 储存日期 | +| `storage_years` | 储存年限 | +| `result_comment` | 检测结果评论 | +| `report_issue_date` | 报告发出日期 | + +### 5.2 `uc_msc`（脐带间充质干细胞） + +**采集与运输 / 邮寄** + +| key | 中文 | +|-----|------| +| `mail_flag` | 是否邮寄 | +| `collection_time` | 脐带采集时间 | +| `transport_temp_c` | 运输温度 /℃ | + +**脐带间充质干细胞检测报告** + +| key | 中文 | +|-----|------| +| `receive_time` | 脐带接收时间 | +| `process_time` | 处理时间 | +| `cryo_time` | 冻存时间 | +| `storage_tube_count` | 储存总量（管） | +| `available_cell_type` | 可提供细胞类型 | +| `available_cell_count_1e7` | 可提供细胞数量 / *10E7 | +| `available_viability_pct` | 可提供细胞存活率 % | +| `endotoxin_test` | 内毒素检测 | +| `bacteria_test` | 细菌检测 | +| `fungus_test` | 真菌检测 | +| `mycoplasma_test` | 支原体检测 | +| `available_cell_morphology` | 可提供细胞形态 | +| `available_immunophenotype` | 可提供细胞免疫表型特征 | + +**母亲血液检测报告**：与 §5.1 母亲血检 8 个 key 相同。 + +**储存证收尾** + +| key | 中文 | +|-----|------| +| `result_judgment` | 检测结果评判 | +| `report_issue_date` | 报告发出日期 | +| `storage_date_p2` | 储存日期 (P2冻存日期) | +| `freeze_method` | 冷冻方式 | +| `storage_temp` | 储存温度 | +| `storage_years` | 储存年限 | + +--- + +## 6. API + +建议前缀：`/web/admin/sample-storage-cert-qc`。 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/{sample_code}` | 读详情：身份只读字段 + `sampleTypeKey` + `filledFlag` + `payload` | +| PUT | `/{sample_code}` | Upsert；body：`payload`（object），可选 `qcWorkOrderId` | + +### 6.1 行为 + +- GET 无行：HTTP 200，`filledFlag=false`，`payload={}`（或 null），**不** 404。 +- PUT：校验样本存在、租户、数据权限、类型为两种之一；写 `sample_type_key`；`filled_flag=1`；覆盖 `payload`。 +- 列表接口本期不扩展整份 payload；样本信息列表点「查看」再 GET。 + +### 6.2 权限 + +- PUT：具备质检工单或我的质检任务相关菜单权限（与工单卡片操作对齐；不额外强制「必须是任务执行人」，除非现有卡片按钮已有更严规则则跟随）。 +- GET：样本信息管理菜单可访问；质检填写弹窗预填亦用同一 GET。 + +--- + +## 7. 前端 + +### 7.1 质检入口 + +- 页面：`qc-work-order`、`my-qc-task`，Tab「细胞存储质检」（`inbound_cell_storage`）。 +- 组件：`QcWorkOrderSingleCard` 操作区增加「填写储存证质检信息」。 +- 显示条件：当前样本类型名为围产期造血干细胞或脐带间充质干细胞。 +- 弹窗：可编辑；GET 预填 → PUT 保存；manage / mine 均显示（规则相同）。 + +### 7.2 样本信息入口 + +- 页面：`/#/market/cell-storage/sample-info`，「细胞存储」Tab。 +- 行操作增加「查看储存证的质检信息」；显示条件同两种类型。 +- 始终可点；`filledFlag=false` 时弹窗空态文案「质检尚未填写」（可保留身份区）；已填则只读同模板字段。 +- 市场侧不可编辑。 + +### 7.3 UI 约定 + +- `label-position="top"`；分组对齐 Demo / Excel 合并表头；栅格最多约 3 列，窄屏降列。 +- 一套字段元数据配置驱动填写（可编）与查看（只读）。 +- 对齐 Fresh Mint / `dialog-form-layout`；遮罩无 backdrop blur。 +- Demo：`docs/demos/2026-10-09-storage-cert-qc-info-demo.html`。 + +### 7.4 样本类型变更（边界） + +极少见。打开表单按**当前**样本类型选模板；保存时按当前模板**整包覆盖** `payload`（实现简单，可接受）。 + +--- + +## 8. 错误处理摘要 + +| 场景 | 行为 | +|------|------| +| 不支持类型 PUT | 400；前端不展示按钮 | +| 样本不存在 / 无权限 | 统一 403/404 | +| GET 无记录 | 200 + 未填形态 | +| payload 非 object | 400 | +| 并发保存 | 后写覆盖 | + +--- + +## 9. 测试要点 + +- 后端：upsert 覆盖、租户隔离、`filled_flag`、类型门禁、GET 空记录。 +- 前端：两类型按钮显隐；质检保存后市场只读可见；未填空态；manage/mine 均有入口。 + +--- + +## 10. 实现落点（指引，非任务清单） + +| 层 | 预期触点 | +|----|----------| +| SQL | `docs/sql/migrations/2026-10-09-sample-storage-cert-qc.sql` | +| Model / CRUD / API | `backend/app/models`、`crud`、`api`（新模块或挂入 qc / sample 相关路由并注册） | +| FE API | `web-admin/src/api/` | +| 字段元数据 | `web-admin/src/utils/` 或业务组件内配置 | +| 填写/查看弹窗 | 共用业务组件 | +| 工单卡片 | `QcWorkOrderSingleCard.vue` | +| 样本信息 | `UnifiedSampleInfoPage.vue`（细胞存储操作列） | + +详细步骤在实现计划中展开（writing-plans）。