Files

Shen Wei ca33cc141f 文档更新

2026-05-02 11:35:20 +08:00

42 KiB

Raw Blame History

PRD：用户登录管理模块

状态: Draft
作者: 产品经理
最后更新: 2026-05-02（v3.0 按 ADR-20260502-003 重写：剥离全部实现细节——具体 API 路径、HTTP 方法、JSON Schema、Redis Key、字段类型、Electron API 名、Cookie 属性、限流接口实现等——交由 Tech / DATA_MODEL 承接；本文件只保留业务能力、页面与导航、业务规则、状态机、验收标准）
版本: 3.0
所属系统: Fonrey 房产经纪管理系统
关联模块: 组织人事管理、权限管理、平台管理后台

关联文档（实现口径）

实现细节（端点路径、HTTP 方法、JSON Schema、错误码、滑块/OTP 算法、限流策略、Electron 客户端约定）：TECH_STACK/登录管理技术方案.md（v4.1）
数据结构（账号表、登录审计表、短信 OTP 表、历史密码表、Redis Key 命名、字段类型与索引）：DATA_MODEL/DATA_MODEL_LOGIN.md
全局 API 契约（统一错误响应、分页、限流外显规范）：TECH_STACK/API_CONTRACT.md
测试用例：TEST_CASES/TEST_CASES_LOGIN_MODULE.md

本 PRD 涉及的"具体路径 / 字段名 / Token TTL 数值 / Cookie 属性 / Redis Key / 框架 API 名"等实现口径，均不在本文件出现，请按上表查阅对应权威文档。

变更历史

版本	日期	作者	变更说明
v1.x	—	产品经理	初稿至 v1.9（详见 git 历史）
v2.0	2026-04-30	产品经理	根据 review 后的 §4 用户故事全面同步 §5 功能详细说明：删除找回用户名流程及邮件模板；找回密码改为纯短信流程；新增 §5.5 手机验证码登录详细说明；§6 技术注意事项更新短信依赖/风险/开放问题；§8.2 接口清单同步正式功能状态；全文「Tenant ID」对外概念统一替换为「Tenant Code」
v3.0	2026-05-02	Sisyphus	按 `ADR-20260502-003` 重写：剥离全部实现细节交由 Tech / DATA_MODEL 承接；删除 §5.1.4 接口规范代码块、§5.2.2 Redis Key 与传输层细节、§5.3.3 字段类型表、§5.6 数据模型字段清单、§5.7 Electron 客户端约定、§6.1 依赖技术选型表、§6.2 多租户实现细节、§8.2 接口清单汇总；保留页面/导航/业务规则/状态机/验收标准；具体口径全部以 `TECH_STACK/登录管理技术方案.md` 为准

1. 问题陈述

1.1 背景

Fonrey 是一套面向房产经纪公司的 B2B SaaS 平台，采用多租户架构，每家经纪公司是一个独立租户。终端用户通过 Windows 桌面客户端（Electron 壳应用） 使用系统，无需手动输入网址即可打开 Web 应用。

在多租户环境下，用户的身份验证流程比单租户系统更复杂：

用户安装客户端后，系统必须先识别当前设备归属哪个租户，才能加载对应租户的登录界面和数据隔离环境
每家经纪公司作为独立租户，其员工账号、组织结构、数据均完全隔离
经纪人账号须与实名员工档案绑定，确保每一条操作记录可追溯至具体自然人
现阶段登录方式以账号密码与手机验证码为主；微信扫码登录需预留入口，待移动端（小程序）上线后实现

1.2 核心痛点

痛点	影响方	当前代价
多租户环境下，客户端不知道应该连接哪个租户的服务端	新用户首次安装后无法正常使用	系统无法启动，用户体验极差
账号密码裸露登录，缺乏验证码保护	所有用户	存在暴力破解、自动化恶意登录风险
用户忘记密码无自助找回通道	Agent（经纪人）	依赖管理员手动重置，效率低
账号未与实名经纪人档案绑定	Tenant Admin（租户管理员）、合规审计	操作行为无法追溯至自然人
无多因素认证，安全系数低	管理层、数据合规	存在账号冒用、数据泄露风险

1.3 目标用户

角色	描述	使用频率
Agent（经纪人）	每日登录系统使用房源/客源功能	每日高频
店长 / 经理	登录后查看全店数据、管理任务	每日
Tenant Admin（租户管理员）	管理账号创建、密码重置、租户初始化	按需
新安装用户	首次安装客户端后需完成 Tenant 识别	一次性

2. 目标与成功指标

目标	指标	当前基准	目标值	衡量周期
降低登录失败率	账号密码正确情况下的登录成功率	待统计	≥ 99%	上线后 30 天
防止恶意登录	每日验证码拦截异常登录请求数	0（无保护）	建立基线，对同 IP 异常突增触发封锁	上线后持续监控
提升找回账号效率	用户自助找回密码耗时	依赖管理员（约 1 工作日）	< 3 分钟（短信验证码自助）	上线后 30 天
确保账号实名绑定率	拥有系统账号且未与员工档案绑定的账号比例	待统计	0%（强制绑定）	上线即达标
Tenant 识别成功率	首次安装后成功完成 Tenant 识别的用户比例	待统计	≥ 98%	上线后 30 天

