MrleeAdmin/backend/plugin/produce/produce-replication-plan.md

# Produce 插件六模块复刻方案

## 1. 文档目的

本文档用于梳理 `backend/plugin/produce` 插件需要优先复刻的 6 个模块，并结合旧项目的前端、后端、SQL 安装脚本，整理出一份可以直接执行的开发方案。

目标模块：

1. 工序管理 `process`
2. 工序步骤 `process-step`
3. 步骤状态 `step-status`
4. 步骤关系 `step-relation`
5. 状态转换 `status-transition`
6. 转换日志 `transition-log`

本文档基于以下真实参考：

- 旧前端目录：`old/web/src/views/produce/*`
- 旧后端路由：`old/server/app/admin/route/produce.php`
- 旧后端控制器：`old/server/app/admin/controller/produce/*`
- 旧后端 Validate：`old/server/app/admin/validate/produce/*`
- 旧后端 DAO / Model / Service：`old/server/app/common/{dao,model,services}/produce/*`
- 旧库 SQL：`old/server/scripts/sql/install.sql`
- 当前插件骨架：`backend/plugin/produce/*`

## 2. 当前 produce 插件现状

### 2.1 已存在结构

当前插件目录：`backend/plugin/produce`

已有基础骨架：

- `app/adminapi/controller/ProduceController.php`
- `config/app.php`
- `config/info.php`
- `config/route.php`
- `resource/menu/admin.php`
- `resource/template/admin/api`
- `resource/template/admin/views/produce/index`
- `resource/template/admin/lang`

### 2.2 缺失结构

以下目录当前基本为空，尚不足以承载 6 个业务模块：

- `app/model`
- `app/dao`
- `app/service`
- `app/validate`
- `app/schema`
- `resource/database/migrations`

结论：当前 `produce` 插件仍是示例骨架，复刻这 6 个模块时需要按插件标准完整补齐后端数据层、控制器、菜单、模板源前端。

## 3. 旧项目总体结构结论

### 3.1 旧前端页面模式

旧前端每个模块基本采用如下模式：

- `index.vue`
- `data.ts`
- `modules/form.vue`

技术模式为：

- `VXE Grid`
- 手写查询表单
- Drawer Form
- 手写列表请求与弹窗逻辑

不适合直接复制到当前项目。当前插件应改造为：

- `BasicCrud`
- `schemas/index.tsx`
- `api/index.ts`
- 插件模板源目录开发

### 3.2 旧后端路由模式

旧后端集中在：`old/server/app/admin/route/produce.php`

6 个目标模块在旧项目均有独立路由分组，说明旧项目对这 6 个模块是完整拆分的，不是页面层虚拟模块。

### 3.3 旧数据库来源

旧项目这 6 张核心表的建表信息没有体现在 `old/server/scripts/migrations` 目录的独立 PHP migration 中，核心定义主要在 SQL 安装脚本中：

- `old/server/scripts/sql/install.sql`

因此本次字段与索引参考，优先以：

1. SQL 安装脚本
2. Model fillable / casts / relation
3. DAO / Service 业务逻辑
4. 旧前端页面字段

作为综合依据。

## 4. 六模块真实表与后端入口对照

| 模块 | 表名（Model） | 旧控制器 | 旧服务/DAO | 旧前端目录 |
|---|---|---|---|---|
| 工序管理 | `produce_process` | `ProduceProcessController` | `ProduceProcessService` / `ProduceProcessDao` | `old/web/src/views/produce/process` |
| 工序步骤 | `produce_process_step` | `ProduceProcessStepController` | `ProduceProcessStepService` / `ProduceProcessStepDao` | `old/web/src/views/produce/process-step` |
| 步骤状态 | `produce_step_status` | `ProduceStepStatusController` | `ProduceStepStatusService` / `ProduceStepStatusDao` | `old/web/src/views/produce/step-status` |
| 步骤关系 | `produce_step_relation` | `ProduceStepRelationController` | `ProduceStepRelationService` / `ProduceStepRelationDao` | `old/web/src/views/produce/step-relation` |
| 状态转换 | `produce_status_transition` | `ProduceStatusTransitionController` | `ProduceStatusTransitionService` / `ProduceStatusTransitionDao` | `old/web/src/views/produce/status-transition` |
| 转换日志 | `produce_transition_log` | `ProduceTransitionLogController` | `ProduceTransitionLogService` / `ProduceTransitionLogDao` | `old/web/src/views/produce/transition-log` |

## 5. 模块依赖关系

这 6 个模块存在清晰的业务依赖链：

