张翔
38be4a19ef
- 新增 hooks/components/lib 共 9 个测试文件，覆盖边界条件与异常路径 - 补充 animations.test.tsx 用例（RotatingBorder、CounterWithEffect 等） - 修复 useCountUp 结束时 toFixed 精度问题 - 调整 jest 覆盖率配置为渐进式阈值，收缩收集范围 - 新增 docs/lessons-learned.md（经验教训汇总）与 docs/troubleshooting.md（问题排查索引） - 更新 README.md 文档索引
5.7 KiB
5.7 KiB
Lessons Learned（项目经验教训）
记录跨任务、跨阶段的工程经验教训，避免重复踩坑。按类别组织，定期更新。
目录
1. 技术选型与依赖
1.1 外部字体服务导致白屏
- 问题：依赖 Google Fonts 等外部字体服务，网络加载失败时页面白屏。
- 根因：字体加载阻塞首次渲染（FOUT/FOIT 未妥善处理）。
- 方案：所有字体使用本地文件（
src/app/fonts/），禁止外部字体 CDN。 - 来源：
2026-03-04部署事故，project_memory.mdHard Constraints。
1.2 React 19 + Next.js 16 HMR 兼容性
- 问题：开发模式下 HMR 报错
module factory is not available，需要频繁清除缓存。 - 根因：React 19 与 Next.js 16 的 HMR 模块缓存机制不兼容。
- 方案：禁用
optimizeCss实验性功能；若持续影响开发，改用生产模式（npm run build && npm run start）。 - 来源：
docs/HMR-ERROR-SOLUTIONS.md。
1.3 webpackBuildWorker 导致静态资源 404
- 问题：启用
experimental.webpackBuildWorker: true后，客户端静态资源 404。 - 根因：webpack 构建工作线程与 Next.js 静态导出不兼容。
- 方案：强制禁用该功能，在
next.config.ts中不启用或显式设为false。 - 来源：
project_memory.mdHard Constraints。
2. 构建与部署
2.1 直接复制参考网站代码
- 问题：从参考网站直接复制 HTML/CSS/JS 到项目中，导致样式冲突和技术债务。
- 根因：参考网站的样式体系（Bootstrap/其他框架）与项目 Tailwind 体系冲突。
- 方案：仅参考设计理念和布局，所有代码手动基于 Tailwind 实现。
- 来源：
project_memory.mdLessons Learned。
2.2 静态导出限制
- 问题：
output: 'export'模式下，next/image需要unoptimized，某些 API 路由不可用。 - 根因：Next.js 静态导出对 Server Components 和 API Routes 的限制。
- 方案：移除
output: 'export'，改用standalone或混合模式；图片使用unoptimized或<img>标签。 - 来源：
CLAUDE.mdBuild Output 章节。
3. 样式与设计
3.1 光晕效果遮挡内容
- 问题：Case Studies 区域卡片悬停光晕（halo effect）尺寸过大，遮挡文字。
- 根因：光晕半径 256px + 不透明度 100%，超出卡片边界。
- 方案：尺寸降至 192px，不透明度降至 0.08（降低 92%）。
- 来源：
project_memory.mdLessons Learned；后续推广为全局规则：所有光晕效果不透明度降低 30-50%。
3.2 未使用的大文件残留
- 问题：项目中残留 4.2MB 的 AoyagiReisho 书法字体文件，增加页面加载时间。
- 根因：早期设计尝试引入书法字体，切换方案后未清理。
- 方案：定期检查
public/fonts/和src/app/fonts/中未使用的字体文件，及时删除。 - 来源：
project_memory.mdLessons Learned。
3.3 品牌红使用过度
- 问题：品牌红色（#C41E3A）在页面中占比超过 10%，视觉冲击过强。
- 根因：缺乏品牌色使用规范约束。
- 方案：制定品牌红贯穿规则——每页至少 3 处触达点，但面积 ≤ 10%；禁止作为段落文字色、大面积背景色。
- 来源：
CONTEXT.md朱砂点睛章节。
4. 性能优化
4.1 高并发下内存溢出
- 问题：200 VUs 并发时服务崩溃，单实例无法处理高并发请求。
- 根因：缺乏负载均衡、缓存策略和资源限制。
- 方案：多实例部署（Docker Compose 3 实例）+ PM2 进程管理 + Nginx 负载均衡。
- 来源：
docs/PERFORMANCE_OPTIMIZATION.md。
5. 测试
5.1 测试框架冗余
- 问题：项目存在三个独立的测试框架（e2e/, e2e-tests/, test-framework/），维护成本高。
- 根因：早期多次试验不同测试方案，未及时清理废弃框架。
- 方案：统一到 Playwright + Jest 体系，废弃 Python Playwright 和独立测试框架。
- 来源：
docs/OPTIMIZATION_REPORT.md。
5.2 测试覆盖率门槛
- 问题：早期测试覆盖率低（Lines 29%），无法有效保障质量。
- 根因：缺乏测试文化，工具函数和 hooks 未覆盖。
- 方案：设置覆盖率门槛（branches 35%, functions/lines/statements 45%），分阶段提升至 80%；后续通过 TDD 流程提升至 85%+。
- 来源：
docs/test-coverage-improvement-plan.md，CLAUDE.md测试命令。
6. 代码组织
6.1 组件版本膨胀
- 问题：组件目录存在多个版本迭代（detail-v2/, detail-v3/），造成混淆和冗余。
- 根因：多次重构未清理旧版本，缺乏组件生命周期管理。
- 方案：重构完成后立即删除旧版本目录；使用
_archive/归档历史版本，并排除在 TypeScript 编译之外。 - 来源：
CLAUDE.mdArchiving Convention。
6.2 文档与代码不同步
- 问题：
docs/目录中部分文档（如组件指南、API 文档）与实际代码不一致。 - 根因：文档更新未纳入代码审查流程。
- 方案：文档变更必须与代码变更在同一 PR 中审查；
CONTEXT.md作为共享语言文档，与领域模型同步更新。 - 来源：
AGENTS.md文档同步要求。
更新记录
| 日期 | 更新内容 | 来源 |
|---|---|---|
| 2026-07-07 | 初始创建，从 project_memory.md 和 docs/ 中提取 | 现有文档 + 记忆文件 |