From 7f31a6b9cc761d79b94c3a5970b7700d51864375 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Mon, 3 Aug 2026 23:35:51 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#5444=20Step2=20canonical=20?= =?UTF-8?q?full=20snapshot=20=E4=B8=8E=E7=A8=B3=E5=AE=9A=E6=A7=BD=E4=BD=8D?= =?UTF-8?q?=20=E4=BA=A4=E6=8E=A5=E5=89=8D=E7=AB=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...tep2-canonical-full-snapshot-与稳定槽位.md | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 changelogs/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md diff --git a/changelogs/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md b/changelogs/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md new file mode 100644 index 0000000..008c15b --- /dev/null +++ b/changelogs/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md @@ -0,0 +1,82 @@ +--- +schema: "hl-changelog/v2" +ticket: "5444" +title: "Step2 canonical full snapshot 与稳定槽位" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "pending" +gateway_status: "pending" +frontend_status: "pending" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "" +updated_at: "2026-08-03" +base: "dev-v3" +generated: "2026-08-03T23:34:18+08:00" +--- + +# Step2 canonical full snapshot 与稳定槽位 + +> #5444（#5366 B08/B09 后端）：派车弹窗 Step2 canonical full snapshot 与稳定槽位。 +> 后端实现已合入 PR #5448（待合并状态）；后端/网关状态以部署验证为准。 + +## 关联 + +- Issue: #5444 +- PR: [#5448](https://git.1814.love:8443/wx/HL/pulls/5448) + +## 变更接口 + +| 方法 | 路径 | 来源 | +|---|---|---| +| `POST` | `/admin/fleet/assignments/candidates` | 响应新增 `canonicalSnapshot` 区块；请求新增可选同代校验参数（additive，向后兼容） | + +## 契约影响文件 + +- `hl-fleet-service/src/main/java/com/hulalv/fleet/assignment/vo/AssignmentCandidateReqVO.java` +- `hl-fleet-service/src/main/java/com/hulalv/fleet/assignment/vo/AssignmentCandidateRespVO.java` +- `hl-fleet-service/src/test/java/com/hulalv/fleet/assignment/controller/AssignmentControllerTest.java` + +## 请求新增（均可选） + +- `expectedPlanGeneration`（Long·String）：Step2 幂等重试/同代校验期望计划代际；携带且与当前 canonical 快照不符时以 `605061` 拒绝（generation 漂移 fail-closed）。 +- `expectedSnapshotVersion`（Long·String）：同上，期望快照版本。 + +## 响应新增 `canonicalSnapshot` 区块（additive） + +- `planGeneration`（Long·String）：当前计划代际（不透明令牌）；与 `snapshotVersion` 共同标识同一份 canonical 快照。 +- `snapshotVersion`（Long·String）：当前快照版本；同代内容修订递增。 +- `retainedSlotIds`（Long·String[]）：有序 RetainedSlotSet（稳定槽位集合）；不重编号、不丢 protected/active slot、至少 1 个。 +- `editableServiceDates`（LocalDate[]）：完整有序可编辑服务日。 +- `cells`：每个 `RetainedSlotSet × editableServiceDates` 笛卡尔积位置唯一 cell： + - `slotId`（Long·String） + - `serviceDate`（LocalDate） + - `used`：`USED` / `UNUSED` / `null`（无切片行=未编辑） + - `readOnly`（Boolean）：只读 cell 不可被批量操作改写 + - `readOnlyReason`（String）：只读原因；可编辑为 null（派单已完结 / 派单已取消 / 服务日期已过去 / 对账期已关账） + - `vehicleId` / `driverId`（Long·String，未派或不用车为 null） +- `selectedVehicle`（对象，未选或资源失效为 null）：`vehicleId` / `plate` / `modelName` / `seats` +- `selectedDriver`（对象，未选或资源失效为 null）：`driverId` / `name` / `maskedPhone`（司机域脱敏）/ `driverStatus` / `season` + +## 行为说明（B08/B09） + +- 首次进入 Step2 且不存在稳定槽位时，后端在 requirement 锁 + 独立新事务内原子生成至少 1 个稳定 `slotId` 并落 `fleet_assignment` unassigned 每日切片；同一 `planGeneration + snapshotVersion` 下重复读取/幂等重试不重复建槽、不重编号。 +- `selectedVehicle`/`selectedDriver` 为与 `snapshotVersion` 同代的已选资源展示快照，独立于候选分页/筛选；null/失效资源 fail-closed 不编造。 +- 未传 `requirementId` 或需求上下文不可用时 `canonicalSnapshot` 为 `null`，候选查询本身不受影响。 + +## 前端/调用方动作 + +- Step2 前端可消费 `canonicalSnapshot` 区块组织稳定槽位 UI；重复读取/幂等重试时回传 `expectedPlanGeneration`/`expectedSnapshotVersion` 做同代校验。 +- 不新增前端建槽 API 与二次批量查询 API；`selectedVehicle`/`selectedDriver` 直接取自现有 `selectedVehicleId`/`selectedDriverId` 入参。 +- 未消费新字段的既有调用保持兼容（additive）。 + +## 验证证据 + +- 定向测试：`Step2CanonicalSnapshotServiceTest`（11 用例：首次原子建槽/同代幂等不重编号/并发/漂移 fail-closed/脱敏/跨页过滤/null 失效/readOnly cell）、`AssignmentCandidateServiceTest`、`AssignmentControllerTest`（canonicalSnapshot 挂载 + 透传），全部通过。 +- Fleet 全量测试：3022/3023 通过；唯一失败 `FleetInsuranceTaskTeamNoMysqlTest` 为 Testcontainers 无 Docker 环境型失败（基线上同样失败）。 +- Spotless `spotless:check` 通过。 +- 网关验证：待测试部署后补充（`backend_status`/`gateway_status` 保持 pending）。 +- 兼容性结论：请求/响应均为 additive 扩展，向后兼容。