soul-yongping/开发文档/4、前端/当前小程序开发细则.md

# 当前小程序开发细则

> 汇总当前 Soul 创业派对小程序的架构、经验与规划，便于新人上手与后续迭代。  
> 最后整理：2026-02

---

## 一、概述与定位

- **产品**：Soul 创业派对 — 微信小程序，内容为《一场 SOUL 的创业实验场》章节阅读 + 找伙伴 + 分销。
- **技术**：原生微信小程序（非 uni-app / Taro），与 Next.js 后端同仓，接口统一走 `apiBase`（如 `https://soul.quwanzhi.com`）。
- **核心能力**：章节阅读（免费/付费）、单章/全书支付、邀请码分销、找伙伴（匹配次数购买）、推广中心、我的订单/设置。

---

## 二、目录与页面结构

### 2.1 目录结构（miniprogram/）

```
miniprogram/
├── app.js / app.json / app.wxss     # 入口、全局配置、样式
├── custom-tab-bar/                  # 自定义底部 tabBar
├── pages/
│   ├── index/         # 首页（推荐章节、已读统计）
│   ├── chapters/      # 目录（全书章节列表）
│   ├── read/          # 阅读页（核心：权限、支付、分享）
│   ├── match/         # 找伙伴（匹配 + 购买次数）
│   ├── my/            # 我的（入口：订单、推广、设置）
│   ├── referral/      # 推广中心（邀请码、收益、海报）
│   ├── purchases/     # 我的订单（当前为本地已购章节列表）
│   ├── settings/      # 设置（提现、绑定账号等）
│   ├── search/        # 搜索
│   ├── about/         # 关于
│   └── addresses/     # 地址（若启用）
├── utils/
│   ├── chapterAccessManager.js  # 章节权限与状态
│   ├── readingTracker.js        # 阅读进度追踪
│   ├── payment.js               # 旧支付封装（部分场景仍用）
│   └── util.js
└── assets/                       # 图标等静态资源
```

### 2.2 TabBar 与主要页面

| Tab | 页面 | 说明 |
|-----|------|------|
| 首页 | pages/index/index | 推荐章节、已读/待读、入口到阅读 |
| 目录 | pages/chapters/chapters | 全书章节列表 |
| 找伙伴 | pages/match/match | 匹配 + 购买匹配次数 |
| 我的 | pages/my/my | 已读/已购、推广中心、订单、设置 |

非 Tab 页：阅读页 read、推广中心 referral、订单 purchases、设置 settings、搜索 search、关于 about。

### 2.3 全局状态（app.js globalData）

- `userInfo`：登录后用户信息（id、openId、nickname、purchasedSections、hasFullBook、referralCode、referralCount 等）。
- `openId` / `isLoggedIn`：微信登录态。
- `readSectionIds`：已读章节 ID 列表（有权限打开全文时打点）。
- `pendingReferralCode`：待绑定推荐码（带 ref 进入时写入，登录后绑定）。
- `apiBase`：后端 API 根地址。

---

## 三、核心流程与经验

### 3.1 阅读与章节权限

- **权威数据源**：章节是否可读以**服务端**为准（`/api/user/check-purchased`、`/api/user/purchase-status`），不依赖前端缓存做最终判断。
- **权限状态**：设计上支持 `unknown / free / locked_not_login / locked_not_purchased / unlocked_purchased / error`（见《章节阅读付费标准流程设计》）；阅读页通过 `chapterAccessManager` 与 `determineAccessState` 等做状态判断。
- **免费章节**：来自后端配置（如 `/api/db/config` 的 freeChapters），页面 onLoad 时拉取最新免费列表再判断；首帧可用本地默认 freeIds，拉取完成后需能刷新当前章状态，避免竞态误判。
- **已读 vs 已购**：
  - **已读**：仅统计“有权限打开并看到全文”的章节（`canAccess=true` 时 `app.markSectionAsRead(sectionId)`），存 `readSectionIds`。
  - **已购**：来自服务端 `userInfo.purchasedSections`、`hasFullBook` 及 orders 表，用于付费墙与购买按钮展示。
- **登录后防误解锁**：登录成功（含支付流程中登录）后必须 `refreshPurchaseFromServer()`，再对当前章节做 `recheckCurrentSectionAndRefresh()`（先拉最新免费列表，再请求 check-purchased），避免“刚登录”时误用旧缓存解锁付费章。
- **内容接口**：当前 `GET /api/book/chapter/[id]` 不校验登录与购买，前端按 `canAccess` 控制展示全文或预览；若未来开放 Web/API，建议章节接口侧做鉴权。

详见：`开发文档/8、部署/章节阅读付费标准流程设计.md`。

### 3.2 支付流程（章节 + 找伙伴）

- **统一入口**：章节支付 `pages/read/read.js` 调 `POST /api/miniprogram/pay`；找伙伴支付 `pages/match/match.js` 同样调该接口，传 `productType: 'match'`。
- **订单先行**：支付前**必须先创建订单**并插入 `orders` 表（status=`created`），再调微信统一下单；即使插库失败也继续支付流程，避免用户卡在“创建订单失败”。
- **请求体约定**：`openId`、`userId`、`productType`（section/fullbook/match）、`productId`、`amount`、`description`；**必须带 `referralCode`**（见下节）。
- **支付成功**：依赖微信回调 `POST /api/miniprogram/pay/notify` 更新订单为 `paid`、解锁用户权限、分佣、清理同产品未支付订单；前端支付成功后调用 `refreshUserPurchaseStatus()` 再 `initSection()` 刷新当前页。
- **兜底**：若回调丢失，依赖**订单状态同步定时任务**（如每 5 分钟调 `GET /api/cron/sync-orders`）查询微信侧状态并同步到本地 orders，保证最终一致。详见 `开发文档/8、部署/宝塔面板配置订单同步定时任务.md`。

