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

This commit is contained in:
张翔 committed 2026-04-12 16:24:51 +08:00
1 parent 1f52d47ed5
commit 5cd7d48bf2
33 files changed
+1140 -1176

No files matched your search

+94 -63
View File
@@ -1,45 +1,98 @@
# Novalon Website 文档
欢迎来到Novalon Website项目文档中心。这里包含了项目的所有技术文档、开发指南和部署说明。
欢迎来到 Novalon Website 项目文档中心。这里包含了项目的所有技术文档、开发指南和部署说明。
## 文档导航
## 📚 文档导航
### 架构文档 (architecture/)
### 📚 架构文档
- [系统设计](architecture/system-design.md) - 系统整体架构设计
- [数据库架构](architecture/database-schema.md) - 数据库表结构和关系
- [API架构](architecture/api-architecture.md) - API设计规范和接口说明
- [架构概述](architecture/architecture.md) - 架构设计原则和模式
- [结构规划](architecture/STRUCTURE_PLAN.md) - 项目结构规划文档
### 开发文档 (development/)
### 💻 开发文档
- [快速开始](development/getting-started.md) - 项目快速开始指南
- [编码规范](development/coding-standards.md) - 代码编写规范和最佳实践
- [组件开发指南](development/component-guide.md) - React组件开发指南
- [调试指南](development/debugging-guide.md) - 开发调试技巧和工具
- [API 文档](development/api.md) - API 接口文档
- [API 版本控制指南](development/api-versioning-guide.md) - API 版本控制最佳实践
- [组件开发指南](development/components.md) - React 组件开发指南
- [OpenAPI 指南](development/openapi-guide.md) - OpenAPI 规范和使用
- [联系方式配置](development/CONTACT_CONFIGURATION.md) - 联系表单配置说明
- [实施报告](development/IMPLEMENTATION-REPORT.md) - 功能实施报告
- [质量门禁](development/quality-gates.md) - 代码质量门禁配置
### 🚀 部署文档
- [生产环境部署](deployment/production.md) - 生产环境部署流程
- [Docker部署](deployment/docker.md) - Docker容器化部署
- [监控配置](deployment/monitoring.md) - 系统监控和告警配置
### 部署文档 (deployment/)
### 🧪 测试文档
- [测试策略](testing/testing-strategy.md) - 测试策略和分层测试
- [E2E测试](testing/e2e-testing.md) - 端到端测试指南
- [单元测试](testing/unit-testing.md) - 单元测试编写指南
- [性能测试](testing/performance-testing.md) - 性能测试和优化
- [部署指南](deployment/DEPLOYMENT.md) - 部署流程和步骤
- [生产环境部署](deployment/PRODUCTION_DEPLOYMENT.md) - 生产环境部署指南
- [轻量级生产部署](deployment/PRODUCTION_DEPLOYMENT_LIGHTWEIGHT.md) - 轻量级部署方案
- [生产发布报告](deployment/PRODUCTION_RELEASE_REPORT.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文档
- [REST API](api/rest-api.md) - REST API接口文档
- [管理API](api/admin-api.md) - 管理后台API文档
### 测试文档 (testing/)
### 📖 使用指南
- [CMS使用指南](guides/cms-guide.md) - 内容管理系统使用指南
- [认证指南](guides/authentication.md) - 用户认证和授权
- [故障排查](guides/troubleshooting.md) - 常见问题排查和解决方案
- [测试指南](testing/testing-guide.md) - 测试编写指南
- [测试概述](testing/testing.md) - 测试策略和方法
- [分层测试](testing/README-TIERED-TESTING.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
- **语言**: TypeScript
- **样式**: Tailwind CSS
@@ -48,46 +101,24 @@ Novalon Website是四川睿新致远科技有限公司的企业官网,采用
- **测试**: 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) 了解如何为项目做出贡献。
## 获取帮助
## 📄 许可证
如果在使用过程中遇到问题,可以:
1. 查看相关文档
2. 搜索[故障排查指南](guides/troubleshooting.md)
3. 联系开发团队
## 文档版本
- **版本**: 1.0.0
- **更新日期**: 2026-03-24
- **维护者**: 开发团队
---
© 2026 四川睿新致远科技有限公司
本项目采用 MIT 许可证。
File renamed without changes.
File renamed without changes.
-475
View File
@@ -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. 自动部署到生产环境
File renamed without changes.
File renamed without changes.
File renamed without changes.
File diff suppressed because it is too large. Load diff
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
@@ -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. 建立知识库和最佳实践文档
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.