# 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 已加 `flowable-service`。本模块**不依赖任何 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 本地验证形态(双库) ```yaml 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` 不同,装配代码零改动: ```yaml 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 不变)。