TJC.Cyclops.ApprovalFlow 2026.4.14.2

Cyclops.ApprovalFlow

🔄 灵活强大的审批流程引擎 🔄

Cyclops.ApprovalFlow 是企服版框架中的审批流开发套件，提供灵活、可扩展的工作流管理能力。该项目采用图论模型设计，通过节点和边的组合构建复杂的审批流程，支持多种节点类型和流转逻辑，为企业应用提供强大的业务流程管理支持。

🌟 核心特性

• 图式流程定义：基于图论的流程模型，通过节点和边的组合构建复杂审批流程
• 多样化节点类型：支持开始节点、任务节点、用户节点、网关节点、结束节点等多种节点类型
• 灵活的流转逻辑：支持条件流转、并行分支、串行审批等复杂流程场景
• 可视化流程设计：支持流程的可视化配置和管理
• 流程监控：实时监控流程执行状态和进度
• 自动推进机制：根据预设规则自动推进流程，提高审批效率
• 可扩展的节点处理器：支持自定义节点处理逻辑
• 完整的事件系统：提供流程生命周期事件，便于集成业务逻辑

🛠️ 技术栈

• 开发框架：.NET 8.0
• 项目类型：类库（Class Library）
• 核心依赖：
  • Cyclops.Common：提供通用工具类支持
  • Cyclops.DI：提供依赖注入能力

📦 安装

dotnet add package Cyclops.ApprovalFlow

🚀 快速开始

1. 从JSON文件加载流程定义

using Cyclops.ApprovalFlow;

// 创建流程构建器实例
var flowBuilder = new FlowBuilder();

// 从JSON文件加载流程定义
string jsonPath = "path/to/your/flowdefinition.json";
var executor = await flowBuilder.CreateExecutorFromJsonFileAsync(jsonPath);

2. 从JSON字符串加载流程定义

using Cyclops.ApprovalFlow;

// 创建流程构建器实例
var flowBuilder = new FlowBuilder();

// 流程定义JSON字符串
string flowJson = @"{
  ""key"": ""LeaveApprovalFlow",
  ""name"": ""请假审批流程",
  ""nodes"": [
    {
      ""id"": ""start",
      ""type"": ""start-node",
      ""text"": { ""value"": ""开始"" }
    },
    {
      ""id"": ""manager-approval",
      ""type"": ""user-node",
      ""text"": { ""value"": ""经理审批"" },
      ""properties"": {
        ""assignee"": ""manager"
      }
    },
    {
      ""id"": ""end",
      ""type"": ""end-node",
      ""text"": { ""value"": ""结束"" }
    }
  ],
  ""edges"": [
    {
      ""id"": ""edge1",
      ""sourceNodeId"": ""start",
      ""targetNodeId"": ""manager-approval",
      ""text"": { ""value"": ""提交"" }
    },
    {
      ""id"": ""edge2",
      ""sourceNodeId"": ""manager-approval",
      ""targetNodeId"": ""end",
      ""text"": { ""value"": ""通过"" }
    }
  ]
}";

// 从JSON字符串加载流程定义
var executor = await flowBuilder.CreateExecutorFromJsonStringAsync(flowJson, "LeaveApprovalFlow");

3. 初始化并启动流程引擎

using Cyclops.ApprovalFlow;

// 初始化流程引擎
var flowEngine = FlowEngine.Instance;

// 启动流程引擎
flowEngine.Start();

// 在应用关闭时停止流程引擎并释放资源
// flowEngine.Dispose();

📖 使用指南

流程执行

using Cyclops.ApprovalFlow;

// 获取流程执行器
var flowBuilder = new FlowBuilder();
if (flowBuilder.TryGetExecutor("LeaveApprovalFlow", out var executor))
{
    // 创建流程实例
    var flowId = await executor.StartFlowAsync();
    Console.WriteLine($"流程已启动，ID: {flowId}");
    
    // 执行流程步骤
    var result = await executor.AdvanceFlowAsync(flowId, "manager-approval", new Dictionary<string, object>
    {
        { "approved", true },
        { "comment", "同意请假" }
    });
    
    // 检查流程状态
    if (result.IsCompleted)
    {
        Console.WriteLine("流程已完成！");
    }
}

