359 lines
7.9 KiB
Markdown
359 lines
7.9 KiB
Markdown
# Easy-Workflow 工作流框架使用指南
|
||
|
||
## 概述
|
||
|
||
本项目已集成 easy-workflow 工作流框架，支持可视化的流程编排和灵活的审批流管理。
|
||
|
||
## 核心概念
|
||
|
||
### 1. 流程定义 (ProcessDefinition)
|
||
|
||
流程定义是工作流的模板，描述了一个完整的审批流程结构。
|
||
|
||
**数据结构：**
|
||
```json
|
||
{
|
||
"process_name": "员工请假",
|
||
"process_code": "leave_request",
|
||
"source": "办公系统",
|
||
"nodes": [
|
||
{
|
||
"node_id": "Start",
|
||
"node_name": "请假申请",
|
||
"node_type": 0,
|
||
"user_ids": ["$starter"],
|
||
"roles": []
|
||
},
|
||
{
|
||
"node_id": "Manager",
|
||
"node_name": "主管审批",
|
||
"node_type": 1,
|
||
"prev_node_ids": ["Start"],
|
||
"roles": ["主管"],
|
||
"is_cosigned": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 2. 节点类型 (NodeType)
|
||
|
||
- **0 - 开始节点**：流程的起点
|
||
- **1 - 审批节点**：需要人工审批的节点
|
||
- **2 - 网关节点**：条件分支或并行分支
|
||
- **3 - 结束节点**：流程终点
|
||
|
||
### 3. 流程实例 (ProcessInstance)
|
||
|
||
每次发起审批时创建的实例，关联具体的业务数据。
|
||
|
||
### 4. 任务 (Task)
|
||
|
||
每个审批节点会生成一个或多个待办任务，分配给具体的处理人。
|
||
|
||
## API 接口
|
||
|
||
### 流程定义管理
|
||
|
||
```bash
|
||
# 创建流程定义
|
||
POST /api/v1/workflow/definitions
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"process_name": "访客预约审批",
|
||
"process_code": "visitor_approval",
|
||
"source": "访客系统",
|
||
"nodes_json": "[...]"
|
||
}
|
||
|
||
# 获取流程定义列表
|
||
GET /api/v1/workflow/definitions
|
||
|
||
# 获取流程定义详情
|
||
GET /api/v1/workflow/definitions/:id
|
||
|
||
# 更新流程定义
|
||
PUT /api/v1/workflow/definitions/:id
|
||
|
||
# 删除流程定义
|
||
DELETE /api/v1/workflow/definitions/:id
|
||
```
|
||
|
||
### 流程实例管理
|
||
|
||
```bash
|
||
# 启动流程实例
|
||
POST /api/v1/workflow/instances
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"process_code": "visitor_approval",
|
||
"business_type": "appointment",
|
||
"business_id": 123,
|
||
"variables": {
|
||
"days": 3,
|
||
"reason": "商务拜访"
|
||
}
|
||
}
|
||
|
||
# 获取流程实例列表
|
||
GET /api/v1/workflow/instances?business_type=appointment&status=0
|
||
|
||
# 获取流程实例详情
|
||
GET /api/v1/workflow/instances/:id
|
||
```
|
||
|
||
### 任务管理
|
||
|
||
```bash
|
||
# 获取待办任务
|
||
GET /api/v1/workflow/tasks/pending
|
||
|
||
# 审批通过
|
||
POST /api/v1/workflow/tasks/:id/approve
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"comment": "同意"
|
||
}
|
||
|
||
# 审批拒绝
|
||
POST /api/v1/workflow/tasks/:id/reject
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"comment": "拒绝，原因：..."
|
||
}
|
||
```
|
||
|
||
## 前端使用
|
||
|
||
### 1. 流程设计器
|
||
|
||
访问路径：`/subpackages/admin/workflow-designer`
|
||
|
||
支持功能：
|
||
- 创建/编辑流程定义
|
||
- 添加/删除节点
|
||
- 配置节点类型和审批人
|
||
- 设置网关条件
|
||
|
||
### 2. 流程管理列表
|
||
|
||
访问路径：`/subpackages/admin/workflow-list`
|
||
|
||
支持功能：
|
||
- 查看所有流程定义
|
||
- 编辑/删除流程
|
||
- 查看流程实例
|
||
|
||
### 3. 我的待办
|
||
|
||
访问路径：`/subpackages/workflow/my-tasks`
|
||
|
||
支持功能：
|
||
- 查看待审批任务
|
||
- 快速审批通过/拒绝
|
||
|
||
### 4. 流程实例详情
|
||
|
||
访问路径：`/subpackages/admin/workflow-instance-detail?id={instanceId}`
|
||
|
||
支持功能：
|
||
- 查看审批进度时间线
|
||
- 查看每个节点的审批意见
|
||
- 执行审批操作
|
||
|
||
## 代码示例
|
||
|
||
### 发起审批流程
|
||
|
||
```typescript
|
||
import workflowAPI from '@/api/workflow'
|
||
|
||
// 发起访客预约审批
|
||
const instance = await workflowAPI.startInstance({
|
||
process_code: 'visitor_approval',
|
||
business_type: 'appointment',
|
||
business_id: appointmentId,
|
||
variables: {
|
||
visitDays: 3,
|
||
visitorCount: 5
|
||
}
|
||
})
|
||
```
|
||
|
||
### 获取待办任务
|
||
|
||
```typescript
|
||
// 获取我的待办
|
||
const tasks = await workflowAPI.getPendingTasks()
|
||
|
||
// 遍历处理
|
||
tasks.forEach(task => {
|
||
console.log(`${task.node_name} - ${task.instance?.process_def?.process_name}`)
|
||
})
|
||
```
|
||
|
||
### 审批操作
|
||
|
||
```typescript
|
||
// 审批通过
|
||
await workflowAPI.approveTask(taskId, '同意申请')
|
||
|
||
// 审批拒绝
|
||
await workflowAPI.rejectTask(taskId, '拒绝，资料不全')
|
||
```
|
||
|
||
## 高级特性
|
||
|
||
### 1. 条件网关
|
||
|
||
```json
|
||
{
|
||
"node_id": "GW-Day",
|
||
"node_name": "请假天数判断",
|
||
"node_type": 2,
|
||
"gw_config": {
|
||
"conditions": [
|
||
{
|
||
"expression": "$days >= 3",
|
||
"node_id": "Manager"
|
||
},
|
||
{
|
||
"expression": "$days < 3",
|
||
"node_id": "END"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 并行网关
|
||
|
||
```json
|
||
{
|
||
"node_id": "GW-Parallel",
|
||
"node_name": "并行审批",
|
||
"node_type": 2,
|
||
"gw_config": {
|
||
"inevitable_nodes": ["HR", "DeputyBoss"],
|
||
"wait_for_all_prev_node": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 会签节点
|
||
|
||
```json
|
||
{
|
||
"node_id": "Board",
|
||
"node_name": "董事会审批",
|
||
"node_type": 1,
|
||
"roles": ["董事 A", "董事 B", "董事 C"],
|
||
"is_cosigned": 1
|
||
}
|
||
```
|
||
|
||
## 数据库表结构
|
||
|
||
### wf_process_definitions
|
||
- 存储流程定义模板
|
||
- 节点配置以 JSON 格式存储
|
||
|
||
### wf_process_instances
|
||
- 存储流程实例
|
||
- 关联业务数据
|
||
- 记录当前节点
|
||
|
||
### wf_tasks
|
||
- 存储审批任务
|
||
- 记录处理人和审批意见
|
||
|
||
## 迁移现有审批逻辑
|
||
|
||
### 步骤 1：创建流程定义
|
||
|
||
使用流程设计器创建对应的流程模板。
|
||
|
||
### 步骤 2：修改业务代码
|
||
|
||
将原有的审批逻辑改为调用工作流引擎：
|
||
|
||
```go
|
||
// 旧代码
|
||
approvalHandler.StartInstance(...)
|
||
|
||
// 新代码
|
||
workflowEngine.StartInstance("visitor_approval", "appointment", appointmentID, userID, variables)
|
||
```
|
||
|
||
### 步骤 3：数据迁移
|
||
|
||
将现有的审批记录迁移到新的工作流表（可选）。
|
||
|
||
## 注意事项
|
||
|
||
1. **流程变量**：使用 `$` 前缀引用，如 `$days`
|
||
2. **角色解析**：审批人可以是具体用户 ID 或角色编码
|
||
3. **会签支持**：设置 `is_cosigned=1` 启用会签
|
||
4. **网关等待**：`wait_for_all_prev_node=1` 表示等待所有前置节点完成
|
||
|
||
## 常见问题
|
||
|
||
### Q: 如何添加自定义事件？
|
||
A: 在节点的 `node_start_events` 或 `node_end_events` 数组中添加事件名称。
|
||
|
||
### Q: 如何获取审批进度？
|
||
A: 调用 `GET /api/v1/workflow/instances/:id` 获取实例详情，包含所有任务记录。
|
||
|
||
### Q: 支持撤回吗？
|
||
A: 当前版本暂不支持，可在流程定义中配置 `revoke_events` 实现。
|
||
|
||
## 访客预约审批流程示例
|
||
|
||
### 流程定义（创建时 nodes_json 内容）
|
||
|
||
```json
|
||
[
|
||
{"node_id":"Start","node_name":"发起预约","node_type":0,"user_ids":["$starter"]},
|
||
{"node_id":"Employee","node_name":"公司接待员工","node_type":1,"prev_node_ids":["Start"],"user_ids":["$employee_id"]},
|
||
{"node_id":"DeptApprover","node_name":"部门指定人审批","node_type":1,"prev_node_ids":["Employee"],"user_ids":["$dept_approver_ids"]},
|
||
{"node_id":"VPApproval","node_name":"分管领导审批","node_type":1,"prev_node_ids":["DeptApprover"],"user_ids":["$vp_ids"]},
|
||
{"node_id":"End","node_name":"审批完成","node_type":3,"prev_node_ids":["VPApproval"]}
|
||
]
|
||
```
|
||
|
||
### 流程变量说明
|
||
|
||
| 变量名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| `$starter` | uint | 发起人的用户 ID（引擎自动填入） |
|
||
| `$employee_id` | uint | 被访员工用户 ID |
|
||
| `$dept_approver_ids` | JSON 数组 | 部门指定审批人 ID 列表，支持多人 |
|
||
| `$vp_ids` | JSON 数组 | 分管领导 ID 列表，支持多人，空数组跳过节点 |
|
||
|
||
### 行为规则
|
||
|
||
- **`$dept_approver_ids` 为空**：跳过「部门指定人审批」节点
|
||
- **`$vp_ids` 为空**：跳过「分管领导审批」节点
|
||
- **`$default_approver_ids` 为空**：跳过「兜底审批」节点，流程直接结束
|
||
- **多个审批人**：会签模式，需全部通过才流转下一节点
|
||
|
||
### 兜底审批流程定义（visitor_approval_simple）
|
||
|
||
当未匹配到员工或部门未配置审批人时使用：
|
||
|
||
```json
|
||
[
|
||
{"node_id":"Start","node_name":"发起预约","node_type":0,"user_ids":["$starter"]},
|
||
{"node_id":"DefaultApproval","node_name":"兜底审批","node_type":1,"prev_node_ids":["Start"],"user_ids":["$default_approver_ids"],"is_cosigned":1},
|
||
{"node_id":"End","node_name":"审批完成","node_type":3,"prev_node_ids":["DefaultApproval"]}
|
||
]
|
||
```
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请联系开发团队或查看示例代码。
|