双部门样本接收 — 质检域与生产域拆分

日期：2026-06-29
状态：待审核
关联：2026-05-19-unified-sample-reception-design.md、2026-05-19-production-work-order-design.md、2026-06-03-sample-reception-lab-storage-code-design.md
关联模块：样本接收、入库生产工单、协议/捐赠查看弹窗、质检工单查看

1. 背景与目标

1.1 现状问题

当前 质检管理 → 样本接收 与 生产管理 → 生产工单 → 样本接收信息填写 共用同一张表 biz_sample_reception、同一套 submit/update API，两侧均可修改全部字段（含体积、净重、检查项、接收结论等）。与客户「质检登记」与「生产登记」分属不同部门、字段不同的诉求不符。

1.2 目标

质检域：仅在【质检管理 → 样本接收】填写；去掉 体积(ml)、净重(g)。
生产域：仅在【生产工单 → 样本接收信息填写】填写；字段按 来源 × 样本类型 动态展示。
互读互斥写：质检弹窗可见生产信息（只读）；生产弹窗可见质检信息（只读）。
展示统一：所有展示样本接收信息的查看弹窗/详情，同时展示 质检接收 与 生产接收 两块。
历史数据（已确认）：volume_ml、net_weight_g 仅从界面与读写 API 去掉；库中保留旧值，不再展示、不迁移。

2. 业务规则

2.1 填写入口与权限

入口	可写域	只读域	写权限
质检 → 样本接收（待接收/已接收/批量）	质检接收	生产接收	现网：`采集接受人`（经手人）、`质量主管`（编辑已接收）
生产工单 → 样本接收信息填写	生产接收	质检接收	实验专员（处理人候选与操作角色一致；可复用 `PRODUCTION_STEP_ASSIGNEE_ROLE`）

后端必须在 API 层拒绝跨域写入，不依赖前端 disabled。

2.2 流程依赖

入库生产工单在 质检接收结论 = 接收(js) 后自动创建（现网逻辑不变）。
生产接收填写 入口仅在入库类生产工单卡片展示（inbound_cell_storage / inbound_research_donation）。
质检拒收(bj)：生产弹窗不展示填写能力；只读展示质检结论即可。
填写顺序：须已存在质检接收记录后，生产方可保存生产接收（生产 API 校验 reception_id 存在）。

2.3 样本类型匹配

与 web-admin/src/utils/sample-reception-lab-storage-code.ts 一致，按 样本类型名称 匹配：

名称	说明
`围产期造血干细胞`	对应需求文档编码 `wcqzxgxb`
`脐带间充质干细胞`	对应需求文档编码 `qdjczgxb`

未在矩阵中的类型（如 胎盘亚全能干细胞）：生产弹窗仅展示公共字段（处理人、处理时间），无类型专属字段；专属字段不做必填校验。

2.4 历史字段 `volume_ml` / `net_weight_g`

决策：选项 A — 停止读写与展示；biz_sample_reception 列保留，不执行数据迁移脚本。
_reception_to_dict 及前端类型定义 不再输出 这两字段（或输出但全链路忽略）。
新生产域字段与历史体积/净重 无自动映射。

3. 字段矩阵

3.1 质检域（`biz_sample_reception`，现有表）

字段	变更
reception_time, handler_user_id, handler_name	保留
receive_temperature	保留
check_results（子表）	保留
accept_conclusion, lab_storage_code	保留
receive_attachments, remark	保留
volume_ml, net_weight_g	停止 API 入参/出参及 UI 展示

3.2 生产域（新表 `biz_sample_production_reception`）

公共字段（所有来源×类型）

字段	类型	规则
handler_user_id	varchar(64)	处理人；默认当前登录用户
handler_name	varchar(100)	处理人姓名快照
process_time	datetime	处理时间；默认当前时间

细胞存储 + 围产期造血干细胞

字段	类型	标签
original_blood_weight_g	decimal(18,4)	原血重量/g
hes_volume_ml	decimal(18,4)	HES用量/ml
blood_type	varchar(32)	血型（文本输入，非下拉）
infectious_four_test_result	varchar(16)	传染四项检测(检测卡)：`zc` 正常 / `bzc` 不正常
enriched_blood_weight_g	decimal(18,4)	富集后血量/g
cryopreservation_volume_ml	decimal(18,4)	冻存液用量/ml

细胞存储 + 脐带间充质干细胞

