diff --git a/docs/迁移手册.md b/docs/迁移手册.md
index c7bdad1..cb9f049 100644
--- a/docs/迁移手册.md
+++ b/docs/迁移手册.md
@@ -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 |
+
---
## 七、库内数据质量已知问题
diff --git a/flowable-service/P3流程服务实测报告.md b/flowable-service/P3流程服务实测报告.md
new file mode 100644
index 0000000..9a7d315
--- /dev/null
+++ b/flowable-service/P3流程服务实测报告.md
@@ -0,0 +1,260 @@
+# 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 不变)。
diff --git a/flowable-service/pom.xml b/flowable-service/pom.xml
new file mode 100644
index 0000000..e1e8897
--- /dev/null
+++ b/flowable-service/pom.xml
@@ -0,0 +1,101 @@
+
+
+ 4.0.0
+
+ com.eip4
+ eip4-platform
+ 0.1.0-SNAPSHOT
+
+ flowable-service
+ flowable-service
+
+ P3 Flowable 独立工作流服务(单客户交付四进程之一:flowable-service.jar,端口 8089)。
+ Flowable 6.8.1 引擎(连 eip4flow.eip3,databaseSchemaUpdate=false)+ v5 兼容层;
+ 3 个表达式 handler bean(com.dsasp.server.wf.*)按原包名移植,经 cfg.setBeans 注册;
+ 候选人解析改直查业务组织库(双数据源:ACT_ 本地 eip4flow + 业务表客户库只读),
+ 不把整个 com.dsasp.server.organize 保真层引擎拖进独立进程。
+ REST 薄封装 Flowable API:待办/已办/发起/办理/挂起/激活/委托。
+
+ 注意:本模块独立于 eip4-platform.jar,不依赖任何 com.eip4 platform-* 模块,
+ 亦不依赖 platform-legacy-core(引擎在独立服务,gateway 只做客户端,见架构第三节)。
+
+
+
+ 6.8.1
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-web
+
+
+ org.springframework.boot
+ spring-boot-starter-jdbc
+
+
+
+
+ org.flowable
+ flowable-engine
+ ${flowable.version}
+
+
+
+ org.flowable
+ flowable5-compatibility
+ ${flowable.version}
+
+
+ org.flowable
+ flowable5-spring-compatibility
+ ${flowable.version}
+
+
+
+ org.postgresql
+ postgresql
+
+
+
+
+ org.codehaus.jackson
+ jackson-mapper-asl
+
+
+
+ joda-time
+ joda-time
+
+
+
+
+ org.springdoc
+ springdoc-openapi-starter-webmvc-ui
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-test
+ test
+
+
+
+
+
+
+ org.springframework.boot
+ spring-boot-maven-plugin
+
+ com.eip4.flowservice.FlowableServiceApplication
+
+
+
+
+
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/bean/BasePropertiesConverter.java b/flowable-service/src/main/java/com/dsasp/server/wf/bean/BasePropertiesConverter.java
new file mode 100644
index 0000000..7936cda
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/bean/BasePropertiesConverter.java
@@ -0,0 +1,74 @@
+package com.dsasp.server.wf.bean;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.codehaus.jackson.JsonNode;
+import org.codehaus.jackson.map.ObjectMapper;
+
+/**
+ * 候选人表达式 JSON 解析器。移植自 framework com.dsasp.server.wf.bean.BasePropertiesConverter,
+ * 仅保留引擎运行期候选人解析所用的两个方法({@link #readTree} / {@link #convertToUserProperties})
+ * 与相关常量,逐字节一致。
+ *
+ *
原版另含 {@code updateTaskPropToBpmnModel/parserUserPropertiesExpress/...} 等
+ * 设计期 BPMN 模型编辑方法,依赖 {@code org.activiti.bpmn.model.*}(设计器侧类,
+ * 不在 Flowable 引擎运行时 classpath 上),且独立工作流服务只负责执行已部署定义、
+ * 不在服务内重编辑 BPMN——故移植时省略,不影响候选人解析行为(该半段从不在 getCandidateUsers 链路调用)。
+ * 省略事实登记于 P3 报告「handler 依赖闭包」一节。
+ */
+public class BasePropertiesConverter {
+ public static final String TYPE = "type";
+ public static final String ITEMES = "items";
+ public static final String CONTENT = "content";
+ public static final String ISSENDMAIL = "isSendMail";
+ public static final String ISSENDPHONE = "isSendPhone";
+ public static final String ISSENDMESSAGE = "isSendMessage";
+ public static final String ISCANDIDATE = "isCandidate";
+ public static final String ISSKIPINITIATOR = "isSkipInitiator";
+ public static final String ISSKIPBEFORETASK = "isSkipBeforeTask";
+ public static final String ISNOUSERSKIP = "isNoUserSkip";
+ public static final String MESSAGETEMPLATE = "messageTemplate";//消息模板
+ public static final String TASKSUCCESSSERVICE = "taskSuccessService";//任务完成后执行的服务
+
+ public static final String CANDIDATESERVICE = "${candidateUsersHandler.getCandidateUsers(execution,'";
+ public static final String MULTIINSTANCESERVICE = "${multiInstanceUsersHandler.getUsers(execution,'";
+ public static final String DUEDATESERVICE = "${dueDateService.getDueDate(execution,";
+
+ public static JsonNode readTree(String content) {
+ ObjectMapper mapper = new ObjectMapper();
+ try {
+ return mapper.readTree(content);
+ } catch (Exception ex) {
+ ex.printStackTrace();
+ return null;
+ }
+ }
+
+ public static List convertToUserProperties(JsonNode node){
+// JsonNode node = readTree(expression);
+ ArrayList list = new ArrayList();
+ if(node == null)
+ return list;
+ JsonNode jsonArray = node.get(ITEMES);
+ for(JsonNode userNode : jsonArray){
+ JsonNode type = userNode.get(TYPE);
+ JsonNode content = userNode.get(CONTENT);
+ JsonNode isSendMail = userNode.get(ISSENDMAIL);
+ JsonNode isSendPhone = userNode.get(ISSENDPHONE);
+ JsonNode isSendMessage = userNode.get(ISSENDMESSAGE);
+ JsonNode isCandidate = userNode.get(ISCANDIDATE);
+ UserProperty userProperty = new UserProperty();
+ userProperty.setCandidate(isCandidate.asBoolean());
+ if(isSendMessage != null){
+ userProperty.setSendMessage(isSendMessage.asBoolean());
+ }
+ userProperty.setSendMail(isSendMail.asBoolean());
+ userProperty.setSendPhone(isSendPhone.asBoolean());
+ userProperty.setContent(content.asText());
+ userProperty.setType(type.asText());
+ list.add(userProperty);
+ }
+ return list;
+ }
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/bean/UserProperty.java b/flowable-service/src/main/java/com/dsasp/server/wf/bean/UserProperty.java
new file mode 100644
index 0000000..bd26a8b
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/bean/UserProperty.java
@@ -0,0 +1,54 @@
+package com.dsasp.server.wf.bean;
+
+/**
+ * 候选人配置项 bean。原样移植自 framework com.dsasp.server.wf.bean.UserProperty
+ * (com.dsasp.server.wf 模块),一字段不增删,保证候选人表达式解析行为逐字节一致。
+ */
+public class UserProperty {
+ private String type;
+ private String content;
+ private boolean isCandidate;
+ private boolean isSendMail;
+ private boolean isSendPhone;
+ private boolean isSendMessage;
+ public String getType() {
+ return type;
+ }
+ public void setType(String type) {
+ this.type = type;
+ }
+ public String getContent() {
+ return content;
+ }
+ public void setContent(String content) {
+ if("null".equals(content)){
+ content = null;
+ }
+ this.content = content;
+ }
+ public boolean isCandidate() {
+ return isCandidate;
+ }
+ public void setCandidate(boolean isCandidate) {
+ this.isCandidate = isCandidate;
+ }
+ public boolean isSendMail() {
+ return isSendMail;
+ }
+ public void setSendMail(boolean isSendMail) {
+ this.isSendMail = isSendMail;
+ }
+ public boolean isSendPhone() {
+ return isSendPhone;
+ }
+ public void setSendPhone(boolean isSendPhone) {
+ this.isSendPhone = isSendPhone;
+ }
+ public boolean isSendMessage() {
+ return isSendMessage;
+ }
+ public void setSendMessage(boolean isSendMessage) {
+ this.isSendMessage = isSendMessage;
+ }
+
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/service/WfContextService.java b/flowable-service/src/main/java/com/dsasp/server/wf/service/WfContextService.java
new file mode 100644
index 0000000..16e68bd
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/service/WfContextService.java
@@ -0,0 +1,69 @@
+package com.dsasp.server.wf.service;
+
+import com.dsasp.server.wf.support.WfBeanRegistry;
+
+/**
+ * 流程上下文服务,BPMN 表达式 {@code ${wfContextService.xxx(...)}} 入口。
+ *
+ * 移植自 framework {@code com.dsasp.server.wf.service.WfContextService}
+ * (com.dsasp.server.wf 模块,被 175 处引用,手册 §6.3)。
+ * 经 {@code ProcessEngineConfiguration.setBeans} 以 bean 名 {@code wfContextService} 注册。
+ *
+ * 独立服务边界(行为登记于 P3 报告):
+ *
+ * - {@link #getOrgByDepartId}:经 {@link com.dsasp.server.wf.support.OrgDirectory}
+ * 直查业务组织库(view_depart_tree),与原版 OrganizationService 同 SQL,已实现。
+ * - {@link #getValue}/{@link #getDisplayValue}/{@link #excuteServiceFlow}:原版依赖保真层
+ * {@code POJOCRUDService}(业务表 CRUD)与 {@code FlowExcuteService}(服务流引擎),
+ * 两者都在 eip4-platform.jar(保真层引擎所在进程),不在本独立服务内
+ * (架构第三节:引擎在独立服务、保真层在平台进程,职责分离)。本服务内 WARN 降级返回 null;
+ * 生产形态由 platform-flow-gateway/platform 经回调或同进程装配补齐(P3-4 聚合任务),报告登记。
+ *
+ */
+public class WfContextService {
+
+ /**
+ * 根据部门ID获取组织ID。
+ */
+ public String getOrgByDepartId(String departId){
+ return WfBeanRegistry.orgDirectory().getOrgIdByDepartId(departId);
+ }
+
+ /**
+ * 获取指定记录属性值。原版经 POJOCRUDService.loadPOJO 取保真层业务表记录;
+ * 该引擎在 eip4-platform.jar,独立工作流服务不内置,WARN 降级。
+ */
+ public Object getValue(String businessKey,String tableName,String columnName){
+ System.out.println("[WARN] wfContextService.getValue 依赖保真层 POJOCRUDService(在 eip4-platform.jar),"
+ + "独立工作流服务未内置,返回 null。businessKey=" + businessKey + " table=" + tableName + " col=" + columnName);
+ return null;
+ }
+
+ /**
+ * 获取指定记录属性显示值。同 {@link #getValue},WARN 降级。
+ */
+ public Object getDisplayValue(String businessKey,String tableName,String columnName){
+ System.out.println("[WARN] wfContextService.getDisplayValue 依赖保真层 POJOCRUDService(在 eip4-platform.jar),"
+ + "独立工作流服务未内置,返回 null。businessKey=" + businessKey + " table=" + tableName + " col=" + columnName);
+ return null;
+ }
+
+ /**
+ * 执行指定服务流。原版经 FlowExcuteService.excute 调保真层服务流引擎;
+ * 该引擎在 eip4-platform.jar,独立工作流服务不内置,WARN 降级。
+ */
+ public Object excuteServiceFlow(String businessKey,String tableName,String flowId){
+ System.out.println("[WARN] wfContextService.excuteServiceFlow 依赖保真层服务流引擎(在 eip4-platform.jar),"
+ + "独立工作流服务未内置,返回 null。flowId=" + flowId);
+ return null;
+ }
+
+ /**
+ * 执行指定服务流(带 execution)。同上,WARN 降级。
+ */
+ public Object excuteServiceFlow(Object execution,String businessKey,String tableName,String flowId){
+ System.out.println("[WARN] wfContextService.excuteServiceFlow(execution) 依赖保真层服务流引擎(在 eip4-platform.jar),"
+ + "独立工作流服务未内置,返回 null。flowId=" + flowId);
+ return null;
+ }
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/support/OrgDirectory.java b/flowable-service/src/main/java/com/dsasp/server/wf/support/OrgDirectory.java
new file mode 100644
index 0000000..a8f4311
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/support/OrgDirectory.java
@@ -0,0 +1,53 @@
+package com.dsasp.server.wf.support;
+
+import java.util.List;
+
+/**
+ * 候选人解析所需的「业务组织目录」窄接口。
+ *
+ * 这是独立 Flowable 服务对 framework 保真层
+ * {@code com.dsasp.server.common.user.service.AssignmentHandler} +
+ * {@code UserFindService} + {@code OrganizationService} 三件套的裁剪替身:
+ * 只暴露候选人/会签解析真正用到的方法,实现走直查业务组织库的 SQL
+ * (见 {@code com.eip4.flowservice.org.OrgDirectoryJdbc}),
+ * 不把整个 com.dsasp.server.organize 引擎(POJOCRUDService/GeneralPOJO/元数据层)
+ * 拖进独立进程(任务纪律:优先直查业务 schema,避免组织服务全闭包)。
+ *
+ * 放在 com.dsasp 包下,使移植的 handler 仅依赖本接口、不反向 import com.eip4
+ * (ArchUnit「保真层禁止依赖现代层」纪律)。运行期实例由
+ * {@code cfg.setBeans} 注册并经 {@link WfBeanRegistry} 取用,
+ * 等价 framework 原版的 {@code SpringBeanOsgiServices.getBeanByName} 间接(手册 §3.1 替换类策略)。
+ */
+public interface OrgDirectory {
+
+ /**
+ * 解析单条候选人配置项为用户 id 列表。
+ *
+ * 对齐 framework {@code AssignmentHandlerImpl.assignmentUser(type, content, initiatorId, initiatorDepartId)}
+ * 的分派语义(见手册 §6.3 candidateUsersHandler 引用 4,761 处)。
+ *
+ * @param type 配置类型(user/roles/depart/position/initiator/...,
+ * 见 framework ProcessDefinitionService 常量)
+ * @param content 配置内容(逗号分隔的 id 串,或脚本/维度等)
+ * @param initiatorId 发起人 id(部分类型需要),可为 null
+ * @param initiatorDepart 发起人所属部门 id(部分类型需要),可为 null
+ * @return 用户 id 列表,永不为 null
+ */
+ List assignmentUser(String type, String content, String initiatorId, String initiatorDepart);
+
+ /**
+ * 项目角色("八大员"等项目内角色)候选人解析。
+ *
+ * 对齐 framework {@code ProjectRoleUser.getUserByProjectRole}。
+ * framework 内无通用实现(项目定制扩展),本服务默认返回空并 WARN,
+ * 客户私有化时按其 ProjectRoleUser 实现接入。
+ */
+ List getUsersByProjectRole(String projectId, String roleContent);
+
+ /**
+ * 部门 id → 组织(公司)id。对齐 framework
+ * {@code OrganizationService.getOrgIdByDepartId}(经 view_depart_tree 查)。
+ * 供 {@code wfContextService.getOrgByDepartId} 使用。
+ */
+ String getOrgIdByDepartId(String departId);
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/support/WfBeanRegistry.java b/flowable-service/src/main/java/com/dsasp/server/wf/support/WfBeanRegistry.java
new file mode 100644
index 0000000..d851478
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/support/WfBeanRegistry.java
@@ -0,0 +1,36 @@
+package com.dsasp.server.wf.support;
+
+/**
+ * 移植 handler 取协作 bean 的入口。
+ *
+ * framework 原版 {@code CandidateUsersHandler} 经
+ * {@code SpringBeanOsgiServices.getInstance().getBeanByName("assignmentHandler")} 取依赖
+ * (手册 §5.17:OSGi 服务注册/发现);独立服务无 OSGi 容器,本类是其等价替换
+ * (手册 §3.1「替换类清单」同款策略):由现代层装配时 {@link #setOrgDirectory} 注入,
+ * handler 侧 {@link #orgDirectory()} 取用,handler 因此不反向依赖 com.eip4。
+ */
+public final class WfBeanRegistry {
+
+ private static volatile OrgDirectory orgDirectory;
+
+ private WfBeanRegistry() {
+ }
+
+ public static void setOrgDirectory(OrgDirectory directory) {
+ orgDirectory = directory;
+ }
+
+ /**
+ * @return 组织目录实现;未注入时抛错(暴露装配遗漏,等价原版 getBeanByName 取空 NPE,
+ * 但信息更明确)。
+ */
+ public static OrgDirectory orgDirectory() {
+ OrgDirectory d = orgDirectory;
+ if (d == null) {
+ throw new IllegalStateException(
+ "OrgDirectory 未注册:flowable-service 装配阶段须 WfBeanRegistry.setOrgDirectory(...) "
+ + "(等价 framework SpringBeanOsgiServices 注册 assignmentHandler/userFindService)");
+ }
+ return d;
+ }
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/support/WfTypes.java b/flowable-service/src/main/java/com/dsasp/server/wf/support/WfTypes.java
new file mode 100644
index 0000000..8e78a4d
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/support/WfTypes.java
@@ -0,0 +1,39 @@
+package com.dsasp.server.wf.support;
+
+/**
+ * 候选人配置类型常量 + 流程变量名常量。
+ *
+ * 逐字节移植自 framework
+ * {@code com.dsasp.server.common.workflow.service.ProcessDefinitionService}(配置类型)
+ * 与 {@code ProcessCoreService}(流程变量名),使移植 handler 的分派语义与原版一致;
+ * 集中到本类避免再拖入 framework workflow 服务模块的接口闭包。
+ */
+public final class WfTypes {
+
+ private WfTypes() {
+ }
+
+ // ===== 配置类型(ProcessDefinitionService) =====
+ public static final String USER = "user";
+ public static final String ROLES = "roles";
+ public static final String DEPART = "depart";
+ public static final String POSITION = "position";
+ public static final String INITIATOR = "initiator";
+ public static final String INITIATORDEPARTMANAGER = "initiatorDepartManager";
+ public static final String INITIATORLEADER = "initiatorLeader";
+ public static final String INITIATORSUBORDINATE = "initiatorSubordinate";
+ public static final String INITIATORDEPART = "initiatorDepart";
+ public static final String SAMETOTASK = "sameToTask";
+ public static final String BEFORETASKLEADER = "beforeTaskLeader";
+ public static final String BEFORETASKDEPARTMANAGER = "beforeTaskDepartManager";
+ public static final String FIXEDDIMENSION = "fixedDimension";
+ public static final String FORMSPECIFIEDDIMENSION = "formSpecifiedDimension";
+ public static final String PROJECTROLETYPE = "projectRoleType";
+ public static final String SCRIPTUSER = "scriptUser";
+
+ // ===== 流程变量名(ProcessCoreService) =====
+ public static final String INITIATORUSERID = "WFINITIATORUSERID";
+ public static final String INITIATORDEPARTID = "WFINITIATORDEPARTID";
+ public static final String PROCESSTITLE = "PROCESSTITLE";
+ public static final String PROJECTID = "PROJECTID";
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/CandidateUsersHandler.java b/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/CandidateUsersHandler.java
new file mode 100644
index 0000000..68ba994
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/CandidateUsersHandler.java
@@ -0,0 +1,157 @@
+package com.dsasp.server.wf.user.assignee;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import org.codehaus.jackson.JsonNode;
+import org.flowable.common.engine.impl.identity.Authentication;
+import org.flowable.engine.ProcessEngines;
+import org.flowable.engine.RuntimeService;
+
+import com.dsasp.server.wf.bean.BasePropertiesConverter;
+import com.dsasp.server.wf.bean.UserProperty;
+import com.dsasp.server.wf.support.OrgDirectory;
+import com.dsasp.server.wf.support.WfBeanRegistry;
+import com.dsasp.server.wf.support.WfTypes;
+
+/**
+ * 候选人表达式 handler。
+ *
+ * 移植自 framework {@code com.dsasp.server.wf.user.assignee.CandidateUsersHandler}
+ * (com.dsasp.server.wf 模块,被 1,509 个 BPMN 里 4,761 处
+ * {@code ${candidateUsersHandler.getCandidateUsers(execution,'...')}} 引用,手册 §6.3)。
+ * 经 {@code ProcessEngineConfiguration.setBeans} 以 bean 名 {@code candidateUsersHandler} 注册。
+ *
+ * 对 framework 原版的两处工程化适配(行为登记于 P3 报告):
+ *
+ * - OSGi 解依赖:{@code SpringBeanOsgiServices.getBeanByName("assignmentHandler"/"processCoreService"/...)}
+ * → {@link WfBeanRegistry#orgDirectory()}(独立服务无 OSGi 容器,手册 §3.1/§5.17 替换类策略);
+ * 候选人解析的真实 SQL 改直查业务组织库,不拖入 com.dsasp.server.organize 引擎全闭包。
+ * - activiti API → Flowable API:{@code ProcessEngines.getDefaultProcessEngine()} 取流程变量;
+ * {@code execution} 形参放宽为 {@code Object}(v5 兼容层与 v6 的 Execution 类型不同,
+ * 仅用其 processInstanceId,经引擎运行时反查,避免对实现类的硬转型,与 PoC 桩同口径)。
+ *
+ *
+ * 当前未接入的分支(WARN 降级,报告登记):{@code scriptUser}(JUEL 脚本,26 处,
+ * 需服务流脚本引擎,超独立服务精简边界)、{@code agentService} 代理人替换后处理(项目定制扩展)。
+ * 占主导的 user/position/depart/formSpecifiedDimension/initiator 等类型(实测分布见报告)全部覆盖。
+ */
+public class CandidateUsersHandler {
+
+ public List getCandidateUsers(Object execution, String expression){
+ String processInstanceId = resolveProcessInstanceId(execution);
+ //FIXME: json text(原版注释保留)
+ JsonNode node = BasePropertiesConverter.readTree(expression.replace("【", "{").replace("】", "}"));
+ List userProperties = BasePropertiesConverter
+ .convertToUserProperties(node);
+ List list = new ArrayList();
+ List phoneList = new ArrayList();
+ List emailList = new ArrayList();
+ List messageList = new ArrayList();
+ String initiatorId = null;
+ String initiatorDepartId = null;
+
+ RuntimeService runtimeService = resolveRuntimeService();
+ String projectId = (String) getVariable(runtimeService, processInstanceId, WfTypes.PROJECTID);
+
+ OrgDirectory directory = WfBeanRegistry.orgDirectory();
+
+ if(userProperties != null){
+ for(UserProperty userProperty : userProperties){
+ List users = null;
+ if(WfTypes.SAMETOTASK.equals(userProperty.getType())
+ || WfTypes.BEFORETASKLEADER.equals(userProperty.getType())
+ || WfTypes.BEFORETASKDEPARTMANAGER.equals(userProperty.getType())){
+ // 原版经 processCoreService.getSpecialActivityProcessor(前一活动处理者)解析;
+ // 该解析依赖历史活动栈遍历(framework ProcessCoreServiceImpl),
+ // 独立服务暂不接入(WARN 降级),报告登记。占比小(sameToTask 5 处)。
+ System.out.println("[WARN] candidateUsersHandler: 类型 " + userProperty.getType()
+ + " 依赖前序活动处理者解析,独立服务暂未接入,跳过该项");
+ users = new ArrayList();
+ }else if(WfTypes.SCRIPTUSER.equals(userProperty.getType())){
+ // 原版经 ScriptingEngines.evaluate(content,"juel",execution) 求值;
+ // 独立服务不内置服务流脚本引擎(精简边界),WARN 降级,报告登记。
+ System.out.println("[WARN] candidateUsersHandler: scriptUser(JUEL 脚本)分支独立服务暂未接入,跳过该项");
+ users = new ArrayList();
+ }else if(WfTypes.PROJECTROLETYPE.equals(userProperty.getType())){
+ users = directory.getUsersByProjectRole(projectId, userProperty.getContent());
+ }
+ else{
+ if(isEmpty(initiatorId)){
+ initiatorId = (String) getVariable(runtimeService, processInstanceId, WfTypes.INITIATORUSERID);
+ }
+ if(isEmpty(initiatorDepartId)){
+ initiatorDepartId = (String) getVariable(runtimeService, processInstanceId, WfTypes.INITIATORDEPARTID);
+ }
+ users = directory.assignmentUser(userProperty.getType(), userProperty.getContent(), initiatorId, initiatorDepartId);
+ }
+ if(users != null && users.size() > 0){
+ if(userProperty.isCandidate()){
+ list.addAll(users);
+ }
+ if(userProperty.isSendMail()){
+ emailList.addAll(users);
+ }
+ if(userProperty.isSendPhone()){
+ phoneList.addAll(users);
+ }
+ if(userProperty.isSendMessage()){
+ messageList.addAll(users);
+ }
+ }
+ }
+ }
+ // 原版此处经 agentService.agent(list,...) 做代理人(委托/出差代办)替换后处理;
+ // agentService 是项目定制扩展(framework AgentServiceImpl 依赖代理表),
+ // 独立服务暂不接入,直接返回原始候选人 list,报告登记。
+ return list;
+ }
+
+ /** 从 v5/v6 Execution 或字符串 id 中取流程实例 id,不硬转型实现类。 */
+ protected String resolveProcessInstanceId(Object execution) {
+ if (execution == null) {
+ return null;
+ }
+ if (execution instanceof String) {
+ return (String) execution;
+ }
+ // v5 org.activiti.engine.runtime.Execution / v6 org.flowable.engine.runtime.Execution
+ // 均有 getProcessInstanceId();反射调用避免对具体 API 版本的编译期耦合。
+ try {
+ Object pid = execution.getClass().getMethod("getProcessInstanceId").invoke(execution);
+ return pid != null ? pid.toString() : null;
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ /** 取默认引擎的 RuntimeService;无默认引擎(如单测)时返回 null,后续按变量缺省处理。 */
+ protected RuntimeService resolveRuntimeService() {
+ try {
+ var engine = ProcessEngines.getDefaultProcessEngine();
+ return engine != null ? engine.getRuntimeService() : null;
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ private Object getVariable(RuntimeService runtimeService, String processInstanceId, String name) {
+ if (runtimeService == null || processInstanceId == null) {
+ return null;
+ }
+ try {
+ return runtimeService.getVariable(processInstanceId, name);
+ } catch (Exception e) {
+ return null;
+ }
+ }
+
+ private static boolean isEmpty(String s) {
+ return s == null || s.trim().isEmpty();
+ }
+
+ /** 取当前发起人(可空),保留以兼容旧 call site;独立服务下经流程变量得到。 */
+ public static String currentInitiator() {
+ return Authentication.getAuthenticatedUserId();
+ }
+}
diff --git a/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/MultiInstanceUsersHandler.java b/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/MultiInstanceUsersHandler.java
new file mode 100644
index 0000000..0707ac9
--- /dev/null
+++ b/flowable-service/src/main/java/com/dsasp/server/wf/user/assignee/MultiInstanceUsersHandler.java
@@ -0,0 +1,21 @@
+package com.dsasp.server.wf.user.assignee;
+
+import java.util.List;
+
+/**
+ * 会签(multiInstance)候选人表达式 handler。
+ *
+ * 移植自 framework {@code com.dsasp.server.wf.user.assignee.MultiInstanceUsersHandler}
+ * (extends {@link CandidateUsersHandler},被 33 处
+ * {@code ${multiInstanceUsersHandler.getUsers(execution,'...')}} 引用,手册 §6.3)。
+ * 经 {@code ProcessEngineConfiguration.setBeans} 以 bean 名 {@code multiInstanceUsersHandler} 注册。
+ *
+ * 原版 {@code getUsers} 直接 {@code return super.getCandidateUsers(execution, expression)}
+ * (会签输入集合 = 候选人集合),逐字保留。execution 形参与父类一致放宽为 Object。
+ */
+public class MultiInstanceUsersHandler extends CandidateUsersHandler {
+
+ public List getUsers(Object execution, String expression){
+ return super.getCandidateUsers(execution, expression);
+ }
+}
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/FlowableServiceApplication.java b/flowable-service/src/main/java/com/eip4/flowservice/FlowableServiceApplication.java
new file mode 100644
index 0000000..182c5a7
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/FlowableServiceApplication.java
@@ -0,0 +1,31 @@
+package com.eip4.flowservice;
+
+import org.springframework.boot.SpringApplication;
+import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration;
+import org.springframework.boot.autoconfigure.jdbc.DataSourceTransactionManagerAutoConfiguration;
+import org.springframework.boot.autoconfigure.liquibase.LiquibaseAutoConfiguration;
+
+/**
+ * Flowable 独立工作流服务启动器(单客户交付四进程之一:flowable-service.jar,端口 8089)。
+ *
+ * 排除三项自动装配,改手工接管:
+ *
+ * - {@link DataSourceAutoConfiguration}:本服务手工装配双数据源
+ * (flowableDataSource + bizDataSource,见 {@code DataSourceConfig}),无 @Primary 单源;
+ * - {@link DataSourceTransactionManagerAutoConfiguration}:事务由 Flowable 引擎内部管理;
+ * - {@link LiquibaseAutoConfiguration}:Flowable 传递依赖带 liquibase,但本服务
+ * databaseSchemaUpdate=false、严禁自动改表(任务红线),不跑任何 schema 迁移。
+ *
+ */
+@SpringBootApplication(exclude = {
+ DataSourceAutoConfiguration.class,
+ DataSourceTransactionManagerAutoConfiguration.class,
+ LiquibaseAutoConfiguration.class
+})
+public class FlowableServiceApplication {
+
+ public static void main(String[] args) {
+ SpringApplication.run(FlowableServiceApplication.class, args);
+ }
+}
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/CandidateController.java b/flowable-service/src/main/java/com/eip4/flowservice/api/CandidateController.java
new file mode 100644
index 0000000..c6c6a6b
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/CandidateController.java
@@ -0,0 +1,94 @@
+package com.eip4.flowservice.api;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+import org.flowable.engine.RepositoryService;
+import org.flowable.engine.RuntimeService;
+import org.flowable.engine.TaskService;
+import org.flowable.task.api.Task;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import com.dsasp.server.wf.support.OrgDirectory;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * 候选人解析验证入口。
+ *
+ * 用于实测对账(P3 报告):给定候选人配置表达式(或挑一个真实待办的处理者来源类型/内容),
+ * 经移植 handler 同款 {@link OrgDirectory} 解析为用户 id 列表,与客户库组织数据对照 SQL 核对。
+ *
+ * 这是验证/诊断口,非业务薄封装的一部分;直接解析单条配置项,绕过 BPMN 表达式串拼装,
+ * 便于对单一 type/content 精确对账。
+ */
+@RestController
+@RequestMapping("/api/flow/candidate")
+@Tag(name = "候选人解析(验证)", description = "候选人配置解析为用户 id,与组织库对账")
+public class CandidateController {
+
+ private final OrgDirectory orgDirectory;
+ private final TaskService taskService;
+ private final RuntimeService runtimeService;
+ private final RepositoryService repositoryService;
+
+ public CandidateController(OrgDirectory orgDirectory, TaskService taskService,
+ RuntimeService runtimeService, RepositoryService repositoryService) {
+ this.orgDirectory = orgDirectory;
+ this.taskService = taskService;
+ this.runtimeService = runtimeService;
+ this.repositoryService = repositoryService;
+ }
+
+ /** 单条配置项解析入参。 */
+ public static class ResolveRequest {
+ public String type;
+ public String content;
+ public String initiatorId;
+ public String initiatorDepart;
+ }
+
+ @PostMapping("/resolve")
+ @Operation(summary = "解析单条候选人配置", description = "type+content(+发起人/部门)→ 用户 id 列表(直查组织库)")
+ public List resolve(@RequestBody ResolveRequest req) {
+ return orgDirectory.assignmentUser(req.type, req.content, req.initiatorId, req.initiatorDepart);
+ }
+
+ @GetMapping("/org-by-depart")
+ @Operation(summary = "部门→组织", description = "view_depart_tree 查公司 id,对账用")
+ public ResponseEntity orgByDepart(String departId) {
+ String org = orgDirectory.getOrgIdByDepartId(departId);
+ return org != null ? ResponseEntity.ok(org) : ResponseEntity.notFound().build();
+ }
+
+ @GetMapping("/task-context")
+ @Operation(summary = "任务上下文", description = "给定 taskId,回显其流程实例的发起人/部门/项目变量,辅助候选人对账")
+ public Map taskContext(String taskId) {
+ Task t = taskService.createTaskQuery().taskId(taskId).singleResult();
+ if (t == null) {
+ return Map.of("error", "task not found: " + taskId);
+ }
+ String piId = t.getProcessInstanceId();
+ List defKey = new ArrayList<>();
+ var def = repositoryService.createProcessDefinitionQuery()
+ .processDefinitionId(t.getProcessDefinitionId()).singleResult();
+ if (def != null) {
+ defKey.add(def.getKey());
+ }
+ Map vars = runtimeService.getVariables(piId);
+ return Map.of(
+ "taskId", taskId,
+ "taskName", t.getName() == null ? "" : t.getName(),
+ "assignee", t.getAssignee() == null ? "" : t.getAssignee(),
+ "processInstanceId", piId,
+ "processDefinitionKey", defKey.isEmpty() ? "" : defKey.get(0),
+ "variables", vars);
+ }
+}
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/FlowController.java b/flowable-service/src/main/java/com/eip4/flowservice/api/FlowController.java
new file mode 100644
index 0000000..40619a6
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/FlowController.java
@@ -0,0 +1,150 @@
+package com.eip4.flowservice.api;
+
+import java.util.List;
+import java.util.stream.Collectors;
+
+import org.flowable.engine.HistoryService;
+import org.flowable.engine.RepositoryService;
+import org.flowable.engine.RuntimeService;
+import org.flowable.engine.TaskService;
+import org.flowable.engine.runtime.ProcessInstance;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+
+/**
+ * 工作流 REST 入口(薄封装 Flowable API,不做语义改写)。
+ *
+ * 提供:待办列表(按用户/候选组)、已办、发起、办理(complete)、挂起/激活、委托(delegate)。
+ * 仅转调 Flowable 引擎服务,出参经 DTO 收敛,避免引擎内部类泄漏。
+ */
+@RestController
+@RequestMapping("/api/flow")
+@Tag(name = "工作流", description = "Flowable 待办/已办/发起/办理/挂起激活/委托 薄封装")
+public class FlowController {
+
+ private final TaskService taskService;
+ private final RuntimeService runtimeService;
+ private final HistoryService historyService;
+ private final RepositoryService repositoryService;
+
+ public FlowController(TaskService taskService, RuntimeService runtimeService,
+ HistoryService historyService, RepositoryService repositoryService) {
+ this.taskService = taskService;
+ this.runtimeService = runtimeService;
+ this.historyService = historyService;
+ this.repositoryService = repositoryService;
+ }
+
+ @GetMapping("/tasks/todo")
+ @Operation(summary = "待办列表", description = "按 assignee(用户)或 candidateGroup(候选组)查活动待办;不传则查全部活动待办")
+ public List todo(
+ @RequestParam(required = false) String assignee,
+ @RequestParam(required = false) String candidateGroup,
+ @RequestParam(required = false) String candidateUser,
+ @RequestParam(defaultValue = "0") int firstResult,
+ @RequestParam(defaultValue = "50") int maxResults) {
+ var q = taskService.createTaskQuery().active();
+ if (assignee != null && !assignee.isBlank()) {
+ q = q.taskAssignee(assignee);
+ }
+ if (candidateGroup != null && !candidateGroup.isBlank()) {
+ q = q.taskCandidateGroup(candidateGroup);
+ }
+ if (candidateUser != null && !candidateUser.isBlank()) {
+ q = q.taskCandidateUser(candidateUser);
+ }
+ return q.orderByTaskCreateTime().desc()
+ .listPage(firstResult, maxResults)
+ .stream().map(TaskDto::of).collect(Collectors.toList());
+ }
+
+ @GetMapping("/tasks/todo/count")
+ @Operation(summary = "待办计数", description = "与 act_ru_task 直查对账用:按 assignee 计活动待办数")
+ public long todoCount(@RequestParam(required = false) String assignee) {
+ var q = taskService.createTaskQuery().active();
+ if (assignee != null && !assignee.isBlank()) {
+ q = q.taskAssignee(assignee);
+ }
+ return q.count();
+ }
+
+ @GetMapping("/tasks/done")
+ @Operation(summary = "已办列表", description = "按 assignee 查已完成的历史任务")
+ public List done(
+ @RequestParam(required = false) String assignee,
+ @RequestParam(defaultValue = "0") int firstResult,
+ @RequestParam(defaultValue = "50") int maxResults) {
+ var q = historyService.createHistoricTaskInstanceQuery().finished();
+ if (assignee != null && !assignee.isBlank()) {
+ q = q.taskAssignee(assignee);
+ }
+ return q.orderByHistoricTaskInstanceEndTime().desc()
+ .listPage(firstResult, maxResults)
+ .stream().map(TaskDto::of).collect(Collectors.toList());
+ }
+
+ @PostMapping("/process/start")
+ @Operation(summary = "发起流程", description = "按 processDefinitionKey 或 processDefinitionId 发起,可带 businessKey 与变量")
+ public ResponseEntity start(@RequestBody Requests.StartRequest req) {
+ ProcessInstance pi;
+ if (req.processDefinitionId != null && !req.processDefinitionId.isBlank()) {
+ pi = runtimeService.startProcessInstanceById(req.processDefinitionId, req.businessKey, req.variables);
+ } else if (req.processDefinitionKey != null && !req.processDefinitionKey.isBlank()) {
+ pi = runtimeService.startProcessInstanceByKey(req.processDefinitionKey, req.businessKey, req.variables);
+ } else {
+ return ResponseEntity.badRequest().build();
+ }
+ return ResponseEntity.ok(ProcessInstanceDto.of(pi));
+ }
+
+ @PostMapping("/tasks/{taskId}/complete")
+ @Operation(summary = "办理任务", description = "complete 任务,可带提交变量。挂起实例的任务会被引擎拒绝(语义回归)")
+ public ResponseEntity complete(@PathVariable String taskId, @RequestBody(required = false) Requests.CompleteRequest req) {
+ if (req != null && req.variables != null) {
+ taskService.complete(taskId, req.variables);
+ } else {
+ taskService.complete(taskId);
+ }
+ return ResponseEntity.noContent().build();
+ }
+
+ @PostMapping("/process/{processInstanceId}/suspend")
+ @Operation(summary = "挂起实例", description = "挂起后该实例任务不可办理")
+ public ResponseEntity suspend(@PathVariable String processInstanceId) {
+ runtimeService.suspendProcessInstanceById(processInstanceId);
+ return ResponseEntity.noContent().build();
+ }
+
+ @PostMapping("/process/{processInstanceId}/activate")
+ @Operation(summary = "激活实例", description = "解除挂起,恢复可办理")
+ public ResponseEntity activate(@PathVariable String processInstanceId) {
+ runtimeService.activateProcessInstanceById(processInstanceId);
+ return ResponseEntity.noContent().build();
+ }
+
+ @PostMapping("/tasks/{taskId}/delegate")
+ @Operation(summary = "委托任务", description = "委托给指定用户:assignee 变为受托人,owner 记原办理人")
+ public ResponseEntity delegate(@PathVariable String taskId, @RequestBody Requests.DelegateRequest req) {
+ if (req == null || req.delegateUserId == null || req.delegateUserId.isBlank()) {
+ return ResponseEntity.badRequest().build();
+ }
+ taskService.delegateTask(taskId, req.delegateUserId);
+ var t = taskService.createTaskQuery().taskId(taskId).singleResult();
+ return ResponseEntity.ok(t != null ? TaskDto.of(t) : null);
+ }
+
+ @GetMapping("/process-definitions/count")
+ @Operation(summary = "流程定义计数", description = "启动后定义加载自检(预期 1,509)")
+ public long processDefinitionCount() {
+ return repositoryService.createProcessDefinitionQuery().count();
+ }
+}
diff --git a/flowable-service/src/main/java/com/eip4/flowservice/api/FlowExceptionHandler.java b/flowable-service/src/main/java/com/eip4/flowservice/api/FlowExceptionHandler.java
new file mode 100644
index 0000000..0299ba3
--- /dev/null
+++ b/flowable-service/src/main/java/com/eip4/flowservice/api/FlowExceptionHandler.java
@@ -0,0 +1,46 @@
+package com.eip4.flowservice.api;
+
+import java.util.Map;
+
+import org.flowable.common.engine.api.FlowableException;
+import org.flowable.common.engine.api.FlowableObjectNotFoundException;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+
+/**
+ * Flowable 引擎异常 → 干净 HTTP 状态映射(薄层 API 不把引擎栈泄漏给调用方)。
+ *
+ *
+ * - {@link FlowableObjectNotFoundException} → 404;
+ * - "Cannot complete a suspended task" 等非法状态 → 409 Conflict
+ * (挂起实例拒绝办理的语义,见 P3 报告语义验证);
+ * - 其余 {@link FlowableException} → 400(多为入参/定义问题)。
+ *
+ */
+@RestControllerAdvice
+public class FlowExceptionHandler {
+
+ @ExceptionHandler(FlowableObjectNotFoundException.class)
+ public ResponseEntity