Files
eip4-platform/docs/plans/2026-06-14-提交审批桥接-design.md
zhengwr 8a16e12101 docs: 提交审批端到端 processCoreService 桥接 bean 设计(MVP,brainstorming 收敛)
逐流写 QA dogfooding 深挖 no-service 定位:248 SUBMIT/审批流调 processCoreService.startWorkflow
未注册。设计 platform-flow-gateway @Component("processCoreService") 桥接 bean(引擎反射调,
不 implements 25 方法接口),桥到既有 FlowableClient.start(8089) + StatusWriteback(SYS_DATASTATUS),
MVP 仅 start+状态(NOSUBMIT1→PROCESSING2/PASS3)。显式前置依赖:客户审批 BPMN 部署进 flowable-service
+ processName(中文名)→流程定义 key 匹配(dev eip4flow 仅 demo);自动过流程发起/重提交后置。
待 writing-plans / TDD 实施。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 00:56:29 +08:00

85 lines
7.0 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.
# 提交审批端到端 — processCoreService 桥接 bean 设计(MVP)
> 日期:2026-06-14
> 状态:设计已收敛(brainstorming 完成),待实施(writing-plans / TDD)。
> 触发:逐流写 QA dogfooding 深挖 `no service`——248 个 SUBMIT/审批写流调 `processCoreService.startWorkflow` 而该 bean 未在 platform-app 注册。
> 边界:**仅设计桥接 bean**;BPMN 部署 + processName→key 映射为显式前置依赖(见 §6)。
---
## 一、背景与根因
amis「提交审批」走 **SAVE_AND_SUBMIT 复合 meta-flow**:SERVICE 节点 `beanName="flowExcuteService"` 调子流 `_ADD/_UPDATE`(落库,pojoCRUDService)→ 子流 `_SUBMIT` 的节点 `beanName="processCoreService" method="startWorkflow"` 启动审批流程。
`SpringBeanOsgiServices.getBeanByName(name)` = `applicationContext.getBean(name)` 按**名字**查。全库无名为 `processCoreService` 的 bean → `FlowExcuteServiceImpl:304` 抛 `RuntimeException("no service")`。**影响 248 流**(SUBMIT 120 / ADDSUBMIT 32 / SZWJ 18 / …)。
**桥接原语多已就位**(platform-flow-gateway):
- `FlowableClient.start(Map startRequest) → ProcessInstanceDto`(POST flowable-service `/api/flow/process/start`)+ complete/todo/trace/delegate;flowable-service:8089 实测在跑。
- `StatusWriteback`(SYS_DATASTATUS 单一所有者):`updateStatus`(upsert)/`getStatus`/`afterComplete`(办理后 PROCESSING/PASS,单调守卫)。
- `candidateUsersHandler`(flowable-service,候选人解析,B2 已验)。
**唯缺**:注册名 `processCoreService`、含 `startWorkflow` 方法的桥接 bean。
旧 `ProcessCoreServiceImpl.startWorkflow(processDefinitionKey, variables, tableName, businessKey, ctx)` 编排 = `runtimeService.startProcessInstanceByKey` + `changeStatus` 状态机(NOSUBMIT 1→PROCESSING 2/PASS 3) + 自动过「流程发起」首任务 + 重提交(RESUBMIT 5)。
---
## 二、架构
platform-flow-gateway 新增 `@Component("processCoreService")` 的 com.eip4 桥接 bean,把保真层服务流引擎调的 `startWorkflow(...)` 桥到既有 `FlowableClient.start` + `StatusWriteback`。
- 引擎经 `SpringBeanOsgiServices.getBeanByName("processCoreService")` 取 bean,再 `obj.getClass().getMethod("startWorkflow", [String,Map,String,String,Properties])` **反射调用**——故**无需 implements 25 方法的 ProcessCoreService 接口**,只需一个签名匹配的公开方法。
- 零改保真层 `com.dsasp.*`;ArchUnit 不触发(com.eip4 可依赖 com.dsasp)。
## 三、组件
`ProcessCoreServiceBridge`(platform-flow-gateway,`@Component("processCoreService")`),构造注入 `FlowableClient` + `StatusWriteback`。
```
public boolean startWorkflow(String processName, Map variables,
String tableName, String businessKey, Properties ctx)
```
(参数类型须与引擎 `getClass(field)` 解析的 `<arg>` 类型逐一匹配:processName/tableName/businessKey=String、map=java.util.Map(用裸 Map 以匹配反射)、ctx=java.util.Properties;返回 boolean=`<result name="result">`。)
逻辑:
1. `businessKey` 空 → 抛 `ValidationException("定义启动流程提交的业务记录不存在,请联系开发商")`(对齐旧,且该消息干净可经 gracefulFlowError 透出)。
2. 注入发起人变量(对齐旧,复用 `ProcessCoreService` 常量名):`INITIATORUSERID=ctx[CURRENTUSER]`、`INITIATORDEPARTID=ctx[CURRENTDEPART]`(缺则补)、`INITIATORTIME=now`。
3. 构造 `startRequest = {processDefinitionKey: processName, businessKey: businessKey, variables: variables}` → `ProcessInstanceDto inst = flowableClient.start(startRequest)`。
4. `statusWriteback.updateStatus(businessKey, tableName, inst.ended()? STATUS_PASS(3): STATUS_PROCESSING(2))`——起审批的 NOSUBMIT 1→2/3。直接 `updateStatus`(非 `afterComplete`,起审批总是从 1 推进,无需单调守卫)。
5. `return true`。
## 四、数据流
```
amis 提交审批 → POST /api/flow/{SAVE_AND_SUBMIT}
→ 引擎跑 meta-flow:save 子流(pojoCRUDService 落库,状态 NOSUBMIT=1,提交事务)
→ submit 子流 → startWorkflow 节点 → ProcessCoreServiceBridge
→ FlowableClient.start(HTTP→8089) 起 Flowable 流程
→ StatusWriteback.updateStatus → PROCESSING=2
后续办理:网关 complete 端点 → FlowableClient.complete → StatusWriteback.afterComplete → 2→3(PASS)
```
## 五、错误与事务语义
- 业务落库与起审批**分属不同服务/事务**(platform-app DB vs flowable-service),无分布式事务,接受最终一致。
- 起审批失败(`FlowServiceUnavailableException` / 流程定义不存在 / 8089 不可达)→ bean 抛 RuntimeException → 经 `FlowController.gracefulFlowError` 兜泛化「数据查询失败…」(内部细节不泄露 + 记完整栈);**状态停留 NOSUBMIT(1)**——业务记录已存,用户可重新提交。
- 幂等:本 MVP 重提交 = 起新流程(去重/复用待**后置**,见 §6)。
## 六、测试
单测 `ProcessCoreServiceBridgeTest`(mock FlowableClient + StatusWriteback):
- 正常:断言 startRequest 含 processDefinitionKey=processName/businessKey/variables;发起人变量已注入;调 `flowableClient.start`;`inst.ended()=false` → `updateStatus(...,PROCESSING)`,`=true` → `updateStatus(...,PASS)`;返回 true。
- businessKey 空 → 抛 ValidationException。
- 反射可解析性:`getMethod("startWorkflow", String.class, Map.class, String.class, String.class, Properties.class)` 能解析(保证引擎按名+签名调得到)。
- dev e2e **后置**(需部署一个 key 匹配的审批 BPMN,出本设计边界)。
## 七、显式前置依赖(出本设计边界,需单独立项/记录)
1. **客户审批 BPMN 部署进 flowable-service**:dev `eip4flow` 库 `ACT_RE_PROCDEF` 仅 demo 流程(process/process2/TEST_REQUEST…),无客户业务审批流程定义。`processName="收房变更申请"`(中文显示名作 startProcessInstanceByKey 的 key,旧 Activiti 约定)→ flowable-service 须部署 key 匹配(中文名)的 BPMN,否则即便桥接 bean 就位,start 也会「流程定义不存在」。生产/客户库疑有那 1509 定义,dev 需部署代表性 BPMN 验证。
2. **ProcessCoreService 其它方法**:passProcess/backProcess/transferAssignee/getProcessInstanceIdByBusinessKey 等若被别的流节点引用(如审批办理/退回/转办的服务流),本 MVP 只实现 startWorkflow → 那些节点仍 `no service`,按需扩同一 bean(追加方法,复用 FlowableClient.complete/delegate 等)。
3. **「流程发起」首任务自动过 + 重提交(RESUBMIT 5)**:旧 startWorkflow 含此逻辑,本 MVP 后置(依赖 BPMN 形态,且可由 BPMN service task 自过;FlowableClient.start 需返回首任务信息才能在桥内自过)。
## 八、影响面与价值
打通 248 个 SUBMIT/审批写流的「启动审批」步——配合前置依赖①(BPMN 部署)即可让「提交审批」端到端可用,是写+审批路径(检查点② 之后的下一大集成)的关键拼图。