diff --git a/changelogs-v2/2026-08/04_5505_HOLD派车短信空串code降级-修改接口-管理后台.md b/changelogs-v2/2026-08/04_5505_HOLD派车短信空串code降级-修改接口-管理后台.md new file mode 100644 index 0000000..9187c5c --- /dev/null +++ b/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