diff --git a/changelogs-v2/2026-07/28_4776_车务驳回用车需求接口-管理后台.md b/changelogs-v2/2026-07/28_4776_车务驳回用车需求接口-管理后台.md new file mode 100644 index 0000000..a101b8d --- /dev/null +++ b/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`。