约客多
blame | 历史 | 原始文档

跨城改派功能升级 - 司机端接口文档（最终版）

文档信息

  • 版本: 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=需要）

响应示例

{
  "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端改动要点

// 原有调用（不传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）

请求示例

{
  "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=拒绝

请求示例

{
  "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 原司机手机号（脱敏）

响应示例

{
  "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）⭐

触发时机

当其他司机发起改派，选择你作为目标司机时

消息格式

{
  "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
}

前端处理

when (message.type) {
    "REASSIGN_CONFIRM_REQUEST" -> {
        // 弹出全屏确认对话框
        showReassignConfirmDialog(message)
        
        // 开始60秒倒计时
        startCountdown(message.expireTime)
        
        // 播放提示音 + 震动
        playNotification()
    }
}

2. 改派成功通知（REASSIGN_SUCCESS）

触发时机

你发起的改派请求被对方同意时

消息格式

{
  "type": "REASSIGN_SUCCESS",
  "reassignId": 12345,
  "orderId": 456789
}

3. 改派被拒绝通知（REASSIGN_REJECTED）

触发时机

你发起的改派请求被对方拒绝时

消息格式

{
  "type": "REASSIGN_REJECTED",
  "reassignId": 12345,
  "orderId": 456789
}

4. 改派超时通知（REASSIGN_TIMEOUT）

触发时机

你发起的改派请求超过60秒未响应时

消息格式

{
  "type": "REASSIGN_TIMEOUT",
  "reassignId": 12345,
  "orderId": 456789
}

📋 Android端改动总结

必须改动（3处）

1. 查询司机列表接口

// 原有代码
api.queryOtherDriverShiftListWithShiftId(driverShiftId)

// ⭐ 改为（改派场景）
api.queryOtherDriverShiftListWithShiftId(driverShiftId, orderId)

2. 处理 needConfirm 字段

data class OtherDriverShiftWarpper(
    val driverId: Int,
    val driverName: String,
    // ...
    val needConfirm: Int  // ⭐ 新增字段
)

// UI展示
when (driver.needConfirm) {
    1 -> showBadge("同批次")  // 不需要确认
    2 -> showBadge("需确认")  // 需要确认
}

3. Socket消息处理

// ⭐ 新增4种消息处理
when (message.type) {
    "REASSIGN_CONFIRM_REQUEST" -> showConfirmDialog()
    "REASSIGN_SUCCESS" -> showSuccessToast()
    "REASSIGN_REJECTED" -> showRejectedDialog()
    "REASSIGN_TIMEOUT" -> showTimeoutDialog()
}

新增接口（2个）

1. 响应改派接口

@POST("/api/orderCrossCity/respondReassign")
fun respondReassign(
    @Field("reassignId") reassignId: Int,
    @Field("responseType") responseType: Int  // 1=同意, 2=拒绝
): Call<BaseResponse>

2. 查询待确认列表接口

@POST("/api/orderCrossCity/queryPendingReassigns")
fun queryPendingReassigns(): Call<BaseResponse<List<PendingReassign>>>

🧪 测试清单

接口测试

  • [ ] 传 orderId 参数，验证返回 needConfirm 字段
  • [ ] 不传 orderId 参数，验证向后兼容
  • [ ] 同意改派接口调用成功
  • [ ] 拒绝改派接口调用成功
  • [ ] 查询待确认列表正常返回
  • [ ] 重复点击同意，返回友好提示

Socket 测试

  • [ ] 收到改派确认请求推送
  • [ ] 收到改派成功通知
  • [ ] 收到改派拒绝通知
  • [ ] 收到改派超时通知

UI 测试

  • [ ] 司机列表正确显示 needConfirm 标识
  • [ ] 改派确认对话框正确展示
  • [ ] 60秒倒计时正确显示
  • [ ] 提示音和震动正常

📞 技术支持

如有疑问，请联系后端开发团队。

文档版本: v2.0（最终版）
最后更新: 2026-06-25
适用版本: 司机端 v2.0+