具体的同 IP 限流阈值与 Tenant Code 校验频控数值，详见 TECH_STACK/登录管理技术方案.md。

3. 非目标（本期不做）

微信扫码登录：移动端小程序上线后实现，本期仅在登录页保留禁用入口，不开放实际功能
单点登录（SSO）/ 企业微信集成：后续版本规划
多设备并发登录的强制踢出策略：本期允许同账号多端登录，后续安全策略模块规划
登录时段限制 / IP 白名单：安全策略模块另行规划
平台管理后台（Platform Admin）登录：属于平台管理后台模块，本 PRD 专注租户内用户登录
找回用户名流程：普通员工用户名固定为手机号，无需找回；Tenant Admin 如忘记用户名请联系平台运营线下处理（原 Story 4 已废弃）

4. 页面清单与导航

本节描述用户视角的页面与跳转关系；具体的前端路由实现与 URL 形态由 TECH_STACK/登录管理技术方案.md 定义。

4.1 页面清单

页面	访问权限	用途
Tenant 识别页	公开（无需登录）	客户端首次启动或切换公司时输入租户识别码
登录页	公开（需先完成 Tenant 识别）	提供「密码登录」/「验证码登录」两种方式，含微信扫码禁用入口
找回密码页（三步）	公开	输入手机号 → 输入短信验证码 → 设置新密码
首次登录强制改密页	已登录且账号处于初始密码状态	强制用户修改初始密码后方可使用系统
系统首页	已登录且非初始密码状态	业务入口；不在本 PRD 范围

4.2 导航流程

[客户端启动]
   │
   ├─ 本地无 Tenant 缓存 ──→ [Tenant 识别页]
   │                              │ 验证成功
   │                              ↓
   │                        缓存 Tenant ──→ [登录页]
   │
   └─ 本地有 Tenant 缓存 ──→ [登录页]

[登录页]
   │
   ├─ 密码 / 验证码登录成功
   │      │
   │      ├─ 账号为"初始密码"状态 ──→ [首次登录强制改密页] ──改密成功──→ [系统首页]
   │      └─ 账号为"非初始密码"状态 ──→ [系统首页]
   │
   ├─ 点击"忘记密码" ──→ [找回密码页（步骤一）] → [步骤二] → [步骤三] ──→ 回 [登录页]
   │
   └─ 点击"切换公司"（二次确认）──→ 清缓存 ──→ [Tenant 识别页]

[系统内]
   │
   ├─ 主动登出 ──→ [登录页]
   ├─ Session 过期 ──→ [登录页]（提示"登录已过期，请重新登录"）
   └─ 客户端版本过低 ──→ [更新提示页] → 阻断后续登录流程

5. 用户故事与验收标准

Story 1：新用户首次启动客户端——Tenant 识别

As 新安装 Fonrey 客户端的经纪人，I want 在首次启动时输入所属公司的 12 位 Tenant Code 完成租户识别，So that 客户端能连接到正确的服务端，后续显示对应公司的登录界面和数据。

验收标准：

客户端首次启动时（本地无 Tenant Code 缓存），自动呈现「Tenant 识别」页面，而非直接显示登录页
页面包含：产品 Logo、产品名称「Fonrey 房睿」、说明文案「请输入您公司的专属识别码」、Tenant Code 输入框、「确认」按钮、帮助文案「不知道识别码？请联系您公司的Tenant Admin（租户管理员）」
Tenant Code 输入框支持粘贴操作，自动去除前后空格，仅接受数字字符（非数字自动过滤），固定 12 位
点击「确认」后展示加载状态（spinner），由客户端向服务端发起 Tenant 验证
验证成功：服务端返回租户名称及品牌信息（公司名称、Logo 等）；客户端将 Tenant Code 持久化到本地（必须加密存储），自动跳转至该租户的登录页；登录页顶部展示「正在登录：XX 房产」
验证失败（识别码无效）：输入框下方显示红色错误提示「识别码无效，请联系您的 Tenant Admin（租户管理员）获取正确的识别码」；Tenant Code 不写入本地缓存；用户可重新输入
网络异常：显示「网络连接失败，请检查网络后重试」，提供「重试」按钮
非首次启动（本地已有合法 Tenant Code 缓存）：直接跳过识别页，进入登录页
登录页提供「切换公司」入口（链接文字，非主要 CTA），点击后弹出二次确认「切换公司将退出当前账号，是否继续？」，确认后清除本地 Tenant Code 缓存并重新显示 Tenant 识别页
Tenant 验证为公开操作，无需登录态，但平台需对该接口做防枚举的频控保护（具体阈值见 Tech 文档）

