# 顾客登录组件 PRD

版本：v0.4
状态：第一阶段 MVP 范围已确认；三种登录分支响应式原型已制作，待开发
组件标识：C-COM-03
适用表面：VISTA C

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-29 | v0.1 | 初始创建 / 重大范围确认 | 将顾客登录纳入 MVP，定义受限页面进入前和会话失效后的阻断式登录、验证反馈、原目标恢复及切换顾客规则；明确未登录不进入状态页，登录成功但无页面授权才进入 403。 |
| 2026-07-29 | v0.2 | 重大：登录方式与本地顾客记录定稿 | 按访问链接是否指定顾客、是否免密码定义三种登录方式；未指定顾客时使用邮箱和密码；登录后在当前浏览器保存最少的顾客识别信息，供后续数据上报关联顾客。 |
| 2026-07-29 | v0.3 | 重大：免密码设置归属定稿 | 确认免密码在“用户分享设置”中按顾客单独设定，同一顾客的所有分享页面统一使用该设置；页面和单条分享链接不再分别设置免密码。 |
| 2026-07-29 | v0.4 | 重大：B端流程边界定稿 | 分享验证和用户分享设置均由现有 B 端产生；MVP 不修改 B 端业务流程、设置页面或生成方式，C 端登录组件只承接并执行已有规则。 |
| 2026-07-29 | v0.4 | 非重大：原型交付同步 | 已完成未指定顾客、指定顾客需密码、指定顾客免密码三种阻断式登录原型，并移除固定手机框。 |

## 1. 文档目的与适用对象

本文档用于产品、设计、C 端开发、登录功能开发、测试及 Codex 统一实现三个 MVP 页面复用的顾客登录能力。

适用页面：

- 项目概览页
- 周边地图页
- 户型列表页
- 403 状态页中的“使用其他顾客身份登录”动作

顾客登录是跨页面通用组件，不是 Widget，不进入 A 端 Widget 注册、排序或页面内容配置。

## 2. 产品背景与目标

A 端项目页面发布快照已经区分是否允许未登录顾客查看。允许时，顾客匿名进入；不允许时，B 端负责授权具体顾客，C 端负责建立顾客登录身份并校验页面授权。

本组件目标：

1. 在受限页面展示任何项目内容前完成顾客登录。
2. 登录成功后恢复原目标地址，并继续执行页面授权校验。
3. 根据访问链接是否已经指定顾客，以及该顾客在“用户分享设置”中是否免密码，显示正确的登录内容。
4. 登录成功后在当前浏览器保存最少的顾客识别信息，供后续数据上报关联顾客。
5. 在登录失效时阻止继续读取受限内容，并允许顾客重新登录。
6. 把邮箱或密码错误、频率限制和登录服务异常限制在组件内部，不额外建立 401、429 或 5xx 状态页。

## 3. 版本范围与边界

### 3.1 MVP 包含

- 受限页面没有有效顾客登录时自动调用登录组件。
- 链接指定顾客时，只输入密码。
- 链接指定顾客，且该顾客统一设为免密码时，无需输入密码。
- 链接未指定顾客时，输入顾客邮箱和密码。
- 免密码顾客通过邮箱登录时，不判断密码是否正确。
- 密码默认隐藏及显示/隐藏切换。
- 必填校验、提交中、验证失败、频率受限和服务不可用反馈。
- 登录成功后恢复原页面地址并重新校验页面授权。
- 登录成功后在当前浏览器保存顾客识别信息。
- 登录失效后的重新登录。
- 从 403 状态页清除当前登录并使用其他顾客账号登录。
- 手机、PAD、PC 的阻断式登录承载。

### 3.2 MVP 明确不做

- 新建或修改 B 端用户分享设置、分享验证、顾客管理及分享链接生成流程。
- 要求 B 端为 MVP 重新配置已有顾客或重新生成已有分享链接。
- 顾客注册、账号申请、邀请接受流程。
- 忘记密码、自助重置密码或修改密码。
- 短信/邮件验证码、一次性口令、社交账号或第三方 OAuth 登录。
- 生物识别、设备信任、“记住我”和多因素认证。
- 顾客中心、个人资料、权限列表和全局常驻账号菜单。
- CRM 建档、销售归属、线索创建、分享归因和埋点。
- 把顾客邮箱、密码或访问链接中的顾客参数作为数据上报字段。
- 在浏览器中长期保存密码。
- 在组件内决定顾客可访问哪些页面。
- 将登录失败跳转为 403、404 或其他状态页。

