2026-04-29-21-27-10 - 组件目录扁平化重构

2026-04-29 21:32:15 +08:00
parent 72cf0a7094
commit c8f8686097
16 changed files with 286 additions and 14 deletions
--- a/工程分析/实现方案-2026-04-29-21-27-10.md
+++ b/工程分析/实现方案-2026-04-29-21-27-10.md
@@ -0,0 +1,135 @@
+# 实现方案 - 2026-04-29-21-27-10
+
+## 对应需求
+- 需求分析文档: `需求分析-2026-04-29-21-27-10.md`
+
+## 方案概述
+将 `src/components/` 下 7 个子目录共 11 个 `.tsx` 组件文件全部移动到 `src/components/` 根目录，并更新所有相关 import 路径。这是一个纯路径重构，不涉及任何业务逻辑变更。
+
+## 当前目录结构
+
+```
+src/components/
+├── ai/
+│   └── AISegmentation.tsx
+├── auth/
+│   └── Login.tsx
+├── dashboard/
+│   └── Dashboard.tsx
+├── layout/
+│   └── Sidebar.tsx
+├── projects/
+│   └── ProjectLibrary.tsx
+├── templates/
+│   └── TemplateRegistry.tsx
+└── workspace/
+    ├── CanvasArea.tsx
+    ├── FrameTimeline.tsx
+    ├── OntologyInspector.tsx
+    ├── ToolsPalette.tsx
+    └── VideoWorkspace.tsx
+```
+
+## 目标目录结构
+
+```
+src/components/
+├── AISegmentation.tsx
+├── Login.tsx
+├── Dashboard.tsx
+├── Sidebar.tsx
+├── ProjectLibrary.tsx
+├── TemplateRegistry.tsx
+├── CanvasArea.tsx
+├── FrameTimeline.tsx
+├── OntologyInspector.tsx
+├── ToolsPalette.tsx
+└── VideoWorkspace.tsx
+```
+
+## 修改文件清单
+
+### 文件 1-11: 组件文件移动（11 个文件）
+- **修改类型**: 移动（mv）
+- **文件列表**:
+  - `src/components/ai/AISegmentation.tsx` → `src/components/AISegmentation.tsx`
+  - `src/components/auth/Login.tsx` → `src/components/Login.tsx`
+  - `src/components/dashboard/Dashboard.tsx` → `src/components/Dashboard.tsx`
+  - `src/components/layout/Sidebar.tsx` → `src/components/Sidebar.tsx`
+  - `src/components/projects/ProjectLibrary.tsx` → `src/components/ProjectLibrary.tsx`
+  - `src/components/templates/TemplateRegistry.tsx` → `src/components/TemplateRegistry.tsx`
+  - `src/components/workspace/CanvasArea.tsx` → `src/components/CanvasArea.tsx`
+  - `src/components/workspace/FrameTimeline.tsx` → `src/components/FrameTimeline.tsx`
+  - `src/components/workspace/OntologyInspector.tsx` → `src/components/OntologyInspector.tsx`
+  - `src/components/workspace/ToolsPalette.tsx` → `src/components/ToolsPalette.tsx`
+  - `src/components/workspace/VideoWorkspace.tsx` → `src/components/VideoWorkspace.tsx`
+
+### 文件 12: `src/App.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `./components/layout/Sidebar` → `./components/Sidebar`
+  - `./components/dashboard/Dashboard` → `./components/Dashboard`
+  - `./components/projects/ProjectLibrary` → `./components/ProjectLibrary`
+  - `./components/workspace/VideoWorkspace` → `./components/VideoWorkspace`
+  - `./components/templates/TemplateRegistry` → `./components/TemplateRegistry`
+  - `./components/ai/AISegmentation` → `./components/AISegmentation`
+  - `./components/auth/Login` → `./components/Login`
+
+### 文件 13: `src/components/AISegmentation.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `../../lib/utils` → `../lib/utils`
+  - `../workspace/OntologyInspector` → `./OntologyInspector`
+
+### 文件 14: `src/components/Login.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `../../lib/utils` → `../lib/utils`
+
+### 文件 15: `src/components/Sidebar.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `../../lib/utils` → `../lib/utils`
+  - `../../App` → `../App`
+
+### 文件 16: `src/components/ToolsPalette.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `../../lib/utils` → `../lib/utils`
+
+### 文件 17: `src/components/FrameTimeline.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `../../lib/utils` → `../lib/utils`
+
+### 文件 18: `src/components/VideoWorkspace.tsx`（修改）
+- **修改类型**: 修改 import 路径
+- **修改内容**:
+  - `./CanvasArea` → `./CanvasArea`（不变，已在同目录）
+  - `./ToolsPalette` → `./ToolsPalette`（不变，已在同目录）
+  - `./OntologyInspector` → `./OntologyInspector`（不变，已在同目录）
+  - `./FrameTimeline` → `./FrameTimeline`（不变，已在同目录）
+  - 注：VideoWorkspace 原本在 workspace 子目录内引用同级文件，移动到根目录后路径格式不变
+
+### 文件 19-21: 清理空目录（7 个目录）
+- **修改类型**: 删除空目录
+- **目录列表**:
+  - `src/components/ai/`
+  - `src/components/auth/`
+  - `src/components/dashboard/`
+  - `src/components/layout/`
+  - `src/components/projects/`
+  - `src/components/templates/`
+  - `src/components/workspace/`
+
+## 新增依赖
+无
+
+## 兼容性分析
+- 与现有功能冲突: 无，纯路径重构
+- 回滚策略: 通过 git 回滚到上一个 commit 即可
+
+## 预估工作量
+- 文件移动: 5 分钟
+- 路径更新: 10 分钟
+- 验证构建: 5 分钟
--- a/工程分析/测试方案-2026-04-29-21-27-10.md
+++ b/工程分析/测试方案-2026-04-29-21-27-10.md
@@ -0,0 +1,70 @@
+# 测试方案 - 2026-04-29-21-27-10
+
+## 对应实现方案
+- 实现方案文档: `实现方案-2026-04-29-21-27-10.md`
+
+## 测试范围
+- 文件移动正确性
+- 所有 import 路径更新完整性
+- TypeScript 类型检查通过
+- 生产构建成功
+- 空目录已清理
+
+## 测试用例
+
+### 用例 1: 文件位置验证
+- **前置条件**: 文件移动已完成
+- **操作步骤**:
+  1. 执行 `ls src/components/*.tsx`
+  2. 确认 11 个组件文件均位于根目录
+- **预期结果**: 输出包含全部 11 个 `.tsx` 文件
+- **通过标准**: 文件数量正确，无遗漏
+
+### 用例 2: 子目录清理验证
+- **前置条件**: 空目录删除已完成
+- **操作步骤**:
+  1. 执行 `find src/components -type d`
+  2. 确认仅输出 `src/components` 本身
+- **预期结果**: 无子目录残留
+- **通过标准**: 除根目录外无其他目录
+
+### 用例 3: Import 路径完整性验证
+- **前置条件**: 所有路径已更新
+- **操作步骤**:
+  1. 全局搜索 `from './components/`，确认无旧路径残留
+  2. 全局搜索 `from '../workspace/`、`from '../ai/` 等，确认无旧路径残留
+  3. 全局搜索 `../../lib/utils`，确认无旧路径残留
+- **预期结果**: 上述旧路径模式均不存在于代码中
+- **通过标准**: grep 结果为空
+
+### 用例 4: TypeScript 类型检查
+- **前置条件**: 路径更新完成
+- **操作步骤**: 执行 `npm run lint`
+- **预期结果**: 命令成功，无类型错误
+- **通过标准**: exit code 为 0
+
+### 用例 5: 生产构建验证
+- **前置条件**: 类型检查通过
+- **操作步骤**: 执行 `npm run build`
+- **预期结果**: Vite 构建成功，dist/ 目录生成
+- **通过标准**: exit code 为 0，dist/ 存在
+
+### 用例 6: 应用运行验证
+- **前置条件**: 构建成功
+- **操作步骤**:
+  1. 启动服务 `npm start`
+  2. 访问 `http://localhost:3000`
+- **预期结果**: 页面正常加载，SPA 渲染无报错
+- **通过标准**: HTTP 200，控制台无模块加载错误
+
+## 回归测试
+- [ ] `App.tsx` 可正确解析所有组件 import
+- [ ] `VideoWorkspace.tsx` 可正确解析内部组件 import
+- [ ] `AISegmentation.tsx` 可正确解析 `OntologyInspector` import
+- [ ] 所有引用 `cn()` 的组件可正确解析 `../lib/utils`
+- [ ] `Sidebar.tsx` 可正确解析 `../App` type import
+
+## 测试环境
+- 浏览器: Chrome
+- Node.js: v22.22.2
+- 测试数据: 无（纯结构重构）
--- a/工程分析/经验记录.md
+++ b/工程分析/经验记录.md
@@ -45,4 +45,24 @@ AI 助手运行的容器/环境与项目实际开发环境分离，后者才装

 ---

