# HOMEVISTA C端通用组件说明

## 修订记录

| 版本 | 日期 | 修改人 | 修改内容 |
|---|---|---|---|
| v0.1 | 2026-07-02 | 唐雷 | 建立文档大纲 |
| v0.2 | 2026-07-03 | Codex | 暂停阶段范围划分，改为组件范围整理 |
| v0.3 | 2026-07-08 | Codex | 新增户型卡片通用组件，承接户型列表和户型及住户卡片模块的卡片表达 |
| v0.4 | 2026-07-09 | Codex | 随文档顺序调整为页面模板和页面 PRD 之后的通用组件说明 |
| v0.5 | 2026-07-09 | Codex | 新增身份验证组件和对象对比组件，承接原系统能力模块的组件归属 |
| v0.6 | 2026-07-09 | Codex | 新增导航与返回组件，承接原导航模块的入口、跳转和返回能力 |
| v0.7 | 2026-07-10 | Codex | 统一对比组件命名为对象对比组件 |
| v0.8 | 2026-07-10 | Codex | 补充户型图缩略图与大图查看为户型卡片组件表现形态 |
| v0.9 | 2026-07-15 | Codex | 因新增 `05-系统状态与错误页PRD.md` 顺延文档编号；组件范围不变 |
| v0.10 | 2026-07-28 | 产品确认 / Codex | **重大组件边界变更：新增项目联系页脚。** 原 `M-02 项目联系方式`退出 Widget 清单，改为固定消费项目级公共联系资料的页面通用组件；不承担预约、销售归属或逐页装配。 |

## 一、文档目的

定义 C端跨模块复用的基础交互、业务展示、转化、导览和数据采集组件。

## 二、组件定义边界

通用组件是页面或 Widget 可复用的界面与局部交互单元，不因存在点击、展开、筛选或全屏查看而自动成为 Widget。组件只消费页面或 Widget 已整理并传入的数据、启用结果和动作回调；不自行读取项目数据、不决定项目是否启用业务能力、不登记为 A端 Widget 区块，也不定义页面级排序、权限策略或埋点口径。

Widget 则是可由 A端独立登记、装配、校验、启停并围绕顾客任务形成闭环的业务能力。Widget 可以使用多个通用组件；通用组件不得反向取代 Widget 的数据适配、业务状态或启用判断。

## 三、组件分类

### 3.1 基础 UI 组件

#### 3.1.1 导航与返回组件

**组件目的**：提供跨页面和跨模块复用的入口、返回、关闭、页面内锚点、模块跳转和对象跳转机制，帮助顾客在项目、户型、住户、资料和转化流程之间保持清晰路径。

**适用场景**：全局导航入口、页面内锚点入口、模块间跳转入口、对象内跳转入口、返回来源路径、关闭弹层或全屏工具、目标不可用提示。

**基础展示状态**：展示入口名称、目标名称、入口状态、返回入口、关闭入口、不可用提示和必要说明。具体入口是否出现、顺序如何、放在页面哪个位置，由页面模板索引和对应页面 PRD 决定。

**数据边界**：组件只消费调用页面或模块传入的目标页面、目标模块、目标对象、入口名称、启用条件、来源路径、默认返回路径和不可用处理结果；不定义页面信息架构、菜单视觉样式、路由技术实现、权限策略和埋点统计口径。

**状态规则**：目标页面、模块或对象未配置时不展示入口；目标模块未启用、目标资产不存在或目标无权限时，优先隐藏入口；已点击后才发现目标不可访问时，展示不可用提示并提供返回来源路径；来源路径缺失时使用调用页面提供的默认返回路径；默认返回路径也缺失时，不得进入空页面。

**不做边界**：不作为独立功能模块，不决定页面有哪些导航入口，不决定入口排序、菜单样式、底部导航样式、页面信息架构、权限判断、销售路径策略和埋点事件。

### 3.2 内容展示组件

#### 3.2.1 户型卡片

**组件目的**：以统一卡片形式展示户型摘要，并在绑定具体住户时叠加住户级摘要信息；支持户型图缩略图、放大查看或全屏图纸查看等表现形态。

**适用模块**：`M-10 户型卡片列表`、`M-12 户型及住户卡片`。两个模块可复用本组件，但模块之间不产生启用依赖。

**基础展示状态**：户型状态。展示户型名称、户型图缩略图、面积、面积口径、房型结构、朝向、户型标签、户型卖点摘要和可用入口；户型图可以按页面需要进入大图查看或全屏图纸查看形态，但不因此形成独立功能模块。

**扩展展示状态**：住户状态。在户型状态基础上，叠加房号、单元、楼栋、楼层、销售状态、可选价格 / 费用摘要、样板间入口、眺望入口和费用入口。

**数据边界**：户型信息来自户型资产；住户级信息来自住户、价格与费用、眺望与景观等关联资产。组件只消费模块传入的数据，不决定资产是否完整、模块是否启用或内容是否对某类顾客可见。

**状态规则**：户型图缺失时可降级为文字摘要；面积、朝向、标签等可选信息缺失时隐藏对应字段；未绑定住户时不展示房号、销售状态、价格、费用、眺望等住户级字段。

