docs(fleet): notify frontend for vehicle requirement reject

changelogs-v2/2026-07/28_4776_车务驳回用车需求接口-管理后台.md

@@ -0,0 +1,88 @@
+# 车务驳回用车需求接口（管理后台）
+
+- 工单：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`。