From 9b9ca15d63efee80acb409b3ce61ff029f1a9f5a Mon Sep 17 00:00:00 2001 From: yaosutu <770858045@qq.com> Date: Tue, 4 Aug 2026 16:24:16 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=8E=86=E5=8F=B2=20changelo?= =?UTF-8?q?g=20=E6=B6=88=E8=B4=B9=E6=96=B9=E8=B7=AF=E7=94=B1=E4=B8=8E?= =?UTF-8?q?=E6=96=87=E4=BB=B6=E5=90=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...绪门禁与清零释放内部契约-修改接口-内部服务.md | 70 ------------------- ...LY_V3配车快照回调降级-修改接口-内部服务.md | 70 ------------------- ...al-full-snapshot与稳定槽位-修改接口-管理后台.md | 2 +- ...46_HOLD通知管理端状态查询与受控重试-新增接口-管理后台.md | 2 +- 4 files changed, 2 insertions(+), 142 deletions(-) delete mode 100644 changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md delete mode 100644 changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md rename changelogs-v2/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md => changelogs/2026-08/04_5444_Step2-canonical-full-snapshot与稳定槽位-修改接口-管理后台.md (98%) rename changelogs-v2/2026-08/2_5446_HOLD-通知管理端状态查询与受控重试.md => changelogs/2026-08/04_5446_HOLD通知管理端状态查询与受控重试-新增接口-管理后台.md (98%) diff --git a/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md b/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md deleted file mode 100644 index ce79294..0000000 --- a/changelogs-v2/2026-08/03_5319_团期配车就绪门禁与清零释放内部契约-修改接口-内部服务.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -schema: "hl-changelog/v2" -ticket: "5319" -title: "团期配车就绪门禁与清零释放内部契约" -consumer: "internal" -change_type: "修改接口" -backend_status: "deployed" -gateway_status: "not_required" -frontend_status: "not_required" -frontend_owner: "" -frontend_ref: "" -target_release: "" -verified_at: "" -status_note: "PR #5432 已合并 dev-v3（c3c78ea8f）；fleet 4b1ab397 / order-v3 5bc5d247 已部署测试环境并经服务直连验证。internal 契约仅供服务间 Feign 消费，前端不涉及。" -updated_at: "2026-08-03" -base: "dev-v3" ---- - - -# 团期配车就绪门禁与清零释放内部契约（#5319） - -> **服务**: hl-fleet-service（8087）/ hl-order-service-v3（8086） -> **PR**: #5432 -> **Issue**: #5319 -> **日期**: 2026-08-03 -> **影响范围**: 团期配车重配就绪校验、整团清零/释放、vehicle_ready 双向回填（服务间 internal Feign） - ---- - -## ⚠️ 关键变化 - -- Fleet `POST /internal/fleet/dispatch/group-batch/reconfigure` 重配前新增 order-v3 权威基线校验： - - 服务日必须完整覆盖团期 departDate..endDate（缺首日/末日/中间日、越界、空洞原子失败） - - 仅 `RESOURCE_PREPARING`（成团后资源配置阶段）可配，已流团/终态及出行后状态拒绝 - - 新增 `clearAll=true` 显式整团清零语义（软删全部活跃配车 + vehicle_ready=false） -- `GROUP_READY` 意图按团期级 planVersion 去重（新表 fleet_group_dispatch_plan），相同计划重复提交不新增意图 - -## 变更接口 - -| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | -|---|------|------|------|----------|------| -| 1 | 团期配车重配 | POST | `/internal/fleet/dispatch/group-batch/reconfigure`（Fleet，Feign 入向） | 修改接口 | 新增权威基线校验 + clearAll 清零；请求体新增 `clearAll` 字段（可空） | -| 2 | 团期配车占用释放 | POST | `/internal/fleet/dispatch/group-batch/:groupBatchId/release`（Fleet，Feign 入向） | 新增接口 | 幂等软删全部活跃配车 + vehicle_ready=false | -| 3 | 团期配车权威基线 | GET | `/v3/internal/group-batch/:groupBatchId/dispatch-baseline`（order-v3，Feign 出向） | 新增接口 | 返回服务日集合 + 生命周期可配判定；团期不存在返 589500 | -| 4 | 重置配车就绪 | POST | `/v3/internal/group-batch/:groupBatchId/vehicle-ready-reset`（order-v3，Feign 出向） | 新增接口 | vehicle_ready=false 幂等重置 | -| 5 | 回填配车就绪 | POST | `/v3/internal/group-batch/:groupBatchId/vehicle-ready`（order-v3，Feign 出向） | 修改接口 | 语义不变（置 true 幂等），配合清零/释放双向闭环 | - -## 调用方动作（internal） - -- order-v3 团期配车编排方：重配请求按权威服务日提交完整计划；需清零时置 `clearAll=true`（demands 可空） -- 共享 DTO：`GroupBatchDispatchBaselineDTO`（hl-common-core）新增 -- 前端不消费任何 internal 端点，无前端动作 - -## 验证证据 - -- 定向测试：Fleet `GroupDispatchServiceTest`（29 用例）+ writer/effect/listener；order-v3 `GroupBatchServiceTest`/Outbox processor/service/listener/controller 契约 -- reactor verify：Fleet 2870 用例（仅 Testcontainers MySQL 无 Docker 环境失败，基线同样失败）；order-v3 全量 verify 通过；fleet spotless:check 通过 -- 网关验证：internal 路径经网关 403 为设计行为（JwtAuthFilter 全局阻断）；经服务直连验证 release=200、dispatch-baseline=589500（失败关闭）、vehicle-ready-reset=200、vehicle-ready=200（证据 `tmp/5319-gateway-evidence.md`） -- 兼容性结论：既有 `vehicle-ready`（置 true）契约不变；重配请求在完整覆盖校验下语义收紧（此前不完整计划可提交），调用方须按权威服务日提交 - -## 关联 / 联系人 - -### 链接 - -- **Issue**: [#5319](https://git.1814.love:8443/wx/HL/issues/5319) -- **PR**: [#5432](https://git.1814.love:8443/wx/HL/pulls/5432) -- **Merge commit**: [c3c78ea8f4](https://git.1814.love:8443/wx/HL/commit/c3c78ea8f4) -### 联系人 - -- **后端负责人**: @wx diff --git a/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md b/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md deleted file mode 100644 index 829566e..0000000 --- a/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -schema: "hl-changelog/v2" -ticket: "5470" -title: "DAILY_V3 配车快照回调 hmac-secret 缺失降级 SHA-256" -consumer: "internal" -change_type: "修改接口" -backend_status: "deployed" -gateway_status: "not_required" -frontend_status: "not_required" -frontend_owner: "" -frontend_ref: "" -target_release: "" -verified_at: "2026-08-04" -status_note: "Fleet→order DAILY_V3 配车快照回调在 order.assignment.snapshot.hmac-secret 未配置时不再 500，降级无密钥 SHA-256 指纹；fleet outbox 投递 SUCCESS、order_vehicle_assignment 正常落库。" -updated_at: "2026-08-04" -base: "dev-v3" ---- - -# 【修改接口·内部服务】DAILY_V3 配车快照回调 hmac-secret 缺失降级 (#5470) - -> **PR**: #5474 | **服务**: order-v3 | **更新时间**: 2026-08-04 - -## 1. 接口背景 - -fleet 派单（holdMode=0 创建成功）后通过 DAILY_V3 快照 outbox 回调 order-v3 同步配车投影。order 侧对回调请求计算拓扑指纹（`topology_fingerprint`，幂等/计数校验共用）需要 `order.assignment.snapshot.hmac-secret` 配置；该配置缺失时原实现 fail-fast 抛 `IllegalStateException` → 回调 HTTP 500 → 快照不落库、fleet outbox 无限重试。本次改为配置缺失时降级为无密钥 SHA-256 指纹并记 warn 日志。 - -## 变更接口清单 - -| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 | -|---|--------|------|------|----------|------| -| 1 | DAILY_V3 配车快照回写 | POST | `/v3/internal/order/vehicle-assignment/callback` | 修改 | hmac-secret 未配置时不再 500，降级 SHA-256 指纹继续落库 | - -## 2. 行为变化 - -| 场景 | 原来 | 现在 | -|------|------|------| -| `order.assignment.snapshot.hmac-secret` 未配置 | HTTP 500 `Fleet snapshot HMAC secret is not configured`，快照不落库，fleet outbox 无限重试 | 200 正常处理；拓扑指纹改用无密钥 SHA-256（64 位 hex），后端 warn 日志提示降级 | -| hmac-secret 已配置 | HMAC-SHA256 指纹 | 不变 | -| 同 payload 重复投递（同 revision+eventId+digest） | IDEMPOTENT | 不变（降级指纹同样幂等） | -| stale revision | STALE_IGNORED | 不变 | - -## 3. 接口详情 - -- **方法/路径**：`POST /v3/internal/order/vehicle-assignment/callback` -- **认证**：internal token（`X-Internal-Token`）+ `VehicleAssignmentSnapshotInternalTokenFilter` fail-closed；网关不暴露至公网 -- **请求体**：`VehicleAssignmentSnapshotCallbackReqVO`（contractVersion=DAILY_V3、eventId、orderId、requirementId、snapshotRevision、planServiceDates/planFleetItemIndexes/planTopologySize、dailyAssignments[]） -- **响应**：`{eventId, orderId, requirementId, result(APPLIED/IDEMPOTENT/STALE_IGNORED/ORDER_CANCELLED_IGNORED), acceptedSnapshotRevision, activeDailyCellCount, usedVehicleDayCount, feeReadyVehicleDayCount, snapshotActive, processedAt}` -- **错误码**：契约不支持/快照非法/需求不存在/订单不匹配/revision 冲突/结算已冻结等业务码不变；不再出现未捕获 500 - -## 4. 前端需要做什么 - -无（internal 接口，无前端消费）。 - -## 5. 后端测试、部署与验证 - -- 单元测试：`VehicleAssignmentSnapshotDigestTest` 3 用例（空 secret 降级 SHA-256 确定性 + 字段敏感、HMAC 确定性、全字段覆盖）；`DailyVehicleAssignmentSnapshotServiceTest` 12 用例（含 IDEMPOTENT/STALE/revision 冲突）。 -- 模块验证：`mvn -pl hl-order-service-v3 -am verify` 7427 测试 0 失败。 -- 部署：TEST hl-order-service-v3 rolling 部署完成（dev-v3 @ 97ad827da，双实例 UP）。 -- 验证（TEST 2026-08-04）：对隔离事件 `342887996946780160`（orderId=2084274056961331202）requeue 重放 → fleet outbox `SUCCESS`（processed_at 14:04:00，retry_count 归零）；`order_vehicle_assignment` 3 行落库（8-03~8-05，used=3/feeReady=3，driver_phone_ciphertext 加密列正常）；`order_vehicle_requirement` 回写 `assignment_contract_version=DAILY_V3`、`assignment_snapshot_revision=1`、`assignment_event_id=342887996946780160`、`assignment_snapshot_active=1`、status=DONE；error_logs 无修复后新增 500（仅 7 条修复前历史记录）。 - -## 关联 / 联系人 - -### 链接 - -- **Issue**: [#5470](https://git.1814.love:8443/wx/HL/issues/5470) -- **PR**: [#5474](https://git.1814.love:8443/wx/HL/pulls/5474) -- **Merge commit**: [97ad827da5](https://git.1814.love:8443/wx/HL/commit/97ad827da5) -### 联系人 - -- **后端负责人**: @wx diff --git a/changelogs-v2/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md b/changelogs/2026-08/04_5444_Step2-canonical-full-snapshot与稳定槽位-修改接口-管理后台.md similarity index 98% rename from changelogs-v2/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md rename to changelogs/2026-08/04_5444_Step2-canonical-full-snapshot与稳定槽位-修改接口-管理后台.md index 2ad9134..e03af05 100644 --- a/changelogs-v2/2026-08/3_5444_Step2-canonical-full-snapshot-与稳定槽位.md +++ b/changelogs/2026-08/04_5444_Step2-canonical-full-snapshot与稳定槽位-修改接口-管理后台.md @@ -19,7 +19,7 @@ generated: "2026-08-03T23:34:18+08:00" --- -# Step2 canonical full snapshot 与稳定槽位 +# 【修改接口·管理后台】Step2 canonical full snapshot 与稳定槽位 > #5444（#5366 B08/B09 后端）：派车弹窗 Step2 canonical full snapshot 与稳定槽位。 > 后端实现已合入 PR #5448（merge 8ceb8c5）；测试部署 task 80234589；网关验证通过。 diff --git a/changelogs-v2/2026-08/2_5446_HOLD-通知管理端状态查询与受控重试.md b/changelogs/2026-08/04_5446_HOLD通知管理端状态查询与受控重试-新增接口-管理后台.md similarity index 98% rename from changelogs-v2/2026-08/2_5446_HOLD-通知管理端状态查询与受控重试.md rename to changelogs/2026-08/04_5446_HOLD通知管理端状态查询与受控重试-新增接口-管理后台.md index 9adbe8e..5a58f2c 100644 --- a/changelogs-v2/2026-08/2_5446_HOLD-通知管理端状态查询与受控重试.md +++ b/changelogs/2026-08/04_5446_HOLD通知管理端状态查询与受控重试-新增接口-管理后台.md @@ -19,7 +19,7 @@ generated: "2026-08-03T23:19:24+08:00" --- -# HOLD 通知管理端状态查询与受控重试 +# 【新增接口·管理后台】HOLD 通知管理端状态查询与受控重试 ## 关联