# P4 前置 —— projectRoleType 候选人解析闭环 实测报告 > 日期:2026-06-11 | 模块:`flowable-service`(端口 8089) > 任务:闭环 P3 最大缺口 projectRoleType(528 处表达式,~11%),并顺带评估/闭环长尾降级类型 > 验证场:本地 PG `localhost:5433` 库 `eip4flow` schema `eip3`(39 张 ACT_ 表,6.8.1.0 真实迁移数据, > 1,509 定义);业务组织库客户库副本 `192.168.20.68:5435` schema `eip3`(ceshi 只读,1,857 用户) > 前置:本报告承接 `P3流程服务实测报告.md`(OrgDirectoryJdbc 架构)与 `docs/迁移手册.md §6.5`(降级清单) --- ## 一、老系统语义侦察(以代码为准) ### 1.1 projectRoleType 不在 organize 的 AssignmentHandlerImpl,而在 wf 的 CandidateUsersHandler `framework/com.dsasp.server.organize/service/AssignmentHandlerImpl.assignmentUser(...)` **不含** projectRoleType 分支(已逐行核对,只到 formSpecifiedDimension 为止)。projectRoleType 是在 **`framework/com.dsasp.server.wf/user/assignee/CandidateUsersHandler.getCandidateUsers`** 里单独分派的(与 scriptUser/sameToTask/beforeTask\* 并列,先于通用 `assignmentHandler.assignmentUser` 兜底): ```java // CandidateUsersHandler.java(framework 原版,L127/L155-161) String projectId = ProcessEngines.getDefaultProcessEngine().getRuntimeService() .getVariable(execution.getProcessInstanceId(), ProcessCoreService.PROJECTID); ... else if (ProcessDefinitionService.PROJECTROLETYPE.equals(userProperty.getType())) { ProjectRoleUser projectRoleUser = (ProjectRoleUser) SpringBeanOsgiServices.getInstance().getBeanByName("projectRoleUser"); if (projectRoleUser != null) { users = projectRoleUser.getUserByProjectRole(projectId, userProperty.getContent()); } } ``` 同款分支另见 `com.dsasp.server.wf/user/listener/TaskCreateListener.java`(L245-250) 与 `com.dsasp.server.quartz/util/JobWorkEngine.java`(L130-133)——三处一致。 ### 1.2 关键侦察结论:framework 无 ProjectRoleUser 实现,是客户私有化扩展点 - `com.dsasp.server.common.user.service.ProjectRoleUser` 只有**接口**,全 eip3 源码树 `grep -rln "implements ProjectRoleUser"` **零命中**; - 也无任何 spring/OSGi xml 注册 `projectRoleUser` bean(`grep` 零命中); - 故 `getBeanByName("projectRoleUser")` 在基线 framework 返回 **null**(所以三处都有 `if(!=null)` 守卫)。 - 接口 javadoc 自述:`roles "true,false,true,...",需要获取的八大员,按枚举顺序判断是否需要获取该角色人员`。 **含义**:projectRoleType 的真正实现(含真实 SQL/表名)由**客户私有化插件**在部署期注入 OSGi 容器; 本机及仓库内**不存在该实现 jar/class**(`find / | grep getUserByProjectRole` 仅命中本服务自身产物)。 因此解析链的「真实 SQL」必须**从客户库数据模型反推 + 用真实流程任务实证**(见第二节), 不能照抄一个不存在的源文件。 ### 1.3 解析链(输入变量 → SQL → 输出) | 环节 | 内容 | |------|------| | **输入 1** | 流程变量 `PROJECTID`(`ProcessCoreService.PROJECTID`,存于 `act_ru_variable`/`act_ru_execution`) | | **输入 2** | 配置项 `content`:八大员 true/false 位枚举串,如 `"true,false,false,false,false,false,false,false"` | | **位序语义** | content 第 i 位(1-based)为 `true` ⇒ 需要角色编号 i 的人员;位枚举长度随流程版本增长(实测 8/9/11 位) | | **SQL** | `SELECT distinct userid FROM pm_project_user WHERE pm_projectid = ? AND isactive = 1 AND role IN ()` | | **输出** | 该项目下这些角色的在用用户 id 列表(去 padding、去重) | > 对齐项:framework `ProjectRoleUser.getUserByProjectRole(projectId, roles)` 契约的两个入参 > 即 `pm_projectid` 与位枚举;位序↔role 编号映射经第二节客户库实证锁定。 --- ## 二、客户库数据模型验证(只读) 连接 `192.168.20.68:5435` schema `eip3`(ceshi 只读)。 ### 2.1 表选型:pm_project_user 是 canonical 项目角色用户表 候选表三张,实测对比后锁定 **`pm_project_user`**: | 表 | 行数 | 角色列 | role 取值分布 | 结论 | |------|-----:|--------|--------------|------| | **`pm_project_user`** | 1615 | `role`(int) | 1–8 各有 + 19/20/1000 扩展位 | ✅ **选用**,覆盖八大员全位序 + 变长扩展位 | | `view_projectuser` | 849 | `roleid`(int) | 仅 1/2/3/5 | ❌ 稀疏,多数项目无数据 | | `pm_projectuserrecord` | 151 | `roleid`(int) | — | ❌ 是变更/历史记录表,非当前态 | `pm_project_user` 列:`pm_projectid`、`userid`、`role`(int)、`isactive`(int,全为 1)。 `pm_projectid`/`userid` 均 `bpchar(36)`:32 字符 hex id 补 4 空格至 36(与手册 §6.7/§5.32 padding 同源)。 PG `char` 比较忽略尾随空格,故 `pm_projectid = '<32字符>'` 等值匹配成立;返回的 `userid` 需 `trim` 去 padding。 ### 2.2 三个(实为五个)真实含 projectRoleType 的流程任务,手工按解析链 SQL 算预期 从 `act_ru_task ⋈ act_re_procdef`(定义所属 deployment 的 BPMN 含 projectRoleType)筛出 **34 个真实在办任务**, 逐个从 BPMN(`act_ge_bytearray`)反转义出该 `task_def_key` 的 projectRoleType `content`,取实例 `PROJECTID`, 按 §1.3 SQL 手工算预期候选人: | # | 任务 id | 任务名 | PROJECTID | content(位序→role) | 手工 SQL 预期候选人 | |---|--------|--------|-----------|---------------------|---------------------| | A | 192023 | 项目经理 | `80d698eb-…-44dc9dbd2dea` | `true,…`→role 1 | `672de215-…-afbf367bd9ef` | | B | 541357 | 项目经理 | `402881344fac0e280150b28dc4104d28` | role 1 | `402881343df56678013e011c8b99065d` | | C | 65647 | 项目经理 | `40288034449a42f60144aa675d750463` | role 1 | `402881343827d0a101382be781150013` | | D | 20361822 | 财务总监 | `ef15252e-…-350d85ce20c2` | role 1 | `d7dd95cb-…-c9e759a12fd5` | | E | 10909062 | 项目工程师交底 | `324a527c-…-83a2bfdbbd4f` | role 2 | **空**(该项目仅 role 1 有数据,BPMN 配 role 2 候选 → 数据漂移,忠实返回空) | > 位序↔role 映射实证:content `true,false,…` 全部对应 `role=1`(项目经理/项目负责人/财务总监); > `false,true,…` 对应 `role=2`。task 名「项目经理」与 role=1 语义一致,交叉印证位序即 1-based 角色编号。 --- ## 三、实现 ### 3.1 projectRoleType 闭环(`OrgDirectoryJdbc.getUsersByProjectRole`) `flowable-service/src/main/java/com/eip4/flowservice/org/OrgDirectoryJdbc.java`: - 去掉原 P3 的 WARN 降级路径(`System.out.println("[WARN] projectRoleType …")` + 返回空); - 新增 `parseProjectRoles(content)`:位枚举 → 1-based role 编号列表(`"true,false,true"`→`[1,3]`); - 参数化直查:`SELECT distinct userid FROM pm_project_user WHERE pm_projectid=? AND isactive=1 AND role IN (?,…)`, `userid` 去 padding(trim)+ `LinkedHashSet` 去重; - 保留 `ProjectRoleResolver` 钩子作**优先级最高的覆盖位**:客户私有化注入自有 `ProjectRoleUser` 时优先委托, 否则走本直查(语义对齐 framework 契约)。 ### 3.2 长尾闭环(性价比高者一并实现) | 类型 | 频次 | 闭环方式 | 落点 | |------|-----:|---------|------| | **initiatorDepartManager** | 24 | `getMainDepart(initiatorId)` → `findDepartManager(mainDepart)`。MASTERDEPART 虚拟列经 **`view_sys_user.masterdepart` 等价子查询**(`sys_positionuser.ismaster=1` → `sys_position.parentdepartid`)落地;部门负责人取 **`sys_depart.leader`** 物理列(实证存在) | `OrgDirectoryJdbc.assignmentUser` 新增分支 + `getMainDepart`/`findDepartManager` | | **fixedDimension** | 12 | `findUsersByDimenDepartPositionTypes(curDepart, dimension, positionTypes, 0)`:经 **`view_sys_dimensiondepart`**(维度树,`parentdepartids` 祖先链)定位本部门,本部门有该岗位类别岗位则返回,否则按维度链**向上回溯**(direction=0,framework 全部调用点即 0;向下分支原版即 TODO 未实现,故不实现) | `OrgDirectoryJdbc.assignmentUser` 新增分支 + `findUsersByDimenDepartPositionTypes` | | **sameToTask** | 5 | `getSpecialActivityProcessor(piId, content)`:经 `historyService` 取流程实例下**已结束 userTask 按结束时间倒序第一条的 assignee**(content 为指定活动 id,空则取最近)。逐条对齐 framework `ProcessCoreServiceImpl.getSpecialActivityProcessor` | `CandidateUsersHandler` 新增 historyService 解析(不经 OrgDirectory,因需历史栈) | `CandidateUsersHandler` 同时把 `beforeTaskLeader`/`beforeTaskDepartManager`(实测 BPMN **0 处**,防御性接入) 映射到 `initiatorLeader`/`initiatorDepartManager` 语义、以前序处理者作入参,与 framework 第 5 形参复用一致。 ### 3.3 验证口新增 `CandidateController` 新增 `GET /api/flow/candidate/project-role?projectId=&content=`(对账用,调 `getUsersByProjectRole`)。 ### 3.4 改动文件清单 | 文件 | 改动 | |------|------| | `…/org/OrgDirectoryJdbc.java` | projectRoleType 直查 + initiatorDepartManager/fixedDimension 分支 + getMainDepart/findDepartManager/findUsersByDimenDepartPositionTypes/parseProjectRoles | | `…/wf/user/assignee/CandidateUsersHandler.java` | sameToTask/beforeTask\* 经 historyService 闭环 + getSpecialActivityProcessor/resolveHistoryService | | `…/api/CandidateController.java` | `GET /project-role` 验证端点 | | `…/test/.../OrgDirectoryJdbcTest.java` | +6 测(projectRoleType 直查/位序解析/全 false/客户私有覆盖、initiatorDepartManager、fixedDimension),改 2 个旧降级断言 | | `…/test/.../CandidateUsersHandlerTest.java` | +2 测(sameToTask 有/无前序处理者) | --- ## 四、验证证据 > 8089 起本服务(本地 eip4flow + 客户库组织只读),8084 未动。 ### 4.1 projectRoleType:REST `/project-role` == 手工 SQL 预期(5 例,含数据漂移空例) | # | 任务 | content | REST 返回 | 手工 SQL 预期 | 一致 | |---|------|---------|-----------|--------------|:---:| | A | 192023 项目经理 | role 1 | `["672de215-…e393…afbf367bd9ef"]` | 同 | ✅ | | B | 541357 项目经理 | role 1 | `["402881343df56678013e011c8b99065d"]` | 同 | ✅ | | C | 65647 项目经理 | role 1 | `["402881343827d0a101382be781150013"]` | 同 | ✅ | | D | 20361822 财务总监 | role 1 | `["d7dd95cb-…-c9e759a12fd5"]` | 同 | ✅ | | E | 10909062(role 2,漂移)| role 2 | `[]` | 空 | ✅ | 另:多角色 content `true,…,true`(role 1+8,项目 `40288034474c75d9…073aa1` 同一人兼多角色)REST 返回 **去重后 1 个 userid**,验证 `LinkedHashSet` 去重生效。 ### 4.2 长尾闭环 REST 实证 | 类型 | 入参 | REST 返回 | 手工 SQL 预期 | 一致 | |------|------|-----------|--------------|:---:| | initiatorDepartManager | initiatorId=`402880343fe2166f013fea6aaf4b0237` | `["402881343827d0a101382be6b8fb0012"]` | `view_sys_user.masterdepart`→`sys_depart.leader` 同 | ✅ | | initiatorDepartManager | initiatorId=`4028803441ba79140141deee59080f5a` | `["402881343826dc6f0138276705120015"]` | 同 | ✅ | | initiatorDepartManager | 不存在用户 | `[]` | 空 | ✅ | | fixedDimension | content=`administrative,73a88072-…-6197608a1726`,depart=`40288034474c75d90147b375c46a191c` | `["003aae9e-…","40288034474c75d9014786212e7509da"]` | 本部门 ptype 岗位人员同 | ✅ | > sameToTask:当前数据集无该 5 处 demo 活动(`sid-233550C4…`)的运行时历史(库内 0 条), > 无可对账的真实运行实例;其 historyService 查询语义经单测(桩历史栈)+ framework 逐字节对齐双重保证, > 与任务「能便宜闭环」尺度一致。 ### 4.3 回归:P3 已验证类型不破 | 类型 | 入参(取自 P3 报告 3.1) | REST 返回 | 一致 | |------|------|-----------|:---:| | position | `fb2ea316-43c2-4d21-946e-3bb9a3052ce8` | `["6d84e817-…-873a9577e393"]`(== P3 3.1) | ✅ | | position(3 人岗位)| `402881343827d0a1013830922bee005c` | 3 个 userid(== P3:顾鼎/顾建方/奚岳云) | ✅ | | user | `u-aaa,u-bbb` | `["u-aaa","u-bbb"]`(直返) | ✅ | ### 4.4 单测 + 全模块 + ArchUnit | 项 | 命令 | 结果 | |----|------|------| | flowable-service 单测 | `mvn test`(本模块)| **33 passed**(原 26 + **新增 7**,0 fail):OrgDirectoryJdbcTest 12→17、CandidateUsersHandlerTest 5→7、FlowControllerTest 9 不变 | | 全反应堆 + ArchUnit | `mvn test`(整库)| **BUILD SUCCESS**,`ArchitectureRulesTest` 绿(保真层 CandidateUsersHandler 仍 **零 `import com.eip4`**,自查 grep=0),各模块全绿 | | 启动 | `java -jar`(8089)| 1.94s 启动,v6+v5 双引擎,零错;验证毕已 `kill` 8089 | --- ## 五、长尾处置结论 | 类型 | 频次 | P3 状态 | P4 处置 | 性价比说明 | |------|-----:|:------:|---------|-----------| | **projectRoleType** | 528 | 降级 WARN | ✅ **直查闭环**(pm_project_user)| 主目标,5 例真实任务对账一致 | | **initiatorDepartManager** | 24 | 降级(虚拟列)| ✅ **直查闭环** | 便宜:MASTERDEPART 经 `view_sys_user` 视图落地,leader 物理列存在;2 例真实用户对账一致 | | **fixedDimension** | 12 | 降级(虚拟列/维度树)| ✅ **直查闭环** | 中等:`view_sys_dimensiondepart` 视图提供祖先链,复用 findUsersByPositions;1 例真实对账一致 | | **sameToTask** | 5 | 降级(活动栈)| ✅ **historyService 闭环** | 便宜:Flowable `HistoricActivityInstanceQuery` 原生支持,逐条对齐 framework;当前数据集无运行时实例,单测+parity 保证 | | **scriptUser** | 26 | 降级(JUEL)| ⛔ **保持降级(写方案)** | 见下:工作量大且风险高,不便宜 | ### 5.1 scriptUser 不闭环的理由与实现方案(任务要求「工作量大就只写方案」) **为何不便宜**: - framework 原版用 `Context.getProcessEngineConfiguration().getScriptingEngines().evaluate(content, "juel", (ExecutionEntity) execution)`, **必须有活的 `ExecutionEntity`**(v6)/v5 execution 才能求值;本 handler 形参 `execution` 是 `Object` (v5/v6 双类型,仅安全取 processInstanceId),拿不到可直接喂给脚本引擎的实体; - content 实测为 `${users}`/`${WRITERS}`/`${RECEIVERS}`/`${APPLYUSERS}` 等读流程变量的 JUEL; 这些变量在 `act_ru_variable` 实测类型分布:**serializable 15 / null 14 / string 7**—— **serializable 是 Java 序列化的 ArrayList**,反序列化依赖原 framework 类在 classpath,独立服务无; - 即接一个表达式引擎,serializable 变量这条主路仍取不回 List,收益打折,风险(误解析/类加载)高。仅 26 处(0.54%)。 **实现方案(待保真层接入或 P3-4 聚合时落地)**: 1. 让 `CandidateUsersHandler.getCandidateUsers` 在 v6 路径下拿到 `DelegateExecution`/`ExecutionEntity` (由 Flowable 在表达式求值时注入,而非反射 id); 2. scriptUser 分支调 `processEngineConfiguration.getExpressionManager().createExpression(content).getValue(execution)` (Flowable 6.8.1 内置 JUEL,无需 Nashorn),结果按 `List`/`String` 收敛为 userid 集(对齐原版收口逻辑); 3. serializable 变量:约束业务侧把用户集存为 `string`(逗号分隔)或 Flowable 原生 `json`, 避免依赖 framework 私有类反序列化;存量 serializable 由数据迁移期规整(属 P3-4/保真层议题)。 4. 工作量评估:表达式引擎接线 0.5d + execution 上下文贯通(与 v5 兼容层交互)0.5d + serializable 规整策略(跨团队)—— 非「顺手」量级,故本次留方案。 --- ## 六、剩余降级类型最终清单(手册 §6.5 缺口表据此更新) | 类型 | 频次 | 占比 | 状态 | |------|-----:|-----:|------| | position / user / formSpecifiedDimension / depart / initiator | 4250 | 87.7% | ✅ P3 已覆盖 | | projectRoleType | 528 | 10.9% | ✅ **P4 闭环** | | initiatorDepartManager | 24 | 0.5% | ✅ **P4 闭环** | | fixedDimension | 12 | 0.25% | ✅ **P4 闭环** | | sameToTask | 5 | 0.10% | ✅ **P4 闭环** | | **scriptUser** | **26** | **0.54%** | ⛔ **唯一剩余降级**(WARN,方案见 §5.1)| - **总占比**:覆盖 4819 / 4845 = **99.46%**;剩余降级仅 scriptUser **0.54%**。 - 较 P3(覆盖 ~91%、5 类降级):**降级类型从 5 类收敛到 1 类,覆盖率 91%→99.46%**。 --- ## 七、收尾 - 8089 验证完成后已 `kill`,端口释放(8084 全程未动)。 - 业务组织库全程**只读**(biz 数据源 `read-only`),无任何写操作;flow 库无数据变更。 - git 仅 add 本任务自有文件(见提交记录)。