changelog: #5603 需求换版/取消后孤儿派单对账清理（新增接口）

changelogs-v2/2026-08/06_5603_需求换版取消后孤儿派单对账清理（assigned孤儿自动取消释放资源）-新增接口-管理后台.md

@@ -0,0 +1,76 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5603"
+title: "需求换版/取消后孤儿派单对账清理（assigned孤儿自动取消释放资源）"
+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: "后端完成：PR #5619/#5620 已合并 dev-v3 并部署 TEST（order-v3/fleet/user 三服务），网关验证通过（sys_job trigger code=200，对账 job 取消 115 条孤儿切片，孤儿残留 0）。新增 internal 对账端点 + 批量需求生效校验 Feign 契约，无前端 API 变化。"
+updated_at: "2026-08-06"
+base: "dev-v3"
+generated: "2026-08-06T18:30:00+08:00"
+---
+
+# 需求换版/取消后孤儿派单对账清理（assigned孤儿自动取消释放资源）
+
+> 后端完成：PR #5619/#5620 已合并 dev-v3 并部署 TEST，网关验证通过。
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#5603](https://git.1814.love:8443/wx/HL/issues/5603)
+- **PR**: [#5619](https://git.1814.love:8443/wx/HL/pulls/5619)、[#5620](https://git.1814.love:8443/wx/HL/pulls/5620)
+- **Merge commit**: [fd48756f1](https://git.1814.love:8443/wx/HL/commit/fd48756f1)、[c2e5b81e6](https://git.1814.love:8443/wx/HL/commit/c2e5b81e6)
+
+### 联系人
+
+- **后端负责人**: @wx
+
+## 背景
+
+需求换版/订单取消时，正常链路经 order-v3 耐久 Outbox 通知 fleet 取消旧派单；但当需求/订单被外部物理删除、Outbox 重放失败或链路中断时，fleet_assignment 残留挂接在失效需求上的 active 切片（unassigned/holding/assigned），其中 **assigned 孤儿持续占用车辆/司机资源**。TEST 环境实测 107 条孤儿（assigned 11 + holding 6 + unassigned 90），全部对应「需求/订单已物理删除」。
+
+## 方案
+
+以 order-v3 为需求权威新增**需求存在性对账**（调度通路同 #5588：user Quartz sys_job → fleet internal 端点，每小时 30 分执行）：
+
+1. **order-v3** 新增 internal 端点 `POST /v3/internal/order/vehicle-requirements/existence-batch`——批量校验需求是否仍生效（仅返回 is_active=1 且未逻辑删除的需求 ID）
+2. **fleet** 新增 `RequirementExistenceReconcileJob`——扫描在途派单 distinct requirement_id → 分批 Feign 校验 → 失效需求逐条走 `cancelActiveByRequirement` **正式取消链路**（需求锁 + 槽位/资源锁 + 保险生命周期锁 + 退保意图 + 占用释放事件）；Feign 降级 fail-closed 跳过本轮不误伤；全局锁多实例互斥
+3. **fleet** 新增端点 `POST /internal/fleet/jobs/requirement-existence-reconcile/run`
+4. **user** 新增 `RequirementExistenceReconcileJobBridge`（sys_job invoke_target：`requirementExistenceReconcileJob.execute()`，已入 Quartz 白名单）
+
+换版重绑窗口安全：order-v3 已换版、fleet 未消费 Outbox 时取消旧版行只会让重放退化为「取消+新建」，最终无重复无残留。
+
+## 变更接口
+
+| 方法 | 路径 | 服务 | 说明 |
+|---|---|---|---|
+| `POST` | `/v3/internal/order/vehicle-requirements/existence-batch` | order-v3 | internal Feign：批量校验需求生效（Req：`RequirementExistenceBatchReqDTO.requirementIds`≤1000；Resp：`activeRequirementIds`） |
+| `POST` | `/internal/fleet/jobs/requirement-existence-reconcile/run` | fleet | internal：Quartz 触发需求存在性对账（无参，返取消需求数） |
+
+均为 `/internal/**` 内网 Feign/Quartz 通路（`InternalAuthInterceptor` 校验 X-Internal-Token，网关不暴露），**无前端 API 变化**。shared 新增 DTO：`RequirementExistenceBatchReqDTO/RespDTO`（hl-common-core）。
+
+## 行为变化
+
+- 需求失效/删除后的孤儿派单（unassigned/holding/assigned）由对账 job 自动软取消（canceled + 退保意图 + 占用释放），历史保留不物理删除
+- 对账幂等：需求仍生效不动作；已无在途切片计 0；Feign 不可用跳过本轮
+- **无自动改派/重派**（#5592 口径延续：系统只取消孤儿，不替车务决策）
+
+## 前端/调用方动作
+
+无（前端零改动）。
+
+## 验证证据
+
+- **测试**：fleet RequirementExistenceReconcileJobTest 7/7、FleetJobInternalControllerTest 7/7、verify 3158 用例 0 失败（排除 ReleaseE 已知环境项）；order-v3 InternalRequirementControllerTest 17/17、RequirementServiceTest 198/198；user QuartzJobExecutorTest 13/13、bridge 4/4；spotless:check 通过
+- **部署**：hl-order-service-v3 / hl-fleet-service / hl-user-service 双实例 UP（18:00-18:19）
+- **网关验证**：sys_job trigger（admin API）code=200；对账 job 执行 `在途需求总数=73 孤儿需求=31 取消切片=115`；DB 断言孤儿残留 0；原 11 条 assigned 孤儿全部 canceled（reason=订单取消或用车需求基线已换版）；释放资源回 idle（仍 busy 的资源均有其它在途派单占用，非泄漏）
+- **存量清理**：evidence/5603/orphan-cleanup-manifest.json（hl-data-cleanup/v1，115 条软取消）+ orphan-cleanup-backup.json（115 行快照）