# 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 编排底座
* 业务流程控制层
* 长任务调度引擎

在不引入新能力的前提下，本说明书描述的即为**当前版本的完整行为定义**。