soul-yongping/.cursor/docs/三角色边界定义.md

Soul 创业派对 - 三角色边界定义（开发）

按各自负责的源码目录与业务功能定义，防止互窜、明确职责。团队为 2 前端 + 1 后端 + 1 产品 + 1 助理，详见 开发团队职责定义.md。

---

一、开发角色总览

角色	源码目录	对接 API 前缀	技术栈
小程序开发工程师	miniprogram/	/api/miniprogram/*	微信原生 WXML/WXSS/JS
管理端开发工程师	soul-admin/	/api/admin/、/api/db/	React + Vite + TypeScript + Tailwind
后端开发	soul-api/	实现上述全部	Go + Gin + GORM + PowerWeChat

---

二、小程序开发工程师

2.1 负责源码

路径	说明
miniprogram/pages/*	页面（index、chapters、read、my、referral、match、settings、withdraw-records、vip 等）
miniprogram/utils/*	工具（scene、payment、chapterAccessManager、readingTracker）
miniprogram/components/*	组件
miniprogram/custom-tab-bar/*	自定义 TabBar
miniprogram/app.js、app.json、app.wxss	全局配置与入口

2.2 负责业务功能

功能域	页面/入口	对接接口
首页与浏览	index、chapters、search	/api/miniprogram/book/*、config
阅读与付费	read	/api/miniprogram/pay、pay/notify、user/check-purchased、user/purchase-status
找伙伴	match	/api/miniprogram/match/、ckb/
推广与分销	referral	/api/miniprogram/referral/*、earnings
提现	推广中心申请、我的待确认、withdraw-records	/api/miniprogram/withdraw、withdraw/records、withdraw/pending-confirm
我的	my	/api/miniprogram/user/、vip/、withdraw/*
设置	settings	/api/miniprogram/login、phone、config
地址	addresses	/api/miniprogram/user/addresses

2.3 边界约束

• 禁止：调用 /api/admin/*、/api/db/*；不得使用 next-project 接口。
• 请求：统一通过 getApp().request(url, options)，baseUrl 指向 soul-api。

---

三、管理端开发工程师

3.1 负责源码

路径	说明
soul-admin/src/pages/*	页面（Dashboard、Content、Chapters、Orders、Users、Withdrawals、Payment、Settings、QRCodes、Distribution 等）
soul-admin/src/components/*	组件（ui、modules 等）
soul-admin/src/api/*	请求封装（client.ts、auth.ts）
soul-admin/src/layouts/*	布局
soul-admin/src/hooks/*	hooks

3.2 负责业务功能

功能域	页面	对接接口
仪表盘	DashboardPage	/api/admin/*
内容管理	ContentPage	/api/admin/content
章节管理	ChaptersPage	/api/admin/chapters
订单	OrdersPage	/api/orders
用户管理	UsersPage	/api/db/users
提现审核	WithdrawalsPage	/api/admin/withdrawals
支付配置	PaymentPage	/api/admin/payment
推广设置	ReferralSettingsPage	/api/admin/referral-settings
系统设置	SettingsPage	/api/admin/settings
二维码	QRCodesPage	/api/db/config 等
分销概览	DistributionPage	/api/admin/distribution/overview
VIP 角色	VipRolesPage	/api/db/vip-roles

3.3 边界约束

• 允许：/api/admin/*、/api/db/*，以及 /api/orders 等与现网一致的管理端接口。
• 禁止：调用 /api/miniprogram/*；不得使用小程序登录或小程序 token。
• 请求：统一通过 client.ts 的 get/post/put/del；鉴权用 auth.ts 的 Bearer admin_token。

---

四、后端开发

4.1 负责源码

路径	说明
soul-api/internal/router	路由注册（miniprogram、admin、db、payment 各组）
soul-api/internal/handler	业务 handler
soul-api/internal/model	数据模型
soul-api/internal/wechat	微信、支付、转账等封装
soul-api/internal/config	配置加载
soul-api/internal/database	数据库连接
soul-api/internal/auth	鉴权（JWT）
soul-api/internal/middleware	中间件

4.2 负责路由分组与业务

路由组	前缀	使用方	典型业务
miniprogram	/api/miniprogram/*	小程序	登录、支付、书籍、推荐、提现、VIP、用户
admin	/api/admin/*	管理端	登录、章节、内容、支付配置、提现审核、设置、分销
db	/api/db/*	管理端	用户、配置、书籍、章节、VIP 角色、初始化
payment	/api/payment/*	微信/支付宝回调	支付回调、订单、商家转账回调

4.3 边界约束

• 按使用方挂路由：小程序接口只挂 miniprogram；管理端接口只挂 admin/db；不得混用。
• 禁止：在 miniprogram 组挂仅 admin 用的接口；在 admin/db 组挂小程序专属逻辑。

4.4 特殊路由说明

类型	示例	说明
微信/支付宝回调	/api/payment/*、/api/miniprogram/pay/notify	由微信/支付宝主动调用，无鉴权；后端负责验签、解密
管理端扁平路径	/api/orders	管理端使用，与 /api/admin/、/api/db/ 并列

---

五、支付/提现相关职责归属

环节	小程序开发工程师	管理端开发工程师	后端开发
支付下单	调 /api/miniprogram/pay，调起 wx.requestPayment	-	实现 Pay handler，调用微信统一下单
支付回调	-	-	实现 PayNotify，验签、更新订单、分佣
提现申请	调 /api/miniprogram/withdraw	-	实现 WithdrawPost；校验余额、写 withdrawals
提现审核	-	调 /api/admin/withdrawals 列表、通过/拒绝	实现 AdminWithdrawalsList、Action；调微信打款
提现回调	-	-	实现 PaymentWechatTransferNotify；验签、解密、更新状态
待确认收款	调 /api/miniprogram/withdraw/pending-confirm	-	实现 WithdrawPendingConfirm

---

六、速查：编辑目录 → 角色

编辑目录	角色	必遵守	主 Skill
miniprogram/**	小程序开发工程师	soul-miniprogram-boundary	SKILL-小程序开发.md
soul-admin/**	管理端开发工程师	soul-admin-boundary	SKILL-管理端开发.md
soul-api/**	后端开发	soul-api	SKILL-API开发.md

---

七、跨端协同与变更检查

场景	动作
跨端功能开发	加载 SKILL-角色流程控制.md，按「需求分析 → 并行开发 → 管理端启动」执行
变更完成准备提交	必过 soul-change-checklist.mdc + SKILL-变更关联检查.md
接口契约	后端开发输出（路径、请求/响应、字段）；小程序/管理端按契约对接

---

八、排除项

• next-project/：仅预览，不参与线上；新增/优化以 miniprogram、soul-admin、soul-api 为准。

---

九、相关文档

文档	说明
开发团队职责定义	五角色团队、Skills 分配
角色驱动Skills分析	Skills 组织方式、改进点
SKILL-角色流程控制	跨端协同流程、决策表
soul-project-boundary.mdc	项目边界、防互窜原则

---

更新日期：2026-02