# miniprogram 功能还原分析报告

## 一、对比结论

| 项目 | miniprogram（甲方） | miniprogram2（你写的） |
|------|-------------------|------------------------|
| 页面分享 | 仅 read、referral 有 | 几乎所有页面都有 |
| scene 解析 | 无 | 有 utils/scene.js |
| 推荐码获取 | 分散（userInfo?.referralCode 等） | 统一 app.getMyReferralCode() |
| 书籍 API | /api/book/all-chapters | /api/miniprogram/book/all-chapters |
| 特有页面 | vip、member-detail | scan、profile-edit |

## 二、已完成的还原项

### 1. 基础能力（app.js + utils/scene.js）

- **新增** `utils/scene.js`：扫码 scene 参数编解码，支持 `mid`、`id`、`ref`
- **app.js**：
  - 引入 `parseScene`，`handleReferralCode` 支持 `options.scene` 解析
  - 新增 `getMyReferralCode()`：统一获取邀请码
  - 新增 `getSectionMid(sectionId)`：根据 id 查 mid
  - `loadBookData` 改为 `/api/miniprogram/book/all-chapters`

### 2. 页面分享（onShareAppMessage）

已为以下页面补充分享，路径统一带 `ref` 参数：

- index、chapters、match、my
- read、referral（原有，已统一用 getMyReferralCode）
- search、settings、purchases、privacy
- withdraw-records、addresses、addresses/edit
- agreement、about、vip、member-detail

### 3. read.js 分享逻辑与 mid 支持

- 使用 `app.getMyReferralCode()` 替代 `userInfo?.referralCode || wx.getStorageSync('referralCode')`
- **mid 支持**：onLoad 支持 `options.scene`、`options.mid`；mid 有值无 id 时从 bookData 或 `/api/miniprogram/book/chapter/by-mid/:mid` 解析 id
- 分享 path 优先用 `mid=`（扫码/海报闭环），无则用 `id=`；API 返回 `res.mid` 时写入 `sectionMid`

### 4. API 路径修正

- `app.loadBookData`：`/api/book/all-chapters` → `/api/miniprogram/book/all-chapters`
- `index.loadBookData`、`loadFeaturedFromServer`、`loadLatestChapters`：同上
- `chapters.loadDailyChapters`：同上
- **VIP 接口**：`/api/vip/*` → `/api/miniprogram/vip/*`（vip.js、my.js、index.js、member-detail.js）

## 三、已处理项

- **vip 相关接口**：已改为 `/api/miniprogram/vip/*`（members、status、profile），符合项目边界。**后端需在 soul-api 的 miniprogram 组下挂对应路由**，可复用现有 handler。
- **页面结构**：保留 vip、member-detail，未引入 scan、profile-edit

## 四、后端已补全（soul-api）

已在 miniprogram 组下新增以下路由：

| 路径 | 方法 | 用途 |
|------|------|------|
| `/api/miniprogram/vip/status` | GET | 查询用户 VIP 状态（按 fullbook/vip 订单判断） |
| `/api/miniprogram/vip/profile` | GET/POST | 获取/更新 VIP 资料（映射 users 表 nickname/phone） |
| `/api/miniprogram/vip/members` | GET | VIP 会员列表（无 id）或单个（?id=） |
| `/api/miniprogram/users` | GET | 用户列表（?limit=）或单个（?id=），首页超级个体、会员详情回退 |

## 五、后续建议

1. **soul-api 路由**：确认 `/api/miniprogram/book/all-chapters` 已注册；VIP 接口见「四、后端待办」。
2. **referral.js**：已统一使用 `app.getMyReferralCode()` 作为回退。
3. **read.js mid 支持**：已完成。若 soul-api 未提供 `/api/miniprogram/book/chapter/by-mid/:mid`，扫码带 mid 时需依赖 bookData 已加载完成；建议后端补充 by-mid 接口。