---
author: "wx(GIT)"
schema: "hl-changelog/v2"
ticket: "5505"
title: "HOLD 派车短信空串 code 降级：不再被阿里云拒收，通知链路收敛"
consumer: "admin"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: "2026-08-04"
status_note: "HOLD（待司机确认）阶段派车短信因无真实行程短链（code 为空）此前被阿里云 TEMPLATE_PARAMS_ILLEGAL 拒收、通知 outbox 无限重试；本次修复为按产品口径降级：短信通道明确 SKIP（send_log status=3 终态，原因含“短信按产品口径降级”），站内通知不受影响，outbox 收敛 SUCCESS。ASSIGNED 后真实短链短信（ITINERARY_READY）不受影响。"
updated_at: "2026-08-04"
base: "dev-v3"
---

# 【修改接口·管理后台】HOLD 派车短信空串 code 降级（#5505）

> **PR**: #5509 | **服务**: fleet + user | **更新时间**: 2026-08-04

## 1. 接口背景

HOLD（待司机确认）派车阶段创建派单后触发 FLEET_DISPATCH_CREATED 短信：模板 SMS_510265061 正文固定含 `https://hr.1814.love/s/${code}` 链接参数，但 HOLD 阶段组行未冻结（#5461）不签发行程短链，`code` 为空串 → 阿里云以 `isv.TEMPLATE_PARAMS_ILLEGAL` 拒收整条短信，司机收不到通知且 fleet outbox 无限重试（retry_count 持续增长）。

## 变更接口清单

| # | 接口名 | 方法 | 路径 | 变更类型 | 说明 |
|---|--------|------|------|----------|------|
| 1 | 通知发送日志 | — | 内部（fleet→user 通知中心） | 修改 | reliable 短信 `code` 缺失/空串时明确 SKIP（status=3，终态），不再外发含空链接参数的短信 |
| 2 | 派单事务 outbox | — | 内部（fleet 定时重放） | 修改 | HOLD 占位快照 + 短信明确 SKIP + 全部通道确定性终态时按降级结算收敛为 SUCCESS，不再重试 |

## 2. 行为变化

| 场景 | 原来 | 现在 |
|------|------|------|
| HOLD 派车（待司机确认）短信 | code="" 外发 → 阿里云 TEMPLATE_PARAMS_ILLEGAL 拒收 → send_log FAIL、outbox 无限重试 | 短信通道明确 SKIP（send_log `status=3`，fail_reason 含「短信按产品口径降级」），outbox 收敛 `SUCCESS`；站内通知不受影响 |
| ASSIGNED 后真实短链短信（ITINERARY_READY） | 正常发送 | 不变（code 有值） |
| 短信真实事故（模板配置错误等 FAIL） | FAIL 重试至 QUARANTINED | 不变（不降级、不伪造成功） |

## 3. 接口详情

- 管理后台「通知日志」状态枚举不变（0~6）：本次新增的短信 SKIP 使用既有 `status=3`（SKIP），fail_reason 为降级说明，可据此识别 HOLD 占位短信
- `holdSentAt` 语义不变：只有真实外部通道成功才写入；HOLD 降级场景不写
- 前端无字段/枚举变化；若通知日志页对 status=3 有专门文案，可补充「HOLD 占位短信降级（行程确认后发送）」类展示（非必须）

## 4. 前端需要做什么

无必须改动。可选：通知日志页 SKIP（status=3）文案适配。

## 5. 后端测试、部署与验证

- 定向：fleet `AssignmentHoldNotificationEffectServiceTest` 32/32（新增降级结算收敛、真实 FAIL 不降级 2 用例；占位快照断言改为 `code` 键不出现）；user `SmsChannelSenderTest` 37/37（两个历史「空 code 允许发送」断言修正为 SKIP 降级）；fleet HOLD/ITINERARY 12 类 + user Dispatcher/LogService 71 用例全绿
- 模块验证：`mvn -pl hl-fleet-service,hl-user-service -am verify`——user 3518 全绿；fleet 3107 用例仅 ReleaseEOccupancyMysql8033RecoveryTest 10 错（缺 CI 专用属性 `fleet.mysql.releaseE.finalMigrationSha256`，基线 dev-v3 同失败，非本次引入）
- 部署：TEST fleet（task_id=80bf903a）+ user（task_id=4bb72dfd）双实例 UP
- 验证（TEST 2026-08-04）：存量 PENDING HOLD_NOTIFICATION 事件重试后按降级收敛（send_log SKIP 终态、outbox SUCCESS、无 TEMPLATE_PARAMS_ILLEGAL）

## 关联 / 联系人

### 联系人

- **后端负责人**: @wx