Files
zkxw/docs/superpowers/specs/2026-05-17-quality-inspection-modules-design.md
T
2026-05-17 23:08:38 +08:00

355 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 质量检测 — 第三方/实验室主数据、质检工单与质检任务
**日期**: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. 核心流程
```mermaid
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 | 初稿:用户确认人工选配、接收触发、工单配置、双类型任务 |