Skip to content

Commit ff417b4

Browse files
committed
docs: 对齐减签/加签与合并审批文档,长段落表格化
- 动作/事件数量由 8 更正为 9,补 REDUCE_AUDIT 与 FlowRecordReduceAuditEvent - action.md 补 batchable()、动作约束与批量能力说明 - exception.md 补减签/加签工厂方法与错误码 - rest-api.md 动作枚举、forwardOperatorIds、FlowContent 字段表格化 - 服务分工补子流程重置/结果/会话工厂;事件/会话/模拟仓储段落表格化 - 使用手册与集成手册同步减签动作与事件,同步前端子模块指针
1 parent c748ee7 commit ff417b4

13 files changed

Lines changed: 126 additions & 76 deletions

File tree

‎docs/Integration/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,12 @@
3232
| [快速开始](./quick-start.md) | 最小集成步骤:引入依赖 → 提供 Bean → 编写流程 → 发起流程 |
3333
| [流程用户体系](./user-integration.md) | `FlowOperatorGateway` / `IFlowOperator` / `GatewayContext` / 线程缓存 / 当前登录人 |
3434
| [流程默认脚本](./script-integration.md) | 12 种脚本类型、`GroovyScriptRequest` 完整 API、`$bind`、默认脚本替换、脚本生命周期 |
35-
| [流程事件机制](./event-integration.md) | 8 种事件、`EventPusher`、`IHandler` 订阅、异步分发管道、事务变体、推送时机 |
35+
| [流程事件机制](./event-integration.md) | 9 种事件、`EventPusher`、`IHandler` 订阅、异步分发管道、事务变体、推送时机 |
3636
| [仓储抽象与持久化](./repository-integration.md) | `IRepositoryHolder`、12 个仓储接口(含 11 个 JPA 实现 + 需自行实现的 `NodeViewJavaScriptRepository`)、脚本仓储、锁机制 |
3737
| [Spring Boot 自动配置](./auto-configuration.md) | `AutoConfiguration` 8 个 Bean、4 个 Register、必选/可选 Bean 清单 |
3838
| [REST API](./rest-api.md) | 5 个 Controller、`mockKey`/`operatorId` 分流机制、请求/响应结构 |
3939
| [Mock 模式](./mock-mode.md) | 全内存沙箱 `MockInstance`、15 分钟过期、接入方式 |
40-
| [节点/动作/策略扩展](./extension-points.md) | 19 种节点 × 8 种动作 × 15 种节点策略 × 2 种流程策略,扩展方式 |
40+
| [节点/动作/策略扩展](./extension-points.md) | 19 种节点 × 9 种动作 × 15 种节点策略 × 2 种流程策略,扩展方式 |
4141
| [编程式 API](./programmatic-api.md) | `WorkflowBuilder`/`FlowFormBuilder` 构建流程、`FlowService` 服务编排、查询服务 |
4242

4343
## 核心架构速览

‎docs/Integration/event-integration.md‎

Lines changed: 10 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ public interface IAsyncEvent extends IEvent {} // 异步事件标记 ←
2727

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

30-
### 1.2 八种事件
30+
### 1.2 九种事件
3131

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

