# RFC 120: 文件夹功能增强

> **状态**: 已实现  
> **创建时间**: 2026-01-20  
> **作者**: AI Assistant  
> **类型**: 功能增强

---

## 概述

本 RFC 描述了文件夹管理功能的增强实现，包括权限管理、克隆功能、统计信息等核心特性。

## 动机

现有的文件夹功能仅支持基础的 CRUD 操作，缺少以下关键特性：

1. **权限管理**：无法与其他用户共享文件夹，无法设置不同的访问权限
2. **克隆功能**：无法快速复制文件夹结构和内容
3. **统计信息**：缺少文件夹使用情况的统计数据
4. **封面图片**：无法为文件夹设置封面图片

这些限制影响了团队协作和文件夹管理的效率。

## 设计方案

### 1. 数据库设计

#### 1.1 folders 表增强

```sql
ALTER TABLE folders ADD COLUMN cover_image_id UUID REFERENCES attachments(attachment_id);
```

新增字段：
- `cover_image_id`: 封面图片 ID（可选）

#### 1.2 folder_members 表

```sql
CREATE TABLE folder_members (
    id UUID PRIMARY KEY,
    folder_id UUID NOT NULL REFERENCES folders(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
    role member_role NOT NULL DEFAULT 'viewer',
    inherited BOOLEAN NOT NULL DEFAULT false,
    invited_by UUID REFERENCES users(user_id),
    joined_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    CONSTRAINT folder_members_unique UNIQUE (folder_id, user_id)
);
```

字段说明：
- `role`: 成员角色（owner/editor/viewer）
- `inherited`: 是否从父文件夹继承权限
- `invited_by`: 邀请人 ID

#### 1.3 PostgreSQL 函数

创建以下函数支持权限管理：

1. **check_folder_permission()**: 检查用户权限（支持继承）
2. **check_folder_cycle()**: 检测循环引用
3. **get_user_accessible_folders()**: 获取用户可访问的文件夹
4. **update_folder_path()**: 自动更新路径触发器

### 2. 权限管理

#### 2.1 角色定义

```python
class MemberRole(str, Enum):
    OWNER = "owner"    # 所有者：完全控制
    EDITOR = "editor"  # 编辑者：可编辑内容
    VIEWER = "viewer"  # 查看者：只读访问
```

#### 2.2 权限继承

- 子文件夹自动继承父文件夹的权限
- 可以在子文件夹中覆盖继承的权限
- 递归查询父文件夹权限链

#### 2.3 权限检查流程

```
1. 检查是否是文件夹所有者 → 是：允许
2. 检查是否有直接权限 → 有：比较角色优先级
3. 检查父文件夹权限（递归） → 有：比较角色优先级
4. 无权限 → 拒绝
```

### 3. 克隆功能

#### 3.1 克隆模式

- **content**: 仅克隆当前文件夹的项目
- **recursive**: 递归克隆所有子文件夹和项目

#### 3.2 克隆流程

```
1. 检查源文件夹权限（需要 viewer）
2. 检查目标位置权限（需要 editor）
3. 生成克隆名称（自动添加 "(副本)" 后缀）
4. 检查名称唯一性
5. 创建新文件夹
6. 复制项目（TODO: 等 Project 模型实现）
7. 递归克隆子文件夹（如果是 recursive 模式）
```

#### 3.3 名称生成规则

```
原名称: "我的文件夹"
第一次克隆: "我的文件夹 (副本)"
第二次克隆: "我的文件夹 (副本 2)"
第三次克隆: "我的文件夹 (副本 3)"
...
```

### 4. 统计信息

#### 4.1 统计项

- `subfolder_count`: 子文件夹数量
- `project_count`: 项目数量
- `member_count`: 成员数量
- `total_size`: 总大小（字节）
- `last_activity`: 最后活动时间
- `resource_count`: 资源统计（图片、视频、音频）

#### 4.2 递归统计

支持递归统计所有子文件夹的数据，提供完整的文件夹使用情况。

### 5. API 设计

#### 5.1 成员管理

```
POST   /api/v1/folders/{folder_id}/members          # 添加成员
GET    /api/v1/folders/{folder_id}/members          # 获取成员列表
PUT    /api/v1/folders/{folder_id}/members/{user_id} # 更新成员角色
DELETE /api/v1/folders/{folder_id}/members/{user_id} # 移除成员
```

#### 5.2 克隆

```
POST   /api/v1/folders/{folder_id}/clone            # 克隆文件夹
```

#### 5.3 统计

