P3-4: platform-flow-gateway 单体侧流程网关(Flowable REST 客户端 + 待办聚合 + 事件回写)

- 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>
This commit is contained in:
2026-06-11 15:12:03 +08:00
parent 6ced9b15f2
commit ac9812e0a1
24 changed files with 1707 additions and 3 deletions

View File

@@ -535,6 +535,27 @@ com.dsasp.* com.eip4.*
| **对策** | 待办查询/聚合层须按 padding 后形态匹配 assignee;REST 调用方(P3-4 gateway/前端)须知此口径,或在聚合层统一 padding 规整 |
| **影响范围** | 所有按 assignee 精确查询的待办接口;实测 padded assignee(尾 4 空格)REST 待办数=act_ru_task 直查数=12,trim 形态=0 |
### 6.8 Flowable 6.8.1 Task 接口无 businessKey;待办聚合须由查询侧从实例补全 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象** | P3-4 gateway 待办聚合需「任务 businessKey → 业务表数据摘要」,但 flowable-service 原 `TaskDto` 不含 businessKey,gateway 无从连接业务数据 |
| **根因** | Flowable 6.8.1 `org.flowable.task.api.TaskInfo`(Task/HistoricTaskInstance 共同父接口)**无 `getBusinessKey()`**(javap 核实,仅 `getProcessInstanceId()`);businessKey 在 process instance 上,不在 task 上 |
| **对策** | flowable-service 查询侧契约增强:`TaskDto` 加 `businessKey` 字段,`/tasks/todo` 用 `runtimeService`、`/tasks/done` 用 `historyService` 按 `processInstanceId` 反查实例 businessKey 补全;另加 `GET /api/flow/process/{id}` 查实例(运行中 ended=false / 已结束历史实例 ended=true / 不存在 404),供 gateway 办理后判定流程是否结束以回写业务状态。gateway 据 `businessKey` 经 `SYS_DATASTATUS.tablename` 映射 + `loadPOJO` 读业务摘要 |
| **影响范围** | 任何需要 task↔业务数据连接的聚合层;契约演进已记入 `flowable-service` REST(todo/done 出参多 businessKey 字段,新增 GET /process/{id});实测 8089 todo 返回 businessKey 与 act_ru_execution.business_key_ 一致 |
### 6.9 单体侧流程网关 503 熔断语义 + SYS_DATASTATUS 回写守卫 [NEW 2026-06-11]
| 栏目 | 内容 |
|------|------|
| **现象一·熔断** | gateway(platform-app 内)是 flowable-service(8089)的 REST 客户端;引擎进程宕机/网络分区时,待办聚合若直接抛出 RestClient 的 `ResourceAccessException` → Spring 默认 500 + 堆栈,语义错误且暴露内部 |
| **对策一** | `FlowableClient` 三道纪律:超时(connect/read 配置化)、重试(仅连接级瞬时故障带退避重试 `eip4.flow.max-retries` 次,业务级 4xx/5xx 绝不重试)、熔断降级(重试耗尽 → `FlowServiceUnavailableException` → `@RestControllerAdvice` 映射 **503** `FLOW_SERVICE_UNAVAILABLE`;引擎在线但拒绝如挂起拒办 409 → `FlowRemoteException` 透传原状态码)。实测:kill 8089 后 `/api/todo` 返回 503 干净 JSON,platform-app 进程存活不崩 |
| **现象二·回写守卫** | 办理(complete)后须按老系统语义回写 `SYS_DATASTATUS.DATASTATUS`;若无守卫,会在无业务状态记录时凭空 INSERT、或把已「通过(3)」回退 |
| **根因/口径** | 逐条对齐 framework `WfChangeStatus`(upsert:先 UPDATE,0 行则 INSERT BUSINESSKEY/TABLENAME/DATASTATUS)+ `ProcessCoreServiceImpl.passProcess`:`status = 流程已结束 ? STATUS_PASS(3) : STATUS_PROCESSING(2)`,且**仅当 `oldstatus != null && oldstatus < status`** 才回写(单调递增,不回退、不在无记录时凭空插入)。DATASTATUS 值语义=`ProcessCoreService` 常量:1 未提交/2 处理中(在批)/3 通过(已归档)/4 未通过/5 重新提交/6 作废 |
| **对策二** | `StatusWriteback.afterComplete` 复刻该守卫;参数化占位收敛原版裸拼注入面(语义不变)。**本地库验证,客户库只读**:回写仅在连本地 eip4m0(可写)时执行,生产/客户库形态由最小权限只读连接约束。实测:本地构造 SYS_DATASTATUS 行 datastatus=1,经 8090 complete(流程结束 ended=true)回写为 3;守卫负向(已达 3 / 无记录)由单测覆盖 |
| **新坑·SYS_DATASTATUS 无主键** | SYS_DATASTATUS 客户库物理表无主键(§7.2 已登记);本地自举表对齐该口径(不建主键,businesskey 上建普通索引),`bootstrap-datastatus.sql`(platform-flow-gateway 模块)随 P3-4 提供 |
| **影响范围** | platform-flow-gateway 全模块;聚合 API `/api/todo`、`/api/done`、`/api/task/{id}/complete`、`/api/process/start`(经 platform-app 暴露,JWT 取 userId/roles) |
---
## 七、库内数据质量已知问题