Files
eip4-platform/flowable-service/P3流程服务实测报告.md
zhengwr 6ced9b15f2 P3-1/2: 新建 flowable-service 独立工作流服务 + 移植 3 个表达式 handler
- 新模块 flowable-service(单客户交付四进程之一,可执行 jar,端口 8089):
  Flowable 6.8.1 引擎(连 eip4flow.eip3,databaseSchemaUpdate=false 严禁自动改表)
  + v5 兼容层 + 双数据源(ACT_ 本地 + 业务组织库客户库只读)
- 3 个 handler 按原包名移植经 cfg.setBeans 注册:CandidateUsersHandler(4761 处)/
  MultiInstanceUsersHandler(33 处会签)/WfContextService(175 处)
- 组织服务全闭包裁剪为 OrgDirectory 窄接口 + OrgDirectoryJdbc 直查业务组织库 SQL
  (逐条对齐 framework AssignmentHandlerImpl/UserFindServiceImpl/OrganizationServiceImpl),
  不拖入保真层元数据引擎;OSGi 取 bean → WfBeanRegistry(§3.1/§5.17 替换类策略);
  com.dsasp.* 零反向依赖 com.eip4(ArchUnit 纪律保持)
- REST 薄封装:待办/已办/发起/办理/挂起激活/委托 + OpenAPI;挂起拒办映射 409
- 26 单测绿;全反应堆 mvn test + ArchUnit 绿
- 实测验证(6.8.1.0 真实迁移数据):1509 定义加载、3 个真实 position 表达式解析
  与客户库组织 SQL 一致、待办口径双向对账(4=4/12=12)、挂起拒办回归、委托语义、会签解析;
  写测试全部可逆还原(act_ru_task 总数 9321 不变)
- 5 个 scriptTask 静态核对:全为 Activiti Explorer demo/report 残留,只读零写库
- 报告 flowable-service/P3流程服务实测报告.md;手册新增 §6.5/§6.6/§6.7 坑位

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 14:40:51 +08:00

18 KiB
Raw Permalink Blame History

P3 Flowable 独立工作流服务 实测报告

日期:2026-06-11 | 模块:flowable-service(单客户交付四进程之一,端口 8089) 任务:P3-1/2 —— 新建独立可执行模块 + 移植 3 个表达式 handler bean,在 6.8.1 真实迁移数据上验证 验证场:本地 PG localhost:5433 库 eip4flow schema eip3(39 张 ACT_ 表,schema.version=6.8.1.0, 1,509 定义 / 9,383 执行 / 9,321 待办 / 26,749 历史,WS4 续跑实证过的真实迁移数据) 业务组织库:客户库副本 192.168.20.68:5435 schema eip3(ceshi 只读,1,857 用户)


一、模块结构

flowable-service/                          独立 Spring Boot 可执行 jar,端口 8089
├── pom.xml                                Flowable 6.8.1 + v5 兼容层 + 双数据源 + springdoc
├── src/main/java/
│   ├── com/eip4/flowservice/              现代层(com.eip4.*)
│   │   ├── FlowableServiceApplication     启动器(排除 DataSource/Liquibase 自动装配)
│   │   ├── config/
│   │   │   ├── DataSourceConfig           双数据源:flowableDataSource + bizDataSource
│   │   │   └── FlowableEngineConfig       引擎装配 + cfg.setBeans 注册 3 handler + WfBeanRegistry 注入
│   │   ├── org/OrgDirectoryJdbc           候选人解析直查业务组织库(替 framework 组织服务全闭包)
│   │   └── api/
│   │       ├── FlowController             待办/已办/发起/办理/挂起/激活/委托 REST 薄封装
│   │       ├── CandidateController        候选人解析验证口(对账用)
│   │       ├── FlowExceptionHandler       Flowable 异常 → 干净 HTTP(挂起拒办=409)
│   │       └── TaskDto/ProcessInstanceDto/Requests   出入参 DTO
│   └── com/dsasp/server/wf/               保真层移植(com.dsasp.* 原包名,不反向依赖 com.eip4)
│       ├── user/assignee/CandidateUsersHandler        ★ 移植(4,761 处引用)
│       ├── user/assignee/MultiInstanceUsersHandler    ★ 移植(33 处,会签)
│       ├── service/WfContextService                   ★ 移植(175 处)
│       ├── bean/BasePropertiesConverter               候选人表达式 JSON 解析(裁剪运行期半段)
│       ├── bean/UserProperty                          配置项 bean(逐字节移植)
│       └── support/
│           ├── OrgDirectory               候选人解析窄接口(handler 仅依赖此,不依赖 com.eip4)
│           ├── WfBeanRegistry             取协作 bean 入口(替 SpringBeanOsgiServices)
│           └── WfTypes                     配置类型 + 流程变量名常量(移植自 ProcessDefinitionService/ProcessCoreService)
└── src/test/java/  (26 单测)
    ├── com/eip4/flowservice/org/OrgDirectoryJdbcTest        12 个(解析逻辑 mock 数据源)
    ├── com/eip4/flowservice/api/FlowControllerTest          9 个(REST 薄层 MockMvc)
    └── com/dsasp/server/wf/CandidateUsersHandlerTest        5 个(handler 解析+分派+降级)

