docs: 添加项目结构规范文档

新增: - docs/PROJECT_STRUCTURE.md - 完整目录结构规范 - data/.gitkeep, logs/.gitkeep, testdata/.gitkeep, uploads/avatars/.gitkeep 更新: - .gitignore 添加临时文件规则 (*_result.txt, *_test*.txt 等) - .gitignore 添加 uploads/avatars/ 内容忽略规则
2026-04-07 19:00:51 +08:00
parent 5b6bd93179
commit 6b2b450e91
6 changed files with 201 additions and 0 deletions
--- a/docs/PROJECT_STRUCTURE.md
+++ b/docs/PROJECT_STRUCTURE.md
@@ -0,0 +1,186 @@
+# 项目目录结构规范
+
+## 目录结构
+
+```
+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/` |