feat: 新增删除流程能力与撤销事件

xlorne · claude · xlorne · commit 48afaeab0ce9 · 2026-06-24T10:28:47.000+08:00
- 新增 FlowDeleteService: 仅允许删除位于开始节点、待办且未流转的流程实例
- 新增 FlowDeleteRequest 请求对象与 FlowRecordDeleteEvent 事件
- FlowRecordService 新增 deleteFlowRecord, 清理合并关系/待办/流程记录
- FlowRecordController 暴露 POST /api/cmd/record/delete
- FlowRevokeService 撤销时对每条被撤销记录推送 FlowRecordRevokeEvent
- FlowStateException 扩展删除相关异常方法
- 同步 README.md 与 CLAUDE.md 核心架构说明

Co-Authored-By: Claude &lt;noreply@anthropic.com&gt;
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -30,6 +30,48 @@ Flow Engine 是一个企业级工作流引擎，基于 Java 17 和 Spring Boot 3
 | `com.codingapi.flow.manager` | 业务管理器 |
 | `com.codingapi.flow.service` | 业务服务层 |
 
+## 核心架构
+
+理解以下跨文件的模式后再动手改动，可避免破坏引擎一致性。
+
+### 服务编排模式（FlowService）
+
+`FlowService`（`flow-engine-framework/.../service/FlowService.java`）是 `@Transactional` 业务入口。**每个流程操作对应一个独立的 `FlowXxxService`**（`FlowCreateService` / `FlowActionService` / `FlowRevokeService` / `FlowDeleteService` / `FlowUrgeService` / `FlowDetailService`），通过 `IRepositoryHolder` 注入依赖，且每次操作前调用 `FlowOperatorLocalThreadCache.getInstance().clear()` 清理线程缓存。新增流程操作应沿用此模式：新建 `FlowXxxService(request, repositoryHolder)`，并在 `FlowService` 暴露一个入口方法。
+
+### 仓储持有者（IRepositoryHolder）
+
+服务层不直接注入仓储，而是通过 `IRepositoryHolder` 获取 `FlowRecordService` / `WorkflowService` / `FlowOperatorGateway` 等依赖。两个实现：
+- `RepositoryHolderContext` — 生产，单例，由 `flow-engine-starter` 自动配置注册
+- `MockRepositoryHolder` — 测试 / Mock 场景
+
+REST 层通过请求参数 `mockKey` 分流到 Mock 实例（见 `FlowRecordController.loadFlowService()` / `loadCurrentOperatorId()`）；`operatorId` 也可由该参数覆盖，便于无登录态测试。
+
+### 流程记录生命周期
+
+三类记录紧密绑定，须保持一致：
+- `FlowRecord` — 流程执行记录（TODO / DONE 状态，`isTodo()` / `isDone()` / `isFinish()`）
+- `FlowTodoRecord` — 待办记录
+- `FlowTodoMerge` — 待办合并关系（开启记录合并 `isMergeable()` 时产生）
+
+保存走 `FlowRecordSaveService.saveAll()`，单次调用顺序执行 `saveRecords → saveTodoMargeRecords → removeTodoMergeRecords`，保证三者一致。删除整条流程走 `FlowRecordService.deleteFlowRecord()`，按 合并关系 → 待办 → 流程记录 顺序清理。
+
+### 节点 / 动作 / 策略三元组
+
+19 种节点（`node/nodes/`）× 8 种动作（`action/actions/`），行为由策略（`strategy/node/`、`strategy/workflow/`）驱动而非继承扩展：
+- `NodeStrategyManager` 持有节点策略（如 `RevokeStrategy`、`OperatorLoadStrategy`、`RecordMergeStrategy`）
+- `ActionManager` 持有节点动作
+- 节点类型常量见 `StartNode.NODE_TYPE`（= `NodeType.START.name()`），`FlowRecord.isNodeType(String)` 用于按类型判定
+
+### 事件（IFlowEvent + EventPusher）
+
+7 种事件：开始 / 待办 / 已办 / 完成 / 催办 / 撤销（`FlowRecordRevokeEvent`）/ 删除（`FlowRecordDeleteEvent`）。操作完成后用 `EventPusher.push(event)` 推送；事件通常携带 `FlowRecord` + `mock` 标记。外部可用 Spring `@EventListener` 订阅。
+
+### API 模块划分
+
+- **命令操作**：`flow-engine-starter-api` — `FlowRecordController`（`/api/cmd/record`：create / action / revoke / delete / urge / detail）与 `WorkflowController`（`/api/cmd/workflow`：流程设计 CRUD）
+- **查询**：`flow-engine-starter-query` — `FlowRecordQueryController`（`/api/query/record`：list / todo / done / notify）
+- **持久化**：`flow-engine-starter-infra` — JPA 实体与仓储实现（含达梦方言）
+
 ## 常用命令
 
 ### 构建与测试
