# 目录结构规范化方案

## 目标

建立清晰、规范的目录结构，符合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，减少错误