zn-ai/LOGIN-README.md

产品需求文档：综合登录系统

1. 文档概述

• 产品名称： 统一认证与登录系统
• 功能模块： 登录页 (Login Page)
• 文档目的： 定义登录功能的详细需求，涵盖账号密码登录、验证码校验、二维码登录及相关的用户体验细节，确保开发实现准确无误。
• 目标用户： 所有需要访问系统权限的注册用户（包括新用户、老用户、遗忘密码用户）。
• 核心目标：
  1. 安全可靠： 保障用户账号安全，防御机器攻击。
  2. 便捷高效： 提供多种登录方式，减少用户操作成本。
  3. 清晰引导： 界面文案清晰，对各类情况给予明确反馈和引导。

2. 功能需求详述

2.1. 账号密码登录（主流程）

• 输入字段：

  • 用户名/邮箱/手机号：
    • 类型：单行输入框。
    • 提示文案(Placeholder): “请输入用户名/邮箱/手机号”。
    • 规则：支持三者之一即可，后端需做兼容判断。前端可做初步格式校验（如邮箱含'@'，手机号为 11 位数字），但最终有效性由后端验证。
  • 密码：
    • 类型：密码输入框（内容默认隐藏）。
    • 提示文案：“请输入密码”。
    • 功能：右侧需提供“眼睛”图标，点击可切换明文/密文显示。
  • 图形验证码：
    • 显示逻辑：非首次输入时触发。为了提高体验，可在用户密码输入框失焦（blur）后、或连续输错 1 次密码后，再出现验证码输入框。
    • 组件：一个输入框 + 一个实时图形验证码图片。
    • 图片：需提供“刷新”图标，点击可无刷新切换新的验证码。图片应清晰可辨，但具备一定的抗机器识别能力。
    • 提示文案：“请输入验证码”。

• 辅助功能：

  • 记住我：
    • 组件：复选框（Checkbox）。
    • 功能：勾选后，下次访问登录页时自动填充用户名（切勿记住密码）。
    • 默认状态：不勾选。
  • 忘记密码：
    • 组件：文字链接。
    • 位置：位于密码框右侧或下方。
    • 功能：点击后跳转至密码找回流程页。

• 主要操作按钮：

  • “登录”按钮：
    • 状态：
      • 默认态：可点击。
      • 加载态：用户点击后，按钮变为禁用状态并显示“登录中...”加载动画，防止重复提交。
    • 功能：触发登录逻辑。

2.2. 二维码登录（便捷流程）

• 切换入口：

  • 在登录框顶部或侧边提供 Tab 页或文字链接，如“账号密码登录” | “二维码登录”，用于切换两种登录方式。

• 二维码显示区域：

  • 初始状态：页面应动态生成一个唯一的二维码（QR Code），并配有文案提示：“请使用【APP 名称】扫描二维码登录”。
  • 自动刷新：该二维码应有时效性（例如 2 分钟）。倒计时在二维码旁可视化显示（如：01:45）。过期后自动刷新生成新的二维码。
  • 手动刷新：提供“刷新”按钮，用户可手动点击更换二维码。

• 登录状态轮询：

  • 一旦二维码生成，前端即开始向后台轮询（Polling）其状态（如每 2 秒一次）。
  • 状态反馈：
    • 待扫描：显示初始状态。
    • 已扫描，待确认：二维码仍显示，下方文案变为“请在手机上确认登录”。
    • 登录成功：轮询停止，前端跳转至登录后页面（或首页）。
    • 过期/失败：二维码区域变灰，显示“二维码已失效”，并自动刷新生成新的二维码。

2.3. 异常与交互流程

• 输入校验（前端 + 后端）：

  • 字段为空：点击登录后，对未填写的必填字段进行红色高亮提示，并显示文案“XXX 不能为空”。
  • 格式错误：在输入框失焦（blur）时即可进行初步校验（如邮箱格式错误），即时提示“邮箱格式不正确”。
  • 验证码错误：提示“验证码错误”，并自动刷新验证码图片。
  • 账号或密码错误：切勿明确提示是“账号错误”还是“密码错误”，统一提示：“用户名或密码错误”，以防黑客枚举用户名。同时，刷新验证码。

• 安全限制：

  • 连续输错密码 N 次（如 5 次）后，除图形验证码外，应触发更严格的验证（如滑块验证、短信验证码）或直接锁定账号一段时间（如 15 分钟），并明确提示用户：“密码错误次数过多，请 15 分钟后再试”。

• 加载与反馈：

  • 任何网络请求都必须有加载状态（如按钮 Loading），防止用户重复操作。
  • 所有错误提示都应清晰、友好，用红色字体在表单项附近或页面顶部固定区域显示。

3. 用户体验（UX）重点

1. 默认焦点： 页面加载后，自动将光标聚焦到“用户名”输入框。
2. 键盘操作： 在最后一项输入框（验证码或密码）按Enter键应触发登录操作。
3. 密码可见性： “眼睛”图标是行业标准，显著降低用户输错密码的概率。
4. 智能验证码： 不要一开始就展示验证码，而是在系统怀疑有风险（如输错一次）时再出现，优化善良用户的体验。
5. 状态反馈： 二维码登录的每种状态（待扫描、已确认、已过期）都必须有明确的视觉和文案反馈，让用户知其所以然。
6. 链路闭环： “忘记密码”和“注册”入口必须清晰可见，为登录失败的用户提供清晰的出路。

4. 非功能性需求

1. 性能： 页面加载速度快，登录接口响应时间应小于 500ms。
2. 安全性：
   • 密码传输必须使用 HTTPS 并加密（如 SHA256 加盐）。
   • 防暴力破解：后端需实施限流策略。
   • Token 管理：登录成功后颁发的 Token 需有有效期并支持刷新机制。
3. 兼容性： 支持主流浏览器（Chrome, Firefox, Safari, Edge）及移动端浏览器。

5. 输出物建议

1. PRD 文档： 即本文档，用于详细阐述逻辑和规则。
2. 线框图（Wireframe）： 绘制登录页的布局，标注各元素和交互点。
3. 高保真原型（High-Fidelity Mockup）： 由 UI 设计师输出，明确视觉样式、颜色、字体等。
4. 交互原型（Interactive Prototype）： 使用 Figma、Axure 等工具制作可点击的原型，演示登录成功、失败、切换等所有流程。