# 合作订单模块

## 职责

合作订单模块面向摄影师/门店角色，管理合作获客业务：

- **获客员线索**：查看合作获客员上报的潜在客户线索（手机号、备注、图片）
- **获客订单**：查看通过合作渠道产生的订单，支持关键词搜索
- **合作获客员**：查看已绑定获客员列表，扫码绑定新获客员

权限 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 加载线索图片