---
schema: "hl-changelog/v2"
ticket: "5302"
title: "派车档期按完整组判定同城衔接"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "仅修正候选与预校验的既有冲突语义，不新增字段或页面动作；前端继续按后端 available、availabilityReasonCode、conflicts 与 conflict 渲染即可"
updated_at: "2026-07-28"
base: "dev-v3"
---

# Fleet：派车档期按完整组判定同城衔接

> **服务**：`hl-fleet-service`
> **Issue**：#5302
> **影响页面**：管理后台车务管理 → 派单候选弹窗、保存前预校验
> **兼容性**：路径、方法、请求/响应字段和错误码形状不变，仅修正既有业务语义

## 问题与目标

派车数据已按服务日期拆成逐日切片。同一辆车或司机已有 D1–D3 多日派车时，旧实现只读取新请求窗口内命中的切片；若新请求只查内部日 D2，D2 会被误当作旧派车组的真实首日/末日，并可能错误套用 R3-EX“真实首尾同城可衔接”，把双重占用误报为可共享。

本次后端在初筛命中后一次批量补齐同 `assignmentGroupId` 的全部有效切片，再按完整组真实首日、末日及首接客地、末送客地判断冲突。候选咨询、保存前预校验及最终写侧重校验使用同一口径。

## 变更接口

### `POST /admin/fleet/assignments/candidates`

响应形状不变，以下既有字段的语义修正：

| 场景 | `available` | `availabilityReasonCode` | `conflicts[].blocking` | `conflicts[].cityJunctionShareCandidate` |
|---|---:|---|---:|---:|
| 请求日位于已有多日派车组内部 | `false` | `ASSIGNMENT_CONFLICT` | `true` | `false` |
| 请求日仅与完整组真实首日或末日相接，且接送城市满足 R3-EX | `true` | `CITY_JUNCTION_SHAREABLE` | `false` | `true` |
| 无重叠 | `true` | `AVAILABLE` | - | - |

内部日冲突的 `conflicts[].startDate/endDate` 返回完整有效派车组范围；`availabilityWindows` 按该真实阻断范围扣减，不再把内部日当成可用窗口。

车辆和司机分别采用同一口径。仅查询 `holding/assigned` 活跃切片；历史空 `assignmentGroupId` 数据继续按原记录区间判断。

### `POST /admin/fleet/assignments/precheck`

响应形状不变：

- 内部日双重占用返回 `data.conflict=true`；
- `data.conflicts[]` 的车辆、司机冲突日期段均为完整有效派车组范围；
- 内部日 `cityJunctionShareCandidate=false`；
- 真实首尾同城衔接仍按既有 R3-EX 返回非阻断结果。

最终创建、改派、车务确认及撤销取消恢复仍在资源锁内重新校验，不信任前端咨询结果；本次同步修正这些写侧入口，避免候选正确但最终写入口径不同。

## 前端处理

无需修改前端代码或请求参数：

1. 继续以候选返回的 `available` 和 `availabilityReasonCode` 控制可选状态与原因展示；
2. 继续以预校验返回的 `conflict` 决定是否阻止提交；
3. 不要在前端自行按单日日期或城市覆盖后端冲突结果；
4. 已有 `ASSIGNMENT_CONFLICT`、`CITY_JUNCTION_SHAREABLE` 展示分支可直接消费修正后的数据。

因此 `frontend_status=not_required`。

## 不影响范围

- 不新增或删除 API 字段，不修改 Long ID 字符串、手机号脱敏及错误码契约。
- 不修改派单状态机、占用写入、保险、价格、对账或车辆/司机常驻关系。
- 不将 `completed/canceled` 切片重新计入活跃占用。
- 不修改 `hl-ui` 仓库。

## 验证证据

- 后端 PR [wx/HL#5303](https://git.1814.love:8443/wx/HL/pulls/5303) 已 squash 合并至 `dev-v3`，合并提交 `d114232ad`。
- `hl-fleet-service` 已滚动部署测试环境，8087/8187 双实例健康。
- 定向 `AssignmentServiceTest,AssignmentCandidateServiceTest,FleetAssignmentMapperTest`：342 tests，0 failures，0 errors，0 skipped。
- Fleet reactor verify：2466 tests，0 failures，0 errors，1 skipped；Spotless 628 Java files clean。
- 真实测试网关选择一个 D1–D4 活跃派车组的内部日 D2 调用候选与预校验：HTTP/code 200；车辆与司机均 `available=false`、`ASSIGNMENT_CONFLICT`、`blocking=true`、`cityJunctionShareCandidate=false`，冲突范围返回完整 D1–D4；全程无业务写入。
- 网关证据：`D:/work2/HL-v3/.tmp/5302-gateway.json`，SHA-256 `b482a78d4129998c0ca3a8ee0e9a10ee63dfb25239fe1bd041b17f51043d4524`。
- OpenAPI/oasdiff：项目未配置可复现 Swagger2→OAS3 与 oasdiff，状态为 `not_configured`；使用源码对比、定向测试和真实网关响应作为人工回退证据。Spring Cloud Contract 为 `not_required`。

当前状态：后端已部署、网关已验证，前端无需改造。

关联：#5302。