1. `process`
2. `process-step` 依赖 `process`
3. `step-status` 依赖 `process-step`
4. `step-relation` 依赖 `process-step`
5. `status-transition` 依赖：
   - `process-step`
   - `step-status`
6. `transition-log` 依赖：
   - `process-step`
   - `step-status`
   - `status-transition`
   - 生产执行侧产生的数据

推荐开发顺序必须遵循该依赖链。

## 6. 六模块详细分析

### 6.1 工序管理 `process`

#### 6.1.1 旧前端参考

目录：`old/web/src/views/produce/process`

查询字段：

- `LIKE_process_code`
- `LIKE_process_name`
- `status`

列表字段：

- `process_code`
- `process_name`
- `description`
- `step_count`
- `sort`
- `status`
- `created_date`

表单字段：

- `process_code`
- `process_name`
- `sort`
- `status`
- `description`

#### 6.1.2 旧后端模型字段

模型：`old/server/app/common/model/produce/ProduceProcess.php`

真实字段：

- `id`
- `tenant_id`
- `process_code`
- `process_name`
- `description`
- `sort`
- `status`
- `step_count`
- `created_by`
- `updated_by`
- `created_at`
- `updated_at`
- `deleted_at`

关系：

- `steps()` -> `hasMany(ProduceProcessStep::class)`

特殊点：

- `step_count` 在模型中带有自动统计能力，不只是纯存储字段。

#### 6.1.3 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_process`

关键约束：

- 唯一索引：`uk_process_code(process_code, tenant_id, deleted_at)`
- 常规索引：`tenant_id`、`status`、`sort`

#### 6.1.4 复杂度评估

- 复杂度：低
- 适合作为第一个落地模块

#### 6.1.5 新插件建议

模块名建议：`process`

后端应提供：

- 标准 CRUD
- 下拉接口 `select/options`

前端建议：

- 标准 `BasicCrud`
- 保留查询项与排序、状态字段

---

### 6.2 工序步骤 `process-step`

#### 6.2.1 旧前端参考

目录：`old/web/src/views/produce/process-step`

查询字段：

- `process_id`
- `LIKE_step_code`
- `LIKE_step_name`
- `status`

列表字段：

- `process_id`（实际显示工序名称）
- `step_code`
- `step_name`
- `description`
- `sort`
- `status`
- `created_date`

表单字段：

- `process_id`
- `step_code`
- `step_name`
- `sort`
- `status`
- `description`

#### 6.2.2 旧后端模型字段

模型：`old/server/app/common/model/produce/ProduceProcessStep.php`

真实字段：

- `id`
- `tenant_id`
- `process_id`
- `step_code`
- `step_name`
- `description`
- `sort`
- `status`
- `prerequisite_steps`
- `prerequisite_mode`
- `prerequisite_require_final`
- `allow_repeat_scan`
- `repeat_scan_statuses`
- `created_by`
- `updated_by`
- `created_at`
- `updated_at`
- `deleted_at`

casts：

- `prerequisite_steps` => `array`
- `repeat_scan_statuses` => `array`
- `allow_repeat_scan` => `integer`
- `prerequisite_require_final` => `integer`

关系：

- `process()` -> `belongsTo(ProduceProcess::class)`

#### 6.2.3 旧前端与真实后端差异

旧前端页面只展示了基础字段，但后端模型里还有生产执行相关能力字段：

- 前置必要步骤
- 前置步骤验证模式
- 是否要求前置终态
- 是否允许重复扫码
- 哪些状态允许重复扫码

这说明：

- 如果只按旧页面复刻，会丢失隐藏业务能力
- 新插件应优先保留这些字段，只是可以分阶段决定首版是否全部开放 UI

#### 6.2.4 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_process_step`

关键约束：

- 唯一索引：`uk_step_code(step_code, process_id, tenant_id, deleted_at)`
- 常规索引通常包括：`tenant_id`、`process_id`、`status`、`sort`

#### 6.2.5 复杂度评估

- 复杂度：中
- 依赖 `process`
- 基础 CRUD 不复杂，但完整业务字段不应忽略

#### 6.2.6 新插件建议

模块名建议：`process-step`

建议分两阶段：

第一阶段：

- 工序下拉
- 步骤编码/名称
- 排序/状态/描述

第二阶段：

- 前置步骤配置
- 重复扫码控制

---

### 6.3 步骤状态 `step-status`

#### 6.3.1 旧前端参考

目录：`old/web/src/views/produce/step-status`

查询字段：

- `step_id`
- `LIKE_status_code`
- `LIKE_status_name`
- `status`

列表字段：

- `step_id`（显示步骤名称）
- `status_code`
- `status_name`
- `is_initial`
- `is_final`
- `description`
- `sort`
- `status`
- `created_date`

