# chatapp3-golang Agent Guide

## 目标
- 这个仓库现在按模块组织，新增功能时不要再把代码堆回平铺目录。
- 路由、业务、工具函数、共享类型要分层放置，优先保持“一个文件只表达一个明确职责”。

## 目录约定
- `cmd/api`
  - 仅负责启动、依赖组装、优雅退出。
- `cmd/consumer`
  - 仅负责事件消费任务启动、优雅退出。
  - 当前只承接 `registerreward` Redis Stream 与 `weekstar` RocketMQ 消费。
- `internal/bootstrap`
  - 负责配置加载、存储初始化、Java 网关装配。
  - `api` 与 `consumer` 统一复用，不要重复写一份启动拼装逻辑。
- `internal/router`
  - 只负责 HTTP 路由注册、请求绑定、中间件、统一响应。
  - 每个模块单独一个 `*_routes.go` 文件。
- `internal/service/<module>`
  - 每个业务模块一个目录。
  - `types.go` 放服务结构体、常量、DTO、内部类型。
  - 模块内辅助函数不要再统一塞进 `utils.go`，而是按语义放进 `normalize.go`、`stream.go`、`mapper.go`、`convert.go` 这类文件。
  - 业务按职责拆文件，例如 `config.go`、`page.go`、`callback.go`、`reward.go`、`consumer.go`。
  - 一个文件只保留一类逻辑，不要再出现“一个文件承接整个模块所有流程”的写法。
- `internal/common`
  - 放跨模块共享的类型，比如 `AppError`、`AuthUser`。
- `internal/utils`
  - 放跨模块复用的通用工具函数。
- `internal/model`
  - 只放 Gorm 模型和表结构映射。
  - 模型按业务模块拆文件，例如 `invite_models.go`、`weekstar_models.go`、`luckygift_models.go`。
- `internal/integration`
  - 只放外部系统调用封装。
  - `integration.Client` 已按职责包装成多个 gateway，新增下游能力时优先按网关语义扩展。
- `internal/repo`
  - 只放基础存储初始化和仓储级装配。
  - 不要再把 schema 自动修正逻辑塞回启动流程，数据库变更统一走 `migrations/`。

## 编码规则
- 新增 helper 时，优先判断是不是“辅助函数”：
  - 模块内使用：放对应模块目录下有语义的文件名里，不要新增 `utils.go`
  - 跨模块复用：放 `internal/utils`
- 不要在 router 里写业务判断，不要在 service 里拼 HTTP 响应。
- 不要把不同模块的 request / response / callback DTO 混放到一个文件里。
- 不要把配置查询、榜单查询、MQ 消费、发奖、回调处理重新揉回一个文件。
- 新增路由时，先在 `internal/router` 下新建模块路由文件，再在 `router.go` 里挂载。
- `weekstar` 自动结算和自动发奖已经迁到 `chatapp-cron`，不要在这个仓库重新引入任何 scheduler/settlement runner。

## 提交前检查
- `goimports -w` 涉及 Go 文件
- `gofmt -w` 涉及文件
- `go test ./...`
- 确认没有把模块 helper 又写回逻辑文件

## 当前模块
- `invite`
- `baishun`
- `luckygift`
- `registerreward`
- `weekstar`

## 运行边界
- `chatapp3-golang`
  - 负责 HTTP API 与事件消费。
  - 不负责 `weekstar` 周期结算扫描、快照冻结、自动发奖、失败补发执行。
- `chatapp-cron`
  - 是 `weekstar` 结算、自动发奖、失败补发执行的唯一执行方。