# 智能派单算法说明

## 概述

本系统实现了基于服务类型匹配和距离优先级的智能派单算法，通过综合考虑多个维度来推荐最适合的师傅，提高派单效率和用户满意度。

## 核心算法

### 匹配度计算

智能派单算法基于以下四个维度计算师傅与订单的匹配度：

1. **服务类型匹配度 (40%权重)**
   - 基于 `KxRider.workTypeKeywords` 字段
   - 从订单商品中提取关键词
   - 计算师傅擅长服务与订单需求的匹配程度

2. **距离评分 (30%权重)**
   - 基于 `KxRider.workRadio` 字段和师傅当前位置
   - 计算师傅与订单地址的实际距离
   - 距离越近分数越高

3. **评分权重 (20%权重)**
   - 基于师傅历史评价分数
   - 从 `KxRiderExt.currentTotalRating` 获取平均评分

4. **经验权重 (10%权重)**
   - 基于师傅完成的订单数量
   - 从 `KxRiderExt.currentTotalOrderCount` 获取经验值

### 评分规则

#### 服务类型匹配度
- 完全匹配：80-100分
- 部分匹配：40-80分
- 无匹配：30分
- 无设置：50分（中等分数）

#### 距离评分
- 工作半径30%内：100分
- 工作半径60%内：85分
- 工作半径内：70分
- 稍超工作半径：50分
- 远超工作半径：20分

#### 评分权重
- 5分制转100分制
- 无评分：60分（基础分数）

#### 经验权重
- 500单以上：100分
- 200-499单：85分
- 100-199单：70分
- 50-99单：55分
- 10-49单：40分
- 10单以下：25分

## 使用方法

### 1. 配置师傅信息

确保师傅的以下信息已正确配置：

```java
// 服务类型关键词 (用逗号分隔)
rider.setWorkTypeKeywords("家电维修,水电维修,开锁换锁");

// 工作半径 (公里)
rider.setWorkRadio(new BigDecimal("10.0"));

// 当前位置 (纬度/经度)
rider.setLatitude(new BigDecimal("39.9042"));
rider.setLongitude(new BigDecimal("116.4074"));
```

### 2. 调用智能派单接口

#### 获取推荐师傅列表
```java
@Autowired
private IKxRiderService riderService;

// 获取推荐师傅列表（按匹配度排序）
List<KxRiderVo> recommendedRiders = riderService.getRecommendedRiders(orderMessage, storageId);
```

#### 自动选择最佳师傅
```java
@Autowired
private ISmartDispatchService smartDispatchService;

// 自动选择最佳师傅（匹配度≥60分）
KxRiderVo bestRider = smartDispatchService.selectBestRider(orderMessage, storageId);
```

### 3. REST API接口

```http
POST /rider/rider/getRecommendedRiders?storageId=1
Content-Type: application/json

{
  "orderNo": "202501080001",
  "latitude": 39.9042,
  "longitude": 116.4074,
  "riderSpuBOList": [
    {
      "spuName": "家电维修服务"
    }
  ]
}
```

## 配置项

可通过配置文件调整算法参数：

```yaml
kxmall:
  smart-dispatch:
    enabled: true                 # 是否启用智能派单
    service-type-weight: 0.4      # 服务类型权重
    distance-weight: 0.3          # 距离权重  
    rating-weight: 0.2            # 评分权重
    experience-weight: 0.1        # 经验权重
    min-match-score: 60.0         # 最低匹配度阈值
    max-recommend-count: 10       # 最大推荐数量
```

## 回退机制

当智能派单算法执行失败或找不到合适师傅时，系统会自动回退到原有的派单逻辑，确保系统的稳定性。

## 服务类型关键词示例

建议师傅设置的服务类型关键词：

- **家电维修**: `家电维修,电器,空调,冰箱,洗衣机,电视`
- **水电维修**: `水电维修,管道,电路,插座,开关,水管`
- **开锁换锁**: `开锁换锁,锁具,门锁,密码锁`
- **家政清洁**: `家政清洁,清洁,保洁,卫生`
- **搬家服务**: `搬家服务,搬运,搬迁`

## 性能优化

1. **缓存机制**: 可考虑缓存师傅位置信息和扩展信息
2. **异步处理**: 对于大量师傅的匹配计算可考虑异步处理
3. **索引优化**: 为经纬度字段添加空间索引提高查询效率

## 监控指标

建议监控以下指标：
- 智能派单成功率
- 平均匹配度分数
- 算法执行时间
- 回退到原逻辑的比例

## 扩展方向

1. **机器学习优化**: 基于历史数据训练模型，提高匹配准确性
2. **实时路况**: 集成实时交通信息，优化距离计算
3. **用户偏好**: 考虑用户的师傅偏好历史
4. **动态权重**: 根据时间段、订单类型动态调整权重