**不做边界**：不定义户型列表排序、推荐算法、住户筛选、客户可见权限、销售分配、价格展示权限和页面跳转路径；不把户型图缩略图、大图查看或全屏图纸查看拆成独立模块。

### 3.3 选择与筛选组件

### 3.4 比较组件

#### 3.4.1 对象对比组件

**组件目的**：提供跨页面和跨模块复用的对象选择、对比池、并列展示、差异提示、清空选择、退出返回等对比展示机制，避免每类对象重复定义相同对比交互。

**适用场景**：空间对象、户型卡片、住户对象、资料对象等需要并列比较的页面或模块；具体对象来源、可比字段和入口位置由调用页面或业务模块提供。

**基础展示状态**：展示已选对象、可进入对比状态、对象数量上限、进入对比入口、清空入口和退出入口。

**数据边界**：组件只消费调用模块传入的对象列表、对象类型、对比字段、字段展示规则和返回路径；不定义具体业务对象、业务字段、价格展示权限、销售状态可见性和推荐排序。

**状态规则**：少于最小对比数量时不展示进入对比入口；超过最大对比数量时阻止继续选择并提示上限；字段缺失时按调用模块规则隐藏、标记缺失或展示待确认；对象加载失败时允许移除对象或返回来源。

**不做边界**：不决定哪些页面或模块必须支持对比，不定义空间 / 户型 / 住户等业务字段，不处理权限、埋点和页面 PRD。

### 3.5 转化组件

#### 3.5.1 项目联系页脚

**组件目的**：在当前项目的营销与内容浏览页面底部，固定提供项目级公共联系入口；在来场预约未启用或不可用时，仍保留不收集个人信息的替代行动。

**适用场景**：项目卖点 Landing、活动与渠道、周边地图、眺望、资料、户型、推荐住户等具有 C端页面壳层的页面页脚。它不是页面中部可编排的转化区块，不支持按页面、渠道、顾客身份或销售归属配置不同联系人；全屏外部应用承载页不强行叠加页脚，应通过返回来源页获得联系入口。

**基础展示状态**：仅展示当前项目已配置且可执行的公共联系项：接待中心地址、咨询电话、咨询邮箱、官网、微信 / LINE / 社交媒体账号或二维码、联系时间和必要说明。电话使用设备拨号、邮箱使用邮件客户端、官网和社交入口打开已配置目标；地址仅在有可用目标时提供查看动作。预约按钮不属于本组件。

**数据边界**：页面壳层将 `project.contact` 作为已整理的项目级公共联系资料传入。组件不自行请求数据，不判断项目是否发布，不处理个人销售联系人、分享人追踪、客户归属、CRM 分配、来场预约表单或提交结果。联系方式资产口径以 `01-内容资产字典.md` 为准。

**状态规则**：单项资料缺失、目标地址不可用或设备不支持对应动作时隐藏该项；至少一项可执行联系资料存在时展示页脚；全部缺失时隐藏整个页脚，不以“预约”“在线咨询”或占位按钮替代。外部目标在打开后发生的错误由目标服务处理，当前页面保留原浏览状态。

**设计系统约束**：本组件属于 VISTA C 页面底部的公共行动区域。现有设计系统组件清单未提供项目联系页脚的专门视觉规格；实现时应采用 VISTA C 页面框架与既有普通行动控件，不引入 VISTA B 后台样式。具体视觉规格标记为“待设计系统补充”。

**验收标准**：所有营销与内容浏览页面在项目有至少一项可执行公共联系资料时显示同一组件；缺失资料不形成空按钮；公共联系方式不展示个人销售信息；M-26 不可用时页脚仍可独立使用；组件不出现在 A端 Widget 台账、模板 Widget 区块或项目页面 Widget 配置中。

### 3.6 访问控制组件

#### 3.6.1 身份验证组件

**组件目的**：在访问受限页面、受限资料或需要确认身份的流程中，承载手机号、邮箱、验证码、访问码或链接口令等身份验证输入与结果反馈。

**适用模块 / 流程**：来场预约、分享页访问、受限资料访问、指定客户页面访问，以及 `07-权限与访问控制规则.md` 中定义的其他受限流程。

**基础展示状态**：展示验证标题、验证说明、必要输入项、验证码 / 访问码输入区、提交按钮、重新发送或重新输入入口、返回入口，以及必要的隐私 / 同意说明。

**数据边界**：组件只消费权限与访问控制规则提供的验证方式、触发场景、字段配置、有效期、重试次数、失败处理和返回路径；不自行决定哪些页面需要验证，也不决定内容是否可见。

**状态规则**：未配置验证方式时不启用；需要收集手机号、邮箱或其他个人信息但缺少隐私 / 同意说明时不得收集；验证发送中、验证中、失败、过期、次数超限和服务不可用时必须给出明确反馈和返回路径。

**不做边界**：不定义访问权限策略、销售分配、CRM 同步、分享人追踪、获客归属、登录态技术实现、风控策略和埋点统计口径。

### 3.7 导览组件

### 3.8 数据采集组件

## 四、组件说明模板

## 五、组件组合模式

## 六、组件数据绑定规则

## 七、组件动作绑定规则

## 八、组件状态规则

## 九、组件权限消费规则

## 十、组件事件上报规则

## 十一、组件范围整理

## 十二、待确认问题