docs/v1.0/.archive/client/folder-project-separation.md

文件夹项目分离重构计划

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

---

1. 背景与目标

1.1 问题描述

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

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

1.2 目标

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

---

2. 实施方案

2.1 数据结构设计

文件夹数据结构

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

项目数据结构更新

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

UI展示用树形结构

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
• 树形结构构建正确

---

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