父 pom 已加 <module>flowable-service</module>。本模块不依赖任何 platform-* 模块 (引擎在独立服务,gateway 只做客户端,架构第三节)。platform-flow-gateway 占位 pom 未动 (其聚合实现是 P3-4 另一任务)。

二、handler 依赖闭包结论(核心决策)

2.1 原始闭包(framework 实况)

3 个 handler 在 framework 中深度耦合 OSGi + 整个组织服务引擎:

handler 直接依赖 传递闭包
CandidateUsersHandler SpringBeanOsgiServices、AssignmentHandler、ProcessCoreService、AgentService、ProjectRoleUser、BasePropertiesConverter → AssignmentHandlerImpl → UserFindServiceImpl(516 行) + OrganizationServiceImpl(212 行) → POJOCRUDService/GeneralPOJO(整个保真层元数据引擎)
MultiInstanceUsersHandler extends CandidateUsersHandler 同上
WfContextService OrganizationService、POJOCRUDService、FlowExcuteService、UserSession → 保真层 CRUD 引擎 + 服务流引擎

若原样移植整条闭包 = 把 com.dsasp.server.organize + com.dsasp.server.common 元数据/CRUD/服务流引擎 全部拖进独立工作流进程——违背任务纪律(「优先直查业务 schema,避免把整个组织服务拖进独立进程」) 与架构第三节(引擎分进程、中间件最小化)。

2.2 落地策略(裁剪替身 + 直查 SQL)

  • handler 按原包名移植(com.dsasp.server.wf.*),bean 名不变(candidateUsersHandler/ multiInstanceUsersHandler/wfContextService),经 cfg.setBeans 注册——对引擎完全透明。
  • OSGi 解耦:SpringBeanOsgiServices.getBeanByName(...) → WfBeanRegistry.orgDirectory() (手册 §3.1/§5.17 替换类策略同款;独立服务无 OSGi 容器)。
  • 组织服务全闭包 → OrgDirectory 窄接口:只暴露候选人/会签解析真正用到的方法, 实现 OrgDirectoryJdbc 直查业务组织库 SQL,逐条对齐 framework AssignmentHandlerImpl/UserFindServiceImpl/OrganizationServiceImpl, 原版 listSelectSpecialCol(param, TABLE,...)(元数据驱动的 SELECT col FROM TABLE WHERE k IN(...)) 落为参数化直查 SQL(同时收敛原版裸拼注入面,对齐架构第四节安全第 2 层方向)。
  • ArchUnit 纪律保持:OrgDirectory/WfBeanRegistry/WfTypes 放 com.dsasp.* 包下, 移植 handler 零 import com.eip4(自查通过),不破「保真层禁止依赖现代层」。

2.3 实测配置类型分布(决定覆盖优先级)

全量 1,509 个 BPMN 候选人配置类型频次(act_ge_bytearray 实测):

