diff --git a/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md b/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md index e2be7d5..453c9cf 100644 --- a/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md +++ b/changelogs-v2/2026-07/18_5037_核团详情司机车辆连续服务区间-新增接口-管理后台.md @@ -10,10 +10,13 @@ > > **影响范围**: 管理后台订单中心核团详情中的司机车辆展示 +> **契约边界修正**:本文只面向前端保留管理端公开接口;Fleet 与 Order v3 之间的 +> internal Feign 契约已迁至 `hl-backend-changelog`,不再作为前端对接内容发布。 + ## 一、前端对接结论 1. 核团详情新增正式接口 `GET /v3/admin/order/{orderId}/settlement/return-detail`。 -2. 前端只调用 Order v3 管理端接口,不得直接调用 Fleet internal API,也不需要传 `currentRequirementId`。 +2. 前端只调用 Order v3 管理端接口;请求只有 Path 参数 `orderId`,无 Query 参数、无请求体。 3. 司机车辆数据来自 Fleet 真实派单,不再生成 mock/占位数据。 4. `driverVehicles` 永远是数组:无有效派车时返回 `[]`,不会返回 `null`。 5. Fleet 不可用时返回业务码 `584072`,前端应显示“暂时不可用/重试”,不得当成“没有派车”。 @@ -28,7 +31,6 @@ | # | 接口 | 方法 | 路径 | 调用方 | 说明 | |---|---|---|---|---|---| | 1 | 核团详情 | GET | `/v3/admin/order/{orderId}/settlement/return-detail` | 管理后台 | 前端正式入口,返回当前有效司机车辆区间 | -| 2 | 订单司机车辆区间 | GET | `/internal/fleet/orders/{orderId}/driver-vehicles` | Order v3 Feign | 内部契约,前端禁止直调 | ## 三、管理端正式接口 @@ -152,21 +154,7 @@ 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`,支持多车、多司机、多区间。 @@ -175,9 +163,8 @@ X-Internal-Token: - [ ] 空数组显示“暂无有效司机车辆”,不得生成 mock 卡片。 - [ ] `584072` 显示加载失败与重试,不显示空态。 - [ ] 房务角色不展示该入口。 -- [ ] 不调用 `/internal/fleet/**`。 -## 八、兼容性与不影响范围 +## 七、兼容性与不影响范围 - 新增只读接口,不修改既有核单 Step1~Step6、汇总、日志或提交接口。 - 不修改派单写入、司机确认、改派、取消和完结状态机。 @@ -185,9 +172,9 @@ X-Internal-Token: - 既有 `MockVehicleProvider` 仍只服务终止行程/退款金额计算,不参与本接口;金融计算链路不在本次变更范围。 - 本次未修改 `hl-ui`,需前端按本文完成接入。 -## 九、测试环境验证 +## 八、测试环境验证 -### 9.1 部署 +### 8.1 部署 ```text PR #5048 已合并:merge commit 736659cd4 @@ -196,19 +183,15 @@ Order v3:Deploy Panel 任务 3e4c2c49,8086/8186 滚动部署成功 测试环境随后再次滚动发布同一 dev-v3,16:00:37 完成;当前四端口均监听且 Nacos healthy ``` -### 9.2 OpenAPI +### 8.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 与日志 +### 8.3 真实 API、DB 与日志 使用测试账号新获取的 `CUSTOMIZER` token,经 `https://api.test.1814.love:9443` 验证: @@ -225,7 +208,7 @@ orderId=0:code 400 Order v3 全组 OpenAPI 生成仍会记录一条既有 Springfox 超长数字 example 的 `NumberFormatException` 栈;本次新增 operation 可正常读取,且业务 API 干净窗口无异常。该日志来自既有文档模型,不由 #5037 数据流触发。 -## 十、后端验证证据 +## 九、后端验证证据 ```text 最新 dev-v3 rebase 后目标回归:120/120 通过(Order v3 65、Fleet 55) @@ -236,13 +219,13 @@ 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)