Soul 创业派对 - API 开发 Skill（soul-api）

当你在 soul-api/ 目录下新增、优化或编辑 Go 代码时，必须遵循本 Skill。本 Skill 与 .cursor/rules/soul-api-coding.mdc 一致并做归纳，重点强调「按使用方归类路由」和「与 miniprogram / soul-admin 的边界」，防止接口互窜。

1. 项目定位与边界

soul-api：Go + Gin + GORM 的后端 API，同时服务 小程序 和 管理端。
路由分组：
- 管理端：/api/admin/*、/api/db/*，鉴权 middleware.AdminAuth()。
- 小程序：/api/miniprogram/*，按接口需要 token 或 openId。
- 禁止：管理端专用逻辑不得挂到 miniprogram 组；小程序专用逻辑不得只挂在 admin/db 下；两端共用的接口在 router 里两处注册（api 下 + miniprogram 下同 path）。

2. 接口按使用方归类（防互窜）

使用方	路由组	路径前缀	鉴权
管理端	admin	`/api/admin/...`	`AdminAuth()`
管理端数据	db	`/api/db/...`	`AdminAuth()`
小程序	miniprogram	`/api/miniprogram/...`	按需 token/openId

仅管理端用的接口：只挂在 admin 或 db，不要出现在 miniprogram。
仅小程序用的接口：只挂在 miniprogram（如小程序登录、支付、提现、小程序码、推荐绑定等）。
两端共用：在 api 下挂一份，再在 miniprogram 组里用同 handler 挂一遍，保证小程序统一走 /api/miniprogram/xxx；handler 注释标明使用方。

新增或修改接口时：先确定使用方（小程序 / 管理端 / 共用） → 再决定挂到哪个 Group → 再实现 handler。

3. 数据访问与 Model

一律使用 GORM，通过 database.DB() 获取 *gorm.DB；禁止在 handler 中手写裸 SQL（除文档允许的少数统计等例外）。
事务：多表写入（支付回调、分佣、订单+用户）必须用 db.Transaction 包裹。
Preload / Joins / Pluck：列表带关联用 Preload 或 Joins 减少 N+1；单列用 Pluck 替代 Raw；复杂条件抽 Scopes。
Model：所有表对应结构体在 internal/model，带 gorm 与 json 标签；不对外暴露字段用 json:"-"。
配置：仅通过 internal/config 的 Load() 读环境变量；业务代码不直接 os.Getenv。

3.1 依赖物尽其用（补充）

依赖	用途	约定
Gin	路由、绑定、响应	`ShouldBindJSON` + `binding:"required"` 等；金额 `gte=0`、手机号 `len=11`、`email` 等
GORM	数据访问	Transaction、Preload、Pluck、Scopes、Joins；原子更新用 `gorm.Expr`
PowerWeChat	微信/支付/转账	统一走 `internal/wechat`，handler 只做参数转换
JWT	管理端鉴权	用 `internal/auth`，不手写解析
中间件	安全、跨域、限流	Secure、cors、RateLimiter；新路由挂到已有 Group
Redis	缓存（可选）	当前未用；若引入需统一封装

4. 响应与错误

统一：成功 gin.H{"success": true, "data": ...} 或带 message；失败 gin.H{"success": false, "error": "..."} 或 message。
不吞错：DB/微信返回的 err 必须处理，并向前端返回明确错误或打日志。
HTTP 状态码：业务错误可 200 + success: false；未授权/禁止用 401/403。

5. 目录与包约定

cmd/server/main.go：入口，只做 config/database/wechat/router 初始化与启停。
internal/handler：HTTP 处理，只做绑定、校验、调 DB/wechat、写响应；复杂逻辑可抽到 internal/service。
internal/router：注册路由与中间件；新增路由按「使用方」挂到 admin / db / miniprogram 或 api+miniprogram。
微信/支付/转账：统一走 internal/wechat 封装，handler 只做参数与结果转换。

6. 与小程序、管理端的对接要点

小程序：只认 /api/miniprogram/*；登录、书籍、支付、提现、推荐、用户等均在该组下；返回字段与小程序 app.request 解析一致（success、data、error/message）。
管理端：只认 /api/admin/*、/api/db/* 等；列表接口需包含管理端所需字段（如 user_name/userNickname、userAvatar、status、amount）；鉴权用 JWT，与 soul-admin 的 Authorization: Bearer <admin_token> 一致。
不要：在 miniprogram 组挂仅 admin 使用的接口；在 admin 组挂小程序专属逻辑；在 handler 内混用「管理端路径」与「小程序路径」的语义。

7. 何时使用本 Skill

在 soul-api/ 下新增或修改路由、handler、model、config、wechat 时。
新增任何 HTTP 接口时（必须先明确使用方再挂路由）。
修改与小程序或管理端对接的返回结构或鉴权方式时。

遵循本 Skill 可保证 soul-api 路由清晰、使用方不混用，并与 miniprogram、soul-admin 的 Skills/Rules 一起防止互窜。

5.1 KiB Raw Blame History Unescape Escape