汉秋
1970572edd
新增 CooperationOrder 模块（双 Tab 列表、获客员绑定、主 Tab 扫码）、订单来源/带客单绑定及配套 API 测试；同步引入 roleCode 权限匹配与相关单元测试。 Co-authored-by: Cursor <cursoragent@cursor.com>
58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# 合作订单模块
|
||
|
||
## 职责
|
||
|
||
合作订单模块面向摄影师/门店角色，管理合作获客业务：
|
||
|
||
- **获客员线索**：查看合作获客员上报的潜在客户线索（手机号、备注、图片）
|
||
- **获客订单**：查看通过合作渠道产生的订单，支持关键词搜索
|
||
- **合作获客员**：查看已绑定获客员列表，扫码绑定新获客员
|
||
|
||
权限 URI：`cooperation_order`（与 Android `CooperationOrderFeature.URI` 一致）。
|
||
|
||
## 核心流程
|
||
|
||
### 首页入口
|
||
|
||
1. 用户点击首页「合作订单」菜单（`cooperation_order`）
|
||
2. `CooperationOrderAccessView` 校验 `PermissionContext.canAccess("cooperation_order")`
|
||
3. 无权限时 Toast 提示并返回；有权限进入 `CooperationOrderListView`
|
||
|
||
### 双 Tab 列表
|
||
|
||
| Tab | API | 说明 |
|
||
| --- | --- | --- |
|
||
| 获客员线索 | `GET .../sale-user/referral-leads` | 分页 10 条，下拉刷新/加载更多 |
|
||
| 获客订单 | `GET .../sale-user/acquisition-orders` | 支持 `keyword` 搜索 |
|
||
|
||
### 获客员绑定
|
||
|
||
1. 列表页右上角「合作获客员」→ `CooperationAcquirerView`
|
||
2. 扫码或主 Tab 扫码识别 `{"method":"sale_user_bind","sale_user_id":N}`
|
||
3. `BindAcquirerView` 加载邀请信息 → 确认 → `POST .../sale-user/accept-bind`
|
||
|
||
## 与订单模块关系
|
||
|
||
订单管理（`orderType` 11 摄影师跟拍 / 14 线下扫码）在订单卡片展示「订单来源」：
|
||
|
||
- Sheet 内选择获客员 → 带客单 → `POST .../bind-referral-order`
|
||
- 全页流程见 `ReferralOrderSelectView`
|
||
- 订单退款成功后，若已绑定带客单，调用 `POST .../referral-orders/{id}/status`（status=3）
|
||
|
||
## 主要文件
|
||
|
||
| 文件 | 说明 |
|
||
| --- | --- |
|
||
| `API/CooperationOrderAPI.swift` | 8 个 sale-user / cooperative 接口 |
|
||
| `Models/CooperationOrderModels.swift` | 实体与解码 |
|
||
| `Services/CooperationOrderFeature.swift` | 权限 URI 常量 |
|
||
| `ViewModels/*` | 列表、获客员、绑定 ViewModel |
|
||
| `Views/*` | SwiftUI 页面与卡片组件 |
|
||
|
||
## 依赖
|
||
|
||
- `@Environment(\.cooperationOrderAPI)` 注入网络层
|
||
- `@EnvironmentObject PermissionContext` 权限校验
|
||
- `@EnvironmentObject ToastCenter` 用户提示
|
||
- Kingfisher 加载线索图片
|