user-system/docs/PROJECT_STRUCTURE.md

项目目录结构规范

目录结构

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 规范

# 编译产物
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/