@@ -70,24 +112,6 @@ cd flow-engine-example && mvn spring-boot:run
 - **与用户沟通及编写文档时，所有内容必须使用中文表述**
 - **在每次修改代码以后，要执行本地化的编译验证确保代码没有错误**
 - Java 代码遵循 Spring Boot 规范
-- 设计涉及流程或 UML 图形的解决方案时，使用纯文本线框图表示
-- 在设计计划方案或执行方案过程中，对于代码的设计规划与调整修改要遵循本项目的代码风格和架构设计规则
-- 设计的计划要保存到本地的 `docs/` 目录下：
-  - `docs/plan/` - 存放详细可执行开发计划，文件命名格式为 `yyyy-mm-dd-标题.md`
-  - `docs/architecture/` - 存放架构设计文档
-  - `docs/todo/` - 存放阶段任务清单
-
-### Git 工作流
-
-**代码提交路径：**
-
-```
-feature/{task-name}  →  PR  →  dev  →  （用户审核）  →  main
-```
-
-- **禁止直接向 main 分支提交**，main 分支由用户手动合并管理
-- **dev 分支为集成分支**，所有 PR 的目标分支均为 dev
-- **所有代码开发必须在 git worktree 中进行**，不在主工作区直接改代码
 
 ### 测试规范
 
