# 使用指南：Vue Flow 工作流设计器

## 🎯 快速上手（5分钟）

### 第一步：打开设计器

访问：`http://localhost:5173/workflow/vue-flow-design`

### 第二步：添加第一个节点

1. 查看左侧节点面板，展开"API 调用"分类
2. 找到"HTTP Request"节点
3. **拖拽**到画布中央
4. 松开鼠标，节点自动生成 ID：`n1`

### 第三步：配置节点

1. **点击**刚创建的节点
2. 右侧抽屉自动打开
3. 填写配置：
   - URL: `https://api.github.com/users/octocat`
   - Method: `GET`
4. 点击"保存"

### 第四步：添加第二个节点

1. 从左侧拖拽"Send Email"节点到画布
2. 连接两个节点：
   - 从 `n1` 右侧的 **○** 连接点拖拽
   - 到 `n2` 左侧的 **○** 连接点
3. 松开鼠标，创建边（连线）

### 第五步：使用字段映射

1. 点击 `n2`（邮件节点）
2. 在"To"字段旁，点击 📋 图标
3. 选择上游节点：`n1 (HTTP Request)`
4. 展开字段树：`output` → `body` → `email`
5. 点击 `email`
6. 自动填充：`${nodes.n1.output.body.email}`

### 第六步：保存工作流

1. 点击顶部工具栏"保存"按钮
2. 控制台输出工作流定义（JSON）
3. 可以导出为文件：更多 → 导出

---

## 📚 详细功能说明

### 1. 节点操作

#### 添加节点
- **方式1**: 拖拽节点面板中的节点到画布
- **方式2**: (未来) 双击画布，选择节点类型

#### 选中节点
- 单击节点
- 节点边框变为蓝色高亮
- 右侧配置面板自动打开

#### 移动节点
- 拖拽节点到新位置
- 位置自动保存

#### 删除节点
- 选中节点后，点击配置面板底部"删除节点"
- 或按键盘 `Delete` 键

### 2. 连接操作

#### 创建连接
1. 从源节点右侧 **○** 拖拽
2. 到目标节点左侧 **○**
3. 创建有向边

#### 条件连接
1. 创建普通连接
2. 点击边（连线）
3. 在配置面板设置条件表达式
4. 示例：`${nodes.n1.output.statusCode} == 200`

#### 删除连接
- 点击边，右侧配置面板显示边信息
- 点击"删除"（未来功能）
- 或选中后按 `Delete`

### 3. 配置面板详解

#### 节点基本信息
- **节点 ID**: 自动生成，不可修改（如 `n1`, `n2`）
- **节点类型**: 固定，不可修改
- **节点名称**: 可编辑，用于显示

#### 动态表单字段

根据节点类型自动生成，常见字段类型：

| 字段类型 | 渲染控件 | 示例 |
|---------|---------|------|
| text | 单行输入 | URL, Email |
| textarea | 多行输入 | Description, Content |
| number | 数字输入 | Timeout, Retry Count |
| select | 下拉选择 | Method, Status |
| boolean | 开关 | Enabled, Required |
| code | 代码编辑器 | SQL, JavaScript |
| key_value | 键值对 | Headers, Parameters |

#### 字段功能按钮

**🔧 表达式按钮** (`supportsExpression=true`)
- 点击切换：静态值 ↔ 表达式
- 表达式模式：输入 `${...}` 格式
- 静态值模式：输入普通文本

**📋 字段选择器按钮** (`supportsFieldMapping=true`)
- 打开字段选择器弹窗
- 从上游节点选择字段
- 自动生成完整表达式

### 4. 字段选择器

#### 使用场景
当需要引用上游节点的输出数据时，使用字段选择器自动生成表达式。

#### 操作步骤
1. 点击字段右侧 📋 按钮
2. 左侧列表选择上游节点
3. 右侧树形展开字段路径
4. 点击叶子节点（绿色标签"可选"）
5. 自动生成表达式并关闭

#### 字段树示例

```
HTTP Request (n1)
└── output
    ├── statusCode: number
    ├── body: object
    │   ├── id: number        ← 可选
    │   ├── name: string      ← 可选
    │   └── email: string     ← 可选
    ├── headers: object
    └── elapsed: number       ← 可选
```

点击 `email` → 生成 `${nodes.n1.output.body.email}`

### 5. 表达式语法

#### 节点数据引用
```javascript
${nodes.n1.output.body.email}       // 引用节点n1的输出
${nodes.http_1.output.statusCode}   // 引用HTTP状态码
```

