68 lines
3.2 KiB
Markdown
68 lines
3.2 KiB
Markdown
# 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` 结算、自动发奖、失败补发执行的唯一执行方。
|