Pre_Seg_Server/工程分析/经验记录.md

经验记录（Knowledge Base）

本文件按代码编纂工作流规范，以四段式记录项目修改过程中遇到的关键问题及解决方案。
格式: A. 具体问题 / B. 产生原因 / C. 解决方案 / D. 后续如何避免

---

2026-04-28-22-55-15 — 建立代码编纂工作流

A. 具体问题

项目缺少标准化的代码修改流程，导致需求管理、方案设计、测试验证、知识沉淀等环节可能遗漏，影响项目质量和可维护性。

B. 产生原因

项目初期以快速原型为主，未建立正式的工程化管理流程；随着功能增加，需要更严谨的变更管理机制。

C. 解决方案

建立完整的代码编纂工作流，包含 10 个阶段：时间戳记录、工程分析、需求分析、实现方案（人工审核）、测试方案（人工审核）、执行前准备（阅读经验记录）、方案执行、经验沉淀、Gitea 备份、重新部署。

D. 后续如何避免问题

• 后续所有项目修改严格按工作流执行
• 每次修改前检查工作流检查表
• 定期回顾经验记录，提取共性预防措施

---

2026-04-28-22-55-15 — 执行环境 Node.js 缺失

A. 具体问题

执行 npm run lint 和 npm run build 时提示 npm: command not found，当前 Shell 环境未安装 Node.js 运行时。

B. 产生原因

AI 助手运行的容器/环境与项目实际开发环境分离，后者才装有 Node.js 和 npm。

C. 解决方案

• 文档创建和 git 操作可在 AI 环境中完成
• 构建验证（npm run lint、npm run build、npm start）需由用户在本地开发环境执行，或 AI 提供精确命令由用户自行运行
• 实际解决: 用户提供了 sudo 权限和密码后，AI 通过 NodeSource 安装了 Node.js 22.x（curl -fsSL https://deb.nodesource.com/setup_22.x | sudo bash + sudo apt install -y nodejs），随后成功执行了完整部署流程
• 在经验记录中标注此限制和解决方案，提醒后续流程

D. 后续如何避免问题

• 每次执行阶段 6 和阶段 9 前，先检查 which npm
• 如 npm 不可用，向用户申请 sudo 权限安装 Node.js，或使用项目预设的容器/CI 环境
• 如用户无法提供 sudo，则提供精确的手动执行命令清单
• 考虑在 CI/CD 流程中统一构建环境

---

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 四段。