# 销售推广模块

## 概述

销售推广模块负责推广员管理、佣金计算、佣金结算等。

---

## 推广员管理

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `salesperson/list` | 推广员列表 |
| GET | `salesperson/detail` | 推广员详情 |
| POST | `salesperson/create` | 创建推广员 |
| POST | `salesperson/update` | 更新推广员 |
| POST | `salesperson/delete` | 删除推广员 |
| GET | `salesperson/option` | 推广员选项 |

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonController` | `app/Http/Controllers/admin/salesperson/SalespersonController.php` | 控制器 |
| `SalespersonService` | `app/Service/admin/salesperson/SalespersonService.php` | 业务服务 |

### 关联模型

| 模型 | 表名 | 说明 |
|------|------|------|
| `ClinicSalespersonModel` | `xk_clinic_salesperson` | 门店推广员 |
| `AdminSalespersonModel` | `xk_admin_salesperson` | 管理员-推广员关联 |
| `UserSalespersonModel` | `xk_user_salesperson` | 用户-推广员绑定 |
| `SalespersonQrCodeModel` | `xk_salesperson_qr_code` | 推广员二维码 |
| `SalespersonStoreConfigModel` | `xk_salesperson_store_config` | 推广员门店配置 |

---

## 佣金计算

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonCommissionAccrualService` | `app/Service/admin/salesperson/SalespersonCommissionAccrualService.php` | 佣金计提 |
| `SalespersonCommissionCalculator` | `app/Service/admin/salesperson/SalespersonCommissionCalculator.php` | 佣金计算 |
| `SalespersonCommissionRecordFormatter` | `app/Service/admin/salesperson/SalespersonCommissionRecordFormatter.php` | 记录格式化 |
| `SalespersonOrderBindService` | `app/Service/admin/salesperson/SalespersonOrderBindService.php` | 订单绑定 |

### 关联模型

| 模型 | 表名 | 说明 |
|------|------|------|
| `SalespersonCommissionRecordModel` | `xk_salesperson_commission_record` | 佣金记录 |
| `SalespersonCommissionTemplateModel` | `xk_salesperson_commission_template` | 佣金模板 |
| `SalespersonCommissionTemplateItemModel` | `xk_salesperson_commission_template_item` | 佣金模板明细 |
| `SalespersonDrugCommissionModel` | `xk_salesperson_drug_commission` | 药品佣金配置 |

### 佣金计算方式

| 方式 | 说明 |
|------|------|
| 固定金额 | 按模板/药品配置固定佣金 |
| 百分比 | 按订单金额百分比计算 |

### 佣金来源

| 来源 | 说明 |
|------|------|
| 直接 | 推广员直接推广的订单 |
| 邀请 | 推广员邀请的用户产生的订单 |

### 佣金计提流程

```mermaid
sequenceDiagram
    participant C as 定时任务
    participant SVC as SalespersonCommissionAccrualService
    participant DB as 数据库

    C->>SVC: app:accrue-salesperson-commission
    SVC->>DB: 查询今天已付款但无佣金的订单
    loop 每个订单
        SVC->>SVC: calculateCommission(order)
        SVC->>DB: INSERT INTO xk_salesperson_commission_record
    end
```

---

## 佣金结算

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `settlement/list` | 结算单列表 |
| GET | `settlement/detail` | 结算单详情 |
| POST | `settlement/create` | 创建结算单 |
| POST | `settlement/settle` | 执行结算 |

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonSettlementService` | `app/Service/admin/salesperson/SalespersonSettlementService.php` | 结算服务 |

### 关联模型

| 模型 | 表名 | 说明 |
|------|------|------|
| `SalespersonSettlementModel` | `xk_salesperson_settlement` | 推广员结算单 |
| `SalespersonSettlementRecordModel` | `xk_salesperson_settlement_record` | 结算-佣金关联 |

### 结算方式

| 方式 | 值 | 说明 |
|------|-----|------|
| 按时段 | 1 | 按时间段结算 |
| 按订单 | 2 | 按订单逐笔结算 |

---

## 佣金冲销

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonCommissionReversalService` | `app/Service/admin/salesperson/SalespersonCommissionReversalService.php` | 冲销服务 |

### 关联 Job

| Job | 文件 | 说明 |
|-----|------|------|
| `SalespersonCommissionRefundJob` | `app/Jobs/SalespersonCommissionRefundJob.php` | 退款后佣金冲销 |

### 冲销流程

```mermaid
sequenceDiagram
    participant R as 退款回调
    participant J as SalespersonCommissionRefundJob
    participant SVC as SalespersonCommissionReversalService
    participant DB as 数据库

    R->>J: 退款成功
    J->>SVC: reverseCommission(order_id)
    SVC->>DB: 查询原佣金记录
    SVC->>DB: INSERT INTO xk_salesperson_commission_record (record_type=退款冲销)
```

---

## 佣金模板

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `commission-template/list` | 模板列表 |
| POST | `commission-template/create` | 创建模板 |
| POST | `commission-template/update` | 更新模板 |
| POST | `commission-template/delete` | 删除模板 |

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonCommissionTemplateService` | `app/Service/admin/salesperson/SalespersonCommissionTemplateService.php` | 模板服务 |

### 关联模型

| 模型 | 表名 | 说明 |
|------|------|------|
| `SalespersonCommissionTemplateModel` | `xk_salesperson_commission_template` | 佣金模板 |
| `SalespersonCommissionTemplateItemModel` | `xk_salesperson_commission_template_item` | 佣金模板明细 |

---

## 门店推广员

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `clinic-salesperson-self/info` | 门店推广员信息 |
| POST | `clinic-salesperson-self/update` | 更新信息 |

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `ClinicSalespersonSelfController` | `app/Http/Controllers/admin/salesperson/ClinicSalespersonSelfController.php` | 控制器 |
| `SalespersonAdminAccountService` | `app/Service/admin/salesperson/SalespersonAdminAccountService.php` | 账户服务 |

---

## 推广员门店配置

### 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `salesperson-store-config/list` | 配置列表 |
| POST | `salesperson-store-config/update` | 更新配置 |

### 关联类

| 类 | 文件 | 说明 |
|----|------|------|
| `SalespersonStoreConfigController` | `app/Http/Controllers/admin/salesperson/SalespersonStoreConfigController.php` | 控制器 |
| `SalespersonStoreConfigService` | `app/Service/admin/salesperson/SalespersonStoreConfigService.php` | 业务服务 |

### 关联模型

| 模型 | 表名 | 说明 |
|------|------|------|
| `SalespersonStoreConfigModel` | `xk_salesperson_store_config` | 推广员门店配置 |

### 配置说明

| 字段 | 类型 | 说明 |
|------|------|------|
| `store_id` | int | 门店 ID（唯一） |
| `see_price` | tinyint | 是否可见价格：0=否, 1=是 |