### 3.3 邀请码与分销（必传、必记）

- **绑定逻辑**：带 `ref` 或 `referralCode` 的链接进入 → `app.js` 的 `handleReferralCode` 写入 `pendingReferralCode` 并**同步写入 `referral_code`**（`wx.setStorageSync('referral_code', refCode)`）；登录后调用 `/api/referral/bind` 完成绑定（30 天有效、可续期/抢夺）。
- **支付必带邀请码**：章节支付、找伙伴支付创建订单时都要传 `referralCode`，来源为 `wx.getStorageSync('referral_code')`；后端据此（或先查 referral_bindings）写入订单的 `referrer_id` 与 **`referral_code`**（下单时使用的邀请码，便于对账与后台展示）。
- **订单表字段**：`orders.referrer_id`（推荐人用户ID）、`orders.referral_code`（下单时邀请码）。若表尚未加字段，需执行 `scripts/add_orders_referrer_id.py`、`scripts/add_orders_referral_code.py`。
- **推荐人 vs 邀请码**：全局只认「推荐人 = 用户ID」；邀请码仅用于解析出 referrer_id，不会混用。分佣以 `referral_bindings` 为准，不依赖订单上的 referrer_id。详见 `开发文档/8、部署/邀请码分销规则说明.md`。

### 3.4 分享与落地

- 阅读页分享：`onShareAppMessage` / `onShareTimeline` 带 `id=章节ID&ref=当前用户邀请码`，落地后 ref 写入 storage，绑定与订单归属同上。
- 文章/章节分销与全局同一套：不按“哪篇文章带来”单独分成或统计，仅按“谁发的链接（ref=谁）”归属。

---

## 四、数据与接口约定

### 4.1 关键接口

| 接口 | 用途 |
|------|------|
| POST /api/miniprogram/login | 微信登录，返回 userInfo（含 purchasedSections、referralCode 等） |
| GET /api/user/purchase-status | 拉取购买状态（已购章节、全书） |
| GET /api/user/check-purchased | 校验指定章节/全书是否已购买 |
| POST /api/miniprogram/pay | 创建订单 + 微信预支付，**需传 referralCode** |
| POST /api/miniprogram/pay/notify | 微信支付回调（服务端） |
| GET /api/cron/sync-orders | 订单状态同步（定时任务，需 secret） |
| POST /api/referral/bind | 绑定推荐关系 |
| GET /api/db/config | 免费章节等配置 |

### 4.2 Storage 约定

- `referral_code`：落地 ref 或 app 检测到 ref 时写入；支付时读取并传后端。
- `pendingReferralCode` / `boundReferralCode`：待绑定/已绑定推荐码（app 层）。
- `readSectionIds`：已读章节 ID 列表。
- `openId`、用户信息等由 app 与登录逻辑维护。

---

## 五、已知问题与修复要点

- **免费章节配置竞态**：onLoad 时若未 await 免费列表再 initSection，首帧可能用默认 freeIds 误判；建议先拉配置再判断当前章，或拉取完成后对当前页再刷一次权限。
- **check-purchased 失败降级**：失败时应**保守**设为无权限（不信任本地缓存），避免误解锁。
- **支付回调丢失**：必须部署订单同步定时任务（如宝塔 crontab 调 `/api/cron/sync-orders`），否则会出现“已扣款但订单仍 created、内容未解锁”。
- **订单表缺字段**：新环境或老库需执行 `add_orders_referrer_id.py`、`add_orders_referral_code.py`，否则下单可能 fallback 成不写这两列（功能仍可用，但订单无推荐人/邀请码记录）。

---

## 六、部署与运维

- **后端**：Next.js 部署至 soul.quwanzhi.com，小程序 `app.globalData.apiBase` 指向该域名。
- **订单同步**：生产环境配置 crontab 每 5 分钟请求 `GET /api/cron/sync-orders?secret=YOUR_SECRET`（如宝塔定时任务），保证回调丢失时仍能同步为 paid 并解锁。见 `开发文档/8、部署/宝塔面板配置订单同步定时任务.md`。
- **数据库**：orders 表需含 `referrer_id`、`referral_code`；若为已有表，执行上述两个 Python 迁移脚本。
- **小程序发布**：按微信后台流程上传代码、提交审核；注意域名白名单、支付商户号与回调 URL 配置。

---

## 七、规划与待办（可选）

- **我的订单页**：当前 `purchases` 页为本地已购章节列表；若需“真实订单列表+邀请码展示”，可对接 `GET /api/orders?userId=xxx` 并展示订单维度数据。
- **阅读进度**：已设计阅读进度状态与 `readingTracker`、可上报服务端；是否全量接入与埋点可按产品需求推进。
- **章节接口鉴权**：若开放 Web 或对外 API，建议在章节内容接口侧按用户与购买记录返回全文/预览，防止直连拿全文。
- **按文章/章节维度的分销统计**：当前未实现；若需要“某章节带来的访问/订单数”，需在访问或订单上增加来源章节等字段并在报表中汇总。

---

## 八、相关文档索引

| 文档 | 说明 |
|------|------|
| 开发文档/8、部署/邀请码分销规则说明.md | 分销规则、订单 referrer_id/referral_code、推荐人 vs 邀请码 |
| 开发文档/8、部署/章节阅读付费标准流程设计.md | 阅读状态机、权限判断、阅读进度设计 |
| 开发文档/4、前端/ui/06-分销系统说明.md | 分销规则与推广方式 |
| 开发文档/4、前端/ui/08-支付系统说明.md | 支付方式与价格体系 |