Document Aliyun SMS and admin login redesign

ai_knowledge_base_v2/development_records/2026-07-09-aliyun-sms-and-admin-login-redesign.md

@@ -0,0 +1,50 @@
+# 阿里云短信接入与管理后台登录页优化
+
+日期：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。
+- 管理后台登录页在桌面和窄屏下都不应出现内容重叠、裁切或明显粗糙感。