# 项目联系组件 PRD

版本：v0.1
状态：第一阶段 MVP 范围已确认；响应式原型已制作，待开发
组件标识：C-COM-01

## 修订记录

| 日期 | 版本 | 变更类型 | 变更摘要 |
| --- | --- | --- | --- |
| 2026-07-28 | v0.1 | 初始创建 / 重大范围确认 | 定义页面末尾联系入口与联系方式弹窗；确认官网、邮箱、电话至少一项有效是页面发布前置，并排除预约、个人销售联系、CRM 与埋点。 |
| 2026-07-29 | v0.1 | 非重大：原型交付同步 | 三个 MVP 页面已统一实现页尾联系入口与响应式联系方式弹窗原型。 |

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

本文档用于产品、设计、开发、测试及 Codex 统一实现三个 MVP 页面复用的项目联系组件。

适用页面：

- 项目概览页
- 周边地图页
- 户型列表页

该组件是页面通用组件，不是 Widget，不进入 A 端 Widget 注册、排序或页面装配配置。

## 2. 产品背景与目标

三个 MVP 页面都需要提供稳定、轻量的项目公共联系入口，但联系方式不应持续占用主体内容空间，也不应被误做成预约或销售线索模块。

本组件目标：

1. 在页面内容末尾提供一致、可发现的联系入口。
2. 用户主动点击后再通过弹窗查看并使用项目公共联系方式。
3. 让三个页面复用同一数据、交互、状态和验收口径。

## 3. 版本范围与边界

### 3.1 MVP 包含

- 页面末尾固定联系入口。
- 点击入口打开联系方式弹窗。
- 展示有效的项目公共官网、邮箱、电话。
- 官网、邮箱、电话至少一项有效的发布校验。
- 弹窗关闭及返回原页面状态。
- 手机、PAD、PC 的响应式使用。
- 单一发布语言下的组件文案。

### 3.2 MVP 明确不做

- 直接在页面末尾展开全部联系方式。
- 项目地址或售楼处地址。
- 个人销售人员姓名、头像、电话、邮箱或归属关系。
- 预约表单、咨询表单、在线客服和即时通讯。
- CRM、线索分配、联系记录、来源追踪和埋点。
- 一键复制、二维码、分享或保存联系人。
- 语言切换和自动翻译。
- 由页面或 Widget 决定是否显示组件。

## 4. 用户角色与核心场景

| 用户角色 | 核心场景 | 用户目标 |
| --- | --- | --- |
| 顾客 / 外部访问者 | 浏览页面后希望进一步联系项目方 | 找到并使用可用的公共联系方式 |
| 项目运营人员 | 发布项目页面 | 确保至少配置一种有效公共联系方式 |

## 5. 用户用例

### UC-CONTACT-01 查看并使用联系方式

**前置条件：**

- 页面已发布并可访问。
- 官网、邮箱、电话中至少一项有效。

**主流程：**

1. 用户浏览至页面主要内容末尾。
2. 用户点击项目联系入口。
3. 页面打开联系方式弹窗。
4. 弹窗只展示当前项目已配置且有效的官网、邮箱和电话项。
5. 用户点击某一项，系统调用对应的浏览器或设备能力。

**结果：**

- 官网打开有效项目网址。
- 邮箱调用设备邮件能力。
- 电话调用设备拨号能力。

### UC-CONTACT-02 关闭弹窗并继续浏览

1. 用户在联系方式弹窗中点击明确的关闭操作。
2. 弹窗关闭。
3. 页面恢复打开弹窗前的滚动、筛选、卡片或地图状态。
4. 键盘操作场景下，焦点返回原联系入口。

### UC-CONTACT-03 发布前联系方式校验

1. 系统检查项目公共官网、邮箱和电话。
2. 无效字段不计入可用联系方式。
3. 至少一项有效时允许页面继续发布。
4. 三项均缺失或无效时阻止页面发布，并指出需要补充项目公共联系方式。

### UC-CONTACT-04 运行时联系方式异常

- 某一联系方式运行时不可用：不展示该项，其他有效项继续使用。
- 三项在运行时均不可用：弹窗显示组件局部错误并允许关闭，不把整个页面升级为 403、404 或全局错误。

## 6. 功能需求矩阵

| 功能 ID | 功能名称 | 关联用例 | 优先级 | 状态 |
| --- | --- | --- | --- | --- |
| F-CONTACT-01 | 页尾联系入口 | UC-CONTACT-01 | P0 | 待设计 / 待开发 |
| F-CONTACT-02 | 联系方式弹窗 | UC-CONTACT-01、02 | P0 | 待设计 / 待开发 |
| F-CONTACT-03 | 联系方式动作 | UC-CONTACT-01 | P0 | 待开发 |
| F-CONTACT-04 | 发布前校验 | UC-CONTACT-03 | P0 | 待开发 |
| F-CONTACT-05 | 局部异常处理 | UC-CONTACT-04 | P0 | 待设计 / 待开发 |

## 7. 功能详细说明

### 7.1 页尾联系入口

- 入口位于页面主要内容之后，不悬浮，不覆盖封面、地图、筛选、户型卡片或图片查看器。
- 入口使用明确的联系语义；最终字号、容器、图标和间距按 VISTA C 设计系统补充。
- 三个页面固定挂载该入口，不开放按页面隐藏、排序或改造成 Widget。

