mashangyoujiu/_ai_archive/docs/README_RIDER_SYSTEM.md

# 骑手订单分配系统

## 系统概述

本系统是在现有电商系统基础上扩展的骑手订单分配功能，实现了智能订单分配、位置追踪、状态同步等核心功能，确保不影响原系统的正常运行。

## 功能特性

### 1. 智能订单分配
- **自动分配算法**：基于距离、骑手状态、负载均衡等多因素智能分配
- **手动分配**：支持后台管理员手动指定骑手
- **批量分配**：支持批量处理多个订单
- **重新分配**：订单被拒绝后自动重新分配

### 2. 骑手管理
- **骑手注册**：支持骑手信息注册和审核
- **状态管理**：工作状态、在线状态实时管理
- **评分系统**：基于服务质量的评分机制
- **权限控制**：不同级别骑手的权限管理

### 3. 位置追踪
- **实时定位**：骑手位置实时更新
- **轨迹记录**：完整的配送轨迹记录
- **范围查询**：查找指定范围内的可用骑手
- **到达提醒**：自动检测到达门店和客户位置

### 4. 订单状态同步
- **双向同步**：骑手端和原系统订单状态实时同步
- **状态一致性**：确保数据一致性检查和修复
- **操作日志**：完整的操作日志记录
- **异常处理**：同步失败自动重试机制

## 系统架构

### 数据表结构

#### 1. 骑手信息表 (ls_rider_info)
```sql
- id: 骑手ID
- real_name: 真实姓名
- phone: 手机号
- id_card: 身份证号
- store_id: 所属门店ID
- status: 账号状态 (0禁用 1启用)
- work_status: 工作状态 (0休息 1工作中)
- rating: 评分
- max_orders: 最大接单数
- last_location_lat/lng: 最后位置
- created_at/updated_at: 创建/更新时间
```

#### 2. 骑手订单表 (ls_rider_order)
```sql
- id: 记录ID
- rider_id: 骑手ID
- bill_id: 原系统订单ID
- order_status: 订单状态 (0待接单 1已接单 2已取货 3配送中 4已完成 5已拒绝 6已取消)
- assign_time: 分配时间
- accept_time: 接单时间
- pickup_time: 取货时间
- delivery_time: 配送完成时间
- estimated_time: 预计送达时间
- delivery_fee: 配送费
```

#### 3. 骑手位置表 (ls_rider_location)
```sql
- id: 记录ID
- rider_id: 骑手ID
- lat/lng: 经纬度
- accuracy: GPS精度
- speed: 速度
- bearing: 方向角
- record_time: 记录时间
```

#### 4. 订单同步日志表 (ls_rider_order_sync_log)
```sql
- id: 日志ID
- rider_order_id: 骑手订单ID
- bill_id: 原系统订单ID
- action: 操作类型
- description: 操作描述
- sync_time: 同步时间
```

### 核心业务类

#### 1. RiderOrderDispatch (订单分配)
- `autoDispatch()`: 自动分配订单
- `manualDispatch()`: 手动分配订单
- `getAvailableRiders()`: 获取可用骑手
- `calculateBestRider()`: 计算最佳骑手

#### 2. OrderMatching (订单匹配)
- `smartMatch()`: 智能匹配算法
- `batchMatch()`: 批量匹配
- `calculateMatchScores()`: 计算匹配分数

#### 3. OrderStatusSync (状态同步)
- `syncOrderStatus()`: 同步订单状态
- `checkStatusConsistency()`: 检查状态一致性
- `fixStatusInconsistency()`: 修复状态不一致

#### 4. RiderLocationModel (位置管理)
- `addLocation()`: 添加位置记录
- `getRidersInRange()`: 获取范围内骑手
- `calculateDistance()`: 计算距离
- `predictArrivalTime()`: 预测到达时间

## API接口

### 骑手端接口 (Api/Controller/RiderOrderController)

#### 1. 获取订单列表
```
POST /Api/RiderOrder/getOrderList
参数: token, status, page, limit
返回: 订单列表数据
```

#### 2. 接受订单
```
POST /Api/RiderOrder/acceptOrder
参数: token, rider_order_id
返回: 操作结果
```

#### 3. 开始配送
```
POST /Api/RiderOrder/startDelivery
参数: token, rider_order_id
返回: 操作结果
```

