张翔
498bb3a3c8
- Move CI/CD configs to config/ci/ directory - Reorganize scripts into categorized directories (deployment, monitoring, testing, utils) - Consolidate documentation into docs/ directory with proper structure - Update linting and testing configurations - Remove obsolete test reports and performance summaries - Add new documentation for code quality tools and contact form security - Improve project organization and maintainability - Fix lint-staged config to only lint JS/TS files - Disable react/react-in-jsx-scope rule for Next.js compatibility - Ignore scripts and test config directories in ESLint
264 lines
8.3 KiB
Markdown
264 lines
8.3 KiB
Markdown
# 目录结构规范化方案
|
||
|
||
## 目标
|
||
|
||
建立清晰、规范的目录结构，符合Next.js最佳实践，提升代码可维护性和团队协作效率。
|
||
|
||
## 当前问题
|
||
|
||
### 1. 配置文件分散
|
||
|
||
- 环境配置文件：`.env.example`, `.env.production`, `.env.production.example`, `e2e/.env.example`, `e2e-tests/.env.example`
|
||
- CI/CD配置：`.github/workflows/`, `.woodpecker/`
|
||
- 测试配置：多个playwright配置文件
|
||
|
||
### 2. 文档文件杂乱
|
||
|
||
- 根目录文档：`README.md`, `DEPLOYMENT.md`, `IMPLEMENTATION-REPORT.md`, `README-TIERED-TESTING.md`, `SECURITY.md`, `TESTING_REPORT.md`
|
||
- 测试报告：`test-reports/`, `test-analysis/`, `performance/`
|
||
- 缺少docs目录结构
|
||
|
||
### 3. 脚本文件组织混乱
|
||
|
||
- scripts目录下有14个脚本文件，分类不清
|
||
- 脚本命名不统一（.sh, .ts, .js）
|
||
- 缺少脚本文档
|
||
|
||
### 4. 临时文件和构建产物
|
||
|
||
- `performance/`目录包含临时测试报告
|
||
- `test-reports/`和`test-analysis/`目录包含测试报告
|
||
- `.gitignore`中忽略了docs目录（已修复）
|
||
|
||
## 优化方案
|
||
|
||
### 1. 标准化目录结构
|
||
|
||
```
|
||
novalon-website/
|
||
├── src/ # 源代码目录
|
||
│ ├── app/ # Next.js App Router
|
||
│ ├── components/ # React组件
|
||
│ │ ├── ui/ # 基础UI组件
|
||
│ │ ├── layout/ # 布局组件
|
||
│ │ ├── sections/ # 页面区块组件
|
||
│ │ ├── effects/ # 视觉效果组件
|
||
│ │ ├── admin/ # 管理后台组件
|
||
│ │ └── analytics/ # 分析组件
|
||
│ ├── lib/ # 工具函数和库
|
||
│ ├── db/ # 数据库相关
|
||
│ ├── hooks/ # 自定义Hooks
|
||
│ ├── contexts/ # React Context
|
||
│ └── types/ # TypeScript类型定义
|
||
├── e2e/ # E2E测试（Playwright）
|
||
├── docs/ # 项目文档
|
||
│ ├── architecture/ # 架构文档
|
||
│ ├── development/ # 开发文档
|
||
│ ├── deployment/ # 部署文档
|
||
│ ├── testing/ # 测试文档
|
||
│ ├── api/ # API文档
|
||
│ └── guides/ # 使用指南
|
||
├── scripts/ # 脚本文件
|
||
│ ├── deployment/ # 部署脚本
|
||
│ ├── monitoring/ # 监控脚本
|
||
│ ├── testing/ # 测试脚本
|
||
│ ├── maintenance/ # 维护脚本
|
||
│ └── utils/ # 工具脚本
|
||
├── config/ # 配置文件
|
||
│ ├── ci/ # CI/CD配置
|
||
│ ├── lint/ # 代码检查配置
|
||
│ └── test/ # 测试配置
|
||
├── public/ # 静态资源
|
||
├── .github/ # GitHub配置
|
||
├── .woodpecker/ # Woodpecker配置
|
||
├── data/ # 数据文件
|
||
├── uploads/ # 上传文件
|
||
├── backups/ # 备份文件
|
||
└── reports/ # 测试报告
|
||
├── e2e/ # E2E测试报告
|
||
├── performance/ # 性能测试报告
|
||
└── coverage/ # 代码覆盖率报告
|
||
```
|
||
|
||
### 2. 文档目录结构
|
||
|
||
```
|
||
docs/
|
||
├── README.md # 文档导航
|
||
├── architecture/
|
||
│ ├── system-design.md # 系统设计
|
||
│ ├── database-schema.md # 数据库架构
|
||
│ └── api-architecture.md # API架构
|
||
├── development/
|
||
│ ├── getting-started.md # 快速开始
|
||
│ ├── coding-standards.md # 编码规范
|
||
│ ├── component-guide.md # 组件开发指南
|
||
│ └── debugging-guide.md # 调试指南
|
||
├── deployment/
|
||
│ ├── production.md # 生产环境部署
|
||
│ ├── docker.md # Docker部署
|
||
│ └── monitoring.md # 监控配置
|
||
├── testing/
|
||
│ ├── testing-strategy.md # 测试策略
|
||
│ ├── e2e-testing.md # E2E测试
|
||
│ ├── unit-testing.md # 单元测试
|
||
│ └── performance-testing.md # 性能测试
|
||
├── api/
|
||
│ ├── rest-api.md # REST API
|
||
│ └── admin-api.md # 管理API
|
||
└── guides/
|
||
├── cms-guide.md # CMS使用指南
|
||
├── authentication.md # 认证指南
|
||
└── troubleshooting.md # 故障排查
|
||
```
|
||
|
||
### 3. 脚本目录结构
|
||
|
||
```
|
||
scripts/
|
||
├── deployment/
|
||
│ ├── deploy-production.sh # 部署生产环境
|
||
│ ├── backup.sh # 备份数据
|
||
│ └── restore.sh # 恢复数据
|
||
├── monitoring/
|
||
│ ├── setup-monitoring.sh # 设置监控
|
||
│ ├── start-monitoring.sh # 启动监控
|
||
│ └── check-monitoring.sh # 检查监控
|
||
├── testing/
|
||
│ ├── test-contact-page.sh # 测试联系页面
|
||
│ └── verify-tiered-testing.sh # 验证分层测试
|
||
├── maintenance/
|
||
│ ├── fix-dev-server.sh # 修复开发服务器
|
||
│ └── fix-login-issue.sh # 修复登录问题
|
||
└── utils/
|
||
├── check-color-contrast.ts # 检查颜色对比度
|
||
├── check-heading-hierarchy.ts # 检查标题层级
|
||
├── validate-woodpecker-config.js # 验证Woodpecker配置
|
||
└── coverage-trend.js # 覆盖率趋势
|
||
```
|
||
|
||
### 4. 配置文件整合
|
||
|
||
```
|
||
config/
|
||
├── ci/
|
||
│ ├── github/ # GitHub Actions配置
|
||
│ └── woodpecker/ # Woodpecker配置
|
||
├── lint/
|
||
│ ├── .eslintrc.json # ESLint配置
|
||
│ ├── .prettierrc # Prettier配置
|
||
│ └── commitlint.config.js # Commitlint配置
|
||
└── test/
|
||
├── playwright.config.ts # Playwright配置
|
||
└── jest.config.js # Jest配置
|
||
```
|
||
|
||
## 迁移计划
|
||
|
||
### 阶段1：创建新目录结构
|
||
|
||
- [ ] 创建docs目录结构
|
||
- [ ] 创建scripts子目录
|
||
- [ ] 创建config目录
|
||
- [ ] 创建reports目录
|
||
|
||
### 阶段2：迁移文档文件
|
||
|
||
- [ ] 移动架构文档到docs/architecture/
|
||
- [ ] 移动开发文档到docs/development/
|
||
- [ ] 移动部署文档到docs/deployment/
|
||
- [ ] 移动测试文档到docs/testing/
|
||
- [ ] 移动API文档到docs/api/
|
||
|
||
### 阶段3：整理脚本文件
|
||
|
||
- [ ] 分类移动脚本文件到scripts子目录
|
||
- [ ] 统一脚本命名规范
|
||
- [ ] 为每个脚本添加文档说明
|
||
|
||
### 阶段4：整合配置文件
|
||
|
||
- [ ] 移动CI/CD配置到config/ci/
|
||
- [ ] 移动代码检查配置到config/lint/
|
||
- [ ] 移动测试配置到config/test/
|
||
|
||
### 阶段5：清理临时文件
|
||
|
||
- [ ] 移动测试报告到reports/
|
||
- [ ] 清理临时文件
|
||
- [ ] 更新.gitignore
|
||
|
||
### 阶段6：更新引用
|
||
|
||
- [ ] 更新所有文件引用路径
|
||
- [ ] 更新package.json脚本
|
||
- [ ] 更新CI/CD配置
|
||
|
||
## 注意事项
|
||
|
||
1. **保持向后兼容**: 迁移过程中确保所有功能正常工作
|
||
2. **分步执行**: 每个阶段完成后进行验证
|
||
3. **备份重要文件**: 迁移前备份重要配置和数据
|
||
4. **更新文档**: 及时更新相关文档
|
||
5. **团队沟通**: 重大变更需要团队review
|
||
|
||
## 预期效果
|
||
|
||
### 代码组织
|
||
|
||
- ✅ 清晰的目录结构
|
||
- ✅ 合理的文件分类
|
||
- ✅ 统一的命名规范
|
||
|
||
### 开发效率
|
||
|
||
- ✅ 快速定位文件
|
||
- ✅ 减少查找时间
|
||
- ✅ 提高开发效率
|
||
|
||
### 团队协作
|
||
|
||
- ✅ 统一的代码组织
|
||
- ✅ 清晰的文档结构
|
||
- ✅ 降低学习成本
|
||
|
||
### 维护性
|
||
|
||
- ✅ 易于维护
|
||
- ✅ 易于扩展
|
||
- ✅ 易于重构
|
||
|
||
## 实施时间
|
||
|
||
- 阶段1: 15分钟
|
||
- 阶段2: 20分钟
|
||
- 阶段3: 15分钟
|
||
- 阶段4: 10分钟
|
||
- 阶段5: 10分钟
|
||
- 阶段6: 15分钟
|
||
|
||
**总计: ~85分钟**
|
||
|
||
## 风险评估
|
||
|
||
### 高风险
|
||
|
||
- 更新文件引用路径可能导致构建错误
|
||
|
||
### 中风险
|
||
|
||
- 迁移配置文件可能影响CI/CD流程
|
||
|
||
### 低风险
|
||
|
||
- 创建新目录结构
|
||
- 移动文档文件
|
||
- 整理脚本文件
|
||
|
||
### 缓解措施
|
||
|
||
1. 逐步迁移，每步验证
|
||
2. 保留备份，便于回滚
|
||
3. 充分测试，确保功能正常
|
||
4. 团队review，减少错误
|