类型 频次 覆盖 解析路径
position 1949 ✅ SYS_POSITIONUSER where positionid IN(...)
user 1683 ✅ content 即 userid,直返
formSpecifiedDimension 601 ✅ 部门→岗位类别岗位→人员,部门内无则回退公司
projectRoleType 528 ⭕ framework 无通用实现(项目定制),留 ProjectRoleResolver 钩子,默认空+WARN
scriptUser 26 ❌ JUEL 脚本 ${users},需服务流脚本引擎,超精简边界,WARN 降级
initiatorDepartManager 24 ❌ 依赖 SYS_USER.MASTERDEPART 元数据虚拟列(客户库无该物理列),需保真层元数据层
depart 14 ✅ 部门→岗位→人员
fixedDimension 12 ❌ 同 initiatorDepartManager(虚拟列/维度树)
sameToTask 5 ❌ 依赖前序活动处理者栈(ProcessCoreServiceImpl),WARN 降级
initiator 3 ✅ 发起人本人(流程变量 WFINITIATORUSERID)

结论:占主导的 user/position/formSpecifiedDimension/depart/initiator(合计 4,250 处,约 91%)全部覆盖。 未覆盖类型(scriptUser/initiatorDepartManager/fixedDimension/sameToTask/projectRoleType) 均为依赖保真层元数据虚拟列、服务流脚本引擎或项目定制扩展者——纯独立服务直查无法复现, WARN 降级返回空并登记;P3-4 聚合或保真层接入时补齐。

2.4 BasePropertiesConverter 裁剪说明

原版 344 行含设计期 BPMN 模型编辑半段(updateTaskPropToBpmnModel 等,依赖 org.activiti.bpmn.model.* 设计器类,不在 Flowable 引擎运行时 classpath)。移植只保留 运行期候选人解析的 readTree/convertToUserProperties 与常量(逐字节一致); 设计期半段从不在 getCandidateUsers 链路调用,省略不影响候选人解析行为。

三、验证证据摘要

# 验证项 方法 结果
1 启动于 6.8.1 真实数据 java -jar,连 eip4flow.eip3,databaseSchemaUpdate=false ✅ 2.0s 启动,v6+v5 双引擎创建,零错
2 1,509 定义加载无错 GET /api/flow/process-definitions/count ✅ 返回 1509
3 候选人解析≥3 真实表达式 POST /candidate/resolve 取 3 个真实 BPMN 的 position content ✅ 见 3.1,REST==客户库组织 SQL
4 待办口径对账 GET /tasks/todo/count vs act_ru_task 直查 ✅ 见 3.2,双口径精确相等
5 挂起拒办(PoC 回归) suspend→complete→activate ✅ complete 返回 409「Cannot complete a suspended task」,激活还原
6 委托后 assignee 变化 POST /tasks/{id}/delegate ✅ 见 3.3,assignee 变受托人/owner 记原人/delegation=PENDING,SQL 精确还原
7 会签(multiInstance)候选解析 真实会签 BPMN 的 user-type item ✅ 见 3.4,getUsers→super.getCandidateUsers 链路解析一致
8 OpenAPI 文档 GET /v3/api-docs ✅ 200,含全部接口注解
9 全模块 mvn test + ArchUnit 整反应堆 mvn test ✅ BUILD SUCCESS,含 ArchitectureRulesTest 绿 + 本模块 26 单测绿

3.1 候选人解析(3 个真实 BPMN position 表达式 → 客户库组织数据一致)

取自 1,509 BPMN 中的真实 position-type 候选人配置内容,REST 解析 == 客户库 sys_positionuser 直查:

真实 position id(取自 BPMN) REST /candidate/resolve 返回 客户库 SQL SELECT userid FROM sys_positionuser WHERE positionid=...
fb2ea316-43c2-4d21-946e-3bb9a3052ce8 ["6d84e817-...e393"] 6d84e817-...e393 ✅
a14a79db-7e57-418b-850e-d636baf9cf61 ["53c4f51b-...eff4"] 53c4f51b-...eff4 ✅
521efd6c-0dd9-48c1-a30b-e98895462b93 ["6c77c063-...59ff"] 6c77c063-...59ff ✅

另:402881343827d0a1013830922bee005c(3 人岗位)REST 返回 3 个 userid,与 SQL 完全一致, 姓名经 sys_user 反查为 顾鼎/顾建方/奚岳云(真实组织数据)。

