diff --git a/changelogs-v2/2026-08/04_5456_派单创建holdMode双流500与失败重试幂等-修改接口-管理后台.md b/changelogs-v2/2026-08/04_5456_派单创建holdMode双流500与失败重试幂等-修改接口-管理后台.md new file mode 100644 index 0000000..680ad1f --- /dev/null +++ b/changelogs-v2/2026-08/04_5456_派单创建holdMode双流500与失败重试幂等-修改接口-管理后台.md @@ -0,0 +1,118 @@ +--- +schema: "hl-changelog/v2" +ticket: "5456" +title: "派单创建 holdMode 双流 500 修复与失败重试幂等释放" +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: "2026-08-04" +status_note: "" +updated_at: "2026-08-04" +base: "dev-v3" +--- + +# 车务派单创建: holdMode=0/1 创建 500 修复 + 失败后同 requestId 可重试 + +> **存放目录**: `changelogs-v2/2026-08/` +> **服务**: hl-fleet-service +> **PR**: #5467 +> **Issue**: #5456 / #5461 / #5451 +> **日期**: 2026-08-04 +> **影响范围**: 管理后台「派单弹窗」创建派单(直接派定 holdMode=0 / 排车锁定 holdMode=1) + +--- + +## ⚠️ 关键变化 + +前一版(#5444 Step2 机制合并后)`POST /admin/fleet/assignments` 对任意 unassigned 订单创建派单必返 500: +- holdMode=0(直接派定):`code=500 服务器内部错误[IllegalStateException]: DAILY_V3 snapshot invalid: daily rows do not cover declared topology` +- holdMode=1(排车锁定):`code=500 服务器内部错误[IllegalStateException]: 派车组身份不完整或已失效,拒绝签发行程单 token` + +本次修复后两者均正常返回 200;同时修复业务校验失败(如 `605036 司机与车辆不是常驻组合`)后同 requestId 立即重试被 `100502 派单创建处理中,请勿重复提交` 卡死的问题——失败后幂等键释放,同 requestId 可立即重试。 + +## 一、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 创建派单 | POST | `/admin/fleet/assignments` | 行为修复 | holdMode=0/1 创建不再 500;业务失败后同 requestId 可立即重试 | + +接口请求/响应字段无任何变化,仅行为修复。 + +## 二、接口契约变化 + +### POST /admin/fleet/assignments(创建派单) + +**使用场景**:车务在派单弹窗选定车辆/司机后创建派单。`holdMode=1` → 落 holding 并发 HOLD 通知;`holdMode=0` → 落 assigned 直接派定。 + +**入参**(无变化):`orderId / requirementId / vehicleId / driverId / startDate / endDate / holdMode(0|1) / headcount / requestId / confirmCrossResident / messageTemplateId / customBody / pickupAt / dropoffAt`。 + +**出参**(无变化):成功返回 `assignmentStatus=holding|assigned` 的派单写结果。 + +**行为变化**: + +| 场景 | 原来 → 现在 | +|------|-------------| +| holdMode=0 对 unassigned 订单创建 | 500 内部错误(DAILY_V3 快照拓扑校验失败,事务回滚)→ 200 创建成功返回 assigned | +| holdMode=1 对 Step2 建槽订单创建 | 500 内部错误(HOLD 通知签发行程单短链时组行未冻结)→ 200 创建成功返回 holding,HOLD 通知正常生成 | +| 业务校验失败(如 605036 非跨常驻未确认)后同 requestId 重试 | 100502 派单创建处理中,请勿重复提交(幂等键残留至 TTL 300s)→ 幂等键释放,同 requestId 可立即重试并得到与首次一致的结果 | +| HOLD 通知短信中的行程链接 | 失败无法发送 → 短信正常发送,行程链接占位文案「行程确认后发送」,司机最终确认(assigned)后行程短信携带真实链接 | + +**错误码**(无变化):`605001/605003/605005/605006/605008/605013/605014/605036/605041/100502`。 + +## 三、典型示例 + +### 成功(holdMode=0 直接派定) + +请求: + +```http +POST /admin/fleet/assignments +Authorization: Bearer +Content-Type: application/json + +{ + "orderId": "2084276690049007618", + "requirementId": "2084276690049007619", + "vehicleId": "2079857985848320002", + "driverId": "2065272150012444674", + "startDate": "2026-08-03", + "endDate": "2026-08-05", + "holdMode": 0, + "headcount": 2, + "confirmCrossResident": true, + "requestId": "qa-5456-direct-001" +} +``` + +响应(200): + +```json +{ + "code": 200, + "message": "成功", + "data": { + "assignmentStatus": "assigned", + "confirmedAt": "2026-08-04T12:00:00" + } +} +``` + +### 业务失败后同 requestId 重试 + +第一次请求(不传 confirmCrossResident,非跨常驻组合)→ `605036 司机与车辆不是常驻组合,请确认跨常驻车派单后重试`;补 `confirmCrossResident: true` 后**同 requestId** 立即重试 → 正常进入业务处理(不再 100502)。 + +## 四、前端需要做什么 + +无需修改。前端如遇 100502 且确认首次请求已失败,可直接同 requestId 重试;HOLD 通知短信内行程链接在司机确认前为占位文案。 + +## 五、后端验证 + +- hl-common/hl-starter-protection verify 31 例全过;hl-fleet-service verify 3060 例(2 个基线环境失败与本改动无关) +- 回归测试:IdempotentAspect 失败释放/成功保留;HOLD 快照降级短链;DIRECT 快照事件发布前冻结断言 +- TEST 部署与网关验证见工单 #5456/#5461/#5451