@@ -40,19 +40,17 @@ public interface IAsyncEvent extends IEvent {} // 异步事件标记 ←
4040
| `FlowRecordRevokeEvent` | 撤销(被撤销的后置记录) | `FlowRecord currentRecord, boolean mock` | `getCurrentRecord()` / `isMock()` |
4141
| `FlowRecordUrgeEvent` | 催办(每条待办) | `FlowRecord, IFlowOperator urgeOperator, boolean mock` | `getFlowRecord()` / `getUrgeOperator()` / `isMock()` |
4242
| `FlowRecordDeleteEvent` | 删除未流转实例(开始节点) | `FlowRecord, boolean mock` | `getFlowRecord()` / `isMock()` |
43+
| `FlowRecordReduceAuditEvent` | 减签(每条被撤下的记录) | `FlowRecord, long reduceOperatorId, boolean mock` | `getFlowRecord()` / `getReduceOperatorId()` / `isMock()` |
4344
| `FlowSubProcessResetEvent` | 子流程数据重置(issue #219) | `SubProcessRecord oldRecord, SubProcessRecord newRecord, long resetRecordId, IFlowOperator resetOperator, boolean mock` | `getOldRecord()` / `getNewRecord()` / `getResetRecordId()` / `getResetOperator()` / `isMock()` |
4445

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

47-
- 事件提醒业务方子流程数据已被重置:`oldRecord` 为被取代的旧聚合组快照(含全部旧实例流程id),
48-
`newRecord` 为重置后的新聚合组——继承实例沿用原流程id,重建实例为新流程id,
49-
重建实例的 `getSourceProcessId()` 记录其替换的旧实例流程id,据此完成旧 → 新流程id映射;
50-
- 事件经异步线程池分发、到达顺序不保证(重置同时伴随被作废记录的 `RevokeEvent`
51-
与重建实例的 `StartEvent`/`TodoEvent`),订阅方应按「同一 `parentRecordId` + 节点维度下
52-
**最大聚合组 id 为活跃组**」做幂等覆盖式收敛,禁止增量累加;
53-
- 事件的 `oldRecord` id 与订阅方当前活跃组 id 不一致时,说明存在丢失的重置事件,
54-
应通过节点记录查询(`/api/cmd/record/processNodes`)全量对账;
55-
- 旧实例记录不会被删除(仅聚合组标记已取代),订阅方收到事件后应自行将旧流程id的数据标记失效。
48+
| 关注点 | 约定 |
49+
|---|---|
50+
| 新旧聚合组 | `oldRecord` 为被取代的旧聚合组快照(含全部旧实例流程id);`newRecord` 为新聚合组,继承实例沿用原流程id、重建实例为新流程id,重建实例的 `getSourceProcessId()` 指向被替换的旧实例 |
51+
| 收敛方式 | 事件异步、到达顺序不保证(同时伴随 `RevokeEvent`/`StartEvent`/`TodoEvent`);按「同一 `parentRecordId` + 节点维度下最大聚合组 id 为活跃组」幂等覆盖,禁止增量累加 |
52+
| 丢事件对账 | `oldRecord` id 与订阅方当前活跃组不一致时,视为丢事件,调用 `/api/cmd/record/processNodes` 全量对账 |
53+
| 旧数据 | 旧实例记录不删除(仅标记聚合组已取代),订阅方需自行将旧流程id数据标记失效 |
5654

5755
范例(`FlowRecordUrgeEvent.java`,唯一带三个字段的事件):
5856

@@ -72,7 +70,7 @@ public class FlowRecordUrgeEvent implements IFlowEvent {
7270

7371
- 基本信息:`getId()`、`getProcessId()`、`getWorkTitle()`、`getWorkCode()`、`getNodeId()`、`getNodeType()`、`getNodeName()`、`getTitle()`、`getFormData()`(`Map<String,Object>`)
7472
- 操作人:`getCurrentOperatorId/Name()`、`getSubmitOperatorId/Name()`、`getCreateOperatorId/Name()`、`getForwardOperatorId/Name()`
75-
- 状态:`isTodo()`、`isDone()`、`isFinish()`、`isAutoDone()`、`isShow()`、`isNotEndNode()`
73+
- 状态:`isTodo()`、`isDone()`、`isFinish()`、`isAutoDone()`、`isShow()`、`isNotEndNode()`、`isPendingApproval()`(待审批,含顺序审批未激活的隐藏记录)
7674
- 抄送标记:`isNotify()`
7775
- 动作:`getActionId()`、`getActionType()`、`getActionName()`、`getAdvice()`
7876
- 并行:`getParallelId()`、`getParallelBranchNodeId()`、`getParallelBranchTotal()`
@@ -113,6 +111,7 @@ EventPusher.push(new FlowRecordStartEvent(flowRecord, session.isMock()));
113111
| `RejectAction.run()` | 当前记录 `DoneEvent` + 回退新记录 `TodoEvent` |
114112
| `ReturnAction.run()` | 当前记录 `DoneEvent` + 退回节点新记录 `TodoEvent` |
115113
| `AddAuditAction.run()` | 加签记录 `TodoEvent` |
114+
| `ReduceAuditAction.run()` | 每条被撤下记录 `ReduceAuditEvent` |
116115
| `TransferAction.run()` | 当前记录 `DoneEvent` + 转交人新记录 `TodoEvent` |
117116
| `DelegateAction.run()` | 当前记录 `DoneEvent` + 委托人新记录 `TodoEvent` |
118117
| `EndNode.fillNewRecord()` | `FinishEvent`(流程正常完成) |

‎docs/Integration/extension-points.md‎

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -37,25 +37,28 @@ SUB_PROCESS, TRIGGER
3737
| `TriggerNode` | `TRIGGER` | 触发节点(`TriggerScript` 副作用) |
3838
| `SubProcessNode` | `SUB_PROCESS` | 子流程节点 |
3939

40-
### 1.2 动作(8 种)
40+
### 1.2 动作(9 种)
4141

4242
`ActionType` 枚举(`flow-engine-framework/.../action/ActionType.java`):
4343

4444
```
45-
SAVE, PASS, REJECT, ADD_AUDIT, DELEGATE, RETURN, TRANSFER, CUSTOM
46-
保存 通过 拒绝 加签 委派 退回 转办 自定义
45+
SAVE, PASS, REJECT, ADD_AUDIT, REDUCE_AUDIT, DELEGATE, RETURN, TRANSFER, CUSTOM
46+
保存 通过 拒绝 加签 减签 委派 退回 转办 自定义
4747
```
4848

49-
| 动作 | 特有配置 | 说明 |
50-
|---|---|---|
51-
| `SaveAction` | — | 仅保存表单,不流转 |
52-
| `PassAction` | — | 通过 → 推进入下一节点;多人审批按策略自动办结/激活 |
53-
| `RejectAction` | `ActionRejectScript` | 拒绝 → 退回指定节点/退回上级/终止流程(`TERMINATE`) |
54-
| `AddAuditAction` | `OperatorLoadScript` + `maxOperatorCount` | 加签(追加审批人) |
55-
| `DelegateAction` | `OperatorLoadScript` + `maxOperatorCount` | 委派(他人代审) |
56-
| `ReturnAction` | — | 退回(目标由 `FlowAdvice.backNode` 提供) |
57-
| `TransferAction` | `OperatorLoadScript` + `maxOperatorCount` | 转办 |
58-
| `CustomAction` | `ActionCustomScript` + `triggerFrontEvent` | 自定义动作(脚本返回动作类型) |
49+
| 动作 | 特有配置 | 批量提交 | 说明 |
50+
|---|---|---|---|
51+
| `SaveAction` | — | 支持 | 仅保存表单,不流转 |
52+
| `PassAction` | — | 支持 | 通过 → 推进入下一节点;多人审批按策略自动办结/激活 |
53+
| `RejectAction` | `ActionRejectScript` | 支持 | 拒绝 → 退回指定节点/退回上级/终止流程(`TERMINATE`) |
54+
| `AddAuditAction` | `OperatorLoadScript` + `maxOperatorCount` | 支持 | 加签;目标已在本节点待办队列时拒绝 |
55+
| `ReduceAuditAction` | `OperatorLoadScript` | **不支持** | 减签;仅循序/并签节点,仅剩 1 名待审批人时拒绝 |
56+
| `DelegateAction` | `OperatorLoadScript` + `maxOperatorCount` | 支持 | 委派(他人代审) |
57+
| `ReturnAction` | — | 支持 | 退回(目标由 `FlowAdvice.backNode` 提供) |
58+
| `TransferAction` | `OperatorLoadScript` + `maxOperatorCount` | 支持 | 转办 |
59+
| `CustomAction` | `ActionCustomScript` + `triggerFrontEvent` | 支持 | 自定义动作(脚本返回动作类型) |
60+
61+
> `batchable()` 由 `IFlowAction` 声明,默认 `true`;`ReduceAuditAction` 为 `false`,detail 响应中以 `actions[].batchable` 下发。
5962
6063
### 1.3 节点策略(15 种)
6164

@@ -155,7 +158,7 @@ IFlowAction#run
155158
| 子类 | 典型工厂方法与错误场景 |
156159
|---|---|
157160
| `FlowValidationException` | `fieldReadOnly`(字段只读)、`operatorCountExceeded(nodeId, max)`(超出最大可选人数)、`operatorOutOfRange`(超出可选范围)、`required` 等 |
158-
| `FlowExecutionException` | `scriptExecutionError`、`routerNodeNotFound`、`operatorCountExceeded`、`invalidJumpTarget(nodeType)`、`errorTriggerLoop`、`subProcessLoop` 等 |
161+
| `FlowExecutionException` | `scriptExecutionError`、`routerNodeNotFound`、`operatorCountExceeded`、`invalidJumpTarget(nodeType)`、`errorTriggerLoop`、`subProcessLoop`、`addAuditOperatorAlreadyInTodo`、`reduceAuditSingleApprover`、`reduceAuditTargetNotFound` 等 |
159162
| `FlowStateException` | `repositoryNotRegistered`、`recordAlreadyDone`、`operatorNotMatch`、`workflowAlreadyDisable`、`recordNotSupportRevoke` 等 |
160163
| `FlowNotFoundException` | `workflow(workCode)`、`record(recordId)`、`node(nodeId)`、`operator(operatorId)`、`action(actionId)` |
161164
| `FlowPermissionException` | `accessDenied(operation)` |

‎docs/Integration/mock-mode.md‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,18 @@ public void clear(String key); // 注销并 cancel 过期调
3434
### 2.3 `MockRepositoryHolder`(`mock/MockRepositoryHolder.java`)
3535

3636
- 实现 `IRepositoryHolder`,构造时 `new` 出 9 个内存仓储(`mock/repository/` 下):
37-
`DelayTaskRepositoryMockImpl`、`FlowRecordRepositoryMockImpl`、`FlowTodoMergeRepositoryMockImpl`、`FlowTodoRecordRepositoryMockImpl`、`ParallelBranchRepositoryMockImpl`、`SubProcessRepositoryMockImpl`、`UrgeIntervalRepositoryMockImpl`、`WorkflowRuntimeRepositoryMockImpl`、`WorkflowVersionRepositoryMockImpl`。
37+
38+
| 仓储实现 | 对应数据 |
39+
|---|---|
40+
| `FlowRecordRepositoryMockImpl` | 流程记录 |
41+
| `FlowTodoRecordRepositoryMockImpl` | 待办记录 |
42+
| `FlowTodoMergeRepositoryMockImpl` | 待办合并关系 |
43+
| `WorkflowRuntimeRepositoryMockImpl` | 运行时快照 |
44+
| `WorkflowVersionRepositoryMockImpl` | 流程版本 |
45+
| `SubProcessRepositoryMockImpl` | 子流程聚合 |
46+
| `ParallelBranchRepositoryMockImpl` | 并行分支 |
47+
| `DelayTaskRepositoryMockImpl` | 延迟任务 |
48+
| `UrgeIntervalRepositoryMockImpl` | 催办间隔 |
3849
- 流程设计(`WorkflowRepository`)使用**真实传入**的仓储 —— Mock 模式可复用生产已保存的流程设计。
3950
- `operatorAssignmentCache`(HashMap,key = `processId:nodeId`)模拟「发起人设定操作人」分配。
4051
- `createFlowActionService(session)` 传 `allowDisabledAction = true`(Mock 下允许执行停用流程的动作)。

‎docs/Integration/programmatic-api.md‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -184,16 +184,17 @@ workflowService.saveWorkflowVersion(new WorkflowVersion(workflow), true, true);
184184

185185
引擎内部以不可变 `FlowSession` 传递执行上下文,业务方在脚本/事件处理中可读取:
186186

187-
```java
188-
session.getCurrentOperator() // 当前审批人
189-
session.getCreatedOperator() // 流程创建者
190-
session.getSubmitOperator() // 提交人
191-
session.getWorkflow() // 流程设计
192-
session.getCurrentNode() // 当前节点
193-
session.getCurrentAction() // 当前动作
194-
session.getCurrentRecord() // 当前记录
195-
session.getFormData("fieldCode") // 表单字段值
196-
session.isMock() // 是否 Mock
197-
session.matchNextNodes() // 匹配的下一节点列表
198-
session.updateSession(node) // 不可变式切换会话(内部流转用)
199-
```
187+
| 方法 | 返回 | 用途 |
188+
|---|---|---|
189+
| `getCurrentOperator()` | `IFlowOperator` | 当前审批人 |
190+
| `getCreatedOperator()` | `IFlowOperator` | 流程创建者 |
191+
| `getSubmitOperator()` | `IFlowOperator` | 提交人 |
192+
| `getWorkflow()` | `Workflow` | 流程设计 |
193+
| `getCurrentNode()` | `IFlowNode` | 当前节点 |
194+
| `getCurrentAction()` | `IFlowAction` | 当前动作 |
195+
| `getCurrentRecord()` | `FlowRecord` | 当前记录 |
196+
| `getCurrentNodeRecords()` | `List<FlowRecord>` | 当前节点实例的全部记录(含隐藏) |
197+
| `getFormData(code)` | `Object` | 表单字段值 |
198+
| `isMock()` | `boolean` | 是否 Mock |
199+
| `matchNextNodes()` | `List<IFlowNode>` | 匹配的下一节点 |
200+
| `updateSession(node)` | `FlowSession` | 不可变式切换会话(内部流转用) |

‎docs/Integration/rest-api.md‎

Lines changed: 22 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ operatorId 请求参数 → 存在 → 使用该 id 作为当前操作人
2626
| GET | `/api/cmd/record/detail` | query `id` | `SingleResponse<FlowContent>` | 流程详情(含当前节点/表单/动作/历史/待办列表) |
2727
| POST | `/api/cmd/record/processNodes` | `FlowProcessNodeRequest` | `MultiResponse<ProcessNode>` | 流程流转节点预览 |
2828
| POST | `/api/cmd/record/create` | `FlowCreateRequest` | `SingleResponse<Long>` | 发起流程,返回首条记录 id |
29-
| POST | `/api/cmd/record/action` | `FlowActionRequest` | `SingleResponse<ActionResponse>` | 执行动作(通过/拒绝/加签/委派/退回/转办/自定义/保存) |
29+
| POST | `/api/cmd/record/action` | `FlowActionRequest` | `SingleResponse<ActionResponse>` | 执行动作(通过/拒绝/加签/减签/委派/退回/转办/自定义/保存) |
3030
| POST | `/api/cmd/record/subProcess/reset` | `FlowSubProcessResetRequest` | `Response` | 子流程数据重置(独立接口,需子流程节点开启重置能力) |
3131
| POST | `/api/cmd/record/urge` | `IdRequest` | `Response` | 催办 |
3232
| POST | `/api/cmd/record/revoke` | `IdRequest` | `Response` | 撤销 |
@@ -140,9 +140,10 @@ public interface FlowRecordQueryService {
140140
}
141141
```
142142

143-
- `actionId` 决定执行动作(PASS/REJECT/ADD_AUDIT/DELEGATE/RETURN/TRANSFER/CUSTOM/SAVE)。
144-
- `forwardOperatorIds`:加签/委派/转办的目标操作人。
143+
- `actionId` 决定执行动作(PASS/REJECT/ADD_AUDIT/REDUCE_AUDIT/DELEGATE/RETURN/TRANSFER/CUSTOM/SAVE)。
144+
- `forwardOperatorIds`:加签/减签/委派/转办的目标操作人。
145145
- `backNodeId`:退回动作的目标节点(仅 Start/Approval/Handle 可退回)。
146+
- 减签每次只能处理一条记录,目标必须是该流程实例当前节点的其他待审批人。
146147

147148
### `FlowSubProcessResetRequest`(子流程数据重置,独立接口)
148149

@@ -177,23 +178,25 @@ public interface FlowRecordQueryService {
177178
- `MANUAL_NODE_SELECT`:通过后需要选择人工节点分支。
178179
- `OPERATOR_SELECT`:下一节点为发起人设定操作人(`INITIATOR_SELECT`),需要选择操作人(`operators` = 可选范围,`maxOperatorCount` = 最大可选人数,-1 不限制)。
179180

180-
### `FlowContent`(详情响应,字段摘要)
181+
### `FlowContent`(详情响应)
181182

182-
```
183-
recordId / processId / workId / workTitle / workDescription / createTime / workCode
184-
view / code / viewTitle / nodeName / nodeId / nodeType
185-
title(节点标题) / adviceRequired / signRequired / adviceHidden
186-
form(FlowForm 元数据) / fieldPermissions(字段权限)
187-
todos(当前节点待办 Body 列表) / actions / actionList
188-
mergeable / createOperator / currentOperator / currentNodeOperators / flowState / recordState
189-
histories(审批历史) / nodes(NodeOption 可操作节点) / revoke / urge
190-
resetSubProcess(子流程重置能力标识:当前待办位于开启重置能力、已汇聚完成的子流程的锁定合并节点上时为 true;更深层下游节点为 false)
191-
```
192-
193-
- `currentNodeOperators`:当前记录所属**节点实例**中仍待审批的人员(`id` / `name`,按人去重,排除当前操作人,含顺序审批尚未激活的隐藏记录)。减签等只能作用于当前节点其他待审批人的动作应以此字段作为候选来源,不要使用宿主的全局用户列表。
194-
- 该字段按单条流程记录计算;合并审批(`mergeable = true`)下多条流程实例的待审批人集合可能不同,不能跨流程合并候选人。
195-
- `actions` / `actionList` 中每个动作额外带有 `batchable` 标记:`true` 表示支持合并批量提交,`false` 表示只能单条记录提交(当前为 `REDUCE_AUDIT`)。该标记只在响应中附加,不写入流程设计持久化数据;旧版本服务端无此字段时前端按 `true` 处理。
196-
- 合并审批(`mergeable = true`)时前端不展示 `batchable = false` 的动作;从合并列表进入**单条流程**后,按该条记录自己的 `actions` / `currentNodeOperators` 展示并提交(提交目标固定为该记录)。
183+
| 分组 | 字段 |
184+
|---|---|
185+
| 标识 | `recordId` / `processId` / `workId` / `workTitle` / `workDescription` / `workCode` / `createTime` |
186+
| 节点与视图 | `nodeId` / `nodeType` / `nodeName` / `title` / `view` / `code` / `viewTitle` |
187+
| 表单 | `form`(FlowForm 元数据) / `fieldPermissions` |
188+
| 意见与签名 | `adviceRequired` / `signRequired` / `adviceHidden` |
189+
| 动作 | `actions`(当前可见) / `actionList`(全部) |
190+
| 人员 | `createOperator` / `currentOperator` / `currentNodeOperators` |
191+
| 待办与状态 | `todos` / `mergeable` / `flowState` / `recordState` |
192+
| 其他 | `histories` / `nodes` / `revoke` / `urge` / `resetSubProcess` |
193+
194+
| 字段/标记 | 说明 |
195+
|---|---|
196+
| `currentNodeOperators` | 当前节点实例仍待审批的人员(去重、排除当前操作人、含未激活隐藏记录);减签候选人来源,按单条记录计算,不可跨流程合并 |
197+
| `actions[].batchable` | 是否支持合并批量提交(当前仅 `REDUCE_AUDIT` 为 `false`);仅响应附加、不落库;旧服务端缺省按 `true` |
198+
| `resetSubProcess` | 当前待办位于开启重置能力且已汇聚完成的子流程锁定节点时为 `true` |
199+
| 合并审批展示 | `mergeable && todos.length > 1` 时隐藏 `batchable=false` 的动作;进入单条流程后按该记录的 `actions` / `currentNodeOperators` 展示并提交 |
197200

198201
### `FlowRecordContent`(列表响应,字段摘要)
199202

0 commit comments

Comments
 (0)