soul-yongping/开发文档/三端需求业务对齐-小程序与API.md

# Soul 创业派对 - 三端需求业务对齐（小程序 ↔ API）

> 供小程序、后端 API、管理端工程师需求与业务对齐使用。  
> 更新日期：2026-02-25

---

## 一、小程序功能模块总览

| 模块 | 页面 | 功能简述 |
|------|------|----------|
| **首页** | index | 精选推荐、最新章节、超级个体（VIP 展示）、跳转目录/搜索/找伙伴/我的 |
| **目录** | chapters | 全书目录、每日新增、跳转阅读/搜索 |
| **阅读** | read | 章节内容、权限判断、购买、分享、海报、推荐码 |
| **找伙伴** | match | 匹配配置、随机匹配、加入弹窗、购买匹配次数 |
| **我的** | my | 用户信息、收益、提现、VIP 状态、设置入口 |
| **分销中心** | referral | 绑定/访问/收益、提现、小程序码、分享 |
| **购买记录** | purchases | 当前用户订单列表 |
| **设置** | settings | 昵称/头像/手机/微信/支付宝、退出登录 |
| **地址管理** | addresses, edit | 收货地址 CRUD |
| **提现记录** | withdraw-records | 提现列表、确认收款 |
| **VIP** | vip | VIP 状态、购买、资料编辑 |
| **会员详情** | member-detail | 创业者详情（VIP/普通用户） |
| **搜索** | search | 热门、关键词搜索章节 |
| **关于** | about | 书籍统计、联系 |
| **协议** | agreement, privacy | 用户协议、隐私政策 |

---

## 二、小程序 API 调用清单（按页面）

### 2.1 已正确使用 `/api/miniprogram/*` 的接口

| 页面/模块 | 路径 | 方法 | 用途 |
|-----------|------|------|------|
| app | /api/miniprogram/referral/visit | POST | 推荐访问记录 |
| app | /api/miniprogram/referral/bind | POST | 推荐码绑定 |
| app | /api/miniprogram/book/all-chapters | GET | 书籍目录 |
| app | /api/miniprogram/login | POST | 微信登录 |
| app | /api/miniprogram/phone-login | POST | 手机号登录 |
| config | /api/miniprogram/config | GET | 免费章节、价格、功能开关 |
| read | /api/miniprogram/book/chapter/:id | GET | 按 id 获取章节 |
| read | /api/miniprogram/book/chapter/by-mid/:mid | GET | 按 mid 获取章节 |
| read | /api/miniprogram/user/purchase-status | GET | 购买状态 |
| read | /api/miniprogram/pay | POST | 支付下单 |
| read | /api/miniprogram/qrcode | POST | 生成小程序码 |
| index | /api/miniprogram/vip/members | GET | 超级个体列表 |
| index | /api/miniprogram/users | GET | 用户补充（limit=20） |
| index | /api/miniprogram/book/all-chapters | GET | 精选、最新 |
| chapters | /api/miniprogram/book/all-chapters | GET | 目录、每日新增 |
| search | /api/miniprogram/book/hot | GET | 热门搜索 |
| search | /api/miniprogram/book/search | GET | 关键词搜索 |
| about | /api/miniprogram/book/stats | GET | 书籍统计 |
| referral | /api/miniprogram/referral/data | GET | 分销数据 |
| referral | /api/miniprogram/qrcode | POST | 小程序码 |
| referral | /api/miniprogram/withdraw | POST | 提现申请 |
| my | /api/miniprogram/config | GET | 配置 |
| my | /api/miniprogram/withdraw/pending-confirm | GET | 待确认提现 |
| my | /api/miniprogram/earnings | GET | 收益 |
| my | /api/miniprogram/user/update | POST | 资料更新 |
| my | /api/miniprogram/vip/status | GET | VIP 状态 |
| settings | /api/miniprogram/user/profile | GET/POST | 资料 |
| settings | /api/miniprogram/user/update | POST | 更新 |
| settings | /api/miniprogram/phone | POST | 手机号 |
| addresses | /api/miniprogram/user/addresses | GET | 地址列表 |
| addresses | /api/miniprogram/user/addresses/:id | GET/PUT/DELETE | 地址 CRUD |
| addresses/edit | /api/miniprogram/user/addresses | POST | 新增地址 |
| withdraw-records | /api/miniprogram/withdraw/records | GET | 提现记录 |
| withdraw-records | /api/miniprogram/withdraw/confirm-info | GET | 确认收款信息 |
| vip | /api/miniprogram/vip/status | GET | VIP 状态 |
| vip | /api/miniprogram/vip/profile | GET/POST | VIP 资料 |
| vip | /api/miniprogram/pay | POST | VIP 购买 |
| member-detail | /api/miniprogram/vip/members | GET | 单个会员 |
| member-detail | /api/miniprogram/users | GET | 单个用户回退 |
| match | /api/miniprogram/ckb/join | POST | 加入弹窗 |
| match | /api/miniprogram/pay | POST | 购买匹配次数 |
| readingTracker | /api/miniprogram/user/reading-progress | POST | 阅读进度 |
| chapterAccessManager | /api/miniprogram/user/check-purchased | GET | 是否已购 |
| chapterAccessManager | /api/miniprogram/user/purchase-status | GET | 购买状态 |
| custom-tab-bar | /api/miniprogram/config | GET | 功能配置 |

