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

- 工单：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 字 | 驳回原因，展示给定制师 / 团期管理员 |

#### 请求示例

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

#### 成功响应示例

```json
{
  "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 |

## 前端调用口径

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

## 错误码

| 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`。