hl-api-changelog/changelogs-v2/2026-08/05_5356_车辆Tab三接口汇总-修改接口-管理后台.md
yaosutu 16e592a497
一些检查失败了
changelog-filename-gate / validate (push) Failing after 1s
新增车辆Tab三接口汇总通知
2026-08-05 17:59:12 +08:00

25 KiB

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base
schema ticket title consumer change_type backend_status gateway_status frontend_status frontend_owner frontend_ref target_release verified_at status_note updated_at base
hl-changelog/v2 5356 车辆 Tab 三接口汇总 admin 修改接口 deployed partial implemented Pi v2.1@21dccf38d1413b098cfd5a456d3fb76611581ebb 2026-08-02 汇总 #5356、#5360、#5380 已实现的车辆 Tab 现行契约;管理后台使用 Step3 GET/PUT 和 vehicle-options,并按 settlementReady/blockReasonCode 区分车辆两类空态。 2026-08-05 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 FLEETMANUAL
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 为准。
  • 车辆来源失败或必要字段无效仍返回业务错误,不转换为空结果。

典型成功请求

GET /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>

无请求体。

典型成功响应

{
  "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
}

边界请求:有需求但费用未就绪

GET /v3/admin/order/900000000003/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>

无请求体。

边界响应

{
  "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
}

边界请求:无当前用车需求

GET /v3/admin/order/900000000002/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>

无请求体。

边界响应

{
  "code": 200,
  "message": "成功",
  "data": {
    "orderId": "900000000002",
    "version": 0,
    "totalAmount": 0.00,
    "allConfirmed": true,
    "settlementReady": true,
    "blockReasonCode": null,
    "items": []
  },
  "traceId": null,
  "success": true
}

业务失败请求:车辆来源暂时不可用

GET /v3/admin/order/900000000004/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>

无请求体。

业务失败响应

{
  "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 FLEETMANUAL
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=nullMANUAL 新行直接传 CONFIRMED
584108 车辆草稿版本冲突 PUT 的 version 已过期
584109 车务来源字段不可改删 修改、删除或漏传现存 FLEET 行的权威字段

业务边界

  • FLEET 行的服务日期、车辆、司机、金额和付款方式不可修改或删除;仅允许修改确认状态、备注和凭证。
  • 全量保存必须带回所有现存 FLEET 行;MANUAL 行可新增、修改,或通过不再提交该行来删除。
  • 手工新行首次只能提交 UNCONFIRMED;取得 id 后,下一次 PUT 才可改为 CONFIRMED
  • version 冲突后必须重新 GET,并基于最新全量草稿重新编辑和保存。

典型成功请求

PUT /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>
Content-Type: application/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": []
    }
  ]
}

典型成功响应

{
  "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 的手工未确认行

PUT /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>
Content-Type: application/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": []
    }
  ]
}

边界响应

{
  "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
}

业务失败请求:提交过期版本

PUT /v3/admin/order/900000000001/settlement/step3/vehicles
Authorization: Bearer <管理后台访问令牌>
Content-Type: application/json
{
  "version": 3,
  "items": []
}

业务失败响应

{
  "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 必须按字符串处理。

典型成功请求

GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?keyword=%E5%BC%A0%E5%B8%88%E5%82%85&limit=10
Authorization: Bearer <管理后台访问令牌>

无请求体。

典型成功响应

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "vehicleId": "9202101",
      "plate": "蒙A-88888",
      "modelName": "丰田汉兰达",
      "typeName": "SUV",
      "primaryDriverId": "9204101",
      "primaryDriverName": "张师傅",
      "label": "蒙A-88888***丰田汉兰达***SUV***张师傅"
    }
  ],
  "traceId": null,
  "success": true
}

边界请求:最大条数且无匹配结果

GET /v3/admin/order/2079454953641836546/settlement/vehicle-options?keyword=%E4%B8%8D%E5%AD%98%E5%9C%A8&limit=20
Authorization: Bearer <管理后台访问令牌>

无请求体。

边界响应

{
  "code": 200,
  "message": "成功",
  "data": [],
  "traceId": null,
  "success": true
}

业务失败请求:订单 ID 非法

GET /v3/admin/order/0/settlement/vehicle-options
Authorization: Bearer <管理后台访问令牌>

无请求体。

业务失败响应

{
  "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=trueblockReasonCode=null
有需求但费用未生成 返回 584102 成功空结果:items=[]settlementReady=falseblockReasonCode=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=200items=[] 时,必须读取 settlementReady,不能直接判失败或无条件放行。
  • 完成核单前同时检查 settlementReadyallConfirmed
  • 清理对 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 #5362 6e396f6fc4 cfac945db2
车辆异步下拉 #5360 #5361 5be7985164 0ff4ef45
GET 空状态语义 #5380 #5393 e4c1720871

13.2 联系人

  • 后端负责人@yst / yaosutu
  • 前端消费方:管理后台车辆核单 Tab