@@ -76,7 +76,23 @@ public class FlowRecordUrgeEvent implements IFlowEvent {
7676- 并行:` getParallelId() ` 、` getParallelBranchNodeId() ` 、` getParallelBranchTotal() `
7777- 时间:` getCreateTime() ` 、` getUpdateTime() ` 、` getFinishTime() ` 、` getTimeoutTime() `
7878
79- ## 2. 推送:` EventPusher `
79+ ## 2. 推送:` FlowEventPublisher ` (引擎内统一入口)
80+
81+ 引擎内部** 不再直接调用** ` EventPusher ` ,统一走 ` com.codingapi.flow.event.FlowEventPublisher ` :
82+
83+ ``` java
84+ FlowEventPublisher . push(new FlowRecordStartEvent (flowRecord, session. isMock()));
85+ ```
86+
87+ ` FlowEventPublisher ` 是门面,行为取决于是否注册了发布器实现(` IFlowEventPublisher ` ):
88+
89+ | 场景 | 行为 |
90+ | ---| ---|
91+ | 引入 ` flow-engine-starter ` (默认) | 由 ` SpringFlowEventPublisher ` 投递:** 事务提交后** 才投递、按 ` IFlowEvent.eventKey() ` (默认流程id)分区** 串行** ,见 4.5 |
92+ | 仅使用 framework / 单元测试 | ** 回退** 为 ` EventPusher.push ` ,与旧版本行为一致 |
93+ | 配置 ` codingapi.flow.event.ordered=false ` | 不注册实现,回退为 ` EventPusher.push ` |
94+
95+ 底层 ` EventPusher ` (回退路径)语义:
8096
8197``` java
8298package com.codingapi.springboot.framework.event ;
@@ -96,12 +112,6 @@ public class EventPusher {
96112}
97113```
98114
99- 调用方式(引擎内部统一使用单参形式):
100-
101- ``` java
102- EventPusher . push(new FlowRecordStartEvent (flowRecord, session. isMock()));
103- ```
104-
105115### 引擎内推送事件的位置
106116
107117| 位置 | 推送内容 |
@@ -184,17 +194,22 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven
184194
185195## 4. 完整分发管道
186196
197+ 引入 starter 时(默认):
198+
187199```
188- 业务代码 → EventPusher.push(event)
189- → DomainEventContext.push (IAsyncEvent → 异步)
190- → EventTraceContext 记录 trace + 循环事件检测(命中抛 EventLoopException)
191- → Spring ApplicationContext.publishEvent(new DomainEvent(event, sync, traceId))
192- → SpringDefaultEventHandler.@EventListener dispatch
193- → 异步:executorService.execute(() -> ApplicationHandlerUtils.handler(event))
194- 同步:内联执行
195- → 按 order() 排序,按泛型匹配执行所有 IHandler
200+ 业务代码 → FlowEventPublisher.push(event)
201+ → SpringFlowEventPublisher.push
202+ → 有事务:登记 TransactionSynchronization#afterCommit(提交后才投递;回滚不投递)
203+ → 无事务:立即投递
204+ → 按 eventKey(默认 processId)散列到单线程分区(同流程串行、跨流程并行)
205+ → ApplicationContext.publishEvent(new DomainEvent(event, sync=true, traceId))
206+ → SpringDefaultEventHandler.dispatch(同步分支)
207+ → 在分区线程内按 order() 排序,按泛型匹配执行所有 IHandler
208+ → handler 异常仅记录日志,不阻塞同分区后续事件
196209```
197210
211+ 回退路径(未注册发布器):` EventPusher.push → DomainEventContext.push → ... ` 与旧版本一致。
212+
198213### 4.1 循环事件检测
199214
200215- 同一 traceId 内,同类事件再次 push 会抛 ` EventLoopException ` (防止事件→动作→事件的无限循环)。
@@ -214,6 +229,19 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven
214229
215230` DomainEventContext ` 在 ` ApplicationContext ` 未初始化时(如纯单元测试)** 静默丢弃事件** 。
216231
232+ ### 4.5 顺序与事务可见性保障(` SpringFlowEventPublisher ` )
233+
234+ 为解决「订阅方在事务提交前消费、同流程事件乱序」的问题(issue #274 ),starter 默认装配 ` SpringFlowEventPublisher ` :
235+
236+ - ** 提交后投递** :有活动事务时通过 ` TransactionSynchronization#afterCommit ` 投递,订阅方回查数据库一定能读到流程记录/待办/关系数据;事务回滚不投递。
237+ - ** 按流程串行** :` IFlowEvent.eventKey() ` 默认取 ` processId ` (子流程重置事件取主流程id),散列到固定的单线程分区(默认 4 个分区),同一流程严格按产生顺序执行,不同流程并行。
238+ - ** 同步执行** :投递时使用 ` DomainEvent(sync=true) ` ,handler 在分区线程内执行完毕,避免再次落入 20 线程池导致乱序。
239+ - ** 异常隔离** :单个 handler 异常只记录日志,不阻塞同分区后续事件;** 注意** :异常不会再回传给业务线程(旧版本异步路径同样不会)。
240+ - ** 线程模型** :` flow-event-dispatch-{分区}-{序号} ` 守护线程;应用关闭时 ` destroy() ` 注销发布器并停止分区线程。
241+ - ** 配置** :` codingapi.flow.event.ordered=false ` 可整体关闭(回退为直接 ` EventPusher.push ` )。
242+
243+ ** 尚未覆盖(见 issue #274 阶段二)** :事件未持久化,进程崩溃或停机瞬间尚未投递的事件会丢失;重试目前仅有单次执行 + 日志。后续将引入 ` t_flow_event_outbox ` (与业务同事务落库 + 定时补偿重试 + 死信),实现「至少一次」,届时订阅方需按 ` processId + eventType + recordId ` 做幂等。
244+
217245## 5. 通知/消息扩展点
218246
219247引擎** 不提供** 任何消息发送/桥接抽象。与「通知」相关的能力:
0 commit comments