# 新建项目弹窗 - 修复虚拟根目录 folderId 传递问题

**日期**: 2026-02-05  
**类型**: Bug 修复  
**影响范围**: 前端 - 项目创建

## 问题描述

在新建项目弹窗中，当用户选择"我的项目"或"协作项目"（虚拟根目录）时，前端会将虚拟 ID（如 `'virtual-mine'`）传递给后端，导致后端尝试将其转换为 UUID 时失败，返回"必须传递 UUID"的错误。

**根本原因**：
1. 虚拟根目录的 ID 是 `'virtual-mine'` 和 `'virtual-collab'`
2. 前端代码中使用的是旧的判断逻辑 `data.folderId === '1' || data.folderId === '2'`
3. 判断失败导致虚拟 ID 被传递给后端

## 解决方案

### 1. 修改表单验证 schema

将 `folderId` 字段改为可选：

```typescript
// 修改前
folderId: z.string().min(1, '请选择项目文件夹'),

// 修改后
folderId: z.string().optional(), // 可选字段，虚拟根目录不需要传递
```

### 2. 修复虚拟根目录判断逻辑

使用 `startsWith('virtual-')` 判断虚拟根目录：

```typescript
// 修改前
folderId: data.folderId === '1' || data.folderId === '2' ? undefined : data.folderId,

// 修改后
folderId: data.folderId?.startsWith('virtual-') ? undefined : data.folderId,
```

## 技术细节

1. **虚拟根目录定义**（`client/src/types/folder.ts`）：
   - "我的项目": `id: 'virtual-mine'`
   - "协作项目": `id: 'virtual-collab'`

2. **提交逻辑**：
   - 虚拟根目录 ID 以 `'virtual-'` 开头
   - 提交时将虚拟 ID 转换为 `undefined`
   - 后端接收 `undefined` 表示项目不属于任何文件夹

3. **后端处理**（`server/app/services/project_service.py`）：
   - `folder_id` 为 `None` 时，不进行文件夹权限检查
   - 项目直接创建在用户的根目录下

## 影响文件

- `client/src/components/features/project/CreateProjectModal.tsx`

## 测试建议

1. ✅ 选择"我的项目"创建项目，验证可以成功创建且不传递 `folderId`
2. ✅ 选择实际文件夹创建项目，验证 `folderId` 正确传递
3. ✅ 选择"协作项目"创建项目，验证可以成功创建且不传递 `folderId`
4. ✅ 验证后端不再返回"必须传递 UUID"错误