# 工艺路线管理模块设计规格

## 概述

实现需求文档 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 继承。