# 登录管理 UI 设计文档（PRD v2.0 对齐）

> **版本**：v2.0 · **日期**：2026-04-30  
> **PRD 来源**：`PRD/登录管理/用户登录管理模块PRD.md`（v2.0）  
> **数据模型来源**：`DATA_MODEL/DATA_MODEL_LOGIN.md`  
> **技术约束来源**：`TECH_STACK/登录管理技术方案.md`、`AGENTS.md`

---

## 1. 模块目标与覆盖范围

本次 UI 调整目标：将登录管理相关设计与 PRD v2.0 全面对齐，重点修正以下差异：

1. 登录页从“单一账号密码登录”升级为**双登录方式 Tab**：
   - 手机号 + 密码登录（默认）
   - 手机号 + 短信验证码登录
2. 删除“忘记用户名”入口（该流程已废弃）
3. 补齐“重置密码/设置新密码”页面（公共组件，支持两种入口文案）
4. 保留“微信扫码登录（即将开放）”禁用态入口

---

## 2. 页面清单（P0）

| 页面 | 文件 | URL 建议 | 对应 Story/US | 状态 |
|---|---|---|---|---|
| Tenant 识别页 | `UI_DESIGN/登录_UI.html` | `/account/tenant/verify/` | Story 1 / US-ACCOUNT-002 | ✅ |
| 登录页（双 Tab） | `UI_DESIGN/登录_账号密码_UI.html` | `/account/login/` | Story 2、Story 5、Story 6(禁用态) | ✅ |
| 设置新密码页（公共组件） | `UI_DESIGN/登录_重置密码_UI.html` | `/account/password/reset/` | Story 3 步骤三 + §5.3.4 | ✅（新增） |

> 注：找回密码 Step1/Step2（手机号+验证码校验）流程在本轮以登录页入口与重置页组件方式完成设计闭环；后续可独立补全完整 Stepper 页面原型。

---

## 3. 设计基线（UI System 对齐）

### 3.1 色彩与组件 Token

- 背景：`neutral-50`
- 主按钮：`primary-600 / 700 / 800`
- 错误提示：`danger-600`
- 成功提示：`success-600`
- 警告提示：`warning-600`
- 卡片：`bg-white + border-neutral-200 + rounded-xl + shadow-lg`

### 3.2 交互组件

- 输入框：Label 在上，错误提示在下
- 密码框：支持显示/隐藏
- 滑块拼图：支持刷新、成功态、失败抖动态
- 登录方式 Tab：默认“密码登录”，切换后清空两侧输入并重置滑块
- CTA 状态：disabled / loading / success 跳转

### 3.3 主题策略

- 本模块静态原型仅提供 Light 模式展示（`data-theme="light"`）
- 不提供主题切换控件

---

## 4. 页面规范

## 4.1 Tenant 识别页（`登录_UI.html`）

### 页面结构

- 左侧：品牌区（Logo、产品价值描述）
- 右侧：Tenant 识别卡片
  - 标题：欢迎使用 Fonrey 房睿
  - 副标题：请输入您公司的专属识别码以继续
  - 字段：公司识别码（12位纯数字）
  - 按钮：确认
  - 错误区：固定高度，避免布局抖动
  - 帮助文案：联系 Tenant Admin 获取识别码

### 校验与状态

- 输入仅保留数字，超长截断为 12 位
- 少于 12 位提交：提示“识别码须为 12 位数字”
- 成功：缓存 tenant 信息并跳转登录页（双 Tab）
- 失败：提示“识别码无效，请联系您的Tenant Admin（租户管理员）获取正确的识别码”
- 网络异常：提示“网络连接失败，请检查网络后重试”

### 接口映射

- `POST /api/auth/tenant/verify/`
- Request：`{ tenant_code }`

---

## 4.2 登录页（`登录_账号密码_UI.html`）

### 顶部信息

- 显示当前租户名：`正在登录：{tenant_name}`
- 提供“切换公司”入口 + 二次确认弹窗
- 可显示 Session 过期提示条

### 登录方式 Tab（核心）

| Tab | 默认 | 字段组成 |
|---|---|---|
| 密码登录 | ✅ | 手机号 + 密码 + 滑块验证 + 登录 |
| 验证码登录 | - | 手机号 + 滑块验证 + 短信验证码 + 登录 |

### Tab 切换规则

