# 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"]}
]
```

## 技术支持

如有问题，请联系开发团队或查看示例代码。