# TraceStudio 文件管理系统使用指南

## 📦 功能概览

TraceStudio 现已集成完整的多用户文件管理系统，支持：

- ✅ 多用户隔离的文件空间
- ✅ 文件上传、下载、删除、重命名
- ✅ 拖拽 CSV 文件到画布自动创建节点
- ✅ 共享资源和私有数据分离
- ✅ 轻量级用户切换（无需复杂鉴权）

---

## 🗂️ 目录结构

服务启动时会在 `cloud/` 目录下自动创建以下结构：

```
cloud/
├── shared/          # 共享资源区
│   └── examples/    # 示例数据
│       └── sample.csv
├── temp/            # 临时缓存区
└── users/           # 用户私有空间
    ├── guest/
    │   ├── workflows/   # 工作流文件
    │   ├── data/        # 数据文件
    │   └── results/     # 结果输出
    ├── admin/
    └── dev/
```

---

## 👤 用户切换

### 在 HeaderBar 右侧点击用户按钮

1. **快速切换**: 点击预设用户（guest、admin、dev）
2. **自定义用户**: 点击"+ 自定义用户名"输入任意用户名
3. **自动创建**: 切换到新用户时，系统自动创建对应目录

### 用户数据隔离

- 每个用户拥有独立的 `/users/{username}/` 目录
- 切换用户后，文件浏览器自动定位到该用户空间
- 工作流保存时默认存储在 `/users/{username}/workflows/`

---

## 📁 文件管理器

### 位置
左侧面板有两个标签：
- **📦 节点**: 原有的节点面板
- **📁 文件**: 新增的文件浏览器

### 基本操作

#### 1. 上传文件
```
点击"📤 上传"按钮 → 选择 .csv/.json/.utrace 文件
```

#### 2. 新建文件夹
```
点击"📁 新建"按钮 → 输入文件夹名称
```

#### 3. 右键菜单
- 文件: 下载、重命名、删除
- 文件夹: 重命名、删除

#### 4. 面包屑导航
点击路径中的任意层级快速返回

---

## 🎯 拖拽集成

### 将 CSV 文件拖入画布

1. 在文件浏览器中找到 `.csv` 文件
2. 按住鼠标左键拖动文件
3. 拖到画布中松开鼠标
4. **自动创建**: 系统自动生成 `CSVLoader` 节点
5. **自动填充**: `file_path` 参数自动填入文件的完整路径

### 示例流程

```
步骤1: 上传 data.csv 到 /users/guest/data/
步骤2: 拖拽 data.csv 到画布
步骤3: 自动生成节点:
   ┌─────────────────────┐
   │  CSV 数据加载器      │
   │  file_path:         │
   │  users/guest/data/  │
   │         data.csv    │
   └─────────────────────┘
步骤4: 点击"运行预览"查看数据
```

---

## 🔌 API 接口

### 后端路由（FastAPI）

```python
GET  /api/files/list?path=...&username=...   # 列出目录
POST /api/files/upload                       # 上传文件
POST /api/files/action                       # 文件操作
GET  /api/files/download?path=...            # 下载文件
GET  /api/files/info?path=...                # 获取文件信息
```

### 文件操作

```typescript
// 删除文件
await fileAction({
  action: 'delete',
  path: 'users/guest/data/old.csv'
})

// 重命名
await fileAction({
  action: 'rename',
  path: 'users/guest/data/old.csv',
  new_name: 'new.csv'
})

// 创建文件夹
await fileAction({
  action: 'mkdir',
  path: 'users/guest/data',
  new_name: 'subfolder'
})
```

---

## 🛠️ 开发指南

### 前端集成

```typescript
// 监听当前用户
const currentUser = useStore((s) => s.currentUser)

// 切换用户
const setCurrentUser = useStore((s) => s.setCurrentUser)
setCurrentUser('newuser')

// 获取当前路径
const currentPath = useStore((s) => s.currentPath)
```

### 后端扩展

```python
# 在 server/file_manager.py 中
# 添加新的文件操作

@router.post("/custom-action")
async def custom_file_action(data: dict):
    # 自定义文件处理逻辑
    pass
```

---

## 🚀 快速开始

### 1. 启动服务

```powershell
# 后端
cd server
python -m uvicorn main:app --reload

# 前端
cd web
npm run dev
```

### 2. 试用流程

1. 打开浏览器访问 `http://localhost:5173`
2. 点击右上角用户按钮，切换到 `guest`
3. 点击左侧"📁 文件"标签
4. 导航到 `shared/examples/`
5. 拖拽 `sample.csv` 到画布
6. 点击节点的"运行预览"按钮
7. 查看数据预览结果

---

## 📝 注意事项

### 安全性
- 当前实现为**轻量级用户切换**，无密码验证
- 适用于单机或受信任环境
- 生产环境建议添加 JWT/OAuth 鉴权

### 路径安全
- 所有路径经过 `sanitize_path()` 清理
- 防止目录遍历攻击（../ 等）
- 仅允许访问 `cloud/` 目录内的文件

### 文件大小
- 默认无上传限制
- 建议在生产环境配置 `client_max_body_size`

---

## 🎨 UI 提示

### 文件图标

- 📁 文件夹
- 📊 CSV 文件
- 📋 JSON 文件
- 🔍 UTrace 文件
- 🖼️ 图片文件
- 📄 其他文件

### 状态指示

- 加载中：显示"加载中..."
- 空文件夹：显示"此文件夹为空"
- 错误：显示红色错误消息

---

## 🐛 常见问题

### Q1: 拖拽没有反应？
A: 确保文件是 `.csv` 格式，其他格式目前不支持直接拖拽

### Q2: 文件上传失败？
A: 检查后端是否正常运行，查看浏览器控制台错误

### Q3: 切换用户后文件不见了？
A: 正常现象，不同用户有独立的文件空间

### Q4: 文件路径显示错误？
A: 路径使用 `/` 分隔，相对于 `cloud/` 目录

---

## 📞 支持

遇到问题或有建议？
- 查看浏览器控制台日志
- 查看后端终端输出
- 检查 `cloud/` 目录权限

---

**版本**: v0.2.0  
**更新日期**: 2026-01-07  
**作者**: TraceStudio Team