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 <cursoragent@cursor.com>
This commit is contained in:
zlwuandCursor committed
1 parent
3a6e2ca128
commit
6e48c4f372
1 file changed
+165
@@ -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）：可选增强，非首版必须
|
||||
Reference in new issue
Block a user