docs: 记录用户端登录页正式改造方案

ai_knowledge_base_v2/development_records/2026-07-10-user-login-redesign.md

@@ -0,0 +1,48 @@
+# 用户端手机号登录页正式改造计划与实施记录
+
+## 目标
+
+根据设计图重新实现“大本营答疑助手”手机号验证码登录页。页面采用移动端优先布局，保持简洁、温和、可信的品牌气质，同时完整保留学员名单校验、短信验证码登录、图形验证码和真实错误反馈。
+
+## 现状检查
+
+- 技术栈：Vue 3、TypeScript、Vite，无前端路由和状态管理库。
+- 页面入口：`apps/user-client/src/App.vue` 根据登录用户状态展示 `LoginPanel.vue` 或聊天页面。
+- 接口封装：`apps/user-client/src/services/api.ts`。
+- 手机号登录：`POST /api/auth/login`，参数为手机号和短信验证码。
+- 短信发送：`POST /api/auth/sms/send`。
+- 图形验证码：`GET /api/auth/captcha`；现有短信发送协议强制要求图形验证码。
+- 学员准入：后端发送短信前检查手机号是否存在于启用学员名单。
+- 用户协议和隐私政策：当前没有独立路由、页面或已有内容组件。
+- 消息提示：用户端没有现成 Toast 组件，当前使用页面提示和错误弹窗。
+
+## 实施决策
+
+1. 不重写应用入口、聊天页面和登录结果处理，只重构 `LoginPanel.vue` 及其局部样式和辅助组件。
+2. 不引入大型 UI 框架；仅使用轻量、可摇树优化的正式图标库，避免 Emoji、自绘 SVG 和静态设计图背景。
+3. 对短信接口做向后兼容扩展：图形验证码字段改为可选。首次正常发送不要求图形验证；同一手机号后续重新发送、验证码连续失败或后端风险状态下返回 HTTP 428，前端再展示图形验证码弹窗。旧客户端继续传入图形验证码时行为不变。
+4. 用户协议和隐私政策使用站内可访问弹窗承载，不创建无效外链。后续如提供正式法律文本，可在不改变登录交互的前提下替换弹窗内容。
+5. 倒计时按手机号写入 `localStorage`，保存发送结束时间；刷新页面或切换手机号后按对应手机号恢复剩余时间。
+6. 帮助入口使用站内弹窗，联系方式从 `VITE_SUPPORT_CONTACT` 读取；未配置时只展示可执行排查步骤，不显示虚假联系方式。
+7. 后端仍保留手机号/IP 限流、验证码错误锁定和学员名单校验，前端按需图形验证码不能绕过发送频率限制。
+
+## 计划修改文件
+
+- `apps/user-client/src/components/LoginPanel.vue`：表单、校验、发送、登录、图形验证、协议和帮助交互。
+- `apps/user-client/src/components/PolicyDialog.vue`：协议与隐私政策弹窗。
+- `apps/user-client/src/components/HelpDialog.vue`：验证码与登录帮助弹窗。
+- `apps/user-client/src/services/api.ts`：保留现有接口路径，增加结构化接口错误和可选图形验证码参数。
+- `apps/user-client/src/styles.css`：登录页主题变量、响应式布局和状态样式。
+- `apps/user-client/package.json`：增加轻量正式图标依赖。
+- `apps/backend/app/schemas/auth.py`、`app/api/auth.py`、`app/services/auth_service.py`：向后兼容的按需图形验证码协议与风险标记。
+- 自动化测试和设计 QA 记录：覆盖接口兼容、倒计时、关键交互和手机尺寸视觉检查。
+
+## 验收口径
+
+- 默认仅显示手机号、短信验证码和安全提示，不常驻图形验证码。
+- 首次短信发送成功后进入 60 秒倒计时；刷新和切换手机号均能正确恢复。
+- 后端要求图形验证时弹出验证窗，验证成功后继续发送并自动关闭。
+- 协议默认不勾选，点击协议文字可查看内容；未同意时不提交登录。
+- 手机号、短信码、加载、网络、超时、错误、重复点击状态均有明确处理。
+- 375、390、414 像素宽度及桌面端不横向溢出、不固定高度截断。
+- 构建、类型检查、后端测试、接口兼容测试和设计 QA 全部通过。