docs(order): 发布核团详情司机车辆契约 (#5037)

2026-07-18 16:06:53 +08:00 · 2026-07-18 16:06:53 +08:00 · 575111baee
--- a/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md
+++ 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 <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 成功响应
+
+```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: <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`