Tenant Code 业务规则：

格式：12 位纯数字
生成：由平台运营在平台管理后台开通租户时自动生成，全局唯一，不允许手动指定
唯一性：全局唯一，同一 Tenant Code 不得分配给多个租户
客户端存储：必须加密落盘，禁止明文（实现细节见 Tech 文档 §十三 Electron 客户端约定）

Story 2：经纪人通过手机号和密码登录

As 已识别租户的经纪人，I want 通过手机号和密码完成登录，So that 进入系统开始工作。

说明：普通员工的登录账号即为其手机号（由 Tenant Admin 在新增员工时自动创建），无需记忆额外用户名。Tenant Admin 账号的登录名为该租户联系人手机号，规则一致。

验收标准：

登录页展示：租户品牌标识（公司 Logo + 公司名称）、登录方式 Tab（「密码登录」/「验证码登录」，默认选中「密码登录」）、手机号输入框、密码输入框、滑块拼图验证区域、「登录」按钮、「忘记密码」链接、「切换公司」入口、微信扫码禁用入口
手机号输入框 Placeholder：「请输入您的手机号」；仅接受数字字符（非数字自动过滤），固定 11 位
密码输入框默认密文显示，右侧提供「显示/隐藏」图标切换明密文
行为验证码（滑块拼图）：展示一张带缺口的背景图和一块可拖动的拼图碎片，用户通过拖动滑块将碎片移动至缺口位置完成验证；无需输入任何字符
验证失败（位置不准或轨迹异常）：拼图区域抖动提示，自动刷新新背景图，用户重新拖动；不计入账号密码错误次数
验证成功后，拼图区域显示绿色对勾 + 「验证通过」文案，状态持续至本次登录提交完成
提供「刷新」图标按钮，允许用户主动刷新背景图
三项（手机号、密码、滑块）均完成后，「登录」按钮才可点击（否则置灰）
点击「登录」触发前端格式校验：
- 手机号为空 → 提示「请输入手机号」
- 手机号不满 11 位 → 提示「请输入完整的 11 位手机号」
- 密码为空 → 提示「请输入密码」
- 滑块未完成 → 提示「请完成滑块验证」
格式校验通过后提交登录，按钮进入 loading 状态防止重复提交
登录成功：
- 若账号处于"非初始密码"状态：直接进入系统首页，顶部显示欢迎信息「欢迎回来，{姓名}」
- 若账号处于"初始密码"状态：立即跳转至「首次登录强制改密页」，不可关闭、不可跳过、不可访问其他功能页面（详见 §6.4）
登录失败（手机号或密码错误）：显示「手机号或密码错误，请重新输入」（不区分具体原因，防止枚举攻击）；滑块自动刷新；密码输入框清空；手机号保留
登录失败（滑块异常）：显示「验证码有误，请重新输入」；滑块自动刷新
账号被锁定（同一账号密码连续错误达到上限）：显示「账号已被临时锁定，请稍后再试，或联系管理员解锁」；锁定状态下「登录」按钮置灰
账号已停用：显示「账号已停用，请联系您的管理员」
Session 过期：用户在系统内操作时 Session 过期，自动跳转至登录页，并提示「登录已过期，请重新登录」

业务规则（具体数值口径见 Tech 文档）：

同一账号密码连续错误达到上限后，账号进入临时锁定状态，到期自动解锁；管理员可手动解锁
滑块验证失败不计入密码错误次数
所有登录请求强制 HTTPS

Story 3：经纪人找回密码

As 忘记密码的经纪人，I want 通过手机号 + 短信验证码完成身份核验，重新设定密码，So that 无需邮箱、无需联系管理员，独立完成密码重置。

说明：考虑到大多数经纪人没有常用邮箱，本期找回密码统一通过短信验证码实现，废弃邮箱找回方式。账号中邮箱字段在本系统无任何必须业务用途，完全可选。

验收标准：

点击登录页「忘记密码」链接，跳转至「找回密码」流程（分三步）

步骤一：输入手机号

页面显示：手机号输入框（11 位数字，自动过滤非数字）、「获取验证码」按钮、「返回登录」链接
手机号为空或不足 11 位 → 点击「获取验证码」时输入框下方提示「请输入完整的 11 位手机号」
手机号格式合法后，点击「获取验证码」，按钮进入 60 秒倒计时冷却态（「重新获取(59s)」），倒计时结束后按钮恢复可点击
不论该手机号是否注册，前端文案统一显示「如该手机号已注册，验证码将在 1 分钟内发送」（不泄露账号是否存在）
后台仅在手机号存在且账号处于可用状态时实际发送短信
同一手机号在一段时间窗口内发送次数有上限，超限后提示「发送次数过多，请稍后再试」
短信内容模板：「【Fonrey 房睿】您的密码重置验证码为 {code}，10 分钟内有效，请勿泄露。」

步骤二：输入短信验证码