- 切换后：
  - 清空当前 Tab 输入
  - 清空错误提示
  - 重置滑块状态
  - 清空短信验证码倒计时状态

### 密码登录（Story 2）

- 手机号：11 位数字，自动过滤非数字
- 密码：必填，显示/隐藏切换
- 滑块：必须先通过
- 登录按钮：三项满足后可点击
- 失败提示：统一“手机号或密码错误，请重新输入”
- 锁定提示：“账号已被临时锁定，请 30 分钟后重试，或联系管理员解锁”
- 停用提示：“账号已停用，请联系您的管理员”

### 验证码登录（Story 5）

- 手机号：11 位数字
- 获取验证码按钮：
  - 需先通过滑块后才可点击
  - 点击后进入 60s 冷却
- 验证码输入：6 位数字
- 登录按钮：手机号 + 验证码均满足后可点击
- 验证失败提示：
  - “验证码有误，请重新输入”
  - 过期：“验证码已过期，请重新获取”

### 其他入口

- 忘记密码（保留）
- 微信扫码登录（即将开放，禁用态）
- 删除“忘记用户名”入口

### 接口映射

- `POST /api/auth/login/`
- `POST /api/auth/login/phone/`
- `POST /api/auth/logout/`
- `POST /api/auth/recover/password/request/`
- `POST /api/auth/recover/password/verify/`
- `POST /api/auth/recover/password/reset/`

---

## 4.3 设置新密码页（`登录_重置密码_UI.html`）

本页面是公共组件页面，支持两种业务上下文：

| 模式 | 标题 | 提示文案 | 按钮文案 | 提交后行为 |
|---|---|---|---|---|
| `initial`（首次登录强制修改） | 欢迎使用 Fonrey，请先设置您的登录密码 | 您当前使用的是初始密码，为保障账号安全，请立即设置新密码后开始使用 | 确认并进入系统 | 保持 Session，进入首页 |
| `recover`（找回密码步骤三） | 重置您的登录密码 | 请输入您的新密码，设置完成后请使用新密码重新登录 | 确认重置密码 | 使所有 Session 失效，跳转登录页并提示 |

### 字段与校验

- 新密码
- 确认新密码
- 实时强度校验（逐条）：
  - 长度 ≥ 8
  - 包含字母
  - 包含数字
- 一致性校验：两次输入必须一致

### 强制约束（initial 模式）

- 不显示“跳过”
- 不允许返回业务页面
- 页面仅保留密码设置流程

---

## 5. 状态矩阵

| 页面 | 状态 | 说明 |
|---|---|---|
| Tenant 识别页 | idle/loading/success/error/network_error | 完整覆盖 Story 1 |
| 登录页-密码 Tab | default/captcha_pass/submitting/credential_error/locked/disabled/session_expired | 完整覆盖 Story 2 |
| 登录页-验证码 Tab | default/captcha_required/otp_sending/otp_countdown/otp_error/otp_expired/submitting | 完整覆盖 Story 5 |
| 设置新密码页 | default/strength_checking/mismatch_error/submitting/success | 覆盖 Story 3 Step3 + §5.3.4 |

---

## 6. 可访问性与实现约束

1. 输入框均有 Label，不仅依赖 placeholder
2. 错误文案使用 `aria-describedby` 关联字段
3. 图标按钮（显示密码/刷新验证码）提供 `aria-label`
4. 支持键盘 Tab 顺序与 Enter 提交
5. 静态原型以原生 JS + Alpine 为主，确保 `file://` 可直接评审

---

## 7. 本轮交付与验收清单

### 交付文件

- `UI_DESIGN/登录管理/登录_UI.md`（本文档）
- `UI_DESIGN/登录_UI.html`（Tenant 识别）
- `UI_DESIGN/登录_账号密码_UI.html`（双 Tab 登录）
- `UI_DESIGN/登录_重置密码_UI.html`（新增：公共设置新密码页）

### 验收项

- [ ] 登录页存在“密码登录 / 验证码登录”双 Tab 且可切换
- [ ] Tab 切换后输入与滑块状态已重置
- [ ] 密码登录按手机号校验（11位数字）
- [ ] 验证码登录需先滑块通过才能“获取验证码”
- [ ] “忘记用户名”入口已移除，“忘记密码”入口保留
- [ ] 新增“设置新密码”页面并覆盖 initial/recover 两种上下文
- [ ] 微信扫码登录为禁用“即将开放”态
- [ ] 关键交互无控制台报错