Files
zkxw/docs/superpowers/specs/2026-06-15-process-equipment-link-design.md
T
2026-06-16 07:38:27 +08:00

230 lines
9.8 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-06-15
> 状态: 已实现
> 关联模块: 设备管理、工艺库管理、工艺路线管理、生产工单/生产任务
---
## 1. 业务背景
【生产基础信息】→【设备管理】维护租户内设备主数据(`biz_equipment`)。
【工艺库管理】→【工艺列表】中「设备名称」目前为自由文本(`equipment_name`),与设备主数据无关联,存在录入不一致、无法校验、无法追溯等问题。
工艺还会经【工艺路线】组合,并在【生产工单】→【生产任务】中作为步骤快照执行。设备字段在三层均采用**快照复制**模式(与工序名称等字段一致),改造需兼顾主数据关联与历史快照完整性。
---
## 2. 需求共识
| # | 决策 | 说明 |
|---|------|------|
| 1 | **步骤级可覆盖(选项 A)** | 工艺路线步骤、生产任务步骤的设备**必须从设备管理选择**,但允许与工艺主数据的默认设备不同 |
| 2 | **多设备逗号存储** | 三表新增 `equipment_ids`(逗号分隔 ID),`equipment_name` 扩展为逗号分隔名称快照(varchar 1000) |
| 3 | **保留名称快照** | `equipment_name` 保存当时设备名称列表(逗号分隔),列表/导出直接展示 |
| 4 | **不自动回写下游** | 修改工艺主数据的设备后,**不**自动更新已存在的路线步骤或生产任务步骤(与现有 `process_name` 等行为一致) |
| 5 | **设备删除约束** | 被工艺/路线步骤引用的设备**禁止软删除**;停用(status=0)允许,下拉中过滤或标记异常 |
| 6 | **UI 控件** | 三处编辑界面:`el-input` 改为 `el-select`(filterable),数据源 `fetchAllEquipments()`,展示「设备编码 / 设备名称」 |
---
## 3. 数据流
```
biz_equipment(设备主数据)
↑ equipment_id 引用
biz_process(工艺默认设备)
│ add_step / 拖入克隆:复制 equipment_id + equipment_name
↓
biz_process_route_step(路线步骤,可覆盖设备)
│ _clone_route_to_task:复制 equipment_id + equipment_name
↓
biz_production_task_step(任务步骤,可覆盖设备)
```
**复制触发点(均需同步 `equipment_id` + `equipment_name`):**
| 触发场景 | 后端函数 |
|----------|----------|
| 工艺拖入路线 | `process_route.add_step()` |
| 路线步骤复制 | `process_route.copy_step()` |
| 路线克隆新版本 | `process_route` 版本复制逻辑(如有) |
| 任务选路线派工 | `production_task._clone_route_to_task()` |
| 任务手动加工艺步骤 | `production_task.add_task_step(process_id=...)` |
| 任务步骤复制 | `production_task.copy_task_step()` |
---
## 4. 数据库变更
### 4.1 变更表(3 张)
在以下表**业务字段区**(`description` 之后或同类位置)新增:
| 表 | 新增字段 | 类型 | 说明 |
|----|----------|------|------|
| `biz_process` | `equipment_id` | VARCHAR(64) DEFAULT NULL | 关联 `biz_equipment.id` |
| `biz_process_route_step` | `equipment_id` | VARCHAR(64) DEFAULT NULL | 步骤级设备,可覆盖工艺默认 |
| `biz_production_task_step` | `equipment_id` | VARCHAR(64) DEFAULT NULL | 任务步骤级设备,可覆盖路线/工艺 |
**保留现有字段:** 三表 `equipment_name` varchar(200) **不删除**,作为快照冗余。
**索引(可选,建议):**
- `idx_process_equipment(equipment_id, del_flag)` — 用于删除引用检查
- 路线/任务步骤表可不建 FK 索引(引用检查走工艺主表即可)
### 4.2 不变表
- `biz_equipment` — 结构不变,增加被引用校验逻辑
- `biz_process_route`、`biz_production_task` 及所有子表(试剂/耗材/产出/采集)— 不涉及设备
### 4.3 迁移 SQL 示例
```sql
ALTER TABLE biz_process
ADD COLUMN equipment_id varchar(64) DEFAULT NULL COMMENT '关联设备ID(biz_equipment.id)' AFTER description;
ALTER TABLE biz_process_route_step
ADD COLUMN equipment_id varchar(64) DEFAULT NULL COMMENT '关联设备ID(biz_equipment.id)' AFTER description;
ALTER TABLE biz_production_task_step
ADD COLUMN equipment_id varchar(64) DEFAULT NULL COMMENT '关联设备ID(biz_equipment.id)' AFTER description;
```
### 4.4 历史数据迁移
1. 对三表现有 `equipment_name` 非空记录,按 `tenant_no` + 精确/trim 后匹配 `biz_equipment.equipment_name` 回填 `equipment_id`
2. 无法匹配的记录:`equipment_id` 留 NULL,`equipment_name` 保留原值;列表/表单展示时提示「未关联设备(历史数据)」
3. 匹配脚本放 `backend/scripts/migrate_process_equipment_id.py`,可 `--dry-run`
---
## 5. 后端设计
### 5.1 Model(`backend/app/models/models.py`)
三个 Model 各增加:
```python
equipment_id = Column(String(64), nullable=True, comment="关联设备ID")
```
### 5.2 CRUD 约定
**写入规则(统一 helper,建议 `resolve_equipment_snapshot(db, equipment_id, tenant_no) -> (id, name)`):**
- 传入 `equipment_id` 时:校验设备存在、未删除、同租户;写入 `equipment_id` 并将 `equipment_name` 设为当前 `biz_equipment.equipment_name`
- 清空设备:`equipment_id = None`,`equipment_name = None`
- **禁止**仅传 `equipment_name` 字符串而不传 ID(API 层废弃纯文本写入,兼容读取旧数据)
**`_row_to_dict` 扩展字段:**
- `equipmentId`
- `equipmentName`(快照名称,已有)
- 列表/详情可选 enrich:`equipmentCode`、`equipmentStatus`(join 设备表,仅展示)
**设备删除(`equipment.py` `soft_delete_equipment`):**
- 删除前查询 `biz_process`、`biz_process_route_step` 是否存在 `equipment_id = ? AND del_flag = 0`
- 存在则 `raise ValueError("该设备已被工艺或工艺路线引用,无法删除")`
- 生产任务步骤**不参与**删除拦截(任务为历史快照,允许设备从主数据删除后任务仍显示快照名称;若需严格可扩展检查)
### 5.3 API Schema(`backend/app/api/production.py` 等)
**ProcessCreateBody / ProcessUpdateBody:**
```python
equipment_id: Optional[str] = Field(None, alias="equipmentId")
# equipment_name 只读出参,Create/Update 不再接受客户端直传 equipmentName
```
**ProcessRouteStepUpdateBody、ProductionTaskStepUpdateBody:**
- 同上,接受 `equipmentId`,服务端解析名称快照
**响应:** 继续返回 `equipmentId` + `equipmentName`;详情可增加 `equipmentCode` 便于展示。
### 5.4 复制逻辑改动清单
| 文件 | 函数 | 改动 |
|------|------|------|
| `crud/process_route.py` | `add_step` | 复制 `proc.equipment_id` + `proc.equipment_name` |
| `crud/process_route.py` | `copy_step` | 复制 `src.equipment_id` + `src.equipment_name` |
| `crud/process_route.py` | `update_step` | 支持 `equipment_id` 参数,经 helper 写快照 |
| `crud/production_task.py` | `_clone_route_to_task` | 复制 `rs.equipment_id` + `rs.equipment_name` |
| `crud/production_task.py` | `add_task_step` | 从工艺复制 `equipment_id` + `equipment_name` |
| `crud/production_task.py` | `update_task_step` | 支持 `equipment_id` |
| `crud/production_task.py` | `copy_task_step` | 复制 `src.equipment_id` + `src.equipment_name` |
---
## 6. 前端设计
### 6.1 改动页面
| 页面 | 文件 | 改动 |
|------|------|------|
| 工艺列表/表单 | `views/production/process/index.vue` | 设备名称 → `el-select`,绑定 `formData.equipmentId`;列表列展示 `equipmentName`(或编码/名称) |
| 工艺路线步骤 | `views/production/process/ProcessRouteTab.vue` | 步骤基本信息区同样改为设备下拉,保存传 `equipmentId` |
| 生产任务步骤 | `views/production/production-work-order/StepDetailPanel.vue` | 同上 |
| 任务步骤编辑器 | `useTaskStepEditor.ts` | 保存 payload 改为 `equipmentId`;选中时本地同步 `equipmentName` 展示 |
### 6.2 下拉数据
- 使用已有 `fetchAllEquipments()`(`/web/admin/equipments/all`)
- Option label:`{equipmentCode} / {equipmentName}`
- 过滤:`status === '1'` 正常设备可选;`status === '0'` 可显示但标记「异常」
- 历史数据 `equipmentId` 为空但 `equipmentName` 有值:select 显示 placeholder「历史文本:xxx」,引导用户重新选择
### 6.3 UI 规范
- 遵循 Fresh Mint 规范;`label-position="top"`
- 与「工序分类」下拉交互一致(filterable + clearable)
- 字段非必填(与现况一致)
---
## 7. 业务规则摘要
| 场景 | 行为 |
|------|------|
| 新建工艺并选设备 | 写 `equipment_id`,冗余 `equipment_name` |
| 工艺改设备 | 仅更新 `biz_process`;已有路线/任务步骤不变 |
| 路线步骤改设备 | 仅更新该步骤;允许与来源工艺不同 |
| 任务步骤改设备 | 仅更新该步骤;执行中可改(与现有步骤编辑一致) |
| 设备改名 | 已存快照名称不变;新保存/新复制使用新名称 |
| 设备停用 | 下拉不可选或弱提示;已关联记录仍显示快照 |
| 设备删除 | 被工艺或路线步骤引用时拒绝删除 |
---
## 8. 测试要点
1. 工艺 CRUD:选设备、清空设备、列表/详情展示
2. 拖入路线:步骤继承工艺设备;步骤级改设备后与原工艺不同
3. 生产任务:选路线克隆、手动加工艺步骤,设备正确复制;步骤级覆盖
4. 设备删除:被工艺引用时拦截;未被引用可删
5. 历史数据:仅有 `equipment_name` 无 ID 时页面不报错,可重新关联
6. 字段一致性:运行 `python scripts/check_field_consistency.py`
---
## 9. 不在本次范围
- 设备与 SOP、环境检测等业务联动
- 生产任务按设备排产/冲突检测
- 小程序端设备展示
- 自动同步工艺设备变更到已有路线/任务
---
## 10. 实现顺序建议
1. SQL + Model + 迁移脚本
2. 后端 helper + process CRUD + API
3. process_route / production_task 复制与更新逻辑
4. 设备删除引用检查
5. 前端三处下拉改造
6. 历史数据迁移 + 联调