# 文件夹项目分离重构计划

> **项目名称**：Jointo（jointo）  
> **功能模块**：文件夹与项目概念分离  
> **文档版本**：v1.0  
> **创建日期**：2025-01-12

---

## 1. 背景与目标

### 1.1 问题描述

当前项目面板混合了文件夹和项目的概念，需要将它们分离：

- 文件夹有独立的API和数据模型
- 项目归属在文件夹下
- 初始化显示"我的项目"和"协作项目"两个根文件夹

### 1.2 目标

- 实现文件夹和项目的概念分离
- 符合API设计规范
- 保持UI展示的一致性
- 为后续文件夹功能扩展打基础

---

## 2. 实施方案

### 2.1 数据结构设计

#### 文件夹数据结构

```typescript
interface Folder {
  id: number;
  name: string;
  parentFolderId: number | null;
  ownerId: number;
  path: string;
  level: number;
  color?: string;
  // ... 其他属性
}
```

#### 项目数据结构更新

```typescript
interface Project {
  // ... 现有属性
  folderId?: number; // 新增：所属文件夹ID
}
```

#### UI展示用树形结构

```typescript
interface TreeNode {
  id: string;
  name: string;
  type: "root-folder" | "folder" | "project";
  folderId?: number; // 文件夹ID
  projectId?: number; // 项目ID
  children?: TreeNode[];
}
```

---

## 3. 实施步骤

### ✅ 步骤1：创建文件夹类型定义

- 创建 `client/src/types/folder.ts`
- 定义 `Folder`、`CreateFolderDto`、`UpdateFolderDto` 等类型
- 定义树形展示用的 `TreeNode` 类型

### ✅ 步骤2：更新项目类型

- 在 `Project` 接口中添加 `folderId` 字段
- 更新类型导出

### ✅ 步骤3：创建文件夹Mock数据

- 创建 `client/src/mocks/folders.ts`
- 实现文件夹的mock数据和辅助函数
- 包含"我的项目"和"协作项目"两个根文件夹

### ✅ 步骤4：更新项目Mock数据

- 为所有项目添加 `folderId` 字段
- 移除旧的 `mockProjectTree`
- 添加 `getProjectsByFolderId` 辅助函数

### ✅ 步骤5：创建树形数据构建工具

- 创建 `client/src/utils/treeBuilder.ts`
- 实现 `buildProjectTree` 函数
- 实现相关辅助函数

### ✅ 步骤6：更新ProjectPanel组件

- 使用新的文件夹和项目数据
- 通过 `buildProjectTree` 构建树形结构
- 更新展开状态管理

### ✅ 步骤7：更新ProjectTreeNode组件

- 支持新的 `TreeNode` 类型
- 区分根文件夹、普通文件夹和项目的处理逻辑
- 暂时注释ProjectContextMenu避免导入问题

### ✅ 步骤8：更新导出文件

- 更新 `client/src/mocks/index.ts`
- 更新 `client/src/types/index.ts`

---

## 4. 数据映射关系

### 4.1 文件夹结构

```
我的项目 (id: 1, parentId: null)
├── 西游记之大圣归来 (id: 3, parentId: 1)
│   └── 2015第一部.kd (projectId: 1, folderId: 3)
├── 琅琊榜 (id: 4, parentId: 1)
│   ├── 第一集.kd (projectId: 2, folderId: 4)
│   ├── 第二集.kd (projectId: 3, folderId: 4)
│   ├── 第三集.kd (projectId: 4, folderId: 4)
│   ├── 第四集.kd (projectId: 5, folderId: 4)
│   └── 第五集.kd (projectId: 6, folderId: 4)
├── 流浪地球 (id: 5, parentId: 1)
│   └── 流浪地球.kd (projectId: 7, folderId: 5)
├── 蒙牛新年好礼2025广告片 (id: 6, parentId: 1)
│   └── 广告片.kd (projectId: 8, folderId: 6)
└── 十三邀 (id: 7, parentId: 1)
    └── 片头动画.kd (projectId: 9, folderId: 7)

协作项目 (id: 2, parentId: null)
└── 协同项目示例.kd (projectId: 10, folderId: 2)
```

---

## 5. 技术要点

### 5.1 树形数据构建

- 使用 `buildProjectTree` 函数动态构建树形结构
- 支持文件夹嵌套和项目归属
- 颜色映射从十六进制转换为预定义颜色

### 5.2 组件更新

- ProjectPanel使用useMemo优化树形数据构建
- ProjectTreeNode支持三种节点类型：root-folder、folder、project
- 根文件夹不显示操作菜单

### 5.3 向后兼容

- 保留旧的类型定义并标记为deprecated
- 渐进式迁移，避免破坏现有功能

---

## 6. 待解决问题

### 6.1 ProjectContextMenu导入问题

- 当前暂时注释了ProjectContextMenu的使用
- 需要后续解决导入路径问题

### 6.2 后续扩展

- 文件夹权限管理
- 文件夹拖拽移动
- 文件夹批量操作

---

## 7. 验证方式

### 7.1 功能验证

- 项目面板正常显示两个根文件夹
- 文件夹可以正常展开/折叠
- 项目正确归属在对应文件夹下

### 7.2 数据验证

- 文件夹数据结构符合API规范
- 项目数据包含正确的folderId
- 树形结构构建正确

---

**实施总结**：
本次重构成功实现了文件夹和项目概念的分离，建立了清晰的数据结构和组件架构。为后续文件夹功能的扩展奠定了良好基础。主要改动包括新增文件夹类型定义、更新项目数据结构、重构组件逻辑等。