docs: 整理文档结构并创建索引（任务 2.3/20）
This commit is contained in:
张翔
+94
-63
@@ -1,45 +1,98 @@
|
|||||||
# Novalon Website 文档
|
# Novalon Website 文档
|
||||||
|
|
||||||
欢迎来到Novalon Website项目文档中心。这里包含了项目的所有技术文档、开发指南和部署说明。
|
欢迎来到 Novalon Website 项目文档中心。这里包含了项目的所有技术文档、开发指南和部署说明。
|
||||||
|
|
||||||
## 文档导航
|
## 📚 文档导航
|
||||||
|
|
||||||
|
### 架构文档 (architecture/)
|
||||||
|
|
||||||
### 📚 架构文档
|
|
||||||
- [系统设计](architecture/system-design.md) - 系统整体架构设计
|
- [系统设计](architecture/system-design.md) - 系统整体架构设计
|
||||||
- [数据库架构](architecture/database-schema.md) - 数据库表结构和关系
|
- [架构概述](architecture/architecture.md) - 架构设计原则和模式
|
||||||
- [API架构](architecture/api-architecture.md) - API设计规范和接口说明
|
- [结构规划](architecture/STRUCTURE_PLAN.md) - 项目结构规划文档
|
||||||
|
|
||||||
|
### 开发文档 (development/)
|
||||||
|
|
||||||
### 💻 开发文档
|
|
||||||
- [快速开始](development/getting-started.md) - 项目快速开始指南
|
- [快速开始](development/getting-started.md) - 项目快速开始指南
|
||||||
- [编码规范](development/coding-standards.md) - 代码编写规范和最佳实践
|
- [API 文档](development/api.md) - API 接口文档
|
||||||
- [组件开发指南](development/component-guide.md) - React组件开发指南
|
- [API 版本控制指南](development/api-versioning-guide.md) - API 版本控制最佳实践
|
||||||
- [调试指南](development/debugging-guide.md) - 开发调试技巧和工具
|
- [组件开发指南](development/components.md) - React 组件开发指南
|
||||||
|
- [OpenAPI 指南](development/openapi-guide.md) - OpenAPI 规范和使用
|
||||||
|
- [联系方式配置](development/CONTACT_CONFIGURATION.md) - 联系表单配置说明
|
||||||
|
- [实施报告](development/IMPLEMENTATION-REPORT.md) - 功能实施报告
|
||||||
|
- [质量门禁](development/quality-gates.md) - 代码质量门禁配置
|
||||||
|
|
||||||
### 🚀 部署文档
|
### 部署文档 (deployment/)
|
||||||
- [生产环境部署](deployment/production.md) - 生产环境部署流程
|
|
||||||
- [Docker部署](deployment/docker.md) - Docker容器化部署
|
|
||||||
- [监控配置](deployment/monitoring.md) - 系统监控和告警配置
|
|
||||||
|
|
||||||
### 🧪 测试文档
|
- [部署指南](deployment/DEPLOYMENT.md) - 部署流程和步骤
|
||||||
- [测试策略](testing/testing-strategy.md) - 测试策略和分层测试
|
- [生产环境部署](deployment/PRODUCTION_DEPLOYMENT.md) - 生产环境部署指南
|
||||||
- [E2E测试](testing/e2e-testing.md) - 端到端测试指南
|
- [轻量级生产部署](deployment/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md) - 轻量级部署方案
|
||||||
- [单元测试](testing/unit-testing.md) - 单元测试编写指南
|
- [生产发布报告](deployment/PRODUCTION_RELEASE_REPORT.md) - 生产发布记录
|
||||||
- [性能测试](testing/performance-testing.md) - 性能测试和优化
|
- [CDN 配置](deployment/CDN_CONFIGURATION.md) - CDN 配置指南
|
||||||
|
- [CDN 快速开始](deployment/CDN_QUICK_START.md) - CDN 快速配置
|
||||||
|
- [CI/CD 快速开始](deployment/CICD_QUICK_START.md) - CI/CD 流程快速指南
|
||||||
|
- [CI/CD 预防指南](deployment/CICD_PREVENTION_GUIDE.md) - CI/CD 问题预防
|
||||||
|
- [CI/CD 验证清单](deployment/CICD_VERIFICATION_CHECKLIST.md) - CI/CD 验证检查清单
|
||||||
|
- [质量门禁 CI](deployment/quality-gates-ci.md) - CI 质量门禁配置
|
||||||
|
- [回滚流程](deployment/rollback-procedure.md) - 部署回滚操作流程
|
||||||
|
- [阶段一部署指南](deployment/phase1-deployment-guide.md) - 第一阶段部署指南
|
||||||
|
- [阶段一部署日志](deployment/phase1-deployment-log.md) - 第一阶段部署记录
|
||||||
|
- [Google Analytics 设置](deployment/GOOGLE_ANALYTICS_SETUP.md) - Google Analytics 配置
|
||||||
|
- [监控设置](deployment/MONITORING_SETUP.md) - 系统监控配置
|
||||||
|
- [监控快速开始](deployment/MONITORING_QUICKSTART.md) - 监控快速配置
|
||||||
|
- [轻量级监控](deployment/MONITORING_LIGHTWEIGHT.md) - 轻量级监控方案
|
||||||
|
- [轻量级监控](deployment/LIGHTWEIGHT_MONITORING.md) - 监控方案说明
|
||||||
|
- [优化报告](deployment/OPTIMIZATION_REPORT.md) - 性能优化报告
|
||||||
|
- [性能优化](deployment/PERFORMANCE_OPTIMIZATION.md) - 性能优化指南
|
||||||
|
|
||||||
### 🔌 API文档
|
### 测试文档 (testing/)
|
||||||
- [REST API](api/rest-api.md) - REST API接口文档
|
|
||||||
- [管理API](api/admin-api.md) - 管理后台API文档
|
|
||||||
|
|
||||||
### 📖 使用指南
|
- [测试指南](testing/testing-guide.md) - 测试编写指南
|
||||||
- [CMS使用指南](guides/cms-guide.md) - 内容管理系统使用指南
|
- [测试概述](testing/testing.md) - 测试策略和方法
|
||||||
- [认证指南](guides/authentication.md) - 用户认证和授权
|
- [分层测试](testing/README-TIERED-TESTING.md) - 分层测试策略
|
||||||
- [故障排查](guides/troubleshooting.md) - 常见问题排查和解决方案
|
- [测试报告](testing/TESTING_REPORT.md) - 测试执行报告
|
||||||
|
- [Allure 报告指南](testing/allure-report-guide.md) - Allure 测试报告使用
|
||||||
|
- [Lighthouse CI 指南](testing/lighthouse-ci-guide.md) - Lighthouse CI 配置
|
||||||
|
- [测试覆盖率改进计划](testing/test-coverage-improvement-plan.md) - 测试覆盖率提升计划
|
||||||
|
- [测试优化指南](testing/test-optimization-guide.md) - 测试优化策略
|
||||||
|
- [测试分层最佳实践](testing/test-tiering-best-practices.md) - 测试分层最佳实践
|
||||||
|
- [用户旅程覆盖矩阵](testing/user-journey-coverage-matrix.md) - 用户旅程测试覆盖
|
||||||
|
- [用户旅程测试指南](testing/user-journey-testing-guide.md) - 用户旅程测试编写
|
||||||
|
|
||||||
## 项目概述
|
### 安全文档 (security/)
|
||||||
|
|
||||||
Novalon Website是四川睿新致远科技有限公司的企业官网，采用现代化的技术栈构建。
|
- [管理员凭证](security/ADMIN-CREDENTIALS.md) - 管理员账户信息
|
||||||
|
- [Jenkins 安全加固指南](security/JENKINS_SECURITY_HARDENING_GUIDE.md) - Jenkins 安全配置
|
||||||
|
|
||||||
|
### 故障排查 (troubleshooting/)
|
||||||
|
|
||||||
|
- [HMR 错误解决方案](troubleshooting/HMR-ERROR-SOLUTIONS.md) - 热更新错误排查
|
||||||
|
- [修复计划 A 指南](troubleshooting/fix-plan-a-guide.md) - 问题修复流程
|
||||||
|
- [生产环境超时排查](troubleshooting/production-timeout-troubleshooting.md) - 生产环境超时问题排查
|
||||||
|
|
||||||
|
### 指南文档 (guides/)
|
||||||
|
|
||||||
|
- [安全指南](guides/SECURITY.md) - 安全最佳实践
|
||||||
|
|
||||||
|
### 计划文档 (plans/)
|
||||||
|
|
||||||
|
包含各种技术改进和功能开发的计划文档，按日期命名。
|
||||||
|
|
||||||
|
### Superpowers 文档 (superpowers/)
|
||||||
|
|
||||||
|
- **plans/** - 实施计划
|
||||||
|
- [项目重组计划](superpowers/plans/2026-04-12-project-reorganization-plan.md)
|
||||||
|
- **reports/** - 实施报告
|
||||||
|
- [用户旅程测试实施总结](superpowers/reports/2026-04-09-user-journey-testing-implementation-summary.md)
|
||||||
|
- **specs/** - 设计规范
|
||||||
|
- [测试质量改进设计](superpowers/specs/2026-04-09-test-quality-improvement-design.md)
|
||||||
|
- [项目重组设计](superpowers/specs/2026-04-12-project-reorganization-design.md)
|
||||||
|
|
||||||
|
## 🎯 项目概述
|
||||||
|
|
||||||
|
Novalon Website 是四川睿新致远科技有限公司的企业官网，采用现代化的技术栈构建。
|
||||||
|
|
||||||
### 技术栈
|
### 技术栈
|
||||||
|
|
||||||
- **框架**: Next.js 16 + React 19
|
- **框架**: Next.js 16 + React 19
|
||||||
- **语言**: TypeScript
|
- **语言**: TypeScript
|
||||||
- **样式**: Tailwind CSS
|
- **样式**: Tailwind CSS
|
||||||
@@ -48,46 +101,24 @@ Novalon Website是四川睿新致远科技有限公司的企业官网，采用
|
|||||||
- **测试**: Playwright + Jest
|
- **测试**: Playwright + Jest
|
||||||
|
|
||||||
### 核心功能
|
### 核心功能
|
||||||
- 企业展示和产品服务介绍
|
|
||||||
- 成功案例和新闻动态
|
|
||||||
- 在线咨询和联系表单
|
|
||||||
- CMS内容管理后台
|
|
||||||
- 响应式设计和SEO优化
|
|
||||||
|
|
||||||
## 快速链接
|
- 📝 内容管理系统 (CMS)
|
||||||
|
- 🔐 用户认证和授权
|
||||||
|
- 📊 数据分析和监控
|
||||||
|
- 🚀 高性能和 SEO 优化
|
||||||
|
- 🔄 CI/CD 自动化部署
|
||||||
|
|
||||||
- [项目README](../README.md) - 项目主文档
|
## 📖 快速链接
|
||||||
- [测试框架整合说明](../e2e/MIGRATION.md) - 测试框架迁移说明
|
|
||||||
- [目录结构规划](STRUCTURE_PLAN.md) - 项目目录结构说明
|
|
||||||
- [优化报告](OPTIMIZATION_REPORT.md) - 项目优化总结报告
|
|
||||||
|
|
||||||
## 贡献指南
|
- [快速开始](development/getting-started.md) - 开始开发
|
||||||
|
- [部署指南](deployment/DEPLOYMENT.md) - 部署到生产环境
|
||||||
|
- [测试指南](testing/testing-guide.md) - 编写测试
|
||||||
|
- [故障排查](troubleshooting/HMR-ERROR-SOLUTIONS.md) - 解决问题
|
||||||
|
|
||||||
### 文档更新
|
## 🤝 贡献指南
|
||||||
1. 确保文档内容准确、清晰
|
|
||||||
2. 使用Markdown格式编写
|
|
||||||
3. 添加必要的代码示例
|
|
||||||
4. 更新相关链接和引用
|
|
||||||
|
|
||||||
### 文档审查
|
请参阅 [开发文档](development/getting-started.md) 了解如何为项目做出贡献。
|
||||||
- 技术准确性
|
|
||||||
- 内容完整性
|
|
||||||
- 格式规范性
|
|
||||||
- 链接有效性
|
|
||||||
|
|
||||||
## 获取帮助
|
## 📄 许可证
|
||||||
|
|
||||||
如果在使用过程中遇到问题，可以：
|
本项目采用 MIT 许可证。
|
||||||
1. 查看相关文档
|
|
||||||
2. 搜索[故障排查指南](guides/troubleshooting.md)
|
|
||||||
3. 联系开发团队
|
|
||||||
|
|
||||||
## 文档版本
|
|
||||||
|
|
||||||
- **版本**: 1.0.0
|
|
||||||
- **更新日期**: 2026-03-24
|
|
||||||
- **维护者**: 开发团队
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
© 2026 四川睿新致远科技有限公司
|
|
||||||
|
|||||||
@@ -1,475 +0,0 @@
|
|||||||
# 部署文档
|
|
||||||
|
|
||||||
## 部署概述
|
|
||||||
|
|
||||||
项目采用 Next.js 静态导出模式，构建生成纯静态 HTML 文件，可部署到任何静态文件服务器或 CDN。
|
|
||||||
|
|
||||||
## 构建配置
|
|
||||||
|
|
||||||
### Next.js 配置
|
|
||||||
|
|
||||||
```typescript
|
|
||||||
// next.config.ts
|
|
||||||
const nextConfig: NextConfig = {
|
|
||||||
output: 'export', // 静态导出模式
|
|
||||||
distDir: 'dist', // 输出目录
|
|
||||||
images: {
|
|
||||||
unoptimized: true, // 静态导出需要禁用图片优化
|
|
||||||
},
|
|
||||||
compress: true,
|
|
||||||
poweredByHeader: false,
|
|
||||||
reactStrictMode: true,
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
### 构建命令
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 开发模式（不导出）
|
|
||||||
npm run dev
|
|
||||||
|
|
||||||
# 生产构建（静态导出）
|
|
||||||
npm run build
|
|
||||||
|
|
||||||
# 输出目录
|
|
||||||
dist/
|
|
||||||
```
|
|
||||||
|
|
||||||
## 环境变量
|
|
||||||
|
|
||||||
### 必需配置
|
|
||||||
|
|
||||||
```env
|
|
||||||
# .env.production
|
|
||||||
RESEND_API_KEY=re_xxxxx
|
|
||||||
COMPANY_EMAIL=contact@novalon.cn
|
|
||||||
```
|
|
||||||
|
|
||||||
### 可选配置
|
|
||||||
|
|
||||||
```env
|
|
||||||
NODE_ENV=production
|
|
||||||
NEXT_PUBLIC_SITE_URL=https://www.novalon.cn
|
|
||||||
```
|
|
||||||
|
|
||||||
### 环境变量说明
|
|
||||||
|
|
||||||
| 变量名 | 必需 | 描述 |
|
|
||||||
|--------|------|------|
|
|
||||||
| `RESEND_API_KEY` | 是 | Resend 邮件服务 API 密钥 |
|
|
||||||
| `COMPANY_EMAIL` | 是 | 公司接收邮件的邮箱地址 |
|
|
||||||
| `NODE_ENV` | 否 | 环境标识 |
|
|
||||||
| `NEXT_PUBLIC_SITE_URL` | 否 | 网站公开 URL |
|
|
||||||
|
|
||||||
## 部署平台
|
|
||||||
|
|
||||||
### 1. Vercel 部署（推荐）
|
|
||||||
|
|
||||||
**优势：**
|
|
||||||
- 零配置部署
|
|
||||||
- 自动 HTTPS
|
|
||||||
- 全球 CDN
|
|
||||||
- 预览部署
|
|
||||||
- 边缘函数支持
|
|
||||||
|
|
||||||
**部署步骤：**
|
|
||||||
|
|
||||||
1. 连接 Git 仓库
|
|
||||||
2. 配置环境变量
|
|
||||||
3. 部署设置：
|
|
||||||
- Build Command: `npm run build`
|
|
||||||
- Output Directory: `dist`
|
|
||||||
- Install Command: `npm install`
|
|
||||||
|
|
||||||
**vercel.json 配置：**
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"buildCommand": "npm run build",
|
|
||||||
"outputDirectory": "dist",
|
|
||||||
"framework": "nextjs",
|
|
||||||
"regions": ["hkg1"]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. 静态文件服务器部署
|
|
||||||
|
|
||||||
**适用场景：**
|
|
||||||
- Nginx
|
|
||||||
- Apache
|
|
||||||
- IIS
|
|
||||||
- 云存储（阿里云 OSS、腾讯云 COS）
|
|
||||||
|
|
||||||
**Nginx 配置示例：**
|
|
||||||
|
|
||||||
```nginx
|
|
||||||
server {
|
|
||||||
listen 80;
|
|
||||||
server_name www.novalon.cn novalon.cn;
|
|
||||||
root /var/www/novalon-website/dist;
|
|
||||||
index index.html;
|
|
||||||
|
|
||||||
# 强制 HTTPS
|
|
||||||
return 301 https://$server_name$request_uri;
|
|
||||||
}
|
|
||||||
|
|
||||||
server {
|
|
||||||
listen 443 ssl http2;
|
|
||||||
server_name www.novalon.cn novalon.cn;
|
|
||||||
root /var/www/novalon-website/dist;
|
|
||||||
index index.html;
|
|
||||||
|
|
||||||
# SSL 证书
|
|
||||||
ssl_certificate /etc/nginx/ssl/novalon.cn.pem;
|
|
||||||
ssl_certificate_key /etc/nginx/ssl/novalon.cn.key;
|
|
||||||
ssl_protocols TLSv1.2 TLSv1.3;
|
|
||||||
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
|
|
||||||
ssl_prefer_server_ciphers off;
|
|
||||||
|
|
||||||
# 安全头部
|
|
||||||
add_header X-Frame-Options "SAMEORIGIN" always;
|
|
||||||
add_header X-Content-Type-Options "nosniff" always;
|
|
||||||
add_header X-XSS-Protection "1; mode=block" always;
|
|
||||||
add_header Referrer-Policy "strict-origin-when-cross-origin" always;
|
|
||||||
add_header Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;" always;
|
|
||||||
|
|
||||||
# Gzip 压缩
|
|
||||||
gzip on;
|
|
||||||
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;
|
|
||||||
gzip_min_length 1000;
|
|
||||||
|
|
||||||
# 静态资源缓存
|
|
||||||
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
|
|
||||||
expires 1y;
|
|
||||||
add_header Cache-Control "public, immutable";
|
|
||||||
}
|
|
||||||
|
|
||||||
# HTML 不缓存
|
|
||||||
location ~* \.html$ {
|
|
||||||
expires -1;
|
|
||||||
add_header Cache-Control "no-store, no-cache, must-revalidate";
|
|
||||||
}
|
|
||||||
|
|
||||||
# SPA 路由支持
|
|
||||||
location / {
|
|
||||||
try_files $uri $uri.html $uri/ =404;
|
|
||||||
}
|
|
||||||
|
|
||||||
# 404 页面
|
|
||||||
error_page 404 /404.html;
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
### 3. Docker 部署
|
|
||||||
|
|
||||||
**Dockerfile:**
|
|
||||||
|
|
||||||
```dockerfile
|
|
||||||
# 构建阶段
|
|
||||||
FROM node:18-alpine AS builder
|
|
||||||
|
|
||||||
WORKDIR /app
|
|
||||||
|
|
||||||
COPY package*.json ./
|
|
||||||
RUN npm ci
|
|
||||||
|
|
||||||
COPY . .
|
|
||||||
RUN npm run build
|
|
||||||
|
|
||||||
# 运行阶段
|
|
||||||
FROM nginx:alpine
|
|
||||||
|
|
||||||
# 复制构建产物
|
|
||||||
COPY --from=builder /app/dist /usr/share/nginx/html
|
|
||||||
|
|
||||||
# 复制 Nginx 配置
|
|
||||||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
|
||||||
|
|
||||||
EXPOSE 80
|
|
||||||
|
|
||||||
CMD ["nginx", "-g", "daemon off;"]
|
|
||||||
```
|
|
||||||
|
|
||||||
**构建和运行：**
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 构建镜像
|
|
||||||
docker build -t novalon-website .
|
|
||||||
|
|
||||||
# 运行容器
|
|
||||||
docker run -d -p 80:80 --name novalon novalon-website
|
|
||||||
```
|
|
||||||
|
|
||||||
### 4. 云存储部署
|
|
||||||
|
|
||||||
**阿里云 OSS：**
|
|
||||||
|
|
||||||
1. 创建 OSS Bucket
|
|
||||||
2. 配置静态网站托管
|
|
||||||
3. 上传 `dist/` 目录内容
|
|
||||||
4. 配置自定义域名
|
|
||||||
5. 配置 HTTPS 证书
|
|
||||||
|
|
||||||
**腾讯云 COS：**
|
|
||||||
|
|
||||||
1. 创建 COS Bucket
|
|
||||||
2. 开启静态网站功能
|
|
||||||
3. 上传构建产物
|
|
||||||
4. 配置 CDN 加速
|
|
||||||
|
|
||||||
## CI/CD 流水线
|
|
||||||
|
|
||||||
### Woodpecker CI 配置
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# .woodpecker.yml
|
|
||||||
pipeline:
|
|
||||||
install:
|
|
||||||
image: node:18-alpine
|
|
||||||
commands:
|
|
||||||
- npm ci
|
|
||||||
when:
|
|
||||||
event:
|
|
||||||
- push
|
|
||||||
- pull_request
|
|
||||||
|
|
||||||
lint:
|
|
||||||
image: node:18-alpine
|
|
||||||
commands:
|
|
||||||
- npm run lint
|
|
||||||
when:
|
|
||||||
event:
|
|
||||||
- push
|
|
||||||
- pull_request
|
|
||||||
|
|
||||||
build:
|
|
||||||
image: node:18-alpine
|
|
||||||
environment:
|
|
||||||
NODE_ENV: production
|
|
||||||
commands:
|
|
||||||
- npm run build
|
|
||||||
when:
|
|
||||||
event:
|
|
||||||
- push
|
|
||||||
branch:
|
|
||||||
- main
|
|
||||||
|
|
||||||
e2e-tests:
|
|
||||||
image: node:18-alpine
|
|
||||||
environment:
|
|
||||||
NODE_ENV: test
|
|
||||||
CI: true
|
|
||||||
commands:
|
|
||||||
- cd e2e
|
|
||||||
- npm ci
|
|
||||||
- npx playwright install --with-deps chromium
|
|
||||||
- npm run test:smoke
|
|
||||||
when:
|
|
||||||
event:
|
|
||||||
- push
|
|
||||||
- pull_request
|
|
||||||
|
|
||||||
deploy:
|
|
||||||
image: node:18-alpine
|
|
||||||
commands:
|
|
||||||
- npm install -g vercel
|
|
||||||
- vercel --prod --token=$VERCEL_TOKEN
|
|
||||||
secrets:
|
|
||||||
- vercel_token
|
|
||||||
when:
|
|
||||||
event:
|
|
||||||
- push
|
|
||||||
branch:
|
|
||||||
- main
|
|
||||||
```
|
|
||||||
|
|
||||||
## 部署检查清单
|
|
||||||
|
|
||||||
### 部署前检查
|
|
||||||
|
|
||||||
- [ ] 环境变量已配置
|
|
||||||
- [ ] 构建成功无错误
|
|
||||||
- [ ] E2E 测试通过
|
|
||||||
- [ ] ESLint 检查通过
|
|
||||||
- [ ] 图片资源已优化
|
|
||||||
- [ ] 死链检查通过
|
|
||||||
|
|
||||||
### 部署后验证
|
|
||||||
|
|
||||||
- [ ] 首页正常加载
|
|
||||||
- [ ] 所有页面可访问
|
|
||||||
- [ ] 表单提交正常
|
|
||||||
- [ ] 移动端适配正常
|
|
||||||
- [ ] HTTPS 证书有效
|
|
||||||
- [ ] 性能指标达标
|
|
||||||
- [ ] SEO 元数据正确
|
|
||||||
|
|
||||||
### 性能指标
|
|
||||||
|
|
||||||
| 指标 | 目标值 |
|
|
||||||
|------|--------|
|
|
||||||
| LCP | < 2.5s |
|
|
||||||
| FID | < 100ms |
|
|
||||||
| CLS | < 0.1 |
|
|
||||||
| TTFB | < 600ms |
|
|
||||||
| 首屏加载 | < 3s |
|
|
||||||
|
|
||||||
## 回滚策略
|
|
||||||
|
|
||||||
### Vercel 回滚
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 列出部署历史
|
|
||||||
vercel ls
|
|
||||||
|
|
||||||
# 回滚到指定版本
|
|
||||||
vercel rollback [deployment-url]
|
|
||||||
```
|
|
||||||
|
|
||||||
### 静态服务器回滚
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# 保留历史版本
|
|
||||||
/var/www/novalon-website/
|
|
||||||
├── current -> releases/20260307-1
|
|
||||||
├── releases/
|
|
||||||
│ ├── 20260307-1/
|
|
||||||
│ ├── 20260306-1/
|
|
||||||
│ └── 20260305-1/
|
|
||||||
└── shared/
|
|
||||||
|
|
||||||
# 回滚操作
|
|
||||||
ln -sfn releases/20260306-1 current
|
|
||||||
```
|
|
||||||
|
|
||||||
## 监控与告警
|
|
||||||
|
|
||||||
### 推荐工具
|
|
||||||
|
|
||||||
| 工具 | 用途 |
|
|
||||||
|------|------|
|
|
||||||
| Vercel Analytics | 性能监控 |
|
|
||||||
| Sentry | 错误监控 |
|
|
||||||
| Uptime Robot | 可用性监控 |
|
|
||||||
| Google Search Console | SEO 监控 |
|
|
||||||
|
|
||||||
### 告警配置
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
# Uptime Robot 配置示例
|
|
||||||
monitors:
|
|
||||||
- name: Novalon Website
|
|
||||||
url: https://www.novalon.cn
|
|
||||||
type: https
|
|
||||||
interval: 300
|
|
||||||
alert_contacts:
|
|
||||||
- email: admin@novalon.cn
|
|
||||||
```
|
|
||||||
|
|
||||||
## 安全配置
|
|
||||||
|
|
||||||
### 安全头部
|
|
||||||
|
|
||||||
```http
|
|
||||||
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
|
|
||||||
X-Frame-Options: SAMEORIGIN
|
|
||||||
X-Content-Type-Options: nosniff
|
|
||||||
X-XSS-Protection: 1; mode=block
|
|
||||||
Referrer-Policy: strict-origin-when-cross-origin
|
|
||||||
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' data:;
|
|
||||||
Permissions-Policy: camera=(), microphone=(), geolocation=()
|
|
||||||
```
|
|
||||||
|
|
||||||
### HTTPS 配置
|
|
||||||
|
|
||||||
- 使用 TLS 1.2 或更高版本
|
|
||||||
- 配置 HSTS
|
|
||||||
- 启用 OCSP Stapling
|
|
||||||
- 使用强加密套件
|
|
||||||
|
|
||||||
## 性能优化
|
|
||||||
|
|
||||||
### 构建优化
|
|
||||||
|
|
||||||
1. **代码分割**
|
|
||||||
- 动态导入非首屏组件
|
|
||||||
- 路由级别分割
|
|
||||||
|
|
||||||
2. **资源优化**
|
|
||||||
- 图片压缩和格式转换
|
|
||||||
- CSS 压缩
|
|
||||||
- JavaScript 压缩
|
|
||||||
|
|
||||||
3. **缓存策略**
|
|
||||||
- 静态资源长缓存
|
|
||||||
- HTML 不缓存
|
|
||||||
- API 响应适当缓存
|
|
||||||
|
|
||||||
### CDN 配置
|
|
||||||
|
|
||||||
```
|
|
||||||
# CDN 缓存规则
|
|
||||||
*.js, *.css -> 缓存 1 年
|
|
||||||
*.jpg, *.png -> 缓存 1 年
|
|
||||||
*.woff, *.woff2 -> 缓存 1 年
|
|
||||||
*.html -> 不缓存
|
|
||||||
```
|
|
||||||
|
|
||||||
## 故障排查
|
|
||||||
|
|
||||||
### 常见问题
|
|
||||||
|
|
||||||
**1. 页面 404 错误**
|
|
||||||
- 检查静态文件是否正确上传
|
|
||||||
- 检查 Nginx 配置的 root 路径
|
|
||||||
- 检查 SPA 路由配置
|
|
||||||
|
|
||||||
**2. 样式加载失败**
|
|
||||||
- 检查 CSS 文件路径
|
|
||||||
- 检查 Content-Security-Policy 配置
|
|
||||||
- 清除浏览器缓存
|
|
||||||
|
|
||||||
**3. 表单提交失败**
|
|
||||||
- 检查 API 路由是否正常
|
|
||||||
- 检查环境变量配置
|
|
||||||
- 检查 CORS 配置
|
|
||||||
|
|
||||||
**4. 性能问题**
|
|
||||||
- 检查图片是否优化
|
|
||||||
- 检查 CDN 是否生效
|
|
||||||
- 检查服务器响应时间
|
|
||||||
|
|
||||||
### 日志查看
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Nginx 访问日志
|
|
||||||
tail -f /var/log/nginx/access.log
|
|
||||||
|
|
||||||
# Nginx 错误日志
|
|
||||||
tail -f /var/log/nginx/error.log
|
|
||||||
|
|
||||||
# Vercel 日志
|
|
||||||
vercel logs [deployment-url]
|
|
||||||
```
|
|
||||||
|
|
||||||
## 维护计划
|
|
||||||
|
|
||||||
### 定期任务
|
|
||||||
|
|
||||||
| 任务 | 频率 |
|
|
||||||
|------|------|
|
|
||||||
| 依赖更新 | 每月 |
|
|
||||||
| 安全扫描 | 每周 |
|
|
||||||
| 性能测试 | 每周 |
|
|
||||||
| 备份验证 | 每月 |
|
|
||||||
| SSL 证书更新 | 到期前 30 天 |
|
|
||||||
|
|
||||||
### 更新流程
|
|
||||||
|
|
||||||
1. 创建更新分支
|
|
||||||
2. 执行依赖更新
|
|
||||||
3. 运行测试套件
|
|
||||||
4. 部署到预览环境
|
|
||||||
5. 验证功能正常
|
|
||||||
6. 合并到主分支
|
|
||||||
7. 自动部署到生产环境
|
|
||||||
+381
-638
File diff suppressed because it is too large
Load Diff
@@ -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. 建立知识库和最佳实践文档
|
||||||
Reference in New Issue
Block a user