Files

T

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

- 采用混合方案（方案B + 方案C）
- 包含项目结构重组、代码质量优化、依赖管理、测试与性能优化、文档整理
- 明确量化指标和验收标准
- 预计执行时间 3.5 天

2026-04-12 14:20:58 +08:00

17 KiB

Raw Blame History

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：

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 处理策略

处理流程：

扫描所有 TODO/FIXME/HACK 注释
分类评估：
- 紧急：立即实现或修复
- 重要：立即实现
- 一般：评估后决定
- 过时：直接删除注释
执行处理：实现/修复或删除
验证：确保所有 TODO/FIXME 已处理

处理原则： 立即实现（用户选择）

5.3 代码风格统一（自动化）

Prettier 配置：

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

ESLint 规则强化：

{
  "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

修复流程：

# 自动修复
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%)

测试补充策略：

API 路由测试：补充关键路径测试
页面组件测试：补充用户交互测试
Server Actions 测试：补充表单提交测试

7.2 性能优化策略

构建性能优化：

并行构建、缓存优化
Tree shaking、代码分割

运行时性能优化：

图片优化（AVIF、WebP）
懒加载、预加载
包大小优化

Lighthouse CI 配置：

{
  "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 文档体系整理

文档整理流程：

文档审计：扫描所有文档，标记状态（有效/过时/废弃）
文档分类：架构/部署/开发/测试/安全/归档
文档优化：合并重复、更新过时、删除废弃
文档索引：创建 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 验收标准

验收清单：

项目结构 ✅
- 根目录脚本文件已分类整理
- Docker 相关文件已移至 docker/ 目录
- 文档已分类整理，建立索引
代码质量 ✅
- 所有 console.log 已清理
- 所有 TODO/FIXME 已处理
- ESLint 无错误
- TypeScript 无类型错误
依赖管理 ✅
- 安全漏洞已修复
- Patch 和 Minor 版本已更新
测试覆盖 ✅
- Lines 覆盖率 ≥ 70%
- Functions 覆盖率 ≥ 65%
- Branches 覆盖率 ≥ 60%
- Statements 覆盖率 ≥ 70%
性能优化 ✅
- Lighthouse 性能评分 ≥ 90
- Lighthouse 可访问性评分 ≥ 95
- Lighthouse 最佳实践评分 ≥ 95
- Lighthouse SEO 评分 ≥ 95
文档完善 ✅
- 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 回滚策略

Git 分支策略：在专门的整理分支上工作
分阶段提交：每个阶段完成后提交，便于回滚
备份关键文件：修改前备份关键配置文件
测试验证：每个阶段完成后运行完整测试

十、后续建议

10.1 短期优化（1-2 周）

监控整理后的项目运行状态
收集团队反馈，优化工作流程
补充遗漏的测试用例
完善文档细节

10.2 中期优化（1-3 月）

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

10.3 长期优化（3-6 月）

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

附录

A. 相关文档

B. 工具清单

ESLint - 代码质量检查
Prettier - 代码格式化
Jest - 单元测试
Playwright - E2E 测试
Lighthouse CI - 性能监控
npm audit - 安全审计

17 KiB Raw Blame History Unescape Escape