Skip to content
Merged

Dev #245

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
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,9 @@ build/
### workbuddy ###
.workbuddy/

### codebuddy ###
.codebuddy/

### Worktrees ###
.worktrees/

Expand Down
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Flow Engine 是一个企业级工作流引擎,基于 Java 17 和 Spring Boot 3

### 服务编排模式(FlowService)

`FlowService`(`flow-engine-framework/.../service/FlowService.java`)是 `@Transactional` 业务入口。**每个流程操作对应一个独立的 `FlowXxxService`**(`FlowCreateService` / `FlowActionService` / `FlowRevokeService` / `FlowDeleteService` / `FlowUrgeService` / `FlowDetailService`),通过 `IRepositoryHolder` 注入依赖,且每次操作前调用 `FlowOperatorLocalThreadCache.getInstance().clear()` 清理线程缓存。新增流程操作应沿用此模式:新建 `FlowXxxService(request, repositoryHolder)`,并在 `FlowService` 暴露一个入口方法。
`FlowService`(`flow-engine-framework/.../service/FlowService.java`)是 `@Transactional` 业务入口,共 8 个入口方法(detail / processNodes / create / action / revoke / delete / urge / resetSubProcess)。**每个流程操作对应一个独立的 `FlowXxxService`**(`FlowCreateService` / `FlowActionService` / `FlowRevokeService` / `FlowDeleteService` / `FlowUrgeService` / `FlowDetailService` / `FlowProcessNodeService` / `FlowSubProcessResetService` / `FlowSubProcessResultService` / `FlowDelayTriggerService` / `OperatorAssignmentService` 等),通过 `IRepositoryHolder` 注入依赖,且每次操作前调用 `FlowOperatorLocalThreadCache.getInstance().clear()` 与 `FlowRuntimeScriptLocalCache` 清理线程缓存。新增流程操作应沿用此模式:新建 `FlowXxxService(request, repositoryHolder)`,并在 `FlowService` 暴露一个入口方法。

### 仓储持有者(IRepositoryHolder)

