Skip to content

About

Ingenious v3:A lightweight workflow engine library for the Madong Admin ecosystem, framework-agnostic, not a plugin, supports both single-tenant and multi-tenant SaaS backends.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

161 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Madong Workflow(Ingenious v3)

Ingenious v3 工作流引擎 | PHP 8.1+ | 包名:madong/workflow | 命名空间:madong\workflow

当前为 v3(包名 madong/workflow);v1(madong/ingenious)与 v2 为历史版本,早期仓库路径 ingenstream/ingenious,已停止演进。

仓库位置

平台 定位 地址
GitHub 主仓库 github.com/madong-code/workflow-engine
Gitee 镜像 gitee.com/motion-code/workflow-engine
GitCode 镜像 gitcode.com/motion-code/workflow-engine

Composer VCS 安装以 GitHub 主仓库为默认源,Gitee / GitCode 镜像可在网络受限时替换 repositories.url。

Madong Workflow(Ingenious v3)是一套基于 PHP 8.1+ OOP 设计的轻量、可扩展工作流引擎(演进自 Ingenious,命名空间与包名已独立)。它能够解析流程设计器导出的 json 流程定义并驱动流程流转,支持决策分支、并行合并、会签、自定义节点、事件、拦截器、模块化、子流程等能力。

✨ 特性

  • 设计器驱动:解析 LogicFlow 设计器导出的 json 流程定义,无需手写建模
  • 节点丰富:开始 / 结束 / 任务 / 决策 / 并行分支 / 合并 / 自定义 / 子流程
  • 会签支持:并行 / 串行会签,多实例任务与完成条件(#nrOfCompletedInstances==N)
  • 条件路由:#变量 / ${变量} 决策表达式,自动分支路由
  • 拦截器体系:节点拦截器 + AOP 流程拦截器(Aspect)
  • 事件驱动:EventBus 发布/订阅,流程生命周期事件
  • 模块化:Module 插拔扩展(依赖拓扑排序)
  • 服务可替换:通过 I*Service 接口对接任意持久化实现
  • 开箱即用:内存服务 + 真实流程 json 集成测试(86 tests / 184 assertions)
  • 可运行 Demo:内置流程中心完整示例(PDO + 原生 SQL + 原生 PHP,零构建链依赖,FPM 直部)

🎯 Demo 示例

demo/ 目录提供一个开箱即跑的流程中心完整示例:PDO + 原生 SQL 存储层、原生 PHP REST API、iframe 嵌 visual-flow 设计器(画布/钉钉双模式),页面布局对标 jeeflow 演示(顶栏 + 左侧菜单 + 右侧详情抽屉)。覆盖工作台、发起申请、待办/已办/抄送、流程定义与设计、审批委托、流程监控等完整场景,内置 5 条种子流程(请假 / 差旅报销 / 会签 / 并行分支 / 自定义节点)。

运行方式(均为请求级执行,无常驻进程依赖):

# 方式一:PHP 内置服务器(本地开发)
php -S 127.0.0.1:8100 -t . demo/public/index.php
# 浏览器打开 http://127.0.0.1:8100/

# 方式二:php-fpm + nginx(部署)
# 配置模板见 demo/config/nginx.conf.example:
# root 指向包根,/assets/* 静态直出,其余请求转发 demo/public/index.php 前端控制器

数据库连接通过 demo/config/.env 配置(模板 .env.example),首次访问自动建表并写入种子数据。冒烟测试与功能清单详见 demo/README.md(php demo/tests/smoke.php,38 条断言)。

📦 安装

本包未发布到 Packagist,需在项目 composer.json 中配置 VCS 仓库后安装:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://gitee.com/motion-code/workflow-engine.git"
        }
    ],
    "require": {
        "madong/workflow": "^3.0"
    }
}

镜像源(网络受限时替换上方 repositories.url):"url": "https://gitee.com/motion-code/workflow-engine.git" 或 "url": "https://gitcode.com/madong-code/workflow-engine.git"

composer update madong/workflow

历史版本:madong/ingenious(v1,旧命名空间 madong\ingenious\*)与 v2 均在早期仓库 ingenstream/ingenious,VCS url 指向该仓库可继续安装旧版;迁移到 v3 需将代码引用替换为 madong\workflow\*。