## 4. 角色与调用条件

| 角色 / 系统 | 职责 |
| --- | --- |
| 顾客 | 按当前访问链接显示的方式完成登录。 |
| A 端 | 在页面发布快照中提供“是否允许未登录查看”；不选择具体顾客。 |
| 现有 B 端 | 按已有业务流程产生分享验证结果，包括指定顾客、顾客邮箱、密码、是否免密码及该顾客可以访问的页面。MVP 不修改该流程。 |
| C 端页面 | 读取 B 端已有分享结果，判断是否需要登录、调用本组件、记录登录结果，并在登录后检查当前页面是否可访问。 |
| 顾客登录组件 | 收集本次登录所需输入、提交验证并展示反馈；不自行计算页面权限。 |

组件仅在以下情况出现：

1. 当前页面发布设置不允许未登录访问，且顾客尚未有效登录。
2. 顾客浏览受限页面期间，登录失效或系统要求重新登录。
3. 顾客在 403 状态页主动选择使用其他顾客身份登录。

公开页面不得为了“统一体验”强制弹出登录组件。

## 5. 登录方式

### 5.1 三种登录情况

| 访问情况 | 顾客看到的内容 | 通过条件 |
| --- | --- | --- |
| 链接已指定顾客，未设免密码 | 只显示“密码”。 | 链接中的顾客有效，且密码正确。 |
| 链接已指定顾客，该顾客统一设为免密码 | 不显示登录输入框，直接完成登录检查。 | 链接中的顾客有效，且该顾客当前设为免密码。 |
| 链接未指定顾客 | 显示“顾客邮箱”和“密码”。 | 先通过邮箱找到顾客；普通顾客需要密码正确，免密码顾客不判断密码是否正确。 |

补充规则：

- “链接已指定顾客”是指系统生成的访问链接中包含可以识别指定顾客的信息，不是顾客自行修改链接文字。
- 页面不得把链接中的顾客编号、内部参数或顾客邮箱直接显示出来。
- 链接中没有顾客信息，或顾客信息无法使用时，统一按“链接未指定顾客”处理，不提示该顾客是否存在。
- 链接未指定顾客时，登录表单仍显示邮箱和密码。系统通过邮箱识别到该顾客允许免密码登录后，不以密码是否正确作为通过条件。
- 普通顾客的邮箱或密码错误时，统一提示“邮箱或密码不正确”，不得分别提示邮箱是否存在。
- 密码默认隐藏；显示密码只改变输入框中的可见状态。
- 密码不得写入访问链接、浏览器本地记录、日志、错误信息或后续数据上报。

### 5.2 免密码登录边界

- 本节“用户”指在 C 端登录和识别的顾客账号。
- 免密码由现有 B 端“用户分享设置”按顾客单独产生，C 端不提供设置入口。
- MVP 不改变 B 端如何新增顾客、设置密码、切换免密码或生成分享链接。
- 免密码不在 C 端项目页面或单条分享链接上分别设定。
- 同一顾客的项目概览、周边地图、户型列表及未来其他分享页面统一使用该顾客当前的免密码设置。
- 该设置只决定页面需要登录时是否检查密码；公开页面不会因为顾客设为普通或免密码而强制弹出登录。
- 每次需要登录时，都读取该顾客当前的免密码设置；修改后对该顾客已有和新生成的分享页面统一生效。
- 访问链接指定顾客时，该顾客当前设为免密码才可以不显示密码输入。
- 访问链接未指定顾客时，先通过邮箱确定顾客，再使用该顾客统一的免密码设置；免密码顾客不判断密码是否正确。
- 免密码只改变登录时是否检查密码，不代表该顾客自动获得所有页面权限。
- 这意味着知道免密码顾客邮箱的人可能以该顾客身份进入。启用免密码前必须确认其业务风险，C 端不得把普通顾客自动改为免密码。

### 5.3 浏览器本地顾客记录

登录成功后，C 端在当前浏览器保存一份最少的顾客记录：

- 系统生成的顾客识别编号。
- 本次登录是否有效。
- 本次登录方式：指定顾客加密码、指定顾客免密码、邮箱加密码或邮箱免密码。
- 登录时间和失效时间（如系统有提供）。

本地记录规则：