字段	类型	标签
inoculation_amount	decimal(18,4)	接种量
cryopreservation_time	datetime	冻存时间
storage_total_tubes	int	储存总量(管)
available_cell_count_1e7	decimal(18,4)	可提供细胞数量/*10E7

科研捐赠 + 脐带间充质干细胞

字段	类型	标签
inoculation_amount	decimal(18,4)	接种量
cryopreservation_time	datetime	冻存时间

科研捐赠 + 围产期造血干细胞

字段	类型	标签
original_blood_volume_ml	decimal(18,4)	原血体积/ml
nucleated_cell_count_1e8	decimal(18,4)	有核细胞数/10E8

必填规则：对当前样本命中的类型专属字段 + 公共字段做前后端必填校验；未命中类型的专属列保持 NULL。

4. 数据库设计

4.1 新表

-- docs/sql/migrate_sample_production_reception.sql

CREATE TABLE `biz_sample_production_reception` (
  `id` varchar(64) NOT NULL COMMENT '主键ID',
  `reception_id` varchar(64) NOT NULL COMMENT '关联 biz_sample_reception.id',
  `sample_code` varchar(32) DEFAULT NULL COMMENT '样本编码快照',
  `reception_source` varchar(20) NOT NULL DEFAULT 'cell_storage' COMMENT '来源 cell_storage/research_donation',
  `sample_type_name` varchar(100) DEFAULT NULL COMMENT '样本类型名称快照',
  `handler_user_id` varchar(64) DEFAULT NULL COMMENT '处理人用户ID',
  `handler_name` varchar(100) DEFAULT NULL COMMENT '处理人姓名',
  `process_time` datetime NOT NULL COMMENT '处理时间',
  `original_blood_weight_g` decimal(18,4) DEFAULT NULL COMMENT '原血重量/g',
  `hes_volume_ml` decimal(18,4) DEFAULT NULL COMMENT 'HES用量/ml',
  `blood_type` varchar(32) DEFAULT NULL COMMENT '血型',
  `infectious_four_test_result` varchar(16) DEFAULT NULL COMMENT '传染四项 zc正常 bzc不正常',
  `enriched_blood_weight_g` decimal(18,4) DEFAULT NULL COMMENT '富集后血量/g',
  `cryopreservation_volume_ml` decimal(18,4) DEFAULT NULL COMMENT '冻存液用量/ml',
  `inoculation_amount` decimal(18,4) DEFAULT NULL COMMENT '接种量',
  `cryopreservation_time` datetime DEFAULT NULL COMMENT '冻存时间',
  `storage_total_tubes` int DEFAULT NULL COMMENT '储存总量(管)',
  `available_cell_count_1e7` decimal(18,4) DEFAULT NULL COMMENT '可提供细胞数量/*10E7',
  `original_blood_volume_ml` decimal(18,4) DEFAULT NULL COMMENT '原血体积/ml',
  `nucleated_cell_count_1e8` decimal(18,4) DEFAULT NULL COMMENT '有核细胞数/10E8',
  `tenant_no` varchar(64) NOT NULL DEFAULT 'zkxw',
  `order_num` int DEFAULT NULL,
  `remark` varchar(512) DEFAULT NULL,
  `create_by` varchar(64) DEFAULT NULL,
  `create_dept_id` varchar(64) NOT NULL DEFAULT '',
  `create_time` datetime NOT NULL,
  `update_by` varchar(64) DEFAULT NULL,
  `update_time` datetime NOT NULL,
  `del_flag` smallint NOT NULL DEFAULT '0',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_reception_id` (`reception_id`,`del_flag`),
  KEY `idx_sample_code` (`tenant_no`,`sample_code`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='生产部门样本接收登记';

关系：与 biz_sample_reception 1:1（reception_id 唯一）；软删除遵循 del_flag。

4.2 现有表

biz_sample_reception.volume_ml、net_weight_g：不删列；应用层停用。

5. API 设计

5.1 质检 API（调整现有 `/web/admin/sample-receptions`）

POST / PUT：请求体移除 volumeMl、netWeightG。
GET 详情 / 列表 / by-sample-code：响应增加 productionReception（对象或 null）；响应移除 volumeMl、netWeightG。
写接口拒绝任何生产域字段（若误传则忽略或 400）。

5.2 生产 API（新增）

前缀建议：/web/admin/production-sample-receptions

方法	路径	说明
GET	`/by-sample-code?sampleCode=&sourceType=`	返回 `{ receptionId, qcReception, productionReception, sampleInfo }`
GET	`/{id}`	生产接收详情
POST	`/`	创建（body 含 `receptionId` 或 `sampleCode`+`sourceType`）
PUT	`/{id}`	更新生产域字段

校验：关联质检记录存在；accept_conclusion !== 'bj'；当前用户具备实验专员角色或等于处理人（编辑策略与质检对称，首版：实验专员可写）。
写接口禁止修改 biz_sample_reception 任意字段。

5.3 聚合读

以下详情接口的 reception 或等价字段扩展为：

{
  "qcReception": { "...质检字段..." },
  "productionReception": { "...生产字段..." }
}

或保持扁平 reception 为质检数据，另增 productionReception。实现时 _row_to_dict 为单一真相源。

影响面：生产工单详情、质检工单入库查看、协议/捐赠样本卡片接口（若内嵌 sampleReception）。

6. 前端设计

6.1 可写表单

组件	改造
`quality-inspection/sample-reception/index.vue`	去掉体积/净重；表单下增加生产接收信息（只读）区块；拉取聚合详情
`production-work-order/SampleReceptionDialog.vue`	重写：上为质检只读，下为生产可编辑（按类型字段模板）；不再调用质检 submit/update
`production/sample-reception-completion/index.vue`	废弃或改为跳转生产工单；菜单保持隐藏

6.2 公共只读组件（新建）

建议：web-admin/src/components/business/sample-reception-dual-readonly-panel/

Props：qcReception、productionReception、sourceType、sampleTypeName
内置 4 套类型字段展示模板 + 空态（「生产尚未登记」/「暂未接收」）
供协议查看、捐赠查看、工单查看、质检任务查看等复用

6.3 只读展示改造清单

文件	改造
`ProtocolViewDialog.vue`	样本卡片拆「质检接收」「生产接收」
`DonationViewDialog.vue`	同上
`production-view-sections.ts`	拆两段 section
`inbound-view-sections.ts`	同上
`QcTaskViewDialog`	同上
`QcWorkOrderTaskSubList`	同上
`StorageReleaseViewDialog`	同上
质检样本接收「接收详情」弹窗	增加生产只读块

6.4 生产处理人下拉

复用 fetchProductionStepAssigneeUsers（角色 实验专员）；打开弹窗时默认选中当前登录用户（若在列表中）。

6.5 UI 规范

弹窗：dialog-form-layout、label-position="top"、只读块用 readonly-grid / data-grid 与现网样本接收弹窗一致。
质检块标题：质检接收信息；生产块：生产接收信息。
传染四项：el-select，选项「正常」「不正常」。

7. 后端模块

路径	职责
`backend/app/models/models.py`	`BizSampleProductionReception`
`backend/app/crud/sample_production_reception.py`	CRUD、类型校验、`_row_to_dict`
`backend/app/api/sample_production_reception.py`	路由
`backend/app/crud/sample_reception.py`	去掉 volume/netWeight 出参；详情挂载 production
`backend/app/api/__init__.py` + `main.py`	注册新路由

字段一致性：运行 python scripts/check_field_consistency.py（若纳入检查范围）。

8. 权限与菜单

新增按钮权限（建议）：production:sample-reception:add、production:sample-reception:edit，挂在生产工单或生产管理菜单下。
质检权限不变：biz:sampleReception:*。

9. 测试要点

质检接收(js) → 生产工单出现 → 生产填写 4 种类型组合字段 → 质检页只读可见。
质检编辑后 → 生产页只读更新；生产编辑后 → 质检页只读更新；双方 API 互不能改对方域。
质检拒收 → 生产无填写入口。
历史记录：volume_ml/net_weight_g 有值的旧数据，界面与 API 均不出现。
未覆盖样本类型：仅公共字段可保存。
实验专员/非实验专员写权限边界。

10. 实施顺序

SQL + Model + 生产 CRUD/API
质检 API 瘦身 + 聚合读
SampleReceptionDialog 重写 + 质检页调整
sample-reception-dual-readonly-panel + 各查看弹窗接入
权限 SQL + 回归

11. 不在本次范围

隐藏菜单「样本接收信息完善」路由删除（可后续清理）。
小程序端样本接收（若有）不同步，除非另行立项。
volume_ml/net_weight_g 列的数据库物理删除。

12. 已确认决策

议题	决策
历史体积/净重	A — 库保留，界面与 API 去掉，不展示不迁移
数据模型	新表 `biz_sample_production_reception`，1:1 关联质检接收
未覆盖样本类型	仅公共字段，无专属必填

2026-06-29-dual-sample-reception-design.md 13 KB パーマリンク 履歴 Raw