diff --git a/changelogs-v2/2026-09/14_7667_提交车务前拦截未回填服务日的接送机需求-修复-管理后台.md b/changelogs-v2/2026-09/14_7667_提交车务前拦截未回填服务日的接送机需求-修复-管理后台.md new file mode 100644 index 00000000..950402f6 --- /dev/null +++ b/changelogs-v2/2026-09/14_7667_提交车务前拦截未回填服务日的接送机需求-修复-管理后台.md @@ -0,0 +1,129 @@ +--- +schema: "hl-changelog/v2" +ticket: "7667" +title: "提交车务前拦截未回填服务日的接送机需求:该端点新返回 809007" +consumer: "admin" +author: "wx(GIT)" +change_type: "修复" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "not_required:不改请求/响应结构、不新增错误码号段、不改路由,无 Flyway。809007(TRANSFER_SERVICE_DATES_NOT_BACKFILLED)早已存在,本单只是让「提交车务」这一步也会返回它。管理后台按通用错误提示展示 message 即可,无需改码;若前端对该端点的失败有特殊分支处理,需知悉多了这一个码。" +updated_at: "2026-09-14" +base: "dev-v3" +--- + +# 团期管理员提交车务:未回填服务日的接送机需求改为失败关闭(修复) + +> **服务**: hl-order-service-v3(`RequirementService#dispatchVehicleToHouse` + `TransferServiceDatesGuard`) +> **PR**: #7693 +> **Issue**: #7667 +> **日期**: 2026-09-14 +> **影响范围**: 1 个管理端接口的失败分支(`kind=TRANSFER` 且服务日未回填时);**不涉及**请求/响应结构、错误码号段、路由与数据库 + +--- + +## ⚠️ 关键变化 + +🔴 **`kind=TRANSFER` 的活跃需求若 `service_dates` 为 NULL 或 `[]`,提交车务现在返回 809007,需求停在 `PENDING_REVIEW` 不动。** + +| 需求 | 服务日 | 改动前 | 改动后 | +|---|---|---|---| +| `kind=TRANSFER` | NULL / `[]` | 推到 `PENDING`,返回成功(之后所有消费方都会抛 809007,且回填端点已无法修复) | **`809007`**,需求仍为 `PENDING_REVIEW`,`dispatch_remark` / 车控状态 / flow 状态 / 时间线均不变 | +| `kind=TRANSFER` | 已回填 | 推到 `PENDING` | **不变** | +| `kind=TRAVEL`(含服务日为空) | 任意 | 放行 | **不变** | + +🟢 行程用车(`TRAVEL`)与已回填的接送机需求,行为逐字段不变。 + +--- + +## 一、背景 + +809007(「接送机需求 {需求ID} 的服务日期尚未回填,无法下发车务」)原先有三个调用点,全部在**消费侧**:`OrderFleetProviderService`、`DailyVehicleAssignmentSnapshotService`、`OrderVehicleDailyFeeSnapshotProvider`。 + +而「提交车务」是全仓唯一把车需求从 `PENDING_REVIEW` 推到 `PENDING` 的写口。未回填的行一旦被推走,就卡死了: + +- 回填接口的 CAS 带 `status = PENDING_REVIEW`,行已不在这个状态,再也补不回来; +- 消费方则一律抛 809007。 + +结果是需求停在一个「回不到可用 TRANSFER 需求」的状态。本单把守卫前移到提交车务这一步,在推走之前就失败关闭。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|------|------|------|------|----------|------| +| 1 | 团期管理员提交车务 | POST | `/v3/admin/order/{id}/vehicle-requirement/dispatch` | 修复 | 新增 809007 失败分支 | + +--- + +## 三、接口详情 + +### 1. 团期管理员提交车务 + +- **方法 / 路径**:`POST /v3/admin/order/{id}/vehicle-requirement/dispatch` +- **路径参数**:`id`(订单 ID) +- **查询参数**:`kind`,可选,`TRAVEL` / `TRANSFER`,不传按 `TRAVEL`(大小写与首尾空白不敏感;非法值返回 809000) +- **请求体**:`DispatchReqVO`(`dispatchRemark`),**不变** +- **响应**:`Result`,**不变** +- **错误码(本单新增触发)**: + +| code | 触发条件 | message | +|---|---|---| +| 809007 | `kind=TRANSFER` 且该活跃需求 `service_dates` 为 NULL 或 `[]` | 接送机需求 {需求ID} 的服务日期尚未回填,无法下发车务(需求 ID 按纯数字渲染,不带千分位) | + +- **请求 / 响应实测原文**: + - **环境**:2026-09-14 测试环境,经网关 `https://api.test.1814.love:9443`,ADMIN 角色。 + - **部署**:`hl-order-service-v3` 为 `dev-v3@79e3b9da7`,含本单 squash `9d534d31e5`,部署于 21:59:54。`hl-gateway` 为 `dev-v3@83c1b1743`。 + - **数据**:夹具为合成数据,用毕已删除。 + +① 服务日为 NULL(TRANSFER)→ 809007,需求与订单逐字段不变: + +``` +POST /v3/admin/order/766717893953749404/vehicle-requirement/dispatch?kind=TRANSFER +{"dispatchRemark": "#7667-AC1-call"} + +HTTP 200 +{"code":809007,"message":"接送机需求 766717893953749406 的服务日期尚未回填,无法下发车务","data":null,"traceId":null,"success":false} +``` + +② 服务日为 `[]`(TRANSFER)→ 809007: + +``` +POST /v3/admin/order/766717893953749404/vehicle-requirement/dispatch?kind=TRANSFER +{"dispatchRemark": "#7667-AC2-call"} + +HTTP 200 +{"code":809007,"message":"接送机需求 766717893953749406 的服务日期尚未回填,无法下发车务","data":null,"traceId":null,"success":false} +``` + +③ 服务日已回填(TRANSFER)→ 成功,需求推到 `PENDING`: + +``` +POST /v3/admin/order/766717893953749404/vehicle-requirement/dispatch?kind=TRANSFER +{"dispatchRemark": "#7667-AC3-call-已回填放行"} + +HTTP 200 +{"code":200,"message":"成功","data":null,"traceId":null,"success":true} +``` + +④ 行程用车、服务日为 NULL(TRAVEL)→ 仍放行: + +``` +POST /v3/admin/order/766717893953749405/vehicle-requirement/dispatch?kind=TRAVEL +{"dispatchRemark": "#7667-AC4-call-TRAVEL放行"} + +HTTP 200 +{"code":200,"message":"成功","data":null,"traceId":null,"success":true} +``` + +--- + +## 四、前端需要做什么 + +无需改码。若管理后台对该端点的失败有按 code 分支的处理,知悉会多出 809007;按通用错误提示展示 `message` 即可。