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>
This commit is contained in:
84
docs/plans/2026-06-14-提交审批桥接-design.md
Normal file
84
docs/plans/2026-06-14-提交审批桥接-design.md
Normal file
@@ -0,0 +1,84 @@
|
||||
# 提交审批端到端 — 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 部署)即可让「提交审批」端到端可用,是写+审批路径(检查点② 之后的下一大集成)的关键拼图。
|
||||
Reference in New Issue
Block a user