novalon/novalon-website
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

test(core): 补充单元测试，修复 useCountUp 精度问题，新增项目文档

Browse Source 
- 新增 hooks/components/lib 共 9 个测试文件，覆盖边界条件与异常路径
- 补充 animations.test.tsx 用例（RotatingBorder、CounterWithEffect 等）
- 修复 useCountUp 结束时 toFixed 精度问题
- 调整 jest 覆盖率配置为渐进式阈值，收缩收集范围
- 新增 docs/lessons-learned.md（经验教训汇总）与 docs/troubleshooting.md（问题排查索引）
- 更新 README.md 文档索引
This commit is contained in:
张翔
2026-07-07 19:42:50 +08:00
parent 55381d7012
commit 38be4a19ef
15 changed files with 2907 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/lessons-learned.md
+135
View File
@@ -0,0 +1,135 @@
# 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/ 中提取 | 现有文档 + 记忆文件 |
docs/troubleshooting.md
+200
View File
@@ -0,0 +1,200 @@
# Troubleshooting（问题排查指南）
> 常见问题快速索引。按类别组织，每个问题指向详细的解决方案文档。
## 快速查找
| 症状 | 可能原因 | 解决方案 |
|------|---------|---------|
| 开发服务器 HMR 报错 | React 19 + Next.js 16 兼容性 | [HMR 错误解决](./HMR-ERROR-SOLUTIONS.md) |
| 构建后静态资源 404 | `webpackBuildWorker` 启用 | [禁用 webpackBuildWorker](#11-构建后静态资源-404) |
| 页面白屏 | 外部字体加载失败 | [使用本地字体](#12-页面白屏---字体加载失败) |
| 大并发下服务崩溃 | 单实例无负载均衡 | [高并发性能优化](./PERFORMANCE_OPTIMIZATION.md) |
| Google Analytics 不生效 | 未配置 GA4 ID | [GA4 配置](./GOOGLE_ANALYTICS_SETUP.md) |
| Sentry 错误上报失败 | 未配置 DSN | [监控配置](./LIGHTWEIGHT_MONITORING.md) |
| 测试覆盖率不达标 | 工具函数/hooks 未覆盖 | [测试覆盖率改进计划](./test-coverage-improvement-plan.md) |
| E2E 测试视觉回归失败 | 快照过期 | [更新快照](../CLAUDE.md#common-commands) |
| 单元测试 Jest 报错 | 配置/路径别名问题 | [测试配置](../config/test/jest.config.js) |
---
## 目录
- [1. 开发环境](#1-开发环境)
- [2. 构建与部署](#2-构建与部署)
- [3. 运行时](#3-运行时)
- [4. 测试](#4-测试)
- [5. 监控与分析](#5-监控与分析)
---
## 1. 开发环境
### 1.1 HMR 模块加载失败
**错误信息**：
```
Module factory is not available. It might have been deleted in an HMR update.
```
**原因**：React 19 与 Next.js 16 的 HMR 模块缓存机制不兼容。
**解决方案**：
1. 清除缓存：`rm -rf .next node_modules/.cache && npm run dev`
2. 禁用 `optimizeCss` 实验性功能
3. 使用修复脚本：`./scripts/fix-dev-server.sh`
4. 深度清理：`./scripts/fix-dev-server.sh --deep`
**详细文档**：[HMR 错误解决](./HMR-ERROR-SOLUTIONS.md)
---
## 2. 构建与部署
### 2.1 构建后静态资源 404
**症状**：部署后 `_next/static/` 路径下的 JS/CSS 文件返回 404。
**原因**：`next.config.ts` 中启用了 `experimental.webpackBuildWorker: true`。
**解决方案**：确保 `next.config.ts` 中该配置为 `false` 或未启用。
### 2.2 Nginx 反向代理配置
**症状**：子域名（product.novalon.cn 等）访问报错或路由失败。
**解决方案**：参考部署文档中的 Nginx 配置模板：
- [部署文档](./deployment/DEPLOYMENT.md)
- [Phase 1 部署指南](./deployment/phase1-deployment-guide.md)
- [回滚流程](./deployment/rollback-procedure.md)
### 2.3 CDN 配置问题
**症状**：CDN 域名下资源加载失败或缓存未生效。
**解决方案**：[CDN 配置指南](./CDN_CONFIGURATION.md) | [CDN 快速入门](./CDN_QUICK_START.md)
---
## 3. 运行时
### 3.1 页面白屏
**症状**：页面加载后空白，控制台无报错或字体加载失败报错。
**原因**：
1. 外部字体服务（Google Fonts）网络加载失败
2. JavaScript 运行时错误
**检查步骤**：
1. 打开浏览器开发者工具 → Network 面板 → 检查字体文件是否加载成功
2. 检查 Console 面板是否有 JS 错误
**解决方案**：
- 确保所有字体使用本地文件（`src/app/fonts/`）
- 检查 `layout.tsx` 中字体引用路径是否正确
### 3.2 图片加载失败
**症状**：页面图片显示为 broken image 图标。
**原因**：`next/image` 在静态导出模式下需要 `unoptimized` 配置。
**解决方案**：
- 在 `next.config.ts` 中设置 `images.unoptimized: true`
- 或改用 `<img>` 标签替代 `next/image`
---
## 4. 测试
### 4.1 单元测试失败
**症状**：`npm run test:unit` 或 `npx jest` 报错。
**常见原因**：
1. 路径别名未解析（`@/` 映射问题）
2. 测试文件引用了被删除/移动的模块
3. 覆盖率门槛未达到
**检查步骤**：
1. 确认 `jest.config.js` 中 `moduleNameMapper` 正确配置
2. 运行 `npx jest --testPathPattern="your-test"` 单独调试
3. 运行 `npx jest --no-coverage` 跳过覆盖率检查
**详细文档**：[测试配置](../config/test/jest.config.js) | [测试指南](./testing-guide.md)
### 4.2 E2E 测试失败
**症状**：`npm run test` 或 `npx playwright test` 报错。
**常见原因**：
1. 开发服务器未运行或端口不匹配
2. 选择器（locator）不匹配当前 DOM 结构
3. 视觉回归快照过期
**解决方案**：
- 运行 `npm run test:visual:update` 更新视觉快照
- 按标签筛选：`npx playwright test --grep "@smoke"`
**详细文档**：[Playwright 配置](../e2e/playwright.config.ts)
### 4.3 视觉回归测试
**症状**：视觉对比测试失败，截图差异过大。
**解决方案**：
- 更新基线快照：`npm run test:visual:update`
- 查看差异报告：`e2e/visual-snapshots/diff/`
- 详细标准：[视觉测试标准](./visual-testing-standards.md)
---
## 5. 监控与分析
### 5.1 Google Analytics 不生效
**症状**：GA4 数据面板无数据或实时报告为空。
**检查步骤**：
1. 确认 `.env.production` 中 `NEXT_PUBLIC_GA_ID` 已配置
2. 检查浏览器 Network 面板是否有 `analytics.google.com` 请求
3. 确认未开启 ad blocker
**详细文档**：[GA4 设置](./GOOGLE_ANALYTICS_SETUP.md)
### 5.2 Sentry 错误上报失败
**症状**：Sentry 面板无错误数据。
**检查步骤**：
1. 确认 `.env.production` 中 `SENTRY_DSN` 已配置
2. 检查 `src/lib/sentry.ts` 初始化代码
3. 确认 Sentry 项目 DSN 与代码一致
**详细文档**：[Sentry 设置](./sentry-setup-guide.md) | [Lighthouse CI 指南](./lighthouse-ci-guide.md)
---
## 参考文档索引
| 文档 | 内容 |
|------|------|
| [HMR 错误解决](./HMR-ERROR-SOLUTIONS.md) | HMR 模块加载失败的所有解决方案 |
| [高并发性能优化](./PERFORMANCE_OPTIMIZATION.md) | 性能瓶颈分析和优化方案 |
| [CDN 配置](./CDN_CONFIGURATION.md) | CDN 部署和缓存配置 |
| [监控配置](./LIGHTWEIGHT_MONITORING.md) | Sentry + UptimeRobot + GA4 配置 |
| [部署文档](./deployment/DEPLOYMENT.md) | 完整部署流程和 Nginx 配置 |
| [回滚流程](./deployment/rollback-procedure.md) | 生产环境回滚操作步骤 |
| [测试覆盖率改进计划](./test-coverage-improvement-plan.md) | 测试覆盖率提升策略 |
| [分层测试优化指南](./test-optimization-guide.md) | 测试分层和执行效率优化 |
| [视觉测试标准](./visual-testing-standards.md) | 视觉回归测试规范 |
---
## 更新记录
| 日期 | 更新内容 |
|------|---------|
| 2026-07-07 | 初始创建，整合现有分散的故障排查文档 |