本地开发可将源码放在 packages/workflow,用 {"type": "path", "url": "./packages/workflow"} 仓库替代(path 优先级高于 vcs)。

环境要求

项目 要求
PHP ^8.1(readonly、enum、命名参数)
Composer 2.x
依赖 php-di/php-di ^7.0、madong/helper ^1.0、monolog/monolog ^2.0|^3.0

🚀 快速开始

use madong\workflow\Engine;
use madong\workflow\config\EngineConfig;
use madong\workflow\interface\services\{
    IProcessDefineService,
    IProcessInstanceService,
    IProcessTaskService,
};

// 1. 创建引擎
$engine = new Engine(new EngineConfig(
    services: [
        IProcessDefineService::class   => \App\Service\ProcessDefineService::class,
        IProcessInstanceService::class => \App\Service\ProcessInstanceService::class,
        IProcessTaskService::class     => \App\Service\ProcessTaskService::class,
    ],
    debug: true,
));

// 2. 发布流程定义
$defineService = $engine->getService(IProcessDefineService::class);
$defineService->createProcessDefine([
    'id'      => 'leave_001',
    'name'    => 'wf-leave',
    'content' => $jsonContent, // 流程定义 json 字符串
]);

// 3. 启动流程
$instance = $engine->startProcess('leave_001', 'user001', ['f_day' => 3]);

// 4. 完成任务
$taskService = $engine->getService(IProcessTaskService::class);
$tasks = $taskService->getDoingTaskList($instance->getId(), '');
$engine->completeTask($tasks[0]->getId(), 'user001', ['approved' => true]);

🧩 核心概念

概念 说明
流程定义 (ProcessDefine) 设计器导出的 json「图纸」
流程模型 (ProcessModel) 解析后的可执行对象模型
流程实例 (ProcessInstance) 一次具体的流程执行
节点 (NodeModel) 流程步骤(任务/判断/分支等)
边 (TransitionModel) 节点间流转,可带条件表达式
任务 (ProcessTask) 推进到任务节点产生的待办

📐 流程定义规范

流程定义统一 snake_case 字段命名,8 种节点类型(ingenious:start/end/task/decision/fork/join/custom/wfSubProcess)。

类名引用(clazz/assignment_handler/拦截器)使用点号形式(json 不允许 \),引擎自动转为命名空间:

{
  "name": "wf-leave",
  "display_name": "请假流程",
  "instance_url": "leaveForm",
  "nodes": [
    {
      "id": "approve",
      "type": "ingenious:task",
      "text": { "value": "部门审批" },
      "properties": {
        "assignee": "${manager}",
        "task_type": "Major",
        "perform_type": "ANY"
      }
    }
  ],
  "edges": []
}

🧰 扩展点

扩展点 机制
自定义节点 clazz 外部类,结果写回 var(类不存在时安全降级)
节点拦截器 pre_interceptors / post_interceptors
AOP 切面 实现 Aspect,按 JoinPoint 织入
事件监听 实现 ProcessEventListener,订阅 EventBus
模块 实现 Module(register/boot/shutdown,依赖排序)
新节点类型 NodeParser + NodeModel + Handler
第三方设计器 实现 DesignerParserInterface

🧪 测试

vendor/bin/phpunit --no-coverage
PHPUnit 10.5.x
OK (86 tests, 184 assertions)
  • 单元测试:tests/unit/
  • 集成测试:tests/integration/engine/(含 5 个真实流程 json + 模块集成)
  • 内存服务:tests/fixture/memory/
  • 自定义类:tests/fixture/handler/、tests/fixture/modular/
  • 流程定义归档:tests/process/

📚 文档

完整索引见 docs/README.md。

文档 说明
docs/02-引擎API.md Engine 全部公开方法
docs/03-流程定义.md 流程定义 json 规范
docs/01-快速开始.md 最小可运行示例
docs/13-实现指南.md 服务实现与扩展
docs/14-框架基础.md 容器/AOP/事件/模块/表达式

宿主集成参考:MDAdmin 的 workflow 插件(plugin/workflow)已实现全部 15 个服务接口(MySQL 持久化 + 调度 + 消息推送),可作为生产级实现范例。

📄 License

Apache-2.0

About

Ingenious v3:A lightweight workflow engine library for the Madong Admin ecosystem, framework-agnostic, not a plugin, supports both single-tenant and multi-tenant SaaS backends.

Topics

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages