novalon-website/docs/superpowers/plans/2026-04-12-project-reorganization-plan.md

# Novalon Website 项目系统性整理实施计划

**创建日期：** 2026-04-12  
**基于设计：** [2026-04-12-project-reorganization-design.md](../specs/2026-04-12-project-reorganization-design.md)  
**执行方式：** 内联执行（使用 executing-plans 技能）

---

## 执行概览

**总预估时间：** 3.5 天  
**执行策略：** 混合方案（方案 B + 方案 C）  
**验收标准：** 参见设计文档第 1.3 节

---

## 阶段一：自动化预处理（方案 C）

**预估时间：** 0.5 天  
**执行方式：** 自动化工具 + 人工验证

### 任务 1.1：代码格式化统一

**文件**: 
- 创建: `.prettierrc`
- 修改: `config/lint/.eslintrc.json`

**职责**: 统一代码风格和格式

**测试**: 运行 `npm run lint` 验证无错误

**步骤**:
1. 创建 `.prettierrc` 配置文件
   ```json
   {
     "semi": true,
     "trailingComma": "es5",
     "singleQuote": true,
     "printWidth": 100,
     "tabWidth": 2,
     "useTabs": false,
     "arrowParens": "always",
     "endOfLine": "lf"
   }
   ```
2. 更新 `config/lint/.eslintrc.json` 强化规则
3. 运行 `npm run lint -- --fix` 自动修复代码格式
4. 运行 `npm run lint` 验证无错误

---

### 任务 1.2：安全漏洞自动修复

**文件**: `package.json`, `package-lock.json`

**职责**: 修复安全漏洞

**测试**: 运行 `npm audit` 验证无漏洞

**步骤**:
1. 运行 `npm audit fix` 自动修复安全漏洞
2. 如自动修复失败，手动更新依赖：
   ```bash
   npm update drizzle-kit @lhci/cli
   ```
3. 运行 `npm audit` 验证漏洞已修复
4. 运行 `npm test` 验证功能正常

---

### 任务 1.3：简单代码问题自动修复

**文件**: 多个源代码文件

**职责**: 自动修复简单的代码问题

**测试**: 运行 `npm run lint` 和 `npm run type-check` 验证

**步骤**:
1. 运行 `npm run lint -- --fix` 自动修复代码问题
2. 运行 `npm run type-check` 验证无类型错误
3. 运行 `npm test` 验证功能正常

---

## 阶段二:项目结构重组（方案 B）

**预估时间:** 0.5 天  
**执行方式:** 人工处理 + 测试验证

### 任务 2.1:脚本文件分类整理

**文件**: 
- 创建: `scripts/deployment/`, `scripts/monitoring/`, `scripts/diagnosis/`, `scripts/security/`, `scripts/maintenance/`, `scripts/tools/`, `scripts/README.md`
- 移动: 根目录的 36 个脚本文件

**职责**: 将根目录的 36 个脚本文件分类整理

**测试**: 
1. 检查 `package.json` 中的脚本路径是否已更新
2. 运行 `npm run build` 验证构建成功
3. 检查根目录脚本文件数量 ≤ 5

**步骤**:
1. 创建 `scripts/` 子目录结构
   ```bash
   mkdir -p scripts/deployment
   mkdir -p scripts/monitoring
   mkdir -p scripts/diagnosis
   mkdir -p scripts/security
   mkdir -p scripts/maintenance
   mkdir -p scripts/tools
   ```
2. 移动部署脚本
   ```bash
   mv deploy.sh scripts/deployment/
   mv deploy-production.sh scripts/deployment/
   mv deploy-cdn.sh scripts/deployment/
   mv refresh-cdn.sh scripts/deployment/
   mv deploy-subdomain-ssl.sh scripts/deployment/
   mv deploy-wildcard-domain.sh scripts/deployment/
   ```
3. 移动监控脚本
   ```bash
   mv monitor-pipeline.sh scripts/monitoring/
   mv monitor-pipeline-32.sh scripts/monitoring/
   mv monitor-pipeline-continuous.sh scripts/monitoring/
   mv cicd-monitor.sh scripts/monitoring/
   mv container-monitor.sh scripts/monitoring/
   ```
4. 移动诊断脚本
   ```bash
   mv diagnose-docker-ci.sh scripts/diagnosis/
   mv diagnose-cicd-issues.sh scripts/diagnosis/
   mv diagnose-webhook-detail.sh scripts/diagnosis/
   mv diagnose-woodpecker.py scripts/diagnosis/
   mv diagnose-auto-trigger.py scripts/diagnosis/
   mv production-diagnosis.sh scripts/diagnosis/
   mv remote-server-diagnosis.sh scripts/diagnosis/
   mv network-diagnosis.sh scripts/diagnosis/
   ```
