Files
eip4-platform/platform-flow-gateway/P3网关实测报告.md
zhengwr ac9812e0a1 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>
2026-06-11 15:12:03 +08:00

185 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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|processDefinitionId, businessKey, variables}` |
熔断:引擎不可达 → **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 结束)。