Skip to content
Merged

Dev #277

Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,11 @@ REST 层通过请求参数 `mockKey` 分流到 Mock 实例(见 `FlowRecordCont

### 事件(IFlowEvent + EventPusher)

9 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)/ 子流程重置(`FlowSubProcessResetEvent`)/ 减签(`FlowRecordReduceAuditEvent`)。操作完成后用 `EventPusher.push(event)` 推送;记录类事件携带 `FlowRecord` + `mock` 标记,重置事件携带新旧聚合组快照。外部可用 Spring `@EventListener` 订阅。
10 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)/ 子流程重置(`FlowSubProcessResetEvent`)/ 减签(`FlowRecordReduceAuditEvent`)/ 二次发起(`FlowRecordReissueEvent`)。操作完成后用 `FlowEventPublisher.push(event)` 推送(**禁止**直接调用 `EventPusher`);引入 starter 时由 `SpringFlowEventPublisher` 保证「事务提交后投递 + 按 `eventKey()`(默认 processId)分区串行」,未注册实现时自动回退 `EventPusher`。记录类事件携带 `FlowRecord` + `mock` 标记,重置事件携带新旧聚合组快照。外部可用 Spring `@EventListener` 订阅。

### API 模块划分

- **命令操作**:`flow-engine-starter-api` — `FlowRecordController`(`/api/cmd/record`:create / action / revoke / delete / urge / detail / processNodes / subProcess/reset)、`WorkflowController`(`/api/cmd/workflow`:流程设计 CRUD 及导入导出)与 `NodeViewJavaScriptController`(`/api/cmd/node-view`:节点视图脚本 getScript / save)
- **命令操作**:`flow-engine-starter-api` — `FlowRecordController`(`/api/cmd/record`:create / action / revoke / delete / urge / detail / processNodes / subProcess/reset / reissue)、`WorkflowController`(`/api/cmd/workflow`:流程设计 CRUD 及导入导出)与 `NodeViewJavaScriptController`(`/api/cmd/node-view`:节点视图脚本 getScript / save)
- **查询**:`flow-engine-starter-query` — `FlowRecordQueryController`(`/api/query/record`:list / todo / done / notify)与 `WorkflowQueryController`(`/api/query/workflow`:list / options / versions)
- **持久化**:`flow-engine-starter-infra` — JPA 实体与仓储实现(含达梦方言)

Expand Down
4 changes: 2 additions & 2 deletions docs/Integration/auto-configuration.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
| `NodeViewJavaScriptCacheContextRegister` | **`NodeViewJavaScriptRepository`** | 构造器内执行 `NodeViewJavaScriptCacheContext.getInstance().setNodeViewJavaScriptRepository(repo)`(15 分钟缓存上下文) |
| `GatewayContextRegister` | **`FlowOperatorGateway`** | 把操作人网关灌入 `GatewayContext` 单例(`InitializingBean`) |
| `FlowScriptContextRegister` | `ApplicationContext` + **`FlowOperatorGateway`** + `FlowRecordRepository` | 给 `FlowScriptContext` 单例设置 `IBeanFactory`(转发 Spring 容器,脚本 `$bind` 依赖) |
| `RepositoryHolderContextRegister` | `WorkflowService` + `FlowRecordService` + 5 个仓储 + `GatewayContextRegister` | 把 7 个依赖灌入 `RepositoryHolderContext` 单例(`InitializingBean`) |
| `RepositoryHolderContextRegister` | `WorkflowService` + `FlowRecordService` + 6 个仓储 + `GatewayContextRegister` | 把 8 个依赖灌入 `RepositoryHolderContext` 单例(`InitializingBean`) |
| `FlowRecordService` | `FlowTodoRecordRepository` + `FlowTodoMergeRepository` + `FlowRecordRepository` | 记录服务 Bean |
| `WorkflowService` | `WorkflowVersionRepository` + `WorkflowRepository` + `WorkflowRuntimeRepository` | 流程设计服务 Bean |
| `FlowService` | `RepositoryHolderContextRegister`(仅保证顺序) | `new FlowService(RepositoryHolderContext.getInstance())`,业务入口 |
Expand All @@ -42,7 +42,7 @@ public void afterPropertiesSet() {
workflowService, flowRecordService,
parallelBranchRepository, delayTaskRepository,
urgeIntervalRepository, flowOperatorAssignmentRepository,
subProcessRepository);
subProcessRepository, flowReissueRepository);
}

// FlowScriptContextRegister
Expand Down
68 changes: 49 additions & 19 deletions docs/Integration/event-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ public interface IAsyncEvent extends IEvent {} // 异步事件标记 ←

同步/异步由 `DomainEventContext.push` 的 `instanceof` 判定:`IAsyncEvent` → 异步(线程池执行);`ISyncEvent`/裸 `IEvent` → 同步(发布线程内联执行)。

### 1.2 九种事件
### 1.2 十种事件

记录类事件均携带 `FlowRecord`(或当前记录)与 `boolean mock` 标记(Mock 模式为 `true`)。

Expand All @@ -42,13 +42,14 @@ public interface IAsyncEvent extends IEvent {} // 异步事件标记 ←
| `FlowRecordDeleteEvent` | 删除未流转实例(开始节点) | `FlowRecord, boolean mock` | `getFlowRecord()` / `isMock()` |
| `FlowRecordReduceAuditEvent` | 减签(每条被撤下的记录) | `FlowRecord, long reduceOperatorId, boolean mock` | `getFlowRecord()` / `getReduceOperatorId()` / `isMock()` |
| `FlowSubProcessResetEvent` | 子流程数据重置(issue #219) | `SubProcessRecord oldRecord, SubProcessRecord newRecord, long resetRecordId, IFlowOperator resetOperator, boolean mock` | `getOldRecord()` / `getNewRecord()` / `getResetRecordId()` / `getResetOperator()` / `isMock()` |
| `FlowRecordReissueEvent` | 已完成流程二次发起(issue #272) | `FlowRecord sourceRecord, FlowRecord newRecord, IFlowOperator operator, boolean mock` | `getSourceRecord()` / `getNewRecord()` / `getOperator()` / `isMock()` |

**子流程重置事件订阅须知**:

| 关注点 | 约定 |
|---|---|
| 新旧聚合组 | `oldRecord` 为被取代的旧聚合组快照(含全部旧实例流程id);`newRecord` 为新聚合组,继承实例沿用原流程id、重建实例为新流程id,重建实例的 `getSourceProcessId()` 指向被替换的旧实例 |
| 收敛方式 | 事件异步、到达顺序不保证(同时伴随 `RevokeEvent`/`StartEvent`/`TodoEvent`);按「同一 `parentRecordId` + 节点维度下最大聚合组 id 为活跃组」幂等覆盖,禁止增量累加 |
| 收敛方式 | 引入 starter 时同一主流程的事件按产生顺序串行到达(同时伴随 `RevokeEvent`/`StartEvent`/`TodoEvent`);仍建议按「同一 `parentRecordId` + 节点维度下最大聚合组 id 为活跃组」幂等覆盖,禁止增量累加 |
| 丢事件对账 | `oldRecord` id 与订阅方当前活跃组不一致时,视为丢事件,调用 `/api/cmd/record/processNodes` 全量对账 |
| 旧数据 | 旧实例记录不删除(仅标记聚合组已取代),订阅方需自行将旧流程id数据标记失效 |

Expand Down Expand Up @@ -76,7 +77,23 @@ public class FlowRecordUrgeEvent implements IFlowEvent {
- 并行:`getParallelId()`、`getParallelBranchNodeId()`、`getParallelBranchTotal()`
- 时间:`getCreateTime()`、`getUpdateTime()`、`getFinishTime()`、`getTimeoutTime()`

## 2. 推送:`EventPusher`
## 2. 推送:`FlowEventPublisher`(引擎内统一入口)

引擎内部**不再直接调用** `EventPusher`,统一走 `com.codingapi.flow.event.FlowEventPublisher`:

```java
FlowEventPublisher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
```

`FlowEventPublisher` 是门面,行为取决于是否注册了发布器实现(`IFlowEventPublisher`):

| 场景 | 行为 |
|---|---|
| 引入 `flow-engine-starter`(默认) | 由 `SpringFlowEventPublisher` 投递:**事务提交后**才投递、按 `IFlowEvent.eventKey()`(默认流程id)分区**串行**,见 4.5 |
| 仅使用 framework / 单元测试 | **回退**为 `EventPusher.push`,与旧版本行为一致 |
| 配置 `codingapi.flow.event.ordered=false` | 不注册实现,回退为 `EventPusher.push` |

底层 `EventPusher`(回退路径)语义:

```java
package com.codingapi.springboot.framework.event;
Expand All @@ -96,12 +113,6 @@ public class EventPusher {
}
```

调用方式(引擎内部统一使用单参形式):

```java
EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
```

### 引擎内推送事件的位置

| 位置 | 推送内容 |
Expand All @@ -120,8 +131,9 @@ EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
| `FlowRevokeService.revoke()` | 当前记录恢复待办 `TodoEvent` + 被撤销后置记录 `RevokeEvent` |
| `FlowDeleteService.delete()` | `DeleteEvent` |
| `FlowSubProcessResetService.reset()` | 被作废记录链逐条 `RevokeEvent` + 子流程重置 `SubProcessResetEvent`;重建实例经 `FlowCreateService` 推送各自的 `StartEvent` + `TodoEvent` |
| `FlowReissueService.reissue()` | 二次发起 `ReissueEvent` + 新流程经 `FlowCreateService` 推送的 `StartEvent` + `TodoEvent` |

> 事件在 `repositoryHolder.saveRecords(...)` **落库之后**推送,保证订阅方看到的记录已持久化。
> 事件在业务数据保存之后推送,且引入 starter 时会在**事务提交后**才投递给订阅方(见 4.5),保证订阅方回查到的记录已持久化。

### 结束节点虚拟记录拦截

Expand All @@ -130,7 +142,7 @@ EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
```java
flowEvents.stream()
.filter(event -> !isEndNodeTodoEvent(event))
.forEach(EventPusher::push);
.forEach(FlowEventPublisher::push);

private boolean isEndNodeTodoEvent(IFlowEvent event) {
return event instanceof FlowRecordTodoEvent todoEvent
Expand Down Expand Up @@ -184,17 +196,22 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven

## 4. 完整分发管道

引入 starter 时(默认):

```
业务代码 → EventPusher.push(event)
→ DomainEventContext.push (IAsyncEvent → 异步)
→ EventTraceContext 记录 trace + 循环事件检测(命中抛 EventLoopException)
→ Spring ApplicationContext.publishEvent(new DomainEvent(event, sync, traceId))
→ SpringDefaultEventHandler.@EventListener dispatch
→ 异步:executorService.execute(() -> ApplicationHandlerUtils.handler(event))
同步:内联执行
→ 按 order() 排序,按泛型匹配执行所有 IHandler
业务代码 → FlowEventPublisher.push(event)
→ SpringFlowEventPublisher.push
→ 有事务:登记 TransactionSynchronization#afterCommit(提交后才投递;回滚不投递)
→ 无事务:立即投递
→ 按 eventKey(默认 processId)散列到单线程分区(同流程串行、跨流程并行)
→ ApplicationContext.publishEvent(new DomainEvent(event, sync=true, traceId))
→ SpringDefaultEventHandler.dispatch(同步分支)
→ 在分区线程内按 order() 排序,按泛型匹配执行所有 IHandler
→ handler 异常仅记录日志,不阻塞同分区后续事件
```

回退路径(未注册发布器):`EventPusher.push → DomainEventContext.push → ...` 与旧版本一致。

### 4.1 循环事件检测

- 同一 traceId 内,同类事件再次 push 会抛 `EventLoopException`(防止事件→动作→事件的无限循环)。
Expand All @@ -214,6 +231,19 @@ public class MyFlowRecordUrgeEventHandler implements IHandler<FlowRecordUrgeEven

`DomainEventContext` 在 `ApplicationContext` 未初始化时(如纯单元测试)**静默丢弃事件**。

### 4.5 顺序与事务可见性保障(`SpringFlowEventPublisher`)

为解决「订阅方在事务提交前消费、同流程事件乱序」的问题(issue #274),starter 默认装配 `SpringFlowEventPublisher`:

- **提交后投递**:有活动事务时通过 `TransactionSynchronization#afterCommit` 投递,订阅方回查数据库一定能读到流程记录/待办/关系数据;事务回滚不投递。
- **按流程串行**:`IFlowEvent.eventKey()` 默认取 `processId`(子流程重置事件取主流程id),散列到固定的单线程分区(默认 4 个分区),同一流程严格按产生顺序执行,不同流程并行。
- **同步执行**:投递时使用 `DomainEvent(sync=true)`,handler 在分区线程内执行完毕,避免再次落入 20 线程池导致乱序。
- **异常隔离**:单个 handler 异常只记录日志,不阻塞同分区后续事件;**注意**:异常不会再回传给业务线程(旧版本异步路径同样不会)。
- **线程模型**:`flow-event-dispatch-{分区}-{序号}` 守护线程;应用关闭时 `destroy()` 注销发布器并停止分区线程。
- **配置**:`codingapi.flow.event.ordered=false` 可整体关闭(回退为直接 `EventPusher.push`)。

**尚未覆盖(见 issue #274 阶段二)**:事件未持久化,进程崩溃或停机瞬间尚未投递的事件会丢失;重试目前仅有单次执行 + 日志。后续将引入 `t_flow_event_outbox`(与业务同事务落库 + 定时补偿重试 + 死信),实现「至少一次」,届时订阅方需按 `processId + eventType + recordId` 做幂等。

## 5. 通知/消息扩展点

引擎**不提供**任何消息发送/桥接抽象。与「通知」相关的能力:
Expand Down
5 changes: 3 additions & 2 deletions docs/Integration/repository-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,7 @@ public interface UrgeIntervalRepository {
| `UrgeIntervalEntity` | `t_flow_urge_interval` |
| `FlowOperatorAssignmentEntity` | `t_flow_operator_assignment` |
| `SubProcessRecordEntity` | `t_flow_sub_process_record` |
| `FlowReissueRecordEntity` | `t_flow_record_reissue`(已完成流程二次发起关系) |

Spring Data 仓储接口位于 `jpa/` 包,全部继承外部 `FastRepository`(来自 `springboot-starter-data-fast`)。

Expand Down Expand Up @@ -233,7 +234,7 @@ public class GroovyScriptRepositoryImpl implements GroovyScriptRepository, Initi
## 6. 替换存储

- **引入 `flow-engine-starter-infra`**:开箱即用(推荐)。
- **不引入 infra**:自行实现 11 个仓储接口 + `NodeViewJavaScriptRepository` 为 Spring Bean 即可。starter 的 `RepositoryHolderContextRegister` 会自动注入。framework 测试包(`src/test/java/com/codingapi/flow/repository/`)提供了一套内存实现可作参考。
- **不引入 infra**:自行实现 12 个仓储接口 + `NodeViewJavaScriptRepository` 为 Spring Bean 即可。starter 的 `RepositoryHolderContextRegister` 会自动注入。framework 测试包(`src/test/java/com/codingapi/flow/repository/`)提供了一套内存实现可作参考。

## 7. 离线/最小装配(脱离 Spring)

Expand All @@ -245,7 +246,7 @@ RepositoryHolderContext.getInstance().register(
workflowService, flowRecordService,
parallelBranchRepository, delayTaskRepository,
urgeIntervalRepository, flowOperatorAssignmentRepository,
subProcessRepository);
subProcessRepository, flowReissueRepository);
// 2. 注册操作人网关
GatewayContext.getInstance().setFlowOperatorGateway(userGateway);
```
13 changes: 13 additions & 0 deletions flow-engine-example/src/main/resources/sql/dm-sequences.sql
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@
-- t_flow_todo_record -> t_flow_todo_record_seq
-- t_flow_todo_marge -> t_flow_todo_marge_seq
-- t_flow_sub_process_record-> t_flow_sub_process_record_seq
-- t_flow_record_reissue -> t_flow_record_reissue_seq
--
-- 序列名 / 步长 与实体 @SequenceGenerator(sequenceName=..., allocationSize=50) 严格一致,
-- 请勿修改,否则 hibernate 会在 insert 时报“无法解析的成员访问表达式[...NEXTVAL]”或出现主键重复。
Expand Down Expand Up @@ -70,5 +71,17 @@ BEGIN
END;
EXECUTE IMMEDIATE 'CREATE SEQUENCE t_flow_sub_process_record_seq INCREMENT BY 50 START WITH ' || v_start;
END IF;

-- ---------- 5. t_flow_record_reissue_seq ----------
SELECT COUNT(*) INTO v_cnt FROM all_sequences
WHERE sequence_name = 'T_FLOW_RECORD_REISSUE_SEQ' AND sequence_owner = USER;
IF v_cnt = 0 THEN
BEGIN
SELECT NVL(MAX(id), 0) + 1 INTO v_start FROM t_flow_record_reissue;
EXCEPTION WHEN OTHERS THEN
v_start := 1;
END;
EXECUTE IMMEDIATE 'CREATE SEQUENCE t_flow_record_reissue_seq INCREMENT BY 50 START WITH ' || v_start;
END IF;
END;
/
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,9 @@ public ActionDisplay display() {

@Override
public boolean show(FlowSession flowSession) {
return this.display.show(flowSession);
// 兼容早期设计/导入的流程数据:动作缺少 display 配置时按默认展示处理,
// 与 ActionDisplay 未配置展示脚本即展示的口径一致,避免详情接口空指针
return this.display == null || this.display.show(flowSession);
}

@Override
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@
import com.codingapi.flow.script.node.OperatorLoadScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -137,7 +137,7 @@ public void run(FlowSession flowSession) {
}

repositoryHolder.saveRecords(flowRecords);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import com.codingapi.flow.script.node.OperatorLoadScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -101,7 +101,7 @@ public void run(FlowSession flowSession) {
}

repositoryHolder.saveRecords(recordList);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);

}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
import com.codingapi.flow.strategy.node.OperatorSelectType;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;

import java.util.ArrayList;
import java.util.List;
Expand Down Expand Up @@ -246,7 +246,7 @@ public void run(FlowSession flowSession) {
// 其 Todo 事件在引擎内虽会生成,但推送业务订阅方前需拦截,避免下游收到"已完成流程的待办"。
flowEvents.stream()
.filter(event -> !isEndNodeTodoEvent(event))
.forEach(EventPusher::push);
.forEach(FlowEventPublisher::push);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.flow.strategy.node.MultiOperatorAuditStrategy;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
Expand Down Expand Up @@ -155,7 +155,7 @@ public void run(FlowSession flowSession) {

// 循序审批的链路由通过时的「最近一条更大 nodeOrder」激活保证,撤销中间记录不需要额外补链
repositoryHolder.saveRecords(saveRecords);
flowEvents.forEach(EventPusher::push);
flowEvents.forEach(FlowEventPublisher::push);
}

/**
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@
import com.codingapi.flow.script.action.ActionRejectScript;
import com.codingapi.flow.session.FlowSession;
import com.codingapi.flow.session.IRepositoryHolder;
import com.codingapi.springboot.framework.event.EventPusher;
import com.codingapi.flow.event.FlowEventPublisher;
import lombok.Getter;

import java.util.ArrayList;
Expand Down Expand Up @@ -129,7 +129,7 @@ public void run(FlowSession flowSession) {
// 结束节点的虚拟记录不是真实业务待办,其 Todo 事件推送业务订阅方前需拦截
flowEvents.stream()
.filter(event -> !isEndNodeTodoEvent(event))
.forEach(EventPusher::push);
.forEach(FlowEventPublisher::push);

}
}
Loading
Loading