短信渠道接入说明
核心框架统一通过 pkg/sms 发送短信，管理端继续使用现有的“开发信息、签名模板、短信模板、发送记录”页面。短信配置允许多个渠道同时启用，但只能有一个启用的默认渠道。
运行环境与开发验证码
config.yaml顶层environment仅允许development、testing、production。environment: development时，用户端发送验证码接口不调用真实短信渠道；输入sms.development_code配置的固定六位验证码即可通过校验，便于本地联调。testing和production环境不会读取固定验证码，仍执行真实渠道发送、Redis 有效期、错误次数限制与一次性消费逻辑。- 部署测试或生产环境时必须显式修改
environment，不能使用开发环境配置。
支持渠道
| provider | 渠道 | access_key_id | access_key_secret | 模板编码 | 默认 Endpoint |
|---|---|---|---|---|---|
| 1 | 阿里云 | AccessKey ID | AccessKey Secret | 必填 | https://dysmsapi.aliyuncs.com |
| 2 | 腾讯云 | 短信应用 SDK AppID | Secret Key | 必填 | https://sms.tencentcloudapi.com |
| 3 | 短信宝 | 登录用户名 | API Key 或 32 位 MD5 密码 | 可选，作为产品 ID g | https://api.smsbao.com/sms |
| 4 | SMS.cn | 登录账号 uid | md5(登录密码 + uid) 得到的 32 位接口密码 | 必填 | https://api.sms.cn/sms/ |
| 5 | 云片 | API Key | 不使用 | 可留空 | https://sms.yunpian.com/v2/sms/single_send.json |
管理端不会回传已保存的密钥。修改配置时密钥留空表示继续使用原值；云片不需要填写密钥字段。自定义 Endpoint 仅允许 http 或 https 地址，生产环境应使用 HTTPS 并限制配置权限。
签名与模板
- 阿里云、腾讯云和 SMS.cn 使用平台审核通过的模板编码。
- 短信宝和云片使用系统模板填充后的完整正文；框架会在正文前拼接
【签名】，如果正文已经以该签名开头则不会重复拼接。 - 短信宝的模板编码可填写平台产品 ID；没有使用产品 ID 时可以留空。
- 验证码模板支持
${code}、{code}、{1}和#{code}占位符。 - 当前发送逻辑只选择同时满足“启用且默认”的唯一开发配置，再按 ID 升序选择该配置下第一条启用的签名和验证码模板。其他渠道可以保持启用，但不会参与发送。
默认渠道规则
- 多个短信渠道可以同时启用，未删除的配置中只能有一个默认渠道。
- 默认渠道必须为启用状态。管理端不允许取消、停用或删除当前默认渠道，必须先把另一个启用渠道设为默认。
- 新增第一条短信渠道时必须启用，系统会自动将它设为默认。
- 管理端切换默认渠道使用数据库事务；
default_slot生成列和唯一索引在数据库层兜底，避免并发请求产生两个默认渠道。 - 用户端发送前会再次查询启用的默认渠道作为兜底；不存在时返回“短信服务未开启，请联系管理员”，且不会生成验证码或占用发送频控次数。
请求与发送记录
三家新增渠道的请求约定如下：
- 短信宝：GET 请求，成功响应码为
0。 - SMS.cn：表单 POST 请求，成功响应字段为
stat=100；验证码参数按{"code":"123456"}发送。 - 云片：表单 POST 请求，成功响应字段为
code=0，返回的sid会写入短信发送记录的平台消息 ID。
所有渠道都复用现有的请求超时、验证码限流和发送日志机制。渠道原始密钥不会写入日志；对外接口只返回统一错误，渠道错误详情仅保存在管理端发送记录中。
配置与验证步骤
- 在“系统配置 / 短信配置 / 开发信息”新增渠道凭证，Endpoint 通常留空。
- 为该开发配置新增已审核的签名。
- 新增类型为“验证码”的模板，并填写模板内容；按上表决定是否填写模板编码。
- 返回“开发信息”新增或修改渠道：测试手机号留空时仅保存；填写手机号时先保存配置，再调用
POST /admin/sms/config/test发送测试验证码。 - 测试接口固定使用所选渠道下按 ID 升序第一条启用的签名和验证码模板，不要求渠道为默认或启用；同一配置和手机号每分钟只能测试一次，结果写入发送记录。
- 将正式使用的渠道设为默认并保持启用；用户端
POST /api/sms/code只使用该启用默认渠道。
新增渠道时必须先保存配置，才能为其创建签名和模板。因此首次在新增表单填写测试手机号时，配置仍会保存成功，但测试会明确提示先维护签名或模板；维护完成后在修改配置表单再次填写手机号即可完成验证。短信属于外部调用，测试失败不会回滚已经保存的配置。
数据库升级
短信所需的完整表结构与菜单已包含在核心 sql/0.0.1/full.sql，新系统随基座一次安装即可。已有系统不重复导入全量；后续变化通过对应版本 incremental.sql 和核心升级命令执行。完整流程见数据库版本管理。