注:部分 BPMN 的 user/depart-type content 指向的 userid 在当前客户库副本已不存在 (BPMN 部署快照与现网组织表存在自然漂移);此时 REST 与 SQL 同样返回空, 解析路径仍忠实(两侧一致)。position 类型的活数据对账是最强证据(1,949 处主力类型)。

3.2 待办口径对账

assignee REST /tasks/todo/count act_ru_task 直查(suspension_state_=1)
829cdcca-4e07-4e12-9c8e-a3da2c105e31(UUID 形态,无 padding) 4 4 ✅
402881343826dc6f0138275d386d000c+尾 4 空格(bpchar padding 形态) 12 12 ✅

新发现(手册 §5.32 padding 坑在工作流侧复现):act_ru_task.assignee_ 对短 id 用空格补齐到 36 字符 (bpchar 语义),与客户库 sys_*.userid 同款 padding。调用方用 trim 后的 id 查 REST 会匹配不到 (精确等值)。这是已知坑在 Flowable 表上的延伸,已登记入手册 §6.4。

3.3 委托语义

任务 20334061(assignee=829cdcca...,owner=NULL)委托给 顾建方:

委托前: assignee=[829cdcca...]  owner=[NULL]      delegation=NULL
委托后: assignee=[402881343826dc6f0138275d386d000c+pad]  owner=[829cdcca...]  delegation=PENDING
还原后: assignee=[829cdcca...]  owner=[NULL]      delegation=NULL   (直 SQL 精确复位)

assignee 变受托人、owner 记原办理人、delegation=PENDING —— 与 Flowable 委托语义一致。

3.4 会签(multiInstance)候选解析

真实会签 BPMN(28 个含 multiInstanceUsersHandler)中取 user-type item (content=829cdcca-...):MultiInstanceUsersHandler.getUsers → super.getCandidateUsers → OrgDirectory.assignmentUser("user", ...) 解析为会签输入集合 ["829cdcca-..."]。 单测 会签handler委托给候选人解析 另以 3 人集合证 getUsers 委托链。 (多数会签 item 为 scriptUser ${users},属 JUEL 降级分支,登记。)

四、5 个 scriptTask 静态核对清单

5 个 scriptTask 全部定位于 Activiti Explorer 内置 demo/report 流程 (资源路径 org/activiti/explorer/demo/process/...),非客户业务流程,库内残留的演示工件。

# BPMN 资源 scriptFormat 脚本语义 引擎执行性结论
1 createTimersProcess.bpmn20.xml groovy if(throwException=='true') throw RuntimeException(...) 纯 Groovy,仅演示定时器+异常;无写库;Flowable 6.8.1 Groovy(JSR-223)可执行
2 reports/taskDurationForProcessDefinition js ReportingUtil.executeSelectSqlQuery("select ... from ACT_HI_TASKINST ...")(只读统计) 依赖 org.activiti.explorer.reporting.ReportingUtil/ReportData(Explorer UI 类,不在本服务 classpath)+ Nashorn JS(JDK17 已移除)→ 不可执行,亦不应执行
3 reports/employeeProductivity js 同上,按月/按员工聚合 ACT_HI_TASKINST(只读) 同 #2,不可执行
4 reports/helpdeskFirstLineVsEscalated js 同上,统计 ACT_HI_ACTINST/ACT_HI_PROCINST(只读) 同 #2,不可执行
5 reports/processInstanceOverview js 同上,JOIN ACT_HI_PROCINST×ACT_RE_PROCDEF(只读) 同 #2,不可执行

核对结论:

  • 全部 5 个为只读统计/演示脚本,零写库动作,无业务风险。
  • 4 个 report 脚本(js)依赖 Activiti Explorer 报表 UASGE 类 + Nashorn,本独立服务故意不内置 (EOL UI 工件 + JDK17 无 Nashorn);它们是历史 demo 残留,业务流程不引用,保持休眠。
  • 1 个 Groovy(createTimers)纯异常演示,Flowable 6.8.1 Groovy 引擎可执行但无业务意义。
  • 静态核对即可(任务允许),未真执行带库访问的脚本,无数据变更。

五、数据变更登记

