# 小程序功能与管理端配置补齐分析

> 基于 miniprogram 功能分析，梳理需管理端补齐的配置与功能。  
> 更新日期：2026-02-25  
> **2026-02-25 已补齐**：mp_config 管理端、网站配置持久化、支付/二维码 POST、小程序 config 读取

---

## 一、小程序配置来源总览

| 配置类型 | 来源 | 管理端入口 | 状态 |
|----------|------|------------|------|
| 免费章节 | system_config.free_chapters | 系统设置 | ✅ 已有 |
| 价格 (section/fullbook) | chapter_config / site_settings | 系统设置 | ✅ 已有 |
| 功能开关 (match/referral/search/about) | feature_config | 系统设置 | ✅ 已有 |
| 找伙伴配置 | match_config | 找伙伴配置页 | ✅ 已有 |
| 推广/分销 | referral_config | 推广设置 | ✅ 已有 |
| 小程序专用 (mp_config) | mp_config | 系统设置 → 小程序配置 | ✅ 已补齐 |
| 订阅消息模板 ID | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 |
| 微信支付商户号 | mp_config 或 app.js 兜底 | 系统设置 → 小程序配置 | ✅ 已补齐 |
| API 地址 (baseUrl) | app.js 硬编码 | 发版时改 baseUrl | 已移除配置 |
| 网站/站点配置 | site_config, page_config | 网站配置 | ✅ 已持久化 |

---

## 二、小程序功能模块与配置依赖

### 2.1 核心配置接口：`GET /api/miniprogram/config`

**返回字段**（来自 GetPublicDBConfig）：

| 字段 | 说明 | 管理端对应 |
|------|------|------------|
| freeChapters | 免费章节 ID 列表 | 系统设置 → 免费章节 |
| prices | { section, fullbook } | 系统设置 → 价格设置 |
| features | matchEnabled, referralEnabled, searchEnabled, aboutEnabled | 系统设置 → 功能开关 |
| mpConfig | appId, apiDomain, buyerDiscount, referralBindDays, minWithdraw | **无管理端** |
| userDiscount | 好友购买优惠 % | 推广设置 |

### 2.2 找伙伴配置：`GET /api/miniprogram/match/config`

| 字段 | 说明 | 管理端对应 |
|------|------|------------|
| matchTypes | 匹配类型列表 | 找伙伴配置页 |
| freeMatchLimit | 每日免费匹配次数 | 找伙伴配置页 |
| matchPrice | 单次匹配价格(元) | 找伙伴配置页 |
| settings | enableFreeMatches, enablePaidMatches, maxMatchesPerDay | 找伙伴配置页 |

### 2.3 小程序 app.js 硬编码项

```javascript
// 当前硬编码，无法通过管理端修改
baseUrl: 'http://localhost:8080',           // 开发/生产需改代码
appId: 'wxb8bbb2b10dec74aa',
withdrawSubscribeTmplId: 'u3MbZGPRkrZIk-...',  // 提现订阅消息模板
mchId: '1318592501',                        // 微信支付商户号
```

---

## 三、管理端需补齐项（按优先级）

### P0 - 必须补齐

| 项 | 说明 | 建议方案 |
|----|------|----------|
| **小程序专用配置 (mp_config)** | appId、apiDomain、minWithdraw 等，小程序从 config 读取 | 在「系统设置」或新建「小程序配置」卡片，支持编辑并写入 system_config.mp_config |
| **订阅消息模板 ID** | 提现申请需用户授权订阅，模板 ID 现硬编码 | 管理端增加「提现订阅模板 ID」配置，写入 mp_config 或单独 key；小程序启动时从 config 拉取 |
| **API 地址 (baseUrl)** | 开发/生产切换需改 app.js | 方案 A：从 mp_config.apiDomain 下发，小程序优先用接口返回值；方案 B：保留硬编码，仅文档说明切换方式 |

### P1 - 建议补齐

| 项 | 说明 | 建议方案 |
|----|------|----------|
| **微信支付商户号** | 支付回调、对账依赖 mchId，现硬编码 | 管理端「支付配置」或「小程序配置」增加 mchId 字段；后端从配置读取，小程序可不改（支付由后端发起） |
| **网站配置持久化** | SitePage 当前保存仅前端状态，未调用后端 | 对接 POST /api/db/config，按 key 保存 site_config、page_config、menu_config |
| **支付/二维码配置持久化** | PaymentPage、QRCodesPage 使用 POST /api/config | soul-api 无 POST /api/config，需新增或改为 POST /api/db/config { key, value } |

### P2 - 可选优化