### 2.2 路径错误（违反边界：应改为 `/api/miniprogram/*`）

| 页面 | 当前调用 | 正确路径 | 说明 |
|------|----------|----------|------|
| **match** | /api/match/config | /api/miniprogram/match/config | 匹配配置，soul-api 已挂 miniprogram |
| **match** | /api/match/users | /api/miniprogram/match/users | 匹配用户，soul-api 已挂 miniprogram |
| **match** | /api/ckb/match | /api/miniprogram/ckb/match | 上报匹配，soul-api 已挂 miniprogram |
| **purchases** | /api/orders?userId= | /api/miniprogram/orders?userId= | 订单列表，**需新增** miniprogram 路由 |
| **my** | /api/user/update | /api/miniprogram/user/update | 头像更新，soul-api 已挂 miniprogram |
| **my** | /api/withdraw | /api/miniprogram/withdraw | 提现申请，soul-api 已挂 miniprogram |

---

## 三、后端 API 需变更项

### 3.1 小程序端需修正的调用（前端改）

| 文件 | 当前 | 改为 |
|------|------|------|
| match.js | `/api/match/config` | `/api/miniprogram/match/config` |
| match.js | `/api/match/users` | `/api/miniprogram/match/users` |
| match.js | `/api/ckb/match` | `/api/miniprogram/ckb/match` |
| my.js | `/api/user/update` | `/api/miniprogram/user/update` |
| my.js | `/api/withdraw` | `/api/miniprogram/withdraw` |

### 3.2 后端需新增/调整的接口

| 接口 | 变更类型 | 说明 |
|------|----------|------|
| **GET /api/miniprogram/orders** | **新增** | 购买记录页专用。当前 `/api/orders` 无 userId 过滤且返回 `orders`；小程序需 `?userId=` 过滤且期望 `data`。建议在 miniprogram 组新增 `MiniprogramOrders`：按 userId 过滤、返回 `{ success, data: [...] }`，字段含 id/order_sn、product_id、product_name、amount、status、created_at |

### 3.3 响应格式对齐

| 接口 | 当前返回 | 小程序期望 | 建议 |
|------|----------|------------|------|
| /api/orders | `{ success, orders }` | `res.data` | 新增 MiniprogramOrders 返回 `{ success, data }`，与小程序一致 |

---

## 四、soul-api 现有 miniprogram 路由（已挂载）

```
/api/miniprogram/config
/api/miniprogram/login, phone-login, phone
/api/miniprogram/pay, pay/notify
/api/miniprogram/qrcode, qrcode/image
/api/miniprogram/book/all-chapters, chapter/:id, chapter/by-mid/:mid, hot, search, stats
/api/miniprogram/referral/visit, bind, data
/api/miniprogram/earnings
/api/miniprogram/match/config
/api/miniprogram/match/users          ← 注意：router 为 POST
/api/miniprogram/ckb/join
/api/miniprogram/ckb/match           ← 已挂载
/api/miniprogram/upload
/api/miniprogram/user/addresses, addresses/:id
/api/miniprogram/user/check-purchased, profile, purchase-status, reading-progress, update
/api/miniprogram/withdraw, withdraw/records, pending-confirm, confirm-received, confirm-info
/api/miniprogram/vip/status, vip/profile, vip/members
/api/miniprogram/users
```

**缺失**：`/api/miniprogram/orders`（需新增）

---

## 五、变更任务分工建议

| 角色 | 任务 |
|------|------|
| **小程序** | 1. match.js：3 处路径改为 /api/miniprogram/*<br>2. my.js：2 处路径改为 /api/miniprogram/*<br>3. purchases.js：路径改为 /api/miniprogram/orders（待后端提供后） |
| **后端 API** | 1. 新增 MiniprogramOrders handler：GET，支持 ?userId=，返回 { success, data }<br>2. router 挂载 miniprogram.GET("/orders", handler.MiniprogramOrders)<br>3. ckb/match 已挂载，无需变更 |
| **管理端** | 无需因本次对齐变更；订单、提现、用户等管理接口保持现状 |

---

## 六、附录：match 接口方法说明

- `GET /api/miniprogram/match/config`：匹配配置（matchTypes、freeMatchLimit、matchPrice）
- `POST /api/miniprogram/match/users`：执行匹配，入参 matchType、userId，返回匹配到的用户

当前 match.js 对 config 使用 `method: 'GET'`，对 users 使用 `method: 'POST'`，与后端一致。仅需将路径从 `/api/match/*` 改为 `/api/miniprogram/match/*`。