5. 移动安全脚本
   ```bash
   mv security-audit.sh scripts/security/
   mv security-hardening.sh scripts/security/
   mv security-verification.sh scripts/security/
   ```
6. 移动维护脚本
   ```bash
   mv auto-cleanup.sh scripts/maintenance/
   mv disk-cleanup-immediate.sh scripts/maintenance/
   mv disk-optimization-long-term.sh scripts/maintenance/
   mv git-cleanup.sh scripts/maintenance/
   mv git-filter-repo-cleanup.sh scripts/maintenance/
   mv production-docker-cleanup.sh scripts/maintenance/
   mv docker-cleanup.sh scripts/maintenance/
   ```
7. 移动工具脚本
   ```bash
   mv optimize-font.py scripts/tools/
   mv analyze-test-coverage.ts scripts/tools/
   mv capture-webhook.sh scripts/tools/
   mv check-job-triggers.groovy scripts/tools/
   mv check-woodpecker-logs.sh scripts/tools/
   mv notify-wechat.sh scripts/tools/
   mv set-woodpecker-trusted.sh scripts/tools/
   mv setup-gitea-oauth2.sh scripts/tools/
   mv setup-gitea-oauth2-auto.sh scripts/tools/
   mv fix-service-restart.sh scripts/tools/
   mv fix-jenkins-nginx.sh scripts/tools/
   ```
8. 更新 `package.json` 中的脚本路径引用
9. 创建 `scripts/README.md` 说明脚本用途
10. 运行测试验证路径正确

---

### 任务 2.2:Docker 文件整理

**文件**: 
- 创建: `docker/`, `docker/nginx/`
- 移动: Docker 相关文件

**职责**: 整理 Docker 配置文件

**测试**: 
1. 运行 `docker build -f docker/Dockerfile .` 验证构建成功
2. 检查 CI/CD 配置文件中的 Docker 路径引用是否已更新

**步骤**:
1. 创建 `docker/` 目录
   ```bash
   mkdir -p docker/nginx
   ```
2. 移动 Dockerfile 文件
   ```bash
   mv Dockerfile docker/
   mv Dockerfile.prod docker/
   mv Dockerfile.tools docker/
   ```
3. 移动 docker-compose 文件
   ```bash
   mv docker-compose.yml docker/
   mv docker-compose.prod.yml docker/
   mv docker-compose.high-perf.yml docker/
   mv docker-compose.server.yml docker/
   ```
4. 移动 nginx 配置
   ```bash
   mv nginx-woodpecker.conf docker/nginx/
   mv nginx-woodpecker-fixed.conf docker/nginx/
   ```
5. 更新 CI/CD 配置中的 Docker 文件路径引用
   - 检查 `.woodpecker-test.yml` 中的 Docker 路径
   - 检查 `Jenkinsfile` 中的 Docker 路径
   - 检查 `config/ci/*.yml` 中的 Docker 路径
6. 运行 `docker build -f docker/Dockerfile .` 验证构建正常

---

### 任务 2.3:文档结构优化

**文件**: 
- 创建: `docs/archive/`, `docs/README.md`
- 移动: 过时文档
- 合并: 重复文档

**职责**: 优化文档结构,建立索引

**测试**: 
1. 使用 `markdown-link-check` 工具验证所有 Markdown 文件中的链接
2. 检查 `docs/README.md` 文档索引是否完整

**步骤**:
1. 创建 `docs/archive/` 目录
   ```bash
   mkdir -p docs/archive
   ```
2. 移动过时计划文档
   ```bash
   mv docs/plans/2026-03-*.md docs/archive/
   ```
3. 合并重复文档
   - 合并 `docs/MONITORING_SETUP.md`, `docs/MONITORING_QUICKSTART.md`, `docs/MONITORING_LIGHTWEIGHT.md`, `docs/LIGHTWEIGHT_MONITORING.md` 为 `docs/guides/monitoring.md`
   - 合并 `docs/PRODUCTION_DEPLOYMENT.md`, `docs/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md` 为 `docs/deployment/production-deployment.md`
4. 创建 `docs/README.md` 文档索引
5. 验证所有文档链接有效

---

### 任务 2.4:配置文件统一管理

**文件**: 检查 `config/` 目录

**职责**: 确保配置文件集中管理

**测试**: 
1. 运行 `npm run build` 验证配置加载正确
2. 检查 `config/` 目录结构是否完整

**步骤**:
1. 检查 `config/` 目录结构
2. 确保所有配置文件都在 `config/` 目录下
3. 验证配置文件加载正确

