修改文档

2026-04-28 07:34:37 +08:00
parent 3224ec4787
commit cf4001c4f8
16 changed files with 1489 additions and 171 deletions
--- a/Project/fonrey/UI_DESIGN/登录管理/登录_UI.md
+++ b/Project/fonrey/UI_DESIGN/登录管理/登录_UI.md
@@ -0,0 +1,239 @@
+# 登录管理 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 与组件规范
+- [ ] 静态页可用于你进行第一轮视觉与交互评审