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

@@ -0,0 +1,89 @@
+---
+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。