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

285 lines
19 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 结束)。
---
## 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 新增镜像表为可重复构造工件。