Expand Down Expand Up @@ -64,11 +64,11 @@ REST 层通过请求参数 `mockKey` 分流到 Mock 实例(见 `FlowRecordCont

### 事件(IFlowEvent + EventPusher)

7 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)。操作完成后用 `EventPusher.push(event)` 推送;事件通常携带 `FlowRecord` + `mock` 标记。外部可用 Spring `@EventListener` 订阅。
8 种事件:开始 / 待办 / 已办 / 完成 / 催办 / 撤销(`FlowRecordRevokeEvent`)/ 删除(`FlowRecordDeleteEvent`)/ 子流程重置(`FlowSubProcessResetEvent`)。操作完成后用 `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-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-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 CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ Flow Engine 是一个企业级工作流引擎,基于 Java 17 和 Spring Boot 3

### 服务编排模式(FlowService)

`FlowService`(`flow-engine-framework/.../service/FlowService.java`)是 `@Transactional` 业务入口。**每个流程操作对应一个独立的 `FlowXxxService`**(`FlowCreateService` / `FlowActionService` / `FlowRevokeService` / `FlowDeleteService` / `FlowUrgeService` / `FlowDetailService`),通过 `IRepositoryHolder` 注入依赖,且每次操作前调用 `FlowOperatorLocalThreadCache.getInstance().clear()` 清理线程缓存。新增流程操作应沿用此模式:新建 `FlowXxxService(request, repositoryHolder)`,并在 `FlowService` 暴露一个入口方法。
`FlowService`(`flow-engine-framework/.../service/FlowService.java`)是 `@Transactional` 业务入口,共 8 个入口方法(detail / processNodes / create / action / revoke / delete / urge / resetSubProcess)。**每个流程操作对应一个独立的 `FlowXxxService`**(`FlowCreateService` / `FlowActionService` / `FlowRevokeService` / `FlowDeleteService` / `FlowUrgeService` / `FlowDetailService` / `FlowProcessNodeService` / `FlowSubProcessResetService` / `FlowSubProcessResultService` / `FlowDelayTriggerService` / `OperatorAssignmentService` 等),通过 `IRepositoryHolder` 注入依赖,且每次操作前调用 `FlowOperatorLocalThreadCache.getInstance().clear()` 与 `FlowRuntimeScriptLocalCache` 清理线程缓存。新增流程操作应沿用此模式:新建 `FlowXxxService(request, repositoryHolder)`,并在 `FlowService` 暴露一个入口方法。

### 仓储持有者(IRepositoryHolder)

Expand Down Expand Up @@ -68,7 +68,7 @@ REST 层通过请求参数 `mockKey` 分流到 Mock 实例(见 `FlowRecordCont

### API 模块划分

- **命令操作**:`flow-engine-starter-api` — `FlowRecordController`(`/api/cmd/record`:create / action / revoke / delete / urge / detail)与 `WorkflowController`(`/api/cmd/workflow`:流程设计 CRUD)
- **命令操作**:`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-query` — `FlowRecordQueryController`(`/api/query/record`:list / todo / done / notify)与 `WorkflowQueryController`(`/api/query/workflow`:list / options / versions)
- **持久化**:`flow-engine-starter-infra` — JPA 实体与仓储实现(含达梦方言)

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Flow Engine 是一个基于 Java 17 和 Spring Boot 3.5.9 构建的企业级工
flow-engine
├── flow-engine-framework # 核心流程引擎框架
├── flow-engine-starter # Spring Boot 自动配置入口
├── flow-engine-starter-api # REST API 层(命令操作:create / action / revoke / delete / urge / detail)
├── flow-engine-starter-api # REST API 层(命令操作:create / action / revoke / delete / urge / detail / processNodes / subProcess/reset,含节点视图脚本接口)
├── flow-engine-starter-infra # 持久化层(JPA 实体、11 个仓储实现、含达梦方言)
├── flow-engine-starter-query # 查询层(流程记录与流程定义只读 API)
├── flow-engine-example # 示例应用(H2/达梦数据库、JWT 认证、端口 8090)
Expand Down
4 changes: 2 additions & 2 deletions docs/Integration/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@
| [流程事件机制](./event-integration.md) | 8 种事件、`EventPusher`、`IHandler` 订阅、异步分发管道、事务变体、推送时机 |
| [仓储抽象与持久化](./repository-integration.md) | `IRepositoryHolder`、12 个仓储接口(含 11 个 JPA 实现 + 需自行实现的 `NodeViewJavaScriptRepository`)、脚本仓储、锁机制 |
| [Spring Boot 自动配置](./auto-configuration.md) | `AutoConfiguration` 8 个 Bean、4 个 Register、必选/可选 Bean 清单 |
| [REST API](./rest-api.md) | 4 个 Controller、`mockKey`/`operatorId` 分流机制、请求/响应结构 |
| [REST API](./rest-api.md) | 5 个 Controller、`mockKey`/`operatorId` 分流机制、请求/响应结构 |
| [Mock 模式](./mock-mode.md) | 全内存沙箱 `MockInstance`、15 分钟过期、接入方式 |
| [节点/动作/策略扩展](./extension-points.md) | 19 种节点 × 8 种动作 × 15 种节点策略 × 2 种流程策略,扩展方式 |
| [编程式 API](./programmatic-api.md) | `WorkflowBuilder`/`FlowFormBuilder` 构建流程、`FlowService` 服务编排、查询服务 |
Expand Down Expand Up @@ -72,7 +72,7 @@ REST 请求 → FlowRecordController
## 版本约定

- 引擎版本:`0.1.0-SNAPSHOT`(根 pom `revision`)
- 外部框架依赖(根 pom `codingapi.framework.version = 17.3.0`):
- 外部框架依赖(根 pom `codingapi.framework.version = 17.3.1`):
- `com.codingapi.springboot:springboot-starter` —— 事件体系(`EventPusher`/`IHandler`)、`UserContext`、`LocaleMessageException`
- `com.codingapi.springboot:springboot-starter-script` —— Groovy 脚本引擎(`GroovyScript`/注解/仓储 SPI)
- `com.codingapi.springboot:springboot-starter-data-fast` —— `FastRepository`(JPA 仓储基类)
Expand Down
3 changes: 2 additions & 1 deletion docs/Integration/extension-points.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ IFlowAction#run

## 5. 异常体系

基类 `FlowException extends LocaleMessageException`,5 个子类(`exception/` 包),均以静态工厂方法构造:
基类 `FlowException extends LocaleMessageException`,6 个子类(`exception/` 包),均以静态工厂方法构造:

| 子类 | 典型工厂方法与错误场景 |
|---|---|
Expand All @@ -159,5 +159,6 @@ IFlowAction#run
| `FlowStateException` | `repositoryNotRegistered`、`recordAlreadyDone`、`operatorNotMatch`、`workflowAlreadyDisable`、`recordNotSupportRevoke` 等 |
| `FlowNotFoundException` | `workflow(workCode)`、`record(recordId)`、`node(nodeId)`、`operator(operatorId)`、`action(actionId)` |
| `FlowPermissionException` | `accessDenied(operation)` |
| `WorkflowTransferException` | `invalidSchema()`、`unsupportedSchema()`、`scriptNotFound()`、`scriptTypeUnsupported()`、`replaceTargetNotFound()`(流程导入导出) |

REST 层经 `LocaleMessageException` 统一转换为 `{ errCode, errMessage }` 响应。
3 changes: 3 additions & 0 deletions docs/Integration/programmatic-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ public class FlowService {
void revoke(FlowRevokeRequest request); // 撤销
void delete(FlowDeleteRequest request); // 删除(仅未流转实例)
void urge(FlowUrgeRequest request); // 催办
void resetSubProcess(FlowSubProcessResetRequest request); // 子流程数据重置(独立接口)
}
```

Expand Down Expand Up @@ -66,6 +67,8 @@ void saveWorkflowRuntime(WorkflowRuntime workflowRuntime);
WorkflowRuntime getOrCreateWorkflowRuntime(Workflow workflow); // @Transactional(REQUIRES_NEW) + lockById
WorkflowRuntime getWorkflowRuntime(String workId, long workVersion);
String importWorkflow(String body, IFlowOperator createOperator); // 导入流程 JSON,返回 workId
String importWorkflow(String body, IFlowOperator createOperator, WorkflowImportMode mode); // 指定导入模式(增量/覆盖)
String exportWorkflow(String workId); // 导出流程及其全部版本和脚本
```

- `saveWorkflowVersion(version, creatable, enable)`:保存版本(`creatable=true` 时创建新版本并切为当前;`enable` 控制是否启用),内部会固化脚本(`WorkflowGroovyScriptUtils.saveScripts`)。
Expand Down
13 changes: 10 additions & 3 deletions docs/Integration/rest-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@ operatorId 请求参数 → 存在 → 使用该 id 作为当前操作人
| POST | `/api/cmd/workflow/create-custom-action` | — | `SingleResponse<Map>` | 创建自定义动作默认配置 |
| POST | `/api/cmd/workflow/mock` | — | `SingleResponse<String>` | 创建 Mock 沙箱,返回 mockKey(需流程管理员) |
| POST | `/api/cmd/workflow/cleanMock` | `IdRequest` | `Response` | 清理 Mock 沙箱 |
| GET | `/api/cmd/workflow/exists` | query `code` | `SingleResponse<Boolean>` | 判断流程编码是否存在 |

## 4. 查询(`/api/query/record`)

Expand Down Expand Up @@ -86,11 +87,14 @@ public interface FlowRecordQueryService {
| GET | `/api/query/workflow/options` | — | `MultiResponse<WorkflowOption>` | 流程下拉选项 |
| GET | `/api/query/workflow/versions` | query `id`(workId) | `MultiResponse<WorkflowVersionOption>` | 流程版本列表 |

## 6. 节点视图脚本(`/api/view/javascript`)
## 6. 节点视图脚本(`/api/cmd/node-view`)

`flow-engine-starter-api/src/main/java/com/codingapi/flow/api/controller/NodeViewJavaScriptController.java`

提供节点视图 JS 的读写接口(`NodeViewJavaScript` 持久化经 `NodeViewJavaScriptRepository`)。
| 方法 | 路径 | 参数/请求体 | 说明 |
|---|---|---|---|
| GET | `/api/cmd/node-view/getScript` | query `key` | 按缓存 key 获取节点视图 JS 内容 |
| POST | `/api/cmd/node-view/save` | JSON 请求体 | 保存节点视图 JS(`NodeViewJavaScript`,持久化经 `NodeViewJavaScriptRepository`) |

## 7. Groovy 脚本接口(`/api/groovy-script`)

Expand Down Expand Up @@ -145,11 +149,14 @@ public interface FlowRecordQueryService {
```json
{
"recordId": 456,
"operatorId": 1001,
"resetInstanceProcessIds": ["选中重建的子流程实例流程id"],
"advice": "重置说明"
}
```

- `operatorId` 必填(`verify()` 强制大于 0,缺失抛 `FlowValidationException.required("operatorId")`)。

- 重置不属于审批动作,不经过 `/action` 接口;仅当子流程节点开启 `resettable` 能力且当前待办位于其下游时可调用。
- 无需指定子流程节点:由选中实例流程id定位其所属聚合组,选中实例须同属一个已放行且未取代的聚合组。
- 流程详情 `FlowContent.resetSubProcess` 标识字段表明当前记录是否具备该能力,前端据此提供交互。
Expand Down Expand Up @@ -201,4 +208,4 @@ recordId / timeoutTime / recordState / flowState / notify
| `SingleResponse<T>` | `{ data: T, success, ... }` |
| `MultiResponse<T>` | `{ data: T[], total, success, ... }` |

异常统一为 `LocaleMessageException` 体系(`FlowException` 的 5 个子类,见 [扩展点](./extension-points.md#异常体系)),错误码见各异常工厂方法。
异常统一为 `LocaleMessageException` 体系(`FlowException` 的 6 个子类,见 [扩展点](./extension-points.md#异常体系)),错误码见各异常工厂方法。
2 changes: 1 addition & 1 deletion docs/Integration/script-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,7 +153,7 @@ request.getWorkflow() // Workflow 对象(可访问 form/nodes 等)

### 4.1 脚本对象(`GroovyScript`)

来自外部依赖 `com.codingapi.springboot:springboot-starter-script:17.3.0`。构造方式:
来自外部依赖 `com.codingapi.springboot:springboot-starter-script:17.3.1`。构造方式:

```java
GroovyScript groovyScript = GroovyScript.builder(key)
Expand Down
2 changes: 1 addition & 1 deletion docs/Integration/user-integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ public class GatewayContext {

### 3.1 用户实体实现 `IFlowOperator`

`flow-engine-example/src/main/java/com/codingapi/example/entity/User.java`:
`flow-engine-example/src/main/java/com/codingapi/example/entity/User.java`(节选,实际类还包含 `ADMIN_ROLE`/`ADMIN_ACCOUNT` 等常量、静态工厂 `admin(PasswordEncoder)`、`getRoles()`、`encodePassword()` 等成员):

```java
package com.codingapi.example.entity;
Expand Down
17 changes: 10 additions & 7 deletions docs/capabilities/flow-engine-framework/exception.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: flow-engine-framework/exception
module: flow-engine-framework
description: 流程异常体系,包含异常基类和 5 种业务异常子类
description: 流程异常体系,包含异常基类和 6 种业务异常子类
status: 已实现
scope: 后端
source: 项目自有
Expand All @@ -13,14 +13,15 @@ symbols:
- FlowStateException
- FlowNotFoundException
- FlowPermissionException
- WorkflowTransferException
content_hash: 1a3438bf88b6b98d84a03fabe6f08ed66948a8da8f44fea35b8a9d49d1f84458
---

## 解决什么问题

提供流程引擎的标准化异常体系,解决以下问题:

- **异常分类**:按业务语义将异常分为执行异常、验证异常、状态异常、未找到异常和权限异常五类
- **异常分类**:按业务语义将异常分为执行异常、验证异常、状态异常、未找到异常、权限异常和导入导出异常六类
- **错误码标准化**:每种异常使用 `errorCode + message` 格式,支持国际化消息
- **工厂方法创建**:每种异常提供静态工厂方法,统一异常创建方式并确保错误码一致

Expand All @@ -30,11 +31,12 @@ content_hash: 1a3438bf88b6b98d84a03fabe6f08ed66948a8da8f44fea35b8a9d49d1f84458

```
FlowException(抽象基类,继承 LocaleMessageException)
├── FlowExecutionException — 流程执行过程中的错误
├── FlowValidationException — 流程配置或参数验证错误
├── FlowStateException — 流程状态不允许当前操作
├── FlowNotFoundException — 请求的资源不存在
└── FlowPermissionException — 操作者无权限执行操作
├── FlowExecutionException — 流程执行过程中的错误
├── FlowValidationException — 流程配置或参数验证错误
├── FlowStateException — 流程状态不允许当前操作
├── FlowNotFoundException — 请求的资源不存在
├── FlowPermissionException — 操作者无权限执行操作
└── WorkflowTransferException — 流程定义导入导出错误
```

### 各类异常的工厂方法
Expand All @@ -46,6 +48,7 @@ FlowException(抽象基类,继承 LocaleMessageException)
| `FlowStateException` | `repositoryNotRegistered()`, `recordAlreadyDone()`, `operatorNotMatch()`, `edgeConfigError()`, `recordLimitUrgeError()` |
| `FlowNotFoundException` | `workflow()`, `record()`, `node()`, `operator()`, `action()` |
| `FlowPermissionException` | `accessDenied()` |
| `WorkflowTransferException` | `invalidSchema()`, `unsupportedSchema()`, `scriptNotFound()`, `scriptTypeUnsupported()`, `replaceTargetNotFound()` |

### 扩展新异常

Expand Down
7 changes: 6 additions & 1 deletion docs/capabilities/flow-engine-framework/flow-service.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ symbols:
- FlowProcessNodeService
- FlowRevokeService
- FlowUrgeService
- FlowDeleteService
- FlowSubProcessResetService
- FlowSubProcessResultService
- SubProcessSessionFactory
- OperatorAssignmentService
- WorkflowGroovyScriptUtils
content_hash: 48847288af1a4551b8327e398d01a8ec4de643dce1c049b90dcdc8ad0134df3b
Expand All @@ -27,7 +31,7 @@ content_hash: 48847288af1a4551b8327e398d01a8ec4de643dce1c049b90dcdc8ad0134df3b

提供流程引擎的业务服务层,将复杂的流程操作封装为高内聚的服务接口,解决以下问题:

- **流程操作入口**:`FlowService` 作为流程审批操作的统一入口,支持创建、审批、撤销、删除、催办
- **流程操作入口**:`FlowService` 作为流程审批操作的统一入口,支持创建、审批、撤销、删除、催办、子流程重置
- **流程设计管理**:`WorkflowService` 管理流程定义的 CRUD 和版本操作
- **职责分离**:每种操作由独立的 Service 实现(如 `FlowActionService`、`FlowCreateService`),保持单一职责
- **线程安全**:每次操作前通过 `FlowOperatorLocalThreadCache.clear()` 与 `FlowRuntimeScriptLocalCache.clear()` 清理线程缓存
Expand All @@ -45,6 +49,7 @@ content_hash: 48847288af1a4551b8327e398d01a8ec4de643dce1c049b90dcdc8ad0134df3b
| `urge(FlowUrgeRequest)` | 催办 |
| `detail(FlowDetailRequest)` | 查询流程详情 |
| `processNodes(FlowProcessNodeRequest)` | 查询流程节点记录 |
| `resetSubProcess(FlowSubProcessResetRequest)` | 子流程数据重置(独立接口,REST 端点 `POST /api/cmd/record/subProcess/reset`) |

### WorkflowService — 流程设计管理

Expand Down
2 changes: 1 addition & 1 deletion docs/capabilities/flow-engine-framework/node.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ IFlowNode(核心节点接口)

```java
// 通过工厂创建默认节点
IFlowNode startNode = NodeFactory.getInstance().createNode(NodeType.StartNode);
IFlowNode startNode = NodeFactory.getInstance().createNode(NodeType.START);

// 从 Map 反序列化节点
Map<String, Object> nodeData = ...;
Expand Down
Loading
Loading