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

261 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 本地验证形态(双库)
```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 不变)。