- 顾客邮箱只用于登录，不作为后续数据上报参数；密码在任何情况下都不得保存。
- 后续增加数据上报时，只上报顾客识别编号，不直接上报邮箱。
- 顾客切换账号、主动退出、登录失效或记录无法确认有效时，必须清除原顾客记录。
- 从未登录的匿名顾客不生成顾客识别编号。
- 已登录顾客访问公开页面时，可以继续使用有效的本地顾客记录；记录失效后按匿名访问处理。

## 6. 核心用户用例

### UC-LOGIN-01 进入受限页面并登录

**前置条件：**

- 页面存在、已发布且不允许未登录访问。
- 顾客当前没有有效登录。

**主流程：**

1. 顾客打开页面原始链接。
2. C 端不渲染项目 Widget、联系方式或其他受限内容，打开顾客登录组件。
3. 顾客按当前情况输入密码，或输入顾客邮箱和密码；指定顾客且统一设为免密码时无需输入。
4. 组件提交登录验证，并在提交期间防止重复提交。
5. 验证成功后关闭登录组件，保留原目标地址。
6. C 端保存顾客识别信息，并检查该顾客能否访问当前页面。
7. 有授权时进入原页面；无授权时进入统一 403。

### UC-LOGIN-02 登录失败并重试

1. 顾客提交无法识别的邮箱，或普通顾客提交错误密码。
2. 组件统一提示“邮箱或密码不正确”，不说明邮箱是否存在。
3. 密码输入清空，顾客邮箱可以保留。
4. 顾客修正后重新提交。
5. 失败期间不显示受限页面内容，也不跳转 403/404。

### UC-LOGIN-03 登录失效后重新登录

1. 顾客正在访问受限页面，登录状态失效。
2. 页面停止继续请求或展示新受限数据，并打开登录组件。
3. 顾客重新登录。
4. C 端重新校验当前页面授权。
5. 授权仍有效时恢复原地址；可安全恢复的筛选、卡片、滚动或地图临时状态继续保留。
6. 授权已被撤销时进入 403。

### UC-LOGIN-04 从 403 切换顾客

1. 已登录顾客进入 403。
2. 顾客选择“使用其他账号登录”。
3. 系统清除当前顾客登录和本地顾客记录，再打开登录组件。
4. 新顾客登录成功后重新校验原目标页面。
5. 有授权则进入原页面；仍无授权则返回 403，不形成自动循环。
6. 新顾客登录成功时，用新顾客记录替换浏览器中的原顾客记录。

### UC-LOGIN-05 免密码进入

1. 顾客打开已经指定顾客的访问链接，且该顾客在“用户分享设置”中当前设为免密码。
2. 页面不显示密码输入框。
3. 系统确认链接中的顾客仍然有效。
4. C 端保存顾客识别信息并检查该顾客能否访问当前页面。
5. 有权限时进入原页面，无权限时进入 403。

### UC-LOGIN-06 登录服务暂不可用

1. 登录提交因服务异常、网络异常或频率限制失败。
2. 组件显示可理解的局部提示和可用重试动作。
3. 页面不跳转 404，不新增 429、500 或 503 状态页。
4. 组件始终保留安全返回来源页的路径。

## 7. 功能需求矩阵

| 功能 ID | 功能名称 | 关联用例 | 优先级 | 状态 |
| --- | --- | --- | --- | --- |
| F-LOGIN-01 | 阻断式打开与受限内容保护 | UC-LOGIN-01、03 | P0 | 待设计 / 待开发 |
| F-LOGIN-02 | 指定顾客链接、邮箱与密码输入 | UC-LOGIN-01、02、05 | P0 | 待开发 |
| F-LOGIN-03 | 登录提交与反馈 | UC-LOGIN-01、02、05、06 | P0 | 待设计 / 待开发 |
| F-LOGIN-04 | 原目标和临时状态恢复 | UC-LOGIN-01、03 | P0 | 待开发 |
| F-LOGIN-05 | 清除原登录并切换顾客 | UC-LOGIN-04 | P0 | 待开发 |
| F-LOGIN-06 | 保存和清除本地顾客记录 | UC-LOGIN-01、03、04、05 | P0 | 待开发 |

## 8. 功能详细说明

### 8.1 阻断式承载

