diff --git a/changelogs-v2/2026-08/06_5588_司机车辆占用缓存态对账任务-新增接口-管理后台.md b/changelogs-v2/2026-08/06_5588_司机车辆占用缓存态对账任务-新增接口-管理后台.md new file mode 100644 index 0000000..53c8690 --- /dev/null +++ b/changelogs-v2/2026-08/06_5588_司机车辆占用缓存态对账任务-新增接口-管理后台.md @@ -0,0 +1,69 @@ +--- +schema: "hl-changelog/v2" +ticket: "5588" +title: "司机/车辆占用缓存态对账任务(修正脏busy并释放过期holding占用)" +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 #5591 已合并 dev-v3 并部署 TEST,网关验证 3/3 通过。新增 internal 对账端点(Quartz 触发),无前端 API 变化。" +updated_at: "2026-08-06" +base: "dev-v3" +generated: "2026-08-06T13:10:00+08:00" +--- + +# 司机/车辆占用缓存态对账任务(修正脏busy并释放过期holding占用) + +> 后端完成:PR #5591 已合并 dev-v3 并部署 TEST,网关验证 3/3 通过。 + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#5588](https://git.1814.love:8443/wx/HL/issues/5588) +- **PR**: [#5591](https://git.1814.love:8443/wx/HL/pulls/5591) +- **Merge commit**: [deecd62b3](https://git.1814.love:8443/wx/HL/commit/deecd62b3) + +### 联系人 + +- **后端负责人**: @wx + +## 背景 + +协调台 E2E 实证:派单发送被"尚未通过候选校验"拦截,根因是 driver_status/vehicle_status 未释放回 idle——**16 个 busy 司机中 6 个无 active 占用(37%),车辆同样**,可派资源被大面积误锁。 + +代码链路核对结论:取消派单释放占用的既有链路(publishCanceledEvents → OCCUPANCY_RECOMPUTE outbox → hasActiveAssignmentBy* 反算 → applyOccupancy 守卫)已覆盖全部取消入口。TEST 库脏 busy 实际根因: +1. **5 个司机从未有派单却 busy**(外部批量写入缓存列,无事件链路可修复) +2. **holding 单服务日自然过期后无事件触发反算**(如乌力吉/蒙C04E04:08-03~05 holding 单 08-05 结束后占用永久残留)——`AssignmentCompleteJob` 只完结 assigned,不处理过期 holding + +## 变更接口 + +| 方法 | 路径 | 来源 | 说明 | +|---|---|---|---| +| `POST` | `/internal/fleet/jobs/occupancy-reconcile/run` | `FleetJobInternalController`(fleet) | **新增** internal 端点,由 hl-user-service Quartz(sys_job)单点触发;返回本轮写入的 OCCUPANCY_RECOMPUTE 意图数 | + +`/internal/*` 经 InternalAuthInterceptor 校验 X-Internal-Token,走内网 Feign LB 直连不经网关(admin token 直 curl 403 属正常)。**无前端 API 变化**。 + +## 行为变化 + +新增 `OccupancyReconcileJob`(占用缓存态对账): +- **对账口径**:以 active 派单(holding/assigned 且 end_date >= today)为唯一真相;busy 但无 active 占用的司机/车辆为脏态 +- **执行方式**:扫 busy 司机/车辆 + 过期 holding 行资源,逐一写 OCCUPANCY_RECOMPUTE 意图(Outbox),由既有处理器在资源锁内反算并按守卫写回 busy/idle +- **安全性**:不改派单行、不直接改缓存列、不绕过业务守卫(rest/pending/maint 人工态不被覆盖);幂等(无 active 占用才回 idle);单资源失败不反噬整轮 +- **附带修复**:过期 holding(服务日已过但从未产生事件)行资源的占用一并释放 + +## 前端/调用方动作 + +无。对账由 sys_job 定时触发(建议每日一次),无需前端配合。 + +## 验证证据 + +- 定向测试:OccupancyReconcileJobTest 4/4;AssignmentServiceTest 372、AssignmentCandidateServiceTest 45 全过 +- fleet verify **3184 项**(含 MySQL 8.0.33 集成)0 失败;spotless 通过 +- 网关验证(TEST,12:58):对账前脏 busy 司机=6 车辆=5;触发对账端点(32 条 recompute 意图全 SUCCESS);对账后脏 busy **归零**(原 6 司机 5 车辆全部 idle);候选复验朝鲁门(有 active 占用)仍 busy + available=false(ASSIGNMENT_CONFLICT),**未被误释放**