323 lines
17 KiB
Markdown
323 lines
17 KiB
Markdown
# 工艺路线管理模块设计规格
|
||
|
||
## 概述
|
||
|
||
实现需求文档 2.3.8 节「工艺路线配置」。在生产管理菜单下的「工艺库管理」之后新增「工艺路线管理」菜单。
|
||
|
||
核心功能:维护工艺路线基础信息(路线编码、名称、产品类型、版本号),支持同编码多版本管理(轻量版:is_current 标记当前版本),并通过拖拽式三栏弹窗配置路线中的工艺步骤和子表数据。
|
||
|
||
## 设计决策
|
||
|
||
| 决策项 | 选择 | 理由 |
|
||
|--------|------|------|
|
||
| 版本号 | 同编码多版本 + is_current 标记当前版本 | 轻量版:同 route_code 可有多条记录,仅一个可标记为当前版本。无发布/草稿状态机 |
|
||
| 子表范围 | 完整复刻4张子表(试剂/耗材/产出物/数据采集) | 从工艺库拖入时克隆默认数据,用户可覆盖编辑 |
|
||
| 排列模式 | 线性排列(A→B→C→D) | 卡片从上到下,无需分支逻辑 |
|
||
| 可编辑范围 | 全部字段可编辑(基础信息+4张子表) | 右侧面板展示完整工艺信息供修改 |
|
||
| 保存方式 | 实时保存,拖入即创建后端记录 | 每步操作即时持久化,弹窗关闭无需额外保存 |
|
||
| UI方案 | 方案A:单弹窗 + vue-draggable-plus | 项目中已有3处成熟用法,跨栏拖拽通过HTML5 Drag API组合实现 |
|
||
| 步骤删除 | 支持删除,软删除步骤+级联软删除子表 | 中栏卡片上有删除按钮,确认后删除 |
|
||
|
||
## 依赖
|
||
|
||
| 依赖模块 | 用途 | 状态 |
|
||
|----------|------|------|
|
||
| 细胞产品类型管理(biz_cell_product_type) | 产品类型下拉 | 已实现 |
|
||
| 工艺工序分类(biz_process_category) | 工艺分组展示 | 已实现 |
|
||
| 工艺库(biz_process + 4张子表) | 拖入时的数据源和克隆来源 | 已实现 |
|
||
| SOP文档(biz_sop_document) | 步骤关联SOP | 已实现 |
|
||
| vue-draggable-plus@0.6.0 | 卡片排序拖拽 | 已安装 |
|
||
| sortablejs@1.15.7 | vue-draggable-plus 底层引擎 | 已安装 |
|
||
|
||
## SQL 表(6 张新建)
|
||
|
||
所有表遵循项目公共字段规范:`id` VARCHAR(64) UUID → 业务字段 → `tenant_no` → `order_num` → `remark` → `create_by` → `create_dept_id` → `create_time` → `update_by` → `update_time` → `del_flag`。
|
||
|
||
### 1. biz_process_route — 工艺路线主表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| route_code | VARCHAR(64) NOT NULL | 路线编码 |
|
||
| route_name | VARCHAR(100) NOT NULL | 路线名称 |
|
||
| product_type_id | VARCHAR(64) DEFAULT NULL | 细胞产品类型ID(引用 biz_cell_product_type) |
|
||
| version | VARCHAR(50) DEFAULT NULL | 版本号(用户手填文本,如 V1.0、V2.0) |
|
||
| is_current | CHAR(1) DEFAULT '0' | 是否当前版本(0-否 1-是)。同 route_code 下仅一条记录 is_current=1 |
|
||
| + 公共字段 | | |
|
||
|
||
索引:`idx_route_tenant(tenant_no, del_flag)`
|
||
|
||
### 2. biz_process_route_step — 路线工序步骤
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| route_id | VARCHAR(64) NOT NULL | 所属路线ID |
|
||
| process_id | VARCHAR(64) DEFAULT NULL | 来源工艺库工艺ID(工艺被删时可null) |
|
||
| step_order | INT DEFAULT NULL | 步骤顺序(拖拽排序时自动计算) |
|
||
| process_code | VARCHAR(64) DEFAULT NULL | 工序代码(从工艺库克隆,可编辑) |
|
||
| category_id | VARCHAR(64) DEFAULT NULL | 工序分类ID(可编辑) |
|
||
| process_name | VARCHAR(100) DEFAULT NULL | 工序名称(可编辑) |
|
||
| description | VARCHAR(500) DEFAULT NULL | 描述(可编辑) |
|
||
| equipment_name | VARCHAR(200) DEFAULT NULL | 预计使用设备(可编辑) |
|
||
| estimated_duration | VARCHAR(100) DEFAULT NULL | 预估耗时(可编辑) |
|
||
| sop_ids | VARCHAR(1000) DEFAULT NULL | 关联SOP文档ID(可编辑,逗号分隔) |
|
||
| + 公共字段 | | |
|
||
|
||
索引:`idx_prs_route(route_id, del_flag)`、`idx_prs_tenant(tenant_no, del_flag)`
|
||
|
||
### 3. biz_process_route_step_reagent — 步骤试剂
|
||
|
||
字段完全镜像 `biz_process_reagent`,但外键改为 `step_id`(关联 biz_process_route_step.id):
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| step_id | VARCHAR(64) NOT NULL | 所属步骤ID |
|
||
| reagent_code | VARCHAR(64) DEFAULT NULL | 试剂编码 |
|
||
| reagent_name | VARCHAR(100) DEFAULT NULL | 试剂名称 |
|
||
| spec | VARCHAR(200) DEFAULT NULL | 规格 |
|
||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||
| unit | VARCHAR(64) DEFAULT NULL | 单位 |
|
||
| is_key_material | CHAR(1) DEFAULT '0' | 是否关键物料(0-否 1-是) |
|
||
| + 公共字段 | | |
|
||
|
||
索引:`idx_prsr_step(step_id, del_flag)`
|
||
|
||
### 4. biz_process_route_step_consumable — 步骤耗材
|
||
|
||
字段完全镜像 `biz_process_consumable`,外键改为 `step_id`:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| step_id | VARCHAR(64) NOT NULL | 所属步骤ID |
|
||
| consumable_code | VARCHAR(64) DEFAULT NULL | 耗材编码 |
|
||
| consumable_name | VARCHAR(100) DEFAULT NULL | 耗材名称 |
|
||
| spec_model | VARCHAR(200) DEFAULT NULL | 规格型号 |
|
||
| standard_usage | VARCHAR(100) DEFAULT NULL | 标准用量 |
|
||
| unit | VARCHAR(64) DEFAULT NULL | 单位 |
|
||
| is_required | CHAR(1) DEFAULT '1' | 是否必需(1-必须 0-可选) |
|
||
| remark | VARCHAR(512) DEFAULT NULL | 备注 |
|
||
| + 公共字段(不含 remark) | | |
|
||
|
||
索引:`idx_prsc_step(step_id, del_flag)`
|
||
|
||
### 5. biz_process_route_step_output — 步骤产出物
|
||
|
||
字段完全镜像 `biz_process_output`,外键改为 `step_id`:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| step_id | VARCHAR(64) NOT NULL | 所属步骤ID |
|
||
| output_type_id | VARCHAR(64) DEFAULT NULL | 产出类型ID |
|
||
| output_name | VARCHAR(200) DEFAULT NULL | 产出物名称 |
|
||
| output_barcode | VARCHAR(200) DEFAULT NULL | 产出物条码 |
|
||
| + 公共字段 | | |
|
||
|
||
索引:`idx_prso_step(step_id, del_flag)`
|
||
|
||
### 6. biz_process_route_step_data_collection — 步骤数据采集
|
||
|
||
字段完全镜像 `biz_process_data_collection`,外键改为 `step_id`:
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| id | VARCHAR(64) PK | UUID |
|
||
| step_id | VARCHAR(64) NOT NULL | 所属步骤ID |
|
||
| collection_name | VARCHAR(100) DEFAULT NULL | 采集信息名称 |
|
||
| unit | VARCHAR(64) DEFAULT NULL | 单位 |
|
||
| + 公共字段 | | |
|
||
|
||
索引:`idx_prsdc_step(step_id, del_flag)`
|
||
|
||
### 菜单数据
|
||
|
||
在「工艺库管理」(order_num=6)之后、「SOP文档」(order_num=7)之前插入,SOP 文档 order_num 改为 8:
|
||
|
||
```sql
|
||
INSERT INTO sys_menu (id, menu_name, parent_id, menu_type, path, component, perms, is_frame, visible, status, tenant_no, order_num, remark, create_by, create_dept_id, create_time, update_by, update_time, del_flag)
|
||
VALUES ('90000000000000000000000000000010', '工艺路线管理', '90000000000000000000000000000001', 'C', 'process-route', '/production/process-route/index', 'production:process-route:list', 1, '1', '1', 'zkxw', 7, NULL, NULL, '', '2026-05-19 00:00:00', NULL, '2026-05-19 00:00:00', 0);
|
||
|
||
-- SOP文档 order_num 从 7 改为 8
|
||
UPDATE sys_menu SET order_num = 8 WHERE id = '90000000000000000000000000000004';
|
||
```
|
||
|
||
## 后端 API
|
||
|
||
路由前缀:`/api/admin/production/route/`
|
||
|
||
### 路线主表 CRUD
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| GET | `/list` | 路线分页列表。支持筛选:route_name(模糊)、route_code(精确)、product_type_id。排序:order_num ASC, create_time DESC。带 tenant_no 隔离。 |
|
||
| POST | `/create` | 创建路线主表。必填:route_code, route_name。自动填充 tenant_no。默认 is_current=0。 |
|
||
| PUT | `/update` | 更新路线主表信息(编码、名称、产品类型、版本号、备注)。 |
|
||
| PUT | `/set-current` | 设置指定路线为当前版本。逻辑:先将同 route_code + tenant_no 下所有记录 is_current 置 0,再将目标记录 is_current 置 1。 |
|
||
| DELETE | `/delete/{id}` | 软删除路线(del_flag=1)+ 级联软删除所有步骤及步骤子表。 |
|
||
| GET | `/detail/{id}` | 获取路线详情:主表 + 步骤列表(按 step_order ASC)+ 每个步骤的4张子表数据。 |
|
||
|
||
### 步骤操作(实时保存)
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| POST | `/step/add` | 从工艺库拖入创建步骤。入参:route_id, process_id, step_order。后端读取 biz_process 基础信息克隆到 step 表,读取4张子表数据批量克隆到 route_step_* 子表。返回完整 step 对象(含子表)。 |
|
||
| PUT | `/step/update` | 更新步骤基础信息(右侧面板字段修改时触发)。 |
|
||
| PUT | `/step/reorder` | 批量重排步骤顺序。入参:route_id, step_ids[](新顺序数组)。遍历更新 step_order。 |
|
||
| DELETE | `/step/delete/{id}` | 软删除步骤(del_flag=1)+ 级联软删除该步骤的4张子表数据。 |
|
||
| PUT | `/step/reagent/update` | 更新步骤试剂子表。入参:step_id, items[](完整替换)。 |
|
||
| PUT | `/step/consumable/update` | 更新步骤耗材子表。入参:step_id, items[](完整替换)。 |
|
||
| PUT | `/step/output/update` | 更新步骤产出子表。入参:step_id, items[](完整替换)。 |
|
||
| PUT | `/step/data-collection/update` | 更新步骤数据采集子表。入参:step_id, items[](完整替换)。 |
|
||
|
||
### 关键后端逻辑
|
||
|
||
**拖入克隆(step/add)**:
|
||
1. 校验 route_id 存在且属于当前租户
|
||
2. 从 `biz_process` 读取工艺基础信息
|
||
3. 插入 `biz_process_route_step`(克隆字段:process_code, category_id, process_name, description, equipment_name, estimated_duration, sop_ids)
|
||
4. 从 `biz_process_reagent` 等4张子表批量读取并插入对应 `biz_process_route_step_*`
|
||
5. 返回完整 step 对象
|
||
|
||
**级联软删除**:
|
||
- 删除路线 → 遍历所有步骤设 del_flag=1 → 遍历每步子表设 del_flag=1
|
||
- 删除步骤 → 遍历该步骤子表设 del_flag=1
|
||
|
||
**子表更新(完整替换策略)**:
|
||
- 接收 items[] 后,将现有记录 del_flag=1,然后批量插入新记录
|
||
- 避免逐条 diff,简化逻辑
|
||
|
||
## 前端设计
|
||
|
||
### 文件清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `web-admin/src/views/production/process-route/index.vue` | 新建 | 路线列表页 + 路线图配置弹窗 |
|
||
| `web-admin/src/api/production.ts` | 追加 | route 相关 API 函数 |
|
||
| `web-admin/src/router/modules/sqxp.ts` | 追加 | process-route 路由条目 |
|
||
|
||
### 列表页
|
||
|
||
遵循标准列表模板(参考 `src/views/system/unit/index.vue`):
|
||
|
||
- **搜索栏**:路线名称(模糊)、路线编码(精确)、产品类型(下拉,数据来自细胞产品类型管理列表 API)
|
||
- **工具栏**:新增按钮(单一 primary)
|
||
- **表格列**:路线名称、路线编码、产品类型名称、版本号、当前版本(is_current=1 时显示绿色 `el-tag` 标签)、备注、创建时间
|
||
- **操作列**(fixed="right", min-width ≥ 260px):路线图配置、编辑、设为当前版本(仅 is_current=0 时显示)、删除
|
||
- **新增/编辑弹窗**:标准表单(label-position="top"),字段:路线编码、路线名称、产品类型(下拉)、版本号(文本)、备注
|
||
|
||
### 路线图配置弹窗
|
||
|
||
**弹窗属性**:`width="90vw"`,`destroy-on-close`,标题显示路线名称和版本号
|
||
|
||
**三栏布局**(flex):
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────┐
|
||
│ 路线图配置 - {路线名称} v{版本号} [关闭] │
|
||
├────────────┬──────────────────────┬──────────────────────────┤
|
||
│ 工艺库 │ 工艺流程布局 │ 工艺详情 │
|
||
│ (240px) │ (flex:1) │ (360px) │
|
||
│ │ │ │
|
||
│ [分类折叠] │ ┌────────────┐ │ 工序名称: [___] │
|
||
│ > 细胞培养 │ │ 步骤1: xxx │ ←拖 │ 工序分类: [下拉] │
|
||
│ [卡片] │ └────────────┘ │ 描述: [___] │
|
||
│ [卡片] │ ┌────────────┐ │ 设备: [___] │
|
||
│ > 病毒转染 │ │ 步骤2: xxx │ │ 预估耗时: [___] │
|
||
│ [卡片] │ └────────────┘ │ SOP: [选择] │
|
||
│ > ... │ │ ────────────── │
|
||
│ │ [+ 拖入工艺卡片] │ [试剂][耗材][产出][采集] │
|
||
│ │ │ (子表tab切换编辑) │
|
||
└────────────┴──────────────────────┴──────────────────────────┘
|
||
```
|
||
|
||
**左栏 — 工艺库面板(240px 固定宽度)**:
|
||
- 使用 `el-collapse` 按工序分类(biz_process_category)分组展示
|
||
- 每组内展示工艺小卡片:工序名称 + 编码
|
||
- 卡片使用 HTML5 `draggable="true"` + `@dragstart` 传递 `process_id`
|
||
- 无分类的工艺归入"未分类"组
|
||
- 仅展示当前租户未删除的工艺
|
||
|
||
**中栏 — 流程布局区(flex:1 自适应)**:
|
||
- 使用 `vue-draggable-plus`(VueDraggable 组件)包裹步骤卡片列表
|
||
- 每张步骤卡片显示:步骤序号(圆角标签)+ 工艺名称 + 操作按钮(删除图标)
|
||
- 支持内部排序拖拽(handle 拖拽手柄,使用 `<el-icon><Rank /></el-icon>`)
|
||
- 空白区域通过 `@dragover.prevent` + `@drop` 接收从左栏拖入的工艺卡片
|
||
- 拖入时调用 `POST /step/add`,即时创建后端记录
|
||
- 排序变化时调用 `PUT /step/reorder`
|
||
- 点击卡片 → 选中态(高亮边框)→ 触发右栏加载详情
|
||
- 卡片上的删除按钮 → 确认弹窗 → `DELETE /step/delete/{id}` → 从列表移除
|
||
|
||
**右栏 — 工艺详情编辑面板(360px 固定宽度)**:
|
||
- **顶部**:工艺基础信息表单
|
||
- 工序名称(el-input)
|
||
- 工序分类(el-select,下拉数据来自工艺工序分类)
|
||
- 描述(el-input textarea)
|
||
- 设备名称(el-input)
|
||
- 预估耗时(el-input)
|
||
- SOP文档(el-select multiple,数据来自 SOP 文档列表)
|
||
- 字段修改时 `@change` 触发 `PUT /step/update` 实时保存
|
||
- **底部**:4 个 el-tab-pane 切换子表编辑
|
||
- **试剂 tab**:表格列(试剂编码、名称、规格、标准用量、单位、是否关键物料),底部"添加"按钮新增行,每行有删除按钮。修改后实时保存 `PUT /step/reagent/update`
|
||
- **耗材 tab**:表格列(耗材编码、名称、规格型号、标准用量、单位、是否必需、备注),同上交互
|
||
- **产出 tab**:表格列(产出类型[下拉选择产出物类型]、名称、条码),同上交互
|
||
- **数据采集 tab**:表格列(采集名称、单位),同上交互
|
||
- 未选中任何步骤时显示空状态提示:"请从左侧工艺库拖入工艺,或点击已添加的步骤查看详情"
|
||
|
||
### 数据流
|
||
|
||
```
|
||
拖入流程:
|
||
左栏卡片 dragstart(process_id)
|
||
→ 中栏 drop 事件
|
||
→ POST /step/add {route_id, process_id, step_order: list.length + 1}
|
||
→ 后端克隆工艺+子表 → 返回完整 step
|
||
→ 前端追加到步骤列表
|
||
|
||
排序流程:
|
||
中栏内 vue-draggable-plus 拖拽排序
|
||
→ @end 回调
|
||
→ PUT /step/reorder {route_id, step_ids: [...]}
|
||
|
||
编辑流程:
|
||
右栏字段 @change
|
||
→ PUT /step/update {step_id, ...fields}
|
||
|
||
右栏子表增删改
|
||
→ PUT /step/{sub-table}/update {step_id, items: [...]}
|
||
|
||
删除步骤:
|
||
卡片删除按钮 → ElMessageBox.confirm
|
||
→ DELETE /step/delete/{step_id}
|
||
→ 前端从列表移除
|
||
|
||
点击步骤:
|
||
中栏卡片 click
|
||
→ 设置 selectedStepId
|
||
→ 右栏加载该步骤详情(从列表数据中取,无需额外 API)
|
||
```
|
||
|
||
## 实现文件清单
|
||
|
||
| 层 | 文件 | 操作 |
|
||
|----|------|------|
|
||
| SQL | `docs/sql/production_process_route.sql` | 新建:6张表DDL + 菜单INSERT + SOP order_num UPDATE |
|
||
| Model | `backend/app/models/models.py` | 追加 6 个 SQLAlchemy Model 类 |
|
||
| Model | `backend/app/models/__init__.py` | 追加 6 个 export |
|
||
| CRUD | `backend/app/crud/process_route.py` | 新建:路线CRUD + 步骤CRUD + 子表CRUD + 克隆逻辑 |
|
||
| API | `backend/app/api/production.py` | 追加 route 子路由(挂载到 production router 下) |
|
||
| Schema | `backend/app/schemas/process_route.py` | 新建:Pydantic v2 schemas |
|
||
| 前端 API | `web-admin/src/api/production.ts` | 追加 route 相关函数(~15个 API 函数) |
|
||
| 前端页面 | `web-admin/src/views/production/process-route/index.vue` | 新建:列表页 + 三栏拖拽配置弹窗 |
|
||
| 路由 | `web-admin/src/router/modules/sqxp.ts` | 追加 process-route 路由条目 |
|
||
|
||
## 风险与注意事项
|
||
|
||
1. **跨容器拖拽**:左栏(HTML5 Drag)→ 中栏(vue-draggable-plus)的跨容器拖入是核心难点。需在 drop 事件中正确获取 process_id 并调用 API。参考项目中 FlowDesigner.vue 的 HTML5 drag 实现。
|
||
2. **大弹窗性能**:90vw 弹窗内三栏 + 多个子表可能数据量大。步骤列表应限制每页展示(暂无分页需求,路线步骤通常 < 50)。
|
||
3. **工艺库删除影响**:步骤的 process_id 引用工艺库,但工艺被删除后步骤保留(process_id 可 null)。右栏编辑时不依赖 process_id 回查,所有数据已克隆到步骤中。
|
||
4. **子表更新策略**:使用完整替换(del旧 + insert新),避免复杂 diff。注意 UUID 生成和 tenant_no 继承。
|