109 lines
6.9 KiB
Markdown
109 lines
6.9 KiB
Markdown
---
|
||
name: soul-api-dev
|
||
description: 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 一起防止互窜。
|