# 面包屑导航功能实现

**日期**: 2026-01-21  
**类型**: Feature  
**影响范围**: ProjectsPage, ProjectHeader

## 变更概述

实现了项目页面的文件夹面包屑导航功能，用户可以通过面包屑快速导航到父级文件夹。

## 技术实现

### 1. API 集成

- 使用 `useFolderPath` Hook 获取文件夹路径数据
- API 端点：`GET /folders/{folder_id}/path`
- 返回格式：`{ path: [{ id, name }, ...] }`

### 2. 面包屑构建逻辑

```typescript
const breadcrumbs = useMemo(() => {
  const crumbs: Array<{ id: string; name: string }> = [];

  // 1. 添加虚拟根节点（我的项目/协作项目）
  const virtualRoot = activeRootId === VIRTUAL_ROOTS.mine.id 
    ? VIRTUAL_ROOTS.mine 
    : VIRTUAL_ROOTS.collab;
  crumbs.push({
    id: virtualRoot.id,
    name: virtualRoot.name,
  });

  // 2. 如果当前不是虚拟根节点，添加真实文件夹路径
  if (!isVirtualRoot(currentFolderId) && folderPath) {
    folderPath.forEach((folder) => {
      crumbs.push({
        id: folder.id,
        name: folder.name,
      });
    });
  }

  return crumbs;
}, [activeRootId, currentFolderId, folderPath]);
```

### 3. UI 展示

- 首页图标显示在第一个面包屑项
- 使用 `ChevronRight` 图标作为分隔符
- 当前文件夹高亮显示（粗体）
- 点击面包屑项可导航到对应文件夹

## 文件变更

### 修改的文件

1. **client/src/pages/ProjectsPage.tsx**
   - 导入 `useFolderPath` Hook
   - 实现面包屑数据构建逻辑
   - 清理未使用的变量和导入

2. **client/src/stores/uiStore.ts**
   - 扩展 `createProjectInitialValues` 类型，添加 `folderId` 字段
   - 支持在创建项目时预设所属文件夹

## 用户体验改进

- ✅ 清晰的层级导航路径
- ✅ 快速返回上级文件夹
- ✅ 视觉上突出当前位置
- ✅ 支持虚拟根节点（我的项目/协作项目）

## 后续优化

- [ ] 添加面包屑项的 hover 效果
- [ ] 支持面包屑项的右键菜单
- [ ] 长路径时的省略显示
- [ ] 面包屑项的拖拽移动功能

## 相关文档

- [RFC 122: 文件夹 API 集成](../rfcs/122-folder-api-integration.md)
- [RFC 124: 文件夹分类前端实现](../rfcs/124-folder-category-frontend.md)