页面显示：6 位验证码输入框（支持分格输入）、「重新发送」倒计时链接、「下一步」按钮
「下一步」按钮：6 位验证码全部输入后方可点击
校验结果：
- 正确且未过期 → 进入步骤三
- 错误 → 提示「验证码有误，请重新输入」；同一验证码连续错误达到上限后作废，需重新获取
- 已过期 → 提示「验证码已过期，请重新获取」

步骤三：重置密码

步骤三依赖步骤二颁发的一次性凭证；凭证无效或过期 → 显示「操作已超时，请重新发起找回密码」，跳回步骤一
本页面复用「设置新密码」公共组件（与首次登录强制改密页为同一组件，详见 §6.4），保持 UI 与交互逻辑完全一致；入口上下文不同时，仅页面标题与提示文案差异：

元素	首次登录强制改密（§6.4）	找回密码步骤三（本 Story）
页面标题	「欢迎使用 Fonrey，请先设置您的登录密码」	「重置您的登录密码」
提示文案	「您当前使用的是初始密码，为保障账号安全，请立即设置新密码后开始使用」	「请输入您的新密码，设置完成后请使用新密码重新登录」
提交按钮文案	「确认并进入系统」	「确认重置密码」
提交后跳转	Session 保持，直接进入首页	该账号所有 Session 立即失效，跳转登录页并提示「密码已重置，请使用新密码登录」

提交成功后：账号"初始密码"标记置为否（找回密码属于用户主动操作，已完成身份核验，不应再触发首次登录强制改密流程）

Story 4：经纪人找回用户名（已废弃）

状态：已废弃。普通员工用户名固定为手机号，无需找回；Tenant Admin 如忘记用户名请联系平台运营线下处理。本 Story 保留占位以维持版本记录，实现时跳过。

Story 5：手机验证码登录（MVP 实现）

As 已有账号的经纪人，I want 通过手机号 + 短信验证码直接登录，So that 在忘记密码或不想输入密码时，仍能快速进入系统。

说明：短信能力在 Story 3 找回密码中已建设完成，本 Story 复用。登录页提供「密码登录」和「验证码登录」两个并列 Tab，用户自由切换，两种方式均为 MVP 正式功能。

验收标准：

登录页提供两种登录方式的切换 Tab：「密码登录」（默认选中）和 「验证码登录」
切换 Tab 时，输入区域平滑切换，已填内容清空，滑块验证状态重置

「验证码登录」界面元素：

手机号输入框（规格同 Story 2，11 位数字）
验证码输入框（6 位数字分格输入）+ 「获取验证码」按钮（60 秒倒计时冷却态）
滑块拼图验证区域（规格同 Story 2，先通过滑块验证，再允许点击「获取验证码」）
「登录」按钮（手机号 + 验证码均填写后方可点击）

获取验证码逻辑：

用户须先完成滑块验证，「获取验证码」按钮方可点击；未完成滑块时点击 → 提示「请先完成滑块验证」
手机号格式不合法 → 前端拦截，提示「请输入完整的 11 位手机号」
不论手机号是否注册，前端文案统一显示「如该手机号已注册，验证码将在 1 分钟内发送」（防止枚举攻击）
后台仅在手机号存在且账号处于可用状态时实际发送短信
同一手机号在一段时间窗口内的发送次数有上限（与找回密码独立计数，互不共享）；超限后提示「发送次数过多，请稍后再试」
短信内容模板：「【Fonrey 房睿】您的登录验证码为 {code}，5 分钟内有效，请勿泄露。」

登录校验逻辑：

校验结果：
- 正确且未过期 → 登录成功，后续行为与 Story 2 密码登录完全一致（含初始密码状态判断）
- 错误 → 提示「验证码有误，请重新输入」；连续错误达到上限 → 本次验证码作废，提示「验证码已失效，请重新获取」
- 已过期 → 提示「验证码已过期，请重新获取」
账号被锁定（密码登录失败次数触发）：验证码登录仍受账号锁定限制，锁定期间无法通过任何方式登录，提示与 Story 2 一致

设计说明：账号锁定是账号维度的安全策略，不区分登录方式；否则锁定形同虚设。
账号已停用：提示「账号已停用，请联系您的管理员」

Story 6：预留——微信扫码登录（v2 实现）

As 绑定了微信账号的经纪人，I want 在登录页扫描微信二维码完成登录，So that 免去输入账号密码的步骤，提升登录体验。

当前状态：

本期登录页 UI 入口以「即将开放」禁用态展示，不提供任何可点击的实际功能
后端服务端在 MVP 中不开放微信相关接口，相关端点仅占位规划，详见 Tech 文档 §5.4
v2 实现时的业务前置要求：
- 微信账号必须先在「个人设置」中与系统账号完成绑定
- 二维码有效期 3 分钟，过期后前端自动刷新二维码
- 同一微信账号在同一租户内只能绑定一个系统账号

6. 业务规则与功能详细说明

6.1 客户端 Tenant 识别业务流程

