novalon/novalon-website

Fork 0

Files

T

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

2026-04-12 16:24:51 +08:00

17 KiB

Raw Blame History

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

创建日期： 2026-04-12
基于设计： 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 验证无错误

步骤:

创建 .prettierrc 配置文件

{
  "semi": true,
  "trailingComma": "es5",
  "singleQuote": true,
  "printWidth": 100,
  "tabWidth": 2,
  "useTabs": false,
  "arrowParens": "always",
  "endOfLine": "lf"
}

更新 config/lint/.eslintrc.json 强化规则
运行 npm run lint -- --fix 自动修复代码格式
运行 npm run lint 验证无错误

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

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

职责: 修复安全漏洞

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

步骤:

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

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

文件: 多个源代码文件

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

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

步骤:

运行 npm run lint -- --fix 自动修复代码问题
运行 npm run type-check 验证无类型错误
运行 npm test 验证功能正常

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

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

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

文件:

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

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

测试:

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

步骤:

创建 scripts/ 子目录结构

mkdir -p scripts/deployment
mkdir -p scripts/monitoring
mkdir -p scripts/diagnosis
mkdir -p scripts/security
mkdir -p scripts/maintenance
mkdir -p scripts/tools

移动部署脚本

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/

移动监控脚本

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/

移动诊断脚本

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/

移动安全脚本

mv security-audit.sh scripts/security/
mv security-hardening.sh scripts/security/
mv security-verification.sh scripts/security/

移动维护脚本

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/

移动工具脚本

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/

更新 package.json 中的脚本路径引用
创建 scripts/README.md 说明脚本用途
运行测试验证路径正确

任务 2.2:Docker 文件整理

文件:

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

职责: 整理 Docker 配置文件

测试:

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

步骤:

创建 docker/ 目录
```
mkdir -p docker/nginx
```

移动 Dockerfile 文件

mv Dockerfile docker/
mv Dockerfile.prod docker/
mv Dockerfile.tools docker/

移动 docker-compose 文件

mv docker-compose.yml docker/
mv docker-compose.prod.yml docker/
mv docker-compose.high-perf.yml docker/
mv docker-compose.server.yml docker/

移动 nginx 配置

mv nginx-woodpecker.conf docker/nginx/
mv nginx-woodpecker-fixed.conf docker/nginx/