```
GET    /api/v1/folders/{folder_id}/stats            # 获取统计信息
```

## 实现细节

### 1. 模型层

- 新增 `MemberRole` 枚举
- 新增 `FolderMember` 模型
- 更新 `Folder` 模型（添加 `cover_image_id` 和 `members` 关系）

### 2. Repository 层

新增方法：
- 成员管理：`add_member()`, `remove_member()`, `update_member_role()`, `get_members()`
- 权限检查：`check_user_permission_with_inheritance()`
- 克隆：`clone_folder_content()`, `clone_folder_recursive()`
- 统计：`get_folder_stats()`, `get_total_size()`, `get_last_activity()`

### 3. Service 层

新增方法：
- 成员管理：`add_folder_member()`, `remove_folder_member()`, `update_folder_member_role()`, `get_folder_members()`
- 克隆：`clone_folder()`, `_generate_clone_name()`
- 统计：`get_folder_stats()`

更新方法：
- `_check_folder_permission()`: 使用新的继承权限检查

### 4. Schema 层

新增 Schema：
- `MemberRoleEnum`, `FolderMemberCreate`, `FolderMemberUpdate`, `FolderMemberResponse`, `FolderMemberListResponse`
- `CloneModeEnum`, `FolderCloneRequest`, `FolderCloneResponse`
- `ResourceCountStats`, `FolderStatsResponse`

更新 Schema：
- `FolderResponse`: 添加 `cover_image_id` 和 `cover_image_url`

## 限制和约束

### 1. 当前限制

- **封面图片**: `cover_image_id` 字段已预留，但 `cover_image_url` 暂时返回 `None`（等待 Attachment 模型实现）
- **项目克隆**: 克隆功能仅复制文件夹结构，项目克隆需要 Project 模型支持
- **资源统计**: `resource_count` 暂时返回空数据（需要 Resource 模型支持）
- **总大小**: `total_size` 暂时返回 0（需要 Attachment 模型支持）

### 2. 性能考虑

- 递归权限检查可能影响性能，建议：
  - 限制文件夹层级（最大 10 层）
  - 使用缓存优化权限查询
  - 考虑使用 PostgreSQL 的递归 CTE

- 递归克隆大文件夹可能耗时较长，建议：
  - 使用后台任务处理
  - 提供进度反馈
  - 设置超时限制

### 3. 安全考虑

- 权限检查必须在所有操作前执行
- 不能移除文件夹所有者
- 克隆时需要检查目标位置权限
- 成员管理需要适当的权限级别

## 未来扩展

### 1. 导出功能

- 支持将文件夹打包为 .zip 文件
- 异步处理大文件夹导出
- 提供下载链接（24 小时有效期）

### 2. 分享功能

- 生成公开分享链接
- 支持密码保护
- 设置链接过期时间
- 记录访问日志

### 3. 批量操作

- 批量移动文件夹
- 批量删除文件夹
- 批量导出文件夹

### 4. 权限模板

- 预定义权限模板
- 快速应用权限配置
- 权限继承规则自定义

## 测试计划

### 1. 单元测试

- 权限检查逻辑
- 克隆功能
- 统计信息计算
- 名称生成规则

### 2. 集成测试

- 成员管理 API
- 克隆 API
- 统计 API
- 权限继承

### 3. 性能测试

- 深层文件夹权限检查
- 大文件夹克隆
- 递归统计性能

## 迁移指南

### 1. 数据库迁移

```bash
cd server
python -m app.migrations.002_folder_enhancement
```

### 2. 回滚

```bash
python -m app.migrations.002_folder_enhancement rollback
```

### 3. 验证

```bash
# 检查表是否创建
psql -d your_database -c "\d folder_members"

# 检查函数是否创建
psql -d your_database -c "\df check_folder_permission"
```

## 相关文档

- [文件夹服务文档](../../requirements/backend/04-services/project/folder-service.md)
- [ADR 001: UUID v7 迁移](../../architecture/adrs/001-uuid-v7-migration.md)
- [数据库设计文档](../../requirements/database-design.md)

## 变更记录

### v1.0 (2026-01-20)

- ✅ 实现权限管理（成员、角色、继承）
- ✅ 实现克隆功能（content/recursive）
- ✅ 实现统计信息
- ✅ 预留封面图片字段
- ✅ 创建 PostgreSQL 函数和触发器
- ⚠️ 项目克隆待 Project 模型实现
- ⚠️ 封面图片 URL 待 Attachment 模型实现
- ⚠️ 资源统计待 Resource 模型实现