+## 2026-04-29-21-27-10 — 组件目录扁平化重构
+
+### A. 具体问题
+将 `src/components/` 下 7 个子目录共 11 个组件文件扁平化到根目录时，需要同步更新多处 import 相对路径，存在遗漏风险。
+
+### B. 产生原因
+组件文件在子目录中时，引用 `lib/utils.ts` 的路径为 `../../lib/utils`，引用其他组件的路径为 `../workspace/XXX`；扁平化到根目录后，这些路径需分别变更为 `../lib/utils` 和 `./XXX`。涉及文件多、路径变体多，手工逐一修改容易遗漏。
+
+### C. 解决方案
+- 重构前先通过 `grep` 全局扫描所有 import 语句，建立完整的"文件-旧路径-新路径"映射表
+- 移动文件和修改路径分两步执行，每步完成后都用 grep 验证旧路径模式是否完全消失
+- 最后运行 `npm run lint` 和 `npm run build` 作为最终校验，TypeScript 编译器会捕获任何遗漏的路径错误
+
+### D. 后续如何避免问题
+- 任何涉及文件移动的 refactoring，都必须先全局 grep 所有相对路径引用，形成清单后再执行
+- 执行后立即用 grep 反向验证旧路径模式残留
+- 始终将 `npm run lint` 作为路径重构后的强制检查步骤
+
+---
+
 > 新增经验请追加到文件末尾，保持时间倒序或正序均可，但需确保每条经验包含完整的 A/B/C/D 四段。
