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

7.0 KiB
Raw Blame History

提交审批端到端 — 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 部署)即可让「提交审批」端到端可用,是写+审批路径(检查点② 之后的下一大集成)的关键拼图。