@@ -152,27 +176,6 @@ class ScriptRuntimeContextTest {
 }
 ```
 
-## 架构设计文档
-
-详细架构设计见 `docs/architecture/` 目录：
-
-| 文档 | 说明 |
-|------|------|
-| `01-项目概览.md` | 项目背景、技术栈 |
-| `02-模块总览.md` | Maven 模块划分 |
-| `03-节点模块.md` | 节点接口、节点类型 |
-| `04-动作模块.md` | 动作接口、动作执行 |
-| `05-策略模块.md` | 节点策略、工作流策略 |
-| `06-脚本模块.md` | Groovy 脚本运行时 |
-| `07-仓储模块.md` | 仓储接口、基础设施实现 |
-| `08-构建器模块.md` | 建造者模式实现 |
-| `09-管理器模块.md` | 业务管理器 |
-| `10-服务模块.md` | 业务服务层 |
-| `11-网关与上下文.md` | 网关接口、上下文 |
-| `12-数据库设计.md` | 实体设计、表结构 |
-| `13-API接口设计.md` | REST API 设计 |
-
-
 <!-- PKR-START -->
 ## PKR 知识查阅（编码前必须）
 
diff --git a/README.md b/README.md
@@ -62,13 +62,15 @@ flow-engine
 │       │   └── UrgeInterval      # 催办间隔
 │       ├── error                 # 错误处理
 │       │   └── ErrorThrow        # 错误抛出器
-│       ├── event                 # 事件系统（5种）
+│       ├── event                 # 事件系统（7种）
 │       │   ├── IFlowEvent                # 事件接口
 │       │   ├── FlowRecordStartEvent      # 流程开始事件
 │       │   ├── FlowRecordTodoEvent       # 待办事件
 │       │   ├── FlowRecordDoneEvent       # 已办事件
 │       │   ├── FlowRecordFinishEvent     # 流程完成事件
-│       │   └── FlowRecordUrgeEvent       # 催办事件
+│       │   ├── FlowRecordUrgeEvent       # 催办事件
+│       │   ├── FlowRecordRevokeEvent     # 流程撤销事件
+│       │   └── FlowRecordDeleteEvent     # 流程删除事件
 │       ├── exception             # 异常系统（6种）
 │       │   ├── FlowException             # 异常基类
 │       │   ├── FlowValidationException   # 参数验证异常
@@ -132,6 +134,7 @@ flow-engine
 │       │   │   ├── FlowActionRequest  # 动作请求
 │       │   │   ├── FlowCreateRequest  # 创建请求
 │       │   │   ├── FlowRevokeRequest  # 撤回请求
+│       │   │   ├── FlowDeleteRequest  # 删除请求
 │       │   │   └── FlowUrgeRequest    # 催办请求
 │       │   └── response          # 响应对象
 │       │       ├── FlowOperator   # 流程操作者
@@ -172,6 +175,7 @@ flow-engine
 │       │   │   ├── FlowActionService    # 流程动作服务
 │       │   │   ├── FlowDelayTriggerService # 延迟触发服务
 │       │   │   ├── FlowRevokeService    # 流程撤回服务
+│       │   │   ├── FlowDeleteService    # 流程删除服务
 │       │   │   ├── FlowUrgeService      # 流程催办服务
 │       │   │   └── FlowDetailService   # 流程详情服务
 │       │   └── FlowService       # 服务接口
@@ -474,6 +478,8 @@ category.subcategory.errorType
 - `notFound.workflow.definition` - 流程定义未找到
 - `permission.field.readOnly` - 字段只读
 - `state.record.alreadyDone` - 记录已完成
+- `state.record.notSupportDelete` - 记录不允许删除
+- `state.node.notStart` - 记录不在开始节点
 - `validation.field.required` - 必填字段为空
 - `execution.script.error` - 脚本执行错误
 
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/event/FlowRecordDeleteEvent.java b/flow-engine-framework/src/main/java/com/codingapi/flow/event/FlowRecordDeleteEvent.java
@@ -0,0 +1,19 @@
+package com.codingapi.flow.event;
+
+import com.codingapi.flow.record.FlowRecord;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 流程删除事件
+ * <p>
+ * 仅当删除位于开始节点且尚未流转的流程实例时触发
+ */
+@Getter
+@AllArgsConstructor
+public class FlowRecordDeleteEvent implements IFlowEvent {
+
+    private final FlowRecord flowRecord;
+
+    private final boolean mock;
+}
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/event/FlowRecordRevokeEvent.java b/flow-engine-framework/src/main/java/com/codingapi/flow/event/FlowRecordRevokeEvent.java
@@ -0,0 +1,25 @@
+package com.codingapi.flow.event;
+
+import com.codingapi.flow.record.FlowRecord;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 流程撤销事件
+ * <p>
+ * 撤销流程时触发,登记被撤销的下级记录数据
+ */
+@Getter
+@AllArgsConstructor
+public class FlowRecordRevokeEvent implements IFlowEvent {
+
+    /**
+     * 被撤销的待办记录
+     */
+    private final FlowRecord currentRecord;
+
+    /**
+     * 是否为模拟环境
+     */
+    private final boolean mock;
+}
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/exception/FlowStateException.java b/flow-engine-framework/src/main/java/com/codingapi/flow/exception/FlowStateException.java
@@ -117,4 +117,31 @@ public static FlowStateException nodeNotSupportRevoke() {
     public static FlowStateException recordLimitUrgeError() {
         return new FlowStateException("record.urge.limit", "record urge limit error");
     }
+
+    /**
+     * Record not support delete (not a todo / finished / revoked)
+     *
+     * @return exception
+     */
+    public static FlowStateException recordNotSupportDelete() {
+        return new FlowStateException("state.record.notSupportDelete", "Flow record is not a todo, delete not allowed");
+    }
+
+    /**
+     * Record is not on the start node, delete not allowed
+     *
+     * @return exception
+     */
+    public static FlowStateException nodeNotStartNode() {
+        return new FlowStateException("state.node.notStart", "Flow record is not on the start node, delete not allowed");
+    }
+
+    /**
+     * Flow already running (has subsequent records), delete not allowed
+     *
+     * @return exception
+     */
+    public static FlowStateException recordAlreadyRunning() {
+        return new FlowStateException("state.record.alreadyRunning", "Flow is already running, delete not allowed");
+    }
 }
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/pojo/request/FlowDeleteRequest.java b/flow-engine-framework/src/main/java/com/codingapi/flow/pojo/request/FlowDeleteRequest.java
@@ -0,0 +1,35 @@
+package com.codingapi.flow.pojo.request;
+
+import com.codingapi.flow.exception.FlowValidationException;
+import lombok.AllArgsConstructor;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * 流程删除请求
+ * <p>
+ * 仅用于删除位于开始节点且尚未流转的流程实例
+ */
+@Data
+@NoArgsConstructor
+@AllArgsConstructor
+public class FlowDeleteRequest {
+
+    /**
+     * 记录id
+     */
+    private long recordId;
+    /**
+     * 操作者
+     */
+    private long operatorId;
+
+    public void verify() {
+        if (recordId <= 0) {
+            throw FlowValidationException.required("recordId");
+        }
+        if (operatorId <= 0) {
+            throw FlowValidationException.required("operatorId");
+        }
+    }
+}
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/service/FlowRecordService.java b/flow-engine-framework/src/main/java/com/codingapi/flow/service/FlowRecordService.java
@@ -120,4 +120,28 @@ public List<FlowRecord> findFlowRecordCurrentNodeRecords(long fromId, String nod
         return this.flowRecordRepository.findCurrentNodeRecords(fromId,nodeId);
     }
 
+
+    /**
+     * 删除流程记录及其关联的待办数据
+     * <p>
+     * 仅用于作废尚未流转的流程实例,会同时清理该流程记录对应的待办记录与合并关系
+     * @param flowRecord 流程记录
+     */
+    public void deleteFlowRecord(FlowRecord flowRecord) {
+        FlowTodoRecord flowTodoRecord = flowTodoRecordRepository.getByTodoKey(flowRecord.getTodoKey());
+        if (flowTodoRecord != null) {
+            // 清理待办合并关系
+            List<FlowTodoMerge> todoMerges = flowTodoMergeRepository.findByTodoId(flowTodoRecord.getId());
+            if (todoMerges != null) {
+                for (FlowTodoMerge todoMerge : todoMerges) {
+                    flowTodoMergeRepository.delete(todoMerge);
+                }
+            }
+            // 清理待办记录
+            flowTodoRecordRepository.delete(flowTodoRecord);
+        }
+        // 删除流程记录
+        flowRecordRepository.delete(flowRecord);
+    }
+
 }
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/service/FlowService.java b/flow-engine-framework/src/main/java/com/codingapi/flow/service/FlowService.java
@@ -85,6 +85,19 @@ public void revoke(FlowRevokeRequest request) {
     }
 
 
+    /**
+     * 删除流程
+     * <p>
+     * 仅用于作废尚未流转(位于开始节点且无后续记录)的流程实例
+     * @param request 删除请求
+     */
+    public void delete(FlowDeleteRequest request) {
+        FlowOperatorLocalThreadCache.getInstance().clear();
+        FlowDeleteService flowDeleteService = new FlowDeleteService(request, this.repositoryHolder);
+        flowDeleteService.delete();
+    }
+
+
     /**
      * 催办
      */
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowDeleteService.java b/flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowDeleteService.java
@@ -0,0 +1,63 @@
+package com.codingapi.flow.service.impl;
+
+import com.codingapi.flow.event.FlowRecordDeleteEvent;
+import com.codingapi.flow.exception.FlowNotFoundException;
+import com.codingapi.flow.exception.FlowStateException;
+import com.codingapi.flow.mock.MockRepositoryHolder;
+import com.codingapi.flow.node.nodes.StartNode;
+import com.codingapi.flow.pojo.request.FlowDeleteRequest;
+import com.codingapi.flow.record.FlowRecord;
+import com.codingapi.flow.service.FlowRecordService;
+import com.codingapi.flow.session.IRepositoryHolder;
+import com.codingapi.springboot.framework.event.EventPusher;
+
+import java.util.List;
+
+/**
+ * 删除流程服务
+ * <p>
+ * 仅允许删除位于开始节点、且尚未流转的待办记录,等价于作废整个尚未发起的流程实例。
+ * 若流程已流转到后续节点,需先撤销退回开始节点后再删除。
+ */
+public class FlowDeleteService {
+
+    private final FlowDeleteRequest request;
+    private final FlowRecordService flowRecordService;
+    private final IRepositoryHolder repositoryHolder;
+
+    public FlowDeleteService(FlowDeleteRequest request, IRepositoryHolder repositoryHolder) {
+        this.request = request;
+        this.flowRecordService = repositoryHolder.getFlowRecordService();
+        this.repositoryHolder = repositoryHolder;
+    }
+
+    public void delete() {
+        request.verify();
+        FlowRecord currentRecord = flowRecordService.getFlowRecord(request.getRecordId());
+        if (currentRecord == null) {
+            throw FlowNotFoundException.record(request.getRecordId());
+        }
+        // 必须是待办状态(未办理、未撤销、未结束)
+        if (!currentRecord.isTodo()) {
+            throw FlowStateException.recordNotSupportDelete();
+        }
+        // 必须位于开始节点
+        if (!currentRecord.isNodeType(StartNode.NODE_TYPE)) {
+            throw FlowStateException.nodeNotStartNode();
+        }
+        // 必须无后续流转记录(流程尚未执行)
+        List<FlowRecord> afterRecords = flowRecordService.findFlowRecordAfterRecords(
+                currentRecord.getProcessId(), currentRecord.getId());
+        if (afterRecords != null && !afterRecords.isEmpty()) {
+            throw FlowStateException.recordAlreadyRunning();
+        }
+        // 权限校验:仅允许当前待办处理人删除
+        if (currentRecord.getCurrentOperatorId() != request.getOperatorId()) {
+            throw FlowStateException.operatorNotMatch();
+        }
+        // 删除流程记录及其关联待办
+        flowRecordService.deleteFlowRecord(currentRecord);
+        // 推送删除事件
+        EventPusher.push(new FlowRecordDeleteEvent(currentRecord, repositoryHolder instanceof MockRepositoryHolder));
+    }
+}
diff --git a/flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowRevokeService.java b/flow-engine-framework/src/main/java/com/codingapi/flow/service/impl/FlowRevokeService.java
@@ -1,5 +1,6 @@
 package com.codingapi.flow.service.impl;
 
+import com.codingapi.flow.event.FlowRecordRevokeEvent;
 import com.codingapi.flow.event.FlowRecordTodoEvent;
 import com.codingapi.flow.event.IFlowEvent;
 import com.codingapi.flow.exception.FlowNotFoundException;
@@ -94,6 +95,8 @@ public void revoke() {
         for (FlowRecord afterRecord : afterRecords) {
             afterRecord.revoke();
             recordList.add(afterRecord);
+            // 撤销事件,登记撤销发起的记录数据
+            flowEvents.add(new FlowRecordRevokeEvent(afterRecord, repositoryHolder instanceof MockRepositoryHolder));
         }
 
         repositoryHolder.saveRecords(recordList);
diff --git a/flow-engine-framework/src/test/java/com/codingapi/flow/service/FlowDeleteServiceTest.java b/flow-engine-framework/src/test/java/com/codingapi/flow/service/FlowDeleteServiceTest.java
diff --git a/flow-engine-starter-api/src/main/java/com/codingapi/flow/api/controller/FlowRecordController.java b/flow-engine-starter-api/src/main/java/com/codingapi/flow/api/controller/FlowRecordController.java