客户端启动
    │
    ├─ 本地有 Tenant Code 缓存？
    │       │
    │      YES ──→ 复核缓存 Tenant Code 是否仍有效
    │                   │
    │                  有效 ──→ 直接进入登录页
    │                   │
    │                 无效 ──→ 清除缓存，进入 Tenant 识别页
    │
    └─ NO ──→ 显示 Tenant 识别页
                   │
               用户输入 Tenant Code → 发起验证
                   │
              验证成功 ──→ 缓存 Tenant Code → 进入登录页
                   │
              验证失败 ──→ 显示错误信息，保持识别页

Tenant 识别页规范

元素	规格
页面背景	品牌色渐变（与登录页保持一致的视觉风格）
Logo	Fonrey 产品 Logo，居中显示
标题	「欢迎使用 Fonrey 房睿」
副标题	「请输入您公司的专属识别码以继续」
Tenant Code 输入框	单行数字输入，固定 12 位，支持粘贴；非数字字符自动过滤，超出 12 位截断
输入框 Label	「公司识别码（Tenant Code）」
确认按钮	主色调按钮，文字「确认」
错误提示	输入框下方红色文字，固定区域占位（不影响布局抖动）
帮助文案	「不知道识别码？请联系您公司的Tenant Admin（租户管理员）」

Tenant 验证接口的具体路径、请求/响应 Schema、限流阈值与 Schema 隔离实现：见 TECH_STACK/登录管理技术方案.md §5.3.1 与 §三。

6.2 登录页设计规范

6.2.1 页面布局

登录页顶部以 Tab 切换 区分两种登录方式（「密码登录」默认选中），Tab 下方的表单区随当前选中 Tab 动态切换；微信扫码作为独立的「其他登录」保持禁用。

┌─────────────────────────────────────────┐
│  [租户 Logo]  [租户公司名称]              │  ← 顶部品牌区（Tenant 识别后回填）
│                                         │
│  ┌──────────────┬──────────────────┐    │
│  │  密码登录 ✓  │   验证码登录      │    │  ← 登录方式 Tab，默认选中「密码登录」
│  └──────────────┴──────────────────┘    │
│                                         │
│  ── 密码登录 Tab（默认展示）───────────  │
│         ┌───────────────────────┐       │
│         │  手机号               │       │
│         └───────────────────────┘       │
│         ┌───────────────────────┐       │
│         │  密码              👁  │       │
│         └───────────────────────┘       │
│   ┌─────────────────────────────────┐   │
│   │ [背景图 + 拼图缺口]          🔄 │   │  ← 右上角刷新图标
│   │ [拼图碎片]  ◀ 拖动滑块完成拼图 ▶│   │
│   └─────────────────────────────────┘   │
│         ┌───────────────────────┐       │
│         │       登  录           │       │  ← 主 CTA，橙色
│         └───────────────────────┘       │
│  忘记密码                               │  ← 文字链接（忘记用户名入口已废弃）
│                                         │
│  ── 验证码登录 Tab（切换后展示）────────  │
│         ┌───────────────────────┐       │
│         │  手机号               │       │
│         └───────────────────────┘       │
│   ┌─────────────────────────────────┐   │
│   │ [拼图验证]  ← 先完成验证，再获取 │   │  ← 验证码登录下滑块前置
│   └─────────────────────────────────┘   │
│   ┌──────────────────┐ ┌─────────────┐  │
│   │ 验证码（6 位）   │ │ 获取验证码  │  │  ← 通过滑块后按钮可点击；60s 冷却
│   └──────────────────┘ └─────────────┘  │
│         ┌───────────────────────┐       │
│         │       登  录           │       │
│         └───────────────────────┘       │
│  忘记密码                               │
│                                         │
│  ─────────────── 其他登录 ──────────────│
│  [微信扫码登录 - 即将开放]               │  ← 禁用态，灰色
│                                         │
│  切换公司                               │  ← 底部，小字链接
└─────────────────────────────────────────┘

6.2.2 安全机制（业务视角）

机制	业务规则
验证码类型	滑块拼图行为验证码：用户拖动碎片至缺口完成验证，无需输入字符
验证判定	综合位置精度与滑动轨迹特征判断是否为人类行为；具体容差与算法见 Tech 文档
背景图来源	预置图库随机抽取，缺口位置每次随机生成，防止固定模式被预测
验证失败处理	拼图区域抖动提示，自动刷新新背景图；不计入账号密码错误次数
密码错误锁定	同一账号连续密码错误达到阈值后自动锁定，到期自动解锁；管理员可手动解锁
验证码刷新	登录失败后自动刷新拼图；用户亦可主动点击「刷新」图标
传输安全	所有登录相关请求强制 HTTPS，不允许 HTTP 降级
会话有效期	默认按工作日单日使用场景设定；可由 Tenant Admin 在「系统设置」中调整

