# 文件夹功能实施方案

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

---

## 1. 方案概述

### 1.1 功能目标

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

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

### 1.2 技术方案

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

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

### 1.3 核心优势

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

---

## 2. 数据库设计

### 2.1 新增表结构

#### folders 表

```sql
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 表

```sql
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 表新增字段

```sql
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 核心算法

#### 权限继承算法

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

#### 循环检测算法

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

---

## 5. 前端实现要点

### 5.1 组件设计

#### FolderTree 组件

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

#### FolderBreadcrumb 组件

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

### 5.2 状态管理

#### 文件夹状态

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

#### 项目状态更新

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

### 5.3 交互设计

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

---

## 6. 实施步骤

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

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

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

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

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

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

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

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

---

## 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 灰度发布

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

### 10.2 数据迁移

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

### 10.3 用户培训

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

---

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