changelogs-v2/2026-07/28_5295_Step3聚合车辆费用-修改接口-管理后台.md

@@ -4,40 +4,40 @@ ticket: "5295"
 title: "Step3 聚合车辆费用"
 consumer: "admin"
 change_type: "修改接口"
-backend_status: "merged"
-gateway_status: "not_required"
+backend_status: "deployed"
+gateway_status: "verified"
 frontend_status: "pending"
 frontend_owner: ""
 frontend_ref: ""
 target_release: ""
-verified_at: "2026-07-27"
-status_note: "GET/PUT Step3 响应新增 vehicleFees；旧车辆费用 GET/confirm 保留兼容，新页面应停止单独确认动作"
+verified_at: ""
+status_note: "hl-order-service-v3 已通过任务 90374dab 部署测试环境；GET Step3 经网关验证返回 vehicleFees，旧车辆费用接口保留兼容"
 updated_at: "2026-07-28"
 base: "dev-v3"
 ---
 
 # 【修改接口·管理后台】Step3 聚合车辆费用 (#5295)
 
-> **PR**: #5297 | **更新时间**: 2026-07-28 00:00
+> **PR**: #5297 | **更新时间**: 2026-07-28 11:26
 
 ## 1. 接口背景
 
 核单 Step3 页面原来需要分别读取人员费用和车辆总车费，并且车辆费用还有额外确认动作。本次把车辆费用聚合到 Step3 查询和保存响应里：进入 Step3 时同屏拿到人员费用与车辆费用；保存人员费用时，同一次保存会校验车辆费用是否满足核单条件，满足时随响应返回已冻结的车辆费用块。
 
-## 2. 变更清单
+## 变更接口
 
 | # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
 |---|------|------|------|----------|------|
-| 1 | Step 3 查询人员费用核单明细 | GET | `/v3/admin/order/{orderId}/settlement/step3` | 修改接口 | 响应新增 `vehicleFees`，包含车辆费用顶层状态、总金额和逐日明细 |
-| 2 | Step 3 录人员费用核单明细 | PUT | `/v3/admin/order/{orderId}/settlement/step3` | 修改接口 | 保存人员费用时校验车辆费用；满足条件时返回冻结后的 `vehicleFees` |
-| 3 | 查询核单车辆总车费 | GET | `/v3/admin/order/{orderId}/settlement/vehicle-fees` | 保留兼容 | 旧接口仍可用；新 Step3 页面应优先读取 Step3 响应内的 `vehicleFees` |
-| 4 | 确认并冻结核单车辆总车费 | POST | `/v3/admin/order/{orderId}/settlement/vehicle-fees/confirm` | 保留兼容 | 旧接口仍可用；新 Step3 页面应移除单独确认车辆费用的动作 |
+| 1 | Step 3 查询人员费用核单明细 | GET | `/v3/admin/order/:orderId/settlement/step3` | 修改接口 | 响应新增 `vehicleFees`，包含车辆费用顶层状态、总金额和逐日明细 |
+| 2 | Step 3 录人员费用核单明细 | PUT | `/v3/admin/order/:orderId/settlement/step3` | 修改接口 | 保存人员费用时校验车辆费用；满足条件时返回冻结后的 `vehicleFees` |
+| 3 | 查询核单车辆总车费 | GET | `/v3/admin/order/:orderId/settlement/vehicle-fees` | 保留兼容 | 旧接口仍可用；新 Step3 页面应优先读取 Step3 响应内的 `vehicleFees` |
+| 4 | 确认并冻结核单车辆总车费 | POST | `/v3/admin/order/:orderId/settlement/vehicle-fees/confirm` | 保留兼容 | 旧接口仍可用；新 Step3 页面应移除单独确认车辆费用的动作 |
 
 ## 3. 接口详情
 
 ### 3.1 GET Step 3 查询人员费用核单明细
 
-- **方法 + 路径**: `GET /v3/admin/order/{orderId}/settlement/step3`
+- **方法 + 路径**: `GET /v3/admin/order/:orderId/settlement/step3`
 - **接口名**: Step 3 查询人员费用核单明细
 - **使用场景**: 进入核单 Step3 页面时调用，展示人员费用表和车辆费用块。
 - **认证**: 需要管理后台登录态；无权限或未登录按统一鉴权错误返回。
@@ -47,7 +47,7 @@ base: "dev-v3"
 
 ### 3.2 PUT Step 3 录人员费用核单明细
 
-- **方法 + 路径**: `PUT /v3/admin/order/{orderId}/settlement/step3`
+- **方法 + 路径**: `PUT /v3/admin/order/:orderId/settlement/step3`
 - **接口名**: Step 3 录人员费用核单明细
 - **使用场景**: 用户保存 Step3 人员费用时调用。保存成功后，响应内同时回传人员费用结果和车辆费用块。
 - **认证**: 需要管理后台登录态和核单资金写权限。
@@ -87,11 +87,11 @@ GET 无 Query 参数，无请求体。
 
 | `staffRole` | `detail` 结构 | 必填说明 |
 |-------------|---------------|----------|