---

## 阶段三:代码质量深度优化（方案 B）

**预估时间:** 1 天  
**执行方式:** 人工处理 + 测试验证

### 任务 3.1:创建统一日志工具

**文件**: 
- 创建: `src/lib/logger.ts`
- 创建: `src/lib/logger.test.ts`

**职责**: 提供统一的日志管理工具

**测试**: `src/lib/logger.test.ts`

**步骤**:
1. 创建 `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();
   ```
2. 编写单元测试验证日志功能
3. 运行测试确保通过

---

### 任务 3.2:console.log 清理

**文件**: 修改所有包含 console.log 的生产代码文件

**职责**: 清理 72 处 console.log,改用统一日志工具

**测试**: 运行测试验证功能正常

**步骤**:
1. 扫描所有 console.log 出现的位置
   ```bash
   grep -r "console\.(log|debug|warn|error)" src/ --include="*.ts,*.tsx" --exclude="*.test.*"
   ```
2. 分类标记：
   - 调试日志（删除）
   - 错误日志（改用 logger.error）
   - 信息日志（评估）
3. 批量处理生产代码中的 console.log
   - API 路由：改用 logger.error
   - 页面组件：删除
   - 客户端组件：删除
   - 管理后台：改用 logger.info
4. 保留测试文件和种子数据文件中的 console.log
5. 运行测试验证功能正常

---

### 任务 3.3:TODO/FIXME 处理

**文件**: 修改包含 TODO/FIXME 的文件

**职责**: 处理 9 个 TODO/FIXME 注释

**测试**: 运行测试验证功能正常

**步骤**:
1. 扫描所有 TODO/FIXME 出现的位置
   ```bash
   grep -r "TODO|FIXME|HACK|XXX" src/ --include="*.ts,*.tsx"
   ```
2. 评估每个 TODO/FIXME 的优先级
3. 实现或修复相关功能
4. 删除已处理的 TODO/FIXME 注释
5. 运行测试验证功能正常

---

### 任务 3.4:代码逻辑优化

**文件**: 优化代码结构和逻辑

**职责**: 提升代码可读性和可维护性

**测试**: 运行测试验证功能正常

**步骤**:
1. 识别需要优化的代码模块
2. 重构代码结构
3. 优化代码逻辑
4. 运行测试验证功能正常

---

## 阶段四:依赖管理与测试（混合）

**预估时间:** 1 天  
**执行方式:** 自动化 + 人工评估 + 测试验证

### 任务 4.1:依赖更新评估

**文件**: `package.json`, `package-lock.json`

**职责**: 评估并更新依赖包

**测试**: 运行测试验证兼容性

**步骤**:
1. 运行 `npm outdated` 查看过时依赖
2. 评估每个依赖的更新影响
3. 更新 Patch 和 Minor 版本依赖
   ```bash
   npm update @playwright/test
   npm update @sentry/nextjs
   npm update @tiptap/extension-image @tiptap/extension-link @tiptap/pm @tiptap/react @tiptap/starter-kit
   npm update drizzle-orm
   npm update @typescript-eslint/eslint-plugin @typescript-eslint/parser
   ```
4. 运行测试验证兼容性

---

### 任务 4.2:API 路由测试补充

**文件**: 创建测试文件

**职责**: 补充 API 路由测试用例

**测试**: 运行测试验证覆盖率提升

**步骤**:
1. 为 `src/app/api/admin/security/route.ts` 创建测试文件
2. 为 `src/app/api/config/route.ts` 创建测试文件
3. 为 `src/app/api/content/route.ts` 创建测试文件
4. 为 `src/app/api/docs/route.ts` 创建测试文件
5. 为 `src/app/api/v1/config/route.ts` 创建测试文件
6. 编写关键路径测试用例
7. 运行测试验证覆盖率提升

---

### 任务 4.3:管理后台测试补充

**文件**: 创建/更新测试文件

**职责**: 补充管理后台测试用例

**测试**: 运行测试验证覆盖率提升

**步骤**:
1. 为 `src/app/admin/settings/page.tsx` 补充测试用例
2. 为 `src/app/admin/users/page.tsx` 补充测试用例
3. 为 `src/app/admin/content/[id]/page.tsx` 补充测试用例
4. 编写用户交互测试用例
5. 运行测试验证覆盖率提升

---

### 任务 4.4:页面组件测试补充

**文件**: 创建测试文件

**职责**: 补充页面组件测试用例

**测试**: 运行测试验证覆盖率提升

**步骤**:
1. 为 `src/app/(marketing)/services/[id]/client.tsx` 创建测试文件
2. 为 `src/app/(marketing)/solutions/page.tsx` 创建测试文件
3. 为 `src/app/(marketing)/contact/actions.ts` 创建测试文件
4. 编写用户交互测试用例
5. 运行测试验证覆盖率提升

