---
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
