张翔
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
8.3 KiB
8.3 KiB
目录结构规范化方案
目标
建立清晰、规范的目录结构，符合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配置
注意事项
- 保持向后兼容: 迁移过程中确保所有功能正常工作
- 分步执行: 每个阶段完成后进行验证
- 备份重要文件: 迁移前备份重要配置和数据
- 更新文档: 及时更新相关文档
- 团队沟通: 重大变更需要团队review
预期效果
代码组织
- ✅ 清晰的目录结构
- ✅ 合理的文件分类
- ✅ 统一的命名规范
开发效率
- ✅ 快速定位文件
- ✅ 减少查找时间
- ✅ 提高开发效率
团队协作
- ✅ 统一的代码组织
- ✅ 清晰的文档结构
- ✅ 降低学习成本
维护性
- ✅ 易于维护
- ✅ 易于扩展
- ✅ 易于重构
实施时间
- 阶段1: 15分钟
- 阶段2: 20分钟
- 阶段3: 15分钟
- 阶段4: 10分钟
- 阶段5: 10分钟
- 阶段6: 15分钟
总计: ~85分钟
风险评估
高风险
- 更新文件引用路径可能导致构建错误
中风险
- 迁移配置文件可能影响CI/CD流程
低风险
- 创建新目录结构
- 移动文档文件
- 整理脚本文件
缓解措施
- 逐步迁移，每步验证
- 保留备份，便于回滚
- 充分测试，确保功能正常
- 团队review，减少错误