新增车辆Tab三接口汇总通知

2026-08-05 17:58:27 +08:00 · 2026-08-05 17:58:27 +08:00 · 16e592a497
--- a/changelogs-v2/2026-08/05_5356_车辆Tab三接口汇总-修改接口-管理后台.md
+++ b/changelogs-v2/2026-08/05_5356_车辆Tab三接口汇总-修改接口-管理后台.md
@ -0,0 +1,709 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5356"
+title: "车辆 Tab 三接口汇总"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "partial"
+frontend_status: "implemented"
+frontend_owner: "Pi"
+frontend_ref: "v2.1@21dccf38d1413b098cfd5a456d3fb76611581ebb"
+target_release: ""
+verified_at: "2026-08-02"
+status_note: "汇总 #5356、#5360、#5380 已实现的车辆 Tab 现行契约；管理后台使用 Step3 GET/PUT 和 vehicle-options，并按 settlementReady/blockReasonCode 区分车辆两类空态。"
+updated_at: "2026-08-05"
+base: "dev-v3"
+---
+
+# 🔧【修改接口·管理后台】车辆 Tab 三接口汇总 (#5356 / #5360 / #5380)
+
+> **服务**：`hl-order-service-v3` ｜ **更新时间**：2026-08-05 ｜ **消费端**：管理后台
+
+## 1. 接口背景
+
+车辆核单 Tab 需要一份可直接对接的完整契约：先用车辆下拉接口检索手工行候选，再读取车辆核单草稿，最后按草稿版本全量保存。本文汇总三个现行接口，并纳入车辆草稿查询的最新空状态语义；不替代或修改三份历史通知。
+
+## 2. 变更清单
+
+| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 查询车辆核单草稿 | `GET` | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 修改 | 返回车辆核单全量草稿；空结果用 `settlementReady/blockReasonCode` 区分是否可继续核单 |
+| 2 | 全量保存车辆核单草稿 | `PUT` | `/v3/admin/order/{orderId}/settlement/step3/vehicles` | 修改 | 携带 `version` 全量保存，保护 `FLEET` 权威行并返回保存后的完整草稿 |
+| 3 | 查询核单车辆异步下拉 | `GET` | `/v3/admin/order/{orderId}/settlement/vehicle-options` | 新增 | 按车牌、品牌型号、车型大类或常驻司机姓名检索候选车辆 |
+
+三个接口均要求管理后台登录态和订单查看权限，房务角色不可访问；无接口级特殊限流。两个 GET 为只读幂等，PUT 以当前 `version` 和全量 `items` 保存。
+
+## 3. 接口详情
+
+### 3.1 查询车辆核单草稿
+
+- **接口说明**：查询车辆 Tab 当前全量明细、草稿版本、确认状态以及车辆费用是否具备完成核单条件。
+- **方法与路径**：`GET /v3/admin/order/{orderId}/settlement/step3/vehicles`
+- **认证**：管理后台登录态；需满足订单查看权限；房务角色不可访问。
+- **幂等性**：是，只读查询。
+- **限流**：未声明独立限流规则。
+
+**路径参数**
+
+| 字段 | 类型 | 必填 | 说明与校验 |
+|---|---|---|---|
+| `orderId` | String(Long) | 是 | 订单 ID，必须为正整数；按字符串传递 |
+
+无 Query 参数、无请求体。
+
+**统一响应外层**
+
+| 字段 | 类型 | 可空 | 说明 |
+|---|---|---|---|
+| `code` | Integer | 否 | 成功为 `200` |
+| `message` | String | 否 | 结果说明 |
+| `data` | VehicleDraft/null | 失败时为空 | 成功时为车辆核单草稿 |
+| `traceId` | String | 是 | 链路追踪 ID |
+| `success` | Boolean | 否 | `code=200` 时为 `true` |
+
+**成功响应 `data`**
+
+| 字段 | 类型 | 可空 | 说明 |
+|---|---|---|---|
+| `orderId` | String(Long) | 否 | 订单 ID，按字符串返回 |
+| `version` | Long | 否 | 当前草稿版本；首次空结果为 `0` |
+| `totalAmount` | Decimal | 否 | 全部车辆明细金额合计；空结果为 `0.00` |
+| `allConfirmed` | Boolean | 否 | 非空明细是否全部确认；空状态取值见判定表 |
+| `settlementReady` | Boolean | 否 | 车辆费用是否具备完成核单条件 |
+| `blockReasonCode` | String/null | 是 | 不具备条件时的机器可读原因；具备条件时为 `null` |
+| `items` | VehicleItem[] | 否 | 当前全量明细；无明细时为 `[]` |
+
+**`data.items[]`**
+
+| 字段 | 类型 | 可空 | 说明 |
+|---|---|---|---|
+| `id` | String(Long) | 否 | 车辆核单明细 ID |
+| `sourceType` | String | 否 | `FLEET` 或 `MANUAL` |
+| `sourceTypeName` | String | 否 | 车务或手工 |
+| `serviceDate` | String(date) | 否 | 服务日期，`YYYY-MM-DD` |
+| `vehicleId` | String(Long) | 是 | 车辆 ID |
+| `vehiclePlate` | String | 是 | 车牌号 |
+| `vehicleModelId` | String(Long) | 是 | 车型 ID |
+| `vehicleModelName` | String | 是 | 车型名称 |
+| `driverId` | String(Long) | 是 | 司机 ID |
+| `driverName` | String | 是 | 司机姓名 |
+| `amount` | Decimal | 否 | 核单金额 |
+| `paymentMethod` | String | 否 | 付款方式编码，见 §6.2 |
+| `paymentMethodName` | String | 否 | 付款方式名称 |
+| `settlementConfirmStatus` | String | 否 | 确认状态编码，见 §6.3 |
+| `settlementConfirmStatusName` | String | 否 | 未确认或已确认 |
+| `remark` | String | 是 | 备注 |
+| `voucherUrls` | String[] | 否 | 凭证 URL；无凭证时为 `[]` |
+
+**错误码**
+
+| code | 含义 | 触发场景 |
+|---|---|---|
+| `400` | 请求参数错误 | `orderId` 不是正整数 |
+| `403` | 无访问权限 | 登录态或角色无权访问 |
+| `581007` | 订单不存在 | `orderId` 对应订单不存在 |
+| `584071` | 无权访问该订单 | 当前账号不在订单可访问范围内 |
+| `584100` | 车辆费用暂时不可用 | 车辆费用来源调用失败、响应身份不匹配或必要字段无效 |
+| `584101` | 车辆费用尚未满足核单条件 | 已有非空车辆明细，但来源未完结或费用条件未满足 |
+
+`584102` 不再表示“有需求但费用尚未生成”；该场景现在返回 `code=200` 的阻断空状态。
+
+**业务边界与空状态判定**
+
+| 场景 | `items` | `totalAmount` | `settlementReady` | `blockReasonCode` | `allConfirmed` | 结果 |
+|---|---|---|---|---|---|---|
+| 无当前用车需求 | `[]` | `0.00` | `true` | `null` | `true` | 成功，可继续完成核单 |
+| 有当前用车需求，但费用尚未生成 | `[]` | `0.00` | `false` | `VEHICLE_FEE_NOT_READY` | `false` | 成功，但不能完成核单 |
+| 有明细、来源就绪，仍有未确认行 | 非空 | 明细合计 | `true` | `null` | `false` | 成功，需先确认明细 |
+| 有明细、来源就绪且全部确认 | 非空 | 明细合计 | `true` | `null` | `true` | 成功，可继续完成核单 |
+
+- `items=[]` 不是失败判据，必须读取 `settlementReady`。
+- `allConfirmed=true` 只说明没有未确认行，能否完成核单仍以 `settlementReady` 为准。
+- 车辆来源失败或必要字段无效仍返回业务错误，不转换为空结果。
+
+**典型成功请求**
+
+```http
+GET /v3/admin/order/900000000001/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**典型成功响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "900000000001",
+    "version": 4,
+    "totalAmount": 1200.00,
+    "allConfirmed": true,
+    "settlementReady": true,
+    "blockReasonCode": null,
+    "items": [
+      {
+        "id": "930000000001",
+        "sourceType": "FLEET",
+        "sourceTypeName": "车务",
+        "serviceDate": "2026-08-01",
+        "vehicleId": "880000000001",
+        "vehiclePlate": "藏A12345",
+        "vehicleModelId": "870000000001",
+        "vehicleModelName": "七座商务车",
+        "driverId": "860000000001",
+        "driverName": "张师傅",
+        "amount": 1200.00,
+        "paymentMethod": "COMPANY_PAID",
+        "paymentMethodName": "公司付款",
+        "settlementConfirmStatus": "CONFIRMED",
+        "settlementConfirmStatusName": "已确认",
+        "remark": "金额已核对",
+        "voucherUrls": []
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+**边界请求：有需求但费用未就绪**
+
+```http
+GET /v3/admin/order/900000000003/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**边界响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "900000000003",
+    "version": 0,
+    "totalAmount": 0.00,
+    "allConfirmed": false,
+    "settlementReady": false,
+    "blockReasonCode": "VEHICLE_FEE_NOT_READY",
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+**边界请求：无当前用车需求**
+
+```http
+GET /v3/admin/order/900000000002/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**边界响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "900000000002",
+    "version": 0,
+    "totalAmount": 0.00,
+    "allConfirmed": true,
+    "settlementReady": true,
+    "blockReasonCode": null,
+    "items": []
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+**业务失败请求：车辆来源暂时不可用**
+
+```http
+GET /v3/admin/order/900000000004/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**业务失败响应**
+
+```json
+{
+  "code": 584100,
+  "message": "车务车辆总车费暂时不可用，请稍后重试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+### 3.2 全量保存车辆核单草稿
+
+- **接口说明**：携带查询所得版本，全量保存车辆核单行并返回保存后的完整草稿。
+- **方法与路径**：`PUT /v3/admin/order/{orderId}/settlement/step3/vehicles`
+- **认证**：管理后台登录态；需满足订单查看及核单写权限；房务角色不可访问。
+- **幂等性**：业务语义为全量替换；成功后版本递增，原请求不可原样重放，使用旧版本重试会返回 `584108`。
+- **限流**：未声明独立限流规则。
+
+**路径参数**
+
+| 字段 | 类型 | 必填 | 说明与校验 |
+|---|---|---|---|
+| `orderId` | String(Long) | 是 | 订单 ID，必须为正整数；按字符串传递 |
+
+无 Query 参数。
+
+**请求体**
+
+| 字段 | 类型 | 必填 | 说明与校验 |
+|---|---|---|---|
+| `version` | Long | 是 | GET 返回的草稿版本，最小 `0` |
+| `items` | VehicleItem[] | 是 | 全量明细；现存 `FLEET` 行必须全部原样带回 |
+| `items[].id` | String(Long) | FLEET/更新时是 | 已保存行 ID；手工新行为空 |
+| `items[].sourceType` | String | 是 | `FLEET` 或 `MANUAL` |
+| `items[].serviceDate` | String(date) | 是 | 服务日期，`YYYY-MM-DD` |
+| `items[].vehicleId` | String(Long) | 否 | 正整数车辆 ID |
+| `items[].vehiclePlate` | String | 否 | 车牌，最长 64 字符 |
+| `items[].vehicleModelId` | String(Long) | 否 | 正整数车型 ID |
+| `items[].vehicleModelName` | String | 否 | 车型名，最长 128 字符 |
+| `items[].driverId` | String(Long) | 否 | 正整数司机 ID |
+| `items[].driverName` | String | 否 | 司机名，最长 64 字符 |
+| `items[].amount` | Decimal | 是 | 大于等于 `0.00`；最多 10 位整数、2 位小数 |
+| `items[].paymentMethod` | String | 是 | `CASH_PAID/SIGNED/COMPANY_PAID` |
+| `items[].settlementConfirmStatus` | String | 是 | `UNCONFIRMED/CONFIRMED` |
+| `items[].remark` | String | 否 | 最长 500 字符 |
+| `items[].voucherUrls` | String[] | 否 | 最多 9 个 HTTP/HTTPS URL；单个最长 1024 字符 |
+
+请求对象和明细对象均不接受未声明字段。
+
+**成功响应**
+
+响应类型同 §3.1 的 `VehicleDraft`，包含 `orderId/version/totalAmount/allConfirmed/settlementReady/blockReasonCode/items` 及完整明细字段；`version` 返回保存后的新版本。
+
+**错误码**
+
+| code | 含义 | 触发场景 |
+|---|---|---|
+| `400` | 参数校验失败 | 必填缺失、格式/长度/枚举错误或出现未知字段 |
+| `403` | 无访问权限 | 登录态、角色或核单写权限不足 |
+| `581007` | 订单不存在 | `orderId` 对应订单不存在 |
+| `584071` | 无权访问该订单 | 当前账号不在订单可访问范围内 |
+| `584089` | 核单或结算已完成 | 当前订单已不能修改资金明细 |
+| `584106` | 确认状态非法 | 非 `UNCONFIRMED/CONFIRMED` |
+| `584107` | 手工新增行必须先未确认 | `id=null` 的 `MANUAL` 新行直接传 `CONFIRMED` |
+| `584108` | 车辆草稿版本冲突 | PUT 的 `version` 已过期 |
+| `584109` | 车务来源字段不可改删 | 修改、删除或漏传现存 `FLEET` 行的权威字段 |
+
+**业务边界**
+
+- `FLEET` 行的服务日期、车辆、司机、金额和付款方式不可修改或删除；仅允许修改确认状态、备注和凭证。
+- 全量保存必须带回所有现存 `FLEET` 行；`MANUAL` 行可新增、修改，或通过不再提交该行来删除。
+- 手工新行首次只能提交 `UNCONFIRMED`；取得 `id` 后，下一次 PUT 才可改为 `CONFIRMED`。
+- `version` 冲突后必须重新 GET，并基于最新全量草稿重新编辑和保存。
+
+**典型成功请求**
+
+```http
+PUT /v3/admin/order/900000000001/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+Content-Type: application/json
+```
+
+```json
+{
+  "version": 3,
+  "items": [
+    {
+      "id": "930000000001",
+      "sourceType": "FLEET",
+      "serviceDate": "2026-08-01",
+      "vehicleId": "880000000001",
+      "vehiclePlate": "藏A12345",
+      "vehicleModelId": "870000000001",
+      "vehicleModelName": "七座商务车",
+      "driverId": "860000000001",
+      "driverName": "张师傅",
+      "amount": 1200.00,
+      "paymentMethod": "COMPANY_PAID",
+      "settlementConfirmStatus": "CONFIRMED",
+      "remark": "金额已核对",
+      "voucherUrls": []
+    }
+  ]
+}
+```
+
+**典型成功响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "900000000001",
+    "version": 4,
+    "totalAmount": 1200.00,
+    "allConfirmed": true,
+    "settlementReady": true,
+    "blockReasonCode": null,
+    "items": [
+      {
+        "id": "930000000001",
+        "sourceType": "FLEET",
+        "sourceTypeName": "车务",
+        "serviceDate": "2026-08-01",
+        "vehicleId": "880000000001",
+        "vehiclePlate": "藏A12345",
+        "vehicleModelId": "870000000001",
+        "vehicleModelName": "七座商务车",
+        "driverId": "860000000001",
+        "driverName": "张师傅",
+        "amount": 1200.00,
+        "paymentMethod": "COMPANY_PAID",
+        "paymentMethodName": "公司付款",
+        "settlementConfirmStatus": "CONFIRMED",
+        "settlementConfirmStatusName": "已确认",
+        "remark": "金额已核对",
+        "voucherUrls": []
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+**边界请求：新增金额为 0 的手工未确认行**
+
+```http
+PUT /v3/admin/order/900000000001/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+Content-Type: application/json
+```
+
+```json
+{
+  "version": 4,
+  "items": [
+    {
+      "sourceType": "MANUAL",
+      "serviceDate": "2026-08-02",
+      "vehicleId": "880000000002",
+      "vehiclePlate": "藏A54321",
+      "vehicleModelId": "870000000001",
+      "vehicleModelName": "七座商务车",
+      "driverId": null,
+      "driverName": null,
+      "amount": 0.00,
+      "paymentMethod": "CASH_PAID",
+      "settlementConfirmStatus": "UNCONFIRMED",
+      "remark": null,
+      "voucherUrls": []
+    }
+  ]
+}
+```
+
+**边界响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "orderId": "900000000001",
+    "version": 5,
+    "totalAmount": 0.00,
+    "allConfirmed": false,
+    "settlementReady": true,
+    "blockReasonCode": null,
+    "items": [
+      {
+        "id": "930000000002",
+        "sourceType": "MANUAL",
+        "sourceTypeName": "手工",
+        "serviceDate": "2026-08-02",
+        "vehicleId": "880000000002",
+        "vehiclePlate": "藏A54321",
+        "vehicleModelId": "870000000001",
+        "vehicleModelName": "七座商务车",
+        "driverId": null,
+        "driverName": null,
+        "amount": 0.00,
+        "paymentMethod": "CASH_PAID",
+        "paymentMethodName": "现金已付",
+        "settlementConfirmStatus": "UNCONFIRMED",
+        "settlementConfirmStatusName": "未确认",
+        "remark": null,
+        "voucherUrls": []
+      }
+    ]
+  },
+  "traceId": null,
+  "success": true
+}
+```
+
+**业务失败请求：提交过期版本**
+
+```http
+PUT /v3/admin/order/900000000001/settlement/step3/vehicles
+Authorization: Bearer <管理后台访问令牌>
+Content-Type: application/json
+```
+
+```json
+{
+  "version": 3,
+  "items": []
+}
+```
+
+**业务失败响应**
+
+```json
+{
+  "code": 584108,
+  "message": "车辆核单明细已变化，请刷新后重试",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+### 3.3 查询核单车辆异步下拉
+
+- **接口说明**：`keyword` 可匹配车牌、品牌型号、车型大类和常驻司机姓名；返回轻量车辆候选。
+- **方法与路径**：`GET /v3/admin/order/{orderId}/settlement/vehicle-options`
+- **认证**：管理后台登录态；管理员、超级管理员可查看任意订单，其他允许角色仅可查看本人作为定制师的订单；房务角色不可访问。
+- **幂等性**：是，只读查询。
+- **限流**：未声明独立限流规则。
+
+**路径与 Query 参数**
+
+| 字段 | 位置 | 类型 | 必填 | 默认值 | 说明与校验 |
+|---|---|---|---|---|---|
+| `orderId` | path | String(Long) | 是 | — | 订单 ID，必须为正整数；按字符串传递 |
+| `keyword` | query | String | 否 | 空 | 模糊匹配车牌、品牌型号、车型大类或常驻司机姓名；空白表示不过滤 |
+| `limit` | query | Integer | 否 | `10` | 非正数按 10 处理；超过 20 按 20 处理 |
+
+无请求体。
+
+**统一响应外层**
+
+| 字段 | 类型 | 可空 | 说明 |
+|---|---|---|---|
+| `code` | Integer | 否 | 成功为 `200` |
+| `message` | String | 否 | 结果说明 |
+| `data` | VehicleOption[] | 失败时为空 | 没有匹配项时为 `[]` |
+| `traceId` | String | 是 | 链路追踪 ID |
+| `success` | Boolean | 否 | `code=200` 时为 `true` |
+
+**`data[]`**
+
+| 字段 | 类型 | 可空 | 说明 |
+|---|---|---|---|
+| `vehicleId` | String(Long) | 否 | 车辆 ID，按字符串返回 |
+| `plate` | String | 是 | 车牌 |
+| `modelName` | String | 是 | 品牌型号 |
+| `typeName` | String | 是 | 车型大类名称 |
+| `primaryDriverId` | String(Long) | 是 | 常驻司机 ID；无常驻司机时为 `null` |
+| `primaryDriverName` | String | 是 | 常驻司机姓名；无常驻司机时为 `null` |
+| `label` | String | 否 | 展示文案，依次包含车牌、品牌型号、车型大类和常驻司机；无常驻司机时最后一段为“无常驻司机” |
+
+`data[]` 只包含以上七个字段，不包含车辆费用、付款方式或核单确认状态。
+
+**错误码**
+
+| code | 含义 | 触发场景 |
+|---|---|---|
+| `400` | 订单 ID 必须大于 0 | `orderId <= 0` |
+| `581007` | 订单不存在 | `orderId` 对应订单不存在 |
+| `581008` | 无权查看此订单 | 非管理员访问其他定制师订单，或上下文缺少订单归属判断所需的管理员 ID |
+| `581045` | 房务角色无权查看订单详情 | 房务管理员或房务组长调用 |
+| `584072` | 车务司机车辆信息暂时不可用 | 车辆候选信息不可用 |
+
+登录态无效或缺失时，请求在进入接口前由统一认证拦截。
+
+**业务边界**
+
+- 最多返回 20 条；没有匹配项返回 `[]`。
+- `keyword` 为空或空白时不过滤；`limit <= 0` 按 10，`limit > 20` 按 20。
+- 本接口只查询候选车辆；成功响应不表示已选择、保存或确认车辆。
+- `vehicleId` 与非空 `primaryDriverId` 必须按字符串处理。
+
+**典型成功请求**
+
+```http
+GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?keyword=%E5%BC%A0%E5%B8%88%E5%82%85&limit=10
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**典型成功响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "vehicleId": "9202101",
+      "plate": "蒙A-88888",
+      "modelName": "丰田汉兰达",
+      "typeName": "SUV",
+      "primaryDriverId": "9204101",
+      "primaryDriverName": "张师傅",
+      "label": "蒙A-88888***丰田汉兰达***SUV***张师傅"
+    }
+  ],
+  "traceId": null,
+  "success": true
+}
+```
+
+**边界请求：最大条数且无匹配结果**
+
+```http
+GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?keyword=%E4%B8%8D%E5%AD%98%E5%9C%A8&limit=20
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**边界响应**
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [],
+  "traceId": null,
+  "success": true
+}
+```
+
+**业务失败请求：订单 ID 非法**
+
+```http
+GET /v3/admin/order/0/settlement/vehicle-options
+Authorization: Bearer <管理后台访问令牌>
+```
+
+无请求体。
+
+**业务失败响应**
+
+```json
+{
+  "code": 400,
+  "message": "订单 ID 必须大于 0",
+  "data": null,
+  "traceId": null,
+  "success": false
+}
+```
+
+## 6. 枚举 / 数据字典
+
+### 6.1 `sourceType`
+
+**所属字段**：车辆草稿请求/响应 `items[].sourceType` ｜ **类型**：String ｜ **必填**：是
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `FLEET` | 车务 | 车务同步的权威行，业务字段不可修改或删除 |
+| `MANUAL` | 手工 | 管理后台手工维护的车辆核单行 |
+
+### 6.2 `paymentMethod`
+
+**所属字段**：车辆草稿请求/响应 `items[].paymentMethod` ｜ **类型**：String ｜ **必填**：是
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `CASH_PAID` | 现金已付 | 现金支付 |
+| `SIGNED` | 签单 | 按签单方式结算 |
+| `COMPANY_PAID` | 公司付款 | 由公司支付 |
+
+### 6.3 `settlementConfirmStatus`
+
+**所属字段**：车辆草稿请求/响应 `items[].settlementConfirmStatus` ｜ **类型**：String ｜ **必填**：是
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `UNCONFIRMED` | 未确认 | 当前车辆费用行尚未完成核单确认 |
+| `CONFIRMED` | 已确认 | 当前车辆费用行已完成核单确认 |
+
+### 6.4 `blockReasonCode`
+
+**所属字段**：车辆草稿响应 `data.blockReasonCode` ｜ **类型**：String/null
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `VEHICLE_FEE_NOT_READY` | 车辆费用尚未就绪 | 有当前用车需求，但尚无可返回的车辆费用明细；此时 `settlementReady=false` |
+| `null` | 无阻断原因 | 此时 `settlementReady=true`；为 JSON 空值，不是字符串 `"null"` |
+
+车辆下拉接口不包含枚举或数据字典字段。
+
+## 10. 修改前后对比
+
+### 10.1 字段级对比
+
+| 字段 | 改前 | 改后 |
+|---|---|---|
+| GET 草稿 `data.settlementReady` | 不对管理后台输出 | 返回 Boolean，明确车辆费用是否具备完成核单条件 |
+| GET 草稿 `data.blockReasonCode` | 不存在 | 返回 String/null；未就绪时为 `VEHICLE_FEE_NOT_READY` |
+| 车辆下拉 `data[]` | 无独立候选接口 | 返回七字段轻量候选数组 |
+
+### 10.2 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 无当前用车需求 | 空明细但无公开就绪原因字段 | `items=[]`、`settlementReady=true`、`blockReasonCode=null` |
+| 有需求但费用未生成 | 返回 `584102` | 成功空结果：`items=[]`、`settlementReady=false`、`blockReasonCode=VEHICLE_FEE_NOT_READY` |
+| 保存车辆草稿 | 车辆入口与字段口径分散 | 使用 Step3 PUT，携带 `version` 和全量 `items` |
+| 手工选择车辆 | 无专用异步候选契约 | 使用 `vehicle-options` 按关键词查询，最多 20 条 |
+
+## 11. 影响评估 / 回滚
+
+- **是否破坏向后兼容**：GET 空状态行为有兼容影响；依赖 `584102` 或仅看 `items.length` 的旧逻辑需调整。新增字段和车辆下拉接口本身向后兼容。
+- **前端是否必须同步上线**：是。车辆 Tab 必须读取 `settlementReady`，并在 PUT 版本冲突后重新查询；需要手工车辆选择时使用 `vehicle-options`。
+- **回滚边界**：前端不得回滚到捕获 `584102` 识别未就绪空态的版本，也不得恢复已下线的旧车辆费用入口。
+
+## 12. 注意事项
+
+- GET 返回 `code=200` 且 `items=[]` 时，必须读取 `settlementReady`，不能直接判失败或无条件放行。
+- 完成核单前同时检查 `settlementReady` 与 `allConfirmed`。
+- 清理对 GET `584102` 的空态兼容逻辑；未就绪现在由 `blockReasonCode=VEHICLE_FEE_NOT_READY` 表达。
+- PUT 必须提交 GET 返回的当前 `version` 和全量明细；不要遗漏或改写 `FLEET` 权威字段。
+- 订单、明细、车辆、车型和司机 ID 均按字符串处理；金额按 Decimal 处理。
+- 车辆下拉只提供候选，不返回费用或确认状态；选中后仍需组装 `MANUAL` 行并通过 Step3 PUT 保存。
+
+## 13. 关联 / 联系人
+
+### 13.1 Issue、PR 与提交
+
+| 范围 | Issue | PR | Feature commit | Merge commit |
+|---|---|---|---|---|
+| 车辆 Step3 GET/PUT | [#5356](https://git.1814.love:8443/wx/HL/issues/5356) | [#5362](https://git.1814.love:8443/wx/HL/pulls/5362) | [6e396f6fc4](https://git.1814.love:8443/wx/HL/commit/6e396f6fc48fbf6581e87224bb85f2c811759727) | [cfac945db2](https://git.1814.love:8443/wx/HL/commit/cfac945db268640b0b9e60b4d8c7ab55739a69e3) |
+| 车辆异步下拉 | [#5360](https://git.1814.love:8443/wx/HL/issues/5360) | [#5361](https://git.1814.love:8443/wx/HL/pulls/5361) | [5be7985164](https://git.1814.love:8443/wx/HL/commit/5be7985164cdae5417cdeb2a2be7d104dc8fdae8) | [0ff4ef45](https://git.1814.love:8443/wx/HL/commit/0ff4ef45ccd0f4ebb1d3be00b27cde06f26bce0b) |
+| GET 空状态语义 | [#5380](https://git.1814.love:8443/wx/HL/issues/5380) | [#5393](https://git.1814.love:8443/wx/HL/pulls/5393) | — | [e4c1720871](https://git.1814.love:8443/wx/HL/commit/e4c1720871f33db38936d709caa7696db199ad1f) |
+
+### 13.2 联系人
+
+- **后端负责人**：@yst / yaosutu
+- **前端消费方**：管理后台车辆核单 Tab