yumi-golang/README.md

chatapp3-golang

现在的结构

项目已经从平铺结构调整为按模块组织，并把运行职责拆成了 api 与 consumer 两个入口：

cmd/api
cmd/consumer
internal/bootstrap
internal/common
internal/config
internal/integration
internal/model
internal/repo
internal/router
internal/service/baishun
internal/service/invite
internal/service/luckygift
internal/service/registerreward
internal/service/weekstar
internal/utils

每个业务模块都已经拆成独立目录，router 也改成模块化注册，不再把所有处理器和平铺 service 混在一起。weekstar 的自动结算、自动发奖和失败补发执行已经迁到 chatapp-cron，当前仓库只保留 API、实时积分消费、查询和失败补发任务投递能力。

分层说明

1. cmd/api

• 只做启动和依赖装配。
• 不承担业务逻辑。
• 当前线上只部署 golang API 进程，所以这里会同时启动 registerreward 的 Redis Stream consumer，确保注册成功事件能被消费并发奖。
• 不启动任何 weekstar 结算 goroutine。

2. cmd/consumer

• 只做事件消费任务启动和优雅退出。
• 当前承接：
  • registerreward 的 Redis Stream 消费
  • weekstar 的 RocketMQ 消费
• 如果后续单独部署 consumer，registerreward 使用同一个 Redis consumer group，重复启动不会重复发奖。

3. internal/bootstrap

• 统一完成配置加载、存储初始化、依赖探活、Java 网关装配。
• cmd/api 与 cmd/consumer 共用这层，避免两份入口各自维护初始化逻辑。

4. internal/router

• 路由按模块拆分。
• router.go 只负责创建 Gin Engine 和统一挂载模块路由。
• invite_routes.go、week_star_routes.go、baishun_routes.go、lucky_gift_routes.go 分别负责各自模块。
• middleware.go、response.go 放公共中间件和统一响应。

5. internal/service/<module>

• 每个业务模块一个目录，避免所有逻辑堆在同一个 service 包里。
• types.go 只放服务结构、常量、DTO、内部类型。
• 业务层只依赖模块自己的 DB/Redis/gateway ports，不再直接依赖大一统 repo.Repository 或 integration.Client。
• 业务流程按职责继续拆文件，例如：
  • weekstar/config.go
  • weekstar/page.go
  • weekstar/reward_retry.go
  • registerreward/consumer.go
  • baishun/callback.go
  • invite/recharge.go
• 当前模块：
  • invite
  • baishun
  • luckygift
  • registerreward
  • weekstar

6. internal/common

• 放跨模块共享结构。
• 当前包含：
  • AppError
  • AuthUser

7. internal/utils

• 放跨模块通用工具。
• 当前保留雪花 ID 生成器。

8. internal/model

• 只放表结构映射，不再维护跨模块大文件。
• 当前已经按模块拆分：
  • common_models.go
  • invite_models.go
  • registerreward_models.go
  • weekstar_models.go
  • luckygift_models.go
  • baishun_models.go

9. internal/integration

• Java 调用已经从单一 Client 继续下沉为多个职责网关：
  • Auth
  • Device
  • InviteCode
  • RewardDispatch
  • RewardQuery
  • Profile
  • Wallet

路由装配方式

在 cmd/api/main.go 里先通过 bootstrap 组装基础依赖，再创建 service，通过 router.Services 统一注入：

engine := router.NewRouter(app.Config, app.Repository, &app.Gateways, router.Services{
    Invite:    inviteService,
    Baishun:   baishunService,
    LuckyGift: luckyGiftService,
    WeekStar:  weekStarService,
})

这样做的好处是：

• 入口依赖一眼可见
• router 不再直接依赖平铺 service 包
• 后续拆模块时不会改爆主入口

现在的拆分原则

• router
  • 一个模块一个路由文件
  • 公共响应、鉴权、中间件单独放公共文件
• service
  • 一个模块一个目录
  • 一个文件只负责一类逻辑
  • 模块内辅助函数使用有语义的文件名，不再新增 utils.go
• common
  • 放跨模块共享对象，例如 AppError、AuthUser
• utils
  • 只放跨模块通用工具，不放业务逻辑

当前模块文件示例

internal/service/weekstar/
  aliases.go
  config.go
  cycle.go
  event.go
  lifecycle.go
  mapper.go
  page.go
  reward_retry.go
  types.go

internal/service/invite/
  bind.go
  home.go
  landing.go
  normalize.go
  recharge.go
  reward.go
  store.go
  task.go
  types.go

运行职责

• chatapp3-golang
  • 负责 HTTP API
  • 负责事件消费
  • 负责 weekstar 配置、实时榜单、快照/发奖记录查询、失败补发任务投递
• chatapp-cron
  • 是 weekstar 周期结算扫描、快照冻结、自动发奖、失败补发执行的唯一执行方

因此当前仓库里不要再新增任何 scheduler、settlement loop、start settlement worker 之类的运行职责。

本地检查

$(go env GOPATH)/bin/goimports -w cmd internal
go test ./...

如果有结构调整，提交前建议再跑一遍：

$(go env GOPATH)/bin/goimports -w cmd internal
gofmt -w cmd internal
go test ./...