提交

2026-08-31 15:18:18 +08:00
1 parent 04d462ad43
commit 7e9155fef1
@@ -0,0 +1,160 @@
+# 质检任务第三方按公司聚合卡片 — 设计
+
+> 日期：2026-08-28  
+> 状态：已实现  
+> 完成日期：2026-08-28  
+> 范围：`web-admin` 质检工单、我的质检任务（批次内任务列表）  
+> 方案：A（前端聚合 + 循环调用现有单任务保存接口）  
+> 交互原型：`.superpowers/brainstorm/80309-1787910046/content/001-qc-company-card-demo.html`  
+> 实现计划：`docs/superpowers/plans/2026-08-28-qc-third-party-company-card.md`
+
+## 1. 背景与目标
+
+现状：检测批次下每个质检项目一张任务卡。第三方公司项目多时，列表卡片过多。
+
+目标：
+
+- **实验室自检**：不合并，仍一项目一卡，交互保持现状。
+- **第三方检测**：同一质检批次下，同一公司的全部（可见）项目聚合成 **一张公司卡**；点击打开弹窗，在弹窗内按项目填写。
+- **分项填写**：检测参数、任务状态、结论按单个项目填写。
+- **共享填写**：备注、检测材料只填一份，并按规则同步到本次保存的可写任务集合。
+
+## 2. 已确认决策
+
+| 决策点 | 结论 |
+|--------|------|
+| 自检是否合并 | 否，保持单项目卡 |
+| 第三方聚合维度 | 同工单、同批次、同 `companyId` |
+| 实现路径 | 方案 A：前端聚合 + 复用 `POST /qc-tasks/{id}/complete-with-result` |
+| 共享字段落库 | 仍写在各任务的 `remark` / `third_party_attachments`（冗余同步，不改表） |
+| 质检工单页保存范围 | 该批次该公司下全部第三方任务 |
+| 我的质检任务页 | 弹窗只展示、只保存当前用户负责的任务；备注/材料也只写这些任务 |
+| 任务状态 / 结论 UI | 沿用现网单选：状态「待执行 / 已完成」；结论「待结论 / 通过 / 不通过」；选已完成时禁用待结论且结论必填 |
+| 本期不做 | 改配置检测 UI、新建批次-公司实体、公司卡批量删除、附件导出目录重构 |
+
+## 3. 列表展示
+
+### 3.1 层级
+
+工单 → 检测批次 Tab → 任务区（`QcWorkOrderBatchSubList` → 任务子列表）。
+
+任务区内混合两类卡片：
+
+1. **自检卡**（`taskType = sysz`）：现有紧凑卡，不改行为。
+2. **公司卡**（由 `taskType = dsfjc` 按 `companyId` 聚合）：新增样式与交互。
+
+排序：先自检卡（保持原任务顺序），再公司卡（按公司名或首次出现顺序稳定排序）；公司卡内项目顺序与配置/原任务顺序一致。
+
+### 3.2 公司卡字段
+
+| 元素 | 规则 |
+|------|------|
+| 主标题 | `companyName` |
+| 副文案 | `第三方 · N 个检测项目`（N = 该卡可见任务数） |
+| 进度 Tag | `已完成数/总数`；全完成 success，部分 warning，全未完成 info |
+| 类型 Tag | `第三方检测` |
+| 负责人 | 可见任务 assignee 去重后拼接 |
+| 主按钮 | 有可填权限 →「填写结果」；否则「查看」 |
+| 点击/双击 | 与主按钮一致，打开公司弹窗 |
+
+第三方现网不需要「开始」；公司卡不提供开始。
+
+### 3.3 我的质检任务聚合
+
+- 仅用当前用户作为负责人的第三方任务参与聚合。
+- 某公司下自己负责 0 项 → 不展示该公司卡。
+
+### 3.4 异常数据
+
+- `companyId` 为空的第三方任务：不并入其它公司卡，各自降级为单项目卡（或单独「未归属公司」卡，实现时二选一，**推荐降级为单项目卡**），避免误聚合。
+
+### 3.5 删除
+
+本期公司卡不提供「删除整公司」。单任务删除仍走现有入口（或配置「调整检测」）；公司弹窗内不做删除，控制范围。
+
+## 4. 公司弹窗
+
+### 4.1 结构（自上而下）
+
+1. 标题：`填写检测结果 · {公司名}` / `查看检测结果 · {公司名}`
+2. **检测项目**（可写/可见集合内每个任务一块）  
+   - 项目名 + 状态 Tag  
+   - **检测参数**：按项目参数模板，三列栅格（文本 / 数字 / 下拉，与现网单任务弹窗一致）  
+   - **检测结论**：现网单选组（任务状态、结论）
+3. **备注与检测材料**（整弹窗一份）  
+   - 备注 textarea  
+   - 检测材料上传组件（与现网第三方附件一致）  
+   - 若可写集合中 **任一项** 任务状态为「已完成」，则检测材料必填
+
+只读模式：全部控件禁用，无保存按钮（或仅关闭）。
+
+### 4.2 打开回显
+
+- 各项目：各自 `results`、任务状态、结论。
+- 共享备注 / 材料：在本次弹窗任务集合中，取 **最近 `updateTime` 且对应字段非空** 的值；皆空则空白。
+
+### 4.3 保存
+
+对可写集合中每个任务依次调用现有：
+
+`POST /qc-tasks/{id}/complete-with-result`
+
+Body 要点：
+
+- 分项：`results`、`taskStatus`、`conclusion`
+- 共享：同一份 `remark`、`thirdPartyAttachments`
+- 校验：逐项校验状态/结论规则（已完成必须结论；与现网一致）
+- 材料：存在任一「已完成」时，共享材料必填（整单校验一次）
+
+失败策略：逐任务提交；失败时提示失败项及原因，已成功项保留。不做跨任务 DB 事务（方案 A 取舍，写入 spec 明示）。
+
+保存成功后刷新批次任务列表 / 触发 `tasks-changed`。
+
+## 5. 前端改动面（实现指引）
+
+主要落点（实现计划阶段再拆任务）：
+
+| 区域 | 改动 |
+|------|------|
+| `QcWorkOrderTaskSubList.vue`（或抽出 composable/子组件） | 将 `tableData` 拆成自检列表 + 按公司分组；渲染公司卡；公司弹窗 |
+| 新建组件（建议） | 如 `QcCompanyTaskResultDialog.vue`：多项目参数 + 共享备注/材料 |
+| 聚合工具 | 如 `groupThirdPartyTasksByCompany(tasks)` |
+| API | 不新增后端接口；复用任务详情、参数、`complete-with-result` |
+| 质检工单 / 我的质检任务 | 共用上述子列表，靠 `listMode` 区分可写集合 |
+
+查看弹窗、工单系统查看里「第三方项目」只读展示：可后续对齐公司分组，**非本期必做**（列表填写路径优先）。
+
+## 6. 后端与数据
+
+- **不改表结构**。`biz_qc_task` 仍一项目一任务；`company_id` / `company_name` 已有。
+- 备注、附件继续按任务冗余存储；同次保存写入相同值。
+- 工单完成判定、附件导出等现有逻辑不变（依赖任务级字段）。
+
+## 7. 风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| 多次请求部分失败 | 明确提示；支持再次打开补救；后续可升级方案 B 批量 API |
+| 历史同公司任务备注/附件不一致 | 打开时按「最近非空」回显；保存后统一为本次共享值 |
+| 我的任务子集与工单全量语义不同 | UI 与保存范围按 `listMode` 分支；文档与验收分开写 |
+| 公司弹窗项目多、参数多导致过长 | `dialog-form-layout` 仅 body 滚动；项目块可考虑默认展开全部（首版不做折叠，除非验收反馈） |
+
+## 8. 验收场景（摘要）
+
+1. 同批次配置 2 个自检 + 公司 A 3 项 + 公司 B 1 项 → 列表为 2 张自检卡 + 2 张公司卡。  
+2. 打开公司 A 弹窗，可见 3 个项目块；多参数项目三列展示；状态/结论为单选。  
+3. 填写共享备注与材料并保存 → 工单页下该公司该批 3 个任务备注与附件一致。  
+4. 我的质检任务：用户仅负责公司 A 的 2/3 项 → 公司卡显示 2 项；保存只更新这 2 项。  
+5. 任一项选「已完成」且无材料 → 保存被拦截。  
+6. 自检卡「开始 / 填写结果」行为与改造前一致。  
+7. 全完成公司卡进度为 success，主按钮可为查看（视权限）。
+
+## 9. 工作量粗估
+
+约 5～8 人天（前端聚合 + 公司弹窗为主；回归两页多 Tab；无后端 DDL）。
+
+## 10. 非目标
+
+- 移动端 / H5 同步改造  
+- OpenSpec 工程规范变更归档（若需可另开 change）  
+- 方案 C（共享实体表）