xk-docs/docs/projects/xk-api/modules/salesperson.md

销售推广模块

概述

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

---

推广员管理

接口

方法	路径	说明
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	药品佣金配置

佣金计算方式

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

佣金来源

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

佣金计提流程

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	退款后佣金冲销

冲销流程

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=是