ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

登录模块审核

Browse Source
This commit is contained in:
Shen Wei
2026-04-30 18:40:55 +08:00
parent 4030a91100
commit 57600598ac
34 changed files with 2544 additions and 2431 deletions
Download Patch File Download Diff File Expand all files Collapse all files

374
Project/fonrey/UI_DESIGN/登录管理/登录_UI.md
View File

@@ -1,239 +1,219 @@
# 登录管理 UI 设计文档
# 登录管理 UI 设计文档（PRD v2.0 对齐）
> **版本**：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 + 会话相关要求）
> **版本**：v2.0 · **日期**：2026-04-30
> **PRD 来源**：`PRD/登录管理/用户登录管理模块PRD.md`（v2.0）
> **数据模型来源**：`DATA_MODEL/DATA_MODEL_LOGIN.md`
> **技术约束来源**：`TECH_STACK/登录管理技术方案.md`
> **技术约束来源**：`TECH_STACK/登录管理技术方案.md`、`AGENTS.md`
---
## 1. 模块概述
## 1. 模块目标与覆盖范围
### 1.1 设计目标（P0）
本次 UI 调整目标：将登录管理相关设计与 PRD v2.0 全面对齐，重点修正以下差异：
本设计文档覆盖 `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 |
> 注：`忘记用户名/忘记密码` 链接在登录页展示；其完整流程页面在后续登录模块增强迭代中展开。
1. 登录页从“单一账号密码登录”升级为**双登录方式 Tab**：
- 手机号 + 密码登录（默认）
- 手机号 + 短信验证码登录
2. 删除“忘记用户名”入口（该流程已废弃）
3. 补齐“重置密码/设置新密码”页面（公共组件，支持两种入口文案）
4. 保留“微信扫码登录（即将开放）”禁用态入口
---
## 2. 视觉与组件基线（对齐 UI System）
## 2. 页面清单（P0）
### 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 字段规范
| 字段 | 组件 | 必填 | 校验 | 数据模型映射 |
| 页面 | 文件 | URL 建议 | 对应 Story/US | 状态 |
|---|---|---|---|---|
| 用户名 | Input | 是 | 1~50 字符；允许字母/数字/下划线（兼容管理员） | `user_accounts.username` |
| 密码 | Password Input | 是 | 非空；提交后后端校验 | `user_accounts.password`（哈希） |
| 验证码通过票据 | 滑块拼图区域 | 是 | 位置偏差 ±5px + 轨迹特征校验 | Redis `captcha_pass:*` |
| 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 | ✅（新增） |
### 3.2.3 主要交互规则
> 注：找回密码 Step1/Step2（手机号+验证码校验）流程在本轮以登录页入口与重置页组件方式完成设计闭环；后续可独立补全完整 Stepper 页面原型。
1. 用户名/密码/验证码三者满足后，“登录”按钮可点击。
2. 点击登录后按钮进入 `loading`，避免重复提交。
3. 登录失败（账号或密码错误）：
- 统一提示 `用户名或密码错误，请重新输入`
- 自动刷新验证码
- 清空密码，保留用户名
4. 验证码失败：提示 `验证码有误，请重新验证`，不计入密码错误次数。
5. 连续密码错误 ≥ 5 次：
- 展示 `账号已被临时锁定，请30分钟后重试`
- 登录按钮禁用
6. 账号停用：提示 `账号已停用，请联系管理员`。
7. Session 过期跳转后，顶部显示提示条：`登录已过期，请重新登录`。
8. 登录成功后，前端跳转到首页路由（本静态原型当前映射为 `./房源列表_UI.html?from=login&login=success`，后续可替换为正式 `/home/`）。
---
### 3.2.4 登录页状态矩阵
## 3. 设计基线（UI System 对齐）
| 状态 | 触发条件 | UI 表现 |
### 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 | 默认 | 字段组成 |
|---|---|---|
| Default | 初始打开 | 空表单 + 新验证码 |
| Captcha Passed | 验证通过 | 验证区绿色对勾 + 文案 |
| Submitting | 点击登录后 | 按钮 spinner，表单禁用 |
| Invalid Credential | 401 | 错误 Alert + 密码清空 |
| Locked | 423/锁定态 | 锁定警示条 + 按钮 disabled |
| Disabled | 账号停用 | 错误提示 + 禁止提交 |
| Session Expired | 过期重定向 | 顶部 warning 条 |
| 密码登录 | ✅ | 手机号 + 密码 + 滑块验证 + 登录 |
| 验证码登录 | - | 手机号 + 滑块验证 + 短信验证码 + 登录 |
### 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/`
---
## 3.3 切换公司确认弹窗（P0 🔴）
## 4.3 设置新密码页（`登录_重置密码_UI.html`）
### 3.3.1 触发入口
本页面是公共组件页面，支持两种业务上下文：
- 登录卡片底部 Link：`切换公司`
| 模式 | 标题 | 提示文案 | 按钮文案 | 提交后行为 |
|---|---|---|---|---|
| `initial`（首次登录强制修改） | 欢迎使用 Fonrey，请先设置您的登录密码 | 您当前使用的是初始密码，为保障账号安全，请立即设置新密码后开始使用 | 确认并进入系统 | 保持 Session，进入首页 |
| `recover`（找回密码步骤三） | 重置您的登录密码 | 请输入您的新密码，设置完成后请使用新密码重新登录 | 确认重置密码 | 使所有 Session 失效，跳转登录页并提示 |
### 3.3.2 弹窗内容
### 字段与校验
- 标题：`切换公司`
- 文案：`切换公司将清除当前租户识别信息，并返回识别页。是否继续？`
- 按钮：`取消`（Secondary）/ `继续切换`（Danger）
- 新密码
- 确认新密码
- 实时强度校验（逐条）：
- 长度 ≥ 8
- 包含字母
- 包含数字
- 一致性校验：两次输入必须一致
### 3.3.3 行为
### 强制约束（initial 模式）
- 确认后：清除本地 tenant 缓存并跳转 `/account/tenant/verify/`
- 取消后：关闭弹窗，不改变当前状态
- 不显示“跳过”
- 不允许返回业务页面
- 页面仅保留密码设置流程
---
## 3.4 会话过期提示（P0 🔴）
## 5. 状态矩阵
- 场景：用户访问业务页时 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/` |
| 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 |
---
## 5. 可访问性与易用性
## 6. 可访问性与实现约束
1. 所有输入框均有可见 Label，不使用仅 placeholder 方案。
2. 错误信息与字段通过 `aria-describedby` 关联。
3. 图标按钮（显示密码、刷新验证码）必须有 `aria-label`。
4. `Tab` 顺序：Tenant ID/用户名 → 密码 → 验证区 → 登录按钮 → 辅助链接。
5. Enter 键：当表单合法时触发提交。
1. 输入框均有 Label，不仅依赖 placeholder
2. 错误文案使用 `aria-describedby` 关联字段
3. 图标按钮（显示密码/刷新验证码）提供 `aria-label`
4. 支持键盘 Tab 顺序与 Enter 提交
5. 静态原型以原生 JS + Alpine 为主，确保 `file://` 可直接评审
---
## 6. 交付物与实现顺序
## 7. 本轮交付与验收清单
1. 本文档：`UI_DESIGN/登录管理/登录_UI.md`（当前）
2. 静态原型：`UI_DESIGN/登录_UI.html`（基于本文档）
3. 评审后迭代：先改 HTML，再回写本 UI 文档
### 交付文件
---
- `UI_DESIGN/登录管理/登录_UI.md`（本文档）
- `UI_DESIGN/登录_UI.html`（Tenant 识别）
- `UI_DESIGN/登录_账号密码_UI.html`（双 Tab 登录）
- `UI_DESIGN/登录_重置密码_UI.html`（新增：公共设置新密码页）
## 7. 验收检查清单（UI 维度）
### 验收项
- [ ] Tenant ID 12 位数字校验与错误提示完整
- [ ] 登录页三要素（用户名/密码/验证码）联动提交规则完整
- [ ] 锁定态、停用态、会话过期态均有明确视觉反馈
- [ ] 切换公司有二次确认弹窗
- [ ] 所有颜色/按钮/输入框样式遵循 UI_SYSTEM Token 与组件规范
- [ ] 静态页可用于你进行第一轮视觉与交互评审
- [ ] 登录页存在“密码登录 / 验证码登录”双 Tab 且可切换
- [ ] Tab 切换后输入与滑块状态已重置
- [ ] 密码登录按手机号校验（11位数字）
- [ ] 验证码登录需先滑块通过才能“获取验证码”
- [ ] “忘记用户名”入口已移除，“忘记密码”入口保留
- [ ] 新增“设置新密码”页面并覆盖 initial/recover 两种上下文
- [ ] 微信扫码登录为禁用“即将开放”态
- [ ] 关键交互无控制台报错