soul-yongping/.cursor/skills/api-dev/SKILL.md

name, description

name	description
soul-api-dev	Soul 创业派对后端 API 开发规范。在 soul-api/ 下编辑时必遵循。Go、Gin、GORM、路由分组 miniprogram/admin/db、响应格式。Use when editing soul-api, 后端, API, Go.

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

当你在 soul-api/ 目录下新增、优化或编辑 Go 代码时，必须遵循本 Skill。本 Skill 与 .cursor/rules/soul-api.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。即使业务逻辑完全相同，也必须按使用方做路径区分，禁止仅提供 /api/xxx 等通用路径让两端混用。例如 VIP 相关接口，若两端都要用，应提供 /api/admin/vip/*（或 /api/db/vip/*）和 /api/miniprogram/vip/*，可复用同一 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.2 新增表/字段完整流程（吸收 vip_roles 经验）

步骤	动作
1	在 internal/model/ 新建 xxx.go，定义结构体与 TableName()
2	在 internal/database/database.go 中 AutoMigrate(&model.Xxx{})
3	在 soul-api/scripts/ 编写迁移 SQL（CREATE TABLE IF NOT EXISTS、ALTER TABLE ADD COLUMN、INSERT IGNORE 默认数据）
4	新建 internal/handler/xxx.go 实现 CRUD（GET 列表、POST 新增、PUT 更新、DELETE 删除）
5	在 router.go 的 db 组下注册：db.GET("/xxx", handler.DBXxxList)、db.POST/PUT/DELETE("/xxx", handler.DBXxxAction)
6	部署前执行迁移脚本：mysql -u user -p db < soul-api/scripts/add-xxx.sql

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> 一致。

列表接口约定：管理端列表必须支持：

• 分页：page、pageSize 查询参数，返回 total、page、pageSize、totalPages
• 筛选：status、matchType、search、vip 等按业务
• 响应格式：{ success, records/users/orders/..., total, page, pageSize, totalPages }
• 错误：{ success: false, error: "..." }

已实现分页的接口：/api/db/users、/api/orders、/api/admin/withdrawals、/api/db/distribution、/api/db/match-records。详见 开发文档/列表标准与角色分工.md。

• 不要：在 miniprogram 组挂仅 admin 使用的接口；在 admin 组挂小程序专属逻辑；在 handler 内混用「管理端路径」与「小程序路径」的语义。

---

7. 何时使用本 Skill

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

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