# HOMEVISTA C端 3D 大楼独立功能页 PRD

## 修订记录

| 版本 | 日期 | 修改人 | 修改内容 |
|---|---|---|---|
| v0.1 | 2026-07-13 | Codex | 建立自有完整 3D 大楼应用的独立功能页 PRD |

## 一、文档目的与适用对象

本文档定义 C端如何以独立页面引用 HOMEVISTA 自有的完整 3D 大楼应用。该页用于产品、设计、开发、测试和 Codex 判断页面承载边界、异常处理与验收，不定义 3D 应用内部的模型交互。

## 二、背景与目标

现有 3D 大楼能力可独立承担“理解项目建筑整体、楼栋与楼层关系”的顾客任务。其完整交互由 HOMEVISTA 自有 3D 应用提供，因此本页不将 3D 应用拆回普通内容区块或页面私有组件，而是以全屏承载方式将其纳入 C端访问路径。

本页目标：

- 让顾客可从 C端独立进入并使用 3D 大楼应用。
- 保持 C端来源页与应用之间的返回路径。
- 在引用配置或应用不可用时，不发布空白页面，也不伪造应用内部状态。

## 三、版本范围与明确不做

### 3.1 本期包含

- 配置并引用 HOMEVISTA 自有的完整 3D 大楼应用。
- 以全屏承载形态提供打开、加载、不可用与返回路径。
- 按 `06` 消费页面访问控制，按 `07` 记录页面级访问与异常结果。

### 3.2 明确不做

- 不在本页面重做 3D 模型旋转、缩放、楼栋 / 楼层选择等应用内部交互。
- 不将应用内部模型、楼栋或楼层数据复制为本页独立内容资产。
- 不定义 3D 引擎、模型加载、跨域策略、应用账号体系或应用内部统计实现。
- 不将该页扩展为 CAVE、VR、大屏或案场演示页面。

## 四、用户角色与核心场景

| 角色 | 进入场景 | 目标 |
|---|---|---|
| 顾客 / 外部访问者 | 从项目介绍、分享链接或其他 C端页面进入 | 查看项目建筑整体与可用的楼栋、楼层关系 |
| 销售人员 | 向顾客分享独立链接 | 让顾客直接进入既有 3D 大楼体验，不承担现场演示流程 |

## 五、页面输入与模块组合

| 项目 | 定义 |
|---|---|
| 页面输入 | 已启用的引用地址、页面名称、HOMEVISTA 作为页面提供方、来源页或独立访问来源、页面访问规则 |
| 当前引用地址 | `https://3d.homevista.jp/demo_v1/`；该地址当前仅作为引用示例与验收基准 |
| 主承载业务 Widget | `M-04 3D 大楼`：定义顾客任务、可用资产关系与业务边界 |
| 承载模块 | `M-25 外部页面嵌入`：以全屏容器承载自有完整应用，不负责应用内部交互 |
| 辅助模块 | 无必需辅助模块；项目名称或必要说明可按页面配置补充 |
| 转化模块 | 本页不强制调用；有效下一步可为返回来源页或进入已配置关联内容 |
| 通用组件 | 身份验证、导航与返回组件；访问控制结果由 `06` 提供。每次访问先判定，受限访问必须先验证。 |
| 不可用处理 | 引用地址、责任主体或页面配置缺失时页面不得发布；应用加载失败时显示不可用状态与返回路径 |

## 六、用户用例

### UC-001：进入并使用 3D 大楼应用

**前置条件**：页面已发布，引用配置与访问条件满足。

1. 顾客从 C端来源页或独立链接进入本页。
2. 页面以全屏承载方式打开自有 3D 大楼应用。
3. 顾客在应用内完成查看建筑、楼栋或楼层等应用自身支持的操作。
4. 顾客通过返回动作回到 C端来源页；独立访问时回到页面配置的安全退出路径。

**结果**：顾客能够使用完整 3D 应用，且不会因退出应用而丢失 C端访问路径。

### UC-002：应用不可用

**前置条件**：页面已发布，但应用地址加载失败、超时、被浏览器拦截或无法嵌入。

