TraceStudio-dev/docs/studio1.3/FUNCTION_NESTING_OVERVIEW.md

# 🎯 函数节点嵌套 - 新功能说明

> **新增功能发布**: 支持工作流函数化和多层嵌套编辑

## 📢 功能亮点

### 什么是函数节点嵌套？

将任何工作流**保存为可复用的函数节点**，并支持**无限层嵌套编辑**。

### 核心特性

| 特性 | 说明 |
|------|------|
| 📦 **函数封装** | 将工作流转为可复用的函数节点 |
| 🔄 **即插即用** | 拖拽函数到其他工作流中使用 |
| 🔍 **双击编辑** | 双击进入函数内部进行编辑 |
| 📍 **面包屑导航** | 清晰定位当前所在层级 |
| 🌳 **多层嵌套** | 函数中可以包含其他函数 |
| 💾 **自动保存** | 所有修改自动保存到磁盘 |

---

## 🚀 5分钟快速开始

### 步骤 1: 创建函数

```
1. 在画布中设计任何工作流
2. 右键 → "保存为函数"
3. 输入函数名: my_function
4. 输入显示名: 我的函数
5. ✅ 完成！
```

### 步骤 2: 使用函数

```
1. 从 NodePalette 找到函数
2. 拖拽到新工作流
3. 连接输入/输出
4. ✅ 完成！
```

### 步骤 3: 编辑函数

```
1. 双击函数节点
2. 看到面包屑: 主工作流 / my_function (L1)
3. 编辑内部工作流
4. 点击面包屑或返回按钮退出
5. ✅ 完成！
```

---

## 📚 详细文档

### 快速开始 (15 分钟)
👉 [FUNCTION_NESTING_QUICKSTART.md](FUNCTION_NESTING_QUICKSTART.md)
- 5分钟快速上手
- 常见问题解答
- 最佳实践建议
- 命名规范说明

### 完整实现指南 (1 小时)
👉 [FUNCTION_NESTING_IMPLEMENTATION.md](FUNCTION_NESTING_IMPLEMENTATION.md)
- 完整的架构设计
- 后端实现详解
- 前端实现详解
- API 文档
- 代码示例
- 测试场景
- 调试指南

### 完成总结 (了解项目)
👉 [COMPLETION_SUMMARY.md](COMPLETION_SUMMARY.md)
- 交付物清单
- 代码统计
- 文档清单
- 技术亮点
- 下一步计划

---

## 🎓 使用场景

### 场景 1: 数据处理工厂

```
主工作流
├─ 加载数据节点
├─ extract_columns 函数 (可复用)
├─ transform_data 函数 (可复用)
└─ 保存结果节点
```

**优势**: 
- 每个函数独立维护
- 在不同工作流中复用
- 易于测试和调试

### 场景 2: 业务流程编排

```
主工作流 (采购流程)
├─ 创建订单 (函数)
├─ 验证库存 (函数)
│  ├─ 查询库存 (函数)
│  └─ 计算可用量 (函数)
├─ 生成采购单 (函数)
└─ 发送通知 (函数)
```

**优势**:
- 业务逻辑清晰
- 功能模块化
- 支持多层嵌套

### 场景 3: 数据分析管道

```
分析工作流
├─ 数据加载 (函数)
├─ 数据清洗 (函数)
│  ├─ 去重 (内部函数)
│  ├─ 填充缺失 (内部函数)
│  └─ 异常检测 (内部函数)
├─ 特征工程 (函数)
└─ 模型预测 (函数)
```

**优势**:
- 流程透明
- 易于复用
- 支持版本管理

---

## 🔧 关键技术

### 后端
- **Python**: FastAPI 框架
- **设计模式**: 工厂模式（动态创建节点类）
- **参数传递**: Context 特殊键 (`__function_input_*`, `__function_output_*`)

### 前端
- **状态管理**: Zustand (栈式结构)
- **组件**: React Hooks
- **交互**: 双击进入、右键保存、面包屑导航

### 存储
- **格式**: JSON
- **位置**: `cloud/custom_nodes/functions/`
- **持久化**: 磁盘 + localStorage

---

## 📊 API 接口

