- 新模块 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>
18 KiB
P3 Flowable 独立工作流服务 实测报告
日期:2026-06-11 | 模块:
flowable-service(单客户交付四进程之一,端口 8089) 任务:P3-1/2 —— 新建独立可执行模块 + 移植 3 个表达式 handler bean,在 6.8.1 真实迁移数据上验证 验证场:本地 PGlocalhost:5433库eip4flowschemaeip3(39 张 ACT_ 表,schema.version=6.8.1.0, 1,509 定义 / 9,383 执行 / 9,321 待办 / 26,749 历史,WS4 续跑实证过的真实迁移数据) 业务组织库:客户库副本192.168.20.68:5435schemaeip3(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,逐条对齐 frameworkAssignmentHandlerImpl/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)
- §6.4 Flowable 独立服务 Liquibase 误触发:flowable-engine 传递依赖带 liquibase,
Boot 的
LiquibaseAutoConfiguration在双数据源(无 @Primary)下抛 "Liquibase migration DataSource missing" 致启动失败;须排除该自动装配 (databaseSchemaUpdate=false下本就不该跑任何迁移)。 - §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 行 + 手册新坑)。
九、收尾
- 验证完成后已
kill8089 端口进程。 - 全部数据变更已还原,库零残留(act_ru_task 总数 9321 不变)。