# LocalFlow UI 使用指南

## 界面布局

```
┌──────────────────────────────────────────────────────────┐
│  LocalFlow                                      [_][□][×] │
├──┬─────────────────────────────────────────────────────┬──┤
│  │                                                     │  │
│ 🔧│              工作流画布                              │📋│
│  │           (右键添加节点)                             │  │
│ ⚙️│                                                     │  │
│  │                                                     │  │
├──┴─────────────────────────────────────────────────────┴──┤
│  状态栏                                                   │
└──────────────────────────────────────────────────────────┘
```

## 主要组件

### 1. 左侧工具栏

#### 🔧 节点浏览器按钮（最上方）
- **功能**: 打开/关闭节点浏览器面板
- **快捷方式**: 点击工具栏顶部的节点图标
- **面板内容**:
  - 📝 变量赋值 - 创建变量并赋值
  - 🔢 变量计算 - 使用表达式计算变量
  - 🔌 SQLite连接 - 连接SQLite数据库
  - 📄 SQL语句 - 构建SQL查询语句
  - ▶️ SQLite执行 - 执行SQL语句

**使用方法**:
1. 点击节点浏览器按钮
2. 在列表中浏览节点类型
3. 双击节点将其添加到画布中心
4. 或使用搜索框快速找到需要的节点

#### ⚙️ 设置按钮（最下方）
- **功能**: 打开设置对话框
- **配置项**:
  - UV包管理工具检测
  - UV安装状态和路径
  - 镜像源配置
  - 一键安装UV

### 2. 右侧工具栏

#### 📋 节点属性按钮
- **功能**: 打开/关闭节点属性面板
- **面板内容**:
  - 节点信息（ID、类型）
  - 节点配置表单
  - 应用按钮

**使用方法**:
1. 在画布上选中一个节点
2. 属性面板自动显示该节点的配置
3. 编辑配置项
4. 点击"应用"保存更改

### 3. 中央工作区

#### 工作流标签页
- **Overview**: 欢迎页面，添加工作流按钮
- **工作流 1, 2, 3...**: 各个工作流的画布

#### 工作流工具栏
```
┌─────────────────────────────────────────────────┐
│ 工作流 1              [▶ 执行工作流] [💾 保存] │
└─────────────────────────────────────────────────┘
```

- **工作流名称**: 显示当前工作流的名称
- **▶ 执行工作流**: 执行当前工作流中的所有节点
- **💾 保存**: 保存工作流到JSON文件

#### 工作流画布
- **背景**: 深色网格背景
- **交互**:
  - 鼠标滚轮：缩放画布
  - 左键拖拽：移动画布（无节点选中时）
  - 右键点击：打开节点菜单

## 核心操作

### 1. 添加节点

#### 方法A: 右键菜单（推荐）
1. 在画布空白处右键点击
2. 从弹出菜单中选择节点类型
3. 节点会出现在点击位置

#### 方法B: 节点浏览器
1. 点击左侧节点浏览器按钮
2. 双击要添加的节点类型
3. 节点会出现在画布中心

### 2. 配置节点

#### 步骤
1. 点击选中节点（节点会显示蓝色边框）
2. 右侧属性面板自动打开并显示配置
3. 填写/修改配置项
4. 点击"应用"按钮

#### 各节点配置说明

##### 📝 变量赋值节点
```
变量名: x
值: 100
类型: int
```
- **变量名**: 要创建的变量名称
- **值**: 变量的值
- **类型**: 数据类型（str, int, float, bool, json）

##### 🔢 变量计算节点
```
表达式: x + y * 2
输出变量: result
```
- **表达式**: Python计算表达式
- **输出变量**: 计算结果保存到的变量名

##### 🔌 SQLite连接节点
```
数据库路径: ./data.db
连接名称: db_conn
```
- **数据库路径**: SQLite数据库文件路径
- **连接名称**: 连接的变量名

##### 📄 SQL语句节点
```
SQL语句: SELECT * FROM users WHERE id = {user_id}
输出变量: sql
```
- **SQL语句**: SQL查询语句（支持变量插值）
- **输出变量**: SQL语句保存到的变量名

##### ▶️ SQLite执行节点
```
连接名称: db_conn
SQL变量: sql
输出变量: query_result
```
- **连接名称**: 使用的数据库连接
- **SQL变量**: 包含SQL语句的变量名
- **输出变量**: 查询结果保存到的变量名

### 3. 连接节点

#### 步骤
1. 找到起始节点的**输出端口**（右侧的圆点）
2. 点击并按住输出端口
3. 拖拽鼠标到目标节点的**输入端口**（左侧的圆点）
4. 释放鼠标完成连接

