# 顾客登录组件 PRD

版本：v0.8
状态：当前正式需求

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-29 | v0.1 | 初始创建 / 重大范围确认 | 定义受限页面进入前和登录失效后的阻断式顾客登录。 |
| 2026-07-29 | v0.2 | 重大 | 确认指定顾客、未指定顾客与免密码三种登录分支及最少本地顾客记录。 |
| 2026-07-29 | v0.3 | 重大 | 确认免密码按顾客的既有用户分享设置统一生效。 |
| 2026-07-29 | v0.4 | 重大 | 确认 C端不修改既有 B端分享验证、用户分享设置和链接生成流程。 |
| 2026-08-03 | v0.5 | 文档合并 / 目录迁移 | 从旧组件目录迁入当前组件需求目录；产品范围与已确认访问规则不变。 |
| 2026-08-03 | v0.6 | 重大：验证码与项目会话规则更新 | C端按 B端顾客分享验证码规则完成认证；确认同项目复用、跨项目隔离和认证页隐私告知。 |
| 2026-08-04 | v0.7 | 重大：页尾登录入口调整 | 确认所有正常 C端业务页面在页尾提供“登录 / 验证访问”入口；公开页面不会因此被强制登录。 |
| 2026-08-09 | v0.8 | 重大：认证界面文案来源收敛 | 固定认证外壳、通用校验和无来源返回状态文案；B端规则仅提供其已定义的输入与业务说明，组件不得自行补写营销或技术解释。 |

## 1. 定义与目标

唯一标识：`customer-login`。在受限 C端页面展示任何项目内容前建立顾客登录身份，并在成功后由上层继续校验该顾客是否能访问目标页面。它不是 Widget，不负责顾客注册、B端分享配置或页面权限授予。

## 2. 调用条件与角色

仅在以下情况调用：受限页面没有有效顾客登录、访问中登录失效、顾客在 403 主动选择“使用其他账号登录”，或顾客主动点击正常业务页面页尾的“登录 / 验证访问”入口。公开页面不得为统一体验而强制登录；页尾入口只提供主动进入方式，不阻断匿名浏览。

| 角色 | 职责 |
| --- | --- |
| 既有 B端 | 提供顾客分享验证规则、验证结果和可访问页面；不因本组件修改流程。 |
| C端页面 | 判断是否需要登录，调用组件；登录后重新校验页面是否可访问。 |
| 登录组件 | 收集必要输入、提交验证、展示反馈并维护最少本地识别信息；不自行授予页面权限。 |

## 3. 登录方式与规则

> B端定义顾客分享验证码的具体输入、发送和验证规则，并返回验证结果；C端负责承载输入、反馈、会话及认证后的页面体验。C端不将邮箱、密码、免密码或任何固定验证码格式写为自身规则。

- 组件只展示 B端当前规则要求的必要输入和说明；规则缺失、验证失败或服务暂不可用时，只显示通用失败提示和重试，不泄露顾客是否存在。
- 验证码或其他验证输入不得进入 URL、日志、错误信息、本地记录或数据上报。
- 认证成功不等于获得全部页面权限；必须继续检查当前页面授权。
- 登录成功后浏览器仅保存顾客识别编号、登录有效性、登录方式及可用时的失效时间；切换账号、退出或失效时清除。邮箱不作为默认上报字段。
- 同一项目内可复用已认证身份；进入另一受限页面仍须静默确认该页面授权，不重复展示验证码输入。
- 绝对禁止跨项目复用身份、会话或页面临时状态；另一项目受限页必须重新认证。
- 认证页固定展示必要用途说明与隐私政策入口。默认不设同意勾选；营销等非访问必需用途另行取得同意。
- 顾客从正常业务页面页尾主动进入认证页时，认证成功后返回原业务页面并保留其临时状态；取消、失败或服务不可用时可安全返回原页面。没有可验证来源或目标的独立认证地址不得擅自跳转项目概览、住户展示或其他业务页面。
- 已有有效登录的顾客仍可使用页尾入口重新验证或切换身份；完成前不清除当前有效身份，避免产生无返回路径的阻断状态。

### 3.1 顾客可见文案

