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

工程分析/经验记录.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 四段。