Store login verification codes in Redis

ai_knowledge_base_v2/development_records/2026-07-09-user-login-graphic-captcha.md

@@ -67,3 +67,26 @@
 - 手机号不存在时，发送短信验证码接口返回“手机号不在学员名单中，请联系管理员”，前端可见。
 - 图形验证码通过且手机号存在时，mock 短信仍可正常发送。
 - Docker 环境中图形验证码字体清晰，不能退化成过小或错位的默认字体。
+
+## 2026-07-09 补充：验证码状态迁移到 Redis
+
+### 变更原因
+
+图形验证码和短信验证码最初沿用进程内字典保存状态。单 worker 本地环境可以正常使用，但生产环境如果开启多个 backend worker 或多实例部署，就可能出现验证码由 A worker 生成、校验请求打到 B worker 后找不到验证码的问题。
+
+### 处理决策
+
+1. 图形验证码状态优先写入 Redis，key 为 `auth:captcha:{captcha_id}`，TTL 为 300 秒。
+2. 短信验证码状态优先写入 Redis，key 为 `auth:sms_code:{phone}`，TTL 使用系统配置中的短信验证码有效期。
+3. Redis 可用时，所有 worker 共享同一份验证码状态。
+4. Redis 未配置或临时不可用时，保留原进程内字典作为降级路径，避免本地开发环境完全不可用。
+5. 验证成功后删除对应 Redis key，保持验证码一次性使用。
+6. mock 短信开关开启时，仍保留“未发送但输入固定 mock 验证码可登录”的开发便利能力。
+
+### 新增验收标准
+
+- Docker dev 环境下，图形验证码和短信验证码应写入 Redis，并可通过 Redis key 观察到 TTL。
+- 发送短信验证码成功后，Redis 中应存在 `auth:sms_code:{phone}`。
+- 图形验证码生成后，Redis 中应存在 `auth:captcha:{captcha_id}`。
+- 验证码校验成功后，对应 Redis key 应被删除。
+- Redis 不可用时，单 worker 本地开发仍可使用内存降级路径。