jrh
/
docs
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
3 Commits
1 Branch
0 Tags
2.6 MiB
 
Branch: main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'main'
${ noResults }
docs/v1.0/server/rfcs/120-folder-enhancement.md

8.0 KiB
Raw Permalink Blame History

RFC 120: 文件夹功能增强

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

概述

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

动机

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

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

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

设计方案

1. 数据库设计

1.1 folders 表增强

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

新增字段：

  • cover_image_id: 封面图片 ID（可选）

1.2 folder_members 表

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 角色定义

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. 数据库迁移

cd server
python -m app.migrations.002_folder_enhancement

2. 回滚

python -m app.migrations.002_folder_enhancement rollback

3. 验证

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

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

相关文档

变更记录

v1.0 (2026-01-20)

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