车务驳回用车需求接口（管理后台）

工单：HL #4776
后端分支：fix/4776-fleet-reject-requirement
前端范围：管理后台车务派单看板 / 矩阵未派占位卡片
变更类型：新增接口

背景

车务需要在“尚未真正派车”的阶段，把当前用车需求退回上游修改。前端不要直接调用 order-v3 旧供应商驳回接口；统一调用 fleet 自有接口，由 fleet 后端根据 assignmentId 反查 orderId/requirementId 并完成状态守卫。

新增接口

1. 车务驳回用车需求

POST /admin/fleet/assignments/{assignmentId}/requirement-reject

Path 参数

字段	类型	必填	说明
assignmentId	string	是	未派占位派单 ID。前端从未派卡片现有数据中取，不需要额外传 `orderId/requirementId`

Body 参数

字段	类型	必填	限制	说明
returnRemark	string	是	1-500 字	驳回原因，展示给定制师 / 团期管理员

请求示例

{
  "returnRemark": "当地无满足条件车辆，请调整车型或用车时间"
}

成功响应示例

{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "orderId": "1934567890123456789",
    "requirementId": "1934567890123456790",
    "canceledUnassignedCount": 2,
    "remainingInFlightCount": 0
  }
}

响应字段

字段	类型	说明
orderId	string	订单 ID
requirementId	string	本次驳回的用车需求 ID
canceledUnassignedCount	number	后端自动取消的旧未派占位数量
remainingInFlightCount	number	驳回后同需求下仍在途的派单数量。成功驳回应为 0

前端调用口径

仅在未派占位卡片上提供“驳回用车需求”入口。
前端只传 assignmentId + returnRemark，不要传 orderId、requirementId、returnTarget。
核心订单退回定制师，团期/拼团订单退回团期管理员；目标由后端按订单类型派生。
驳回成功后，当前旧需求下的未派占位会被后端自动取消；前端刷新派单看板 / 矩阵即可。
上游重新提交用车需求后，会生成新的需求版本和新的未派占位。

错误码

code	message	前端处理
400 / 400001	参数校验失败	检查 `returnRemark` 是否为空或超过 500 字
605009	派单不存在	刷新页面，该卡片可能已被处理
605018	该用车需求已派单，请先取消派单后再驳回	提示车务先取消派单并完成司机告知存证，再执行驳回
605906	无可派的待派需求项，请先展开用车需求	当前卡片已不是未派占位或缺少需求关联，刷新页面
582080	用车需求不存在或已失效	当前需求版本已变化，刷新订单/派单数据
582083	需求状态不允许此操作，请检查当前状态	当前需求状态不能驳回，刷新后按最新状态处理
503001	订单服务不可用	稍后重试；不要在前端本地移除卡片

关键业务规则

只要同一 requirementId 下存在 holding 或 assigned 派单，后端返回 605018，不修改 order-v3 需求状态。
若同一 requirementId 下只有 unassigned 占位，后端先驳回 order-v3 当前 active 用车需求，再取消 fleet 旧未派占位。
驳回不触发客户退款；司机险、车队成本、对账仍由派单取消/保险/对账链路处理。
前端不要用旧接口：/v3/admin/order/{id}/vehicle-requirement/supplier-reject。

3.6 KiB 原始文件 Blame 文件历史 Unescape Escape