319 lines
5.0 KiB
Markdown
319 lines
5.0 KiB
Markdown
# Workflow Engine 使用说明书
|
||
|
||
> 版本：v1.1（sqlor 持久化 + 子流程 input/output mapping）
|
||
|
||
本文档用于说明当前 Workflow Engine 的**设计目标、核心概念、数据模型、DSL 用法、执行语义以及使用示例**。不涉及未来规划能力。
|
||
|
||
---
|
||
|
||
## 1. 引擎定位与设计原则
|
||
|
||
### 1.1 引擎是什么
|
||
|
||
这是一个：
|
||
|
||
* **DAG（有向无环图）流程引擎内核**
|
||
* 支持 **条件转移 / 并发 / 子流程**
|
||
* 支持 **Definition / Instance 分离**
|
||
* 支持 **数据库持久化与恢复**
|
||
|
||
它不是：
|
||
|
||
* 简单任务编排脚本
|
||
* BPMN UI 工具
|
||
* 强绑定某种业务或 skill 的框架
|
||
|
||
---
|
||
|
||
### 1.2 核心设计原则
|
||
|
||
1. **流程定义不可变，实例可变**
|
||
2. **所有运行状态必须可持久化**
|
||
3. **流程控制与业务执行解耦**
|
||
4. **子流程是边界，而不是函数调用**
|
||
5. **数据流必须显式声明（input / output mapping）**
|
||
|
||
---
|
||
|
||
## 2. 核心概念说明
|
||
|
||
### 2.1 FlowDefinition（流程定义）
|
||
|
||
* 描述“流程长什么样”
|
||
* 由 YAML DSL 表达
|
||
* 可被多个流程实例复用
|
||
|
||
包含内容：
|
||
|
||
* 起始节点（start）
|
||
* 节点集合（nodes）
|
||
* 边集合（edges）
|
||
|
||
---
|
||
|
||
### 2.2 FlowInstance（流程实例）
|
||
|
||
* 流程的一次真实运行
|
||
* 持有自己的：
|
||
|
||
* ctx（上下文）
|
||
* active_nodes（当前活跃节点）
|
||
* status（running / finished）
|
||
|
||
**所有流转都发生在实例中，而不是定义中。**
|
||
|
||
---
|
||
|
||
### 2.3 Node 类型
|
||
|
||
| 类型 | 说明 |
|
||
| -------- | ------------------ |
|
||
| task | 普通执行节点（业务 / skill） |
|
||
| decision | 条件判断节点 |
|
||
| join | 并发汇合节点 |
|
||
| subflow | 子流程节点 |
|
||
| end | 结束节点 |
|
||
|
||
---
|
||
|
||
## 3. 数据模型（数据库表）
|
||
|
||
### 3.1 flow_definition
|
||
|
||
用于存储流程定义（DSL）。
|
||
|
||
关键字段：
|
||
|
||
* id：定义 ID
|
||
* name / version：业务标识
|
||
* dsl：YAML 内容
|
||
|
||
---
|
||
|
||
### 3.2 flow_instance
|
||
|
||
用于存储流程运行状态。
|
||
|
||
关键字段：
|
||
|
||
* id：实例 ID
|
||
* flow_def_id：关联定义
|
||
* ctx：JSON 上下文
|
||
* active_nodes：当前节点集合
|
||
* status：running / finished
|
||
|
||
---
|
||
|
||
### 3.3 node_execution
|
||
|
||
用于记录节点执行历史（审计 / 回放）。
|
||
|
||
关键字段：
|
||
|
||
* instance_id
|
||
* node_id
|
||
* input_ctx / output_ctx
|
||
* status
|
||
|
||
---
|
||
|
||
### 3.4 subflow_instance
|
||
|
||
用于描述父子流程关系。
|
||
|
||
关键字段：
|
||
|
||
* parent_instance_id
|
||
* parent_node_id
|
||
* child_instance_id
|
||
* status
|
||
|
||
这是“子流程存在性”的核心表。
|
||
|
||
---
|
||
|
||
## 4. YAML DSL 说明
|
||
|
||
### 4.1 基本结构
|
||
|
||
```yaml
|
||
id: order_flow_v1
|
||
start: start
|
||
|
||
nodes:
|
||
start:
|
||
type: task
|
||
|
||
end:
|
||
type: end
|
||
|
||
edges:
|
||
- from: start
|
||
to: end
|
||
```
|
||
|
||
---
|
||
|
||
### 4.2 条件转移
|
||
|
||
```yaml
|
||
edges:
|
||
- from: decision
|
||
to: approved
|
||
when: ctx.ok == true
|
||
|
||
- from: decision
|
||
to: rejected
|
||
when: ctx.ok == false
|
||
```
|
||
|
||
条件表达式在运行时基于 ctx 求值。
|
||
|
||
---
|
||
|
||
### 4.3 并发（Fork / Join）
|
||
|
||
#### Fork（隐式）
|
||
|
||
```yaml
|
||
edges:
|
||
- from: fetch
|
||
to: validate
|
||
- from: fetch
|
||
to: enrich
|
||
```
|
||
|
||
#### Join
|
||
|
||
```yaml
|
||
nodes:
|
||
join:
|
||
type: join
|
||
wait_for:
|
||
- validate
|
||
- enrich
|
||
```
|
||
|
||
join 节点只有在所有依赖节点完成后才会继续。
|
||
|
||
---
|
||
|
||
## 5. 子流程（SubFlow）说明
|
||
|
||
### 5.1 子流程的定义方式
|
||
|
||
```yaml
|
||
nodes:
|
||
payment:
|
||
type: subflow
|
||
flow: payment_flow_v1
|
||
|
||
input:
|
||
order_id: ctx.order.id
|
||
amount: ctx.order.total
|
||
|
||
output:
|
||
pay_status: ctx.payment.status
|
||
pay_id: ctx.payment.id
|
||
```
|
||
|
||
---
|
||
|
||
### 5.2 子流程的执行语义
|
||
|
||
1. 父流程第一次到达 subflow 节点：
|
||
|
||
* 创建子流程实例
|
||
* 根据 input mapping 构建子 ctx
|
||
* 父流程阻塞在该节点
|
||
|
||
2. 子流程运行中：
|
||
|
||
* 父流程不推进
|
||
|
||
3. 子流程完成：
|
||
|
||
* 根据 output mapping 合并 ctx
|
||
* 父流程继续流转
|
||
|
||
---
|
||
|
||
### 5.3 input / output mapping 原则
|
||
|
||
* 子流程只能看到显式声明的输入
|
||
* 父流程只接收显式声明的输出
|
||
* ctx 不做隐式全量共享
|
||
|
||
这样可以保证：
|
||
|
||
* 数据边界清晰
|
||
* 子流程可复用
|
||
* 行为可审计
|
||
|
||
---
|
||
|
||
## 6. 执行模型
|
||
|
||
### 6.1 推进方式
|
||
|
||
引擎通过反复调用：
|
||
|
||
```
|
||
engine.step(instance_id)
|
||
```
|
||
|
||
来推进流程。
|
||
|
||
* 每次 step 只推进“可推进的节点”
|
||
* 阻塞节点（join / subflow）会被保留在 active_nodes 中
|
||
|
||
---
|
||
|
||
### 6.2 结束判定
|
||
|
||
当：
|
||
|
||
* active_nodes 中全部为 end 节点
|
||
|
||
则流程实例状态被置为：
|
||
|
||
```
|
||
status = finished
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 当前能力边界说明
|
||
|
||
### 已支持
|
||
|
||
* DAG 流程
|
||
* 条件转移
|
||
* 并发 / join
|
||
* 子流程（含 input/output mapping）
|
||
* 持久化 / 可恢复
|
||
|
||
### 明确未支持（但结构允许）
|
||
|
||
* 失败补偿
|
||
* 超时 / 重试
|
||
* 表达式安全沙箱
|
||
* 人工任务
|
||
|
||
---
|
||
|
||
## 8. 总结
|
||
|
||
当前这套 Workflow Engine 是一个：
|
||
|
||
> **结构清晰、语义明确、可扩展的流程引擎内核**
|
||
|
||
它适合作为：
|
||
|
||
* skills / agents 编排底座
|
||
* 业务流程控制层
|
||
* 长任务调度引擎
|
||
|
||
在不引入新能力的前提下，本说明书描述的即为**当前版本的完整行为定义**。
|
||
|