滑块容差像素值、密码错误次数阈值、锁定时长、Session 默认时长、密码哈希算法、登录失败计数存储位置等实现口径，统一由 TECH_STACK/登录管理技术方案.md §六、§七、§八定义；本 PRD 不重复。

6.3 账号与员工实名绑定规范

6.3.1 绑定原则

每个系统登录账号必须与「组织人事管理」模块中的一条**员工档案（Staff）**绑定
账号与员工是 1:1 关系，一个员工对应一个账号，一个账号只能绑定一个员工
不支持用户自行注册，所有账号均由有权限的管理角色创建

6.3.2 账号创建权限分层

系统内共有两类账号创建场景，权限和规则各不相同：

① Tenant Admin 账号（每个租户的超级管理账号）

项目	业务规则
创建时机	平台运营在平台管理后台开通租户时，系统自动以该租户联系人手机号创建 Tenant Admin 账号，无需手动设置
用户名	固定为该租户联系人的手机号（11 位数字），全局唯一，创建后不可更改
初始密码	系统统一固定初始密码（由平台运营在系统配置中设定），与普通员工相同
首次登录	强制修改初始密码，不可跳过
权限范围	拥有该租户内最高权限，可管理员工账号、角色、系统设置等
数量限制	每个租户仅限 1 个 Tenant Admin 账号（v2 可扩展为多管理员）
数据来源	联系人手机号在开通租户时由平台运营录入，必填

② 普通员工账号（经纪人、店长、行政等）

项目	业务规则
创建时机	Tenant Admin 在「组织人事管理 → 新增员工」时，系统自动为该员工创建登录账号
用户名	固定为该员工的手机号（11 位数字），同租户内唯一，创建后不可更改
初始密码	系统统一固定初始密码（与 Tenant Admin 共用同一配置）
首次登录	强制修改初始密码，不可跳过（详见 §6.4）
密码重置	Tenant Admin 可在员工管理界面对任意员工账号执行「重置密码」，重置后恢复为固定初始密码，触发首次登录强制改密流程
账号禁用	员工离职或被停用时，对应账号自动禁用；禁用账号无法登录，历史操作记录保留

6.3.3 账号字段语义（业务视角）

字段	Tenant Admin	普通员工	业务说明
用户名	联系人手机号	员工手机号	登录 ID，创建后不可更改
密码	系统统一初始密码	系统统一初始密码	必须安全哈希存储；首次登录强制修改
手机号	必填，同时作为用户名	必填，同时作为用户名	用于密码登录与短信验证码登录；存储须加密
邮箱	选填	选填	在本系统无必须业务用途，完全可选
员工档案关联	可选关联	必须关联	实名绑定
账号状态	active / disabled / locked	active / disabled / locked	locked 为密码错误锁定，到期自动恢复
初始密码标记	是 / 否	是 / 否	为"是"时登录成功后强制跳转改密页
创建人	平台运营	Tenant Admin	审计追溯

字段类型、字段名、表名、索引、跨 App 依赖、Migration 顺序等实现口径，全部以 DATA_MODEL/DATA_MODEL_LOGIN.md 为唯一权威。

6.4 首次登录强制修改密码

新员工账号创建后，账号处于「初始密码」状态
员工使用手机号 + 固定初始密码登录成功后，系统立即跳转至「首次登录强制改密页」，不可关闭、不可跳过，任何其他系统功能页面均不可访问
Tenant Admin 对员工账号执行「重置密码」后，账号重新进入「初始密码」状态，该员工下次登录时再次触发强制改密流程
修改成功后，账号脱离「初始密码」状态，原 Session 保持有效，直接进入系统首页

首次登录强制改密页规范：

元素	规格
页面标题	「欢迎使用 Fonrey，请先设置您的登录密码」
提示文案	「您当前使用的是初始密码，为保障账号安全，请立即设置新密码后开始使用」
新密码输入框	密文显示，右侧「显示/隐藏」切换
确认新密码输入框	密文显示，与新密码一致性实时校验
密码强度提示	逐条实时显示规则达标状态（✓/✗）：长度 ≥ 8 位 / 包含字母 / 包含数字
提交按钮	「确认并进入系统」
不可操作项	无「跳过」按钮；顶部导航栏、侧边菜单、关闭按钮均禁用

历史密码校验范围、密码强度算法等实现细节见 Tech 文档与 DATA_MODEL_LOGIN.md 中历史密码记录表设计。

6.5 找回密码业务流程

实现细节（一次性凭证 TTL、OTP 有效期、错误次数阈值、限流计数策略）见 TECH_STACK/登录管理技术方案.md §6.3 与 §七。

用户点击「忘记密码」
    │
步骤1：输入手机号
    │
    ├─ 输入 11 位手机号，点击「获取验证码」
    │       │
    │   前端文案统一为「如该手机号已注册，验证码将在 1 分钟内发送」（防止枚举）
    │       │
    │   后台：手机号存在且账号可用 → 生成 OTP → 发送短信
    │         不存在或已停用 → 静默处理
    │