-| `DRIVER` | `{ "days": [{ "service_date": "2026-07-29", "vehicle_brief": "蒙A****", "daily_fee": "700.00", "is_used": true, "note": "" }], "extra_cost": "0.00", "extra_breakdown": [] }` | `days[]` 必须存在；每个元素必须包含 `service_date`、`daily_fee` |
-| `GUIDE` | `{ "persons": [{ "name": "导游A", "days": 3, "per_day": "300.00", "note": "" }] }` | `persons[]` 必须存在；每个元素必须包含 `name`、`days`、`per_day` |
-| `PHOTOGRAPHER` | `{ "persons": [{ "name": "摄影A", "days": 3, "per_day": "400.00", "note": "" }] }` | `persons[]` 必须存在；每个元素必须包含 `name`、`days`、`per_day` |
-| `LEADER` | `{ "days": 3, "per_day": "500.00" }` | `days`、`per_day` 必须存在 |
-| `OTHER` | `{ "items": [{ "name": "其他人员费用", "amount": "100.00", "note": "" }] }` | `items[]` 用于其他人员费用明细 |
+| `DRIVER` | `days[]`（`service_date`、`vehicle_brief`、`daily_fee`、`is_used`、`note`），以及 `extra_cost`、`extra_breakdown[]` | `days[]` 必须存在；每个元素必须包含 `service_date`、`daily_fee` |
+| `GUIDE` | `persons[]`（`name`、`days`、`per_day`、`note`） | `persons[]` 必须存在；每个元素必须包含 `name`、`days`、`per_day` |
+| `PHOTOGRAPHER` | `persons[]`（`name`、`days`、`per_day`、`note`） | `persons[]` 必须存在；每个元素必须包含 `name`、`days`、`per_day` |
+| `LEADER` | `days`、`per_day` | `days`、`per_day` 必须存在 |
+| `OTHER` | `items[]`（`name`、`amount`、`note`） | `items[]` 用于其他人员费用明细 |
 
 ## 5. 出参字段
 
@@ -502,7 +502,7 @@ Content-Type: application/json
 
 - **是否破坏向后兼容**: 否。Step3 响应新增 `vehicleFees`，旧字段保留；旧车辆费用 GET 和确认 POST 保留兼容。
 - **前端是否必须同步上线**: 否，但建议管理后台 Step3 页面尽快切到 `data.vehicleFees`，并移除额外车辆费用确认动作。
-- **旧页面兼容**: 继续调用旧 `GET /v3/admin/order/{orderId}/settlement/vehicle-fees` 和 `POST /v3/admin/order/{orderId}/settlement/vehicle-fees/confirm` 不会因本次变更直接失效。
+- **旧页面兼容**: 继续调用旧 `GET /v3/admin/order/:orderId/settlement/vehicle-fees` 和 `POST /v3/admin/order/:orderId/settlement/vehicle-fees/confirm` 不会因本次变更直接失效。
 
 ### 11.2 回滚方案
 
@@ -511,12 +511,22 @@ Content-Type: application/json
 
 ## 12. 注意事项
 
-- 新 Step3 页面不要再单独调用 `POST /v3/admin/order/{orderId}/settlement/vehicle-fees/confirm` 作为额外确认按钮或保存后动作。
-- 新 Step3 页面读取车辆费用时优先使用 `GET /v3/admin/order/{orderId}/settlement/step3` 返回的 `data.vehicleFees`。
+- 新 Step3 页面不要再单独调用 `POST /v3/admin/order/:orderId/settlement/vehicle-fees/confirm` 作为额外确认按钮或保存后动作。
+- 新 Step3 页面读取车辆费用时优先使用 `GET /v3/admin/order/:orderId/settlement/step3` 返回的 `data.vehicleFees`。
 - `paymentTypeCode` 是车辆费用付款类型字段，枚举值为 `CASH_PAID`、`SIGNED`、`COMPANY_PAID`；不要用人员费用的 `paymentMethod` 去覆盖车辆费用字段。
 - `totalAmount` 与 `totalVehicleFee` 都表示车辆费用总金额；为兼容旧页面，当前两者应按同一金额展示。
 - `frozen=false` 不等于接口失败；无有效车辆需求或车辆费用尚未满足核单条件时都可能返回未冻结块。
 
+## 验证证据
+
+- 后端 PR [wx/HL#5297](https://git.1814.love:8443/wx/HL/pulls/5297) 已合并至 `dev-v3`，合并提交 `5194183f6`。
+- `dev-v3@ca23f64fc` 执行 `mvn -pl hl-order-service-v3 -am test` 通过。
+- 测试环境滚动部署任务 `90374dab` 成功；`hl-order-service-v3` 8086/8186 双实例健康。
+- 经测试网关只读调用 `GET /v3/admin/order/:orderId/settlement/step3`：HTTP 200、业务码 200，响应包含 `vehicleFees`，样本返回 9 条逐日费用明细。
+- 网关证据：`D:/work2/HL-v3/.tmp/5295-gateway.json`，SHA-256 `dafa5257c4df241e9511c95dba1f689397742133e9f46aefa4701a6d00228ab6`。
+- OpenAPI/oasdiff：项目未配置可复现的 Swagger 2 到 OAS3 导出与 oasdiff，状态为 `not_configured`；已用 Controller/VO 源码对比、Controller 测试和真实网关响应完成人工回退核对。
+- `frontend_status` 保持 `pending`；前端真实领取后再迁移为 `claimed` 并填写 `frontend_owner`。
+
 ## 13. 关联 / 联系人
 
 ### 13.1 链接