修订 Step3 聚合车辆费用前端 changelog

- 删除兼容保留的车辆费用独立接口说明
- 明确 PUT Step3 响应仅表达成功或失败

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

@@ -11,7 +11,7 @@ frontend_owner: "hl-ui-pi"
 frontend_ref: "0a35da1e3b88f9c375d3e79516780e5a66f2b8ad"
 target_release: ""
 verified_at: "2026-07-28T14:38:26+08:00"
-status_note: "hl-order-service-v3 已部署并通过网关验证；hl-admin 已改用 Step3 GET/PUT 聚合 vehicleFees，旧 GET 仅缺字段时回退，独立确认动作已移除；全量 checkpoint 通过"
+status_note: "hl-order-service-v3 已部署并通过网关验证；hl-admin 已改用 Step3 GET 聚合 vehicleFees，PUT 保存响应仅按成功/失败处理；全量 checkpoint 通过"
 updated_at: "2026-07-28"
 base: "dev-v3"
 ---
@@ -22,16 +22,14 @@ base: "dev-v3"
 
 ## 1. 接口背景
 
-核单 Step3 页面原来需要分别读取人员费用和车辆总车费，并且车辆费用还有额外确认动作。本次把车辆费用聚合到 Step3 查询和保存响应里：进入 Step3 时同屏拿到人员费用与车辆费用；保存人员费用时，同一次保存会校验车辆费用是否满足核单条件，满足时随响应返回已冻结的车辆费用块。
+核单 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` |
+| 2 | Step 3 录人员费用核单明细 | PUT | `/v3/admin/order/:orderId/settlement/step3` | 修改接口 | 保存人员费用时校验车辆费用；响应只表达成功或失败，`data` 不返回操作数据 ID |
-| 3 | 查询核单车辆总车费 | GET | `/v3/admin/order/:orderId/settlement/vehicle-fees` | 保留兼容 | 旧接口仍可用；新 Step3 页面应优先读取 Step3 响应内的 `vehicleFees` |
-| 4 | 确认并冻结核单车辆总车费 | POST | `/v3/admin/order/:orderId/settlement/vehicle-fees/confirm` | 保留兼容 | 旧接口仍可用；新 Step3 页面应移除单独确认车辆费用的动作 |
 
 ## 3. 接口详情
 
@@ -49,11 +47,11 @@ base: "dev-v3"
 
 - **方法 + 路径**: `PUT /v3/admin/order/:orderId/settlement/step3`
 - **接口名**: Step 3 录人员费用核单明细
-- **使用场景**: 用户保存 Step3 人员费用时调用。保存成功后，响应内同时回传人员费用结果和车辆费用块。
+- **使用场景**: 用户保存 Step3 人员费用时调用。保存成功以 `code=200` 和 `message` 表达，`data` 不返回新增、更新、删除 ID 或车辆费用块。
 - **认证**: 需要管理后台登录态和核单资金写权限。
-- **幂等性**: 同一 `items` 内容重复提交，人员费用结果保持一致；车辆费用已冻结后再次保存仍返回冻结块。
+- **幂等性**: 同一 `items` 内容重复提交，人员费用结果保持一致；车辆费用已冻结后再次保存仍按成功或失败返回。
 - **限流**: 无接口级特殊限流。
-- **响应类型**: `Result<SettlementStaffFeesSaveRespVO>`
+- **响应类型**: `Result<Void>`
 
 ## 4. 接口入参
 
@@ -100,19 +98,16 @@ GET 无 Query 参数，无请求体。
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `code` | Integer | 业务状态码；`200` 表示成功 |
-| `data` | Object/null | 成功时为 `SettlementStaffFeesSaveRespVO`；失败时通常为 `null` |
+| `data` | Object/null | GET 成功时为 `SettlementStaffFeesSaveRespVO`；PUT 成功和失败时为 `null` |
 | `message` | String | 响应消息 |
 
-### 5.2 `data` 字段
+### 5.2 GET 成功响应 `data` 字段
 
 | 字段 | 类型 | 说明 |
 |------|------|------|
-| `addedIds` | Array<String> | PUT 成功时新增的人员费用行 ID；GET 可为空数组 |
-| `updatedIds` | Array<String> | PUT 成功时更新的人员费用行 ID；GET 可为空数组 |
-| `deletedIds` | Array<String> | PUT 成功时软删的人员费用行 ID；GET 可为空数组 |
 | `totalActualCost` | String(decimal) | 人员费用实际成本合计 |
 | `items` | Array<StaffFeeRespItem> | 人员费用明细行 |
-| `vehicleFees` | Object | 本次新增：车辆费用块；无有效车辆需求时仍返回对象，`items=[]`、金额为 `0.00`、`frozen=false` |
+| `vehicleFees` | Object | GET 本次新增：车辆费用块；无有效车辆需求时仍返回对象，`items=[]`、金额为 `0.00`、`frozen=false` |
 
 ### 5.3 `data.items[]` 人员费用明细
 
@@ -140,7 +135,7 @@ GET 无 Query 参数，无请求体。
 | 字段 | 类型 | 说明 |
 |------|------|------|
 | `orderId` | String | 订单 ID |
-| `frozen` | Boolean | 车辆费用是否已冻结；PUT 成功冻结后为 `true` |
+| `frozen` | Boolean | 车辆费用是否已冻结；保存成功并冻结后，后续 GET 返回 `true` |
 | `requirementId` | String/null | 当前车辆需求 ID；无有效车辆需求时为 `null` |
 | `settlementReady` | Boolean | 车辆费用是否满足核单条件；为 `false` 时 PUT 可能返回 `584101` |
 | `totalAmount` | String(decimal) | 车辆费用总金额 |
@@ -228,9 +223,6 @@ Authorization: Bearer <token>
   "code": 200,
   "message": "success",
   "data": {
-    "addedIds": [],
-    "updatedIds": [],
-    "deletedIds": [],
     "totalActualCost": "3600.00",
     "items": [
       {
@@ -386,9 +378,6 @@ Authorization: Bearer <token>
   "code": 200,
   "message": "success",
   "data": {
-    "addedIds": [],
-    "updatedIds": [],
-    "deletedIds": [],
     "totalActualCost": "0.00",
     "items": [],
     "vehicleFees": {
@@ -404,7 +393,60 @@ Authorization: Bearer <token>
 }
 ```
 
