- 新模块 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>
261 lines
18 KiB
Markdown
261 lines
18 KiB
Markdown
# 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 不变)。
|