docs(design): 添加项目系统性整理设计方案

- 采用混合方案（方案B + 方案C） - 包含项目结构重组、代码质量优化、依赖管理、测试与性能优化、文档整理 - 明确量化指标和验收标准 - 预计执行时间 3.5 天
2026-04-12 14:20:58 +08:00
parent 2c01752017
commit 3f1b8277dd
1 changed files with 601 additions and 0 deletions
@@ -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)