来源：AI开发日志公众号专辑「Build Your Own X With AI」
原文链接：https://mp.weixin.qq.com/s?__biz=MzUxMjg3MjE2OA==&mid=2247485975&idx=1&sn=d7d06bd4a9b22e8c54d489bca3ad14c0&chksm=f95c9190ce2b1886b1f5c382a97fb545dffce20df4cbd2488d18de2b1c3360c31f88308e3d12#rd
需求文档
介绍
本功能旨在创建一个交互式 3D 可视化系统，用于展示 Git 版本控制系统的核心概念和操作。通过 3D 动画，用户可以直观地理解 Git 的分支、提交、合并等操作，使抽象的版本控制概念变得具象化和易于理解。
术语表
- Visualization System（可视化系统）
-
负责渲染和管理 3D 场景的核心系统
- Git Parser（Git 解析器）
-
读取和解析 Git 仓库数据的组件
- Commit Node（提交节点）
-
在 3D 空间中代表单个 Git 提交的可视化对象
- Branch Line（分支线）
-
连接提交节点的 3D 线条，表示 Git 分支
- Animation Controller（动画控制器）
-
管理场景中所有动画效果的组件
- Camera System（相机系统）
-
控制用户视角和场景导航的系统
- User Interface（用户界面）
-
提供用户交互控制的界面层
需求
需求 1
用户故事: 作为开发者，我想要看到 Git 提交历史的 3D 可视化，以便更直观地理解项目的演进过程
验收标准
WHEN Git Parser 读取仓库数据，THE Visualization System SHALL 为每个提交创建一个 Commit Node
THE Visualization System SHALL 在 3D 空间中按时间顺序排列 Commit Node
THE Visualization System SHALL 使用 Branch Line 连接父子提交关系
THE Commit Node SHALL 显示提交的哈希值、作者和消息摘要
WHEN 用户悬停在 Commit Node 上，THE User Interface SHALL 显示完整的提交详情
需求 2
用户故事: 作为开发者，我想要看到 Git 分支的 3D 表示，以便理解分支之间的关系和合并历史
验收标准
THE Visualization System SHALL 为每个 Git 分支分配唯一的颜色
THE Branch Line SHALL 使用对应分支的颜色进行渲染
WHEN 检测到分支分叉，THE Visualization System SHALL 在 3D 空间中分离 Branch Line
WHEN 检测到分支合并，THE Animation Controller SHALL 播放合并动画效果
THE User Interface SHALL 显示所有活动分支的列表和颜色标识
需求 3
用户故事: 作为用户，我想要控制 3D 场景的视角，以便从不同角度查看 Git 历史
验收标准
THE Camera System SHALL 支持鼠标拖拽旋转视角
THE Camera System SHALL 支持鼠标滚轮缩放场景
THE Camera System SHALL 支持键盘方向键平移视角
THE Camera System SHALL 提供重置视角到默认位置的功能
WHEN 用户双击 Commit Node，THE Camera System SHALL 平滑移动并聚焦到该节点
需求 4
用户故事: 作为用户，我想要看到 Git 操作的动画效果，以便理解操作的执行过程
验收标准
WHEN 播放提交操作，THE Animation Controller SHALL 显示新 Commit Node 的创建动画
WHEN 播放分支操作，THE Animation Controller SHALL 显示新 Branch Line 的生长动画
WHEN 播放合并操作，THE Animation Controller SHALL 显示两条 Branch Line 汇聚的动画
THE Animation Controller SHALL 提供播放、暂停和重置动画的控制功能
THE User Interface SHALL 显示当前动画的时间轴和进度
需求 5
用户故事: 作为用户，我想要加载本地或远程 Git 仓库，以便可视化任何项目的历史
验收标准
THE User Interface SHALL 提供输入本地仓库路径的功能
THE User Interface SHALL 提供输入远程仓库 URL 的功能
WHEN 用户提交仓库路径，THE Git Parser SHALL 验证路径的有效性
IF 仓库路径无效，THEN THE User Interface SHALL 显示错误提示信息
WHEN Git Parser 成功加载仓库，THE Visualization System SHALL 开始渲染 3D 场景
需求 6
用户故事: 作为用户，我想要过滤和搜索特定的提交，以便专注于感兴趣的历史部分
验收标准
THE User Interface SHALL 提供按作者过滤提交的功能
THE User Interface SHALL 提供按日期范围过滤提交的功能
THE User Interface SHALL 提供按提交消息搜索的功能
WHEN 应用过滤条件，THE Visualization System SHALL 仅显示匹配的 Commit Node
THE Visualization System SHALL 保持过滤后节点之间的连接关系可见
需求 7
用户故事: 作为用户，我想要导出 3D 场景的截图或视频，以便分享可视化结果
验收标准
THE User Interface SHALL 提供截图功能按钮
THE User Interface SHALL 提供录制视频功能按钮
WHEN 用户点击截图，THE Visualization System SHALL 捕获当前视角的高分辨率图像
WHEN 用户开始录制，THE Visualization System SHALL 记录场景的帧序列
THE User Interface SHALL 允许用户选择导出文件的保存位置和格式
实施计划
[-] 1. 初始化项目结构和依赖
使用 Vite 创建 React + TypeScript 项目
安装核心依赖：three, @react-three/fiber, @react-three/drei, isomorphic-git, zustand, gsap, tailwindcss
配置 TypeScript 和 ESLint
创建基础目录结构：src/components, src/lib, src/hooks, src/store, src/types
需求: 5.5
[ ] 2. 实现 Git 数据解析层
创建 TypeScript 类型定义（Commit, Branch, Repository 等接口）
实现 GitParser 类，包含 loadLocalRepository 和 getCommitHistory 方法
实现仓库路径验证逻辑
添加错误处理和自定义错误类型（GitVisualizationError）
需求: 5.3, 5.4, 1.1
[ ] 3. 实现数据转换和布局算法
创建 DataTransformer 类
实现 transformCommitsToNodes 方法，将 Git 提交转换为 3D 节点数据
实现 calculateNodePositions 方法，使用时间轴布局算法计算节点位置
实现 generateBranchLines 方法，生成贝塞尔曲线连接线
实现 assignBranchColors 方法，为分支分配唯一颜色
需求: 1.1, 1.2, 1.3, 2.1, 2.3
[ ] 4. 创建状态管理 Store
使用 Zustand 创建全局状态管理
定义 AppState 接口，包含 repository, commits, branches, nodes, lines 等状态
实现 loadRepository action
实现 selectNode action
实现 applyFilters action
需求: 5.5, 6.4
[ ] 5. 实现 3D 场景核心组件
[ ] 5.1 创建 CommitNodeMesh 组件
使用 Three.js 创建球体几何体表示提交节点
添加文字标签显示提交哈希和消息
实现高亮和取消高亮效果
需求: 1.1, 1.4
[ ] 5.2 创建 BranchLineMesh 组件
使用 Three.js Line 创建分支连接线
实现贝塞尔曲线路径
应用分支颜色
需求: 1.3, 2.2
[ ] 5.3 创建 SceneManager 组件
使用 React Three Fiber 初始化 3D 场景
实现 addNode 和 addLine 方法
设置场景光照和背景
实现渲染循环
需求: 1.1, 1.2, 5.5
[ ] 6. 实现相机控制系统
创建 CameraController 类
使用 @react-three/drei 的 OrbitControls 实现鼠标拖拽旋转
实现鼠标滚轮缩放功能
实现键盘方向键平移功能
实现 focusOnNode 方法，双击节点时平滑聚焦
实现 reset 方法，重置相机到默认位置
需求: 3.1, 3.2, 3.3, 3.4, 3.5
[ ] 7. 实现动画控制系统
创建 AnimationController 类
使用 GSAP 实现提交节点的创建动画（淡入 + 缩放）
实现分支线的生长动画（路径绘制效果）
实现合并动画（两条线汇聚效果）
创建动画时间轴控制（播放、暂停、停止、速度调整）
需求: 4.1, 4.2, 4.3, 4.4
[ ] 8. 创建用户界面组件
[ ] 8.1 创建仓库加载面板
创建输入框组件用于输入本地仓库路径
创建输入框组件用于输入远程仓库 URL
添加加载按钮和加载状态指示器
实现错误提示显示
需求: 5.1, 5.2, 5.4
[ ] 8.2 创建控制面板
创建动画控制按钮（播放、暂停、停止）
创建速度调节滑块
创建时间轴进度条
创建相机重置按钮
需求: 4.4, 4.5, 3.4
[ ] 8.3 创建信息面板
创建提交详情显示组件（悬停时显示）
创建分支列表组件，显示所有分支和颜色标识
实现节点选中时的详细信息展示
需求: 1.5, 2.5
[ ] 8.4 创建过滤和搜索面板
创建作者过滤下拉选择器
创建日期范围选择器
创建提交消息搜索输入框
实现过滤条件应用和清除功能
需求: 6.1, 6.2, 6.3
[ ] 9. 实现过滤引擎
创建 FilterEngine 类
实现 filterByAuthor 方法
实现 filterByDateRange 方法
实现 searchByMessage 方法
实现 applyFilters 方法，组合多个过滤条件
更新场景以仅显示过滤后的节点和连线
需求: 6.1, 6.2, 6.3, 6.4, 6.5
[ ] 10. 实现导出功能
实现截图功能，使用 canvas.toDataURL 捕获当前场景
创建截图按钮和下载逻辑
实现视频录制功能，使用 MediaRecorder API 记录帧序列
创建录制控制按钮（开始/停止录制）
实现文件保存对话框和格式选择
需求: 7.1, 7.2, 7.3, 7.4, 7.5
[ ] 11. 实现性能优化
实现视锥剔除，只渲染可见节点
使用 THREE.InstancedMesh 优化大量相似节点的渲染
实现 LOD（细节层次），远处节点使用简化几何体
添加分页加载，限制一次渲染的节点数量
实现内存管理，及时释放不再使用的 Three.js 对象
需求: 1.1, 1.2
[ ] 12. 集成所有组件并完成主应用
创建主 App 组件，整合所有子组件
连接状态管理和 UI 组件
实现组件间的事件通信
添加加载状态和错误边界
测试完整的用户流程：加载仓库 → 查看可视化 → 交互控制 → 过滤搜索 → 导出
需求: 1.1, 1.2, 1.3, 1.4, 1.5, 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 3.4, 3.5, 4.1, 4.2, 4.3, 4.4, 4.5, 5.1, 5.2, 5.3, 5.4, 5.5, 6.1, 6.2, 6.3, 6.4, 6.5, 7.1, 7.2, 7.3, 7.4, 7.5
[ ]* 13. 编写测试
[ ]* 13.1 编写 GitParser 单元测试
测试 loadLocalRepository 方法
测试 getCommitHistory 方法
测试错误处理逻辑
需求: 5.3, 5.4
[ ]* 13.2 编写 DataTransformer 单元测试
测试节点位置计算算法
测试分支线生成逻辑
测试颜色分配算法
需求: 1.2, 1.3, 2.1
[ ]* 13.3 编写 FilterEngine 单元测试
测试各种过滤条件
测试过滤条件组合
测试边界情况
需求: 6.1, 6.2, 6.3, 6.4
[ ]* 13.4 编写组件集成测试
测试仓库加载流程
测试相机交互
测试动画播放
测试过滤和搜索
需求: 5.5, 3.1, 3.2, 4.4, 6.4