229 lines
6.7 KiB
Markdown
229 lines
6.7 KiB
Markdown
# 销售推广模块
|
||
|
||
## 概述
|
||
|
||
销售推广模块负责推广员管理、佣金计算、佣金结算等。
|
||
|
||
---
|
||
|
||
## 推广员管理
|
||
|
||
### 接口
|
||
|
||
| 方法 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 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=是 |
|