质量检测 — 第三方/实验室主数据、质检工单与质检任务

日期：2026-05-17
依据：用户确认的业务规则；docs/中科兴皖需求V0.3.md 签收后触发样本检测流程；既有 biz_sample_reception、样本接收 Web 页。
范围：web-admin + backend（FastAPI）；租户隔离、软删除、公共字段与工程规范一致。

1. 已确认业务规则

项	规则
样本类型	不考虑；主数据维护全部检测项目，由人员自选
样本接收 UI	保持现状，不在接收弹窗勾选检测项目
触发时机	接收结论为接收（`js`）时，自动生成 1 条质检工单（与 `biz_sample_reception` 1:1）；拒收（`bj`）不建单
项目配置	在质检工单界面配置：检测方式（实验室自检 / 第三方检测，可多选）及具体项目
任务生成	实验室 + 第三方所选项目各生成 1 条质检任务；处理逻辑按任务类型区分
任务差异	实验室自检：本实验室处理（一期仅状态/骨架）；第三方：需上传第三方检测材料
样本类型映射	不做

2. 目标与非目标

2.1 目标（一期）

在「质量检测」下新增 5 个菜单（见 §4）。
主数据 CRUD：第三方检测公司、第三方检测项目及费用（归属公司）、实验室自检项目。
接收成功 → 自动创建 待配置 质检工单。
质检工单：列表、查看、配置检测（勾选方式与项目）→ 确认后批量生成任务，工单变为 已配置。
质检任务：列表、查看；实验室任务最小状态流转；第三方任务支持附件上传并完结。
后端在 create_sample_reception 提交事务内（或同事务）创建工单，保证幂等（同一 reception_id 仅一条工单）。

2.2 非目标（一期不做）

检测任务完整实验过程录入、仪器对接、审批流。
检测结论回写协议样本状态（sample_status / 作废 / 入库）— 留二期。
按样本类型自动匹配项目。
在接收弹窗配置检测项目。
工作流引擎驱动质检。

3. 方案对比（已选方案 A）

方案	说明	结论
A. 工单头 + 明细行 + 任务表	工单存头信息；配置时写入工单明细（快照）；确认后按明细生成 `biz_qc_task`	采用 — 便于待配置态展示、费用汇总、审计快照
B. 仅工单 + 任务	配置直接写任务，无中间明细	待配置编辑与历史追溯弱
C. JSON 存配置	配置存 JSON 字段	不利于列表筛选与报表

4. 菜单与路由

一级菜单 质量检测（/quality-inspection，已有）下新增：

序号	菜单名称	path	组件	权限前缀（建议）
1	第三方检测公司	`third-party-company`	`views/quality-inspection/third-party-company/index.vue`	`biz:qcThirdPartyCompany`
2	第三方检测项目	`third-party-item`	`views/quality-inspection/third-party-item/index.vue`	`biz:qcThirdPartyItem`
3	实验室自检项目	`lab-test-item`	`views/quality-inspection/lab-test-item/index.vue`	`biz:qcLabTestItem`
4	质检工单	`qc-work-order`	`views/quality-inspection/qc-work-order/index.vue`	`biz:qcWorkOrder`
5	质检任务	`qc-task`	`views/quality-inspection/qc-task/index.vue`	`biz:qcTask`

保留现有：样本接收、接收检查项配置。

同步：web-admin/src/router/modules/sqxp.ts、backend/app/api/menu.py、docs/sql/sys_menu_quality_inspection.sql（或增量 SQL）。

UI：列表对齐 system/unit/index.vue；弹窗 label-position="top"、.dialog-form-layout；色板 Fresh Mint。

5. 数据模型

命名空间表前缀：biz_qc_*。均含标准公共字段（id UUID、tenant_no、order_num、remark、create_by、create_dept_id、create_time、update_by、update_time、del_flag）。

5.1 `biz_qc_third_party_company` — 第三方检测公司

字段	类型	说明
company_code	VARCHAR(64)	公司编码，租户内唯一
company_name	VARCHAR(200)	公司名称
contact_name	VARCHAR(100)	联系人
contact_phone	VARCHAR(32)	联系电话
address	VARCHAR(500)	地址
status	CHAR(1)	`1` 启用 / `0` 停用

5.2 `biz_qc_third_party_item` — 第三方检测项目及费用

字段	类型	说明
company_id	VARCHAR(64)	FK → 第三方公司
item_code	VARCHAR(64)	项目编码（租户内可与 company 联合唯一）
item_name	VARCHAR(200)	项目名称
fee_amount	DECIMAL(18,2)	费用（元）
status	CHAR(1)	`1` 启用 / `0` 停用

列表页支持按公司筛选；新增/编辑必须选择所属公司。

5.3 `biz_qc_lab_test_item` — 实验室自检项目

