登录管理 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 页面结构
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 布局结构
3.2.2 字段规范
| 字段 |
组件 |
必填 |
校验 |
数据模型映射 |
| 用户名 |
Input |
是 |
1~50 字符；允许字母/数字/下划线（兼容管理员） |
user_accounts.username |
| 密码 |
Password Input |
是 |
非空；提交后后端校验 |
user_accounts.password（哈希） |
| 验证码通过票据 |
滑块拼图区域 |
是 |
位置偏差 ±5px + 轨迹特征校验 |
Redis captcha_pass:* |
3.2.3 主要交互规则
- 用户名/密码/验证码三者满足后，“登录”按钮可点击。
- 点击登录后按钮进入
loading，避免重复提交。
- 登录失败（账号或密码错误）：
- 统一提示
用户名或密码错误，请重新输入
- 自动刷新验证码
- 清空密码，保留用户名
- 验证码失败：提示
验证码有误，请重新验证，不计入密码错误次数。
- 连续密码错误 ≥ 5 次：
- 展示
账号已被临时锁定，请30分钟后重试
- 登录按钮禁用
- 账号停用：提示
账号已停用，请联系管理员。
- Session 过期跳转后，顶部显示提示条：
登录已过期，请重新登录。
- 登录成功后，前端跳转到首页路由（本静态原型当前映射为
./房源列表_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 触发入口
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. 可访问性与易用性
- 所有输入框均有可见 Label，不使用仅 placeholder 方案。
- 错误信息与字段通过
aria-describedby 关联。
- 图标按钮（显示密码、刷新验证码）必须有
aria-label。
Tab 顺序：Tenant ID/用户名 → 密码 → 验证区 → 登录按钮 → 辅助链接。- Enter 键：当表单合法时触发提交。
6. 交付物与实现顺序
- 本文档：
UI_DESIGN/登录管理/登录_UI.md（当前）
- 静态原型：
UI_DESIGN/登录_UI.html（基于本文档）
- 评审后迭代：先改 HTML，再回写本 UI 文档
7. 验收检查清单（UI 维度）