### 保存函数
```
POST /api/functions/save
Content-Type: application/json

{
  "function_name": "extract_data",
  "display_name": "提取数据",
  "description": "从源数据中提取列",
  "nodes": [...],
  "edges": [...],
  "inputs": [],
  "outputs": []
}
```

### 获取函数列表
```
GET /api/functions/list

响应:
{
  "success": true,
  "data": [
    {
      "function_name": "extract_data",
      "display_name": "提取数据",
      ...
    }
  ]
}
```

### 获取函数详情
```
GET /api/functions/extract_data

响应:
{
  "success": true,
  "data": {
    "function_name": "extract_data",
    "nodes": [...],
    "edges": [...],
    ...
  }
}
```

完整 API 文档见: [FUNCTION_NESTING_IMPLEMENTATION.md](FUNCTION_NESTING_IMPLEMENTATION.md#-api-文档)

---

## ✨ 新增内容

### 后端新增
- `server/app/core/function_nodes.py` (281 行)
  - InputNode, OutputNode, FunctionNode, 工厂函数
  
- `server/app/core/node_loader.py` 修改 (67 行新增)
  - 函数节点加载器
  
- `server/app/api/endpoints_graph.py` 修改 (120 行新增)
  - 3 个 API 端点
  
- `cloud/custom_nodes/functions/` 目录
  - 函数存储目录

### 前端新增
- `web/src/stores/useStore.ts` 修改 (130 行新增)
  - 函数嵌套状态管理
  
- `web/src/components/Workspace.tsx` 修改 (95 行新增)
  - 双击进入、右键保存功能
  
- `web/src/components/BreadcrumbNav.tsx` (148 行)
  - 面包屑导航组件

### 文档新增
- `FUNCTION_NESTING_QUICKSTART.md` (700+ 行)
- `FUNCTION_NESTING_IMPLEMENTATION.md` (2,300+ 行)
- `COMPLETION_SUMMARY.md` (800+ 行)

---

## ❓ 常见问题

### Q: 如何创建第一个函数？
A: 见 [快速开始](FUNCTION_NESTING_QUICKSTART.md#第1步-创建一个函数)

### Q: 如何进入函数编辑？
A: 双击函数节点即可进入。见 [双击进入](FUNCTION_NESTING_QUICKSTART.md#第3步-进入函数编辑)

### Q: 支持多少层嵌套？
A: 理论无限制，建议不超过 5 层。

### Q: 函数修改后如何保存？
A: 自动保存到 localStorage，可右键"保存工作流"永久保存。

### Q: 如何分享函数？
A: 导出 `functions/*.json` 文件，发给其他用户。他们放入同目录即可使用。

更多问题见: [常见问题](FUNCTION_NESTING_QUICKSTART.md#-常见问题)

---

## 🎯 下一步

### 立即体验
1. 阅读 [快速开始](FUNCTION_NESTING_QUICKSTART.md)
2. 创建第一个函数
3. 尝试多层嵌套

### 深入学习
1. 阅读 [完整实现指南](FUNCTION_NESTING_IMPLEMENTATION.md)
2. 查看代码实现
3. 理解架构设计

### 贡献改进
1. 提出功能建议
2. 报告 Bug
3. 贡献代码

---

## 📞 获取帮助

| 问题类型 | 查看文档 |
|---------|--------|
| 快速上手 | [快速开始](FUNCTION_NESTING_QUICKSTART.md) |
| 常见问题 | [常见问题](FUNCTION_NESTING_QUICKSTART.md#-常见问题) |
| 完整文档 | [实现指南](FUNCTION_NESTING_IMPLEMENTATION.md) |
| API 接口 | [API 文档](FUNCTION_NESTING_IMPLEMENTATION.md#-api-文档) |
| 最佳实践 | [最佳实践](FUNCTION_NESTING_QUICKSTART.md#💡-最佳实践) |
| 项目总结 | [完成总结](COMPLETION_SUMMARY.md) |

---

## 🎉 功能发布信息

- **版本**: v1.0.0
- **发布日期**: 2024-01-15
- **状态**: ✅ 生产就绪
- **代码行数**: ~843 行
- **文档行数**: ~3,800 行
- **API 端点**: 3 个
- **测试场景**: 8 个

---

**开始体验新功能吧！** 🚀

👉 [立即开始](FUNCTION_NESTING_QUICKSTART.md)