项目/
├── .github/
│ └── workflows/ # CI/CD 自动化流水线配置
├── api/
│ └── v1/ # OpenAPI 规范、Protobuf 等接口契约定义
├── cmd/
│ ├── cron/ # 独立入口：定时任务/跑批程序
│ │ └── main.go
│ └── server/ # 独立入口：主服务 (API & Bot)
│ ├── main.go # 纯净的启动函数
│ └── wire.go # (可选) Google Wire 依赖注入配置
├── configs/
│ ├── loader/ # 配置加载器 (封装 Viper，支持 Env/YAML 读取)
│ ├── config.go # 强类型的全局配置结构体定义
│ └── config.example.yaml # 配置文件模板 (开发环境使用)
├── deployments/
│ ├── docker-compose.yml # 本地/测试环境的容器编排
│ └── Dockerfile # 生产环境的多阶段构建配置
├── docs/
│ ├── api/ # Swagger 等 API 说明文档
│ └── development/ # 团队开发指南、环境搭建文档
├── internal/ # 🌟 核心业务层 (外部项目不可见)
│ ├── bot/ # Telegram 机器人交互、事件监听与分发
│ ├── domain/ # 核心业务实体 (Entity)、通用数据结构定义
│ ├── handler/ # HTTP 请求处理层 (Controller)
│ ├── metrics/ # 可观测性：Prometheus 监控指标与 Tracing
│ ├── middleware/ # 拦截器：Auth(鉴权), CORS(跨域), I18n(多语言)
│ ├── repository/ # 数据访问层：MySQL/Redis/MongoDB 各种具体操作
│ ├── service/ # 核心业务逻辑层 (协调 Repository 和 Bot)
│ └── pkg/ # 🔧 内部共享组件
│ ├── errors/ # 统一业务错误码与错误处理定义
│ ├── i18n/ # 国际化解析引擎
│ ├── logger/ # 日志库封装 (Zap/Slog)
│ ├── response/ # 统一 JSON 输出封装 (Success/Error/Page)
│ └── validator/ # 参数校验器封装
├── locales/
│ ├── en-US.yaml # 英文翻译文本
│ └── zh-CN.yaml # 中文翻译文本
├── migrations/ # 数据库 Schema 版本迁移脚本 (00001_init.up.sql)
├── pkg/ # (预留) 确认可以开源或给其他项目引用的底层通用库
├── third_party/ # 外部第三方资源 (如 Swagger UI 静态文件)
├── .editorconfig # 统一团队编辑器格式规范
├── .gitignore # Git 忽略文件配置
├── .golangci.yml # 代码静态检查器配置
├── Makefile # 快捷指令集 (make run, make build, make lint)
├── go.mod # 模块依赖管理
├── go.sum
└── README.md # 项目概览与快速启动说明