Files

Made-with: Cursor

2026-03-07 22:58:43 +08:00

8.4 KiB

Raw Blame History

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/ 2. my.js：2 处路径改为 /api/miniprogram/ 3. purchases.js：路径改为 /api/miniprogram/orders（待后端提供后）
后端 API	1. 新增 MiniprogramOrders handler：GET，支持 ?userId=，返回 { success, data } 2. router 挂载 miniprogram.GET("/orders", handler.MiniprogramOrders) 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/*。

8.4 KiB Raw Blame History Unescape Escape

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

一、小程序功能模块总览

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

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

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

三、后端 API 需变更项

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

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

3.3 响应格式对齐

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

五、变更任务分工建议

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

8.4 KiB

Raw Blame History

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

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