- 登录组件在受限页面内容之前工作，不先渲染项目名称、封面、地图、POI、户型、联系方式或其他受限摘要。
- 手机端使用全视口阻断层；PAD/PC 可使用居中登录容器，但背景只能是中性品牌表面，不得透出受限项目内容。
- 组件保留 HOMEVISTA/VISTA 基础品牌识别，不使用项目专属内容暗示受限资源是否存在。
- 直接打开受限链接时，关闭/返回动作返回安全来源；没有安全来源时保持登录界面，不跳转到项目概览页。

### 8.2 输入与提交

| 状态 | 组件行为 |
| --- | --- |
| 初始 | 链接指定普通顾客时只显示密码；链接指定统一免密码顾客时不显示输入框；未指定顾客时显示顾客邮箱和密码。 |
| 必填缺失 | 在对应字段附近提示，不提交请求。 |
| 提交中 | 锁定本次提交按钮，避免重复请求；输入内容不写入 URL。 |
| 验证成功 | 保存本地顾客记录，关闭组件并重新检查当前页面是否可访问。 |
| 邮箱或密码错误 | 使用统一提示，不说明邮箱是否存在或哪一项错误。 |
| 频率受限 | 暂停提交并提示稍后再试；不建立 429 状态页。 |
| 服务不可用 | 显示组件局部错误、重试和返回来源；不建立 5xx 状态页。 |

### 8.3 原目标恢复

- 打开登录组件前保存原页面地址，但不得把密码、登录信息或页面权限信息写入恢复地址。
- 登录成功后先重新校验页面存在性、发布状态和当前顾客授权，再决定是否恢复页面。
- 登录成功不等于获得页面权限；无授权必须进入 403。
- 登录失效后恢复的筛选、滚动、卡片和地图状态只能来自本次访问，不跨设备、不跨顾客恢复。
- 切换顾客后清除前一顾客的页面临时状态，防止数据串用。

### 8.4 安全与隐私

- 密码、登录凭据和页面权限明细不得出现在可见错误、访问链接、前端日志、数据上报或第三方分析参数中。
- 浏览器本地只保存系统生成的顾客识别编号和维持登录所需的信息，不保存密码；邮箱默认不作为数据上报参数。
- 登录失败提示不得用于判断账号是否存在。
- 组件不得缓存或自动填入其他顾客的账号和密码；是否使用浏览器自带的密码保存能力由开发方案决定。
- 登录组件只处理顾客登录，不创建顾客、销售线索或新的页面权限。

## 9. 响应式与设计系统

| 视口 | 产品规则 |
| --- | --- |
| 320px / 375px | 登录阻断层占满视口；字段、错误和主操作均可在单列中完成；键盘弹出后仍能看到当前输入与提交结果。 |
| 768px | 可使用居中容器，但不得显示受限页面内容作为背景。 |
| 1024px / 1440px | 可增加容器留白和品牌空间，不增加桌面专属登录方式。 |

VISTA C 设计系统已有 `弹窗 / Login` 类别，因此原型应复用其登录语义和液态玻璃视觉语言。登录弹窗的精确尺寸、按钮位置、遮罩、进入/退出动效和移动端键盘避让规格尚不完整，统一标记为 **待设计系统补充**。

