cykj/zkxw
1
0 Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
Files
92c59d67b45a5a3e7fd33e2fb069d387f222023a
zkxw/docs/superpowers/specs/2026-10-09-storage-cert-qc-info-design.md
T
zlwuandCursor 55ed0d8929 docs: add storage-cert QC info design and HTML demo. 
Capture the confirmed sample-level JSON payload approach, field maps from the Excel sheets, and UI entry points for QC fill and market view.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-09 12:22:23 +08:00

11 KiB
Raw Blame History

储存证质检信息 — 实现设计（方案 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）。

Reference in new issue View Git Blame Copy Permalink