yumi-golang/AGENT.md

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 结算、自动发奖、失败补发执行的唯一执行方。