#### 工作流输入
```javascript
${workflow.input.userId}            // 工作流启动时的输入
${workflow.input.approver}          // 审批人
```

#### 工作流变量
```javascript
${workflow.variables.env}           // 工作流级别变量
${workflow.variables.timeout}
```

#### 环境变量
```javascript
${env.API_KEY}                      // 系统环境变量
${env.DATABASE_URL}
```

#### 条件表达式（边）
```javascript
${nodes.n1.output.statusCode} == 200
${nodes.n2.output.approved} == true
${nodes.n3.output.count} > 10
${nodes.n4.output.type} == "success"
```

### 6. 工具栏功能

#### 撤销/重做
- **撤销**: Ctrl+Z 或点击"撤销"按钮
- **重做**: Ctrl+Shift+Z 或点击"重做"按钮
- 最多保留50步历史记录

#### 保存
- 点击"保存"按钮
- 生成 `WorkflowDefinition` JSON
- 提交到后端 API（未来集成）

#### 更多菜单
- **预览定义**: 查看生成的 JSON
- **导出**: 下载为 `.json` 文件
- **导入**: 从文件加载工作流
- **加载示例**: 加载预设示例工作流
- **清空画布**: 删除所有节点和连线

### 7. 画布操作

#### 平移画布
- **鼠标中键拖拽**
- **鼠标右键拖拽**
- 触控板双指滑动

#### 缩放画布
- **鼠标滚轮**
- 右下角控制面板的 + / - 按钮
- 触控板双指缩放

#### 适应视图
- 点击右下角控制面板的 🔲 按钮
- 自动调整缩放和位置，显示所有节点

#### 小地图
- 右下角显示整个画布的缩略图
- 不同节点类型用不同颜色标识
- 点击小地图可快速导航

---

## 💡 实战案例

### 案例1：用户注册流程

**需求**：
1. 调用 API 创建用户
2. 如果成功，发送欢迎邮件
3. 如果失败，记录错误日志

**实现步骤**：

1. **添加节点**：
   - `n1`: HTTP Request (POST /api/users)
   - `n2`: Condition (检查状态码)
   - `n3`: Send Email (欢迎邮件)
   - `n4`: Database Query (记录错误)

2. **配置 n1 (HTTP Request)**：
   ```json
   {
     "url": "https://api.example.com/users",
     "method": "POST",
     "body": {
       "name": "${workflow.input.name}",
       "email": "${workflow.input.email}"
     }
   }
   ```

3. **配置 n2 (Condition)**：
   ```javascript
   ${nodes.n1.output.statusCode} == 201
   ```

4. **连接节点**：
   - `n1` → `n2`
   - `n2` → `n3` (条件: true)
   - `n2` → `n4` (条件: false)

5. **配置 n3 (Send Email)**：
   ```json
   {
     "to": "${workflow.input.email}",
     "subject": "欢迎注册",
     "content": "Hello ${workflow.input.name}"
   }
   ```

### 案例2：数据同步

**需求**：
1. 从数据库查询数据
2. 转换数据格式
3. 调用 API 上传

**实现步骤**：

1. **添加节点**：
   - `n1`: Database Query
   - `n2`: Data Transform
   - `n3`: HTTP Request

2. **配置 n1**：
   ```sql
   SELECT * FROM users WHERE updated_at > '${workflow.input.lastSyncTime}'
   ```

3. **配置 n2**：
   ```javascript
   return ${nodes.n1.output.rows}.map(user => ({
     id: user.id,
     name: user.full_name,
     email: user.email
   }))
   ```

4. **配置 n3**：
   ```json
   {
     "url": "https://api.example.com/sync",
     "method": "POST",
     "body": "${nodes.n2.output.result}"
   }
   ```

---

## ⚠️ 常见问题

### Q1: 字段选择器为什么是灰色？
**A**: 没有上游节点。请先添加上游节点并连接。

### Q2: 表达式报错"找不到节点"？
**A**: 检查表达式中的节点 ID 是否正确。节点 ID 区分大小写。

### Q3: 如何引用数组中的第一个元素？
**A**: 使用 `${nodes.n1.output.items[0].name}`

### Q4: 如何设置默认值？
**A**: 在 Mock 数据的 `FieldDefinition` 中设置 `defaultValue`。

### Q5: 保存按钮没反应？
**A**: 目前只输出到控制台。后续会集成真实 API。

---

## 📞 获取帮助

- **查看日志**: 打开浏览器控制台（F12）
- **查看文档**: `ARCHITECTURE.md` 和 `README.md`
- **查看示例**: 工具栏 → 更多 → 加载示例

---

**祝您使用愉快！** 🎉

