fnvtk/soul-yongping
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
soul-yongping/开发文档/小程序功能与管理端配置补齐分析.md
卡若 b7c35a89b0 初始提交：一场soul的创业实验-永平 网站与小程序 
Made-with: Cursor
2026-03-07 22:58:43 +08:00

8.3 KiB
Raw Permalink Blame History

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

基于 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 硬编码项

// 当前硬编码，无法通过管理端修改
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