### 7.2 联系方式弹窗

- 点击入口后在当前页面之上打开弹窗，不进入新页面。
- 弹窗包含标题、有效联系方式列表和明确关闭操作。
- 弹窗打开时背景内容不可误操作；关闭后页面状态不变。
- 手机、PAD、PC 使用同一内容和动作规则；弹窗尺寸、出现位置和动效标记为 **待设计系统补充**。

### 7.3 联系方式动作

| 联系方式 | 展示条件 | 点击结果 |
| --- | --- | --- |
| 官网 | 存在有效项目公共网址 | 打开对应官网，不自动改写或搜索网址 |
| 邮箱 | 存在有效项目公共邮箱 | 调用邮件能力并带入收件地址，不预填营销正文 |
| 电话 | 存在有效项目公共电话 | 调用拨号能力，不自动拨出 |

- 只展示有效项，不使用空值、示例值或其他项目数据补位。
- 三项的展示顺序固定为电话、邮箱、官网，不开放页面级排序。

### 7.4 发布前校验

- 官网、邮箱、电话至少一项有效是三个 MVP 页面共同的发布前置。
- 字段格式无效时不计入有效项。
- 校验只判断联系方式是否可用于公开展示和对应动作，不替代业务方对内容真实性的审核。

## 8. 交互与状态规则

| 状态 | 处理 |
| --- | --- |
| 入口默认状态 | 位于页面末尾，可点击，使用当前发布语言的固定联系文案 |
| 弹窗打开 | 展示有效联系方式；背景内容不可误操作 |
| 单项有效 | 只展示该项，不保留另外两项的空占位 |
| 两项或三项有效 | 按电话、邮箱、官网顺序展示 |
| 单项运行时失效 | 隐藏该项，保留其他有效项 |
| 全部运行时失效 | 弹窗显示局部错误和关闭操作；页面主体继续可用 |
| 弹窗关闭 | 恢复原页面临时状态；键盘焦点返回入口 |

## 9. 数据与配置说明

建议由页面从项目级公共联系数据读取：

- `project.contact.phone`
- `project.contact.email`
- `project.contact.website`

最终稳定数据键以 `04-项目内容数据与素材字典.md` 为准。

约束：

- 三个页面读取同一项目公共联系数据，不建立页面专用联系方式副本。
- 组件不自行请求个人销售联系人或第三方搜索结果。
- 联系方式使用页面实例的发布语言上下文；本期不提供语言切换。
- 组件固定启用，不提供 Widget 注册、拖拽排序或页面显隐配置。

## 10. 验收标准

| AC | Given | When | Then |
| --- | --- | --- | --- |
| AC-CONTACT-01 | 任一 MVP 页面正常发布 | 用户浏览至主要内容末尾 | 显示项目联系入口，不直接展开联系方式 |
| AC-CONTACT-02 | 至少一项有效联系方式 | 用户点击联系入口 | 弹窗打开并只展示有效项 |
| AC-CONTACT-03 | 仅电话有效 | 用户打开弹窗并点击电话 | 只显示电话并调用拨号能力，不自动拨出 |
| AC-CONTACT-04 | 仅邮箱有效 | 用户点击邮箱 | 调用邮件能力并带入收件地址 |
| AC-CONTACT-05 | 仅官网有效 | 用户点击官网 | 打开已配置的项目公共网址 |
| AC-CONTACT-06 | 三项均缺失或无效 | 运营尝试发布页面 | 发布被阻止，并提示补充至少一项有效联系方式 |
| AC-CONTACT-07 | 弹窗已打开 | 用户关闭弹窗 | 返回原页面并保留滚动、筛选、卡片或地图状态 |
| AC-CONTACT-08 | 某 Widget 局部失败 | 用户使用联系入口 | 联系组件仍可独立打开和使用 |
| AC-CONTACT-09 | 320px、375px、768px、1024px、1440px | 用户打开弹窗 | 内容可读、动作可操作，不出现被裁切且无法关闭的状态 |
| AC-CONTACT-10 | 当前发布语言确定 | 用户查看入口和弹窗 | 组件文案使用该语言，不自动混入其他语言 |

## 11. 风险与依赖

| 风险 / 依赖 | 类型 | 影响 | 应对 |
| --- | --- | --- | --- |
| 项目公共联系方式数据不完整 | 依赖 | 高 | 发布前执行至少一项有效校验 |
| VISTA C 弹窗详细规格不完整 | 设计依赖 | 中 | 复用现有弹窗类别，精确尺寸、位置和动效标记为待设计系统补充 |
| 设备不支持对应外部动作 | 运行风险 | 低 | 页面保持可用，联系方式仍以可读文字展示 |

## 12. 待确认事项

- 弹窗精确尺寸、移动端承载方式、进入/退出动效和背景遮罩规格：**待设计系统补充**，不影响本 PRD 的产品范围与开发逻辑确认。

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

- 必须把该能力实现为页面通用组件，不得注册为 Widget。
- 不得把联系入口扩展为预约、咨询、客服、分享或销售追踪。
- 不得因某个页面布局不同而复制三套联系方式数据或交互。
- 原型必须先验证 320px、375px 的入口可发现性、弹窗关闭和联系方式动作，再扩展 PAD/PC。