9.3 KiB
9.3 KiB
【新增接口·管理后台】核团详情接入真实司机车辆连续服务区间（#5037）
Issue: wx/HL#5037
PR: wx/HL#5048
服务:
hl-order-service-v3/hl-fleet-service日期: 2026-07-18
影响范围: 管理后台订单中心核团详情中的司机车辆展示
契约边界修正：本文只面向前端保留管理端公开接口；Fleet 与 Order v3 之间的 internal Feign 契约已迁至
hl-backend-changelog，不再作为前端对接内容发布。
一、前端对接结论
- 核团详情新增正式接口
GET /v3/admin/order/{orderId}/settlement/return-detail。 - 前端只调用 Order v3 管理端接口；请求只有 Path 参数
orderId，无 Query 参数、无请求体。 - 司机车辆数据来自 Fleet 真实派单，不再生成 mock/占位数据。
driverVehicles永远是数组：无有效派车时返回[]，不会返回null。- Fleet 不可用时返回业务码
584072，前端应显示“暂时不可用/重试”，不得当成“没有派车”。 - 同一
vehicleId + driverId的连续自然日合并为一个闭区间；换车、换司机或日期断档会拆成不同项。 - 同一订单允许多车、多司机并行，前端必须遍历完整数组，不能只展示第一项。
driverId、vehicleId按字符串处理，禁止转 JavaScriptNumber。driverPhone已在 Fleet 出域前脱敏；前端不得尝试补全、缓存或日志打印明文手机号。- 房务管理员、房务组长无订单详情查看权限，调用会返回
581045；该入口面向有订单查看权限的管理端角色。
二、接口清单
| # | 接口 | 方法 | 路径 | 调用方 | 说明 |
|---|---|---|---|---|---|
| 1 | 核团详情 | GET | /v3/admin/order/{orderId}/settlement/return-detail |
管理后台 | 前端正式入口，返回当前有效司机车辆区间 |
三、管理端正式接口
3.1 请求
GET /v3/admin/order/2000000000000000001/settlement/return-detail HTTP/1.1
Authorization: Bearer <admin-token>
3.2 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---|---|---|
orderId |
Path | String | 是 | 正整数 | 订单雪花 ID；按字符串传递 |
无 Query 参数、无请求体。当前有效用车需求由 Order v3 在服务端解析，前端不得缓存或拼接需求版本。
3.3 出参 Result<SettlementReturnDetailRespVO>
| 字段 | 类型 | 必定存在 | 说明 |
|---|---|---|---|
data.driverVehicles |
Array | 是 | 当前有效需求下的司机车辆连续服务区间；无数据固定 [] |
driverVehicles[] 字段：
| 字段 | 类型 | 说明 |
|---|---|---|
driverId |
String / null | 司机 ID；正常最终态有值，异常历史缺档案记录可能为 null |
driverName |
String / null | 司机姓名；档案归档时回退派单快照 |
driverPhone |
String / null | 脱敏手机号，例如 138****0000 |
vehicleId |
String / null | 车辆 ID；按字符串处理 |
vehiclePlateNo |
String / null | 派单车牌快照 |
vehicleModelName |
String / null | 当前车型名，档案归档时回退派单快照 |
seatCount |
Integer / null | 当前车辆座位数 |
startDate |
String | 闭区间开始日期，格式 yyyy-MM-dd |
endDate |
String | 闭区间结束日期，格式 yyyy-MM-dd |
3.4 成功响应
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"driverVehicles": [
{
"driverId": "2000000000000000101",
"driverName": "测试司机",
"driverPhone": "138****0000",
"vehicleId": "2000000000000000201",
"vehiclePlateNo": "蒙A·TEST1",
"vehicleModelName": "测试七座车",
"seatCount": 7,
"startDate": "2026-07-23",
"endDate": "2026-07-28"
}
]
}
}
3.5 空业务结果
订单存在但没有当前有效用车需求、订单已取消，或当前需求没有 assigned/completed 最终派车时：
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"driverVehicles": []
}
}
前端空态判断只能使用 driverVehicles.length === 0，不要判断 data == null。
四、聚合口径
4.1 纳入与排除
| Fleet 派单状态 | 是否展示 | 说明 |
|---|---|---|
assigned |
是 | 已形成最终司机车辆关系 |
completed |
是 | 已形成并完成的最终关系 |
unassigned |
否 | 尚未派车 |
holding |
否 | 排车/司机确认链路未最终完成 |
canceled |
否 | 关系已失效 |
仅查询 Order v3 当前有效 requirementId。历史需求即使保留 assigned/completed 数据，也不会进入当前核团详情。
4.2 连续区间
同车同司机：07-23、07-24、07-25 → 07-23 ~ 07-25（一项）
同车同司机：07-23、07-25 → 两项（日期断档）
同车换司机或同司机换车 → 分项
同日多车并行 → 全部返回
startDate/endDate 都包含当天。前端不得自行补日期、重算关系或按姓名/车牌合并。
五、错误码与前端行为
| code | 含义 | 前端处理 |
|---|---|---|
200 |
查询成功 | 渲染完整 driverVehicles；空数组展示空态 |
400 |
orderId 非正数/参数非法 |
提示参数错误，不发起重试风暴 |
401 |
未登录或登录失效 | 走统一登录失效处理 |
581007 |
订单不存在 | 提示订单不存在/已删除 |
581045 |
房务角色无权查看订单详情 | 隐藏入口并走统一无权限提示 |
584072 |
Fleet 司机车辆信息暂时不可用 | 保留页面上下文，显示错误与重试；禁止渲染空态 |
584072 与成功空数组含义不同：
code=200 + driverVehicles=[] → 业务上确实没有有效司机车辆
code=584072 → 跨服务查询失败，当前状态未知
六、前端接入清单
- 核团详情改调
GET /v3/admin/order/{orderId}/settlement/return-detail。 - 遍历
data.driverVehicles，支持多车、多司机、多区间。 - 所有 ID 保持 String，不经过
Number()、parseInt()。 - 日期按后端闭区间直接展示，不自行合并或补齐断档。
- 空数组显示“暂无有效司机车辆”，不得生成 mock 卡片。
584072显示加载失败与重试，不显示空态。- 房务角色不展示该入口。
七、兼容性与不影响范围
- 新增只读接口，不修改既有核单 Step1～Step6、汇总、日志或提交接口。
- 不修改派单写入、司机确认、改派、取消和完结状态机。
- 不涉及 DDL、Redis Key、MQ Topic 或网关顶级路由变更。
- 既有
MockVehicleProvider仍只服务终止行程/退款金额计算，不参与本接口；金融计算链路不在本次变更范围。 - 本次未修改
hl-ui，需前端按本文完成接入。
八、测试环境验证
8.1 部署
PR #5048 已合并：merge commit 736659cd4
Fleet：Deploy Panel 任务 9d0a2ada，8087/8187 滚动部署成功
Order v3：Deploy Panel 任务 3e4c2c49，8086/8186 滚动部署成功
测试环境随后再次滚动发布同一 dev-v3，16:00:37 完成；当前四端口均监听且 Nacos healthy
8.2 OpenAPI
Order v3 /v2/api-docs?group=default：
/v3/admin/order/{orderId}/settlement/return-detail 存在
operation summary 存在，description 明确包含 584072
8.3 真实 API、DB 与日志
使用测试账号新获取的 CUSTOMIZER token，经 https://api.test.1814.love:9443 验证：
主样本：Fleet DB 6 条连续日切片（2026-07-23 ~ 2026-07-28）
Fleet 8087/8187：均返回 1 个闭区间，与只读 DB 精确一致，手机号已脱敏
Order v3 网关：HTTP 200 / code 200，返回同一 1 个区间
Long ID：driverId/vehicleId 均为 JSON String
空样本：Fleet 最终态 0 行，driverVehicles=[] 且非 null
无 token：code 401
orderId=0：code 400
最终业务探测窗口：Order v3 8086/8186 均 0 ERROR/异常栈；Fleet 双实例 0 ERROR/异常栈
Order v3 全组 OpenAPI 生成仍会记录一条既有 Springfox 超长数字 example 的 NumberFormatException 栈；本次新增 operation 可正常读取，且业务 API 干净窗口无异常。该日志来自既有文档模型，不由 #5037 数据流触发。
九、后端验证证据
最新 dev-v3 rebase 后目标回归：120/120 通过（Order v3 65、Fleet 55）
Fleet 全量 clean verify：1815/1815 通过
Fleet Spotless：502 个生产 Java 文件，0 违规
Order v3 全量：5660 tests；5 项失败均在纯上游基线独立复现，#5037 无新增失败
git diff --check、secret scan、数据流 gate_check：通过
独立盲审、API 契约审计、最终复审：无阻断项
十、回滚
- 无 DDL，代码回滚即可。
- 回滚顺序：先 Order v3，后 Fleet，避免消费者依赖不存在的提供方契约。
- 回滚后前端应兼容接口不可用，不得回退到本地 mock。