跨城改派功能升级 - Android端接口变更总结

📅 发布信息

发布日期: 2026-06-25
版本: v2.0
影响范围: 司机端 Android

🎯 核心变更

原有接口名称保持不变 ✅

GET /queryOtherDriverShiftListWithShiftId - 查询可改派司机（已扩展）
POST /api/orderCrossCity/reassignOrderCrossCityReassign - 提交改派（保持不变）

接口参数变更

1. queryOtherDriverShiftListWithShiftId（必改）⭐

// 原有调用
api.queryOtherDriverShiftListWithShiftId(driverShiftId)

// ⭐ 新调用（改派场景必须传orderIds）
// 单个订单
api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789")

// 多个订单（逗号分隔）
api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789,790,791")

参数说明:
- driverShiftId: 司机排班ID（原有）
- orderIds: 订单ID字符串（⭐新增，改派场景必传，多个以逗号分隔）

向后兼容:
- 不传 orderIds 仍然可用（返回同批次司机，needConfirm=1）
- 传了 orderIds 返回同批次+其他司机（needConfirm=1或2）
- 多个订单时，使用第一个订单ID进行判断

2. 响应字段变更

{
  "lineShiftDriverId": 1001,
  "driverId": 5001,
  "driverName": "李师傅",
  "needConfirm": 1  // ⭐ 新增字段
}

needConfirm 字段说明:
- 1 = 不需要确认（同批次司机，直接改派）
- 2 = 需要确认（其他司机，Socket推送）

新增接口（2个）

1. 响应改派接口

POST /api/orderCrossCity/respondReassign

用途: 司机收到改派推送后，点击"同意"或"拒绝"

2. 查询待确认列表

POST /api/orderCrossCity/queryPendingReassigns

用途: 查询待确认的改派申请列表

新增Socket消息（4种）

when (message.type) {
    "REASSIGN_CONFIRM_REQUEST" -> // 收到改派确认请求
    "REASSIGN_SUCCESS" -> // 改派成功通知
    "REASSIGN_REJECTED" -> // 改派被拒绝通知
    "REASSIGN_TIMEOUT" -> // 改派超时通知
}

📱 Android端改动清单

必须改动（3处）

✅ 1. 修改接口调用
```kotlin
// 改派场景必须传orderIds（字符串，多个以逗号分隔）
api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789")

// 多个订单
api.queryOtherDriverShiftListWithShiftId(driverShiftId, "789,790,791")
```

✅ 2. 数据模型添加字段
kotlin data class OtherDriverShiftWarpper( // ... 原有字段 val needConfirm: Int // ⭐ 新增 )

✅ 3. UI展示needConfirm
kotlin when (driver.needConfirm) { 1 -> showDirectReassign() // 直接改派 2 -> showNeedConfirm() // 需要确认 }

新增功能（4处）

✅ 4. 新增响应改派接口
kotlin @POST("/api/orderCrossCity/respondReassign") fun respondReassign( @Field("reassignId") reassignId: Int, @Field("responseType") responseType: Int ): Call<BaseResponse>

✅ 5. 新增查询待确认接口
kotlin @POST("/api/orderCrossCity/queryPendingReassigns") fun queryPendingReassigns(): Call<BaseResponse<List<PendingReassign>>>

✅ 6. 处理4种新Socket消息
- REASSIGN_CONFIRM_REQUEST（显示确认对话框）
- REASSIGN_SUCCESS（显示成功提示）
- REASSIGN_REJECTED（显示被拒绝提示）
- REASSIGN_TIMEOUT（显示超时提示）

✅ 7. 改派确认对话框UI
- 全屏对话框
- 60秒倒计时
- 订单详情展示
- 同意/拒绝按钮

🔄 业务流程

旧流程（同批次改派）

选择司机 → 提交改派 → 直接成功 ✅

新流程（其他司机改派）

选择司机 → 提交改派 → Socket推送 → 
等待60秒 → 同意/拒绝/超时

🧪 测试要点

接口测试

查询司机列表，验证 needConfirm 字段
不传 orderId，验证向后兼容
传 orderId，验证返回扩展司机列表
同意改派，验证创建临时排班
拒绝改派，验证通知原司机
重复点击，验证幂等性

Socket测试

收到改派确认请求推送
60秒倒计时显示
同意后收到成功通知
拒绝后原司机收到通知
超时后自动取消

并发测试⭐

多个司机同时点击"同意"
预期：只有1个成功，其他返回"已被接受"

📄 完整文档

详细文档请查看：
- documents/android_api_documentation_final.md - 完整接口文档
- documents/reassign_upgrade_final_summary.md - 功能总结
- documents/reassign_idempotency_protection.md - 幂等性说明

⏰ 开发时间估算

任务	预估时间
接口参数修改	0.5小时
数据模型添加字段	0.5小时
UI展示needConfirm	1小时
新增响应改派接口	2小时
Socket消息处理	2小时
改派确认对话框UI	3小时
测试验证	2小时
总计	11小时

✅ 验收标准

[ ] 查询司机列表返回 needConfirm 字段
[ ] needConfirm=1 的司机点击后直接改派
[ ] needConfirm=2 的司机点击后发送推送
[ ] 收到推送后显示确认对话框
[ ] 60秒倒计时正常
[ ] 点击同意后改派成功
[ ] 点击拒绝后通知原司机
[ ] 超时后自动取消
[ ] 重复点击返回友好提示
[ ] 并发点击只有1个成功

🆘 常见问题

Q: 必须传orderIds吗？
A: 改派场景必须传，否则只返回同批次司机（功能受限）

Q: orderIds格式是什么？
A: 字符串格式，多个订单以逗号分隔，如 "123,456,789"

Q: 多个订单如何处理？
A: 后端使用第一个订单ID进行判断是否需要确认

Q: 向后兼容吗？
A: 完全兼容，不传orderId仍可使用旧逻辑

Q: nowDriverId传什么？
A: 传 lineShiftDriverId，不是 driverId

Q: Socket断线怎么办？
A: 实现自动重连，重连后调用查询待确认列表接口

Q: 60秒如何计算？
A: 后端返回 expireTime，前端计算剩余秒数

发布时间: 2026-06-25
责任人: 后端开发团队
联系方式: xxx@company.com