## 10. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-LOGIN-01 | 页面允许未登录访问 | 匿名顾客打开 | 直接进入页面，不出现登录组件。 |
| AC-LOGIN-02 | 页面不允许未登录访问且顾客尚未有效登录 | 顾客打开 | 先显示阻断式登录组件，受限项目内容不渲染。 |
| AC-LOGIN-03 | 链接指定顾客且未设免密码 | 打开登录组件 | 不展示顾客邮箱和内部编号，只显示密码。 |
| AC-LOGIN-04 | 链接指定顾客，且该顾客统一设为免密码 | 顾客打开页面 | 不显示登录输入框；确认顾客有效后继续检查页面权限。 |
| AC-LOGIN-05 | 链接未指定顾客 | 打开登录组件 | 显示顾客邮箱和密码。 |
| AC-LOGIN-06 | 链接未指定顾客，邮箱对应普通顾客 | 顾客提交 | 只有邮箱和密码均正确才登录成功。 |
| AC-LOGIN-07 | 链接未指定顾客，邮箱对应免密码顾客 | 顾客提交 | 不判断密码是否正确，登录后继续检查页面权限。 |
| AC-LOGIN-08 | 普通顾客邮箱或密码错误 | 顾客提交 | 统一提示邮箱或密码不正确，可重试，不进入 403/404。 |
| AC-LOGIN-09 | 登录成功且顾客有页面授权 | 完成页面检查 | 返回原目标页面，不跳项目概览页。 |
| AC-LOGIN-10 | 登录成功但顾客无页面授权 | 完成页面检查 | 进入统一 403，不展示页面摘要。 |
| AC-LOGIN-11 | 已登录状态失效 | 页面请求受限内容 | 停止继续展示新受限数据并打开登录组件；重新登录后再次检查。 |
| AC-LOGIN-12 | 登录服务不可用或频率受限 | 顾客提交 | 在组件内显示错误与重试，不新增状态页。 |
| AC-LOGIN-13 | 顾客从 403 切换账号 | 新顾客登录 | 清除前一顾客记录与临时页面状态，再检查原目标。 |
| AC-LOGIN-14 | 任一种登录方式成功 | 检查浏览器本地记录 | 保存系统生成的顾客识别编号和登录方式，不保存密码。 |
| AC-LOGIN-15 | 后续数据上报读取有效顾客记录 | 顾客已登录 | 使用顾客识别编号关联顾客，不直接上报邮箱和密码。 |
| AC-LOGIN-16 | 顾客退出、切换账号或登录失效 | 状态变化 | 清除原顾客记录，不继续以上一顾客身份上报。 |
| AC-LOGIN-17 | 检查网络、日志、URL和错误提示 | 完成成功或失败登录 | 不出现密码、登录凭据或页面权限明细。 |
| AC-LOGIN-18 | 320px、375px、768px、1024px、1440px | 完成输入、失败、重试和成功流程 | 关键字段与操作可达，不透出受限页面内容。 |
| AC-LOGIN-19 | 同一顾客分享多个页面 | 顾客需要登录 | 所有分享页面使用该顾客同一份免密码设置，不按页面或单条链接产生不同结果。 |
| AC-LOGIN-20 | 修改某顾客的免密码设置 | 该顾客再次通过已有或新分享链接登录 | 所有分享页面按修改后的设置执行；不影响其他顾客。 |

## 11. C端需要读取的已有结果

| B 端已有结果 | C 端使用方式 |
| --- | --- |
| 正式分享链接及其中的指定顾客信息 | 直接读取现有 B 端结果；不得信任顾客手工修改出的顾客编号，也不得显示链接中的内部信息。 |
| 顾客邮箱 | 链接未指定顾客时作为登录账号。 |
| 顾客密码和免密码状态 | 固定读取该顾客现有“用户分享设置”；C 端不新增设置入口。 |
| 顾客可以访问的页面 | 登录成功后读取现有 B 端结果，决定进入页面或 403。 |
| 登录保持时间和延长方式 | 由开发方案确定；登录失效后的产品行为按本 PRD。 |
| 密码错误次数、暂停登录时间和访问频率限制 | 由开发方案定义；组件必须能承接暂时不能继续提交的状态。 |
| 本地顾客记录保存方式 | 由开发方案确定，但只能保存本 PRD 列出的最少信息，并能在退出、切换或失效时清除。 |
| 精确视觉和动效 | 待设计系统补充，不影响登录、授权和状态流转开发。 |

上述技术数值不得由前端临时写死为产品承诺。

## 12. 供 Codex 使用的执行说明

- 未登录、邮箱或密码错误和登录失效不是 403；必须先使用本组件完成顾客登录。
- 登录成功不等于有权限；必须再调用权限规则校验当前页面。
- 链接指定普通顾客时只显示密码；指定统一免密码顾客时不显示输入框；未指定顾客时显示邮箱和密码。
- 免密码顾客通过邮箱登录时，不判断密码是否正确，但仍必须检查该顾客的页面权限。
- 同一顾客的所有分享页面必须使用一份统一的免密码设置，不得按页面或链接复制设置。
- 不得为了 C 端 MVP 修改 B 端现有分享流程；如现有字段名称不同，只做读取对应，不改变业务规则。
- 登录成功后只保存顾客识别编号等最少信息，不保存密码，不把邮箱作为默认上报参数。
- 不得在受限内容已经渲染后才用半透明弹窗遮住页面。
- 不得新增注册、找回密码、验证码、社交登录、顾客中心或全局账号菜单。
- 原型先完成 320px、375px 的阻断、输入、失败、重试和成功状态，再扩展 PAD/PC。