---
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 行快照）