# 跨城改派功能升级 - 司机端接口文档（最终版） ## 文档信息 - **版本**: v2.0 - **更新日期**: 2026-06-25 - **适用端**: 司机端（Android） - **基础URL**: `http://api.yourdomain.com` --- ## 📋 需求概述 ### 功能变更 跨城改派功能升级，司机可改派的范围从"仅同批次同时间司机"扩大为： 1. **同批次同时间司机**（无需确认，直接改派） 2. **其他同公司司机**（需要确认，Socket推送，60秒超时） ### 业务流程 #### 流程1：同批次改派（原有逻辑） ``` 司机A发起改派 → 选择同批次司机B → 支付 → 直接改派成功 ✅ ``` #### 流程2：其他司机改派（新增） ``` 司机A发起改派 → 选择其他司机C → 支付 → Socket推送给司机C（60秒倒计时）→ 司机C点击同意/拒绝 → 同意：创建临时排班，改派成功 ✅ 拒绝：通知司机A被拒绝 ❌ 超时：通知司机A超时 ❌ ``` --- ## 🔄 接口变更说明 ### 1. 查询可改派司机列表（已修改）⭐ **接口**: `GET /queryOtherDriverShiftListWithShiftId` **变更内容**: - **新增参数**: `orderId`（改派场景必传） - **响应变更**: 新增 `needConfirm` 字段 - `needConfirm=1`: 不需要确认（同批次），可直接改派 - `needConfirm=2`: 需要确认（其他司机），需Socket推送 --- ### 2. 提交改派申请（保持不变） **接口**: `POST /api/orderCrossCity/reassignOrderCrossCityReassign` **说明**: 接口名称和参数保持不变，后端会自动判断是否需要确认 --- ### 3. 司机响应改派接口（新增）⭐ **接口**: `POST /api/orderCrossCity/respondReassign` **用途**: 司机收到改派推送后，点击"同意"或"拒绝" --- ### 4. 查询待确认改派列表（新增）⭐ **接口**: `POST /api/orderCrossCity/queryPendingReassigns` **用途**: 查询当前司机待确认的改派申请列表 --- ### 5. Socket消息（新增4种）⭐ - `REASSIGN_CONFIRM_REQUEST` - 改派确认请求 - `REASSIGN_SUCCESS` - 改派成功通知 - `REASSIGN_REJECTED` - 改派被拒绝通知 - `REASSIGN_TIMEOUT` - 改派超时通知 --- ## 📡 接口详情 ### 1. 查询可改派司机列表（已修改）⭐ #### 基本信息 - **接口**: `GET /queryOtherDriverShiftListWithShiftId` - **说明**: 查询可以改派的司机列表 - **变更**: - ✅ 新增 `orderId` 参数（改派场景必传） - ✅ 响应中新增 `needConfirm` 字段 #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | driverShiftId | Long | 是 | 司机排班记录ID | | orderIds | String | **改派场景必传** | 订单ID（⭐新增，多个以逗号分隔，如"123,456"） | #### 请求示例 ``` GET /queryOtherDriverShiftListWithShiftId?driverShiftId=123456&orderIds=789,790 ``` #### 响应参数 | 参数名 | 类型 | 说明 | |-------|------|------| | code | Integer | 状态码，200=成功 | | msg | String | 提示信息 | | data | Array | 司机列表 | | ├─ lineShiftDriverId | Integer | 司机排班ID | | ├─ driverId | Integer | 司机ID | | ├─ driverName | String | 司机姓名 | | ├─ headImgUrl | String | 司机头像 | | ├─ carLicensePlate | String | 车牌号 | | ├─ carColor | String | 车辆颜色 | | ├─ carModel | String | 车辆品牌型号 | | ├─ totalSeat | Integer | 总座位数 | | ├─ laveSeat | Integer | 剩余座位数 | | ├─ score | Double | 司机评分 | | ├─ startTime | String | 班次时间（如"08:00-09:00"） | | ├─ **needConfirm** | **Integer** | **⭐ 是否需要确认（1=不需要，2=需要）** | #### 响应示例 ```json { "code": 200, "msg": "success", "data": [ { "lineShiftDriverId": 1001, "driverId": 5001, "driverName": "李师傅", "headImgUrl": "http://example.com/avatar/5001.jpg", "carLicensePlate": "京A12345", "carColor": "白色", "carModel": "大众帕萨特", "totalSeat": 5, "laveSeat": 3, "score": 4.8, "startTime": "08:00-09:00", "needConfirm": 1 // ⭐ 不需要确认，同批次司机 }, { "lineShiftDriverId": null, "driverId": 5002, "driverName": "王师傅", "headImgUrl": "http://example.com/avatar/5002.jpg", "carLicensePlate": "京B67890", "carColor": "黑色", "carModel": "本田雅阁", "totalSeat": 5, "laveSeat": 5, "score": 4.9, "startTime": "08:00-09:00", "needConfirm": 2 // ⭐ 需要确认，其他司机 } ] } ``` #### ⚠️ Android端改动要点 ```kotlin // 原有调用（不传orderIds，仍然兼容） api.queryOtherDriverShiftListWithShiftId(driverShiftId) // 新调用（改派场景，必须传orderIds） // 单个订单 api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789") // 多个订单（逗号分隔） api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789,790,791") ``` #### 向后兼容 - ✅ 如果**不传** `orderIds`，返回同批次司机，`needConfirm` 默认为 1 - ✅ 如果**传了** `orderIds`，返回同批次+其他司机，`needConfirm` 根据实际情况返回 1 或 2 - ✅ 多个订单时，使用第一个订单ID进行判断 --- ### 2. 提交改派申请（保持不变） #### 基本信息 - **接口**: `POST /api/orderCrossCity/reassignOrderCrossCityReassign` - **说明**: 提交改派申请 - **变更**: 无（接口保持不变，后端自动判断） #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | orderIds | String | 是 | 订单ID（多个以逗号分隔） | | payType | Integer | 否 | 改派支付方式（1=微信，2=支付宝，3=余额） | | reason | String | 是 | 改派原因 | | remark | String | 否 | 备注 | | nowDriverId | Integer | 否 | 指定的新司机ID（⚠️注意：这里传的是 lineShiftDriverId，不是 driverId） | #### 请求示例 ```json { "orderIds": "123456", "payType": 3, "reason": "临时有事", "remark": "", "nowDriverId": 1001 // 从司机列表中选择的 lineShiftDriverId } ``` #### 后端自动判断逻辑 - 如果选择的司机 `needConfirm=1`：直接改派 - 如果选择的司机 `needConfirm=2`：发送Socket推送，等待确认 #### Android端无需修改 - ✅ 保持原有调用方式 - ✅ 后端自动判断是否需要确认 - ✅ Android端只需监听新的Socket消息 --- ### 3. 司机响应改派接口（新增）⭐ #### 基本信息 - **接口**: `POST /api/orderCrossCity/respondReassign` - **说明**: 司机收到改派推送后，点击"同意"或"拒绝"调用此接口 - **幂等性**: ✅ 支持，重复点击返回友好提示 #### 请求头 ``` Authorization: Bearer {token} ``` #### 请求参数 | 参数名 | 类型 | 必填 | 说明 | |-------|------|------|------| | reassignId | Integer | 是 | 改派申请ID | | responseType | Integer | 是 | 响应类型：1=同意，2=拒绝 | #### 请求示例 ```json { "reassignId": 12345, "responseType": 1 // 1=同意，2=拒绝 } ``` #### 响应参数 | 参数名 | 类型 | 说明 | |-------|------|------| | code | Integer | 状态码，200=成功 | | msg | String | 提示信息 | | data | Object | 空 | #### 响应示例 **成功（同意）**: ```json { "code": 200, "msg": "改派成功", "data": null } ``` **成功（拒绝）**: ```json { "code": 200, "msg": "已拒绝改派", "data": null } ``` **失败（已被其他司机接受）**: ```json { "code": 500, "msg": "该改派申请已被其他司机接受或已过期", "data": null } ``` **失败（已超时）**: ```json { "code": 500, "msg": "该改派申请已超时", "data": null } ``` #### 错误码说明 | 错误信息 | 说明 | |---------|------| | 改派申请不存在 | reassignId 无效 | | 无权操作 | 当前司机不是目标司机 | | 该改派申请已被接受 | 已经被处理（重复点击） | | 该改派申请已被拒绝 | 已经被处理 | | 该改派申请已超时 | 超过60秒未响应 | | 该改派申请已被其他司机接受或已过期 | 并发场景，被其他司机抢先接受 | | 订单不存在 | 订单已取消或删除 | | 订单状态已变更，无法改派 | 订单已完成或取消 | --- ### 4. 查询待确认改派列表（新增）⭐ #### 基本信息 - **接口**: `POST /api/orderCrossCity/queryPendingReassigns` - **说明**: 查询当前司机待确认的改派申请列表（可用于"改派通知"页面） #### 请求头 ``` Authorization: Bearer {token} ``` #### 请求参数 无（从token中获取司机ID） #### 响应参数 | 参数名 | 类型 | 说明 | |-------|------|------| | code | Integer | 状态码，200=成功 | | msg | String | 提示信息 | | data | Array | 待确认改派列表 | | ├─ reassignId | Integer | 改派申请ID | | ├─ orderId | Integer | 订单ID | | ├─ orderType | Integer | 订单类型（3=跨城） | | ├─ startAddress | String | 起点地址 | | ├─ endAddress | String | 终点地址 | | ├─ peopleNumber | Integer | 乘客人数 | | ├─ travelTime | String | 出行时间 | | ├─ orderMoney | Double | 订单金额 | | ├─ expireTime | String | 超时时间 | | ├─ reason | String | 改派原因 | | ├─ insertTime | String | 申请时间 | | ├─ originalDriverName | String | 原司机姓名 | | ├─ originalDriverPhone | String | 原司机手机号（脱敏） | #### 响应示例 ```json { "code": 200, "msg": "success", "data": [ { "reassignId": 12345, "orderId": 456789, "orderType": 3, "startAddress": "北京站", "endAddress": "天津站", "peopleNumber": 3, "travelTime": "2026-06-25 08:00:00", "orderMoney": 150.00, "expireTime": "2026-06-25 07:31:00", "reason": "临时有事", "insertTime": "2026-06-25 07:30:00", "originalDriverName": "张师傅", "originalDriverPhone": "138****1234" } ] } ``` --- ## 🔔 Socket 消息 ### 连接信息 - **协议**: WebSocket - **URL**: `ws://api.yourdomain.com/socket` - **认证**: 连接时传递token --- ### 1. 改派确认请求（REASSIGN_CONFIRM_REQUEST）⭐ #### 触发时机 当其他司机发起改派，选择你作为目标司机时 #### 消息格式 ```json { "type": "REASSIGN_CONFIRM_REQUEST", "reassignId": 12345, "orderId": 456789, "startAddress": "北京站", "endAddress": "天津站", "peopleNumber": 3, "travelTime": "2026-06-25 08:00:00", "expireTime": "2026-06-25 07:31:00", "money": 150.00 } ``` #### 前端处理 ```kotlin when (message.type) { "REASSIGN_CONFIRM_REQUEST" -> { // 弹出全屏确认对话框 showReassignConfirmDialog(message) // 开始60秒倒计时 startCountdown(message.expireTime) // 播放提示音 + 震动 playNotification() } } ``` --- ### 2. 改派成功通知（REASSIGN_SUCCESS） #### 触发时机 你发起的改派请求被对方同意时 #### 消息格式 ```json { "type": "REASSIGN_SUCCESS", "reassignId": 12345, "orderId": 456789 } ``` --- ### 3. 改派被拒绝通知（REASSIGN_REJECTED） #### 触发时机 你发起的改派请求被对方拒绝时 #### 消息格式 ```json { "type": "REASSIGN_REJECTED", "reassignId": 12345, "orderId": 456789 } ``` --- ### 4. 改派超时通知（REASSIGN_TIMEOUT） #### 触发时机 你发起的改派请求超过60秒未响应时 #### 消息格式 ```json { "type": "REASSIGN_TIMEOUT", "reassignId": 12345, "orderId": 456789 } ``` --- ## 📋 Android端改动总结 ### 必须改动（3处） #### 1. 查询司机列表接口 ```kotlin // 原有代码 api.queryOtherDriverShiftListWithShiftId(driverShiftId) // ⭐ 改为（改派场景） api.queryOtherDriverShiftListWithShiftId(driverShiftId, orderId) ``` #### 2. 处理 needConfirm 字段 ```kotlin data class OtherDriverShiftWarpper( val driverId: Int, val driverName: String, // ... val needConfirm: Int // ⭐ 新增字段 ) // UI展示 when (driver.needConfirm) { 1 -> showBadge("同批次") // 不需要确认 2 -> showBadge("需确认") // 需要确认 } ``` #### 3. Socket消息处理 ```kotlin // ⭐ 新增4种消息处理 when (message.type) { "REASSIGN_CONFIRM_REQUEST" -> showConfirmDialog() "REASSIGN_SUCCESS" -> showSuccessToast() "REASSIGN_REJECTED" -> showRejectedDialog() "REASSIGN_TIMEOUT" -> showTimeoutDialog() } ``` ### 新增接口（2个） #### 1. 响应改派接口 ```kotlin @POST("/api/orderCrossCity/respondReassign") fun respondReassign( @Field("reassignId") reassignId: Int, @Field("responseType") responseType: Int // 1=同意, 2=拒绝 ): Call ``` #### 2. 查询待确认列表接口 ```kotlin @POST("/api/orderCrossCity/queryPendingReassigns") fun queryPendingReassigns(): Call>> ``` --- ## 🧪 测试清单 ### 接口测试 - [ ] 传 orderId 参数，验证返回 needConfirm 字段 - [ ] 不传 orderId 参数，验证向后兼容 - [ ] 同意改派接口调用成功 - [ ] 拒绝改派接口调用成功 - [ ] 查询待确认列表正常返回 - [ ] 重复点击同意，返回友好提示 ### Socket 测试 - [ ] 收到改派确认请求推送 - [ ] 收到改派成功通知 - [ ] 收到改派拒绝通知 - [ ] 收到改派超时通知 ### UI 测试 - [ ] 司机列表正确显示 needConfirm 标识 - [ ] 改派确认对话框正确展示 - [ ] 60秒倒计时正确显示 - [ ] 提示音和震动正常 --- ## 📞 技术支持 如有疑问，请联系后端开发团队。 --- **文档版本**: v2.0（最终版） **最后更新**: 2026-06-25 **适用版本**: 司机端 v2.0+