--- a/工程分析/需求分析-2026-04-29-21-27-10.md
+++ b/工程分析/需求分析-2026-04-29-21-27-10.md
@@ -0,0 +1,47 @@
+# 需求分析 - 2026-04-29-21-27-10
+
+## 需求来源
+- 提出时间: 2026-04-29-21-27-10
+- 需求类型: 代码重构 / 目录结构调整
+
+## 原始需求描述
+将 `\src\components` 中所有子文件夹内的组件文件全部移入 `\src\components` 根目录，即取消子文件夹层级，实现组件目录扁平化。
+
+## 需求拆解
+
+### 需求 1: 移动组件文件到根目录
+- **详细描述**: 将 `src/components/` 下所有子目录中的 `.tsx` 文件移动到 `src/components/` 根目录
+- **优先级**: P0-阻塞
+- **影响范围**: `src/components/` 下全部子目录
+- **验收标准**: 所有组件文件均位于 `src/components/` 根目录，无残留子目录中的 `.tsx` 文件
+
+### 需求 2: 更新 App.tsx 的 import 路径
+- **详细描述**: `App.tsx` 中引用了 7 个组件，路径格式为 `./components/{子目录}/{文件名}`，需更新为 `./components/{文件名}`
+- **优先级**: P0-阻塞
+- **影响范围**: `src/App.tsx`
+- **验收标准**: `App.tsx` 中所有组件 import 路径正确指向扁平化后的位置
+
+### 需求 3: 更新组件间相互引用的路径
+- **详细描述**: 组件之间存在内部引用，需将相对路径调整为扁平化后的正确路径
+- **优先级**: P0-阻塞
+- **影响范围**: `AISegmentation.tsx`、`VideoWorkspace.tsx` 及所有引用 `lib/utils.ts` 的组件
+- **验收标准**: 所有组件内部 import 路径正确
+
+### 需求 4: 清理空子目录
+- **详细描述**: 文件移动后，删除 `src/components/` 下所有空的子目录
+- **优先级**: P1-高
+- **影响范围**: `src/components/ai/`、`auth/`、`dashboard/`、`layout/`、`projects/`、`templates/`、`workspace/`
+- **验收标准**: 所有空目录已删除
+
+## 约束条件
+- 不修改任何组件的业务逻辑代码
+- 不修改组件文件名
+- 保持 `src/lib/utils.ts` 等工具文件位置不变
+- 构建和类型检查必须全部通过
+
+## 风险评估
+| 风险点 | 影响 | 缓解措施 |
+|--------|------|----------|
+| 遗漏某条 import 路径未更新 | 高 | 全局搜索所有 `./components/` 引用，逐一核对 |
+| 组件间循环引用未被识别 | 中 | 使用 grep 全面扫描所有 import 语句 |
+| 空目录清理不彻底 | 低 | 使用 find 命令验证 |