表单字段：

- `step_id`
- `status_code`
- `status_name`
- `is_initial`
- `is_final`
- `sort`
- `status`
- `description`

#### 6.3.2 旧后端模型字段

模型：`old/server/app/common/model/produce/ProduceStepStatus.php`

真实字段：

- `id`
- `tenant_id`
- `step_id`
- `status_code`
- `status_name`
- `is_initial`
- `is_final`
- `description`
- `sort`
- `status`
- `created_by`
- `updated_by`
- `created_at`
- `updated_at`
- `deleted_at`

关系：

- `step()` -> `belongsTo(ProduceProcessStep::class)`

#### 6.3.3 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_step_status`

典型业务含义：

- `is_initial`：步骤初始状态
- `is_final`：步骤终态

这是状态机基础数据，不应简化掉。

#### 6.3.4 复杂度评估

- 复杂度：中
- 依赖 `process-step`
- 是状态转换模块的基础配置表

#### 6.3.5 新插件建议

模块名建议：`step-status`

建议保留：

- 所属步骤联动下拉
- 初始/终态布尔字段
- 基础启停状态

---

### 6.4 步骤关系 `step-relation`

#### 6.4.1 旧前端参考

目录：`old/web/src/views/produce/step-relation`

查询字段：

- `from_step_id`
- `to_step_id`
- `relation_type`
- `status`

列表字段：

- `from_step_id`（显示源步骤名称）
- `to_step_id`（显示目标步骤名称）
- `relation_type`
- `priority`
- `flow_condition`
- `description`
- `sort`
- `status`
- `created_date`

表单字段：

- `from_step_id`
- `to_step_id`
- `relation_type`
- `priority`
- `flow_condition`
- `sort`
- `status`
- `description`

关系类型枚举：

- `normal` 正常流转
- `exception` 异常流转

#### 6.4.2 旧后端模型 / DAO 参考

模型：`ProduceStepRelation`

真实表：`produce_step_relation`

DAO：`ProduceStepRelationDao`

体现出的真实业务能力：

- 支持按 `from_step_id` / `to_step_id` / `relation_type` 搜索
- 支持按 `priority asc, sort asc` 排序
- 提供 `getPreviousSteps(int $currentStepId)` 能力

这说明该模块不仅是配置关系，还直接用于生产流转路径判断。

#### 6.4.3 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_step_relation`

真实字段：

- `from_step_id`
- `to_step_id`
- `relation_type`
- `flow_condition`（JSON 文本）
- `priority`
- `description`
- `sort`
- `status`

#### 6.4.4 复杂度评估

- 复杂度：中偏高
- 核心复杂点在 `flow_condition`
- 仍可标准 CRUD 化

#### 6.4.5 新插件建议

模块名建议：`step-relation`

前端首版可先：

- 使用多行文本录入 JSON
- 列表中直接字符串展示

后续增强：

- JSON 校验
- 条件构造器 UI

---

### 6.5 状态转换 `status-transition`

#### 6.5.1 旧前端参考

目录：`old/web/src/views/produce/status-transition`

查询字段：

- `step_id`
- `trigger_event`
- `status`

列表字段：

- `step_id`
- `from_status_id`
- `to_status_id`
- `trigger_event`
- `transition_type`
- `auto_trigger`
- `priority`
- `description`
- `sort`
- `status`
- `created_date`

表单字段：

- `step_id`
- `from_status_id`
- `to_status_id`
- `trigger_event`
- `transition_type`
- `side_effect_type`
- `side_effect_config`
- `auto_trigger`
- `priority`
- `event_config`
- `sort`
- `status`
- `description`

触发事件枚举：

- `next_step_scan`
- `scan_trigger`
- `exception_trigger`
- `manual_trigger`
- `timer_trigger`
- `complete_trigger`

转换类型枚举：

- `primary`
- `side_effect`

副作用类型枚举：

- `log`
- `notify`
- `update_field`
- `trigger_event`

#### 6.5.2 旧后端模型 / DAO 参考

模型：`ProduceStatusTransition`

真实字段：

- `step_id`
- `from_status_id`
- `to_status_id`
- `trigger_event`
- `event_config`
- `auto_trigger`
- `priority`
- `transition_type`
- `side_effect_type`
- `side_effect_config`
- `description`
- `sort`
- `status`

关系：

- `step()`
- `fromStatus()`
- `toStatus()`

JSON 处理：

- `event_config` 自动 JSON 编解码
- `side_effect_config` 自动 JSON 编解码

DAO 体现出的业务能力：

- `getAutoTransitionsByStep(stepId, fromStatusId)`
- `getAutoTransitions(stepId, fromStatusId, triggerEvent)`

