# RFC 016: 文件夹服务实现

> **状态**: 已实现  
> **创建日期**: 2025-01-18  
> **作者**: 架构团队

---

## 概述

实现文件夹管理服务，支持文件夹的 CRUD 操作、树形结构管理、移动、权限控制等功能。

## 动机

用户需要通过文件夹组织项目，支持：

1. 多层级文件夹结构
2. 文件夹移动（防止循环引用）
3. 文件夹删除（级联删除）
4. 权限管理（所有者/编辑者/查看者）
5. 统计信息（子文件夹数、项目数）

## 设计

### 数据模型

```python
class Folder(SQLModel, table=True):
    id: str = Field(default_factory=generate_uuid, primary_key=True)
    name: str
    description: Optional[str]
    parent_folder_id: Optional[str]
    owner_id: str
    path: str  # 路径缓存，如 "/folder1/folder2/"
    level: int  # 层级深度
    sort_order: int
    color: Optional[str]
    icon: Optional[str]
    is_shared: bool
    created_at: datetime
    updated_at: datetime
    deleted_at: Optional[datetime]
```

### 核心功能

#### 1. 文件夹创建

- 自动计算 `path` 和 `level`
- 检查同级名称唯一性
- 验证父文件夹权限

#### 2. 文件夹移动

- 检查循环引用（不能移动到自己的子文件夹）
- 递归更新所有子文件夹的 `path` 和 `level`
- 验证目标位置权限

**循环引用检测算法**：

```python
async def would_create_cycle(folder_id: str, target_parent_id: str) -> bool:
    """向上遍历目标文件夹的所有父级，检查是否包含当前文件夹"""
    current_id = target_parent_id
    visited = set()

    while current_id:
        if current_id in visited or current_id == folder_id:
            return True
        visited.add(current_id)
        folder = await get_by_id(current_id)
        current_id = folder.parent_folder_id if folder else None

    return False
```

#### 3. 文件夹删除

- 软删除（标记 `deleted_at`）
- 支持级联删除子文件夹和项目
- 仅所有者可删除

#### 4. 树形结构查询

- 递归查询子文件夹
- 支持限制最大深度
- 返回统计信息（子文件夹数、项目数）

### API 设计

```
GET    /api/v1/folders              # 获取文件夹列表（分页）
GET    /api/v1/folders/tree         # 获取树形结构
GET    /api/v1/folders/{id}         # 获取文件夹详情
POST   /api/v1/folders              # 创建文件夹
PUT    /api/v1/folders/{id}         # 更新文件夹
DELETE /api/v1/folders/{id}         # 删除文件夹
POST   /api/v1/folders/{id}/move    # 移动文件夹
GET    /api/v1/folders/{id}/path    # 获取文件夹路径（面包屑）
```

### 权限模型

- **Owner（所有者）**：完全控制（CRUD、移动、删除、共享）
- **Editor（编辑者）**：可编辑、移动（未来实现）
- **Viewer（查看者）**：只读（未来实现）

当前版本：仅所有者可访问自己的文件夹。

## 实现细节

### 文件结构

```
server/app/
├── models/folder.py              # 数据模型
├── schemas/folder.py             # Pydantic Schema
├── repositories/folder_repository.py  # 数据访问层
├── services/folder_service.py    # 业务逻辑层
└── api/v1/folders.py             # API 路由
```

### 关键技术点

1. **路径缓存**：`path` 字段存储完整路径，避免递归查询
2. **层级字段**：`level` 字段快速判断深度
3. **软删除**：保留数据，支持恢复
4. **异步操作**：所有数据库操作使用 async/await
5. **事务管理**：移动操作使用事务保证一致性

### 性能优化

1. **索引**：
   - `parent_folder_id`（查询子文件夹）
   - `owner_id`（查询用户文件夹）
   - `path`（路径查询）
   - `name`（名称搜索）

2. **查询优化**：
   - 使用 `path` 字段避免递归查询
   - 分页查询避免大量数据加载
   - 统计信息按需计算

## 测试计划

### 单元测试

- [ ] 文件夹创建（正常、重名、无权限）
- [ ] 文件夹移动（正常、循环引用、无权限）
- [ ] 文件夹删除（正常、非空、级联）
- [ ] 循环引用检测算法

### 集成测试

- [ ] API 端到端测试
- [ ] 并发操作测试
- [ ] 性能测试（1000+ 文件夹）

## 未来扩展

1. **共享功能**：支持文件夹共享给其他用户
2. **权限细化**：实现 Editor/Viewer 角色
3. **文件夹模板**：预设文件夹结构
4. **批量操作**：批量移动、删除
5. **回收站**：软删除后的恢复功能
6. **全文搜索**：基于 Elasticsearch 的文件夹搜索

## 依赖

- SQLModel 0.0.14
- PostgreSQL 17+ (原生 UUID v7 支持)
- FastAPI 0.109.0

## 相关文档

- [ADR 001: UUID v7 迁移](../../architecture/adrs/001-uuid-v7-migration.md)
- [文件夹服务需求文档](../../requirements/backend/04-services/project/folder-service.md)

---

**实施状态**：✅ 已完成核心功能