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

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

> 按各自负责的**源码目录**与**业务功能**定义，防止互窜、明确职责。团队为 **2 前端 + 1 后端 + 1 产品 + 1 助理**，详见 [开发团队职责定义.md](./开发团队职责定义.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 为准。

---

## 九、相关文档

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

---

**更新日期**：2026-02