diff --git a/changelogs-v2/2026-09/07_7203_车务显式声明整段不用车-新增接口-管理后台.md b/changelogs-v2/2026-09/07_7203_车务显式声明整段不用车-新增接口-管理后台.md index 76b99301..df6a37b4 100644 --- a/changelogs-v2/2026-09/07_7203_车务显式声明整段不用车-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/07_7203_车务显式声明整段不用车-新增接口-管理后台.md @@ -12,7 +12,7 @@ frontend_owner: "mmg" frontend_ref: "" target_release: "" verified_at: "2026-09-07" -status_note: "2026-09-07 PR #7260 已合并 dev-v3 并部署测试服(02d7e59be),三端点网关实测通过(五种派车行拒绝/接送机互斥 605917/撤销同步门禁 605920/605921/开关 605035/幂等四情形/并发撤销+排车/迟到旧版本不覆盖)。前端待做:派单向导第②步加整段不用车声明入口+撤销入口+状态回显(syncStatus≠订单状态、REVOKED 时 syncStatus=null 不展示、撤销仅 SYNCED 可点、605920/605921 提示可轮询或联系运维、只想继续排车不必先撤销)。决策:本条并入 #7067 U5 向导四步化一起做(同落向导体第②步,避免同文件两次动),排在 U3/U4 之后,本条保持 pending 至 U5 落地。" +status_note: "2026-09-07 PR #7260 已合并 dev-v3 并部署测试服(02d7e59be),三端点网关实测通过(五种派车行拒绝/接送机互斥 605917/撤销同步门禁 605920/605921/605923/605924/开关 605035/幂等四情形/并发撤销+排车/迟到旧版本不覆盖)。二轮复审(PR #7275)已合并:同步失败不等于订单侧未收到,三码分流(605921=已核实未接受可排车、605923/605924=须运维对账);撤销仅 605921 分支不必先撤销。前端待做:派单向导第②步加整段不用车声明入口+撤销入口+状态回显(syncStatus≠订单状态、REVOKED 时 syncStatus=null 不展示、撤销仅 SYNCED 可点、605921 提示可轮询或联系运维、605923/605924 必须联系运维对账)。决策:本条并入 #7067 U5 向导四步化一起做(同落向导体第②步,避免同文件两次动),排在 U3/U4 之后,本条保持 pending 至 U5 落地。" updated_at: "2026-09-07" base: "dev-v3" --- @@ -35,7 +35,7 @@ base: "dev-v3" order-v3 可能按自己的规则忽略了这次回调（订单已取消、版本落后）。要展示订单状态请读订单侧的字段。 - **`declarationStatus=REVOKED` 时 `syncStatus` 为 `null`**，此时**不要展示同步状态**。 - **撤销按钮不是任何时候都能点**：只有 `syncStatus=SYNCED` 才可点。`PENDING` 会返回 605920（提示稍后重试）， - `FAILED` 会返回 605921（提示联系运维重投）。**但「想继续排车」不需要先撤销**——见「六、边界行为」。 + `FAILED` 会分流到三个错误码（见错误码表），对应三种应对方式。**只有 605921 分支不需要先撤销**，其他两码必须走运维对账。 --- @@ -259,11 +259,13 @@ DELETE /admin/fleet/assignments/requirements/2096644145371033602/no-vehicle | 605047 | 行程已结束 | 禁用入口 | | 605919 | 该需求当前不存在生效的不用车声明 | 刷新回显后重试 | | 605920 | 声明快照尚未成功投递（`syncStatus=PENDING`） | 提示「同步中，请稍后再撤销」，可轮询 GET | -| 605921 | 声明快照投递已隔离（`syncStatus=FAILED`） | 提示「同步失败请联系运维重投；如果只是想继续排车，不必先撤销」 | +| 605921 | 声明快照投递已隔离，但**经回查确认** order-v3 侧尚未接受该声明 | 提示「已核实订单侧未接受，可直接重新排车」；声明记录请联系运维重投后再撤销 | +| 605923 | 声明快照投递已隔离，但订单侧已接受该声明（需求已 DONE 且零非取消派车行） | **不能**重新排车（会被 605906 拒），联系运维对账处置隔离事件后再撤销 | +| 605924 | 声明快照投递已隔离，且无法确认订单侧是否已接受（需求状态为空 / PENDING / PENDING_REVIEW / REJECTED_*，或需求已 DONE 但本地还有非取消派车行） | 联系运维对账后再撤销 | #### 业务边界 -- **必须先同步成功才能撤销**（605920 / 605921）。这条是 fail-closed，不是过度谨慎： +- **必须先同步成功才能撤销**（605920 / 605921 / 605923 / 605924）。这条是 fail-closed，不是过度谨慎： 若允许在快照还在投递时撤销，会出现「接口回了 200 REVOKED，但订单侧随后仍被那条在途快照推成完成」的 终态错乱——车管侧显示已撤销、订单侧显示已完成，且此后再撤销会被 605919 拒死。 - **幂等**：撤销侧有自己的唯一键 `(requirementId, revokeRequestId)` 与自己的请求指纹， @@ -397,7 +399,7 @@ Authorization: Bearer {token} - 声明成功 → 需要刷新订单侧状态展示（用车需求会流转到完成）。 - 撤销成功 → 需求回到处理中、恢复可排车；前端应把第②步排车入口重新放开。 -- 撤销被 605920 / 605921 拒绝 → 不要把按钮置灰后就不管了，应提示可轮询 GET 或联系运维。 +- 撤销被 605920 / 605921 / 605923 / 605924 拒绝 → 三种隔离码给车务的下一步互斥，前端**不得**把它们合并成一句提示，应按各码说明逐项区分处理。 --- @@ -419,9 +421,11 @@ Authorization: Bearer {token} ## 六、边界行为 -- **同步失败（`FAILED`）时不阻断重新排车**。声明记录不参与排车门禁——排车只看订单侧状态与派车行。 - 所以「声明快照被隔离了、撤销不了」的情况下，车务直接走第②步排车即可，不需要先撤销成功。 - 这条要写进 UI 提示，否则车务会以为自己被卡死了。 +- **同步失败（`FAILED`）时的处置取决于订单侧是否已接受**。这是本轮二轮复审推翻的核心断言： + 隔离不等于订单侧没收到。远端已提交成功但回执丢失时，发送端重试耗尽后同样会进隔离，但订单侧已是 DONE。 + 直接排车会被 605906 拒。故撤销接口回查订单侧实况后分流三码： + - 605921（已核实未接受）→ 可直接重新排车，声明记录联系运维重投后再撤销 + - 605923/605924（已接受或不确定）→ 必须联系运维对账处置隔离事件后再撤销。 - **接送机与不用车互斥**。大交通声明了接机或送机时不允许声明整段不用车（605917）——接送机本身就是用车， 允许的话等于给 #7067 的接送机门禁开后门。要真的整段不用车，先由定制师改大交通声明清掉接送机要求。 - **已发生的用车事实不可被覆盖**。`completed`（已跑完）与 `exception`（未处理异常）同样触发 605916， @@ -445,7 +449,7 @@ Authorization: Bearer {token} |---|---|---| | `PENDING` | 投递中 | 快照事件在途（含首次投递与重试退避） | | `SYNCED` | 已投递 | 快照已成功投递——订单侧已受理，或已按其规则忽略（订单已取消、版本落后）。不代表订单车控是完成态 | -| `FAILED` | 投递已隔离 | 重试预算耗尽，需运维重投 | +| `FAILED` | 投递已隔离 | 重试预算耗尽，需运维重投；不代表 order-v3 没收到，订单侧是否已接受以撤销接口返回码为准 | | `null` | 不适用 | 仅出现在 `declarationStatus=REVOKED` 时 | --- @@ -493,7 +497,7 @@ GET /admin/fleet/assignments/requirements/{id}/no-vehicle → 三态（null | 需求版本传旧值 | 605905 ✓ | | 行程已结束的需求声明 | 605047 ✓ | | 撤销时快照仍在投递（`syncStatus=PENDING`） | 605920 ✓，声明状态未变、未写出重开事件 | -| 撤销时快照已隔离（`syncStatus=FAILED`） | 605921 ✓ | +| 撤销时快照已隔离（旧口径）| 605921 ✓ 注：该行是二轮复审前的验证记录。新版本按订单侧实况分流为 605921/605923/605924（见错误响应表） | | 需求级生命周期开关关闭时撤销 | 605035 ✓，声明状态未变 | ### 幂等（四种情形）