7.9 KiB

Raw Blame History

文件夹功能实施方案

项目名称：Jointo（jointo）
功能模块：无限极文件夹系统
文档版本：v1.0
创建日期：2025-01-27

1. 方案概述

1.1 功能目标

实现支持无限层级嵌套的文件夹系统，项目可以归属在文件夹下，支持：

✅ 无限层级文件夹创建（限制最大10层）
✅ 文件夹权限继承和独立设置
✅ 项目在文件夹间移动
✅ 文件夹批量操作
✅ 树形结构展示和导航
✅ 拖拽移动支持

1.2 技术方案

采用邻接列表 + 路径缓存的混合方案：

使用 parent_folder_id 存储父子关系
缓存完整路径 path 字段提升查询性能
支持权限继承和批量操作
PostgreSQL 递归查询支持树形结构

1.3 核心优势

实现简单：邻接列表模式易于理解和维护
性能平衡：路径缓存加速常用查询
权限灵活：支持继承和独立权限设置
扩展性好：后续可优化为混合模式

2. 数据库设计

2.1 新增表结构

folders 表

CREATE TABLE folders (
    folder_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    name TEXT NOT NULL,
    description TEXT,
    parent_folder_id BIGINT REFERENCES folders(folder_id) ON DELETE CASCADE,
    owner_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
    path TEXT, -- 缓存路径
    level INTEGER NOT NULL DEFAULT 0 CHECK (level >= 0 AND level <= 10),
    sort_order INTEGER NOT NULL DEFAULT 0,
    color TEXT,
    icon TEXT,
    is_shared BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
    deleted_at TIMESTAMPTZ
);

folder_members 表

CREATE TABLE folder_members (
    folder_member_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
    folder_id BIGINT NOT NULL REFERENCES folders(folder_id) ON DELETE CASCADE,
    user_id BIGINT NOT NULL REFERENCES users(user_id) ON DELETE CASCADE,
    role member_role NOT NULL DEFAULT 'viewer',
    inherited BOOLEAN NOT NULL DEFAULT false,
    created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

2.2 修改现有表

projects 表新增字段

ALTER TABLE projects ADD COLUMN folder_id BIGINT REFERENCES folders(folder_id) ON DELETE SET NULL;

3. API 接口设计

3.1 文件夹管理接口

方法	端点	说明
GET	`/api/v1/folders`	获取文件夹列表
GET	`/api/v1/folders/tree`	获取树形结构
GET	`/api/v1/folders/{id}`	获取文件夹详情
POST	`/api/v1/folders`	创建文件夹
PATCH	`/api/v1/folders/{id}`	更新文件夹
POST	`/api/v1/folders/{id}/move`	移动文件夹
DELETE	`/api/v1/folders/{id}`	删除文件夹
POST	`/api/v1/folders/batch`	批量操作

3.2 文件夹成员管理

方法	端点	说明
GET	`/api/v1/folders/{id}/members`	获取成员列表
POST	`/api/v1/folders/{id}/members`	添加成员
PATCH	`/api/v1/folders/{id}/members/{id}`	更新成员角色
DELETE	`/api/v1/folders/{id}/members/{id}`	移除成员

3.3 项目接口更新

项目列表支持 folderId 参数筛选
项目创建支持指定 folderId
新增项目移动接口：POST /api/v1/projects/{id}/move
新增批量移动接口：POST /api/v1/projects/batch/move

4. 后端服务架构

4.1 新增服务

FolderService

文件夹 CRUD 操作
树形结构查询
权限继承处理
批量操作支持

FolderRepository

数据库操作封装
递归查询优化
权限检查函数

4.2 更新现有服务

ProjectService

支持文件夹权限检查
项目移动功能
批量移动支持

4.3 核心算法

权限继承算法

def check_folder_permission(user_id, folder_id, required_role):
    # 1. 检查直接权限
    # 2. 递归检查父文件夹权限
    # 3. 返回最高权限级别

循环检测算法

def check_folder_cycle(folder_id, new_parent_id):
    # 1. 向上遍历新父文件夹的祖先链
    # 2. 检查是否包含当前文件夹
    # 3. 返回是否存在循环

5. 前端实现要点

5.1 组件设计

FolderTree 组件

树形结构展示
展开/折叠功能
拖拽移动支持
右键菜单操作

FolderBreadcrumb 组件

面包屑导航
快速跳转功能
路径显示

5.2 状态管理

文件夹状态

interface FolderState {
  folders: Folder[];
  currentFolder: Folder | null;
  expandedFolders: Set<string>;
  selectedFolders: Set<string>;
}

项目状态更新

interface ProjectState {
  projects: Project[];
  currentFolderId: string | null;
  // ... 其他状态
}

5.3 交互设计

拖拽移动：支持文件夹和项目的拖拽移动
批量选择：支持多选文件夹和项目
快捷操作：右键菜单提供常用操作
搜索增强：支持在指定文件夹内搜索

6. 实施步骤

阶段1：数据库和后端基础（1-2天）

创建数据库表和索引
实现 FolderRepository 基础功能
实现 FolderService 核心逻辑
添加权限检查函数

阶段2：API 接口开发（2-3天）

实现文件夹 CRUD 接口
实现文件夹成员管理接口
更新项目相关接口
添加批量操作接口

阶段3：前端组件开发（3-4天）

开发 FolderTree 组件
开发 FolderBreadcrumb 组件
更新项目列表组件
实现拖拽移动功能

阶段4：集成测试和优化（1-2天）

前后端集成测试
性能优化
用户体验优化
错误处理完善

7. 风险评估与应对

7.1 技术风险

风险：大量文件夹时查询性能问题应对：

使用路径缓存加速查询
实现分页和懒加载
添加数据库索引优化

风险：权限继承逻辑复杂应对：

使用递归函数简化逻辑
添加权限缓存机制
完善单元测试覆盖

7.2 用户体验风险

风险：文件夹层级过深导致操作困难应对：

限制最大层级为10层
提供面包屑导航
支持搜索和快速跳转

7.3 数据安全风险

风险：文件夹删除导致数据丢失应对：

实现软删除机制
提供数据恢复功能
删除前确认提示

8. 性能优化策略

8.1 数据库优化

为常用查询字段创建索引
使用递归 CTE 优化树形查询
实现查询结果缓存

8.2 API 优化

支持分页和过滤
实现批量操作接口
添加响应数据压缩

8.3 前端优化

实现虚拟滚动
使用懒加载策略
添加本地缓存机制

9. 测试策略

9.1 单元测试

文件夹服务逻辑测试
权限检查函数测试
循环检测算法测试

9.2 集成测试

API 接口功能测试
前后端数据流测试
权限继承场景测试

9.3 用户测试

文件夹操作流程测试
拖拽移动功能测试
批量操作性能测试

10. 上线计划

10.1 灰度发布

内部测试环境验证
小范围用户测试
逐步扩大用户范围
全量发布

10.2 数据迁移

现有项目默认放在根目录
提供批量整理工具
用户自主迁移数据

10.3 用户培训

功能介绍文档
操作视频教程
在线帮助支持

实施方案总结：本方案采用邻接列表 + 路径缓存的设计，平衡了实现复杂度和性能需求。通过分阶段实施，确保功能稳定可靠。预计总开发周期 8-10 天，能够满足无限极文件夹的核心需求。

7.9 KiB Raw Blame History