docs: 整理文档结构并创建索引（任务 2.3/20）

2026-04-12 16:24:51 +08:00
parent 1f52d47ed5
commit 5cd7d48bf2
33 changed files with 1140 additions and 1176 deletions
@@ -0,0 +1,665 @@
+# 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. 建立知识库和最佳实践文档