字段	类型	说明
item_code	VARCHAR(64)	项目编码，租户内唯一
item_name	VARCHAR(200)	项目名称
description	VARCHAR(500)	描述/方法说明（可选）
status	CHAR(1)	`1` 启用 / `0` 停用

5.4 `biz_qc_work_order` — 质检工单

字段	类型	说明
work_order_no	VARCHAR(32)	工单号（规则：`ZJ` + yyyyMMdd + 4 位序，租户内按日序）
reception_id	VARCHAR(64)	接收记录 ID，唯一（未删除）
protocol_sample_id	VARCHAR(64)	协议样本 ID
collection_protocol_id	VARCHAR(64)	协议单 ID
protocol_no	VARCHAR(64)	协议号快照（列表展示）
sample_code	VARCHAR(32)	样本编码快照
work_order_status	VARCHAR(16)	见 §6.1
has_lab	CHAR(1)	`1`/`0` 是否含实验室自检
has_third_party	CHAR(1)	`1`/`0` 是否含第三方检测
configured_time	DATETIME	配置确认时间
configured_by	VARCHAR(64)	配置人用户 ID
third_party_fee_total	DECIMAL(18,2)	第三方项目费用合计（配置时汇总）

5.5 `biz_qc_work_order_lab_item` — 工单-实验室项目明细（配置快照）

字段	类型	说明
work_order_id	VARCHAR(64)	工单 ID
lab_test_item_id	VARCHAR(64)	主数据 ID
item_code / item_name	VARCHAR	快照

5.6 `biz_qc_work_order_third_item` — 工单-第三方项目明细（配置快照）

字段	类型	说明
work_order_id	VARCHAR(64)	工单 ID
third_party_item_id	VARCHAR(64)	主数据 ID
company_id	VARCHAR(64)	公司 ID
company_name	VARCHAR(200)	公司名快照
item_code / item_name	VARCHAR	快照
fee_amount	DECIMAL(18,2)	费用快照

5.7 `biz_qc_task` — 质检任务

字段	类型	说明
work_order_id	VARCHAR(64)	工单 ID
task_no	VARCHAR(32)	任务号（`RW` + 日序，或工单号 + `-` + 序号）
task_type	VARCHAR(16)	`sysz` 实验室自检 / `dsfjc` 第三方检测
source_line_id	VARCHAR(64)	对应工单明细行 ID（lab 或 third 明细表）
item_code / item_name	VARCHAR	快照
company_id / company_name	VARCHAR	第三方任务填公司快照；实验室为空
fee_amount	DECIMAL(18,2)	第三方费用快照
task_status	VARCHAR(16)	见 §6.2
third_party_attachments	VARCHAR(4000)	第三方检测材料 URL，逗号分隔（MinIO）
completed_time	DATETIME	完成时间
completed_by	VARCHAR(64)	完成人

6. 状态与字典

6.1 工单状态 `work_order_status`

值	标签	说明
`dpz`	待配置	接收后自动创建
`ypz`	已配置	已确认检测方式与项目，任务已生成
`ywc`	已完成	全部任务已完成（可由任务聚合更新，一期可实现自动推进）

6.2 任务状态 `task_status`

值	标签	说明
`dzx`	待执行	刚生成
`jxz`	进行中	实验室：开始处理；第三方：已上传部分材料可选
`ywc`	已完成	实验室：手动完成；第三方：上传材料后确认完成

6.3 字典类型（可选 `sys_dict`）

qc_task_type：sysz / dsfjc
qc_work_order_status：dpz / ypz / ywc
qc_task_status：dzx / jxz / ywc

一期也可前端常量 + 标签函数（与样本接收结论一致）。

7. 核心流程

sequenceDiagram
  participant SR as 样本接收
  participant WO as 质检工单
  participant TK as 质检任务

  SR->>WO: 结论=接收(js) 提交
  Note over WO: 创建工单 status=dpz
  WO->>WO: 质检专员打开「配置检测」
  Note over WO: 勾选 has_lab / has_third_party<br/>多选启用项目
  WO->>WO: POST 确认配置
  WO->>WO: 写入明细快照 status=ypz
  loop 每个实验室项目
    WO->>TK: 创建 task_type=sysz
  end
  loop 每个第三方项目
    WO->>TK: 创建 task_type=dsfjc
  end
  TK->>TK: 实验室：状态流转(一期骨架)
  TK->>TK: 第三方：上传材料 → 完成
  TK->>WO: 全部 ywc 时工单→ywc

7.1 自动建单（后端）

在 create_sample_reception 中，当 accept_conclusion == 'js' 且提交成功后：

若该 reception_id 尚无未删除工单，则插入 biz_qc_work_order（dpz）。
填充 reception_id、protocol_sample_id、collection_protocol_id；从协议单/样本补 protocol_no、sample_code。
生成 work_order_no。
同一事务 commit。

幂等：已存在工单则跳过（防重复接收场景应在前置校验拦截，此处防御性检查）。

7.2 配置检测（工单）

仅 work_order_status = dpz 可配置。
请求体示例：
- hasLab: boolean
- hasThirdParty: boolean
- labItemIds: string[]（hasLab 时至少 1 项）
- thirdPartyItemIds: string[]（hasThirdParty 时至少 1 项）
校验：所选 ID 均为本租户启用主数据；第三方项目带公司信息写入快照。
行为：
1. 删除该工单下已有明细（dpz 态理论上无任务，若有则拒绝）。
2. 批量插入 lab/third 明细行。
3. 按明细 每条生成 1 个任务（dzx）。
4. 更新工单：ypz、has_lab、has_third_party、third_party_fee_total、configured_*。
已配置后一期不允许修改项目（避免任务与明细不一致）；追加以二期为准。

7.3 任务处理（一期）

类型	操作
`sysz`	列表查看；支持「开始」「完成」状态变更（无结果表单）
`dsfjc`	上传第三方检测材料（附件卡片，MinIO）；「完成」前至少 1 个附件

工单完成：该工单下所有任务 ywc → 工单 ywc（可在任务完成 API 内聚合更新）。

8. API 设计（前缀 `/api/web/admin`）

8.1 第三方检测公司

GET /qc-third-party-companies — 分页列表，keyword、status
GET /qc-third-party-companies/options — 下拉（启用）
POST /qc-third-party-companies
PUT /qc-third-party-companies/{id}
DELETE /qc-third-party-companies/{id} — 软删；若存在未删第三方项目则拒绝

8.2 第三方检测项目

GET /qc-third-party-items — companyId、keyword、status
GET /qc-third-party-items/options — companyId 可选
POST / PUT / DELETE — 标准 CRUD

8.3 实验室自检项目

GET /qc-lab-test-items — 分页
GET /qc-lab-test-items/options — 启用项，供工单配置多选
POST / PUT / DELETE

8.4 质检工单

GET /qc-work-orders — keyword（工单号/协议号/样本编码）、workOrderStatus
GET /qc-work-orders/{id} — 含接收摘要、明细、任务列表
POST /qc-work-orders/{id}/configure — §7.2 配置确认

（不提供手工新建：仅接收触发。）

8.5 质检任务

GET /qc-tasks — keyword、taskType、taskStatus、workOrderId
GET /qc-tasks/{id}
POST /qc-tasks/{id}/start — sysz：dzx→jxz
POST /qc-tasks/{id}/complete — sysz：jxz→ywc；dsfjc：校验附件后 ywc
PUT /qc-tasks/{id}/attachments — dsfjc 更新 third_party_attachments

路由注册：app/api/qc_*.py 或合并 quality_inspection.py；__init__.py + main.py。

权限：require_menu_code + apply_data_scope（与 sample_reception 一致）。

9. 前端要点

9.1 第三方检测公司 / 项目 / 实验室项目

标准列表 CRUD；项目列表带公司筛选，表单公司用 el-select（options 接口）。
停用主数据后，工单配置下拉不出现，不影响已生成工单快照与任务。

9.2 质检工单

列表列：工单号、协议号、样本编码、接收时间、工单状态、检测方式（实验室/第三方标签）、配置时间。
操作：查看、配置检测（仅 dpz）。
配置弹窗：
- 区块1：检测方式 el-checkbox-group（实验室自检、第三方检测）
- 区块2：实验室项目 el-checkbox-group 或表格多选（仅启用项）
- 区块3：第三方项目 — 可按公司分组展示全部启用项目 + 费用列，多选
- 确认前校验：勾选方式与所选项目一致；至少选 1 个项目
查看弹窗：只读展示接收信息、已选明细、关联任务列表。

9.3 质检任务

列表：taskType 筛选；类型列区分标签。
操作：
- 实验室：开始 / 完成
- 第三方：上传材料（附件卡片）、完成
查看：展示工单关联、项目快照、附件只读。

10. 实施分期建议

阶段	交付
P1	SQL + Models + 主数据 3 模块 API/页面
P2	接收触发改单 + 工单列表/配置/查看 + 配置生成任务
P3	任务列表 + 分类型操作 + 工单完成聚合
P4（二期）	检测结果、样本状态联动、配置后追加项目、统计报表

实施计划文件：docs/superpowers/plans/2026-05-17-quality-inspection-modules.md（待 writing-plans 生成）。

11. 测试要点

接收 js → 生成 dpz 工单；bj → 无工单。
同一接收重复提交应被接收层拦截，不重复工单。
配置仅选实验室 → 仅 sysz 任务；仅第三方 → 仅 dsfjc 任务；两者都选 → 两类任务总数 = 所选项目数。
第三方任务无附件不可完成；全部任务完成后工单 ywc。
租户隔离、软删除、停用主数据不参与新配置。

12. 变更记录

日期	说明
2026-05-17	初稿：用户确认人工选配、接收触发、工单配置、双类型任务

2026-05-17-quality-inspection-modules-design.md 15 KB Historie Surový