sc-lktx-mp/sc-lktx-backend/docs/easy-workflow.md

Easy-Workflow 工作流框架使用指南

概述

本项目已集成 easy-workflow 工作流框架，支持可视化的流程编排和灵活的审批流管理。

核心概念

1. 流程定义 (ProcessDefinition)

流程定义是工作流的模板，描述了一个完整的审批流程结构。

数据结构：

{
  "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 接口

流程定义管理

# 创建流程定义
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

流程实例管理

# 启动流程实例
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

任务管理

# 获取待办任务
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}

支持功能：

• 查看审批进度时间线
• 查看每个节点的审批意见
• 执行审批操作

代码示例

发起审批流程

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
  }
})

获取待办任务

// 获取我的待办
const tasks = await workflowAPI.getPendingTasks()

// 遍历处理
tasks.forEach(task => {
  console.log(`${task.node_name} - ${task.instance?.process_def?.process_name}`)
})

审批操作

// 审批通过
await workflowAPI.approveTask(taskId, '同意申请')

// 审批拒绝
await workflowAPI.rejectTask(taskId, '拒绝，资料不全')

高级特性

1. 条件网关

{
  "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. 并行网关

{
  "node_id": "GW-Parallel",
  "node_name": "并行审批",
  "node_type": 2,
  "gw_config": {
    "inevitable_nodes": ["HR", "DeputyBoss"],
    "wait_for_all_prev_node": 1
  }
}

3. 会签节点

{
  "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：修改业务代码

将原有的审批逻辑改为调用工作流引擎：

// 旧代码
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 内容）

[
  {"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）

当未匹配到员工或部门未配置审批人时使用：

[
  {"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"]}
]

技术支持

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