docs: add production task set design spec and implementation plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-18 16:16:57 +08:00
1 parent 4c45e52296
commit 0707a4c95e
@@ -0,0 +1,260 @@
+# 生产任务集合 — 设计文档
+
+> 日期：2026-08-18  
+> 状态：已确认，待实现计划  
+> 范围：【生产基础信息】任务集合主数据；【生产工单】派发任务弹窗、存为集合  
+> 不改：【我的生产任务】派发入口（本来就没有）；单条派发后的三栏编辑工艺 / 步骤派发 / 完成工单
+
+---
+
+## 1. 背景与目标
+
+### 1.1 问题
+
+同类型生产工单每次派发的任务内容往往相同（任务名称、工艺路线、描述、备注）。当前「派发任务」每次只生成 **1** 条生产任务，用户需反复打开弹窗填写，效率低。
+
+### 1.2 目标
+
+1. 引入可维护、可复用的 **生产任务集合**：一条集合 = 多条「派发信息」（与现有派发表单字段一致）。
+2. 「派发任务」弹窗支持 **按集合一次生成多条** 生产任务（集合 4 条 → 生成 4 条任务）。
+3. 保留现有 **单条** 派发（选工艺路线等）流程不变。
+4. 支持把当前生产工单已派发的任务 **存为** 一套新集合。
+
+### 1.3 已确认产品决策
+
+| 项 | 决策 |
+|----|------|
+| 形态 | 独立主数据「生产任务集合」，非绑死某一工单 Tab |
+| 条目内容 | 与派发表单一致：任务名称、工艺路线（可选）、描述、备注 |
+| 不存 | 工艺步骤快照、负责人、步骤派发信息 |
+| 派发后 | 集合派发：生成后关闭弹窗并刷新任务列表；不进入三栏编辑 |
+| 单条派发 | 仍：生成 1 条 → 进入编辑工艺（现状） |
+| 存为集合 | 仅【生产工单】管理页；有任务即可（含已完成工单） |
+| 路线语义 | 派发时按当时路线克隆步骤；工单上事后改过的步骤不进集合 |
+
+---
+
+## 2. 概念关系
+
+```
+工艺路线（步骤集合）     生产任务集合（派发信息集合）
+        │                         │
+        │ 可选引用                  │ 有序多条
+        ▼                         ▼
+生产任务 ←── 单条派发 / 按集合批量派发 ── 生产工单
+```
+
+- **工艺路线**：一条任务内部的步骤模板。
+- **任务集合**：多条「待生成生产任务」的派发参数模板。
+- 派发时：对集合每一条目调用与现有单条创建相同的建任务逻辑（含可选路线克隆），同一事务。
+
+---
+
+## 3. 数据模型
+
+### 3.1 `biz_production_task_set`（集合）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | VARCHAR(64) | 主键 UUID |
+| `set_name` | VARCHAR(200) NOT NULL | 集合名称；租户内未删除记录唯一 |
+| `status` | CHAR(1) NOT NULL DEFAULT '1' | `1` 启用 / `0` 停用 |
+| 公共字段 | | `tenant_no`、`order_num`、`remark`、`create_by`、`create_dept_id`、`create_time`、`update_by`、`update_time`、`del_flag` |
+
+字段顺序：`id` → 业务字段 → 公共字段。软删。列表默认不展示 `order_num`。
+
+### 3.2 `biz_production_task_set_item`（条目）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | VARCHAR(64) | 主键 UUID |
+| `set_id` | VARCHAR(64) NOT NULL | 所属集合 |
+| `task_name` | VARCHAR(200) NOT NULL | 任务名称 |
+| `route_id` | VARCHAR(64) NULL | 工艺路线 ID，可选 |
+| `route_name` | VARCHAR(100) NULL | 路线名称快照（展示用） |
+| `description` | VARCHAR(500) NULL | 描述 |
+| `remark` | VARCHAR(512) NULL | 备注 |
+| 公共字段 | | 同上；条目顺序用 `order_num` |
+
+约束：
+
+- 保存集合时至少一条有效条目（`task_name` 非空）。
+- `route_id` 若有值，须指向本租户未删除的工艺路线；写入时同步 `route_name` 快照。
+- 更新集合时：**整表替换**条目（先软删旧条目再插入新条目，或等价事务内重建）。
+
+### 3.3 SQL
+
+- 新建：`docs/sql/` 下建表脚本（及菜单授权脚本，见 §7）。
+- 不改现有生产任务 / 工艺路线表结构。
+
+---
+
+## 4. 后端 API
+
+前缀与鉴权对齐现有 production 管理端：`/web/admin/...`，`require_admin_or_super_admin`，租户隔离。
+
+### 4.1 集合 CRUD
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/production-task-sets` | 分页列表；keyword、status；返回含 `itemCount` |
+| GET | `/production-task-sets/active` | 启用集合简表（派发下拉：id、setName、itemCount） |
+| GET | `/production-task-sets/{id}` | 详情 + 按 `order_num` 排序的条目（含路线展示名） |
+| POST | `/production-task-sets` | 新增（body：setName、status、remark、items[]） |
+| PUT | `/production-task-sets/{id}` | 更新（整表替换 items） |
+| DELETE | `/production-task-sets/{id}` | 软删集合及条目 |
+
+`items[]` 元素：`taskName`、`routeId?`、`description?`、`remark?`（顺序即数组序，服务端写 `order_num`）。
+
+### 4.2 从工单生成集合
+
+`POST /production-task-sets/from-work-order`
+
+Body：`workOrderId`、`setName`、`remark?`
+
+规则：
+
+1. 工单须存在且属当前租户。
+2. 读取该工单下未删除生产任务，按 `create_time ASC`、`id ASC` 稳定排序。
+3. 每条任务映射为一条目：`taskName`、`routeId`、`routeName`（若有路线则解析名称）、`description`、`remark`。
+4. **`task_name` 为空的任务跳过**；若跳过后无任何条目 → `400`，提示无可保存任务。
+5. 集合 `status` 默认启用。
+6. `set_name` 冲突 → `400`。
+
+成功响应带 `skippedEmptyNameCount`（无跳过则为 0），便于前端提示。
+
+### 4.3 按集合批量创建任务
+
+`POST /production-tasks/from-set`
+
+Body：`workOrderId`、`setId`
+
+规则：
+
+1. 工单状态须为 `dpz` 或 `jxz`（与现有可派发条件一致）。
+2. 集合须存在、未删、`status=1`，且至少一条条目。
+3. 对每条条目：若 `route_id` 非空但路线不存在/已删 → **整单回滚**，错误信息列出缺失路线。
+4. 按 `order_num` 顺序，对每条调用与现有 `create_production_task` 相同逻辑（`task_name`、`route_id`、`description`、`remark`，以及由工单推导的 `task_type` / `order_source`）；有路线则克隆步骤与路线默认设备。
+5. 同一事务；成功后同步工单状态（复用现有 `sync_production_work_order_status_from_tasks`）。
+6. 响应：新建任务列表摘要（id、taskName、taskNo）或至少 `createdCount`。
+
+**不改** `POST /production-tasks` 单条创建行为。
+
+---
+
+## 5. 前端
+
+### 5.1 维护页（P01）
+
+- 路径建议：`/#/production-group/production-base/production-task-set`
+- 源码：`web-admin/src/views/production/production-task-set/index.vue`
+- 参考：`quality-inspection/inspection-item-template/index.vue`
+- 面板标题：`生产任务集合列表`（须写入 `App.vue` `panelTitleBarTextRules`）
+
+列表：集合名称、任务条数、状态 Tag、备注、创建时间；操作查看 / 编辑 / 删除。
+
+筛选：关键词、状态。工具栏：新增集合（唯一 primary）。
+
+新增/编辑弹窗：
+
+- `label-position="top"`，`dialog-form-layout`，约 720～900px（条目子表需宽）
+- 集合名称、状态、备注
+- 全宽条目表：任务名称、工艺路线（远程检索，同 `DispatchTaskDialog`）、描述、备注；增行 / 删行 / 上移下移；至少一行
+- 底栏：取消 Close / 确定 Check
+
+查看：只读展示同上字段。
+
+### 5.2 派发弹窗 `DispatchTaskDialog.vue`
+
+阶段一表单顶部增加 **派发方式**：
+
+| 方式 | UI | 主按钮 | 成功后 |
+|------|-----|--------|--------|
+| 单条任务（默认） | 现有：任务名称、工艺路线、描述、备注 | 生成任务 | 进入三栏编辑工艺（现状） |
+| 任务集合 | 下拉选启用集合（`/active`）；选中后 `GET /{id}` 拉条目做只读预览（名称/路线/描述/备注） | 生成任务 | 调用 `from-set` → 关闭弹窗 → 刷新任务列表；**不**进编辑阶段 |
+
+校验：
+
+- 集合方式：必须选中集合；预览至少一条。
+- 后端返回路线缺失等错误：弹窗内提示，不关闭。
+
+编辑已有任务（`editTaskId`）路径不变，不出现派发方式切换。卡片头与任务区空态的「派发任务」共用本弹窗，一并生效。
+
+### 5.3 存为集合
+
+仅 `pageMode === 'manage'`：
+
+- 卡片 `…` 菜单增加「存为任务集合」。
+- 显示条件：该工单已加载到至少一条生产任务（可用卡片内 `presetTasks` / 任务区数据判断）。
+- 弹窗：集合名称、备注、只读预览映射条目；确定调 `from-work-order`。
+- 【我的生产任务】不出现该菜单项。
+
+### 5.4 API 模块
+
+新建 `web-admin/src/api/production-task-set.ts`；`production-task.ts` 增加 `fetchCreateProductionTasksFromSet`。
+
+---
+
+## 6. 错误处理与边界
+
+| 场景 | 行为 |
+|------|------|
+| 集合名为空 / 重名 | 400，前端表单校验 + 接口提示 |
+| 无条目或任务名全空 | 保存失败 |
+| 停用集合 | 不出现在 `/active`；已打开派发若仍提交由后端拒绝 |
+| 集合中路线已删 | `from-set` 整单失败，提示缺失路线 |
+| 工单已完成/已作废 | 不允许 `from-set`；仍允许「存为集合」 |
+| 集合派发后 | 用户对每条任务单独「编辑工艺」「步骤派发」 |
+| 同一工单多次派发同一集合 | 允许（与多次单条派发一致，会再生成一批任务） |
+
+---
+
+## 7. 菜单与权限
+
+- 父级：生产基础信息（`production-base` / PRB）
+- C 菜单：生产任务集合；`path=production-task-set`；`component=/production/production-task-set/index`
+- SQL：`docs/sql/alter_sys_menu_add_production_task_set.sql`，幂等；对已有 PRB 子菜单权限的角色授予（对照废弃物 / 检测项目模版菜单脚本）
+
+| 能力 | perms |
+|------|-------|
+| 列表/查看 | `production:task-set:list` |
+| 新增（含从工单存为集合） | `production:task-set:add` |
+| 编辑（含启停） | `production:task-set:edit` |
+| 删除 | `production:task-set:remove` |
+
+派发弹窗「任务集合」方式：有 list 权限才展示集合下拉；无 list 时仍可用「单条任务」。无 add 权限则隐藏「存为任务集合」。
+
+---
+
+## 8. 非目标
+
+- 集合与工单 Tab / 产品类型的强制绑定或自动默认选中
+- 步骤级快照、批量步骤派发、批量进入执行
+- 派发集合后自动打开第一条的三栏编辑
+- 小程序 / mobile-h5 侧派发
+- 修改「我的生产任务」卡片操作（仍无派发任务）
+
+---
+
+## 9. 验收
+
+1. 维护页可增改删启停集合；条目含名称/可选路线/描述/备注；停用后派发下拉不可见。
+2. 派发弹窗「单条」行为与改前一致（生成 → 编辑工艺）。
+3. 派发弹窗「任务集合」选含 4 条的集合 → 一次生成 4 条任务 → 弹窗关闭 → 卡片任务区可见 4 条；不进入三栏编辑。
+4. 集合内某路线已删 → 一条任务都不生成，有明确错误。
+5. 工单「存为任务集合」可保存名称/路线/描述/备注；空名称任务跳过；无有效任务时失败。
+6. 【我的生产任务】无「派发任务」「存为任务集合」。
+
+---
+
+## 10. 实现落点（摘要）
+
+| 层 | 落点 |
+|----|------|
+| SQL | 建表 + 菜单授权 |
+| Model / CRUD / Schema | `BizProductionTaskSet`、`BizProductionTaskSetItem`；CRUD；复用 `create_production_task` |
+| API | `production.py` 注册集合 CRUD、`from-work-order`、`from-set` |
+| 前端页 | `production-task-set/index.vue` + 路由/菜单 |
+| 派发 | `DispatchTaskDialog.vue` |
+| 存为 | `ProductionWorkOrderCardList.vue` + TabPanel/index 命令处理 |
+| 测试 | 后端：`from-set` 事务与路线校验；`from-work-order` 跳过空名；集合名唯一 |