novalon-website/docs/superpowers/specs/2026-04-12-project-reorganization-design.md

# 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)