29 lines
1.6 KiB
Markdown
29 lines
1.6 KiB
Markdown
# 短信网关接入契约
|
||
|
||
## 元数据
|
||
|
||
- Owner：通知适配维护人
|
||
- 实现：`pkg/sms/`
|
||
- 协议版本：渠道 SMS HTTP 1.6；仓库仅保留当前实现所需字段摘要
|
||
- 核验日期：2026-08-07
|
||
|
||
## 当前实际使用范围
|
||
|
||
系统使用 `POST <gateway_url>/sms/api/sendMessageMass` 批量发送短信；未发现状态回执查询或上行短信处理。
|
||
|
||
## 配置、认证与字段
|
||
|
||
配置键为 `sms.gateway_url`、`sms.username`、`sms.password`、`sms.signature`、`sms.timeout`。默认配置超时为 10 秒，运行配置可覆盖。客户端把短信签名拼在正文前，提交 `userName`、`content`、`phoneList`、毫秒时间戳和 `sign`。签名算法为小写 `MD5(username + timestamp + MD5(password))`。
|
||
|
||
响应关键字段为 `code`、`message`、`msgId`、`smsCount`；只有代码中定义的 `CodeSuccess` 才视为提交成功，其他状态转换为 `SMSError` 并保留渠道码。
|
||
|
||
## 幂等、重试与安全
|
||
|
||
客户端不自动重试，也不生成业务幂等键；调用方需以通知业务标识防重，并在网络结果不确定时先判断是否允许重发。密码、签名原文、完整手机号列表和完整正文不得记录；当前实现只输出手机号列表和最多 50 个字符的内容预览，部署侧仍需日志脱敏。
|
||
|
||
## 验证
|
||
|
||
可复现静态证据：`pkg/sms/client.go`、`pkg/sms/types.go`、`pkg/config/config.go`。真实验收需使用测试号码核对单条/批量、错误签名、超时和重复发送；本次 Context 重建不发送真实短信。
|
||
|
||
协议版本、端点、认证、字段、成功码或重试语义变化时更新本文。
|