diff --git a/docs/superpowers/specs/2026-04-12-project-reorganization-design.md b/docs/superpowers/specs/2026-04-12-project-reorganization-design.md new file mode 100644 index 0000000..ad8398b --- /dev/null +++ b/docs/superpowers/specs/2026-04-12-project-reorganization-design.md @@ -0,0 +1,601 @@ +# Novalon Website 项目系统性整理设计方案 + +**设计日期：** 2026-04-12 +**设计人员：** 张翔 +**整理方案：** 混合方案（方案 B + 方案 C） + +--- + +## 一、需求背景与目标 + +### 1.1 需求概述 + +对 Novalon Website 项目进行系统性整理，包括： +- 优化项目目录结构，确保文件分类清晰合理 +- 整理代码文件，删除冗余代码、注释和未使用资源 +- 统一代码风格和格式，确保符合项目编码规范 +- 更新依赖包至稳定版本并解决版本冲突 +- 整理项目文档，包括 README、API 文档和开发指南 +- 检查并修复潜在的代码质量问题和安全隐患 +- 建立或完善项目构建、测试和部署流程 + +### 1.2 整理策略 + +采用 **混合方案（方案 B + 方案 C）**： +- **方案 B（人工深度处理）**：项目结构重组、console.log 清理、TODO/FIXME 处理、测试用例补充、文档价值判断 +- **方案 C（自动化工具）**：代码格式化、依赖安全修复、简单重构、文档生成、性能检查 + +### 1.3 成功标准 + +| 指标类别 | 具体指标 | 目标值 | +|----------|----------|--------| +| **代码质量** | ESLint 错误 | 0 | +| | TypeScript 错误 | 0 | +| | console.log（生产代码） | 0 | +| | TODO/FIXME | 0 | +| **测试覆盖率** | Lines | ≥ 70% | +| | Functions | ≥ 65% | +| | Branches | ≥ 60% | +| | Statements | ≥ 70% | +| **安全性** | 高危漏洞 | 0 | +| | 中危漏洞 | 0 | +| | 低危漏洞 | ≤ 2 | +| **性能** | Lighthouse 性能评分 | ≥ 90 | +| | Lighthouse 可访问性评分 | ≥ 95 | +| | Lighthouse 最佳实践评分 | ≥ 95 | +| | Lighthouse SEO 评分 | ≥ 95 | +| **项目结构** | 根目录脚本文件 | ≤ 5 | + +--- + +## 二、项目现状分析 + +### 2.1 项目概况 + +**项目名称：** Novalon Website +**项目类型：** 企业官网 +**技术栈：** Next.js 16 + React 19 + TypeScript 5 + Tailwind CSS 4 + +### 2.2 当前问题 + +| 维度 | 现状 | 问题等级 | +|------|------|----------| +| 根目录脚本文件 | 36 个脚本文件散落在根目录 | 🔴 高 | +| 文档数量 | 74 个 Markdown 文档 | 🟡 中 | +| 安全漏洞 | 存在 moderate 和 low 级别漏洞 | 🟡 中 | +| 测试覆盖率 | Lines 54%, Functions 48%, Branches 41% | 🟡 中 | +| 代码质量 | 72 处 console.log，9 个 TODO/FIXME | 🟡 中 | +| 依赖更新 | 多个依赖需要更新（含主版本升级） | 🟡 中 | + +### 2.3 测试覆盖率详情 + +**当前覆盖率：** +- Lines: 54.07% +- Functions: 48.63% +- Branches: 41.54% +- Statements: 53.03% + +**覆盖率较低的文件：** +- API 路由：部分文件覆盖率 0% +- 管理后台：部分页面覆盖率 < 35% +- 效果组件：覆盖率 0%（可接受，视觉效果组件） + +--- + +## 三、整理方案设计 + +### 3.1 执行阶段划分 + +**阶段一：自动化预处理（方案 C）** - 0.5 天 +- 代码格式化统一 +- 安全漏洞自动修复 +- 简单代码问题自动修复 + +**阶段二：项目结构重组（方案 B）** - 0.5 天 +- 脚本文件分类整理 +- 文档结构优化 +- 配置文件统一管理 + +**阶段三：代码质量深度优化（方案 B）** - 1 天 +- console.log 清理与日志规范化 +- TODO/FIXME 处理 +- 代码逻辑优化 + +**阶段四：依赖管理与测试（混合）** - 1 天 +- 依赖更新评估与执行 +- 测试覆盖率提升 +- 性能优化 + +**阶段五：文档与验收（方案 B）** - 0.5 天 +- 文档更新与整理 +- 全面回归测试 +- 验收报告生成 + +**总计：3.5 天** + +--- + +## 四、项目结构重组设计 + +### 4.1 目标结构 + +``` +novalon-website/ +├── .github/ # GitHub 配置 +├── .husky/ # Git hooks +├── .trae/ # Trae AI 配置 +├── config/ # 配置文件集中管理 +│ ├── ci/ # CI/CD 配置 +│ ├── lint/ # Lint 配置 +│ └── test/ # 测试配置 +├── docs/ # 文档集中管理 +│ ├── architecture/ # 架构文档 +│ ├── deployment/ # 部署文档 +│ ├── development/ # 开发文档 +│ ├── guides/ # 指南文档 +│ ├── plans/ # 计划文档 +│ ├── security/ # 安全文档 +│ ├── superpowers/ # Superpowers 相关 +│ ├── testing/ # 测试文档 +│ ├── troubleshooting/ # 故障排查 +│ ├── archive/ # 归档文档（新增） +│ └── README.md # 文档索引（新增） +├── drizzle/ # Drizzle ORM 迁移 +├── e2e/ # E2E 测试 +├── public/ # 静态资源 +├── scripts/ # 脚本集中管理（重组） +│ ├── deployment/ # 部署脚本 +│ ├── monitoring/ # 监控脚本 +│ ├── optimization/ # 优化脚本 +│ ├── security/ # 安全脚本 +│ ├── maintenance/ # 维护脚本（新增分类） +│ ├── diagnosis/ # 诊断脚本（新增分类） +│ ├── tools/ # 工具脚本（新增分类） +│ └── README.md # 脚本使用说明（新增） +├── src/ # 源代码 +├── docker/ # Docker 相关（新增目录） +│ ├── Dockerfile +│ ├── Dockerfile.prod +│ ├── Dockerfile.tools +│ ├── docker-compose.yml +│ ├── docker-compose.prod.yml +│ └── nginx/ # Nginx 配置 +├── .env.example +├── .gitignore +├── package.json +├── package-lock.json +├── tsconfig.json +├── next.config.ts +└── README.md # 项目主 README +``` + +### 4.2 文件迁移计划 + +**脚本文件迁移：** + +| 当前位置 | 目标位置 | 分类 | +|----------|----------|------| +| `deploy.sh`, `deploy-production.sh`, `deploy-cdn.sh`, `refresh-cdn.sh` | `scripts/deployment/` | 部署 | +| `monitor-pipeline*.sh`, `cicd-monitor.sh`, `container-monitor.sh` | `scripts/monitoring/` | 监控 | +| `diagnose-*.sh`, `production-diagnosis.sh`, `network-diagnosis.sh` | `scripts/diagnosis/` | 诊断 | +| `security-*.sh` | `scripts/security/` | 安全 | +| `*-cleanup.sh`, `auto-cleanup.sh` | `scripts/maintenance/` | 维护 | +| `optimize-font.py`, `analyze-test-coverage.ts` | `scripts/tools/` | 工具 | + +**Docker 文件迁移：** + +| 当前位置 | 目标位置 | +|----------|----------| +| `Dockerfile`, `Dockerfile.prod`, `Dockerfile.tools` | `docker/` | +| `docker-compose.yml`, `docker-compose.prod.yml` | `docker/` | +| `nginx-woodpecker.conf`, `nginx-woodpecker-fixed.conf` | `docker/nginx/` | + +**文档归档：** + +| 文档类型 | 处理方式 | +|----------|----------| +| 过时的计划文档（2026-03-*） | 移至 `docs/archive/` | +| 重复的文档（MONITORING_*.md, PRODUCTION_*.md） | 合并 | +| 根目录的 .md 文件 | 移至 `docs/` 对应目录 | + +--- + +## 五、代码质量优化设计 + +### 5.1 console.log 清理策略 + +**清理原则：** + +| 文件类型 | console.log 用途 | 处理方式 | +|----------|------------------|----------| +| API 路由 | 调试、错误日志 | 保留错误日志，改用 `logger.error()`，删除调试日志 | +| 页面组件 | 调试信息 | 全部删除 | +| 客户端组件 | 调试信息 | 全部删除 | +| 管理后台 | 操作日志 | 改用统一的日志服务 | +| 测试文件 | 测试输出 | 保留（测试需要） | +| 种子数据 | 进度信息 | 保留（开发工具） | + +**日志规范化方案：** + +创建统一的日志工具 `src/lib/logger.ts`： + +```typescript +type LogLevel = 'debug' | 'info' | 'warn' | 'error'; + +class Logger { + private isDevelopment = process.env.NODE_ENV === 'development'; + + debug(message: string, ...args: unknown[]) { + if (this.isDevelopment) { + console.debug(`[DEBUG] ${message}`, ...args); + } + } + + info(message: string, ...args: unknown[]) { + console.info(`[INFO] ${message}`, ...args); + } + + warn(message: string, ...args: unknown[]) { + console.warn(`[WARN] ${message}`, ...args); + } + + error(message: string, error?: Error, ...args: unknown[]) { + console.error(`[ERROR] ${message}`, error, ...args); + } +} + +export const logger = new Logger(); +``` + +### 5.2 TODO/FIXME 处理策略 + +**处理流程：** + +1. 扫描所有 TODO/FIXME/HACK 注释 +2. 分类评估： + - 紧急：立即实现或修复 + - 重要：立即实现 + - 一般：评估后决定 + - 过时：直接删除注释 +3. 执行处理：实现/修复或删除 +4. 验证：确保所有 TODO/FIXME 已处理 + +**处理原则：** 立即实现（用户选择） + +### 5.3 代码风格统一（自动化） + +**Prettier 配置：** + +```json +{ + "semi": true, + "trailingComma": "es5", + "singleQuote": true, + "printWidth": 100, + "tabWidth": 2, + "useTabs": false, + "arrowParens": "always", + "endOfLine": "lf" +} +``` + +**ESLint 规则强化：** + +```json +{ + "rules": { + "no-console": ["error", { "allow": ["warn", "error"] }], + "prefer-const": "error", + "no-var": "error", + "@typescript-eslint/no-unused-vars": ["error", { + "argsIgnorePattern": "^_", + "varsIgnorePattern": "^_" + }] + } +} +``` + +### 5.4 代码质量指标 + +| 指标 | 当前值 | 目标值 | +|------|--------|--------| +| ESLint 错误 | 未知 | 0 | +| ESLint 警告 | 未知 | ≤ 10 | +| TypeScript 错误 | 未知 | 0 | +| console.log | 72 | 0（生产代码） | +| TODO/FIXME | 9 | 0 | + +--- + +## 六、依赖管理与安全加固设计 + +### 6.1 依赖更新评估 + +**更新策略：** + +``` +Patch 更新（x.x.PATCH）→ ✅ 直接更新 +Minor 更新（x.MINOR.x）→ ✅ 评估后更新 +Major 更新（MAJOR.x.x）→ ❌ 暂不更新，单独计划 +``` + +**重点依赖评估：** + +| 依赖包 | 当前版本 | 最新版本 | 更新类型 | 建议 | +|--------|----------|----------|----------|------| +| @playwright/test | 1.58.2 | 1.59.1 | Minor | ✅ 更新 | +| @sentry/nextjs | 10.46.0 | 10.48.0 | Minor | ✅ 更新 | +| @tiptap/* | 3.20.5 | 3.22.3 | Minor | ✅ 更新 | +| drizzle-orm | 0.45.1 | 0.45.2 | Patch | ✅ 更新 | +| eslint | 8.57.1 | 10.2.0 | Major | ❌ 暂不更新 | +| @types/node | 20.19.37 | 25.6.0 | Major | ❌ 暂不更新 | + +### 6.2 安全漏洞修复 + +**当前漏洞：** + +| 漏洞来源 | 严重程度 | 修复方案 | +|----------|----------|----------| +| @esbuild-kit/core-utils | Moderate | 更新 drizzle-kit | +| @lhci/cli | Low | 更新 @lhci/cli | + +**修复流程：** + +```bash +# 自动修复 +npm audit fix + +# 手动修复（如需要） +npm update drizzle-kit @lhci/cli + +# 验证 +npm audit +``` + +### 6.3 依赖管理指标 + +| 指标 | 当前值 | 目标值 | +|------|--------|--------| +| 高危漏洞 | 0 | 0 | +| 中危漏洞 | 2 | 0 | +| 低危漏洞 | 存在 | ≤ 2 | +| 过时依赖 | ~10 | ≤ 5（非 Major） | + +--- + +## 七、测试与性能优化设计 + +### 7.1 测试覆盖率提升策略 + +**重点改进文件（覆盖率 < 30%）：** + +**优先级 1（API 路由）：** +- src/app/api/admin/security/route.ts (0%) +- src/app/api/config/route.ts (0%) +- src/app/api/content/route.ts (0%) +- src/app/api/docs/route.ts (0%) +- src/app/api/v1/config/route.ts (0%) + +**优先级 2（管理后台）：** +- src/app/admin/settings/page.tsx (31%) +- src/app/admin/users/page.tsx (30%) +- src/app/admin/content/[id]/page.tsx (32%) + +**优先级 3（页面组件）：** +- src/app/(marketing)/services/[id]/client.tsx (0%) +- src/app/(marketing)/solutions/page.tsx (0%) +- src/app/(marketing)/contact/actions.ts (0%) + +**测试补充策略：** + +1. **API 路由测试**：补充关键路径测试 +2. **页面组件测试**：补充用户交互测试 +3. **Server Actions 测试**：补充表单提交测试 + +### 7.2 性能优化策略 + +**构建性能优化：** +- 并行构建、缓存优化 +- Tree shaking、代码分割 + +**运行时性能优化：** +- 图片优化（AVIF、WebP） +- 懒加载、预加载 +- 包大小优化 + +**Lighthouse CI 配置：** + +```json +{ + "ci": { + "assert": { + "assertions": { + "categories:performance": ["error", { "minScore": 0.9 }], + "categories:accessibility": ["error", { "minScore": 0.95 }], + "categories:best-practices": ["error", { "minScore": 0.95 }], + "categories:seo": ["error", { "minScore": 0.95 }] + } + } + } +} +``` + +### 7.3 测试与性能指标 + +**测试覆盖率目标：** + +| 指标 | 当前值 | 目标值 | 提升幅度 | +|------|--------|--------|----------| +| Lines | 54.07% | 70% | +15.93% | +| Functions | 48.63% | 65% | +16.37% | +| Branches | 41.54% | 60% | +18.46% | +| Statements | 53.03% | 70% | +16.97% | + +**性能指标目标：** + +| 指标 | 目标值 | +|------|--------| +| Lighthouse 性能评分 | ≥ 90 | +| Lighthouse 可访问性评分 | ≥ 95 | +| Lighthouse 最佳实践评分 | ≥ 95 | +| Lighthouse SEO 评分 | ≥ 95 | +| 首次内容绘制 (FCP) | < 1.5s | +| 最大内容绘制 (LCP) | < 2.5s | +| 累积布局偏移 (CLS) | < 0.1 | +| 首次输入延迟 (FID) | < 100ms | + +--- + +## 八、文档与验收设计 + +### 8.1 文档体系整理 + +**文档整理流程：** + +1. 文档审计：扫描所有文档，标记状态（有效/过时/废弃） +2. 文档分类：架构/部署/开发/测试/安全/归档 +3. 文档优化：合并重复、更新过时、删除废弃 +4. 文档索引：创建 docs/README.md 作为主索引 + +**文档更新清单：** + +| 文档 | 状态 | 操作 | +|------|------|------| +| README.md | 有效 | 更新项目结构说明 | +| docs/architecture/system-design.md | 有效 | 保持 | +| docs/deployment/DEPLOYMENT.md | 有效 | 更新部署流程 | +| docs/plans/2026-03-*.md | 过时 | 移至 archive/ | +| docs/MONITORING_*.md | 重复 | 合并为一个文档 | + +### 8.2 验收标准 + +**验收清单：** + +1. **项目结构** ✅ + - 根目录脚本文件已分类整理 + - Docker 相关文件已移至 docker/ 目录 + - 文档已分类整理，建立索引 + +2. **代码质量** ✅ + - 所有 console.log 已清理 + - 所有 TODO/FIXME 已处理 + - ESLint 无错误 + - TypeScript 无类型错误 + +3. **依赖管理** ✅ + - 安全漏洞已修复 + - Patch 和 Minor 版本已更新 + +4. **测试覆盖** ✅ + - Lines 覆盖率 ≥ 70% + - Functions 覆盖率 ≥ 65% + - Branches 覆盖率 ≥ 60% + - Statements 覆盖率 ≥ 70% + +5. **性能优化** ✅ + - Lighthouse 性能评分 ≥ 90 + - Lighthouse 可访问性评分 ≥ 95 + - Lighthouse 最佳实践评分 ≥ 95 + - Lighthouse SEO 评分 ≥ 95 + +6. **文档完善** ✅ + - README.md 已更新 + - 文档索引已建立 + - 过时文档已归档 + +### 8.3 验收流程 + +**阶段一：自动化验证** +- npm run lint +- npm run type-check +- npm run test:coverage +- npm run build +- npm audit + +**阶段二：手动验证** +- 检查项目结构 +- 检查文档完整性 +- 检查代码质量 +- 检查性能指标 + +**阶段三：功能验证** +- 启动开发服务器 +- 运行 E2E 测试 +- 检查关键功能 +- 检查部署流程 + +**阶段四：生成报告** +- 测试覆盖率报告 +- Lighthouse 报告 +- 安全审计报告 +- 整理总结报告 + +--- + +## 九、风险评估与应对 + +### 9.1 风险识别 + +| 风险类型 | 风险描述 | 风险等级 | 应对措施 | +|----------|----------|----------|----------| +| 代码破坏 | 文件迁移导致引用路径错误 | 中 | 逐个验证引用路径，运行测试 | +| 功能回归 | 代码清理导致功能异常 | 中 | 边改边测，保留回滚点 | +| 依赖冲突 | 依赖更新导致兼容性问题 | 中 | 逐个更新，充分测试 | +| 测试失败 | 新增测试用例失败 | 低 | 修复代码或调整测试 | + +### 9.2 回滚策略 + +1. **Git 分支策略**：在专门的整理分支上工作 +2. **分阶段提交**：每个阶段完成后提交，便于回滚 +3. **备份关键文件**：修改前备份关键配置文件 +4. **测试验证**：每个阶段完成后运行完整测试 + +--- + +## 十、后续建议 + +### 10.1 短期优化（1-2 周） + +1. 监控整理后的项目运行状态 +2. 收集团队反馈，优化工作流程 +3. 补充遗漏的测试用例 +4. 完善文档细节 + +### 10.2 中期优化（1-3 月） + +1. 评估 Major 版本依赖更新的可行性 +2. 引入更严格的代码质量门禁 +3. 优化 CI/CD 流程 +4. 提升测试覆盖率至 80%+ + +### 10.3 长期优化（3-6 月） + +1. 建立持续的技术债务管理机制 +2. 定期进行代码审查和重构 +3. 引入更多自动化工具 +4. 建立知识库和最佳实践文档 + +--- + +## 附录 + +### A. 相关文档 + +- [项目 README](../../README.md) +- [测试指南](../testing/testing-guide.md) +- [部署指南](../deployment/DEPLOYMENT.md) + +### B. 工具清单 + +- ESLint - 代码质量检查 +- Prettier - 代码格式化 +- Jest - 单元测试 +- Playwright - E2E 测试 +- Lighthouse CI - 性能监控 +- npm audit - 安全审计 + +### C. 参考资料 + +- [Next.js 官方文档](https://nextjs.org/docs) +- [React 测试最佳实践](https://testing-library.com/docs/react-testing-library/intro/) +- [TypeScript 最佳实践](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html)