---

### 任务 4.5:性能优化

**文件**: 
- 修改: `next.config.ts`
- 修改: `config/test/lighthouserc.json`

**职责**: 优化构建和运行时性能

**测试**: 运行 Lighthouse CI 验证性能指标

**步骤**:
1. 优化 `next.config.ts` 配置
   ```typescript
   const nextConfig = {
     experimental: {
       optimizePackageImports: ['lucide-react', 'framer-motion'],
     },
     images: {
       formats: ['image/avif', 'image/webp'],
       deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
       imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
     },
     compress: true,
     poweredByHeader: false,
     productionBrowserSourceMaps: false,
   };
   ```
2. 配置 Lighthouse CI
3. 运行 Lighthouse CI 验证性能指标

---

## 阶段五:文档与验收（方案 B）

**预估时间:** 0.5 天  
**执行方式:** 人工处理 + 自动化验证

### 任务 5.1:README 更新

**文件**: `README.md`

**职责**: 更新项目主 README 文档

**测试**: 验证文档内容准确

**步骤**:
1. 更新项目结构说明
2. 更新技术栈版本信息
3. 更新质量保障章节
4. 更新文档导航链接
5. 验证文档内容准确

---

### 任务 5.2:文档索引创建

**文件**: `docs/README.md`

**职责**: 创建文档中心索引

**测试**: 验证文档链接有效

**步骤**:
1. 创建文档索引结构
2. 添加快速导航链接
3. 分类整理文档链接
4. 验证所有链接有效

---

### 任务 5.3:全面回归测试

**文件**: 运行所有测试

**职责**: 确保所有功能正常

**测试**: 运行完整测试套件

**步骤**:
1. 运行 `npm run lint` 验证代码质量
2. 运行 `npm run type-check` 验证类型正确
3. 运行 `npm run test:coverage` 验证测试覆盖率
4. 运行 `npm run build` 验证构建成功
5. 运行 `npm audit` 验证安全性
6. 运行 `npm run test:e2e` 验证 E2E 测试

---

### 任务 5.4:验收报告生成

**文件**: `docs/superpowers/reports/2026-04-12-project-reorganization-report.md`

**职责**: 生成整理总结报告

**测试**: 验证报告内容完整

**步骤**:
1. 收集测试覆盖率报告
2. 收集 Lighthouse 报告
3. 收集安全审计报告
4. 生成整理总结报告
5. 验证报告内容完整

---

## 验收标准

### 代码质量
- [ ] 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
- [ ] 文档索引已建立
- [ ] 配置文件集中管理

---

## 风险应对

### 风险 1:文件迁移导致引用路径错误
- **应对**: 逐个验证引用路径，运行测试
- **回滚**: Git 分支策略，每个阶段完成后提交

### 风险 2:代码清理导致功能异常
- **应对**: 边改边测，保留回滚点
- **回滚**: 分阶段提交，便于回滚

### 风险 3:依赖更新导致兼容性问题
- **应对**: 逐个更新，充分测试
- **回滚**: 保留 package-lock.json 备份

### 风险 4:测试失败
- **应对**: 修复代码或调整测试
- **回滚**: 单独的测试分支

---

## 执行检查点

### 检查点 1:阶段一完成后
- 运行 `npm run lint` 无错误
- 运行 `npm audit` 漏洞已修复
- 运行 `npm test` 测试通过

### 检查点 2:阶段二完成后
- 验证所有脚本路径正确
- 验证 Docker 构建正常
- 验证文档链接有效

### 检查点 3:阶段三完成后
- 验证 console.log 已清理
- 验证 TODO/FIXME 已处理
- 运行测试功能正常

### 检查点 4:阶段四完成后
- 验证测试覆盖率达标
- 验证性能指标达标
- 验证依赖更新正常

### 检查点 5:阶段五完成后
- 验证文档更新完整
- 运行完整测试套件通过
- 验收报告已生成

---

## 后续建议

### 短期（1-2 周）
1. 监控整理后的项目运行状态
2. 收集团队反馈，优化工作流程
3. 补充遗漏的测试用例
4. 完善文档细节

### 中期（1-3 月）
1. 评估 Major 版本依赖更新的可行性
2. 引入更严格的代码质量门禁
3. 优化 CI/CD 流程
4. 提升测试覆盖率至 80%+

### 长期（3-6 月）
1. 建立持续的技术债务管理机制
2. 定期进行代码审查和重构
3. 引入更多自动化工具
4. 建立知识库和最佳实践文档