培训系统
编辑 | blame | 历史 | 原始文档

jnpf-flow-engine — JNPF 独立流程引擎（自有源码重建工程）

JNPF 独立流程引擎 jnpf-workflow-admin 的**自有源码**版本。由黑盒发行 jar
（jnpf-workflow-admin-1.0.0-RELEASE.jar，无源码）反编译还原（2026-07-17，任务 B），
实现"引擎侧 bug 可修、Flowable 版本可升"。

这是什么

黑盒引擎 = 官方 Flowable 7.0.1 + 极少量 JNPF 定制。反编译确认定制仅 42 个自有类：

层 类 说明
启动 JnpfFlowableApplication 标准 @SpringBootApplication
REST 控制器 admin/controller/{Definition,Instance,Task}Controller /api/Flow/* 共 27 端点
响应/异常 admin/result/Result、admin/handle/GlobalExceptionHandler 统一 {success,code,msg,data} 包装
服务实现 flowable/service/{Definition,Instance,Task}ServiceImpl 调 Flowable 引擎 API
拓扑工具 flowable/util/FlowableUtil、flowable/cmd/JumpCmd BPMN 图推导 + 自定义节点跳转命令
契约模型 common/model/fo/*（14 个）、common/model/vo/*（9 个） 请求/响应对象
契约接口 common/service/I{Definition,Instance,Task}Service
枚举/异常/工具 common/exception/{ResultCode,BizException}、common/util/FlowUtil
Liquibase 补丁 liquibase/snapshot/JdbcDatabaseSnapshot 达梦 DM8 表快照适配，仅 jdbc:dm 连接串生效

liquibase/snapshot/JdbcDatabaseSnapshot 是官方 liquibase-core 4.27.0 同名类的 JNPF 补丁版
（覆盖 classpath 里的官方类）：给达梦 DM8 增加 queryDM() 表清单查询 + escapeForLike/getTables
分支。现交付库是 PostgreSQL 用不到此路径，但**逐行保真保留**以维持 100% 等价（切达梦库零改动）。
本工程用官方 4.27.0 源码为底、仅打这 3 处 DM 补丁（见文件内 JNPF 补丁 注释）。

HTTP 契约（不可变）

/api/Flow/* 27 端点与黑盒 jar 契约兼容，调用方 = jnpf-flowable 的 FlowAbleUrl（唯一调用方）。
兼容边界（见验证）：success/code/data 三字段逐字节一致；**唯一例外**是 move 系列参数校验的
多字段错误 msg 拼接顺序（Bean Validation 对约束违反集合的遍历序未定义、跨编译不保证稳定），
但调用方只判 success/code、不解析该 msg，故不影响契约。关键约束：
- Result.success 是 Boolean（调用方判 Boolean.FALSE.equals(getSuccess())）
- Result.code 是 String（成功 = "200"，勿写数字）
- 引擎**不校验 token**（无 Sa-Token filter），调用方透传 Authorization 头但引擎忽略——勿加鉴权

构建

独立 Spring Boot 3.3.2 / JDK 21 工程，**不挂主仓父 POM**（主仓是 Spring Cloud/JDK 8 体系，不同源）。

mvn -f jnpf-flow-engine/pom.xml clean package -DskipTests
# 产物：jnpf-flow-engine/target/jnpf-workflow-admin-1.0.0-RELEASE.jar

依赖版本与黑盒 jar 逐项对齐（Spring Boot 3.3.2、Flowable 7.0.1、knife4j 4.5.0、hutool 5.8.27、
postgresql 42.6.2、五家数据库驱动 + protobuf）。构建产物依赖清单与黑盒 jar 仅差 3 项：
2 个 JNPF 定制 jar（已展开为本工程源码）+ lombok（compile-only，正确排除）。

部署（容器）

镜像工程在 docker/flow-engine/。prepare-context.sh 取源优先级：
1. FLOWAPI_JAR 环境变量显式指定
2. 本工程 jnpf-flow-engine/target/ 的构建产物（默认）
3. 黑盒原件 ~/Infra/jnpf/flowApi/（回滚锚点）

mvn -f jnpf-flow-engine/pom.xml clean package -DskipTests
docker compose build jnpf-flow-engine && docker compose up -d jnpf-flow-engine

回滚到黑盒（必须显式，脚本不再自动降级）：
FLOWAPI_JAR=~/Infra/jnpf/flowApi/jnpf-workflow-admin-1.0.0-RELEASE.jar ./docker/flow-engine/prepare-context.sh。

回归测试

test/ 下两个脚本固化了 A/B 验证，改引擎后重跑即可：
- test/contract-smoke.sh [base]：27 端点错误码/空数据断言；新旧引擎各跑一遍 diff = 契约字节对比
- test/lifecycle.sh [base] [tag]：deploy→start→next→complete→back(JumpCmd)→historic→delete 全生命周期，
抽 taskKey/code/name 骨架 A/B diff（覆盖状态机写路径）

验证（2026-07-17 已过）

  • 27 项契约响应 A/B 对比：26 逐字节一致；唯一差异 = move 校验多字段错误 msg 拼接顺序
    （Bean Validation 约束集合遍历序未定义、跨编译不保证；调用方只判 success/code 不解析 msg，非契约）
  • 完整生命周期 A/B（deploy→start→next→complete→back(JumpCmd 节点跳转)→historic→delete）
    语义骨架逐行一致
  • 自建镜像容器 healthy，全栈 16 容器启动，jnpf-flowable 日志无"流程引擎异常"

许可

JNPF 商业授权客户对自有部署做等价重建属维护行为；**产物不外发/不开源**。