cykj/zkxw
1
0 Fork 0
Code Issues 5 Pull Requests Packages Projects Releases Wiki Activity
Files
56cee052d4094547264894e9d2dff070fa8482fd
zkxw/docs/superpowers/specs/2026-05-17-quality-inspection-modules-design.md
T
zlwu 2a4767a014 提交
2026-05-17 23:08:38 +08:00

15 KiB
Raw Blame History

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

日期：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' 且提交成功后：

  1. 若该 reception_id 尚无未删除工单，则插入 biz_qc_work_order（dpz）。
  2. 填充 reception_id、protocol_sample_id、collection_protocol_id；从协议单/样本补 protocol_no、sample_code。
  3. 生成 work_order_no。
  4. 同一事务 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 初稿：用户确认人工选配、接收触发、工单配置、双类型任务
Reference in new issue View Git Blame Copy Permalink