# 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/ 中提取 | 现有文档 + 记忆文件 |