240 lines
10 KiB
Markdown
240 lines
10 KiB
Markdown
# 登录管理 UI 设计文档
|
||
|
||
> **版本**：v1.0 · **日期**：2026-04-27
|
||
> **依赖规范**：`UI_SYSTEM/UI_SYSTEM.md v1.2`、`UI_SYSTEM/组件规范设计.md v1.0`
|
||
> **PRD 来源**：`PRD/登录管理/用户登录管理模块PRD.md`（Story 1、Story 2 + 会话相关要求）
|
||
> **数据模型来源**：`DATA_MODEL/DATA_MODEL_LOGIN.md`
|
||
> **技术约束来源**：`TECH_STACK/登录管理技术方案.md`
|
||
|
||
---
|
||
|
||
## 1. 模块概述
|
||
|
||
### 1.1 设计目标（P0）
|
||
|
||
本设计文档覆盖 `TASK.md` 的登录管理 P0 范围：
|
||
|
||
- **US-ACCOUNT-001**：账号密码登录（含验证码、错误提示、锁定态）
|
||
- **US-ACCOUNT-002**：多租户识别（Tenant ID 识别与切换公司）
|
||
- **US-ACCOUNT-003**：Token/会话超时相关前端状态（过期提示、重新登录入口）
|
||
|
||
### 1.2 页面职责
|
||
|
||
| 页面 | URL 建议 | 优先级 | 对应 US |
|
||
|---|---|---|---|
|
||
| Tenant 识别页 | `/account/tenant/verify/` | P0 🔴 | US-ACCOUNT-002 |
|
||
| 登录页 | `/account/login/` | P0 🔴 | US-ACCOUNT-001 / US-ACCOUNT-003 |
|
||
| 切换公司确认弹窗 | 登录页内 Modal | P0 🔴 | US-ACCOUNT-002 |
|
||
| 会话过期提示态 | 登录页内 Alert/Toast | P0 🔴 | US-ACCOUNT-003 |
|
||
|
||
> 注：`忘记用户名/忘记密码` 链接在登录页展示；其完整流程页面在后续登录模块增强迭代中展开。
|
||
|
||
---
|
||
|
||
## 2. 视觉与组件基线（对齐 UI System）
|
||
|
||
### 2.1 色彩与层级
|
||
|
||
- 页面背景：`bg-neutral-50`
|
||
- 登录主按钮：`bg-primary-600 hover:bg-primary-700 active:bg-primary-800`
|
||
- 错误提示：`text-danger-600`
|
||
- 成功提示：`text-success-600`
|
||
- 卡片容器：`bg-white border border-neutral-200 rounded-xl shadow-lg`
|
||
|
||
### 2.2 组件复用清单
|
||
|
||
| 场景 | 组件规范来源 | 使用说明 |
|
||
|---|---|---|
|
||
| 主/次按钮 | `UI_SYSTEM.md §3.1` | 登录=Primary；刷新验证码/切换公司=Secondary/Link |
|
||
| 输入框/密码框 | `UI_SYSTEM.md §3.2` | 统一 Label 在上、错误提示在下、密码可见切换 |
|
||
| 确认弹窗 | `UI_SYSTEM.md §3.6` | 切换公司二次确认使用 Confirm Modal |
|
||
| Toast 提示 | `UI_SYSTEM.md §3.8` | 网络异常、登录成功/失败统一 Toast 反馈 |
|
||
| 登录页布局模板 | `UI_SYSTEM.md §5.7` | 独立布局，无 Sidebar，品牌区 + 表单区 |
|
||
|
||
### 2.3 主题策略说明
|
||
|
||
依据 `UI_SYSTEM.md §9.1`：**v1 仅 Light 主题**。
|
||
本页面不提供用户可见主题切换按钮，但保留 `data-theme="light"` 扩展点，为后续主题系统接入预留。
|
||
|
||
---
|
||
|
||
## 3. 页面设计规范
|
||
|
||
## 3.1 Tenant 识别页（P0 🔴）
|
||
|
||
### 3.1.1 页面结构
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ 左侧品牌区（Logo + Slogan + 租户价值说明） │
|
||
│ 右侧识别卡片 │
|
||
│ 标题：欢迎使用 Fonrey 房睿 │
|
||
│ 描述：请输入您公司的专属识别码 │
|
||
│ [公司识别码输入框] │
|
||
│ [确认按钮] │
|
||
│ 错误提示区（固定高度，防布局抖动） │
|
||
│ 帮助文案：不知道识别码？请联系管理员 │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.1.2 字段与校验
|
||
|
||
| 字段 | 类型 | 必填 | 规则 |
|
||
|---|---|---|---|
|
||
| Tenant ID | 文本输入（仅数字） | 是 | 固定 12 位；自动 trim；非数字过滤 |
|
||
|
||
### 3.1.3 交互状态
|
||
|
||
| 状态 | 触发 | 视觉反馈 |
|
||
|---|---|---|
|
||
| Idle | 首次进入 | 按钮可点击（输入满足 12 位） |
|
||
| Loading | 点击“确认”后 | 按钮 Loading + 禁用；输入框禁用 |
|
||
| Success | 验证通过 | 展示租户名，自动跳转登录页 |
|
||
| Invalid | Tenant 无效 | 输入框下方红色文案：识别码无效… |
|
||
| Network Error | 请求失败/超时 | 错误提示 + “重试”按钮 |
|
||
|
||
### 3.1.4 API 对齐
|
||
|
||
- `POST /api/auth/tenant/verify/`（PRD）
|
||
- 请求体：`{ tenant_id }`
|
||
- 成功返回：`tenant_name / tenant_logo_url / login_url`
|
||
- 失败返回：`TENANT_NOT_FOUND`
|
||
|
||
---
|
||
|
||
## 3.2 登录页（P0 🔴）
|
||
|
||
### 3.2.1 布局结构
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────┐
|
||
│ 左侧品牌区（租户 Logo / 公司名 / 产品卖点） │
|
||
│ 右侧登录卡片（max-w-md） │
|
||
│ [用户名] │
|
||
│ [密码 + 显示/隐藏] │
|
||
│ [滑块拼图验证区域 + 刷新] │
|
||
│ [登录按钮] │
|
||
│ [忘记用户名] [忘记密码] │
|
||
│ [手机验证码登录（即将开放，禁用）] │
|
||
│ [微信扫码登录（即将开放，禁用）] │
|
||
│ [切换公司]（Link） │
|
||
└────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.2.2 字段规范
|
||
|
||
| 字段 | 组件 | 必填 | 校验 | 数据模型映射 |
|
||
|---|---|---|---|---|
|
||
| 用户名 | Input | 是 | 1~50 字符；允许字母/数字/下划线（兼容管理员） | `user_accounts.username` |
|
||
| 密码 | Password Input | 是 | 非空；提交后后端校验 | `user_accounts.password`（哈希） |
|
||
| 验证码通过票据 | 滑块拼图区域 | 是 | 位置偏差 ±5px + 轨迹特征校验 | Redis `captcha_pass:*` |
|
||
|
||
### 3.2.3 主要交互规则
|
||
|
||
1. 用户名/密码/验证码三者满足后，“登录”按钮可点击。
|
||
2. 点击登录后按钮进入 `loading`，避免重复提交。
|
||
3. 登录失败（账号或密码错误）：
|
||
- 统一提示 `用户名或密码错误，请重新输入`
|
||
- 自动刷新验证码
|
||
- 清空密码，保留用户名
|
||
4. 验证码失败：提示 `验证码有误，请重新验证`，不计入密码错误次数。
|
||
5. 连续密码错误 ≥ 5 次：
|
||
- 展示 `账号已被临时锁定，请30分钟后重试`
|
||
- 登录按钮禁用
|
||
6. 账号停用：提示 `账号已停用，请联系管理员`。
|
||
7. Session 过期跳转后，顶部显示提示条：`登录已过期，请重新登录`。
|
||
8. 登录成功后，前端跳转到首页路由（本静态原型当前映射为 `./房源列表_UI.html?from=login&login=success`，后续可替换为正式 `/home/`）。
|
||
|
||
### 3.2.4 登录页状态矩阵
|
||
|
||
| 状态 | 触发条件 | UI 表现 |
|
||
|---|---|---|
|
||
| Default | 初始打开 | 空表单 + 新验证码 |
|
||
| Captcha Passed | 验证通过 | 验证区绿色对勾 + 文案 |
|
||
| Submitting | 点击登录后 | 按钮 spinner，表单禁用 |
|
||
| Invalid Credential | 401 | 错误 Alert + 密码清空 |
|
||
| Locked | 423/锁定态 | 锁定警示条 + 按钮 disabled |
|
||
| Disabled | 账号停用 | 错误提示 + 禁止提交 |
|
||
| Session Expired | 过期重定向 | 顶部 warning 条 |
|
||
|
||
---
|
||
|
||
## 3.3 切换公司确认弹窗（P0 🔴）
|
||
|
||
### 3.3.1 触发入口
|
||
|
||
- 登录卡片底部 Link：`切换公司`
|
||
|
||
### 3.3.2 弹窗内容
|
||
|
||
- 标题：`切换公司`
|
||
- 文案：`切换公司将清除当前租户识别信息，并返回识别页。是否继续？`
|
||
- 按钮：`取消`（Secondary）/ `继续切换`（Danger）
|
||
|
||
### 3.3.3 行为
|
||
|
||
- 确认后：清除本地 tenant 缓存并跳转 `/account/tenant/verify/`
|
||
- 取消后：关闭弹窗，不改变当前状态
|
||
|
||
---
|
||
|
||
## 3.4 会话过期提示（P0 🔴）
|
||
|
||
- 场景：用户访问业务页时 Session 失效，被重定向回登录页
|
||
- 位置：登录卡片顶部 Alert（warning）
|
||
- 文案：`登录已过期，请重新登录`
|
||
- 可关闭：是（仅隐藏提示，不恢复会话）
|
||
|
||
---
|
||
|
||
## 4. 与数据模型/技术方案映射
|
||
|
||
## 4.1 关键字段映射
|
||
|
||
| UI 关注点 | 数据模型字段/实体 | 说明 |
|
||
|---|---|---|
|
||
| 账号状态 | `user_accounts.status` | `active/disabled/locked` 驱动登录态文案 |
|
||
| 锁定截止时间 | `user_accounts.locked_until` | 锁定倒计时文案来源 |
|
||
| 初始密码标记 | `user_accounts.is_initial_password` | 登录成功后是否强制跳转改密页 |
|
||
| 登录失败计数 | Redis `login_fail:{tenant}:{username}` | 达阈值触发锁定 |
|
||
| 登录审计 | `login_attempts` | 失败原因不在前端细分展示 |
|
||
|
||
## 4.2 API 映射（前端使用）
|
||
|
||
| 目标 | 接口 |
|
||
|---|---|
|
||
| 租户识别 | `/api/auth/tenant/verify/` |
|
||
| 获取验证码 | `/api/account/captcha/generate/` |
|
||
| 校验验证码 | `/api/account/captcha/verify/` |
|
||
| 登录提交 | `/api/account/login/` |
|
||
| 登出 | `/api/account/logout/` |
|
||
|
||
---
|
||
|
||
## 5. 可访问性与易用性
|
||
|
||
1. 所有输入框均有可见 Label，不使用仅 placeholder 方案。
|
||
2. 错误信息与字段通过 `aria-describedby` 关联。
|
||
3. 图标按钮（显示密码、刷新验证码）必须有 `aria-label`。
|
||
4. `Tab` 顺序：Tenant ID/用户名 → 密码 → 验证区 → 登录按钮 → 辅助链接。
|
||
5. Enter 键：当表单合法时触发提交。
|
||
|
||
---
|
||
|
||
## 6. 交付物与实现顺序
|
||
|
||
1. 本文档：`UI_DESIGN/登录管理/登录_UI.md`（当前）
|
||
2. 静态原型：`UI_DESIGN/登录_UI.html`（基于本文档）
|
||
3. 评审后迭代：先改 HTML，再回写本 UI 文档
|
||
|
||
---
|
||
|
||
## 7. 验收检查清单（UI 维度）
|
||
|
||
- [ ] Tenant ID 12 位数字校验与错误提示完整
|
||
- [ ] 登录页三要素（用户名/密码/验证码）联动提交规则完整
|
||
- [ ] 锁定态、停用态、会话过期态均有明确视觉反馈
|
||
- [ ] 切换公司有二次确认弹窗
|
||
- [ ] 所有颜色/按钮/输入框样式遵循 UI_SYSTEM Token 与组件规范
|
||
- [ ] 静态页可用于你进行第一轮视觉与交互评审
|