From 6e48c4f3722d16e906d89b4bd6e4c05b36b1dce5 Mon Sep 17 00:00:00 2001 From: zlwu <704541015@qq.com> Date: Mon, 17 Aug 2026 12:32:24 +0800 Subject: [PATCH] docs: add QC inspection item template design. Capture the agreed master-data + configure-dialog apply/save-as approach before implementation planning. Co-authored-by: Cursor --- ...8-17-qc-inspection-item-template-design.md | 165 ++++++++++++++++++ 1 file changed, 165 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-17-qc-inspection-item-template-design.md diff --git a/docs/superpowers/specs/2026-08-17-qc-inspection-item-template-design.md b/docs/superpowers/specs/2026-08-17-qc-inspection-item-template-design.md new file mode 100644 index 00000000..2efd45f4 --- /dev/null +++ b/docs/superpowers/specs/2026-08-17-qc-inspection-item-template-design.md @@ -0,0 +1,165 @@ +# 质检检测项目模版 — 设计文档 + +**日期**：2026-08-17 +**状态**：已确认，待实现计划 +**范围**：web-admin「质检工单 / 配置检测」+ 质检基础信息主数据 +**界面模式**：列表页对齐 P01 标准列表（参考 `web-admin/src/views/system/unit/index.vue`） + +## 1. 背景与目标 + +配置检测弹窗按批次勾选实验室自检与第三方检测项目时，用户需在多个批次中重复勾选同一套项目，操作成本高。 + +**目标**：提供租户级可维护的「检测项目模版」主数据；在配置检测时选用模版，自动覆盖当前批次勾选；支持将当前勾选存成新模版。 + +**非目标**： + +- 不改变配置检测确认后的工单/批次/任务落库逻辑 +- 模版不存储负责人、批次名称 +- 「我的质检任务」不提供配置检测入口（现状保持） +- 不与「检测项目参数模板」`biz_qc_item_param` 混用（后者是单项目填报参数，非项目组合） + +## 2. 已确认决策 + +| 项 | 决策 | +|----|------| +| 方案 | 独立列表页（质检基础信息）+ 配置弹窗集成 | +| 模版内容 | 仅实验室项目 ID + 第三方项目 ID | +| 套用范围 | 仅当前正在编辑的批次 | +| 归属 | 租户级共享，按菜单权限维护/使用 | +| 覆盖策略 | 覆盖勾选；当前批次已有勾选时二次确认 | + +## 3. 数据模型 + +表名：`biz_qc_inspection_item_template` + +| 字段 | 类型 | 说明 | +|------|------|------| +| `id` | VARCHAR(64) | 主键 UUID | +| `template_name` | VARCHAR(200) | 模版名称；租户内未删除范围内唯一 | +| `lab_item_ids` | VARCHAR(2000) | 实验室项目 ID，逗号分隔 | +| `third_party_item_ids` | VARCHAR(2000) | 第三方项目 ID，逗号分隔 | +| `status` | CHAR(1) | `1` 启用 / `0` 停用，默认 `1` | +| 公共字段 | | `tenant_no`、`order_num`、`remark`、`create_by`、`create_dept_id`、`create_time`、`update_by`、`update_time`、`del_flag` | + +索引建议： + +- `(tenant_no, del_flag, status)` 供启用列表 +- 名称唯一：业务层校验（租户内 `del_flag=0` 下 `template_name` 唯一）；不做含软删的 DB UNIQUE，避免恢复/重名冲突难处理 + +字段顺序：`id` → 业务字段 → 公共字段。 + +**边界**： + +- 与工单无外键；删除/停用模版不影响已配置工单 +- 写入前校验项目 ID 属于本租户且 `del_flag=0`（停用项目可保留在模版中，套用时再过滤） +- 至少 1 个有效项目 ID（实验室与第三方合计） + +## 4. 菜单、列表页与权限 + +### 4.1 菜单 + +- 位置：质检 → **质检基础信息**，与「质检项目管理」「第三方检测公司」同级 +- 名称：**检测项目模版** +- 路由 path 建议：`inspection-item-template` +- component：`/quality-inspection/inspection-item-template/index` +- 同步：`web-admin` 静态路由 + `docs/sql` 菜单脚本（及待同步清单） + +### 4.2 列表页 + +对齐标准列表模板： + +- 筛选：模版名称、状态 +- 列：模版名称、实验室项目数、第三方项目数、状态（`el-tag`）、创建时间、操作（`fixed="right"`） +- 工具栏：首版不做批量多选；**新增**为行内唯一 `type="primary"` 主按钮 +- 操作：编辑、启用/停用、删除（软删） +- 新增/编辑弹窗：`dialog-form-layout`，`label-position="top"`；勾选实验室 + 第三方项目（交互对齐配置检测左右分栏或等价勾选）；名称必填；至少选 1 项 +- 列表默认不展示 `order_num`（符合工程约定） + +### 4.3 权限 + +| 能力 | perms 建议 | +|------|------------| +| 列表/查看 | `biz:qcInspectionItemTemplate:list` | +| 新增 | `biz:qcInspectionItemTemplate:add` | +| 编辑（含启停） | `biz:qcInspectionItemTemplate:edit` | +| 删除 | `biz:qcInspectionItemTemplate:remove` | + +配置检测弹窗： + +- **选用模版**：需 list 权限；无权限则不展示选用区 +- **存成新模版**：需 add 权限；无权限则隐藏按钮 + +## 5. 配置检测弹窗交互 + +入口：质检工单卡片「配置检测 / 调整检测」→ 现有弹窗内 `QcWorkOrderConfigureBatches`。 + +每个批次 Tab 内（批次名称/负责人下方、已选项目上方）增加模版操作条： + +### 5.1 选用模版 + +1. 下拉加载启用模版（可搜索名称） +2. 选中后若当前批次已有 `labItemIds` 或 `thirdPartyItemIds` → `ElMessageBox.confirm` 确认覆盖 +3. 确认后覆盖当前批次项目 ID，并同步 `hasLab` / `hasThirdParty` +4. 套用时过滤：仅勾选仍启用且未删除的项目；跳过的失效 ID 用 `ElMessage.warning` 提示数量 +5. 若过滤后有效项目数为 0 → **不覆盖**，并警告 +6. 负责人、批次名称不变；其他批次不变 +7. 取消确认则不改勾选，下拉可清空/保持未套用状态 + +### 5.2 存成新模版 + +1. 读取当前批次已勾项目；若为空则提示不可保存 +2. 弹窗输入模版名称（必填） +3. 调用新增 API；名称唯一校验失败则提示 +4. 成功后刷新启用列表；可不强制再套用一遍 + +### 5.3 不变部分 + +- 添加/删除/清空批次 +- 确认提交后的 configure API 与任务生成逻辑 + +## 6. API + +前缀与现有质检管理端一致（如 `/web/admin/...`），租户隔离；查询应用数据权限。 + +| 接口 | 行为 | +|------|------| +| 分页列表 | 名称模糊、状态；默认 `create_time DESC` | +| 启用列表 | `status=1`，返回 id、名称、两组 ID 数组，供下拉 | +| 详情 | 编辑回填 | +| 新增 | 名称唯一；至少 1 个有效项目；校验租户内项目存在 | +| 更新 | 同新增规则；可改 status | +| 删除 | `del_flag=1` | + +`_row_to_dict` 为可读字段单一来源；Create/Update Body 与前端 form 字段与之对齐（见 field-consistency 约定）。 + +## 7. 错误与边界 + +- 空项目、重名、非法/跨租户 ID → 业务错误 +- 模版引用的项目后续停用/删除：模版仍可编辑；套用时跳过并提示 +- 软删模版不出现在启用下拉；列表可按需查历史（已删默认不展示） + +## 8. 验收要点 + +1. 质检基础信息可增删改、启停「检测项目模版」 +2. 配置检测选用模版只覆盖当前批次；有勾选时二次确认 +3. 「存成新模版」写入主数据且可再选用 +4. 无 list 不显示选用；无 add 不显示存成新模版 +5. 套用时停用/已删项目被跳过并提示；全无效则不覆盖 +6. 确认配置后工单任务生成行为与改前一致 + +## 9. 实现落点（参考） + +| 层 | 路径提示 | +|----|----------| +| SQL | `docs/sql/` 建表 + 菜单 + 角色授权脚本；同步 `zkxw.sql` / 待同步清单 | +| 后端 | model / crud / schemas / `app/api/qc.py`（或独立路由模块并注册） | +| 前端主数据页 | `web-admin/src/views/quality-inspection/inspection-item-template/` | +| API 模块 | `web-admin/src/api/qc-inspection-item-template.ts`（命名可微调） | +| 配置弹窗 | `QcWorkOrderConfigureBatches.vue`（及必要时 `index.vue`） | +| 路由 | `web-admin/src/router/modules/sqxp.ts` | + +## 10. 开放细节（实现时可定，不阻塞） + +- 启停：独立接口或并入 update +- 多值字段长度：若项目极多可改为 TEXT；首版 VARCHAR(2000) 足够则保持 +- 列表是否展示项目名称摘要（tooltip）：可选增强，非首版必须