# 变更日志：文件夹分类系统前端实现

**日期**: 2026-01-21  
**版本**: v1.0.0  
**类型**: 功能实现

## 概述

完成文件夹分类系统的前端实现，使用虚拟根节点方式展示"我的项目"和"协作项目"，对接后端 `folder_category` 字段。

## 新增功能

### 1. 虚拟根节点系统
- 定义虚拟根 ID：`virtual-mine`（我的项目）、`virtual-collab`（协作项目）
- 提供工具函数：`isVirtualRoot()`, `getVirtualRootCategory()`, `getVirtualRootById()`
- 虚拟根不对应数据库记录，仅用于前端导航

### 2. 文件夹分类类型
- 新增 `FolderCategory` 常量对象（兼容 `erasableSyntaxOnly` 配置）
- 值：`MY_PROJECTS = 1`, `COLLABORATIVE_PROJECTS = 2`
- 对应后端 SMALLINT 字段

### 3. API 层增强
- `folderApi.getAll()` 支持 `folderCategory` 查询参数
- 创建文件夹时自动处理虚拟根 ID 转换

### 4. 创建文件夹逻辑
- 在虚拟根下创建：`parentFolderId = undefined`, 指定 `folderCategory`
- 在真实文件夹下创建：指定 `parentFolderId`，自动继承分类

## 文件变更

### 新增
- `client/src/types/folder.ts` - 文件夹类型定义

### 修改
- `client/src/services/api/folders.ts` - API 层更新
- `client/src/hooks/api/useFolders.ts` - Hooks 更新
- `client/src/pages/ProjectsPage.tsx` - 使用虚拟根 ID
- `client/src/components/features/project/CreateFolderModal.tsx` - 创建逻辑更新
- `client/src/types/project-view.ts` - 废弃旧常量

### 文档
- `docs/client/rfcs/124-folder-category-frontend.md` - 实现 RFC
- `docs/client/changelogs/2026-01-21-folder-category.md` - 本变更日志

## Breaking Changes

无。旧的 `ROOT_ID_MINE` 和 `ROOT_ID_COLLAB` 已标记为废弃但未删除，保持向后兼容。

## 迁移指南

如果其他组件使用了旧的根 ID 常量：

```typescript
// 旧代码
import { ROOT_ID_MINE, ROOT_ID_COLLAB } from '@/types/project-view';

// 新代码
import { VIRTUAL_ROOTS } from '@/types/folder';
const mineId = VIRTUAL_ROOTS.mine.id;
const collabId = VIRTUAL_ROOTS.collab.id;
```

## 测试建议

1. 测试在"我的项目"下创建文件夹
2. 测试在"协作项目"下创建文件夹
3. 测试在子文件夹下创建文件夹
4. 验证面包屑导航
5. 验证搜索功能限定在当前分类

## 相关文档

- [RFC 124: 文件夹分类系统前端实现](../rfcs/124-folder-category-frontend.md)
- [后端 RFC 123: 文件夹分类枚举字段](../../server/rfcs/123-folder-category-enum.md)
- [后端部署指南](../../../server/DEPLOY_FOLDER_CATEGORY.md)