docs/v1.0/server/rfcs/016-folder-service-implementation.md

RFC 016: 文件夹服务实现

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

---

概述

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

动机

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

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

设计

数据模型

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
• 验证目标位置权限

循环引用检测算法：

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 迁移
• 文件夹服务需求文档

---

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