纪律:写操作克制;办理类挑可逆/影响小;每次写前记录目标行现状,验证后还原。

操作 目标行 写前现状 写后 还原 净变更
挂起→激活 实例 20329543 / 任务 20329569 suspension_state_=1(active) suspend→state=2,complete 被拒(409) activate→state=1 零(state=1,任务在)
委托→复位 任务 20334061 assignee=829cdcca / owner=NULL / delegation=NULL assignee=顾建方 / owner=829cdcca / delegation=PENDING 直 SQL 复位三列 零(三列还原)
  • 全库 act_ru_task 总数验证前后均为 9321(无新增/删除)。
  • 未做任何 complete 实际办理:complete 推进流程+落历史,不可逐字节还原; 本任务「写操作克制 + 数据宝贵」纪律下,挂起拒办(已证 complete 路径被引擎拦)+ 委托(可逆) 已充分覆盖语义验证,故不消耗不可逆的真实办理额度。挂起场景的 complete 调用被引擎在写库前拒绝, 不构成数据变更。

六、双数据源装配 + 生产单库形态配置示意

6.1 本地验证形态(双库)

flowable.datasource:                 # ACT_ 引擎库
  jdbc-url: jdbc:postgresql://localhost:5433/eip4flow?currentSchema=eip3
biz.datasource:                      # 业务组织库(客户库只读)
  jdbc-url: jdbc:postgresql://192.168.20.68:5435/postgres?currentSchema=eip3
  read-only: true

6.2 生产单库分 schema 形态(架构第三节)

生产为同一 PG 库、不同 schema(ACT_ 在 flowable schema、业务表在 business schema), 仅 URL 的 currentSchema 不同,装配代码零改动:

flowable.datasource:
  jdbc-url: jdbc:postgresql://<生产PG>:5432/eip4?currentSchema=flowable
biz.datasource:
  jdbc-url: jdbc:postgresql://<生产PG>:5432/eip4?currentSchema=business
  read-only: true                    # 业务库只读连接走最小权限账户(架构第四节安全第 3 层)

要点:

  • databaseSchemaUpdate=false 写死在 FlowableEngineConfig,任何形态都严禁引擎自动改表。
  • 业务库连接 read-only,DDL 永不经本服务(最小权限账户由 P2 数据权限线提供)。
  • Liquibase/DataSource/事务管理器自动装配全部排除,避免 Flowable 传递依赖的 liquibase 误触发迁移。

6.3 与 PG 升级分窗的衔接注意

  • 决策会已拍板 PG 升级与 Flowable 升级分两个独立停机窗口(手册 §6.2)。
  • 本服务连的是已完成两步升级(5.23→6.8.1)后的 6.8.1.0 schema; 生产切到单库分 schema 形态时,flowable schema 须已是 6.8.1.0(升级 Runbook 第二步产物), 否则 databaseSchemaUpdate=false 会在引擎构建期 fail-fast(这是预期的安全栅栏,不是 bug)。
  • PG 大版本升级窗口(9.4→15+)在 Flowable 升级窗口之前完成;两窗口各自走变更四要素, 本服务不参与 schema 迁移,只在两步都就绪后接管运行。

七、新坑(已写入手册 §6.4 / §6.5)

  1. §6.4 Flowable 独立服务 Liquibase 误触发:flowable-engine 传递依赖带 liquibase, Boot 的 LiquibaseAutoConfiguration 在双数据源(无 @Primary)下抛 "Liquibase migration DataSource missing" 致启动失败;须排除该自动装配 (databaseSchemaUpdate=false 下本就不该跑任何迁移)。
  2. §6.5 act_ru_task.assignee_ 的 bpchar padding:短 id 被补空格到 36 字符, 与客户库 sys_*.userid padding 同源(手册 §5.32);待办按 assignee 精确等值查询须用 padding 后形态,trim 查询会漏。REST 调用方/聚合层须知此口径。

八、git 提交

见任务结束提交记录(仅 add 本任务自有文件:flowable-service/** + 父 pom module 行 + 手册新坑)。

九、收尾

  • 验证完成后已 kill 8089 端口进程。
  • 全部数据变更已还原,库零残留(act_ru_task 总数 9321 不变)。