更新开发文档,强调接口路径必须按使用方区分,禁止通用路径混用。新增小程序分享功能,统一使用推荐码,确保用户体验一致性。

This commit is contained in:
Alex-larget
2026-02-25 11:47:36 +08:00
parent 8e4d61e22b
commit 52c5a8abab
145 changed files with 20844 additions and 30 deletions

View File

@@ -61,6 +61,12 @@ alwaysApply: false
- **两端共用的接口**:在 `router.go` 里两处都注册同一 handler先写在 `api` 的对应区块(如「推荐」「用户」),再在 `// ----- 小程序组 -----` 里用 `miniprogram.GET/POST(... path, handler.XXX)` 挂一遍,保证小程序统一走 `/api/miniprogram/xxx`。
- handler 注释和路由注释中标明使用方,例如:`// GET /api/miniprogram/withdraw/records 小程序-提现记录`、`// GET /api/admin/withdrawals 管理端-提现列表`。
**工程师必守:即使业务逻辑完全相同,也必须按使用方做路径区分。** 例如 VIP 相关接口status、profile、members 等),若小程序和管理端都要用:
- 管理端:`/api/admin/vip/*` 或 `/api/db/vip/*`
- 小程序:`/api/miniprogram/vip/*`(可复用同一 handler但路径必须显式挂到 miniprogram 组)
禁止仅提供 `/api/vip/*` 等「通用路径」让两端混用,违反项目边界。
**管理端列表接口返回约定**:列表类接口(如 withdrawals、orders、users的响应应包含 soul-admin 通用展示所需字段:`user_name` 或 `userNickname`、`userAvatar`、`status`、`amount`(金额用数字)。提现状态:数据库存值 `pending`/`processing`/`success`/`failed`,前端展示可映射 `success`→`completed`、`failed`→`rejected`。
## 5. 目录与包约定