- FlowableClient:RestClient 调 flowable-service(eip4.flow.base-url,默认 8089);
超时/重试(仅连接级)/熔断降级——引擎不可达 → 503 语义(非 500 堆栈),业务错 4xx/5xx 透传。
- 待办聚合(经 platform-app 暴露):GET /api/todo(JWT userId+roles 候选组)、GET /api/done、
POST /api/task/{id}/complete、POST /api/process/start;聚合层把 Flowable 任务与业务摘要连接
(businessKey → SYS_DATASTATUS.tablename → loadPOJO 只读标题字段;业务摘要数据源客户库只读,
拼不到优雅降级为仅流程字段)。
- 事件回写:complete 后按老系统 ProcessCoreServiceImpl.passProcess + WfChangeStatus 语义更新
SYS_DATASTATUS(结束→STATUS_PASS=3,未结束→STATUS_PROCESSING=2,守卫 oldstatus<status 单调递增;
upsert UPDATE 命中或 0 行 INSERT);本地库验证,客户库只读。
- flowable-service 契约增强:Flowable 6.8.1 TaskInfo 无 getBusinessKey(),todo/done 出参由查询侧
从实例补全 businessKey;新增 GET /api/flow/process/{id} 查实例(供办理后判定流程是否结束)。
验证(8089 连本地 eip4flow+客户库只读,8090 连本地 eip4m0,8084 未动):
- 待办聚合数=直查一致:真实用户 829cdcca /api/todo=4 == 8089 直查 count=4。
- 业务摘要拼接正确 + 优雅降级共存:命中条目拼到 SYS_USERGROUP 标题字段,同列表 3 条无映射降级为仅流程字段。
- 熔断:kill 8089 后 /api/todo 返回 503 干净 JSON,platform-app 进程存活不崩。
- 事件回写:本地构造 datastatus=1,经 8090 complete(流程结束)回写为 3;引擎侧实例确结束。
- 21 单测(客户端重试/降级、聚合拼接、回写守卫)+ 全模块 mvn test + ArchUnit 绿。
坑入手册 §6.8(TaskInfo 无 businessKey)/§6.9(503 熔断 + 回写守卫 + SYS_DATASTATUS 无主键)。
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
13 KiB
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.eip36.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列 (frameworkProcessCoreServiceImpl第 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)
- §6.8 Flowable 6.8.1 Task 接口无 businessKey:
TaskInfo无getBusinessKey()(javap 核实); 待办聚合 task↔业务数据连接须由 flowable-service 查询侧从 process instance 反查补全 (TaskDto加 businessKey 字段;新增GET /api/flow/process/{id}查实例)。 - §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 结束)。