diff --git a/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md b/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md new file mode 100644 index 0000000..e2be7d5 --- /dev/null +++ b/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md @@ -0,0 +1,250 @@ +# 【新增接口·管理后台】核团详情接入真实司机车辆连续服务区间(#5037) + +> **Issue**: [wx/HL#5037](https://git.1814.love:8443/wx/HL/issues/5037) +> +> **PR**: [wx/HL#5048](https://git.1814.love:8443/wx/HL/pulls/5048) +> +> **服务**: `hl-order-service-v3` / `hl-fleet-service` +> +> **日期**: 2026-07-18 +> +> **影响范围**: 管理后台订单中心核团详情中的司机车辆展示 + +## 一、前端对接结论 + +1. 核团详情新增正式接口 `GET /v3/admin/order/{orderId}/settlement/return-detail`。 +2. 前端只调用 Order v3 管理端接口,不得直接调用 Fleet internal API,也不需要传 `currentRequirementId`。 +3. 司机车辆数据来自 Fleet 真实派单,不再生成 mock/占位数据。 +4. `driverVehicles` 永远是数组:无有效派车时返回 `[]`,不会返回 `null`。 +5. Fleet 不可用时返回业务码 `584072`,前端应显示“暂时不可用/重试”,不得当成“没有派车”。 +6. 同一 `vehicleId + driverId` 的连续自然日合并为一个闭区间;换车、换司机或日期断档会拆成不同项。 +7. 同一订单允许多车、多司机并行,前端必须遍历完整数组,不能只展示第一项。 +8. `driverId`、`vehicleId` 按字符串处理,禁止转 JavaScript `Number`。 +9. `driverPhone` 已在 Fleet 出域前脱敏;前端不得尝试补全、缓存或日志打印明文手机号。 +10. 房务管理员、房务组长无订单详情查看权限,调用会返回 `581045`;该入口面向有订单查看权限的管理端角色。 + +## 二、接口清单 + +| # | 接口 | 方法 | 路径 | 调用方 | 说明 | +|---|---|---|---|---|---| +| 1 | 核团详情 | GET | `/v3/admin/order/{orderId}/settlement/return-detail` | 管理后台 | 前端正式入口,返回当前有效司机车辆区间 | +| 2 | 订单司机车辆区间 | GET | `/internal/fleet/orders/{orderId}/driver-vehicles` | Order v3 Feign | 内部契约,前端禁止直调 | + +## 三、管理端正式接口 + +### 3.1 请求 + +```http +GET /v3/admin/order/2000000000000000001/settlement/return-detail HTTP/1.1 +Authorization: Bearer +``` + +### 3.2 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `orderId` | Path | String | 是 | 正整数 | 订单雪花 ID;按字符串传递 | + +无 Query 参数、无请求体。当前有效用车需求由 Order v3 在服务端解析,前端不得缓存或拼接需求版本。 + +### 3.3 出参 `Result` + +| 字段 | 类型 | 必定存在 | 说明 | +|---|---|---|---| +| `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 成功响应 + +```json +{ + "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` 最终派车时: + +```json +{ + "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 连续区间 + +```text +同车同司机: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` 与成功空数组含义不同: + +```text +code=200 + driverVehicles=[] → 业务上确实没有有效司机车辆 +code=584072 → 跨服务查询失败,当前状态未知 +``` + +## 六、内部 Feign 契约(前端不可调用) + +```http +GET /internal/fleet/orders/{orderId}/driver-vehicles?currentRequirementId={requirementId} +X-Internal-Token: +``` + +| 参数 | 类型 | 必填 | 说明 | +|---|---|---|---| +| `orderId` | Long | 是 | 订单 ID | +| `currentRequirementId` | Long | 是 | Order v3 本地解析的当前有效用车需求 ID | + +该接口归 Fleet 所有。Order v3 只通过 Feign 消费,Fleet 不同步回调 Order,因此不存在 `Order → Fleet → Order` 环形调用。 + +## 七、前端接入清单 + +- [ ] 核团详情改调 `GET /v3/admin/order/{orderId}/settlement/return-detail`。 +- [ ] 遍历 `data.driverVehicles`,支持多车、多司机、多区间。 +- [ ] 所有 ID 保持 String,不经过 `Number()`、`parseInt()`。 +- [ ] 日期按后端闭区间直接展示,不自行合并或补齐断档。 +- [ ] 空数组显示“暂无有效司机车辆”,不得生成 mock 卡片。 +- [ ] `584072` 显示加载失败与重试,不显示空态。 +- [ ] 房务角色不展示该入口。 +- [ ] 不调用 `/internal/fleet/**`。 + +## 八、兼容性与不影响范围 + +- 新增只读接口,不修改既有核单 Step1~Step6、汇总、日志或提交接口。 +- 不修改派单写入、司机确认、改派、取消和完结状态机。 +- 不涉及 DDL、Redis Key、MQ Topic 或网关顶级路由变更。 +- 既有 `MockVehicleProvider` 仍只服务终止行程/退款金额计算,不参与本接口;金融计算链路不在本次变更范围。 +- 本次未修改 `hl-ui`,需前端按本文完成接入。 + +## 九、测试环境验证 + +### 9.1 部署 + +```text +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 +``` + +### 9.2 OpenAPI + +```text +Fleet /v2/api-docs?group=default: + /internal/fleet/orders/{orderId}/driver-vehicles 存在 + currentRequirementId required=true + +Order v3 /v2/api-docs?group=default: + /v3/admin/order/{orderId}/settlement/return-detail 存在 + operation summary 存在,description 明确包含 584072 +``` + +### 9.3 真实 API、DB 与日志 + +使用测试账号新获取的 `CUSTOMIZER` token,经 `https://api.test.1814.love:9443` 验证: + +```text +主样本: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 数据流触发。 + +## 十、后端验证证据 + +```text +最新 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。 + +## 十二、关联链接 + +- Issue: [#5037](https://git.1814.love:8443/wx/HL/issues/5037) +- PR: [#5048](https://git.1814.love:8443/wx/HL/pulls/5048) +- Merge commit: [736659cd4](https://git.1814.love:8443/wx/HL/commit/736659cd4) +- 车务读模型统一说明: `60_4936_车务看板详情候选与矩阵读模型统一-管理后台.md`