# TraceStudio v0.2.0 更新日志

## 🎉 重大更新：多用户文件管理系统

### 新增功能

#### 📁 文件管理器
- **完整的文件系统**: 浏览、上传、下载、删除、重命名文件
- **目录导航**: 面包屑路径，支持快速返回父级
- **右键菜单**: 直观的文件操作
- **文件图标**: 根据文件类型显示不同图标

#### 👤 多用户支持
- **用户切换**: 点击 HeaderBar 右侧用户按钮即可切换
- **数据隔离**: 每个用户拥有独立的文件空间
- **自动创建**: 首次登录自动创建用户目录结构

#### 🎯 拖拽集成
- **CSV 拖拽**: 从文件浏览器拖拽 CSV 文件到画布
- **自动创建节点**: 自动生成 CSVLoader 节点
- **自动填充路径**: 节点参数自动填入文件路径

#### 🗂️ 目录结构
```
cloud/
├── shared/          # 共享资源（所有用户可见）
├── temp/            # 临时文件
└── users/           # 用户私有空间
    └── {username}/
        ├── workflows/   # 工作流
        ├── data/        # 数据文件
        └── results/     # 结果
```

### 技术实现

#### 后端 (Python/FastAPI)
- **新增模块**: `server/file_manager.py`
- **API 路由**: `/api/files/*` (list, upload, action, download)
- **路径安全**: 防止目录遍历攻击
- **自动初始化**: 启动时创建基础目录结构

#### 前端 (React/TypeScript)
- **新组件**: `FileExplorer.tsx` (文件浏览器)
- **Store 扩展**: 添加 `currentUser`, `currentPath` 状态
- **UI 集成**: 左侧面板新增"文件"标签
- **用户切换器**: HeaderBar 右侧新增用户按钮

### 修复的 Bug

#### ✅ 无限循环渲染问题
- **问题**: `useEffect` 中同步调用 `setState` 导致级联渲染
- **解决**: 
  - 移除 UniversalNode 中的空 useEffect
  - Workspace 使用 ref 跟踪更新来源
  - 避免所有同步 setState 调用

#### ✅ 空值安全问题
- **问题**: 访问 `preview.data.length` 未使用可选链
- **解决**: 所有预览数据访问添加 `?.` 和 `Array.isArray` 检查

### API 变更

#### 新增接口
```typescript
// 文件管理 API
listFiles(path, username)       // 列出目录
uploadFile(file, path, username) // 上传文件
fileAction(action)              // 文件操作
getDownloadUrl(path)            // 获取下载链接
getFileInfo(path)               // 获取文件信息
```

#### Store 新增
```typescript
// 用户状态
currentUser: string             // 当前用户名
setCurrentUser(user)            // 切换用户

// 文件浏览器
showFileExplorer: boolean       // 显示/隐藏
currentPath: string             // 当前路径
setCurrentPath(path)            // 设置路径
```

### 使用指南

#### 快速开始

1. **启动服务**
   ```bash
   # 后端
   python -m uvicorn server.main:app --reload
   
   # 前端
   cd web && npm run dev
   ```

2. **切换用户**
   - 点击 HeaderBar 右上角用户按钮
   - 选择预设用户或自定义用户名

3. **上传文件**
   - 点击左侧"📁 文件"标签
   - 点击"📤 上传"选择文件

4. **拖拽创建节点**
   - 拖动 CSV 文件到画布
   - 自动生成 CSVLoader 节点

### 性能优化

- **React 渲染优化**: 使用 ref 避免循环依赖
- **异步加载**: 文件列表异步获取，不阻塞 UI
- **懒加载**: 只在需要时加载文件列表

### 下一步计划

- [ ] 工作流文件（.utrace）的保存/加载
- [ ] 拖拽支持更多文件类型（JSON、图片）
- [ ] 文件搜索功能
- [ ] 文件夹批量操作
- [ ] 文件预览（CSV、图片）
- [ ] 用户权限管理（生产环境）

### 文档

- 📖 [文件管理器使用指南](./docs/FILE_MANAGER_GUIDE.md)
- 📖 [功能更新文档](./docs/FEATURE_UPDATE_v0.2.0.md)

---

**版本**: v0.2.0  
**发布日期**: 2026-01-07  
**重大变更**: 是  
**向后兼容**: 是