diff --git a/docs/plans/2026-06-14-提交审批桥接-design.md b/docs/plans/2026-06-14-提交审批桥接-design.md new file mode 100644 index 0000000..10f5b73 --- /dev/null +++ b/docs/plans/2026-06-14-提交审批桥接-design.md @@ -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)` 解析的 `` 类型逐一匹配:processName/tableName/businessKey=String、map=java.util.Map(用裸 Map 以匹配反射)、ctx=java.util.Properties;返回 boolean=``。) + +逻辑: +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 部署)即可让「提交审批」端到端可用,是写+审批路径(检查点② 之后的下一大集成)的关键拼图。