| 场景 | 固定文案或来源 |
| --- | --- |
| 页面标题 | `验证后继续访问`。 |
| 通用说明 | `此页面仅向获得分享权限的顾客开放。请输入您收到的访问验证信息。` |
| 输入标签与补充说明 | 由 B端当前顾客分享验证规则提供；规则未提供顾客可读标签时使用通用标签 `访问验证信息`。 |
| 提交动作 | `验证并继续`。 |
| 必填缺失 | `请填写访问验证信息。`；如 B端正式规则已提供更具体且不泄露信息的文案，以该规则为准。 |
| 安全返回 | `返回原页面`，只在存在安全来源时显示。 |
| 用途说明 | `访问验证信息仅用于确认本次页面访问资格。`，并显示正式隐私政策入口。 |
| 独立地址完成验证但无可恢复来源 | 标题 `验证已完成`；说明 `当前地址没有可恢复的来源页面，请从原分享链接继续访问。`；不自动跳转业务页面。 |

除 B端正式规则提供的顾客可读输入与反馈外，组件不得增加营销文案、账号类型说明、验证机制、内部错误原因或评审提示。

## 4. 核心流程、状态与安全边界

1. 顾客打开受限页面时，页面不渲染项目名称、封面、地图、户型、联系方式或其他受限摘要，先打开阻断式登录；顾客从公开页面页尾主动进入时，原公开页面不受阻断。
2. 顾客按 B端顾客分享规则完成输入与验证；提交中防止重复提交。
3. 成功后保存最少记录，再检查目标页面存在、发布状态和顾客授权：有授权恢复原目标；无授权进入统一 403。
4. 登录失效时停止展示新的受限数据并重新登录；从 403 切换账号时先清除原顾客记录与临时页面状态。

| 状态 | 处理 |
| --- | --- |
| 必填缺失 | 在字段附近提示，不提交。 |
| 提交中 | 锁定本次提交，输入不写入 URL。 |
| 验证失败 | 统一错误，可重试，不进入 403/404。 |
| 频率受限 / 服务不可用 | 组件内提示与重试/安全返回，不建立 429 或 5xx 页面。 |
| 登录成功但无授权 | 进入既有 403；不得显示页面摘要。 |
| 从页尾主动进入 | 成功后返回原业务页面；取消或失败可安全返回，并保留来源页临时状态。 |

## 5. UI、响应式与设计系统

采用 **VISTA C 登录页面或阻断层**。正常业务页面页尾固定显示“登录 / 验证访问”文字入口；进入认证后，手机端全视口，PAD/PC 可居中承载，但背景只能是中性品牌表面，不得透出受限项目内容。本期原型不规定颜色、液态玻璃或动效。320px 至 1440px 下入口、输入、错误、重试、关闭/安全返回均可达；精确尺寸与移动端键盘避让为 **待设计系统补充**。

## 6. 验收

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-LOGIN-01 | 页面允许匿名访问 | 匿名顾客打开 | 直接进入页面，不出现登录组件。 |
| AC-LOGIN-02 | 页面受限且无有效登录 | 顾客打开 | 先显示阻断式登录，受限内容不渲染。 |
| AC-LOGIN-03 | B端提供顾客分享验证规则 | 登录组件打开 | 显示该规则要求的输入和反馈，不写死邮箱、密码、免密码或验证码格式，也不暴露内部顾客信息。 |
| AC-LOGIN-04 | 登录成功且顾客有授权 | 页面校验完成 | 恢复原目标页面。 |
| AC-LOGIN-05 | 登录成功但无授权 | 页面校验完成 | 进入统一 403，不显示页面摘要。 |
| AC-LOGIN-06 | 错误、限频、服务不可用或登录失效 | 顾客继续访问 | 在组件内提供安全反馈与重试，不新增状态页或泄露凭据。 |
| AC-LOGIN-07 | 切换账号、退出或失效 | 状态变化 | 清除原顾客记录和不应跨顾客保留的页面临时状态。 |
| AC-LOGIN-08 | 顾客位于任一正常 C端业务页面 | 浏览至页尾 | 可发现“登录 / 验证访问”入口；未点击时不阻断公开页面匿名浏览。 |
| AC-LOGIN-09 | 顾客从页尾主动进入认证页 | 成功、取消或失败 | 成功后返回原业务页面；取消或失败可安全返回且保留来源页临时状态。 |
| AC-LOGIN-10 | 检查认证界面全部可见文字 | 页面打开或状态变化 | 仅出现本 PRD 固定文案、B端正式规则提供的输入/反馈及正式隐私政策入口，无 AI 补写或技术解释。 |

## 7. 明确不做

- 不做注册、找回/重置密码、OAuth、MFA、顾客中心、全局账号菜单、CRM、埋点或 B端分享设置；验证码具体规则属于 B端，不在此定义。
- 不做由组件决定顾客可访问哪些页面；登录成功后必须继续执行 [权限与访问控制规则](../05-权限与访问控制规则.md)。