# 用户端手机号登录页正式改造计划与实施记录

## 目标

根据设计图重新实现“大本营答疑助手”手机号验证码登录页。页面采用移动端优先布局，保持简洁、温和、可信的品牌气质，同时完整保留学员名单校验、短信验证码登录、图形验证码和真实错误反馈。

## 现状检查

- 技术栈：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 全部通过。

## 实施结果

1. `808ba74`：短信发送协议向后兼容地支持可选图形验证码；首次发送直接执行，后续发送或风险状态返回 HTTP 428；后端测试增加到 9 项。
2. `2e274de`：重构登录表单、主题样式和 API 错误；新增协议、隐私、帮助和通用弹窗；加入正式图标依赖；完成按手机号持久化倒计时。
3. `fc8a593`：修复 390 像素视口输入容器横向溢出。
4. `dc4b1bf`：持久化最近一次合法手机号，页面刷新后可立即恢复对应倒计时。

## 验证结论

- 375 × 667：无横向溢出，允许自然滚动，主按钮仍位于首屏范围内。
- 390 × 844、414 × 896：登录结构完整，无重叠或截断。
- 1280 × 900：主体宽度固定为 460 像素并水平居中。
- 实测首次发送、倒计时、刷新恢复、按需图形验证、协议拦截、协议弹窗、帮助弹窗、真实登录和退出。
- 浏览器控制台无错误或警告。
- 设计 QA 报告：`design-qa.md`，最终结果为通过。

## 待业务确认

当前用户协议和隐私政策为可正常查看的基础版本。正式法律文本不属于代码推断范围，上线前应由业务或法务确认最终内容；替换文本不需要改变现有交互和接口。
