Files
eip4-platform/platform-flow-gateway/P3网关实测报告.md
zhengwr ba6e7559fa P4-6: platform-flow-gateway 待办→业务页映射(tablename→templateId→pageUrl)
- 侦察口径:sys_entity+view_templateentity+view_template 两步映射;
  多模板优先级 type=7(表单)>1(列表)>其余升序,同 type 按 templateid 字典序取首个
- 新建 PageTemplateService:findTemplateId() 查只读客户库,
  @Cacheable("pageTemplateByTable") Caffeine TTL=10min/maxSize=2000
- FlowGatewayConfig 启用 @EnableCaching + flowGatewayCacheManager(Caffeine)
- TodoItem 增加 pageTemplateId/pageUrl/pageUrlReason;
  查不到映射时 pageUrl=null+reason,前端据此禁用跳转(优雅降级)
- TodoAggregator 注入 PageTemplateService,aggregate 逐条 fillPageTemplate
- PageTemplateMappingTest 10 单测;TodoAggregatorTest 补 @Mock PageTemplateService
- 验证:真实用户(829cdcca)3 条待办带出 templateId=7042cb37(PM_SAFE_CLARIFICATION/安全技术交底),
  与客户库直查一致;全反应堆 31+ArchUnit 绿

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 16:52:50 +08:00

19 KiB
Raw Permalink Blame History

P3-4 单体侧流程网关 实测报告

日期:2026-06-11 | 模块:platform-flow-gateway(单体 platform-app 内的 Flowable 客户端 + 待办聚合 + 事件回写) 任务:P3-4 —— FlowableClient(REST 客户端 + 超时/重试/熔断降级)、待办聚合 API(经 platform-app 暴露)、 事件回写(complete 后按老系统 ProcessCoreServiceImpl/WfChangeStatus 语义更新 SYS_DATASTATUS) 验证场:flowable-service 起 8089(连本地 eip4flow.eip3 6.8.1 真实迁移数据 + 客户库副本 192.168.20.68:5435 组织只读); platform-app 起 8090(local profile,连本地 eip4m0,可写);8084 未动 架构定位:引擎在独立 flowable-service(四进程之一),gateway 只做 REST 客户端(架构第三节)


一、模块结构

