# 骑手订单分配系统 - 测试与发布指南 ## 📋 概述 本指南详细说明如何测试和发布订单到骑手端，包括完整的操作流程、API接口使用方法和故障排除指南。 ## 🚀 快速开始 ### 1. 运行测试脚本 ```bash # 完整测试流程 php test_order_dispatch.php # 或者通过Web访问 http://your-domain.com/test_order_dispatch.php ``` ### 2. 查看系统状态 ```bash # 查看骑手和订单状态 php test_order_dispatch.php status # 或者Web访问 http://your-domain.com/test_order_dispatch.php?action=status ``` ## 📊 系统架构 ### 核心组件 1. **订单分配引擎** (`RiderOrderDispatch.class.php`) - 自动分配算法 - 骑手评分计算 - 距离和时间优化 2. **骑手端API** (`RiderApi\Controller\OrderController.class.php`) - 获取可接订单 - 接受/拒绝订单 - 订单状态更新 3. **订单管理** (`RiderOrderController.class.php`) - 订单列表查询 - 状态流转控制 - 配送流程管理 ## 🔄 完整测试流程 ### 步骤1：创建测试订单 ```php // 使用测试脚本创建订单 php test_order_dispatch.php create // 或者手动创建 $orderData = [ 'bill_id' => 'TEST_' . date('YmdHis') . rand(1000, 9999), 'order_no' => 'RO' . date('YmdHis') . rand(1000, 9999), 'merchant_id' => 1, 'store_id' => 1, 'customer_name' => '测试客户', 'customer_phone' => '13800138000', 'delivery_address' => '测试地址', 'delivery_lat' => 39.9042, 'delivery_lng' => 116.4074, 'order_amount' => 58.50, 'delivery_fee' => 8.00, 'total_amount' => 66.50, 'order_type' => 1, 'order_status' => 0, // 待分配 'add_time' => date('Y-m-d H:i:s') ]; ``` ### 步骤2：订单分配 #### 自动分配 ```php $dispatch = new \Common\Business\RiderOrderDispatch(); $result = $dispatch->dispatchOrder([ 'bill_id' => $orderData['bill_id'], 'merchant_id' => $orderData['merchant_id'], 'store_id' => $orderData['store_id'], 'auto_assign' => true ]); ``` #### 手动分配 ```php $result = $dispatch->dispatchOrder([ 'bill_id' => $orderData['bill_id'], 'merchant_id' => $orderData['merchant_id'], 'store_id' => $orderData['store_id'], 'rider_id' => 3, // 指定骑手ID 'auto_assign' => false ]); ``` ### 步骤3：骑手接单 #### 获取可接订单 ```php // API: /RiderApi/Order/getAvailableOrders $orders = $riderController->getAvailableOrders([ 'rider_id' => 3, 'page' => 1, 'limit' => 10 ]); ``` #### 接受订单 ```php // API: /RiderApi/Order/acceptOrder $result = $riderController->acceptOrder([ 'rider_id' => 3, 'order_id' => $orderId ]); ``` ### 步骤4：配送流程 #### 订单状态流转 ``` 0 - 待分配 → 1 - 已接单 → 2 - 已取餐 → 3 - 配送中 → 4 - 已送达 ``` #### 更新订单状态 ```php // API: /RiderApi/Order/updateOrderStatus $result = $riderController->updateOrderStatus([ 'rider_id' => 3, 'order_id' => $orderId, 'status' => 2, // 已取餐 'lat' => 39.9042, 'lng' => 116.4074 ]); ``` ## 🔌 API接口详解 ### 骑手端核心API #### 1. 获取可接订单列表 ``` GET /RiderApi/Order/getAvailableOrders 参数: - rider_id: 骑手ID - page: 页码 (默认1) - limit: 每页数量 (默认10) 返回: { "status": 1, "msg": "获取成功", "data": { "list": [...], "total": 5, "page": 1, "limit": 10 } } ``` #### 2. 接受订单 ``` POST /RiderApi/Order/acceptOrder 参数: - rider_id: 骑手ID - order_id: 订单ID 返回: { "status": 1, "msg": "接单成功", "data": { "order_id": 123, "accept_time": "2024-01-15 14:30:00" } } ``` #### 3. 更新订单状态 ``` POST /RiderApi/Order/updateOrderStatus 参数: - rider_id: 骑手ID - order_id: 订单ID - status: 新状态 (1-4) - lat: 当前纬度 (可选) - lng: 当前经度 (可选) 返回: { "status": 1, "msg": "状态更新成功", "data": { "order_id": 123, "new_status": 2, "update_time": "2024-01-15 14:35:00" } } ``` #### 4. 获取当前订单 ``` GET /RiderApi/Order/getCurrentOrder 参数: - rider_id: 骑手ID 返回: { "status": 1, "msg": "获取成功", "data": { "order_id": 123, "order_no": "RO20240115001", "status": 2, "customer_info": {...}, "delivery_info": {...} } } ``` ### 管理端API #### 1. 订单分配 ``` POST /Admin/RiderOrder/dispatchOrder 参数: - bill_id: 订单编号 - merchant_id: 商户ID - store_id: 门店ID - rider_id: 骑手ID (可选，用于手动分配) - auto_assign: 是否自动分配 (true/false) 返回: { "status": 1, "msg": "分配成功", "data": { "order_id": 123, "rider_id": 3, "rider_name": "张三", "assign_time": "2024-01-15 14:25:00" } } ``` #### 2. 获取可用骑手 ``` POST /Admin/RiderOrder/getAvailableRiders 参数: - merchant_id: 商户ID - store_id: 门店ID - order_lat: 订单纬度 - order_lng: 订单经度 返回: { "status": 1, "msg": "获取成功", "data": [ { "id": 3, "rider_name": "张三", "phone": "13800138000", "distance": 1.2, "score": 85.5, "current_orders": 1, "max_orders": 3 } ] } ``` ## 🧪 测试场景 ### 场景1：正常订单流程测试 1. **创建订单** → 2. **自动分配** → 3. **骑手接单** → 4. **配送完成** ```bash # 运行完整测试 php test_order_dispatch.php full ``` ### 场景2：手动分配测试 ```php // 指定骑手分配 $dispatch = new \Common\Business\RiderOrderDispatch(); $result = $dispatch->dispatchOrder([ 'bill_id' => 'TEST_20240115001', 'rider_id' => 3, 'auto_assign' => false ]); ``` ### 场景3：高峰期压力测试 ```php // 批量创建订单测试 for ($i = 0; $i < 10; $i++) { $test = new OrderDispatchTest(); $orderId = $test->createTestOrder(); $test->testOrderDispatch($orderId); } ``` ### 场景4：异常情况测试 - 无可用骑手 - 骑手拒绝订单 - 网络异常 - 位置信息缺失 ## 📱 骑手端集成 ### 移动端接入 #### 1. 初始化配置 ```javascript // 骑手端配置 const riderConfig = { apiBaseUrl: 'http://your-domain.com/RiderApi', riderId: 3, autoRefresh: true, refreshInterval: 30000 // 30秒 }; ``` #### 2. 获取订单列表 ```javascript async function getAvailableOrders() { const response = await fetch(`${riderConfig.apiBaseUrl}/Order/getAvailableOrders`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ rider_id: riderConfig.riderId, page: 1, limit: 10 }) }); const result = await response.json(); return result; } ``` #### 3. 接受订单 ```javascript async function acceptOrder(orderId) { const response = await fetch(`${riderConfig.apiBaseUrl}/Order/acceptOrder`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ rider_id: riderConfig.riderId, order_id: orderId }) }); const result = await response.json(); return result; } ``` #### 4. 更新位置和状态 ```javascript async function updateOrderStatus(orderId, status, location) { const response = await fetch(`${riderConfig.apiBaseUrl}/Order/updateOrderStatus`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ rider_id: riderConfig.riderId, order_id: orderId, status: status, lat: location.lat, lng: location.lng }) }); const result = await response.json(); return result; } ``` ## 🔧 配置说明 ### 骑手配置参数 ```sql -- 骑手信息表关键字段 ALTER TABLE ls_rider_info ADD COLUMN max_orders_per_time INT DEFAULT 3 COMMENT '同时接单上限'; ALTER TABLE ls_rider_info ADD COLUMN auto_accept_orders TINYINT DEFAULT 0 COMMENT '是否自动接单'; ALTER TABLE ls_rider_info ADD COLUMN min_delivery_fee DECIMAL(10,2) DEFAULT 0 COMMENT '最低配送费'; ALTER TABLE ls_rider_info ADD COLUMN max_delivery_distance DECIMAL(10,2) DEFAULT 10 COMMENT '最大配送距离(km)'; ALTER TABLE ls_rider_info ADD COLUMN work_start_time TIME DEFAULT '08:00:00' COMMENT '工作开始时间'; ALTER TABLE ls_rider_info ADD COLUMN work_end_time TIME DEFAULT '22:00:00' COMMENT '工作结束时间'; ``` ### 系统配置参数 ```php // 配置文件 Application/Common/Conf/config.php 'RIDER_SYSTEM' => [ 'AUTO_DISPATCH_ENABLED' => true, // 启用自动分配 'MAX_DISPATCH_DISTANCE' => 10, // 最大分配距离(km) 'DISPATCH_TIMEOUT' => 300, // 分配超时时间(秒) 'RIDER_RESPONSE_TIMEOUT' => 60, // 骑手响应超时(秒) 'MAX_RETRY_COUNT' => 3, // 最大重试次数 'SCORE_WEIGHTS' => [ // 评分权重 'distance' => 0.4, // 距离权重 'rating' => 0.3, // 评分权重 'on_time_rate' => 0.2, // 准时率权重 'order_count' => 0.1 // 订单数权重 ] ] ``` ## 🚨 故障排除 ### 常见问题 #### 1. 订单分配失败 **问题**: 订单创建后无法分配给骑手 **解决方案**: - 检查骑手状态 (`work_status = 1` 且 `auth_status = 2`) - 确认骑手位置信息完整 - 验证门店和订单位置信息 - 检查骑手当前订单数量是否达到上限 ```sql -- 检查骑手状态 SELECT id, rider_name, work_status, auth_status, current_orders, max_orders_per_time FROM ls_rider_info WHERE status = 1; -- 检查订单信息 SELECT id, bill_id, order_status, delivery_lat, delivery_lng, store_lat, store_lng FROM ls_rider_order WHERE order_status = 0; ``` #### 2. 骑手无法接单 **问题**: 骑手端显示无可接订单 **解决方案**: - 确认骑手认证状态 - 检查工作时间设置 - 验证接单偏好配置 - 确认网络连接正常 ```php // 调试骑手接单条件 $riderInfo = M('rider_info')->find($riderId); var_dump([ 'work_status' => $riderInfo['work_status'], 'auth_status' => $riderInfo['auth_status'], 'current_time' => date('H:i:s'), 'work_start_time' => $riderInfo['work_start_time'], 'work_end_time' => $riderInfo['work_end_time'] ]); ``` #### 3. 位置信息异常 **问题**: 距离计算错误或位置信息缺失 **解决方案**: - 检查GPS坐标格式 (纬度在前，经度在后) - 确认坐标系统一致性 (建议使用WGS84) - 验证坐标范围合理性 ```php // 验证坐标有效性 function validateCoordinates($lat, $lng) { return ($lat >= -90 && $lat <= 90) && ($lng >= -180 && $lng <= 180); } ``` #### 4. 订单状态同步问题 **问题**: 订单状态更新不及时或不一致 **解决方案**: - 检查数据库连接 - 确认事务处理正确 - 验证缓存更新机制 - 检查并发处理逻辑 ### 调试工具 #### 1. 日志查看 ```bash # 查看系统日志 tail -f Runtime/Logs/Common/24_01_15.log # 查看错误日志 tail -f Runtime/Logs/Common/24_01_15_error.log ``` #### 2. 数据库调试 ```sql -- 开启SQL日志 SET GLOBAL general_log = 'ON'; SET GLOBAL general_log_file = '/var/log/mysql/mysql.log'; -- 查看慢查询 SHOW PROCESSLIST; ``` #### 3. 性能监控 ```php // 添加性能监控 $startTime = microtime(true); // ... 业务逻辑 ... $endTime = microtime(true); $executionTime = ($endTime - $startTime) * 1000; error_log("执行时间: {$executionTime}ms"); ``` ## 📈 性能优化 ### 数据库优化 #### 1. 索引优化 ```sql -- 骑手信息表索引 ALTER TABLE ls_rider_info ADD INDEX idx_work_status (work_status, auth_status, status); ALTER TABLE ls_rider_info ADD INDEX idx_location (lat, lng); -- 订单表索引 ALTER TABLE ls_rider_order ADD INDEX idx_status_time (order_status, add_time); ALTER TABLE ls_rider_order ADD INDEX idx_rider_status (rider_id, order_status); ALTER TABLE ls_rider_order ADD INDEX idx_location (delivery_lat, delivery_lng); ``` #### 2. 查询优化 ```php // 使用合适的查询条件 $riders = M('rider_info') ->field('id, rider_name, lat, lng, current_orders, max_orders_per_time') ->where([ 'work_status' => 1, 'auth_status' => 2, 'status' => 1, 'merchant_id' => $merchantId ]) ->limit(50) // 限制查询数量 ->select(); ``` ### 缓存策略 #### 1. Redis缓存 ```php // 缓存骑手位置信息 $redis = new Redis(); $redis->setex("rider_location_{$riderId}", 300, json_encode([ 'lat' => $lat, 'lng' => $lng, 'update_time' => time() ])); ``` #### 2. 内存缓存 ```php // 使用静态变量缓存计算结果 class RiderOrderDispatch { private static $distanceCache = []; private function calculateDistance($lat1, $lng1, $lat2, $lng2) { $key = "{$lat1},{$lng1},{$lat2},{$lng2}"; if (!isset(self::$distanceCache[$key])) { self::$distanceCache[$key] = $this->haversineDistance($lat1, $lng1, $lat2, $lng2); } return self::$distanceCache[$key]; } } ``` ## 📋 部署清单 ### 生产环境部署 #### 1. 环境检查 - [ ] PHP 版本 >= 5.6 - [ ] MySQL 版本 >= 5.7 - [ ] Redis 服务正常 - [ ] 网络连接稳定 - [ ] SSL证书配置 #### 2. 数据库准备 - [ ] 执行数据库迁移脚本 - [ ] 创建必要的索引 - [ ] 配置数据库连接池 - [ ] 设置备份策略 #### 3. 配置文件 - [ ] 更新数据库配置 - [ ] 设置Redis连接 - [ ] 配置日志级别 - [ ] 设置错误报告 #### 4. 测试验证 - [ ] 运行单元测试 - [ ] 执行集成测试 - [ ] 进行压力测试 - [ ] 验证API接口 #### 5. 监控告警 - [ ] 配置系统监控 - [ ] 设置错误告警 - [ ] 建立日志分析 - [ ] 制定应急预案 ## 📞 技术支持 如果在使用过程中遇到问题，请按以下步骤排查： 1. **查看日志文件** - 检查系统和错误日志 2. **运行测试脚本** - 使用 `test_order_dispatch.php` 验证功能 3. **检查配置** - 确认数据库和系统配置正确 4. **联系技术支持** - 提供详细的错误信息和日志 --- **最后更新**: 2024年1月15日 **版本**: v1.0.0 **维护者**: 骑手订单分配系统开发团队