2026-10-09-storage-cert-qc-info-design.md 11 KB
储存证质检信息 — 实现设计（方案 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）。