排序规则：

- `priority desc` / `sort asc`

说明：

- 该模块不只是配置表，而是生产执行流程中的规则引擎核心

#### 6.5.3 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_status_transition`

真实字段里已经明确包含：

- `transition_type`
- `side_effect_type`
- `side_effect_config`
- `event_config`

#### 6.5.4 复杂度评估

- 复杂度：高
- 是 6 个模块里最复杂的配置模块

复杂来源：

- 依赖步骤与步骤状态双层联动
- 表单中有条件显示字段
- 存在 JSON 配置字段
- 影响实际状态机执行逻辑

#### 6.5.5 新插件建议

模块名建议：`status-transition`

建议实现分两层：

第一层：

- 完整字段 CRUD
- 文本方式维护 JSON
- 步骤切换后刷新状态选项

第二层：

- JSON 结构校验
- 副作用配置器
- 事件配置器

---

### 6.6 转换日志 `transition-log`

#### 6.6.1 旧前端参考

目录：`old/web/src/views/produce/transition-log`

查询字段：

- `LIKE_work_order_no`
- `step_id`
- `trigger_event`
- `LIKE_trigger_user`
- `is_success`

列表字段：

- `work_order_no`
- `step_id`
- `from_status_id`
- `to_status_id`
- `trigger_event`
- `trigger_user`
- `is_auto`
- `is_success`
- `duration`
- `error_message`
- `created_date`

操作：

- 只有 `detail`

#### 6.6.2 旧后端模型 / Service 参考

模型：`ProduceTransitionLog`

真实字段：

- `work_order_id`
- `work_order_no`
- `step_id`
- `transition_id`
- `from_status_id`
- `to_status_id`
- `trigger_event`
- `trigger_data`
- `trigger_user`
- `trigger_ip`
- `is_auto`
- `is_success`
- `error_message`
- `duration`
- `remark`
- `created_by`
- `created_at`

特征：

- `UPDATED_AT = null`
- `trigger_data` 自动 JSON 解码
- 服务 `read()` 会加载：
  - `step`
  - `transition`
  - `fromStatus`
  - `toStatus`

旧路由里还存在额外查询接口：

- `work-order-history`
- `step-statistics`

说明：

- 该模块是典型只读日志模块
- 不适合做标准新增/编辑/删除页面

#### 6.6.3 SQL 参考

来源：`old/server/scripts/sql/install.sql`

表：`ma_produce_transition_log`

关键字段：

- `trigger_data` JSON
- `trigger_ip`
- `duration`
- `error_message`
- `remark`

#### 6.6.4 复杂度评估

- 复杂度：中
- 不是 CRUD 复杂，而是业务只读特征与统计扩展

#### 6.6.5 新插件建议

模块名建议：`transition-log`

实现建议：

- 列表页 + 详情页
- 默认只读
- 不开放新增/编辑/删除
- 后续可补：
  - 工单历史
  - 步骤统计

## 7. 推荐复刻顺序

必须按依赖顺序推进：

1. `process`
2. `process-step`
3. `step-status`
4. `step-relation`
5. `status-transition`
6. `transition-log`

推荐分阶段：

### 第一阶段：基础主数据

- `process`
- `process-step`
- `step-status`

### 第二阶段：流程规则

- `step-relation`
- `status-transition`

### 第三阶段：只读日志

- `transition-log`

## 8. 新插件目录落点建议

### 8.1 后端

建议新增如下结构：

- `backend/plugin/produce/app/model/Process.php` 等
- `backend/plugin/produce/app/dao/*`
- `backend/plugin/produce/app/service/admin/*`
- `backend/plugin/produce/app/validate/*`
- `backend/plugin/produce/app/schema/request/*`
- `backend/plugin/produce/app/schema/response/*`
- `backend/plugin/produce/app/adminapi/controller/*`
- `backend/plugin/produce/resource/database/migrations/*`

建议 6 模块一一对应生成：

- `Process`
- `ProcessStep`
- `StepStatus`
- `StepRelation`
- `StatusTransition`
- `TransitionLog`

### 8.2 前端模板源

正式维护目录必须放在：

- `backend/plugin/produce/resource/template/admin/api/index.ts`
- `backend/plugin/produce/resource/template/admin/views/produce/process/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/process/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/views/produce/process-step/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/process-step/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/views/produce/step-status/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/step-status/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/views/produce/step-relation/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/step-relation/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/views/produce/status-transition/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/status-transition/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/views/produce/transition-log/index.vue`
- `backend/plugin/produce/resource/template/admin/views/produce/transition-log/schemas/index.tsx`
- `backend/plugin/produce/resource/template/admin/lang/zh-cn/zh.json`
- `backend/plugin/produce/resource/template/admin/lang/en/en.json`

