aiagent/数据转换节点功能说明.md

# 数据转换节点功能说明

## ✅ 已完成

已实现完整的数据转换节点功能，支持字段映射、数据过滤、数据计算等多种转换模式。

## 功能特性

### 1. 数据转换服务 (`backend/app/services/data_transformer.py`)

- 字段映射：支持简单和嵌套字段映射
- 数据过滤：支持多种过滤规则
- 数据计算：支持表达式计算
- 嵌套路径访问：支持 `user.name`、`items[0].price` 等

### 2. 支持的转换模式

#### 字段映射 (mapping)
将源字段映射到目标字段

#### 数据过滤 (filter)
根据条件过滤数据

#### 数据计算 (compute)
使用表达式计算新字段

#### 全部 (all)
同时应用所有转换模式

## 使用方法

### 1. 在工作流中添加转换节点

1. 打开工作流设计器
2. 从节点工具箱拖拽"转换"节点到画布
3. 配置转换规则

### 2. 配置转换节点

#### 字段映射模式

**配置示例**:
```json
{
  "mode": "mapping",
  "mapping": {
    "new_name": "old_name",
    "new_age": "old_age",
    "user_email": "email"
  }
}
```

**输入**:
```json
{
  "old_name": "张三",
  "old_age": 25,
  "email": "zhangsan@example.com"
}
```

**输出**:
```json
{
  "new_name": "张三",
  "new_age": 25,
  "user_email": "zhangsan@example.com"
}
```

#### 嵌套字段映射

**配置示例**:
```json
{
  "mode": "mapping",
  "mapping": {
    "user_name": "user.name",
    "user_age": "user.profile.age",
    "first_item_price": "items[0].price"
  }
}
```

**输入**:
```json
{
  "user": {
    "name": "李四",
    "profile": {
      "age": 30
    }
  },
  "items": [
    {"id": 1, "price": 100},
    {"id": 2, "price": 200}
  ]
}
```

**输出**:
```json
{
  "user_name": "李四",
  "user_age": 30,
  "first_item_price": 100
}
```

#### 数据过滤模式

**配置示例**:
```json
{
  "mode": "filter",
  "filter_rules": [
    {"field": "status", "operator": "==", "value": "active"},
    {"field": "count", "operator": ">", "value": 10}
  ]
}
```

**支持的运算符**:
- `==`: 等于
- `!=`: 不等于
- `>`: 大于
- `>=`: 大于等于
- `<`: 小于
- `<=`: 小于等于
- `in`: 包含
- `not in`: 不包含

#### 数据计算模式

**配置示例**:
```json
{
  "mode": "compute",
  "compute_rules": {
    "subtotal": "{price} * {quantity}",
    "total": "({price} * {quantity}) * (1 - {discount})"
  }
}
```

**输入**:
```json
{
  "price": 100,
  "quantity": 3,
  "discount": 0.1
}
```

**输出**:
```json
{
  "price": 100,
  "quantity": 3,
  "discount": 0.1,
  "subtotal": 300,
  "total": 270.0
}
```

## 前端配置

在节点配置面板中：

1. **选择转换模式**：字段映射、数据过滤、数据计算或全部
2. **配置映射规则**：JSON格式的字段映射
3. **配置过滤规则**：JSON数组格式的过滤规则
4. **配置计算规则**：JSON格式的计算表达式

## 测试结果

### 测试覆盖

- ✅ 字段映射 (通过)
- ✅ 嵌套字段映射 (通过)
- ✅ 数据过滤 (通过)
- ✅ 数据计算 (通过)
- ✅ 工作流中的转换节点 (通过)

### 测试用例

1. **简单字段映射**: `{"username": "name"}` ✅
2. **嵌套字段映射**: `{"user_name": "user.name"}` ✅
3. **数组索引访问**: `{"first_item_price": "items[0].price"}` ✅
4. **数据过滤**: 多条件过滤 ✅
5. **数据计算**: 复杂表达式计算 ✅

## 工作流示例

### 示例1: 数据格式转换

```
开始 → 转换节点(字段映射) → LLM节点 → 结束
```

转换节点配置：
```json
{
  "mode": "mapping",
  "mapping": {
    "input_text": "raw_input",
    "user_id": "id"
  }
}
```

### 示例2: 数据预处理

```
开始 → 转换节点(过滤) → 条件节点 → [True] → LLM节点 → 结束
```

转换节点配置：
```json
{
  "mode": "filter",
  "filter_rules": [
    {"field": "status", "operator": "==", "value": "active"}
  ]
}
```

### 示例3: 数据计算

```
开始 → 转换节点(计算) → 输出节点 → 结束
```

转换节点配置：
```json
{
  "mode": "compute",
  "compute_rules": {
    "total": "{price} * {quantity}",
    "discounted_price": "{total} * (1 - {discount})"
  }
}
```

## 注意事项

1. **JSON格式**: 配置规则必须是有效的JSON格式
2. **字段路径**: 嵌套路径使用点号分隔，数组使用方括号
3. **表达式安全**: 计算表达式只支持安全的数学运算
4. **错误处理**: 如果转换失败，节点会返回错误信息

## 后续计划

- [ ] 支持更多转换函数（字符串处理、日期格式化等）
- [ ] 支持数组操作（map、filter、reduce）
- [ ] 可视化配置界面
- [ ] 转换规则模板

---

**状态**: ✅ 已完成
**时间**: 2024年