Files
zkxw/docs/superpowers/specs/2026-06-25-qc-work-order-protocol-group-design.md
T
2026-06-26 00:50:04 +08:00

262 lines
11 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.
# 入库质检工单 · 协议单多样本 Tab 分组 — 设计文档
> 日期:2026-06-25
> 状态:已实现
> 范围:`web-admin` 【质检工单】【我的质检任务】入库类 Tab;后端列表关键词补协议号
> 关联:`2026-06-16-qc-work-order-tab-split-design.md`、`2026-06-25-qc-work-order-all-tab-design.md`、`2026-06-25-qc-inspection-batch-design.md`
---
## 1. 背景与目标
### 1.1 问题
细胞存储质检、科研捐赠质检的工单均来自**采集协议单 / 科赠协议单**。一份协议单可含**多个样本**,每个样本接收后各生成至少一条质检工单(生产过程可再追加)。
现网列表按 **`sampleCode`(样本编码)** 分组:同一协议下的多个样本各自占一张卡片,协议号等信息在组头副标题重复出现,用户难以「按协议一眼看全样本质检进度」。
### 1.2 目标
在 **细胞存储质检**、**科研捐赠质检** 两个 Tab 中,将同一协议单下的多个样本**合并为一张协议组卡片**,组内用 **Tab 切换样本**;样本内仍保留现网 **触发来源 Tab**(样本接收 / 生产过程)。
【质检工单】与【我的质检任务】**共用**同一套列表组件与分组逻辑。
### 1.3 非目标
- 不改变出库、临时 Tab 的列表布局。
- 不在 **「所有」** Tab 做协议分组(沿用平铺 + 类型 Tag,见 `2026-06-25-qc-work-order-all-tab-design.md` §1.3)。
- 不合并细胞存储与科研捐赠(仍分 Tab)。
- 不把同协议多样本压成**单层扁平卡片**(去掉样本层级)。
- 本期不做「按协议分页」后端改造(分页仍按工单条数;见 §5.3 边界说明)。
---
## 2. 列表信息架构
### 2.1 三层结构
```
协议组(新增外层)
└── 样本 Tab(新增中层)
└── 触发来源 Tab(现网 QcWorkOrderSampleGroup 内层)
└── 工单卡片 + 检测批次 + 任务
```
### 2.2 分组键
| 层级 | 分组字段 | 回退 |
|------|----------|------|
| 协议 | `collectionProtocolId` | `(protocolNo).trim()`,仍空则用首条工单 `id` |
| 样本 | `sampleCode` | 工单 `id` |
| 工单 | 同样本下按 `triggerSource` Tab 切换 | 现网逻辑 |
说明:科赠工单的 `collectionProtocolId` 存的是 `research_donation_id`(后端建单已如此),与细胞存储共用分组字段名。
### 2.3 Tab 配置
`listLayout` **保持** `inbound-grouped`(语义扩展为「入库分组列表」,实现改为协议优先分组,不再在 `QcWorkOrderCardList` 顶层直接使用 `QcWorkOrderSampleGroup`)。
受影响 Tab:
| Tab Key | 展示标签 | 列表布局(实现) |
|---------|----------|------------------|
| `inbound_cell_storage` | 细胞存储质检 | 协议分组 + 样本 Tab |
| `inbound_research_donation` | 科研捐赠质检 | 协议分组 + 样本 Tab |
---
## 3. UI 设计
### 3.1 协议组头(`qc-protocol-row__ctx`)
视觉对齐现网 `qc-sample-row__ctx`(绿渐变顶栏 + 序号)。
| 元素 | 细胞存储 | 科研捐赠 |
|------|----------|----------|
| 主标题 | 协议号 `protocolNo` | 捐赠单号 `protocolNo` |
| 副标题 | 协议状态 Tag + `N 个样本` + 可选进度摘要 | 捐赠状态 Tag + `N 个样本` + 可选进度摘要 |
| Badge | 组内工单总数(如 `5 条质检`) | 同左 |
**进度摘要(可选展示):** 如 `2/3 已配置`,按样本维度统计:该样本下存在 `workOrderStatus !== 'dpz'` 的 gate 工单(优先 `triggerSource=reception`,否则取组内首条)即计为「已配置样本」。无数据时不展示。
**协议费用条:** 仅 **细胞存储** Tab、且组内存在 `paymentSummary` 的工单时,在协议组头下方展示 **一次** `QcWorkOrderProtocolPaymentPanel`(compact),**不要**在每个样本 Tab 内重复。
### 3.2 样本 Tab 行(`qc-protocol-sample-tabs`)
- 样式复用现网 `qc-wo-indep-tabs__btn` / pill Tab(与 `QcWorkOrderSampleGroup` 触发来源 Tab 一致)。
- **仅当组内样本数 ≥ 2** 时展示 Tab 行;**单样本**时隐藏 Tab 行,直接展示该样本工单区。
每个 Tab pill 文案:
| 部分 | 内容 |
|------|------|
| 序号 | `1` `2` `3`(圆点序号,与现网一致) |
| 主文案 | 样本编码(monospace) |
| 辅助 | 样本类型 `sampleTypeName`(有值时) |
| 状态 | 该样本 gate 工单 `workOrderStatus` 的 `el-tag` |
Tab 排序:按样本编码字典序;同编码按 gate 工单 `createTime` ASC。
### 3.3 样本工单区
选中样本后渲染 **`QcWorkOrderSampleGroup`**,传入该样本下的 `workOrders` 子集,并增加 prop:
| Prop | 值 | 说明 |
|------|-----|------|
| `hideContextBar` | `true` | 隐藏原样本组头(协议组头 + 样本 Tab 已表达上下文) |
| 其余 | 与现网一致 | 内层触发来源 Tab、卡片、批次、任务 |
单样本且仅 1 条工单时:无样本 Tab、无触发来源 Tab,直接展示 `QcWorkOrderSingleCard`。
### 3.4 线框(ASCII)
```
┌─ 1 XY2026001 [协议进行中] 3 个样本 · 2/3 已配置 [5 条质检] ─┐
│ [协议费用 compact — 仅细胞存储] │
├─ 样本 Tab ───────────────────────────────────────────────────────┤
│ [1 A001·脐带血·待配置] [2 A002·胎盘·已配置] [3 B003·进行中] │
├─ 触发来源 Tab(样本 A001 有 2 条工单时)───────────────────────────┤
│ [样本接收 ZJ…] [生产过程 ZJ…] │
├─ 工单 meta + 检测批次 + 任务 ─────────────────────────────────────┤
└───────────────────────────────────────────────────────────────────┘
```
---
## 4. 前端实现要点
### 4.1 新增工具(`web-admin/src/utils/qc-work-order-groups.ts`)
```typescript
export type QcWorkOrderProtocolGroupModel = {
groupKey: string
protocolId: string
protocolNo: string
receptionSource: 'cell_storage' | 'research_donation'
sampleGroups: QcWorkOrderSampleGroupModel[]
workOrders: QcWorkOrder[] // 组内全部工单(扁平)
}
export function groupInboundQcWorkOrdersByProtocol(
rows: QcWorkOrder[]
): QcWorkOrderProtocolGroupModel[]
```
实现步骤:
1. 按 `collectionProtocolId`(及回退键)聚合工单。
2. 每组内调用现有 `groupInboundQcWorkOrders` 得到 `sampleGroups`。
3. 协议组排序:组内最新工单 `createTime DESC`(与列表默认排序一致)。
### 4.2 新增组件
**`QcWorkOrderProtocolGroup.vue`**
- Props / Emits 与 `QcWorkOrderSampleGroup` 对齐(`configure` / `view` / `command` / `tasks-changed`)。
- 内含样本 Tab 状态 `activeSampleKey`(`sampleCode` 或回退 `id`)。
- 渲染选中样本的 `QcWorkOrderSampleGroup`(`hideContextBar=true`)。
### 4.3 修改组件
| 文件 | 变更 |
|------|------|
| `QcWorkOrderSampleGroup.vue` | 新增 `hideContextBar?: boolean`,为 true 时不渲染 `qc-sample-row__ctx` |
| `QcWorkOrderCardList.vue` | `cardMetaUsesInboundGroups` 时渲染 `QcWorkOrderProtocolGroup` 而非直接 `QcWorkOrderSampleGroup` |
| `qc-work-order-card-meta.ts` | 新增 `buildProtocolGroupContextSubtitle(group)`;细胞存储/捐赠分别用协议/捐赠文案 |
### 4.4 「所有」Tab
**不变。** `buildAllTabListItems` 中 inbound 仍可按样本合并(或维持现状);本需求不修改 `all` Tab 布局。
### 4.5 我的质检任务
与 manage 共用 `QcWorkOrderCardList` + 协议分组;`pageMode='mine'` 时卡片仅查看、任务区 `taskListMode='mine'`。
前端 mine 关键词过滤补充 `protocolNo` 字段(`qc-mine-task-groups.ts` → `keywordMatchesWorkOrder`,inbound 组)。
---
## 5. 后端变更
### 5.1 列表关键词 — 协议号(必须)
`list_work_orders` 在现有关键词 OR 条件中增加:
```python
BizQcWorkOrder.protocol_no.like(like)
```
适用于入库类及「所有」Tab 跨类型搜索。
### 5.2 筛选 placeholder
入库 Tab 关键词 placeholder 更新为:
`工单号/协议号/样本编码/入库编码`
(细胞存储写「协议号」,科研捐赠写「捐赠单号」——按 Tab 文案区分。)
### 5.3 分页边界
- 分页单位仍为 **工单条数**(`pageSize` 默认 100)。
- 同一协议多样本可能**跨页**:当前页仅展示本页工单所属的样本 Tab;未出现在本页的样本不出 Tab。**可接受**,二期可选「按协议 ID 拉全量样本工单再分组」(非本期)。
---
## 6. 与检测批次的关系
检测批次在 **工单卡片内部**(`QcWorkOrderBatchSubList`),与协议/样本分组**正交**:
```
协议 → 样本 Tab → 触发来源 Tab → 工单 → 批次 → 任务
```
本需求不修改批次配置 API 与 UI。
---
## 7. 验收标准
1. 【质检工单】细胞存储 / 科研捐赠 Tab:同一 `collectionProtocolId` 下多样本合并为 **一张协议组卡片**。
2. 协议组内 **样本 Tab** 可切换;切换后展示对应样本工单与任务。
3. 同样本多工单(接收 + 生产)仍显示 **触发来源 Tab**,行为与改动前一致。
4. 单样本协议组 **不显示** 样本 Tab 行,直接展示工单区。
5. 细胞存储协议组 **协议费用条** 组级展示一次;科研捐赠不展示费用条。
6. 【我的质检任务】同上,且仅查看 + 任务操作。
7. 关键词输入协议号 / 捐赠单号可筛出该协议下全部相关工单。
8. 「所有」Tab、出库 Tab、临时 Tab 列表行为 **回归不变**。
9. 配置检测 / 调整检测 / 查看弹窗 **回归不变**。
---
## 8. 已确认决策
| 问题 | 决策 |
|------|------|
| 是否按协议合并多样本? | **是** |
| 样本切换交互? | **Tab(pill)**,复用现网触发来源 Tab 样式 |
| 单样本是否仍显示 Tab? | **否**,隐藏样本 Tab 行 |
| 两页是否一致? | **是** |
| 「所有」Tab 是否协议分组? | **否** |
| 分页是否改为按协议? | **否**(本期) |
| 协议费用条位置? | **协议组头一次**(仅细胞存储) |
---
## 9. 实现阶段建议
| 阶段 | 内容 | 预估 |
|------|------|------|
| P1 | `groupInboundQcWorkOrdersByProtocol` + `QcWorkOrderProtocolGroup` + SampleGroup `hideContextBar` | 1~1.5 人天 |
| P2 | CardList 接入 + card-meta 协议组头 + placeholder | 0.5 人天 |
| P3 | 后端 `protocol_no` 关键词 + mine 前端关键词 | 0.5 人天 |
| P4 | 两页联调、回归六 Tab + 所有 Tab | 0.5~1 人天 |
| **合计** | | **2.5~3.5 人天** |
---
## 10. 下一步
1. 评审本文档 — 无遗漏后进入实现计划(`writing-plans` → `docs/superpowers/plans/`)。
2. 可选:同步 OpenSpec capability `qc-work-order-protocol-group`(与 `ui-conventions` 卡片分组约定对齐)。