步骤2：输入短信验证码
    │
    ├─ 输入 6 位验证码，点击「下一步」
    │       │
    │   正确且未过期 → 颁发一次性凭证 → 进入步骤3
    │   错误（次数未到上限）→ 提示「验证码有误，请重新输入」
    │   错误（达到上限）→ 提示「验证已失败，请重新获取验证码」，本次 OTP 作废
    │   已过期 → 提示「验证码已过期，请重新获取」
    │
步骤3：重置密码
    │
    ├─ 服务端校验一次性凭证有效性
    │       │
    │   无效/过期 → 提示「操作已超时，请重新发起找回密码」，跳回步骤1
    │
    ├─ 用户输入新密码 + 确认新密码，实时逐条校验复杂度规则（✓/✗）
    │
    └─ 提交成功
            → 更新密码，账号脱离「初始密码」状态
            → 清除该账号所有有效 Session（强制重新登录）
            → 跳转登录页，提示「密码已重置，请使用新密码登录」

6.6 手机验证码登录（业务规则补充）

本节为 Story 5 的业务规则补充。短信能力在 Story 3 找回密码中已建设完成，本节描述在登录场景下复用时的关键业务差异点。

与找回密码短信逻辑的业务差异对比：

维度	找回密码（Story 3）	验证码登录（Story 5）
业务场景	密码重置	登录认证
OTP 有效期	较长	较短
每小时发送上限	较低	较高
验证成功后动作	颁发一次性凭证 → 步骤三重置密码	直接登录成功
短信文案	「密码重置验证码」	「登录验证码」
账号锁定影响	不受密码错误锁定限制（非密码登录路径）	受账号锁定限制（账号维度安全策略，不区分方式）

各项数值（OTP 时长、每小时上限）口径见 TECH_STACK/登录管理技术方案.md §6.3、§6.4、§七。

滑块验证前置规则（验证码登录特有）：

用户须先完成滑块拼图验证，「获取验证码」按钮方可点击
滑块验证通过后，拼图区域保持「验证通过」状态，不需要在点击「登录」前再次验证
切换 Tab 时，滑块验证状态重置（须重新完成验证后方可获取验证码）

短信记录复用说明：

不新建表，复用 DATA_MODEL_LOGIN.md 中定义的短信验证码记录表
通过场景字段区分"登录"与"密码重置"，各自独立限流计数
同一手机号同一场景同一时间只有一条有效 OTP；新发送时将旧记录置为失效

6.7 后端数据模型

数据模型已迁移至独立文档，请参阅：DATA_MODEL/DATA_MODEL_LOGIN.md

该文档包含：

账号主表（完整字段定义、约束、索引）
登录审计表
短信验证码记录表（找回密码 + 验证码登录共用）
历史密码记录表
Redis 缓存结构说明
账号状态机与创建流程
与 org.Staff 的关联规则及跨 App 依赖设计
Migrations 迁移顺序说明
架构决策说明（ADR）

6.8 Electron 客户端约定

Electron 客户端在登录链路上的实现约定（Tenant Code 加密存储、Session Cookie 策略、登录页加载、多标签页、登出、窗口关闭、强制更新、安全约束）已迁移至 TECH_STACK/登录管理技术方案.md §十三 Electron 客户端约定。

本 PRD 仅约束业务行为：

客户端必须在登录前完成 Tenant 识别，且 Tenant Code 须加密持久化
客户端登出后，本地不得保留可直接复用的登录凭证
客户端版本低于服务端要求的最低版本时，必须阻断登录流程并展示更新提示（联动平台管理后台 PRD 的客户端发布章节）
同一客户端窗口内的多标签页应共享同一登录态

7. 技术注意事项（产品视角）

7.1 业务依赖

短信发送依赖具备短信资质的服务商；签名与模板审核须在功能上线前完成
短信发送须异步处理，避免阻塞登录链路；密码登录可作为短信故障时的保底入口
多租户隔离与跨 Schema 调用细节由 TECH_STACK/登录管理技术方案.md 与 DATA_MODEL/DATA_MODEL_LOGIN.md 定义

7.2 已知风险

风险	可能性	影响	缓解措施
滑块验证被机器模拟轨迹绕过	低	高	服务端综合位置 + 轨迹特征校验；后续可引入设备指纹加固
Tenant Code 枚举攻击（暴力试探）	低	中	接口限流 + 统一外显文案，不区分「未找到」与「已禁用」
密码重置凭证泄露	低	高	一次性、短时效、HTTPS 传输
短信服务故障	中	高	失败告警 + 密码登录保底 + 建议配置备用短信通道
多端同时登录同一账号	高（日常场景）	低	本期允许，后续如需踢出再做版本号机制

7.3 开放问题（开发前需确认）

