# 字段映射功能指南

## 功能概述

字段映射功能允许您将上游节点的输出字段映射到当前节点的输入字段，实现数据在工作流节点之间的流转。

## 使用方法

### 1. 创建工作流

首先创建一个包含多个节点的工作流：

```
HTTP Request (n1) → Database Query (n2) → HTTP Request (n3)
```

### 2. 配置第一个节点

1. 点击第一个 HTTP Request 节点（n1）
2. 在右侧配置面板中填写：
   - URL: `https://api.example.com/users/1`
   - Method: `GET`
   
这个节点会返回用户数据，例如：
```json
{
  "output": {
    "body": {
      "id": 1,
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}
```

### 3. 配置第二个节点并使用字段映射

1. 点击第二个 Database Query 节点（n2）
2. 在 `query` 字段右侧，点击 **🕐 字段选择器**按钮
3. 在弹出的字段选择器中：
   - 左侧选择上游节点 `HTTP Request (n1)`
   - 右侧展开字段树，选择 `output.body.email`
4. 点击选择后，表达式会自动生成：`${nodes.n1.output.body.email}`
5. 在输入框下方会显示字段映射信息：
   ```
   🔗 来自节点 HTTP Request 的字段 output.body.email
   ```

### 4. 手动输入表达式

除了使用字段选择器，您也可以手动输入表达式：

1. 点击字段右侧的 **ƒ 表达式切换**按钮
2. 在输入框中手动输入：`${nodes.n1.output.body.email}`
3. 系统会自动解析并显示映射信息

### 5. 清除字段映射

如果要清除已配置的字段映射：

1. 点击字段映射信息右侧的 **×** 按钮
2. 字段会恢复为静态值输入模式

## 字段映射信息显示

当字段配置了映射后，会在输入框下方显示蓝色的信息条：

```
🔗 来自节点 HTTP Request 的字段 output.body.email
[×]
```

- **蓝色背景**：表示这是一个字段映射
- **节点名称**：显示数据来源的节点名称
- **字段路径**：显示具体的字段路径（以 `code` 样式显示）
- **× 按钮**：点击可清除映射

## 表达式语法

### 节点字段表达式

```
${nodes.<节点ID>.<字段路径>}
```

例如：
- `${nodes.n1.output.body.email}`
- `${nodes.n2.output.rows.0.id}`
- `${nodes.n3.output.status}`

### 工作流输入表达式

```
${workflow.<字段路径>}
```

例如：
- `${workflow.input.userId}`
- `${workflow.input.params.startDate}`

### 环境变量表达式

```
${env.<变量名>}
```

例如：
- `${env.API_KEY}`
- `${env.DATABASE_URL}`

## 支持字段映射的字段类型

以下类型的字段支持字段映射：

- ✅ **text** - 文本输入
- ✅ **textarea** - 多行文本
- ✅ **number** - 数字输入
- ✅ **select** - 下拉选择
- ✅ **code** - 代码编辑
- ✅ **json** - JSON 编辑

## 字段定义示例

在节点类型元数据中定义字段：

```typescript
{
  name: 'email',
  label: '收件人邮箱',
  type: 'text',
  required: true,
  supportsExpression: true,      // 支持表达式
  supportsFieldMapping: true,    // 显示字段选择器按钮
  placeholder: '输入邮箱地址'
}
```

## 注意事项

1. **字段路径区分大小写**：确保字段路径与输出 schema 完全匹配
2. **类型兼容性**：确保源字段类型与目标字段类型兼容
3. **节点依赖**：使用字段映射会创建节点间的依赖关系，系统会验证是否存在循环依赖
4. **节点删除**：如果删除了被引用的节点，相关的字段映射表达式需要手动更新
5. **只能选择叶子节点**：在字段树中只有叶子节点（标记为"可选"）才能被选择

## 完整示例

### 场景：用户注册流程

```
1. HTTP Request (获取用户信息)
   - URL: https://api.example.com/users/${workflow.input.userId}
   - Output: { body: { id, email, name } }

2. Database Query (保存到数据库)
   - SQL: INSERT INTO users (email, name) VALUES (?, ?)
   - Params[0]: ${nodes.n1.output.body.email}
   - Params[1]: ${nodes.n1.output.body.name}
   
3. Send Email (发送欢迎邮件)
   - To: ${nodes.n1.output.body.email}
   - Subject: Welcome, ${nodes.n1.output.body.name}!
   - Body: ...
```

## 调试技巧

1. **查看表达式原始值**：在表达式输入框中可以看到完整的表达式语法
2. **使用浏览器控制台**：表达式解析错误会在控制台输出
3. **检查输出 Schema**：确保上游节点定义了正确的输出 schema
4. **测试表达式**：在节点执行后，查看实际解析的值

## 高级功能（计划中）

- [ ] 支持表达式计算（如 `${nodes.n1.output.price * 0.8}`）
- [ ] 支持字符串模板（如 `Hello, ${nodes.n1.output.name}!`）
- [ ] 支持条件表达式（如 `${nodes.n1.output.age > 18 ? 'adult' : 'minor'}`）
- [ ] 字段映射可视化连线
- [ ] 批量字段映射
- [ ] 智能字段推荐

## 相关文件

- `components/NodeConfigPanel.vue` - 节点配置面板
- `components/FieldMappingSelector.vue` - 字段选择器
- `utils/expression.ts` - 表达式解析工具
- `utils/fieldTree.ts` - 字段树构建工具

