Files
eip4-platform/flowable-service/P4前置-projectRoleType闭环报告.md
zhengwr 3a13c50a01 P4前置: 闭环 flowable-service projectRoleType 候选人解析 + 长尾收敛
侦察老系统语义(以代码为准):projectRoleType 在 com.dsasp.server.wf
CandidateUsersHandler 单独分派(非 organize 的 AssignmentHandlerImpl),
调客户私有 ProjectRoleUser.getUserByProjectRole(projectId, "八大员位枚举");
framework 无该实现(项目定制 OSGi 扩展点)。解析链经客户库数据模型反推 +
真实流程任务实证锁定:content 位序(1-based)即 pm_project_user.role。

实现:
- OrgDirectoryJdbc.getUsersByProjectRole 去 WARN 降级,参数化直查
  pm_project_user(pm_projectid + role IN(true 位序) + isactive=1),
  保留 ProjectRoleResolver 钩子作客户私有覆盖位;
- 顺带闭环长尾: initiatorDepartManager(view_sys_user.masterdepart 子查询
  →sys_depart.leader)、fixedDimension(view_sys_dimensiondepart 维度树
  向上回溯)、sameToTask(historyService 取前序 userTask assignee);
- CandidateController 加 GET /project-role 对账端点。

验证(8089 起本地 eip4flow + 客户库只读):5 个真实 projectRoleType 任务
REST==手工 SQL(含数据漂移空例);initiatorDepartManager/fixedDimension
真实数据对账一致;P3 position/user 回归不破;新增 7 单测(原 26→33),
全反应堆 mvn test + ArchUnit 绿。

缺口:降级类型 5 类→1 类(仅 scriptUser 26 处),覆盖率 91%→99.46%。
scriptUser 需活的 ExecutionEntity + 反序列化变量,超独立服务边界,留方案。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 15:41:57 +08:00

17 KiB
Raw Permalink Blame History

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 兜底):

// 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 (<true 的位序集合>)
输出 该项目下这些角色的在用用户 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 本任务自有文件(见提交记录)。