汉秋
49e997ddba
将扫码页提升到列表层弹出并补齐 AppDelegate.window，避免扫码时 UIKit 取主窗口崩溃；Toast 改用独立 UIWindow 显示在 sheet 之上；合作获客员支持短信验证修改分成比例，同时优化冷启动根视图创建时机并补充相关测试。 Co-authored-by: Cursor <cursoragent@cursor.com>
68 lines
3.0 KiB
Markdown
68 lines
3.0 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. 扫码页由 `CooperationOrderListView` 统一弹出（避免在 `navigationDestination` 子页内嵌 `fullScreenCover` 导致 SwiftUI 栈溢出崩溃）
|
||
3. 扫码或主 Tab 扫码识别 `{"method":"sale_user_bind","sale_user_id":N}`
|
||
4. `BindAcquirerView` 加载邀请信息 → 填写分账比例（0–100）→ `POST .../sale-user/accept-bind?sale_user_id=&commission_rate=`
|
||
|
||
### 获客员备注名
|
||
|
||
1. 合作获客员列表每行右上角「修改备注」→ 弹窗编辑备注名
|
||
2. 备注名最多 20 个字符；点击保存时校验，超出则提示且不提交
|
||
3. 修改备注弹窗展示 `saler_real_name`：「为 {获客员真实姓名} 设置备注名」
|
||
4. 保存 → `POST .../sale-user/update-remark`，Body：`{ "sale_user_id": Int, "photog_remark_name": String }`
|
||
5. 展示规则：优先 `photog_remark_name`，为空时回退获客员原名（`name` / `saler_name` / `sale_user_name`）
|
||
6. 绑定确认页（`BindAcquirerView`）仍展示真实获客员名，不使用备注名
|
||
|
||
## 与订单模块关系
|
||
|
||
订单管理（`orderType` 11 摄影师跟拍 / 14 线下扫码）在订单卡片展示「订单来源」：
|
||
|
||
- Sheet 内选择获客员 → 带客单 → `POST .../bind-referral-order`
|
||
- 全页流程见 `ReferralOrderSelectView`
|
||
- 订单退款成功后，若已绑定带客单，调用 `POST .../referral-orders/{id}/status`（status=3）
|
||
|
||
## 主要文件
|
||
|
||
| 文件 | 说明 |
|
||
| --- | --- |
|
||
| `API/CooperationOrderAPI.swift` | 9 个 sale-user / cooperative 接口 |
|
||
| `Models/CooperationOrderModels.swift` | 实体与解码 |
|
||
| `Services/CooperationOrderFeature.swift` | 权限 URI 常量 |
|
||
| `ViewModels/*` | 列表、获客员、绑定 ViewModel |
|
||
| `Views/*` | SwiftUI 页面与卡片组件 |
|
||
|
||
## 依赖
|
||
|
||
- `@Environment(\.cooperationOrderAPI)` 注入网络层
|
||
- `@EnvironmentObject PermissionContext` 权限校验
|
||
- `@EnvironmentObject ToastCenter` 用户提示
|
||
- Kingfisher 加载线索图片
|