zkxw/docs/superpowers/specs/2026-05-19-process-route-management-design.md

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

概述

实现需求文档 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：

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 继承。