diff --git a/changelogs-v2/2026-07/28_5302_派车档期按完整组判定同城衔接-修改接口-管理后台.md b/changelogs-v2/2026-07/28_5302_派车档期按完整组判定同城衔接-修改接口-管理后台.md new file mode 100644 index 0000000..0b4d54c --- /dev/null +++ b/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。