355 lines
15 KiB
Markdown
355 lines
15 KiB
Markdown
# 质量检测 — 第三方/实验室主数据、质检工单与质检任务
|
||
|
||
**日期**: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 | 初稿:用户确认人工选配、接收触发、工单配置、双类型任务 |
|