# chatapp3-golang

## 现在的结构

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

```text
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` 的 RocketMQ 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` 统一注入：

```go
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`
  - 只放跨模块通用工具，不放业务逻辑

## 当前模块文件示例

```text
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` 之类的运行职责。

## 本地检查

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

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

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