| 项 | 说明 | 建议方案 |
|----|------|----------|
| **referral_config 的 withdrawFee** | 文档有提现手续费，ReferralSettingsPage 未展示 | 若业务需要，在推广设置页增加「提现手续费」字段 |
| **主题色/品牌色** | app.js theme 硬编码 | 若需多端统一，可从 site_config 或 mp_config 下发 |

---

## 四、配置与 system_config 键名映射

| system_config.config_key | 管理端页面 | 说明 |
|--------------------------|------------|------|
| free_chapters | 系统设置 | 免费章节 ID 数组 |
| feature_config | 系统设置 | 功能开关对象 |
| site_settings | 系统设置 | 价格、作者信息 |
| chapter_config | (可选) | 合并 freeChapters + prices，GetPublicDBConfig 优先用 |
| match_config | 找伙伴配置 | 匹配类型、免费次数、价格 |
| referral_config | 推广设置 | 分销比例、提现门槛、绑定期等 |
| mp_config | **待新增** | 小程序专用：appId, apiDomain, withdrawSubscribeTmplId, mchId 等 |
| site_config | 网站配置 | 站点名称、logo 等（需持久化） |
| page_config | 网站配置 | 页面标题（需持久化） |
| menu_config | 网站配置 | 菜单开关（需持久化） |
| payment_methods | 支付配置 | 微信/支付宝活码等（需确认 POST 接口） |
| live_qr_codes | 二维码管理 | 群活码（需确认 POST 接口） |

---

## 五、接口与数据流检查

### 5.1 管理端调用与后端支持

| 管理端页面 | 调用 | 后端支持 | 备注 |
|------------|------|----------|------|
| 系统设置 | GET/POST /api/admin/settings | ✅ | 写入 free_chapters, feature_config, site_settings |
| 推广设置 | GET/POST /api/admin/referral-settings | ✅ | 写入 referral_config |
| 找伙伴配置 | GET /api/db/config/full?key=match_config | ✅ | 需 AdminAuth |
| 找伙伴配置 | POST /api/db/config | ✅ | body: { key: 'match_config', value: {...} } |
| 支付配置 | GET/POST /api/config | ⚠️ | GET 有，POST 无；需新增或改用 db/config |
| 网站配置 | GET /api/config | ⚠️ | GET 有，保存未对接 |
| 二维码管理 | GET/POST /api/config | ⚠️ | 同上 |

### 5.2 小程序读取链

```
小程序 onLoad / custom-tab-bar
  → GET /api/miniprogram/config
  → GetPublicDBConfig
  → 读取 system_config: chapter_config, free_chapters, feature_config, mp_config, referral_config
  → 返回 freeChapters, prices, features, mpConfig, userDiscount
```

---

## 六、实施建议（管理端开发任务）

### 任务 1：新增「小程序配置」区块（P0）

- **位置**：系统设置页新增卡片，或独立「小程序配置」页
- **字段**：
  - API 域名 (apiDomain)：如 `https://soulapi.quwanzhi.com`
  - 小程序 AppID (appId)：如 `wxb8bbb2b10dec74aa`
  - 提现订阅模板 ID (withdrawSubscribeTmplId)
  - 微信支付商户号 (mchId)（可选，后端也可用 env）
  - 最低提现金额 (minWithdraw)（可与 referral_config 同步）
- **存储**：POST /api/admin/settings 扩展，或 POST /api/db/config { key: 'mp_config', value: {...} }
- **小程序**：app.js 启动时请求 config，若 mp_config 存在则覆盖 baseUrl；withdrawSubscribeTmplId 从 config 取

### 任务 2：网站配置持久化（P1）

- SitePage 保存时调用 POST /api/db/config，按 key 分别保存 site_config、page_config、menu_config
- 或扩展 AdminSettingsPost 支持 site_config 等

### 任务 3：支付/二维码配置接口（P1）

- 方案 A：新增 POST /api/admin/config，支持 payment_methods、live_qr_codes 等 key
- 方案 B：PaymentPage、QRCodesPage 改为调用 POST /api/db/config，body: { key, value }

---

## 七、附录：小程序页面与配置使用

| 页面 | 使用的配置 | 接口 |
|------|------------|------|
| custom-tab-bar | features.matchEnabled | GET /api/miniprogram/config |
| 阅读 read | freeChapters, prices | GET /api/miniprogram/config (chapterAccessManager) |
| 找伙伴 match | matchTypes, freeMatchLimit, matchPrice | GET /api/miniprogram/match/config |
| 我的 my | features, 收益/提现规则 | GET /api/miniprogram/config, referral/data |
| 分销 referral | shareRate, minWithdraw, bindingDays | GET /api/miniprogram/referral/data |
| 支付流程 | mchId (后端), openId | app.js 硬编码 + 后端 env |