安装后再复制到：

- `frontend/admin/src/apps/produce/*`

## 9. 菜单与权限建议

当前插件菜单 `backend/plugin/produce/resource/menu/admin.php` 只有一个示例菜单项，不能满足这 6 个模块。

建议调整为：

- 根菜单：`生产管理`
- 子菜单：
  - `工序管理`
  - `工序步骤`
  - `步骤状态`
  - `步骤关系`
  - `状态转换`
  - `转换日志`

权限码建议统一前缀：

- `produce:process:*`
- `produce:process-step:*`
- `produce:step-status:*`
- `produce:step-relation:*`
- `produce:status-transition:*`
- `produce:transition-log:*`

注意：

- 日志模块建议只保留 `list/detail` 等只读权限
- 不建议给 `create/edit/delete`

## 10. 接口风格迁移建议

旧项目接口风格：

- `/admin/produce/process/list`
- `/admin/produce/process/get/{id}`
- `/admin/produce/process/create`
- `/admin/produce/process/update/{id}`
- `/admin/produce/process/delete/{id}`

新插件建议按当前项目标准 CRUD 控制器收敛，避免继续沿用旧式 `list/get/create/update/delete` 命名。

建议资源路径：

- `/adminapi/produce/process`
- `/adminapi/produce/process-step`
- `/adminapi/produce/step-status`
- `/adminapi/produce/step-relation`
- `/adminapi/produce/status-transition`
- `/adminapi/produce/transition-log`

附加只读接口可补：

- 下拉选项接口
- 状态联动接口
- 日志统计接口

## 11. 风险与注意事项

### 11.1 旧前端不等于真实后端能力

最典型的是 `process-step`：

旧页面未暴露：

- 前置步骤数组
- 前置验证模式
- 重复扫码控制

但后端模型与 SQL 已经存在这些字段。

结论：

- 不能只按旧页面抄字段
- 应优先以 SQL + Model 为准

### 11.2 `status-transition` 是规则引擎核心

该模块不是普通配置表，DAO 已体现真实执行用途：

- 获取自动转换规则
- 按优先级执行
- 依赖事件与状态

因此该模块开发时应把：

- 数据正确性
- JSON 配置合法性
- 联动逻辑

放在比页面美化更高的优先级。

### 11.3 `transition-log` 是只读模块

不要把它误做成标准增删改查。

推荐：

- 列表
- 详情
- 历史/统计扩展

### 11.4 迁移来源差异

旧项目这几张表的核心定义主要在 SQL 安装脚本，不在当前已检索到的 PHP migration 单文件中。

因此新插件开发时：

- 迁移文件需要重新按当前项目规范补建
- 不能直接依赖旧 `scripts/migrations` 目录复用
- 但可以严格参考 `install.sql` 的字段与索引

## 12. 推荐实施计划

### 12.1 第一批落地

先完成：

1. `process`
2. `process-step`
3. `step-status`

交付标准：

- 后端 CRUD 可运行
- 菜单可访问
- 模板源前端完成
- 运行目录联调通过

### 12.2 第二批落地

再完成：

4. `step-relation`
5. `status-transition`

重点：

- 规则字段
- JSON 输入
- 状态联动

### 12.3 第三批落地

最后完成：

6. `transition-log`

重点：

- 列表
- 详情
- 历史/统计接口是否保留

## 13. 待确认事项

正式开始开发前，建议你确认以下内容：

1. 插件显示名称是否确定为“生产管理”
2. 这 6 个模块是否全部进入一期
3. `process-step` 的隐藏字段是否一期就开放 UI
4. `status-transition` 的 JSON 字段是否先用文本方式维护
5. `transition-log` 是否确认只读
6. 是否要把旧路由里的 `select`、`statistics`、`work-order-history` 一并纳入一期
7. 数据库主键是否统一按当前项目雪花 ID 规范重建，而不是继续使用旧 AUTO_INCREMENT 风格

## 14. 结论

结论如下：

1. `produce` 插件当前只是骨架，无法直接承接旧功能。
2. 旧项目这 6 个模块具备完整前后端参考，可复刻。
3. 复刻时应以 `install.sql + Model + DAO/Service` 为准，不能只照搬旧页面字段。
4. 最推荐的首批实现是：
   - `process`
   - `process-step`
   - `step-status`
5. `status-transition` 是业务核心，复杂度最高，应在基础模块稳定后实现。
6. `transition-log` 应按只读日志模块实现，而不是标准 CRUD。