流程监控

using Cyclops.ApprovalFlow;
using Cyclops.ApprovalFlow.Models;

// 注册流程事件监听器
FlowEngine.Instance.OnFlowStarted += (sender, e) => {
    Console.WriteLine($"流程 {e.FlowId} 已启动");
};

FlowEngine.Instance.OnFlowCompleted += (sender, e) => {
    Console.WriteLine($"流程 {e.FlowId} 已完成");
};

FlowEngine.Instance.OnFlowNodeCompleted += (sender, e) => {
    Console.WriteLine($"流程 {e.FlowId} 的节点 {e.NodeId} 已完成");
};

自定义节点处理器

using Cyclops.ApprovalFlow;
using Cyclops.ApprovalFlow.Core;

// 自定义节点处理器
public class CustomNodeHandler : IFlowNodeHandler
{
    public async Task<FlowStepResult> HandleAsync(FlowNodeHandleContext context)
    {
        // 处理节点逻辑
        Console.WriteLine($"处理节点: {context.Node.Id}");
        
        // 模拟处理时间
        await Task.Delay(1000);
        
        // 返回处理结果
        return new FlowStepResult
        {
            Success = true,
            OutputData = new Dictionary<string, object>
            {
                { "processedBy", "CustomHandler" },
                { "processedAt", DateTime.Now }
            }
        };
    }
}

// 注册自定义处理器
FlowBuilder.RegisterNodeHandler("custom-node", typeof(CustomNodeHandler));

🔧 配置说明

流程定义JSON结构

{
  "key": "流程唯一标识",
  "name": "流程名称",
  "nodes": [
    {
      "id": "节点ID",
      "type": "节点类型",
      "text": { "value": "节点显示文本" },
      "properties": {
        "自定义属性1": "值1",
        "自定义属性2": "值2"
      }
    }
  ],
  "edges": [
    {
      "id": "边ID",
      "sourceNodeId": "源节点ID",
      "targetNodeId": "目标节点ID",
      "text": { "value": "边显示文本" },
      "properties": {
        "condition": "流转条件表达式"
      }
    }
  ]
}

📋 支持的节点类型

• start-node：开始节点，流程的起点
• user-node：用户节点，需要用户参与的审批节点
• task-node：任务节点，自动执行的任务
• gateway-node：网关节点，用于分支和合并
• end-node：结束节点，流程的终点

⚠️ 使用注意事项

1. 流程定义格式：确保流程定义JSON符合GraphFlowDefinition的数据结构要求，特别是节点和边的ID必须唯一且相互匹配
2. 节点类型选择：根据业务需求选择适当的节点类型，如开始节点(start-node)、任务节点(task-node)、用户节点(user-node)、网关节点(gateway-node)和结束节点(end-node)等
3. 资源管理：使用完FlowEngine后，务必调用Dispose()方法释放资源，避免内存泄漏
4. 错误处理：加载流程定义时可能会抛出异常，请确保添加适当的错误处理逻辑
5. 并发安全：在多线程环境下使用FlowBuilder和FlowEngine时，请注意线程安全问题
6. 流程版本管理：对于需要频繁变更的流程，建议实现版本管理机制，确保流程定义的可追溯性
7. 性能优化：对于大量流程实例的场景，可以考虑优化线程池配置和定期清理过期的流程实例

🤝 贡献

我们欢迎社区贡献！如果您有任何想法或建议，欢迎提交 Issue 或 Pull Request。

📄 许可证

MIT License

Cyclops.ApprovalFlow - 让审批流程管理变得简单高效，为企业业务流程赋能！✨