# 项目目录结构规范

## 目录结构

```
project-root/
├── .env.example              # 环境变量示例（必须）
├── .gitignore                # Git忽略规则（必须）
├── Makefile                  # 项目构建入口
├── README.md                 # 项目说明
├── go.mod / go.sum          # Go模块定义
├── go.work                   # Go workspace（多模块时）
│
├── bin/                      # 编译产物（二进制、可执行文件）
│   └── *.exe / main          # 禁止提交编译产物
│
├── cmd/                      # 应用入口（每个应用一个子目录）
│   └── server/               # 主服务器入口
│       └── main.go
│
├── internal/                 # 私有内部包（不可被外部导入）
│   ├── api/                  # API层
│   │   ├── handler/          # HTTP Handler
│   │   ├── middleware/       # 中间件
│   │   └── router/          # 路由
│   ├── auth/                 # 认证鉴权
│   ├── cache/                # 缓存
│   ├── config/               # 配置
│   ├── database/             # 数据库
│   ├── domain/               # 领域模型（实体、值对象）
│   ├── repository/           # 数据访问层
│   ├── service/              # 业务逻辑层
│   └── pkg/                  # 内部共享工具包
│       ├── errors/           # 错误定义
│       ├── response/         # 响应封装
│       └── ...
│
├── pkg/                      # 公共外部包（可被外部导入）
│   └── ...                   # 仅当需要作为独立库发布时使用
│
├── configs/                  # 配置文件（JSON/YAML/TOML）
├── deployment/               # 部署配置（Docker/K8s/Compose）
│   ├── docker-compose.yml
│   ├── kubernetes/
│   └── helm/
│
├── docs/                     # 项目文档
│   ├── guides/              # 使用指南
│   ├── design/              # 设计文档
│   ├── code-review/         # 代码审查报告
│   └── specs/               # 规格说明
│
├── frontend/                 # 前端代码
│   └── admin/               # 管理后台前端
│
├── scripts/                  # 脚本（按功能分类）
│   ├── dev/                 # 开发脚本
│   │   ├── run_tests.sh
│   │   └── check_gitea.sh
│   ├── deploy/              # 部署脚本
│   │   └── deploy_*.sh
│   ├── ops/                 # 运维脚本
│   │   └── sre-*.ps1
│   ├── test/                # 测试脚本
│   │   └── test_*.sh
│   └── chaos/               # 混沌工程脚本
│
├── tools/                    # 工具脚本（Python/Shell）
│   ├── db_check.go
│   └── *.py
│
├── data/                     # 运行时数据目录
│   └── *.db                  # SQLite数据库文件
│
├── logs/                     # 日志输出目录
│   └── *.log
│
├── migrations/               # 数据库迁移
│
├── testdata/                 # 测试数据
│
├── uploads/                  # 用户上传文件
│   └── avatars/              # 头像上传
│
└── runtime/                  # 运行时文件（pid/socket）
```

## 命名规范

### 目录命名
- 使用 **小写字母 + 中划线** 或 **小写字母**（无特殊字符）
- 示例：`code-review`, `test-data`, `scripts`

### 文件命名
| 类型 | 规范 | 示例 |
|------|------|------|
| Go源文件 | `snake_case.go` | `user_service.go` |
| 测试文件 | `*_test.go` | `user_service_test.go` |
| 配置文件 | `snake_case.json/yaml/toml` | `database_config.yaml` |
| 脚本文件 | `snake_case.sh/ps1/py` | `check_gitea.sh` |
| Markdown | `snake_case.md` 或 ` kebab-case.md` | `api_design.md` |

## 文件放置规则

### 禁止在根目录放置的文件
- ❌ `*.exe`, `*.dll`, `*.so` （编译产物 → `bin/`）
- ❌ `*_result.txt`, `*_test.txt`, `*_output.log` （临时输出 → 删除）
- ❌ `*.tmp`, `*.log` （运行时文件 → 对应目录）
- ❌ `server.exe`, `ums.exe` （可执行文件 → `bin/`）
- ❌ `upload.json`, `debug.log` （临时文件 → 删除）

### 必须放置根目录的文件
- ✅ `go.mod`, `go.sum` （Go项目标识）
- ✅ `.gitignore` （Git配置）
- ✅ `.env.example` （环境变量模板）

### 脚本放置规则
| 脚本类型 | 放置位置 |
|----------|----------|
| 开发辅助 | `scripts/dev/` |
| 部署相关 | `scripts/deploy/` |
| 运维监控 | `scripts/ops/` |
| 测试相关 | `scripts/test/` |
| 混沌工程 | `scripts/chaos/` |

## .gitignore 规范

```gitignore
# 编译产物
bin/
*.exe
*.dll
*.so

# 运行时数据
*.db
*.log
logs/
data/*.db

# 上传文件
uploads/avatars/*
!uploads/avatars/.gitkeep

# 临时文件
*.tmp
*.temp
*_result.txt
*_test*.txt
*_output.txt

# 环境配置
.env
.env.local

# IDE
.idea/
.vscode/
*.swp

# 系统文件
.DS_Store
Thumbs.db

# Go
.gocache/
.gomodcache/
```

## 新增目录检查清单

添加新目录前，确认：

1. **是否有必要？** 能用现有目录表达吗？
2. **符合命名规范？** 小写字母、中划线分隔
3. **放置位置正确？** 对应到上表的位置
4. **是否需要版本控制？** `data/`、`logs/`、`uploads/` 通常不提交

## 常见错误

| 错误 | 正确做法 |
|------|----------|
| 在根目录放置 `test_output.txt` | 删除或放到 `scripts/test/` |
| 在根目录放置 `server.exe` | 移动到 `bin/` |
| 创建 `internal/utils/` | 使用现有 `internal/pkg/` |
| 创建 `pkg/response/` | 使用 `internal/pkg/response/` |