-### 8.3 业务失败：PUT 时车辆费用未满足核单条件
+### 8.3 典型成功：PUT Step3 只返回成功结果
+
+**请求**:
+
+```http
+PUT /v3/admin/order/2079454953641836546/settlement/step3
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+```json
+{
+  "items": [
+    {
+      "id": "9300000000001",
+      "staffRole": "DRIVER",
+      "staffId": "6800001001",
+      "detail": {
+        "days": [
+          {
+            "service_date": "2026-07-29",
+            "vehicle_brief": "蒙A12345",
+            "daily_fee": "700.00",
+            "is_used": true,
+            "note": ""
+          }
+        ],
+        "extra_cost": "0.00",
+        "extra_breakdown": []
+      },
+      "reimburse": "0.00",
+      "paymentMethod": "COMPANY_PAID",
+      "voucherUrls": [],
+      "settlementConfirmStatus": "UNCONFIRMED",
+      "settleStatus": "PENDING",
+      "settledDate": null,
+      "transferRef": null,
+      "remark": ""
+    }
+  ]
+}
+```
+
+**响应**:
+
+```json
+{
+  "code": 200,
+  "message": "success",
+  "data": null
+}
+```
+
+### 8.4 业务失败：PUT 时车辆费用未满足核单条件
 
 **请求**:
 
@@ -459,11 +501,11 @@ Content-Type: application/json
 
 ## 9. 业务边界
 
-- **适用场景**: 核单 Step3 页面查询和保存；页面需要同时展示人员费用与车辆费用时，直接使用 Step3 响应。
+- **适用场景**: 核单 Step3 页面查询和保存；页面需要同时展示人员费用与车辆费用时，直接使用 GET Step3 响应。
 - **车辆费用可为空的场景**: 订单没有有效车辆需求时，GET Step3 返回 `vehicleFees.items=[]`、`frozen=false`、`settlementReady=false`、金额为 `0.00`。
 - **PUT 保存门禁**: 存在有效车辆需求时，PUT Step3 会校验车辆费用是否满足核单条件；不满足时返回 `584101`，本次人员费用保存不视为成功。
 - **空明细门禁**: 存在有效车辆需求但没有可核单车辆费用明细时，PUT Step3 返回 `584102`。
-- **已冻结场景**: 车辆费用已冻结后，GET/PUT Step3 都返回冻结后的 `vehicleFees`。
+- **已冻结场景**: 车辆费用已冻结后，GET Step3 返回冻结后的 `vehicleFees`。
 
 ## 10. 修改前后对比
 
@@ -471,47 +513,44 @@ Content-Type: application/json
 
 | 字段 | 改前 | 改后 |
 |------|------|------|
-| `data.vehicleFees` | GET/PUT Step3 不返回 | GET/PUT Step3 均返回车辆费用块 |
+| `data`（PUT Step3） | 返回新增、更新、删除 ID 等操作数据 | 只表达成功或失败，成功时 `data=null` |
-| `data.vehicleFees.frozen` | 无 | 返回车辆费用是否冻结 |
+| `data.vehicleFees` | GET Step3 不返回 | GET Step3 返回车辆费用块 |
-| `data.vehicleFees.requirementId` | 无 | 返回当前车辆需求 ID；无有效车辆需求时为 `null` |
+| `data.vehicleFees.frozen` | 无 | GET Step3 返回车辆费用是否冻结 |
-| `data.vehicleFees.settlementReady` | 无 | 返回车辆费用是否满足核单条件 |
+| `data.vehicleFees.requirementId` | 无 | GET Step3 返回当前车辆需求 ID；无有效车辆需求时为 `null` |
-| `data.vehicleFees.totalAmount` | 无 | 返回车辆费用总金额 |
+| `data.vehicleFees.settlementReady` | 无 | GET Step3 返回车辆费用是否满足核单条件 |
-| `data.vehicleFees.totalVehicleFee` | 无 | 返回车辆费用总金额兼容字段 |
+| `data.vehicleFees.totalAmount` | 无 | GET Step3 返回车辆费用总金额 |
-| `data.vehicleFees.items[]` | 无 | 返回逐日车辆费用明细 |
+| `data.vehicleFees.totalVehicleFee` | 无 | GET Step3 返回车辆费用总金额兼容字段 |
-| `data.vehicleFees.items[].sourceDetailId` | 无 | 返回逐日费用来源明细 ID |
+| `data.vehicleFees.items[]` | 无 | GET Step3 返回逐日车辆费用明细 |
-| `data.vehicleFees.items[].serviceDate` | 无 | 返回逐日服务日期 |
+| `data.vehicleFees.items[].sourceDetailId` | 无 | GET Step3 返回逐日费用来源明细 ID |
-| `data.vehicleFees.items[].dailyPrice` | 无 | 返回当日车费 |
+| `data.vehicleFees.items[].serviceDate` | 无 | GET Step3 返回逐日服务日期 |
-| `data.vehicleFees.items[].paymentTypeCode` | 无 | 返回车辆费用付款类型编码 |
+| `data.vehicleFees.items[].dailyPrice` | 无 | GET Step3 返回当日车费 |
-| `data.vehicleFees.items[].paymentTypeName` | 无 | 返回车辆费用付款类型名称 |
+| `data.vehicleFees.items[].paymentTypeCode` | 无 | GET Step3 返回车辆费用付款类型编码 |
-| `data.vehicleFees.items[].amount` | 无 | 返回本条核单金额 |
+| `data.vehicleFees.items[].paymentTypeName` | 无 | GET Step3 返回车辆费用付款类型名称 |
-| `data.vehicleFees.items[].settlementReady` | 无 | 返回本条车辆费用是否满足核单条件 |
+| `data.vehicleFees.items[].amount` | 无 | GET Step3 返回本条核单金额 |
+| `data.vehicleFees.items[].settlementReady` | 无 | GET Step3 返回本条车辆费用是否满足核单条件 |
 
 ### 10.2 行为级对比
 
 | 行为 | 改前 | 改后 |
 |------|------|------|
 | 进入 Step3 页面 | 需要单独读取人员费用和车辆费用 | 调用 GET Step3 即可拿到人员费用与车辆费用 |
-| 保存 Step3 | 只保存人员费用 | 保存人员费用时同步校验车辆费用；满足条件时返回冻结后的车辆费用 |
+| 保存 Step3 | 只保存人员费用，响应可能携带操作数据 ID | 保存人员费用时同步校验车辆费用；成功响应 `data=null`，不返回新增、更新、删除 ID |
-| 车辆费用确认 | 前端可能单独调用 `POST /settlement/vehicle-fees/confirm` | 新 Step3 页面应停止单独调用，移除额外确认动作 |
+| 无有效车辆需求 | Step3 查询无法直接表达车辆费用空态 | GET Step3 内直接返回空未冻结 `vehicleFees` 块 |
-| 旧 GET 车辆费用 | 作为车辆费用主要读取入口 | 保留兼容；新 Step3 页面优先读 `data.vehicleFees` |
-| 无有效车辆需求 | 需要前端自行处理独立接口空态 | GET Step3 内直接返回空未冻结 `vehicleFees` 块 |
 
 ## 11. 影响评估 / 回滚
 
 ### 11.1 影响评估
 
-- **是否破坏向后兼容**: 否。Step3 响应新增 `vehicleFees`，旧字段保留；旧车辆费用 GET 和确认 POST 保留兼容。
+- **是否破坏向后兼容**: 否。GET Step3 响应新增 `vehicleFees`，PUT Step3 成功响应 `data=null`。
-- **前端是否必须同步上线**: 否，但建议管理后台 Step3 页面尽快切到 `data.vehicleFees`，并移除额外车辆费用确认动作。
+- **前端是否必须同步上线**: 否，但建议管理后台 Step3 页面尽快切到 `data.vehicleFees`，并按 PUT Step3 成功响应不含操作数据 ID 处理。
-- **旧页面兼容**: 继续调用旧 `GET /v3/admin/order/:orderId/settlement/vehicle-fees` 和 `POST /v3/admin/order/:orderId/settlement/vehicle-fees/confirm` 不会因本次变更直接失效。
 
 ### 11.2 回滚方案
 
-- **回滚后前端表现**: 如果回滚到旧契约，GET/PUT Step3 不再包含 `data.vehicleFees`；前端需要保留对 `vehicleFees` 缺失的空值兼容。
+- **回滚后前端表现**: 如果回滚到旧契约，GET Step3 不再包含 `data.vehicleFees`；前端需要保留对 `vehicleFees` 缺失的空值兼容。
-- **前端兼容建议**: 读取 `data.vehicleFees` 前先判空；为空时可降级到旧车辆费用 GET。
+- **前端兼容建议**: 读取 `data.vehicleFees` 前先判空；为空时按车辆费用空态展示。
 
 ## 12. 注意事项
 
-- 新 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` 都表示车辆费用总金额；为兼容旧页面，当前两者应按同一金额展示。