economic_crime/docs/工作流定义.md

该项目集成的是国产轻量级工作流引擎 WarmFlow。整个工作流机制的定义和使用方式如下：

---

一、 核心概念与数据模型

在项目中，流程模块主要围绕以下核心概念展开（在 net.lab1024.sa.admin.module.flow 目录下）：

概念	对应 WarmFlow 实体类	说明
流程定义	Definition / FlowDefinition	流程图的物理定义（模版），包括流程编码 (flowCode)、绑定的自定义表单路径 (formPath) 等。
流程实例	Instance / FlowInstance	用户发起审批后，由流程定义生成的一条具体流转实例。关联了具体的业务单据 ID (businessId)。
待办任务	Task / FlowTask	流程实例流转到的当前审批节点，包含当前审批人、审批权限等。
历史任务	HisTask / FlowHisTask	已经审批通过或被退回的历史流转记录。

---

二、 流程定义是如何使用的

流程定义的管理和检索通过 FlowDefinitionService 和 DefService 来实现：

1. 模版设计与部署：流程定义在后台由管理员进行设计并发布，产生版本号 (version)。
2. 表单关联：流程定义会关联一个 formPath（前端表单路径），用于指定该流程在流转时展示何种表单页面（例如请假单或报销单）。
3. 流程检索：在发起流程时，前端通过定义列表查询可用的流程，根据 flowCode 匹配需要启用的工作流。

---

三、 怎么在项目中使用和流转流程

业务系统（例如 OA 请假、财务报销）与工作流引擎是通过 “业务 ID (businessId) + 流程变量” 进行解耦和联动的。具体流程流转过程如下：

sequenceDiagram
    participant Front as 前端页面
    participant Controller as ExecuteController
    participant Service as FlowTaskService
    participant WarmFlow as WarmFlow引擎 (InsService/TaskService)

    Note over Front, WarmFlow: 1. 发起/启动流程
    Front->>Controller: 提交表单 (包含业务主键 businessId & flowDefinitionId)
    Controller->>Service: 调用 startWorkFlow
    Service->>WarmFlow: insService.start(businessId, flowParams)
    WarmFlow-->>Front: 流程实例启动成功

    Note over Front, WarmFlow: 2. 审批与流转
    Front->>Controller: 办理/审批任务 (/completeTask 传入 taskId, 审批意见, 变量)
    Controller->>Service: 调用 completeTask
    Service->>WarmFlow: taskService.skip(taskId, flowParams)
    WarmFlow-->>Front: 任务流转至下一节点/完成

1. 发起/启动工作流

当用户填写完业务表单（例如保存了一张请假单，生成了请假单主键 leaveId）并点击“提交申请”时，前端会请求 /flow/execute/startWorkFlow 接口：

• 后端获取对应的流程定义，调用 insService.start(String.valueOf(businessId), flowParams) 启动该实例。
• 此时，流程实例会与当前业务 ID 绑定，并进入流程的第一个审批节点。

2. 查询我的待办和已办

• 待办任务（/flow/execute/toDoPage）： 系统根据当前登录用户的 employeeId（用户 ID）、roleId（角色 ID）、deptId（部门 ID）组合成权限标识链，去 taskService 中检索指派给当前用户处理的 Task 列表。
• 已办任务（/flow/execute/donePage）： 去历史表查询当前用户审批过的所有任务记录。

3. 审批与流转（同意、驳回、退回）

当审批人打开审批页面，进行“同意”或“驳回”操作时，前端会请求 /flow/execute/completeTask 接口：

• 后端提取表单传入的 taskId（任务 ID）、targetNodeCode（目标节点编码）、以及流程变量（如审批动作是同意还是拒绝）。
• 通过调用 WarmFlow 核心的 taskService.skip(taskId, flowParams)，推进流程走向下一个节点（或结束流程）。

4. 高级交互干预

工作流还提供了一些干预接口（在 ExecuteController 中）：

• 转办 (Transfer)：将当前任务交给其他人审批。
• 委托 (Depute)：委托他人代办。
• 加签 / 减签 (Add/Reduction Signature)：在当前审批环节增加或减少审批人。