# 阿里云短信接入与管理后台登录页优化

日期：2026-07-09

## 需求背景

当前用户端短信验证码仍以 mock 固定验证码为主，无法用于真实用户登录。管理后台登录页也偏简陋，不利于作为正式后台入口交付。

## 本次目标

1. 用户端短信验证码接入阿里云短信服务。
2. 阿里云短信所需参数加入“系统配置”，由管理员在后台维护。
3. 保留 mock 短信开关，方便本地开发和演示环境继续使用固定验证码。
4. 管理后台登录页重新设计，提高正式感、可读性和登录体验。

## 阿里云短信配置项

系统配置页新增以下配置：

| 配置项 | 说明 |
| --- | --- |
| `aliyun_sms_access_key_id` | 阿里云 RAM 用户 AccessKey ID |
| `aliyun_sms_access_key_secret` | 阿里云 RAM 用户 AccessKey Secret |
| `aliyun_sms_sign_name` | 阿里云短信签名名称 |
| `aliyun_sms_template_code` | 阿里云短信模板 Code |
| `aliyun_sms_template_param_key` | 验证码模板变量名，默认 `code` |
| `aliyun_sms_endpoint` | 阿里云短信服务 endpoint，默认 `dysmsapi.aliyuncs.com` |

## 设计决策

- 当 `mock_sms_enabled=true` 时，仍使用 mock 短信验证码。
- 当 `mock_sms_enabled=false` 时，调用阿里云短信真实发送验证码。
- 后端生成验证码后先调用阿里云发送，发送成功后再写入内存验证码记录，避免短信失败但验证码可登录。
- 阿里云 AccessKey Secret 在系统配置页使用密码输入框展示，不在日志中输出。
- 阿里云调用错误对用户返回统一“短信发送失败，请稍后再试”，避免把供应商内部错误直接暴露给用户端。
- 管理后台登录页只优化登录入口，不改变管理员账号密码登录方式。

## 参考依据

- 阿里云官方 Python SDK 文档建议使用 `alibabacloud_dysmsapi20170525`。
- 阿里云 SendSms 示例参数包括手机号、签名名、模板 Code 和模板变量 JSON。
- 阿里云官方安全建议包括使用 RAM 用户、避免硬编码 AccessKey、避免日志打印敏感信息。

## 验收标准

- 系统配置页能维护阿里云短信参数。
- mock 开启时，原固定验证码登录流程不受影响。
- mock 关闭且阿里云参数缺失时，发送短信接口返回明确错误。
- mock 关闭且阿里云参数完整时，后端调用阿里云 SendSms。
- 管理后台登录页在桌面和窄屏下都不应出现内容重叠、裁切或明显粗糙感。
