hl-api-changelog/changelogs-v2/2026-07/28_5302_派车档期按完整组判定同城衔接-修改接口-管理后台.md

schema, ticket, title, consumer, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

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