短信服务商选型：阿里云 / 腾讯云 / 其他？短信签名与模板审核需要 1–3 个工作日 — 负责人：后端负责人 — 截止：开发启动前
Session 默认有效期：8 小时是否满足各租户需求？是否允许 Tenant Admin 自行配置？— 负责人：产品经理 — 截止：开发启动前
滑块拼图实现方案：自研还是集成第三方行为验证服务？需评估数据合规要求 — 负责人：后端负责人 + 安全 — 截止：开发启动前
账号锁定通知：账号被锁定后，是否自动发短信通知用户和/或通知管理员？— 负责人：产品经理 — 截止：开发启动前
历史密码校验范围：最近 3 次是否足够？是否需要额外规则（如不能与用户名相同）？— 负责人：产品经理 — 截止：开发启动前

8. 发布计划

阶段	时间	受众	准入门槛
内部 Alpha	待定	研发团队 + 1 家种子租户	核心流程（Tenant 识别 + 账密登录 + 找回密码）无 P0 Bug
封闭 Beta	待定	5 ~ 10 家测试租户	登录成功率 ≥ 99%，验证码拦截机制正常运作
正式发布	待定	全量租户	Beta 阶段无未修复的安全漏洞；帮助文档发布

回滚标准：若正式发布后 24 小时内登录失败率（非验证码拦截原因）超过 2%，或出现账号数据泄露事件，立即回滚并启动安全审查。

9. 附录

9.1 登录状态流转图

[未识别 Tenant]
    │ 输入有效 Tenant Code
    ↓
[未登录]
    │ 账密 / 验证码登录成功
    ↓
[初始密码状态]（如账号为初始密码）
    │ 强制改密成功
    ↓
[已登录 - Active Session]
    │ Session 过期 / 主动登出 / 管理员强制登出
    ↓
[未登录]（跳转登录页）

[账号锁定状态]（密码连续错误达到阈值后）
    │ 锁定时长结束自动解锁 或 管理员手动解锁
    ↓
[未登录]（可重新登录）

9.2 业务能力清单（替代原"接口清单"）

本文件不再列出具体接口路径与 HTTP 方法。完整 API 端点清单（含路径、方法、Schema 位置、是否鉴权、预留端点）请查阅 TECH_STACK/登录管理技术方案.md §五。

业务能力	提供给谁	说明
Tenant 识别	客户端	输入 12 位 Tenant Code，返回租户品牌与登录入口
获取/校验滑块验证码	登录页	行为验证码生成与校验，输出一次性通过凭证
密码登录	已识别租户的用户	手机号 + 密码 + 滑块凭证完成认证
验证码登录	已识别租户的用户	手机号 + 短信验证码完成认证（需先通过滑块再获取验证码）
登出	已登录用户	销毁服务端会话与本地登录凭证
找回密码（三步）	忘记密码的用户	发送 OTP → 校验 OTP → 设置新密码
首次登录强制改密	处于初始密码状态的用户	强制流程，提交后脱离初始密码状态
微信扫码登录（v2 预留）	全量用户	MVP 仅展示禁用入口，v2 实现

9.3 相关文档参考

技术栈总纲：TECH_STACK/TECH_STACK.md
登录管理技术方案（实现口径权威）：TECH_STACK/登录管理技术方案.md
登录管理数据模型（数据口径权威）：DATA_MODEL/DATA_MODEL_LOGIN.md
全局 API 契约：TECH_STACK/API_CONTRACT.md
ADR：ADR.md（特别是 ADR-20260502-003 PRD/Tech 职责边界、ADR-20260430-004 登录接口路径同步规则）

42 KiB Raw Blame History Unescape Escape

PRD：用户登录管理模块

关联文档（实现口径）

变更历史

1. 问题陈述

1.1 背景

1.2 核心痛点

1.3 目标用户

2. 目标与成功指标

3. 非目标（本期不做）

4. 页面清单与导航

4.1 页面清单

4.2 导航流程

5. 用户故事与验收标准

Story 1：新用户首次启动客户端——Tenant 识别

Story 2：经纪人通过手机号和密码登录

Story 3：经纪人找回密码

Story 4：经纪人找回用户名（已废弃）

Story 5：手机验证码登录（MVP 实现）

Story 6：预留——微信扫码登录（v2 实现）

6. 业务规则与功能详细说明

6.1 客户端 Tenant 识别业务流程

Tenant 识别页规范

6.2 登录页设计规范

6.2.1 页面布局

6.2.2 安全机制（业务视角）

6.3 账号与员工实名绑定规范

6.3.1 绑定原则

6.3.2 账号创建权限分层

6.3.3 账号字段语义（业务视角）

6.4 首次登录强制修改密码

6.5 找回密码业务流程

6.6 手机验证码登录（业务规则补充）

6.7 后端数据模型

6.8 Electron 客户端约定

7. 技术注意事项（产品视角）

7.1 业务依赖

7.2 已知风险

7.3 开放问题（开发前需确认）

8. 发布计划

9. 附录

9.1 登录状态流转图

9.2 业务能力清单（替代原"接口清单"）

9.3 相关文档参考

42 KiB

Raw Blame History