TraceStudio-dev/docs/web1.1_filemanager/UPDATE_v0.2.1.md

# TraceStudio v0.2.1 更新说明

## 🎉 多用户功能完善

### ✨ 新增功能

#### 1. 工作流标题管理
- **位置**: HeaderBar 顶部栏
- **功能**:
  - 显示当前工作流名称
  - 点击标题可编辑
  - 支持 Enter 确认、Escape 取消
  - 默认标题: "未命名工作流"

#### 2. 工作流保存
- **保存位置**: `cloud/users/{username}/workflows/`
- **文件格式**: `.utrace` (JSON)
- **保存内容**:
  - 工作流标题
  - 所有节点和连线
  - 全局设置
  - 保存时间戳
- **操作方式**: 点击标题旁边的 💾 按钮
- **提示**: 保存成功后显示完整路径

#### 3. 工作流加载
- **方式**: 在文件浏览器中双击 `.utrace` 文件
- **效果**: 自动加载所有节点、连线和设置
- **提示**: 加载成功后显示工作流名称

#### 4. 增强的用户切换器

##### 新增输入框创建用户
```
┌─────────────────────────┐
│ 切换用户空间             │
├─────────────────────────┤
│ 创建/切换用户           │
│ [输入用户名...] [➕]   │
├─────────────────────────┤
│ ✓ guest                 │
│   admin                 │
│   dev                   │
│   test                  │
└─────────────────────────┘
```

##### 操作方式
1. **下拉框**: 点击用户按钮展开菜单
2. **创建**: 在输入框输入用户名，按 Enter 或点击 ➕
3. **切换**: 点击列表中的用户名
4. **预设用户**: guest, admin, dev, test

##### 特性
- 输入即创建，无需确认
- 自动创建用户目录结构
- 切换后文件浏览器自动刷新

#### 5. 文件路径复制功能

##### 右键菜单新增选项
```
┌─────────────┐
│ 📥 下载     │
│ 📋 复制路径 │  ← 新增
│ ✏️ 重命名   │
│ 🗑️ 删除    │
└─────────────┘
```

##### 复制的路径格式
- **格式**: 相对于根目录的相对路径
- **示例**: `users/guest/data/sample.csv`
- **用途**: 填入节点参数（如 CSVLoader 的 file_path）

##### 使用流程
```
步骤1: 右键点击文件或文件夹
步骤2: 点击"📋 复制路径"
步骤3: 路径已复制到剪贴板
步骤4: 粘贴到节点参数输入框
```

---

## 📖 完整工作流

### 场景：数据分析工作流

#### 1. 创建用户空间
```
点击用户按钮 → 输入 "analyst" → Enter
系统自动创建: users/analyst/workflows/
```

#### 2. 上传数据文件
```
切换到"📁 文件"标签
导航到 users/analyst/data/
点击"📤 上传" → 选择 sales_data.csv
```

#### 3. 创建工作流
```
拖拽 sales_data.csv 到画布
自动生成 CSVLoader 节点
file_path 自动填充: users/analyst/data/sales_data.csv
```

#### 4. 编辑工作流标题
```
点击顶部"未命名工作流"
输入"销售数据分析"
按 Enter 确认
```

#### 5. 添加处理节点
```
从节点面板拖入 Transform 节点
连接到 CSVLoader 输出
配置转换参数
```

#### 6. 保存工作流
```
点击标题旁 💾 按钮
工作流保存到: users/analyst/workflows/销售数据分析.utrace
显示成功提示: ✅ 工作流已保存到: users/analyst/workflows/销售数据分析.utrace
```

#### 7. 下次加载
```
切换到"📁 文件"标签
导航到 users/analyst/workflows/
双击 销售数据分析.utrace
工作流自动加载
```

---

## 🔧 技术细节

### 工作流文件格式 (.utrace)
```json
{
  "title": "销售数据分析",
  "nodes": [
    {
      "id": "n_123_456",
      "type": "universal",
      "function": "Loader",
      "position": { "x": 100, "y": 100 },
      "data": {
        "label": "CSV 数据加载器",
        "file_path": "users/analyst/data/sales_data.csv",
        "delimiter": ",",
        "meta": { ... }
      }
    }
  ],
  "edges": [ ... ],
  "globalSettings": {
    "sampleRate": 0.1,
    "timeRange": { "start": 0, "end": 1000 }
  },
  "savedAt": "2026-01-07T12:34:56.789Z"
}
```

### 路径规范
所有路径均为**相对于 `cloud/` 目录的相对路径**：