更新 CI/CD 配置中的 Docker 文件路径引用
- 检查 .woodpecker-test.yml 中的 Docker 路径
- 检查 Jenkinsfile 中的 Docker 路径
- 检查 config/ci/*.yml 中的 Docker 路径
运行 docker build -f docker/Dockerfile . 验证构建正常

任务 2.3:文档结构优化

文件:

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

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

测试:

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

步骤:

创建 docs/archive/ 目录
```
mkdir -p docs/archive
```

移动过时计划文档

mv docs/plans/2026-03-*.md docs/archive/

合并重复文档
- 合并 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
创建 docs/README.md 文档索引
验证所有文档链接有效

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

文件: 检查 config/ 目录

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

测试:

运行 npm run build 验证配置加载正确
检查 config/ 目录结构是否完整

步骤:

检查 config/ 目录结构
确保所有配置文件都在 config/ 目录下
验证配置文件加载正确

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

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

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

文件:

创建: src/lib/logger.ts
创建: src/lib/logger.test.ts

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

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

步骤:

创建 src/lib/logger.ts 文件

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();

编写单元测试验证日志功能
运行测试确保通过

任务 3.2:console.log 清理

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

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

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

步骤:

扫描所有 console.log 出现的位置

grep -r "console\.(log|debug|warn|error)" src/ --include="*.ts,*.tsx" --exclude="*.test.*"

分类标记：
- 调试日志（删除）
- 错误日志（改用 logger.error）
- 信息日志（评估）
批量处理生产代码中的 console.log
- API 路由：改用 logger.error
- 页面组件：删除
- 客户端组件：删除
- 管理后台：改用 logger.info
保留测试文件和种子数据文件中的 console.log
运行测试验证功能正常

任务 3.3:TODO/FIXME 处理

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

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

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

步骤:

扫描所有 TODO/FIXME 出现的位置

grep -r "TODO|FIXME|HACK|XXX" src/ --include="*.ts,*.tsx"

评估每个 TODO/FIXME 的优先级
实现或修复相关功能
删除已处理的 TODO/FIXME 注释
运行测试验证功能正常

任务 3.4:代码逻辑优化

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

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

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

步骤:

识别需要优化的代码模块
重构代码结构
优化代码逻辑
运行测试验证功能正常

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

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

任务 4.1:依赖更新评估

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

职责: 评估并更新依赖包

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

步骤:

运行 npm outdated 查看过时依赖
评估每个依赖的更新影响

更新 Patch 和 Minor 版本依赖

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.2:API 路由测试补充

文件: 创建测试文件

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

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

步骤:

为 src/app/api/admin/security/route.ts 创建测试文件
为 src/app/api/config/route.ts 创建测试文件
为 src/app/api/content/route.ts 创建测试文件
为 src/app/api/docs/route.ts 创建测试文件
为 src/app/api/v1/config/route.ts 创建测试文件
编写关键路径测试用例
运行测试验证覆盖率提升

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

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

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

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

步骤:

为 src/app/admin/settings/page.tsx 补充测试用例
为 src/app/admin/users/page.tsx 补充测试用例
为 src/app/admin/content/[id]/page.tsx 补充测试用例
编写用户交互测试用例
运行测试验证覆盖率提升

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

文件: 创建测试文件

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

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

步骤:

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

任务 4.5:性能优化

文件:

修改: next.config.ts
修改: config/test/lighthouserc.json

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

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

步骤:

优化 next.config.ts 配置

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,
};

配置 Lighthouse CI
运行 Lighthouse CI 验证性能指标

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

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

任务 5.1:README 更新

文件: README.md

职责: 更新项目主 README 文档

测试: 验证文档内容准确

步骤:

更新项目结构说明
更新技术栈版本信息
更新质量保障章节
更新文档导航链接
验证文档内容准确

任务 5.2:文档索引创建

文件: docs/README.md

职责: 创建文档中心索引

测试: 验证文档链接有效

步骤:

创建文档索引结构
添加快速导航链接
分类整理文档链接
验证所有链接有效

任务 5.3:全面回归测试

文件: 运行所有测试

职责: 确保所有功能正常

测试: 运行完整测试套件

步骤:

运行 npm run lint 验证代码质量
运行 npm run type-check 验证类型正确
运行 npm run test:coverage 验证测试覆盖率
运行 npm run build 验证构建成功
运行 npm audit 验证安全性
运行 npm run test:e2e 验证 E2E 测试

任务 5.4:验收报告生成

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

职责: 生成整理总结报告

测试: 验证报告内容完整

步骤:

收集测试覆盖率报告
收集 Lighthouse 报告
收集安全审计报告
生成整理总结报告
验证报告内容完整

验收标准

代码质量

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-3 月）

评估 Major 版本依赖更新的可行性
引入更严格的代码质量门禁
优化 CI/CD 流程
提升测试覆盖率至 80%+

长期（3-6 月）

建立持续的技术债务管理机制
定期进行代码审查和重构
引入更多自动化工具
建立知识库和最佳实践文档

17 KiB Raw Blame History Unescape Escape

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

执行概览

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

任务 1.1：代码格式化统一

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

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

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

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

任务 2.2:Docker 文件整理

任务 2.3:文档结构优化

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

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

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

任务 3.2:console.log 清理

任务 3.3:TODO/FIXME 处理

任务 3.4:代码逻辑优化

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

任务 4.1:依赖更新评估

任务 4.2:API 路由测试补充

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

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

任务 4.5:性能优化

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

任务 5.1:README 更新

任务 5.2:文档索引创建

任务 5.3:全面回归测试

任务 5.4:验收报告生成

验收标准

代码质量

测试覆盖率

安全性

性能

项目结构

风险应对

风险 1:文件迁移导致引用路径错误

风险 2:代码清理导致功能异常

风险 3:依赖更新导致兼容性问题

风险 4:测试失败

执行检查点

检查点 1:阶段一完成后

检查点 2:阶段二完成后

检查点 3:阶段三完成后

检查点 4:阶段四完成后

检查点 5:阶段五完成后

后续建议

短期（1-2 周）

中期（1-3 月）

长期（3-6 月）

17 KiB

Raw Blame History