1. 页面识别到可检测的引用失败。
2. 页面不展示空白承载区域，不尝试替代应用内部内容。
3. 页面展示不可用提示和返回来源页入口；如无来源页，提供页面配置的安全退出路径。

**结果**：顾客不会停留在不可恢复的空白页面。

## 七、功能需求

| 功能 ID | 功能 | 规则 |
|---|---|---|
| F-01 | 自有应用引用 | 页面仅引用已配置的 HOMEVISTA 自有完整应用；引用地址、提供方和责任主体缺一不可。 |
| F-02 | 全屏承载 | 3D 应用作为完整页面承载，不与普通页面内容区块混排。具体嵌入技术由实现方案确定。 |
| F-03 | 应用边界 | 应用内部的信息架构、模型交互、权限、错误与统计由 3D 应用负责；C端不重复定义。 |
| F-04 | 返回路径 | 从 C端来源进入时应返回来源页；独立访问时使用页面配置的安全退出路径。 |
| F-05 | 页面级异常 | 可检测的加载失败、超时、浏览器拦截或禁止嵌入时，显示不可用状态与返回入口。 |
| F-06 | 权限与统计引用 | 页面访问限制以 `06` 为准；页面进入、引用失败和返回等事件以 `07` 的统一口径为准。 |
| F-07 | 身份验证模块 | 公开策略不要求登录；受限页面在承载应用前调用身份验证。验证取消、失败、过期或服务不可用时不得加载应用，显示重试和返回路径。 |

## 八、交互与状态规则

| 状态 | 触发条件 | 页面处理 |
|---|---|---|
| 默认 | 引用配置与访问条件完整 | 打开完整 3D 应用承载页 |
| 加载中 | 应用尚未完成加载 | 显示加载状态；不得将其误判为应用内部错误 |
| 不可发布 | 未配置引用地址、页面提供方或责任主体 | 不生成对外页面入口 |
| 引用不可用 | 可检测的加载失败、超时、浏览器拦截或禁止嵌入 | 显示不可用提示、返回来源页或安全退出路径 |
| 应用内部错误 | C端无法识别或无法控制的应用内部异常 | 由 3D 应用处理；C端仅保留退出或返回能力 |

### 8.1 页面视觉层级与响应式

- 3D 应用始终是全屏内容主体；C端仅保留不遮挡主体的返回、加载、验证和异常状态层。
- 验证未完成、引用失败或不可发布时，不加载或不暴露应用内容；状态层提供重试和返回。
- 移动端保持同一全屏内容逻辑，返回与状态入口避开系统手势区；不在容器页复刻应用内部导航。

## 九、验收标准

- 访问已发布页面时，能够打开配置的完整 3D 大楼应用，而非静态截图或普通内容区块。
- 页面仅将自有应用作为全屏承载对象；不复制或重定义应用内部功能。
- 引用配置缺失时，页面不可发布。
- 可检测的引用不可用状态有明确提示和返回路径。
- 从 C端来源进入时，返回后能够回到来源页；独立访问时不会进入不可恢复的空白路径。
- 本页的访问与异常事件可以按 `07` 的统一规则记录，不新增孤立统计口径。

## 十、待确认问题

| 编号 | 待确认问题 | 对页面的影响 |
|---|---|---|
| 3D-Q01 | 正式项目是否均使用独立的 3D 应用地址，还是复用当前地址并通过项目参数切换 | 决定引用配置模型和页面输入 |
| 3D-Q02 | 全屏承载采用受控嵌入、同窗口跳转还是其他实现方式 | 影响返回路径、加载失败识别和技术验收；不改变产品边界 |

## 十一、供 Codex 使用的执行说明

- 不得把 3D 应用内部交互拆为新的 C端页面需求或普通 UI 组件。
- 页面实现只负责引用配置、全屏承载、访问控制结果、页面级异常与返回路径。
- 如 3D 应用需要项目、楼栋或来源上下文，应先补充第十章问题后再定义参数，不得自行假设 URL 参数或模型数据结构。