platform-flow-gateway/                       单体 platform-app 内组件(com.eip4.platform.flowgateway)
├── pom.xml                                  依赖 platform-legacy-core(loadPOJO 业务摘要)+ platform-auth(JWT ctx)
│                                            + spring-boot-starter-web/jdbc + springdoc
├── src/main/java/com/eip4/platform/flowgateway/
│   ├── client/                              ★ Flowable REST 客户端
│   │   ├── FlowGatewayProperties            配置(eip4.flow.base-url 默认 http://localhost:8089 / 超时 / 重试)
│   │   ├── FlowGatewayConfig                RestClient bean(超时落到请求工厂)
│   │   ├── FlowableClient                   超时/重试(仅连接级)/熔断降级;调 8089 待办/已办/办理/发起/查实例
│   │   ├── FlowServiceUnavailableException  引擎不可达 → 503 语义载体
│   │   ├── FlowRemoteException              引擎在线但拒绝(4xx/5xx)→ 透传原状态码
│   │   ├── FlowTaskDto / ProcessInstanceDto 出参契约(贴 flowable-service DTO)
│   ├── aggregate/                           ★ 待办聚合
│   │   ├── TodoItem                         聚合条目:流程字段 + 业务摘要
│   │   ├── BusinessSummaryService           businessKey → SYS_DATASTATUS.tablename → loadPOJO 标题字段;全程降级兜底
│   │   └── TodoAggregator                   调 client + 逐条拼业务摘要
│   ├── writeback/
│   │   └── StatusWriteback                  ★ 事件回写(对齐 WfChangeStatus + passProcess 语义)
│   └── web/                                 ★ 经 platform-app 暴露的聚合 API
│       ├── TodoController                   GET /api/todo、GET /api/done、POST /api/task/{id}/complete、POST /api/process/start
│       ├── GatewayRequests                  入参 DTO(办理/发起)
│       └── FlowGatewayExceptionHandler      503 熔断 + 业务错透传
├── src/main/resources/bootstrap/
│   └── bootstrap-datastatus.sql             本地回写验证自举(SYS_DATASTATUS 表 + 测试实体行)
└── src/test/java/  (21 单测)
    ├── FlowableClientTest          5(重试耗尽降级 503 / 409 透传不重试 / 待办解析 / 候选组多值 / 404→null)
    ├── BusinessSummaryServiceTest  5(businessKey 空 / 无映射降级 / loadPOJO 异常降级 / 标题字段剔系统列 / null 降级)
    ├── TodoAggregatorTest          4(拼接业务摘要 / 摘要拼不到降级 / 已办拼接 / 空列表)
    └── StatusWritebackTest         7(未结束→2 / 结束→3 / null 不写 / 已达 3 不回退 / upsert UPDATE 命中或 0 行 INSERT / 空 key)

ArchUnit 纪律保持:gateway 在 com.eip4.platform.flowgateway,只 import com.eip4.* / com.dsasp.*(允许方向), 无反向依赖;ArchitectureRulesTest(platform-app)绿。

二、REST 契约

2.1 gateway 对外(经 platform-app 暴露,JWT 取 userId/roles)

方法 路径 说明
GET /api/todo?firstResult=&maxResults= 当前用户待办(assignee=JWT userId,候选组=JWT roles);聚合业务摘要
GET /api/done?firstResult=&maxResults= 当前用户已办;聚合业务摘要
POST /api/task/{id}/complete 办理 + 回写;body 可带 {variables, businessKey, processInstanceId, tableName}
POST /api/process/start 发起;body `{processDefinitionKey

熔断:引擎不可达 → 503 {"status":503,"error":"FLOW_SERVICE_UNAVAILABLE","message":"工作流引擎服务暂不可达,请稍后重试"}; 业务错(如挂起拒办 409)→ 透传原状态码 FLOW_REMOTE_ERROR。

2.2 gateway 调 flowable-service(8089;含本任务对 flowable-service 的契约增强)

方法 路径 备注
GET /api/flow/tasks/todo?assignee=&candidateGroup=&candidateUser=&firstResult=&maxResults= 出参新增 businessKey(从运行时实例补全)
GET /api/flow/tasks/done?assignee=&firstResult=&maxResults= 出参新增 businessKey(从历史实例补全)
POST /api/flow/tasks/{id}/complete body {variables}
POST /api/flow/process/start
GET /api/flow/process/{id} 新增:查实例(运行中 ended=false / 已结束历史 ended=true / 不存在 404),供办理后判定流程是否结束

契约增强原因(手册 §6.8):Flowable 6.8.1 TaskInfo 无 getBusinessKey()(javap 核实),task 无从直接带 businessKey; 由查询侧从 process instance 反查补全。flowable-service 26 单测仍全绿(改动未破契约)。

三、验证证据摘要

# 验证项 方法 结果
1 flowable-service 起 8089 连本地 eip4flow + 客户库只读,2.4s 启动 ✅ 定义计数 1509
2 platform-app 起 8090 local profile 连 eip4m0,1.6s 启动 ✅ /api/todo 200
3 待办聚合数=直查一致 真实用户 829cdcca,JWT userId 调 8090 /api/todo vs 8089 直查 count ✅ 见 3.1,双口径=4 精确相等
4 业务摘要拼接正确 本地构造 SYS_DATASTATUS 映射 + 业务表行,验证 businessKey→标题字段 ✅ 见 3.2,拼到 SYS_USERGROUP + NAME 等标题字段
5 优雅降级共存 同一待办列表中无本地映射的 businessKey ✅ 见 3.2,3 条降级为仅流程字段(businessTable=null)与拼接条目共存
6 熔断 503 kill 8089 后调 8090 /api/todo ✅ 见 3.3,HTTP 503 干净 JSON,platform-app 进程存活不崩
7 事件回写 本地构造 datastatus=1,经 8090 complete(流程结束)回写 ✅ 见 3.4,SYS_DATASTATUS 1→3,引擎侧实例确结束
8 全模块 mvn test + ArchUnit 整反应堆 ✅ BUILD SUCCESS;gateway 21 单测 + flowable-service 26 + ArchitectureRulesTest 绿

3.1 待办聚合数 == flowable-service 直查(真实用户 829cdcca)

JWT(userId=829cdcca-4e07-4e12-9c8e-a3da2c105e31)调 8090 /api/todo,与 8089 /tasks/todo/count 直查对账:

口径 数
8089 直查 /tasks/todo/count?assignee=829cdcca-... 4
8090 聚合 /api/todo(JWT userId=829cdcca) 4

精确相等。首条流程字段完整(taskId/taskName=接收交底(项目部)/assignee/businessKey 全有)。

3.2 业务摘要拼接正确 + 优雅降级共存

本地构造(eip4m0 可写):取真实待办首条 businessKey e8a37edb-..., 在 eip4m0 造 SYS_DATASTATUS(businesskey=e8a37edb, tablename=SYS_USERGROUP, datastatus=2) + SYS_USERGROUP 业务行(主键=e8a37edb, name=安全技术交底单-端到端摘要验证)。8090 /api/todo 该条:

businessKey   = e8a37edb-15f0-46fb-973d-68888a75b6fb
businessTable = SYS_USERGROUP                       (经 SYS_DATASTATUS.tablename 映射)
businessSummary= {NAME:"安全技术交底单-端到端摘要验证", DESCRIPTION:"...", GROUPTYPE:1, ORDERASC:1}
                                                    (loadPOJO 标题字段;主键 SYS_USERGROUP_ID 与系统列 CREATEBY/CREATETIME 已剔除)

同一响应另 3 条 businessKey 无本地映射(其业务表在客户库,本地 eip4m0 无)→ businessTable=null、businessSummary={} —— 优雅降级为仅流程字段,与拼接成功条目在同一列表共存。这同时证明: 聚合层业务摘要数据源 = platform-app 主 JdbcTemplate(本地 eip4m0;生产/默认 profile 即客户库只读),拼不到不拖垮列表。

3.3 熔断:kill 8089 → /api/todo 503

精确 kill <flowable PID> 停 8089(platform-app 进程保留),调 8090:

HTTP 状态码 = 503
{"error":"FLOW_SERVICE_UNAVAILABLE","message":"工作流引擎服务暂不可达,请稍后重试","status":503}
platform-app 进程存活(引擎宕机不拖垮单体,明确 503 语义而非 500 堆栈)

FlowableClient 连接级失败重试(maxRetries 默认 2,带退避)→ 耗尽抛 FlowServiceUnavailableException → @RestControllerAdvice 映射 503。

3.4 事件回写:本地 complete → SYS_DATASTATUS 1→3

阶段 eip4m0 SYS_DATASTATUS(e8a37edb) eip4flow 实例 20334081
complete 前 datastatus=1(本地构造为未提交,演示状态推进) 活动任务 1 个(20334106),ended=false
经 8090 /api/task/20334106/complete(带 businessKey+processInstanceId) 响应 {completed:true, processEnded:true, statusWritten:true} —
complete 后 datastatus=3(通过/已归档) 剩余活动任务 0,act_hi_procinst 已结束(2026-06-11 15:08:24)

回写算法忠实复刻 passProcess:流程结束 ended=true → 目标 STATUS_PASS(3);守卫 oldstatus(1) < target(3) 通过 → 回写。 守卫负向(oldstatus=null 不凭空插 / oldstatus 已达 3 不回退)由 StatusWritebackTest 7 单测覆盖。

四、回写语义结论(侦察老系统后照原语义实现)

侦察 framework com.dsasp.server.wf.service.ProcessCoreServiceImpl(2112 行)+ WfChangeStatus + ChangeStatus 接口:

  • DATASTATUS 值语义(ProcessCoreService 常量,即盘点报告所指 DATASTATUS=3「已归档/在批」一类): STATUS_NOSUBMIT=1 未提交 / STATUS_PROCESSING=2 处理中(在批/审批中) / STATUS_PASS=3 通过(已归档/审批通过) / STATUS_NOPASS=4 未通过 / STATUS_RESUBMIT=5 重新提交 / STATUS_INVALID=6 作废。
  • 办理(passProcess)回写(本任务 complete 对齐):complete 后取流程实例 businessKey 与 TABLENAME 变量, oldstatus = getStatus(businessKey);isEnd(实例已结束) ? STATUS_PASS(3) : STATUS_PROCESSING(2); 仅当 oldstatus != null && oldstatus < status 才 UpdateStatus(单调递增守卫)。
  • upsert(WfChangeStatus.UpdateStatus):先 UPDATE SYS_DATASTATUS SET DATASTATUS=? WHERE BUSINESSKEY=?, 影响 0 行则 INSERT(BUSINESSKEY, TABLENAME, DATASTATUS)。本任务参数化占位(原版裸拼,收敛注入面,语义不变)。
  • businessKey → tablename 映射口径:SYS_DATASTATUS 有 tablename + businesskey 列 (framework ProcessCoreServiceImpl 第 2018 行 select tablename,businesskey from SYS_DATASTATUS where businesskey=...); 聚合层据此把流程任务连接到业务摘要(loadPOJO 只读标题字段)。

五、数据变更登记

纪律:本地库验证,客户库只读;每次写前记录现状,本地数据可重复构造。

操作 目标库.行 写前 写后 性质
bootstrap 自举 eip4m0.SYS_DATASTATUS(表) 表不存在 建表 + 2 测试行(P34-WB-TEST-0001=2 / 0002=3) 本地自举,可重复执行
业务摘要构造 eip4m0.SYS_USERGROUP / SYS_DATASTATUS(e8a37edb) 无 映射 SYS_USERGROUP + 业务行 本地构造,演示拼接
真实 complete eip4flow 任务 20334106 / 实例 20334081 活动(ended=false) 已办理,流程结束 不可逆(complete 推进+落历史);eip4flow 为迁移数据副本,非客户生产库
回写 eip4m0.SYS_DATASTATUS(e8a37edb) datastatus=1 datastatus=3 本地可写
  • 客户库(192.168.20.68:5435)全程只读:flowable-service 业务组织库连接 read-only,gateway 业务摘要数据源在本地 eip4m0。
  • 真实 complete 仅在本地 eip4flow 迁移副本上做一条(回写验证核心交付,需真实流程结束以触发 STATUS_PASS 分支); P3-1/2 报告出于「逐字节还原」洁癖未做真实 complete,P3-4 回写验证需要,故在迁移副本(非客户生产)上执行一条并完整记录。

六、坑列表(已写入手册 §6.8 / §6.9)

  1. §6.8 Flowable 6.8.1 Task 接口无 businessKey:TaskInfo 无 getBusinessKey()(javap 核实); 待办聚合 task↔业务数据连接须由 flowable-service 查询侧从 process instance 反查补全 (TaskDto 加 businessKey 字段;新增 GET /api/flow/process/{id} 查实例)。
  2. §6.9 网关 503 熔断 + 回写守卫:引擎不可达 → 503 语义(非 500 堆栈),连接级重试 + 业务错透传; 回写守卫 oldstatus<status 单调递增,SYS_DATASTATUS 无主键(对齐 §7.2 客户库口径), bootstrap-datastatus.sql 随模块提供;本地库验证,客户库只读。

七、收尾

  • 验证完成后 kill 本任务起的 8089 / 8090(8084 未动)。
  • 客户库零写入;本地 eip4m0 测试数据为可重复构造的自举工件(bootstrap-datastatus.sql)。
  • eip4flow 迁移副本上 1 条真实 complete 已完整登记(实例 20334081 结束)。

P4-6 增补:待办→业务页映射(tablename → templateId → pageUrl)

日期:2026-06-11 | 任务:P4-6 —— TodoItem 增加 pageTemplateId/pageUrl 字段; 映射口径侦察;Caffeine 缓存;单测 ≥4;真实待办验证

P4-6.1 映射规则结论(侦察客户库 view_templateentity + view_template + sys_entity)

两步映射:

  1. SYS_DATASTATUS.tablename → sys_entity.sys_entity_id(entityid):UPPER(tablename) 归一大小写
  2. entityid → view_templateentity.templateid(经 view_template.type 优先级筛选,取最优一条)

多模板优先级规则(TemplateType 枚举语义 + 待办填写场景):

优先级 type 名称 理由
0(最优) 7 EDITFORM 表单模板 待办详情 = 填写/审批页面,表单模板最贴近
1 1 GRID 列表模板 无专属表单时退回列表页
2–5 3/4/6/5 树/树列表/组合/日历 功能性模板,语义次之
6–7 100/101 弹窗选择 非主页面,兜底
8 200 报表模板 报表展示,非流程业务页

同 type 多条时按 templateid 字典序取首个(稳定可重复)。

数据佐证(客户库直查):

  • OA_SEALUSEAPPLY:有 type=7「填写印章使用申请」→ 优先选 type=7 ✅
  • PM_SAFE_CLARIFICATION:仅 type=1「安全技术交底」→ 退回 type=1 ✅
  • PM_CONTRACTACCOUNTS:仅 type=1「项目分包合同决算」→ type=1 ✅

P4-6.2 实现要点

文件 变更
pom.xml 新增 spring-boot-starter-cache + caffeine 依赖
FlowGatewayConfig @EnableCaching + flowGatewayCacheManager(Caffeine,TTL=10min,maxSize=2000)
PageTemplateService(新建) findTemplateId(tableName) 查客户库两步映射,@Cacheable("pageTemplateByTable");buildPageUrl() 静态工具
TodoItem 新增 pageTemplateId/pageUrl/pageUrlReason 三字段
TodoAggregator 注入 PageTemplateService;fillPageTemplate() 填充新字段;降级写 pageUrlReason

降级策略(优雅降级,前端禁用跳转):

  • businessTable=null(SYS_DATASTATUS 无映射)→ pageUrl=null,pageUrlReason="businessTable 未映射,无法定位模板"
  • sys_entity/view_templateentity 找不到模板 → pageUrl=null,pageUrlReason 含表名
  • 数据库异常 → PageTemplateService 内部 catch,返回 Optional.empty(),降级同上

P4-6.3 真实待办验证

服务:flowable-service 8089(本地 eip4flow 迁移数据)+ platform-app 8090(local profile,eip4m0)

用户 829cdcca-4e07-4e12-9c8e-a3da2c105e31(wangwu)待办 3 条,全部 businessKey → PM_SAFE_CLARIFICATION:

taskId businessKey businessTable pageTemplateId pageUrl
20334061 4f89dbc4-... PM_SAFE_CLARIFICATION 7042cb37-9581-4dfe-bb9f-18ed0e0b6b53 /page/7042cb37-...
20333989 36e9763f-... PM_SAFE_CLARIFICATION 7042cb37-9581-4dfe-bb9f-18ed0e0b6b53 /page/7042cb37-...
20329569 1ef1559b-... PM_SAFE_CLARIFICATION 7042cb37-9581-4dfe-bb9f-18ed0e0b6b53 /page/7042cb37-...

与客户库直查对照:PM_SAFE_CLARIFICATION → sys_entity_id=8c3c71e9 → templateid=7042cb37(type=1 安全技术交底) ✅ 完全一致。

降级形态:pageUrl=null + pageUrlReason 非空 —— 由单测 PageTemplateMappingTest 3 个降级用例覆盖。

P4-6.4 单测总计

PageTemplateMappingTest(10 单测,新增):

用例 验证点
tableName有映射_返回templateId 正常映射路径
tableName无映射_返回empty 数据库 null 结果
tableName为null_返回empty不查库 空保护
tableName为空串_返回empty不查库 空保护
buildPageUrl_路由格式正确 /page/{id} 格式
数据库异常_降级返回empty 异常静默降级
聚合_有模板条目pageUrl正确填充 聚合层正常路径
聚合_无模板映射_pageUrl为null且reason含表名 模板未找到降级
聚合_businessTable为null_pageUrl为null且reason含提示 SYS_DATASTATUS 无映射降级
聚合_有模板与无模板条目共存_优雅降级 混合列表共存

全模块 mvn test:31 单测(platform-flow-gateway)全绿;ArchitectureRulesTest 绿;全反应堆 BUILD SUCCESS。

P4-6.5 数据变更登记

操作 目标库.行 性质
插入本地 wangwu 用户 eip4m0.sys_user 本地自举,可重复
插入 3 条 SYS_DATASTATUS eip4m0.sys_datastatus(PM_SAFE_CLARIFICATION) 本地构造,演示映射
建 view_template / view_templateentity eip4m0(两张新表) 本地镜像,可重复构造
插入 sys_entity + view_template + view_templateentity eip4m0,PM_SAFE_CLARIFICATION 的镜像数据 本地构造
客户库 零写入 只读 ✅

P4-6.6 新坑

  1. mvn spring-boot:run 用的是 classpath 而非 jar:依赖模块(platform-flow-gateway)改动后须先 mvn install 再重启 platform-app,否则 platform-app 运行时仍加载旧 .class(本次 platform-app 在 flow-gateway 编译之前已启动,导致新字段/新 Service 未生效,初查误认为缓存或代理问题)。
  2. local profile 无客户库表时 PageTemplateService 静默降级:view_template/view_templateentity 在本地 eip4m0 需手动建镜像表(最小结构)才能在 local 验证;生产/default profile 直连客户库则无需此步骤。

七-B、P4-6 收尾

  • 验证完成后已 kill 8089(PID 15942)和 8090(PID 18609)。
  • 客户库零写入;本地 eip4m0 新增镜像表为可重复构造工件。