#### 连接规则
- ✅ 只能从输出端口（右侧）连接到输入端口（左侧）
- ✅ 一个节点可以有多个输入和输出
- ❌ 不能连接到同一个节点
- ❌ 不能从输入端口开始连接

#### 连接线
- **颜色**: 绿色（🟢）
- **样式**: 贝塞尔平滑曲线
- **表示**: 数据流向

### 4. 移动节点

#### 步骤
1. 点击节点（非端口区域）
2. 拖拽到目标位置
3. 释放鼠标

### 5. 删除节点

#### 步骤
1. 右键点击要删除的节点
2. 选择"删除节点"
3. 节点及其连接会被移除

### 6. 执行工作流

#### 步骤
1. 配置好所有节点
2. 连接好节点之间的关系
3. 点击工具栏的"▶ 执行工作流"按钮
4. 等待执行完成
5. 查看结果弹窗

#### 执行过程
```
准备环境 → 生成脚本 → 拓扑排序 → 按序执行 → 显示结果
```

#### 执行结果
- **成功**: 弹窗显示所有变量的值
- **失败**: 弹窗显示错误信息

### 7. 保存工作流

#### 步骤
1. 点击工具栏的"💾 保存"按钮
2. 查看保存路径确认弹窗
3. 工作流保存为JSON文件

#### 保存位置
```
workflows/
└── 工作流名称/
    ├── .venv/           # 虚拟环境
    ├── scripts/         # 生成的脚本
    └── workflow.json    # 工作流定义
```

## 工作流示例

### 示例1: 简单计算

#### 节点配置
```
[节点1: 变量赋值]
变量名: x
值: 10
类型: int

[节点2: 变量赋值]
变量名: y
值: 20
类型: int

[节点3: 变量计算]
表达式: x + y * 2
输出变量: result
```

#### 连接关系
```
节点1 ──→ 节点3
节点2 ──→ 节点3
```

#### 执行结果
```
x = 10
y = 20
result = 50
```

### 示例2: 数据库查询

#### 节点配置
```
[节点1: SQLite连接]
数据库路径: ./users.db
连接名称: db

[节点2: 变量赋值]
变量名: user_id
值: 1
类型: int

[节点3: SQL语句]
SQL语句: SELECT * FROM users WHERE id = {user_id}
输出变量: query

[节点4: SQLite执行]
连接名称: db
SQL变量: query
输出变量: result
```

#### 连接关系
```
节点1 ──→ 节点4
节点2 ──→ 节点3
节点3 ──→ 节点4
```

## 快捷操作

### 画布操作
- **缩放**: 鼠标滚轮
- **平移**: 左键拖拽空白区域
- **添加节点**: 右键点击空白区域

### 节点操作
- **选中**: 左键点击节点
- **移动**: 拖拽节点
- **配置**: 双击节点（或选中后在右侧编辑）
- **删除**: 右键 → 删除节点

### 连接操作
- **创建**: 从输出端口拖拽到输入端口
- **删除**: （暂未实现，需删除相关节点）

## 状态指示

### 节点状态
- **正常**: 灰色边框
- **选中**: 蓝色边框 🔵
- **执行中**: 绿色边框 🟢
- **错误**: 红色边框 🔴

### 节点颜色
- **变量赋值**: 🟢 绿色头部
- **变量计算**: 🔵 蓝色头部
- **SQLite连接**: 🟠 橙色头部
- **SQL语句**: 🔷 青色头部
- **SQLite执行**: 🟣 紫色头部

## 常见问题

### Q1: 节点浏览器不显示？
**A**: 点击左侧工具栏顶部的节点图标按钮

### Q2: 节点属性面板是空的？
**A**: 先在画布上选中一个节点

### Q3: 无法创建连接？
**A**: 
- 确保从输出端口（右侧）开始
- 确保拖拽到输入端口（左侧）
- 不能连接到同一个节点

### Q4: 执行失败？
**A**: 
- 检查节点配置是否正确
- 检查变量名是否一致
- 查看错误消息了解具体原因

### Q5: 保存后在哪里找到文件？
**A**: `workflows/工作流名称/workflow.json`

## 最佳实践

### 1. 命名规范
- 变量名使用小写和下划线：`user_id`, `result_data`
- 连接名称简洁明了：`db_conn`, `api_conn`

### 2. 节点布局
- 从左到右排列节点（数据流向）
- 相关节点放在一起
- 留出足够空间避免混乱

### 3. 调试技巧
- 先测试简单的工作流
- 逐步添加节点并测试
- 查看生成的脚本文件

### 4. 保存习惯
- 完成一个功能模块后及时保存
- 执行前保存当前状态
- 定期备份重要工作流

---

**开始使用LocalFlow构建你的工作流！** 🚀