Files
zkxw/docs/superpowers/specs/2026-07-28-process-route-default-equipment-design.md
T
2026-07-28 21:33:15 +08:00

132 lines
6.9 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.
# 工艺路线默认设备(路线级)设计文档
> 日期: 2026-07-28
> 状态: 已确认
> 范围: `biz_process_route` + 工艺库「路线图配置」+ 生产任务派发带入
> 关联: 派发任务任务级设备面板(`TaskEquipmentPanel`);历史步骤级设备设计见 `2026-06-15-process-equipment-link-design.md`(本需求不改造步骤级 UI)
## 1. 背景与目标
**现状**
- 【工艺库管理】→【工艺路线】→【路线图配置】可配置工序步骤,但**不能**配置路线级默认设备。
- 【生产工单】→【派发任务】可选工艺路线生成步骤,并在任务编辑区「设备」面板配置**任务级**设备;设备需每次手选。
- 库表已有:`biz_process` / `biz_process_route_step` / `biz_production_task` / `biz_production_task_step` 的 `equipment_ids` + `equipment_name`;**`biz_process_route` 尚无**设备字段。派发克隆路线时只拷贝步骤及子表,**不**带设备到任务。
**目标**
- 在「路线图配置」中为整条工艺路线预制一套默认设备。
- 派发任务选中该路线时,自动将默认设备写入任务「设备」面板(可再改)。
**非目标**
- 不在新增/编辑路线弹窗配置设备。
- 不改造工艺列表 / 路线步骤 / 任务步骤的步骤级设备 UI。
- 不把已派发任务与路线默认设备双向同步。
- 不做小程序端改动。
## 2. 已确认决策
| 项 | 决策 |
|----|------|
| 设备挂载层级 | **A. 路线级**:整条路线一套默认设备 |
| 配置入口 | **B. 「路线图配置」弹窗**内单独「默认设备」虚拟块(对齐派发任务设备卡) |
| 实现方案 | **方案 1**:`biz_process_route` 增加 `equipment_ids` / `equipment_name`;复用 `TaskEquipmentPanel` |
| 带入时机 | 创建生产任务且传入 `routeId` 时,一次性拷贝到 `biz_production_task` |
| 后续修改 | 改路线不影响已有任务;任务内改设备不回写路线 |
| 未配设备 / 未选路线 | 任务设备为空,可手选 |
| 复制路线 | 若后续/现有存在「复制路线」能力,须一并复制默认设备;当前仅有步骤复制则本需求不新增路线复制入口 |
## 3. 数据模型
### 3.1 `biz_process_route` 新增字段
在业务字段区(建议 `is_current` 之后、`tenant_no` 之前)新增:
| 字段 | 类型 | 说明 |
|------|------|------|
| `equipment_ids` | VARCHAR(1000) NULL | 关联 `biz_equipment.id`,逗号分隔 |
| `equipment_name` | VARCHAR(1000) NULL | 设备名称快照,逗号分隔 |
与任务表 `biz_production_task.equipment_ids` / `equipment_name` 约定一致。
### 3.2 快照规则
- 保存路线默认设备时调用现有 `resolve_equipment_list_snapshot(db, equipment_ids, tenant_no)`,同时写入 ID 串与名称快照。
- 派发拷贝:将路线上的 `equipment_ids`、`equipment_name` **原样写入**任务(创建时快照);任务侧后续再保存时仍走任务自己的快照解析。
### 3.3 与步骤级字段的关系
- `biz_process_route_step.equipment_*`、任务步骤 `equipment_*` **本需求不读写、不展示**。
- 历史设计(步骤级可覆盖)保留为后续可选能力,与本需求正交。
## 4. 数据流
```
biz_equipment(设备主数据)
↑ 勾选引用
biz_process_route.equipment_ids / equipment_name(路线默认设备)
│ create_production_task(route_id=…)
↓
biz_production_task.equipment_ids / equipment_name(任务设备面板)
```
步骤克隆 `_clone_route_to_task` 仍只负责步骤与试剂/耗材/产出/采集子表;**路线默认设备在创建任务主表时额外写入**(可在 `_clone_route_to_task` 前后对 `BizProductionTask` 赋值,或抽小函数 `_apply_route_default_equipment`)。
## 5. 接口
| 接口 | 变更 |
|------|------|
| `GET /web/admin/process-routes` | 列表项增加 `equipmentIds`(数组)、`equipmentName`(可选,展示用) |
| `GET /web/admin/process-routes/{id}` | 详情(含路线头)返回同上 |
| `PUT /web/admin/process-routes/{id}` | `ProcessRouteUpdateBody` 增加可选 `equipmentIds`;有传则解析快照并更新 |
| 创建生产任务(现有派发 API) | 存在 `route_id` 时,将路线默认设备写入新任务 |
前端:`fetchUpdateProcessRoute(id, { equipmentIds })` 即可;列表/详情类型补字段。
序列化建议与任务侧一致:`equipmentIds` 为 `string[]`(`parse_equipment_ids`),`equipmentName` 为字符串。
## 6. UI(路线图配置)
对齐 `DispatchTaskDialog` 中间栏虚拟设备卡:
1. **中间栏顶部**:虚拟卡片「默认设备」
- 未选设备:`el-tag` info「暂无」
- 已选:`el-tag` success「已选 N 台」
2. **选中逻辑**:点击「默认设备」→ 清除步骤选中;点击步骤 → 清除「默认设备」选中。右侧互斥展示。
3. **右侧**:复用 `TaskEquipmentPanel`
- `equipmentOptions`:与派发/任务编辑相同数据源(如 `fetchAllEquipments` 或任务编辑选项接口中的 equipments)
- 保存:调用 `PUT process-routes/{id}` 写 `equipmentIds`;成功后刷新本地路线头状态与标签
4. **新增/编辑路线弹窗**:不加设备字段。
样式:复用已有 `virtual-step-card` / `dispatch-equipment-card` 等 class(或抽公共样式到 `route-config`),保持 Fresh Mint,勿引入小程序色值。
## 7. 改动文件(预期)
| 区域 | 文件 |
|------|------|
| SQL | `docs/sql/` 下新增迁移(ALTER `biz_process_route`);视需要同步 `zkxw.sql` 表结构片段 |
| Model | `backend/app/models/models.py` → `BizProcessRoute` |
| Schema | `backend/app/schemas/process_route.py` → UpdateBody(及如有独立详情结构) |
| CRUD | `backend/app/crud/process_route.py` → `_route_row_to_dict` / `update_route` |
| CRUD | `backend/app/crud/production_task.py` → 创建任务带入路线默认设备 |
| API | `backend/app/api/production.py` → update route 传 `equipment_ids` |
| UI | `web-admin/src/views/production/process/ProcessRouteTab.vue` |
| 可选复用 | `TaskEquipmentPanel.vue`、`equipment-select` 工具 |
完成后执行 `./scripts/update-graph.sh backend` 与 `./scripts/update-graph.sh frontend`(或按实际改动项目)。
## 8. 验收标准
1. 路线图配置可勾选并保存默认设备;关闭再打开仍显示。
2. 派发任务选择该路线 → 进入编辑阶段后,「设备」面板已预填相同设备。
3. 任务内修改或清空设备不影响路线;修改路线默认设备不影响已创建任务。
4. 未选路线或路线无默认设备 → 任务设备为空。
5. 停用设备在勾选列表中的表现与现有任务设备面板一致。
## 9. 测试要点
- 保存含多台设备、清空设备、非法/已删设备 ID 的后端校验。
- 选路线派发 vs 不选路线派发。
- 路线有设备但任务创建后改路线再派发新任务:新任务用新默认值,旧任务不变。