diff --git a/AGENT.md b/AGENT.md
new file mode 100644
index 0000000..f701e42
--- /dev/null
+++ b/AGENT.md
@@ -0,0 +1,67 @@
+# 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` 结算、自动发奖、失败补发执行的唯一执行方。
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..705d636
--- /dev/null
+++ b/README.md
@@ -0,0 +1,180 @@
+# 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`
+- 只做启动和依赖装配。
+- 不承担业务逻辑。
+- 不启动任何 `weekstar` 结算 goroutine。
+
+### 2. `cmd/consumer`
+- 只做事件消费任务启动和优雅退出。
+- 当前承接：
+  - `registerreward` 的 Redis Stream 消费
+  - `weekstar` 的 RocketMQ 消费
+
+### 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 ./...
+```