| 类型 | 路径格式 | 示例 |
|------|---------|------|
| 共享资源 | `shared/...` | `shared/examples/sample.csv` |
| 用户数据 | `users/{username}/data/...` | `users/guest/data/test.csv` |
| 工作流 | `users/{username}/workflows/...` | `users/admin/workflows/分析.utrace` |
| 结果 | `users/{username}/results/...` | `users/dev/results/output.csv` |
| 临时文件 | `temp/...` | `temp/cache_123.tmp` |

### API 调用

#### 保存工作流
```typescript
const saveWorkflow = async () => {
  const blob = new Blob([JSON.stringify(workflowData)], { 
    type: 'application/json' 
  })
  const file = new File([blob], `${title}.utrace`, { 
    type: 'application/json' 
  })
  
  const formData = new FormData()
  formData.append('file', file)
  
  await fetch(`/api/files/upload?path=users/${user}/workflows&username=${user}`, {
    method: 'POST',
    body: formData
  })
}
```

#### 加载工作流
```typescript
const loadWorkflow = async (path: string) => {
  const response = await fetch(`/api/files/download?path=${encodeURIComponent(path)}`)
  const workflowData = await response.json()
  
  // 恢复状态
  setNodes(workflowData.nodes)
  setEdges(workflowData.edges)
  setWorkflowTitle(workflowData.title)
  setGlobalSettings(workflowData.globalSettings)
}
```

#### 复制路径
```typescript
const copyPath = async (path: string) => {
  await navigator.clipboard.writeText(path)
  // 路径格式: users/guest/data/file.csv
}
```

---

## 🎯 使用技巧

### 1. 工作流命名建议
- ✅ 使用描述性名称: `销售数据分析`
- ✅ 包含日期: `数据清洗_20260107`
- ✅ 区分版本: `模型训练_v1`, `模型训练_v2`
- ❌ 避免特殊字符: `/\:*?"<>|`

### 2. 文件组织建议
```
users/analyst/
├── workflows/
│   ├── 销售分析.utrace
│   ├── 库存统计.utrace
│   └── 月度报告.utrace
├── data/
│   ├── raw/          # 原始数据
│   ├── processed/    # 处理后的数据
│   └── backup/       # 备份
└── results/
    ├── 2026-01/      # 按月归档
    └── 2026-02/
```

### 3. 快捷键
- `Enter`: 确认编辑（标题、用户名）
- `Escape`: 取消编辑
- `双击`: 加载 .utrace 工作流
- `右键`: 打开文件菜单

### 4. 路径使用示例

#### CSVLoader 节点
```
file_path: users/guest/data/sales.csv
```

#### Transform 节点（如果需要输出）
```
output_path: users/guest/results/transformed.csv
```

#### 共享数据
```
file_path: shared/examples/sample.csv
```

---

## 🐛 故障排除

### 问题1: 工作流保存失败
**症状**: 点击 💾 按钮后显示"❌ 保存失败"

**原因**: 
- 后端服务未启动
- 用户目录不存在

**解决**:
```bash
# 检查后端是否运行
python -m uvicorn server.main:app --reload

# 检查 cloud 目录结构
ls cloud/users/{username}/workflows
```

### 问题2: 工作流加载失败
**症状**: 双击 .utrace 文件无响应

**原因**:
- 文件格式错误
- 文件损坏

**解决**:
- 用文本编辑器检查 .utrace 文件是否为有效 JSON
- 重新保存工作流

### 问题3: 路径复制不工作
**症状**: 右键点击"复制路径"无反应

**原因**:
- 浏览器不支持剪贴板 API
- 权限不足

**解决**:
- 使用现代浏览器（Chrome, Edge, Firefox）
- 允许剪贴板权限
- 降级方案会自动使用 execCommand

### 问题4: 用户切换后文件不见了
**症状**: 切换用户后文件列表为空

**原因**: 
- 新用户目录尚未创建
- 正常隔离机制

**解决**:
- 上传文件到新用户空间
- 或从共享目录访问公共资源

---

## 📊 版本对比

| 功能 | v0.2.0 | v0.2.1 |
|------|--------|--------|
| 用户切换 | ✅ 按钮菜单 | ✅ 下拉框 + 输入框 |
| 工作流标题 | ❌ | ✅ 可编辑 |
| 工作流保存 | ❌ | ✅ 保存到服务器 |
| 工作流加载 | ❌ | ✅ 双击加载 |
| 路径复制 | ❌ | ✅ 右键菜单 |
| 文件浏览器 | ✅ 基础功能 | ✅ 增强交互 |

---

## 🚀 下一步计划

- [ ] 工作流版本管理（自动备份）
- [ ] 工作流模板系统
- [ ] 用户间共享工作流
- [ ] 工作流执行历史
- [ ] 文件搜索功能
- [ ] 批量文件操作
- [ ] 工作流预览图生成

---

**版本**: v0.2.1  
**更新日期**: 2026-01-07  
**向后兼容**: 是  
**需要后端更新**: 否