短信微服务

功能概述

将短信发送模块从快递业务代码中完全拆离，部署为独立微服务。全平台所有业务线（快递、洗衣、用户中心等）统一通过该服务发送短信，实现短信能力的复用和集中管控。

用户故事

作为 业务系统开发者，我希望 调用一个统一的短信 API 即可完成短信发送，以便 无需关心底层短信渠道的切换和维护。

作为 平台运营管理员，我希望 在后台管理短信模板、签名和发送配额，以便 不必每次改短信内容都找研发。

前置条件

快递业务系统已完成基本的服务化拆分（或本次同步完成）
消息队列基础设施已就绪（Kafka / RocketMQ）
至少一个短信渠道（阿里云 / 腾讯云）已开通

功能详述

场景 1：业务方调用短信发送（正常流程）

业务方携带 API Key 调用 POST /api/v1/sms/send
短信服务校验 API Key 有效性、租户日配额余量、模板状态
校验通过，消息落库并写入消息队列，立即返回 { "status": "queued", "message_id": "..." }
消费者从队列中取出消息，调用对应短信渠道 API 完成发送
发送结果回调通知业务方（如果配置了回调 URL）

场景 2：运营管理员创建短信模板

运营管理员在后台进入「短信模板」页面，点击「新建模板」
填写：模板名称、适用渠道（阿里云/腾讯云）、渠道模板 ID、模板内容（含变量占位符 {code}）、关联签名
提交后，模板状态为「待审核」
超级管理员审核通过后，模板状态变为「已启用」，业务方可使用

场景 3：短信发送失败处理

消费者调用渠道 API 失败（如网络超时、余额不足）
记录失败原因到发送日志
若失败原因为可重试类型（网络超时、限流），自动入重试队列（最多 3 次）
重试 3 次仍失败，标记为「发送失败」，通过回调或告警通知
若失败原因为不可重试类型（号码黑名单、签名未报备），直接标记失败并记录原因

场景 4：配额超限

某租户当日发送量已达配额上限
后续请求返回 { "code": 429, "message": "日发送配额已用尽" }
同时通过站内通知提醒租户管理员
运营管理员可在后台为该租户临时或永久提升配额

交互说明

核心参数

元素	类型	说明	规则
api_key	string	租户标识	必填，Header 传递
template_id	string	短信模板 ID	必填，需为已启用模板
mobiles	string[]	目标手机号	必填，单条最多 100 个
variables	object	模板变量值	与模板占位符数量一致
callback_url	string	回调地址	选填，接收发送结果

状态说明

queued：已入队，等待发送
sending：正在调用渠道发送
success：发送成功
failed：发送失败（含失败原因码）
rate_limited：被限流，等待重试

验收标准

[ ] F-101-AC01：快递业务短信发送已切换至新服务，旧代码已移除
[ ] F-101-AC02：全平台任意业务线接入短信服务只需 API Key + 调用 send 接口
[ ] F-101-AC03：短信模板可通过后台创建、审核、启用/停用，无需发版
[ ] F-101-AC04：发送失败自动重试 3 次，3 次后告警
[ ] F-101-AC05：租户日配额超限自动拦截，返回明确错误码
[ ] F-101-AC06：发送成功率 > 98%（正常时段，不含无效号码）

技术备注

消息队列选型建议 RocketMQ（公司统一中间件），保证消息持久化
短信渠道适配器模式：新增渠道只需实现 SmsProvider 接口
发送日志保留 90 天，过期归档