#### 4. 完成配送
```
POST /Api/RiderOrder/completeDelivery
参数: token, rider_order_id
返回: 操作结果
```

### 位置追踪接口 (Api/Controller/RiderLocationController)

#### 1. 更新位置
```
POST /Api/RiderLocation/updateLocation
参数: token, lat, lng, accuracy, speed
返回: 操作结果
```

#### 2. 获取位置轨迹
```
POST /Api/RiderLocation/getLocationTrack
参数: token, start_time, end_time
返回: 位置轨迹数据
```

### 后台管理接口 (Admin/Controller/RiderManageController)

#### 1. 订单分配页面
```
GET /Admin/RiderManage/orderDispatch
返回: 分配页面
```

#### 2. 获取待分配订单
```
POST /Admin/RiderManage/getPendingOrders
参数: page, limit, store_id
返回: 待分配订单列表
```

#### 3. 手动分配订单
```
POST /Admin/RiderManage/manualDispatch
参数: bill_id, rider_id
返回: 分配结果
```

## 安装部署

### 1. 数据库初始化
执行 `client/rider_tables.sql` 文件创建相关数据表：
```bash
mysql -u username -p database_name < client/rider_tables.sql
```

### 2. 文件部署
将以下文件复制到对应目录：
- 业务逻辑类：`Application/Common/Business/`
- 模型类：`Application/Common/Model/`
- 控制器类：`Application/Api/Controller/` 和 `Application/Admin/Controller/`

### 3. 配置检查
确保以下配置正确：
- 数据库连接配置
- 缓存配置
- 日志配置

### 4. 功能测试
运行测试脚本验证功能：
```bash
php test_rider_system.php
```

## 使用流程

### 1. 骑手注册流程
1. 骑手提交注册信息
2. 后台管理员审核
3. 审核通过后激活账号
4. 骑手登录开始工作

### 2. 订单分配流程
1. 客户下单（原系统）
2. 订单进入待分配状态
3. 系统自动匹配最佳骑手
4. 骑手接收订单通知
5. 骑手确认接单

### 3. 配送流程
1. 骑手前往门店取货
2. 系统检测到达门店
3. 骑手确认取货
4. 开始配送到客户
5. 系统检测到达客户位置
6. 骑手完成配送

### 4. 状态同步流程
1. 骑手端状态变更
2. 触发同步机制
3. 更新原系统订单状态
4. 记录同步日志
5. 发送状态通知

## 配置参数

### 分配算法参数
```php
// 最大分配距离（公里）
'max_dispatch_distance' => 10,

// 骑手最大接单数
'max_orders_per_rider' => 3,

// 分配超时时间（秒）
'dispatch_timeout' => 300,

// 自动重新分配次数
'max_reassign_times' => 3,
```

### 位置追踪参数
```php
// 位置更新间隔（秒）
'location_update_interval' => 30,

// 位置记录保留天数
'location_retention_days' => 30,

// GPS精度要求（米）
'gps_accuracy_threshold' => 50,
```

## 监控和维护

### 1. 日志监控
- 订单分配日志：`ls_rider_order_sync_log`
- 系统错误日志：ThinkPHP日志系统
- 位置追踪日志：`ls_rider_location`

### 2. 性能监控
- 分配响应时间
- 同步成功率
- 骑手在线率
- 订单完成率

### 3. 数据维护
- 定期清理过期位置数据
- 清理过期同步日志
- 备份重要业务数据
- 检查数据一致性

## 常见问题

### Q1: 订单分配失败怎么办？
A: 系统会自动重试分配，如果多次失败会记录日志，管理员可以手动分配。

### Q2: 位置追踪不准确怎么办？
A: 检查GPS精度设置，确保骑手端开启高精度定位，调整精度阈值参数。

### Q3: 状态同步失败怎么办？
A: 系统有自动重试机制，可以查看同步日志定位问题，必要时手动修复数据。

### Q4: 如何优化分配算法？
A: 根据实际业务数据调整各项权重参数，可以通过A/B测试验证效果。

## 技术支持

如有技术问题，请查看：
1. 系统日志文件
2. 数据库错误日志
3. 测试报告文件
4. 本文档常见问题部分

## 版本更新

### v1.0.0 (当前版本)
- 基础订单分配功能
- 位置追踪功能
- 状态同步机制
- 后台管理界面

### 后续规划
- 推送通知功能
- 数据统计分析
- 移动端APP
- 第三方配送平台对接