From 725a8a79bfb8004e58c794c842442c48c5c856a3 Mon Sep 17 00:00:00 2001
From: wx <wx>
Date: Tue, 4 Aug 2026 14:05:08 +0800
Subject: [PATCH] =?UTF-8?q?chore(changelog):=20#5470=20DAILY=5FV3=20?=
 =?UTF-8?q?=E9=85=8D=E8=BD=A6=E5=BF=AB=E7=85=A7=E5=9B=9E=E8=B0=83=E9=99=8D?=
 =?UTF-8?q?=E7=BA=A7-=E4=BF=AE=E6=94=B9=E6=8E=A5=E5=8F=A3-=E5=86=85?=
 =?UTF-8?q?=E9=83=A8=E6=9C=8D=E5=8A=A1?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...LY_V3配车快照回调降级-修改接口-内部服务.md | 65 +++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md

diff --git a/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md b/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md
new file mode 100644
index 0000000..ab9ef7e
--- /dev/null
+++ b/changelogs-v2/2026-08/04_5470_DAILY_V3配车快照回调降级-修改接口-内部服务.md
@@ -0,0 +1,65 @@
+---
+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 条修复前历史记录）。
+
+## 关联 / 联系人
+
+### 联系人
+
+- **后端负责人**: @wx