chore(changelog): #5505 HOLD派车短信空串code降级-修改接口-管理后台

changelogs-v2/2026-08/04_5505_HOLD派车短信空串code降级-修改接口-管理后台.md

@@ -0,0 +1,63 @@
+---
+schema: "hl-changelog/v2"
+ticket: "5505"
+title: "HOLD 派车短信空串 code 降级：不再被阿里云拒收，通知链路收敛"
+consumer: "admin"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+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