张翔
38be4a19ef
- 新增 hooks/components/lib 共 9 个测试文件，覆盖边界条件与异常路径 - 补充 animations.test.tsx 用例（RotatingBorder、CounterWithEffect 等） - 修复 useCountUp 结束时 toFixed 精度问题 - 调整 jest 覆盖率配置为渐进式阈值，收缩收集范围 - 新增 docs/lessons-learned.md（经验教训汇总）与 docs/troubleshooting.md（问题排查索引） - 更新 README.md 文档索引
135 lines
5.7 KiB
Markdown
135 lines
5.7 KiB
Markdown
# Lessons Learned（项目经验教训）
|
||
|
||
> 记录跨任务、跨阶段的工程经验教训，避免重复踩坑。按类别组织，定期更新。
|
||
|
||
## 目录
|
||
|
||
- [1. 技术选型与依赖](#1-技术选型与依赖)
|
||
- [2. 构建与部署](#2-构建与部署)
|
||
- [3. 样式与设计](#3-样式与设计)
|
||
- [4. 性能优化](#4-性能优化)
|
||
- [5. 测试](#5-测试)
|
||
- [6. 代码组织](#6-代码组织)
|
||
|
||
---
|
||
|
||
## 1. 技术选型与依赖
|
||
|
||
### 1.1 外部字体服务导致白屏
|
||
|
||
- **问题**：依赖 Google Fonts 等外部字体服务，网络加载失败时页面白屏。
|
||
- **根因**：字体加载阻塞首次渲染（FOUT/FOIT 未妥善处理）。
|
||
- **方案**：所有字体使用本地文件（`src/app/fonts/`），禁止外部字体 CDN。
|
||
- **来源**：`2026-03-04` 部署事故，`project_memory.md` Hard 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.md` Hard Constraints。
|
||
|
||
---
|
||
|
||
## 2. 构建与部署
|
||
|
||
### 2.1 直接复制参考网站代码
|
||
|
||
- **问题**：从参考网站直接复制 HTML/CSS/JS 到项目中，导致样式冲突和技术债务。
|
||
- **根因**：参考网站的样式体系（Bootstrap/其他框架）与项目 Tailwind 体系冲突。
|
||
- **方案**：仅参考设计理念和布局，所有代码手动基于 Tailwind 实现。
|
||
- **来源**：`project_memory.md` Lessons Learned。
|
||
|
||
### 2.2 静态导出限制
|
||
|
||
- **问题**：`output: 'export'` 模式下，`next/image` 需要 `unoptimized`，某些 API 路由不可用。
|
||
- **根因**：Next.js 静态导出对 Server Components 和 API Routes 的限制。
|
||
- **方案**：移除 `output: 'export'`，改用 `standalone` 或混合模式；图片使用 `unoptimized` 或 `<img>` 标签。
|
||
- **来源**：`CLAUDE.md` Build Output 章节。
|
||
|
||
---
|
||
|
||
## 3. 样式与设计
|
||
|
||
### 3.1 光晕效果遮挡内容
|
||
|
||
- **问题**：Case Studies 区域卡片悬停光晕（halo effect）尺寸过大，遮挡文字。
|
||
- **根因**：光晕半径 256px + 不透明度 100%，超出卡片边界。
|
||
- **方案**：尺寸降至 192px，不透明度降至 0.08（降低 92%）。
|
||
- **来源**：`project_memory.md` Lessons Learned；后续推广为全局规则：所有光晕效果不透明度降低 30-50%。
|
||
|
||
### 3.2 未使用的大文件残留
|
||
|
||
- **问题**：项目中残留 4.2MB 的 AoyagiReisho 书法字体文件，增加页面加载时间。
|
||
- **根因**：早期设计尝试引入书法字体，切换方案后未清理。
|
||
- **方案**：定期检查 `public/fonts/` 和 `src/app/fonts/` 中未使用的字体文件，及时删除。
|
||
- **来源**：`project_memory.md` Lessons 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.md` Archiving Convention。
|
||
|
||
### 6.2 文档与代码不同步
|
||
|
||
- **问题**：`docs/` 目录中部分文档（如组件指南、API 文档）与实际代码不一致。
|
||
- **根因**：文档更新未纳入代码审查流程。
|
||
- **方案**：文档变更必须与代码变更在同一 PR 中审查；`CONTEXT.md` 作为共享语言文档，与领域模型同步更新。
|
||
- **来源**：`AGENTS.md` 文档同步要求。
|
||
|
||
---
|
||
|
||
## 更新记录
|
||
|
||
| 日期 | 更新内容 | 来源 |
|
||
|------|---------|------|
|
||
| 2026-07-07 | 初始创建，从 project_memory.md 和 docs/ 中提取 | 现有文档 + 记忆文件 | |