# 工艺设备关联设备管理 设计文档 > 日期: 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. 历史数据迁移 + 联调