初始提交：一场soul的创业实验-永平 网站与小程序

Made-with: Cursor

soul-api/开发文档/miniprogram接口补全说明.md

@@ -0,0 +1,55 @@
+# soul-api 小程序接口补全说明
+
+## 变更背景
+
+miniprogram 功能还原后，需将 VIP 相关接口从 `/api/vip/*` 迁移至 `/api/miniprogram/vip/*`，并补充 miniprogram 组下的 users 接口，符合项目边界（小程序只调 `/api/miniprogram/*`）。
+
+## 新增接口
+
+### 1. VIP 接口（handler/vip.go）
+
+| 路径 | 方法 | Handler | 用途 |
+|------|------|---------|------|
+| `/api/miniprogram/vip/status` | GET | VipStatus | 查询用户 VIP 状态 |
+| `/api/miniprogram/vip/profile` | GET | VipProfileGet | 获取 VIP 资料 |
+| `/api/miniprogram/vip/profile` | POST | VipProfilePost | 更新 VIP 资料 |
+| `/api/miniprogram/vip/members` | GET | VipMembers | VIP 会员列表或单个 |
+
+**实现说明**：
+- **status**：按 orders 表查 `product_type IN ('fullbook','vip')` 且 `status='paid'` 判断是否 VIP；返回 `isVip`、`daysRemaining`、`expireDate`、`price`
+- **profile**：GET 从 users 表读 nickname、phone；POST 更新 nickname、phone
+- **members**：无 `?id` 时返回有 fullbook/vip 订单的用户列表；有 `?id` 时返回单个用户，含 `vip_name`、`vip_avatar`、`vip_contact`、`is_vip` 等字段
+
+### 2. 用户接口（handler/miniprogram.go）
+
+| 路径 | 方法 | Handler | 用途 |
+|------|------|---------|------|
+| `/api/miniprogram/users` | GET | MiniprogramUsers | 用户列表或单个 |
+
+**实现说明**：
+- `?limit=20`：返回用户列表，用于首页「超级个体」不足 4 人时的补充
+- `?id=xxx`：返回单个用户，用于会员详情页在 vip/members 失败时的回退
+- 返回格式：`{ success, data }`，与 miniprogram 期望一致
+
+## 已有接口（无需变更）
+
+以下接口已在 miniprogram 组挂载，miniprogram 已正确调用：
+
+- `/api/miniprogram/book/all-chapters`
+- `/api/miniprogram/book/chapter/:id`
+- `/api/miniprogram/book/chapter/by-mid/:mid`
+- `/api/miniprogram/book/hot`
+- `/api/miniprogram/book/search`
+- `/api/miniprogram/book/stats`
+
+## 路由注册位置
+
+`internal/router/router.go` 中 miniprogram 组末尾：
+
+```go
+miniprogram.GET("/vip/status", handler.VipStatus)
+miniprogram.GET("/vip/profile", handler.VipProfileGet)
+miniprogram.POST("/vip/profile", handler.VipProfilePost)
+miniprogram.GET("/vip/members", handler.VipMembers)
+miniprogram.GET("/users", handler.MiniprogramUsers)
+```