# 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 ` 停 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 日期: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 新增镜像表为可重复构造工件。