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>
This commit is contained in:
2026-06-11 14:40:51 +08:00
parent 3b59e90504
commit 6ced9b15f2
26 changed files with 2161 additions and 1 deletions

View File

@@ -500,10 +500,41 @@ com.dsasp.* com.eip4.*
□ 第一步:Flowable 5.23 完整升级 + 验证 schema.version 达到 5.x 末版
□ 第二步:Flowable 6.8.1 启用 flowable5-compatibility 升级
□ 升级后:验证 1,515 个定义可见 + 抽取运行中实例 engineVer=v5 + schema.version=6.8.1.0
□ platform-flow-gateway 已包含 3 个 handler bean + cfg.setBeans 注册
□ flowable-service 已包含 3 个 handler bean + cfg.setBeans 注册(P3 落地:独立服务侧而非 gateway,见 6.5)
□ 工具链运行前确认 JAVA_HOME 指向 JDK17(export JAVA_HOME=/path/to/jdk17)
```
### 6.5 3 个 handler 落在独立服务而非 gateway;组织服务全闭包改直查 SQL [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | §6.3 原写「将 3 个 handler 移植到 `platform-flow-gateway`」;但架构第三节裁定交付为 4 进程,`flowable-service.jar` 是独立进程、引擎在独立服务,`platform-flow-gateway` 只做客户端。handler 须随引擎落在 **`flowable-service`** 模块,非 gateway |
| **根因** | 候选人表达式由 Flowable 引擎在 `cfg.setBeans` 注册的 bean 上求值,bean 必须与引擎同进程;gateway 是 REST 客户端、无引擎,注册无意义 |
| **对策** | handler 按原包名移植进 `flowable-service`(`com.dsasp.server.wf.*`),bean 名不变经 `cfg.setBeans` 注册。**关键裁剪**:原版 handler 经 `SpringBeanOsgiServices` 取 `AssignmentHandler`/`UserFindService`/`OrganizationService`,传递闭包是整个保真层元数据/CRUD 引擎(`POJOCRUDService`/`GeneralPOJO`);独立服务**不拖入该闭包**,改为 `OrgDirectory` 窄接口 + `OrgDirectoryJdbc` 直查业务组织库 SQL(逐条对齐 framework `AssignmentHandlerImpl`/`UserFindServiceImpl`/`OrganizationServiceImpl`)。OSGi 取 bean → `WfBeanRegistry`(§3.1/§5.17 替换类策略)。详见 `flowable-service/P3流程服务实测报告.md` 第二节 |
| **覆盖面** | 实测配置类型分布 position 1949/user 1683/formSpecifiedDimension 601/depart 14/initiator 3 等占主导(~91%)已直查覆盖;scriptUser(JUEL 脚本)/initiatorDepartManager·fixedDimension(依赖 SYS_USER.MASTERDEPART 元数据虚拟列,客户库无物理列)/sameToTask(前序活动栈)/projectRoleType(项目定制扩展)依赖保真层或定制,WARN 降级,P3-4 聚合或保真层接入补齐 |
| **影响范围** | P3 模块落点(flowable-service 而非 gateway);gateway 聚合实现是 P3-4 客户端任务 |
### 6.6 Flowable 独立服务 Boot 自动装配两坑 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象一** | flowable-service 启动抛 `IllegalStateException: Liquibase migration DataSource missing`,context 初始化失败 |
| **根因一** | `flowable-engine` 传递依赖带 liquibase-core,Boot `LiquibaseAutoConfiguration` 被激活,但本服务双数据源无 `@Primary`,liquibase 找不到迁移数据源 |
| **对策一** | `@SpringBootApplication(exclude={DataSourceAutoConfiguration, DataSourceTransactionManagerAutoConfiguration, LiquibaseAutoConfiguration})`;`databaseSchemaUpdate=false` 下本就严禁任何 schema 迁移,liquibase 不该跑 |
| **现象二** | Hikari 报 `jdbcUrl is required with driverClassName`,引擎构建失败 |
| **根因二** | `DataSourceBuilder.build()` 产出 `HikariDataSource`,`@ConfigurationProperties` 绑 `url` 属性时 Hikari 无 `setUrl` setter(其属性名是 `jdbcUrl`) |
| **对策二** | YAML 用 Hikari 原生属性名 `jdbc-url`(非 `url`) |
| **影响范围** | 凡手工装配 Flowable 引擎 + 多数据源的独立 Boot 服务(非 flowable-spring-boot-starter 路径) |
### 6.7 act_ru_task.assignee_ 的 bpchar padding(待办按 assignee 精确查询坑)[NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | 待办 REST 按 assignee 精确查询,用 trim 后的 userid 查不到记录,但库里确有该用户的待办 |
| **根因** | `act_ru_task.assignee_` 对短 id(如 32 字符 hex)补空格到 36 字符(bpchar padding),与客户库 `sys_*.userid` 的 padding 同源(§5.32);Flowable taskQuery `taskAssignee()` 走精确等值,padding 不一致则不匹配 |
| **对策** | 待办查询/聚合层须按 padding 后形态匹配 assignee;REST 调用方(P3-4 gateway/前端)须知此口径,或在聚合层统一 padding 规整 |
| **影响范围** | 所有按 assignee 精确查询的待办接口;实测 padded assignee(尾 4 空格)REST 待办数=act_ru_task 直查数=12,trim 形态=0 |
---
## 七、库内数据质量已知问题