# estate-lookhouse-samplecode

众趣科技房产 VR 展示前端 Sample Code 项目，基于众趣 zqsdk 的展示端开发示例与二次开发指导。帮助开发者快速搭建并定制 VR 看房、户型图、楼层切换等能力。

---

## 介绍

本项目是**众趣科技**提供的房产/空间 VR 展示前端示例代码，面向需要将众趣 SDK 集成到自有业务系统的开发者。项目采用 Vue 3 + TypeScript + Vite 技术栈，实现全景看房、户型图、 dollhouse、标尺、标签、微信分享等完整展示能力，并预留移动端与二次扩展入口，便于按业务需求裁剪或扩展。

**适用场景**：

- 快速体验众趣 SDK 在 Web 端的展示效果
- 基于本仓库进行二次开发，接入自有品牌与业务逻辑
- 参考架构与目录规范，从零搭建与 SDK 对接的前端工程

---

## 快速了解

### 技术选型

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | ^3.5 | 前端框架，Composition API + `<script setup>` |
| TypeScript | ~5.9 | 类型系统 |
| Pinia | ^3.0 | 状态管理 |
| Vue Router | ^5.0 | 路由（当前单页） |
| Vite | ^7.3 | 构建与开发服务器 |
| SCSS | sass-embedded ^1.97 | 样式预处理器 |
| zqsdk | UMD 全局 | 众趣 VR 展示核心 SDK（通过 `index.html` 同步加载） |

运行环境：**Node.js** `^20.19.0` 或 `>=22.12.0`（见 `package.json` 的 `engines`）。

### 项目简介

- **单页应用**：唯一路由为 `/`，入口视图为 `HouseView`，根据设备选择 PC 或移动端布局（当前仅实现 PC）。
- **分层架构**：自顶向下为 `views` → `layouts` → `modules` → `components` → `stores` → `utils/config/types`，依赖单向向下，便于维护与扩展。
- **SDK 桥接**：所有与 zqsdk / housePlay 的交互集中在 `stores/vr.ts`，通过事件监听与转发驱动户型图、标尺、楼层等模块，避免业务组件直接依赖 SDK。

### 功能集合

| 功能 | 说明 |
|------|------|
| VR 全景 | 全景模式下的漫游与视角控制 |
| 户型图模式 | 全屏户型图，房间名称、宽高标尺、入户门、雷达位置 |
| 迷你户型图 | 右上角迷你图与雷达点位、朝向 |
| Dollhouse | 俯视户型 + 点击进入全景 |
| 模式切换 | 全景 / 户型图 / 娃娃屋 切换入口（右侧面板等） |
| 标尺 | 全景下标尺线（左/右/高），约 X.Xm 展示 |
| 标签 | 全景内标签显示开关 |
| 帮助 | 帮助说明/引导 |
| 楼层 | 多楼层时的楼层列表与切换（含「全部楼层」） |
| 微信分享 | 二维码弹层，分享当前页链接 |
| 免责声明 / 介绍 / 公司 Logo | 底部栏与品牌相关 UI |
| 房源详情 | 顶部标题栏 + 详情面板（房源信息、地图、小区照片） |
| AI 讲房 | AI 语音讲解，含房源信息、地图、图片轮播、航拍等展示模块 |
| 一键换装 | 全景模式下的装修风格切换（分屏/全屏对比） |
| 导览 | 场景导览面板，支持场景列表与快速跳转 |
| 多语言 | 中文/英文/日文切换 |

### 项目模块说明

- **`src/views/`**：页面级入口，当前仅 `HouseView.vue`，负责选择 PC/Mobile 布局。
- **`src/layouts/pc/`**：PC 布局编排，`PcHouseLayout.vue` 引入并排列所有 PC 业务组件（VR 播放器、户型图、底部栏、标尺、微信二维码等）。
- **`src/modules/pc/`**：PC 端业务组件，如 `NestVrPlayer`、`NestFloorPlan`、`NestBottomBar`、`NestPanoSize`、`NestWechatQrOverlay` 等。
- **`src/components/common/`**：跨平台复用 UI 组件（如 `NestRadarIcon`、`NestLoadingOverlay`、`NestErrorDisplay`、`NestModeButton`），不直接依赖 Store。
- **`src/stores/`**：Pinia 状态与业务逻辑，`vr.ts` 为 SDK 生命周期与事件唯一入口，`floor-plan.ts`、`toolbar.ts`、`floor.ts` 等负责户型图、工具栏、楼层等状态。
- **`src/config/`**：全局常量（如 `VR_MODE`、`SDK_CONTAINER_ID`）。
- **`src/types/`**：TypeScript 类型定义（VR/SDK、户型图等），由 `index.ts` 统一导出。
- **`src/utils/`**：纯工具函数（URL 参数、SDK 数据转换等）。
- **`src/composables/`**：可复用逻辑（如设备检测、二维码生成）。
- **`public/js/`**：jQuery、TWEEN、zqsdk 的 UMD 脚本，**加载顺序固定**：jQuery → TWEEN → zqsdk → 应用入口。

更细的目录职责、命名与扩展流程见 **[二次开发规范文档](docs/DEVELOPMENT.md)**。

---

## 环境部署

### 前置要求

- **Node.js**：`^20.19.0` 或 `>=22.12.0`
- **npm**：建议使用 npm 9+（或与项目锁文件一致的包管理器）

### 安装依赖

在项目根目录执行：

```bash
npm install
```

如需使用国内镜像，可配置 `.npmrc` 或使用 `npm install --registry=...`。

### 配置说明

- **模型 ID**：应用从 URL 查询参数 **`m`** 读取模型 ID，用于初始化 zqsdk。例如：  
  `http://localhost:5173/?m=your_model_id`
- **SDK 资源**：`public/js/` 下的 `jquery.min.js`、`tween.umd.js`、`zqsdk.js` 需由众趣或项目方提供，并保证在 `index.html` 中的加载顺序不变。
- **全局配置**：部分能力（如标尺单位）依赖 `window.conf`（如 `unit_conversion_value`、`unit_name`），由 SDK 或宿主页面注入，详见业务/SDK 文档。

---

## 启动

### 开发环境

```bash
npm run dev
```

启动后访问 **http://localhost:5173/**，并在 URL 中加上模型参数，例如：

```text
http://localhost:5173/?m=你的模型ID
```

无 `m` 参数时，应用会提示缺少模型 ID，无法进入 VR 展示。

### 生产构建

```bash
npm run build
```

构建前会先执行 **类型检查**（`vue-tsc --build`），通过后输出到 `dist/`。部署时将 `dist` 目录及 `public` 中的静态资源一并发布，并保证 `index.html` 中引用的 `/js/*.js` 路径可访问。

### 预览构建结果

```bash
npm run preview
```

用于本地预览 `dist` 内容，同样需带 `?m=模型ID` 访问。

---

## 常用脚本

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动 Vite 开发服务器（热更新） |
| `npm run build` | 类型检查 + 生产构建 |
| `npm run preview` | 预览生产构建结果 |
| `npm run type-check` | 仅执行 TypeScript 类型检查（vue-tsc） |
| `npm run lint` | 执行 oxlint 与 eslint（含自动修复） |
| `npm run format` | 使用 oxfmt 格式化 `src/` 代码 |

---

## 项目结构概览

```text
estate-lookhouse-samplecode/
├── public/                 # 静态资源（不经过 Vite 处理）
│   ├── favicon.ico
│   └── js/                 # 必须保持加载顺序：jQuery → TWEEN → zqsdk
│       ├── jquery.min.js
│       ├── tween.umd.js
│       └── zqsdk.js
├── src/
│   ├── main.ts             # 应用入口
│   ├── App.vue             # 根组件与全局样式
│   ├── config/             # 常量（VR_MODE、SDK_CONTAINER_ID 等）
│   ├── types/              # 类型定义与统一导出
│   ├── utils/              # 工具函数（URL、SDK 数据处理）
│   ├── composables/        # 组合式函数（设备检测、二维码等）
│   ├── stores/             # Pinia（vr、floor-plan、toolbar、floor）
│   ├── components/common/  # 跨平台公共组件
│   ├── modules/pc/         # PC 端业务组件
│   ├── layouts/pc/         # PC 布局编排
│   ├── views/              # 页面视图（HouseView）
│   ├── router/             # 路由配置
│   └── assets/             # 需经构建的资源（图标、图片等）
├── docs/
│   └── DEVELOPMENT.md      # 二次开发规范与扩展指引
├── versions/               # 版本记录
├── index.html
├── vite.config.ts
├── tsconfig.json
└── package.json
```

---

## 相关文档

### 指南文档

- **[众趣科技房产VR展示指导文档总览](docs/guides/功能模块指南/众趣科技房产VR展示指导文档总览.md)**：众趣房产VR展示的整体介绍和功能概览。
- **[VR初始化展示指南](docs/guides/功能模块指南/VR初始化展示指南.md)**：VR展示的初始化和基本展示流程。
- **[户型图集成指南](docs/guides/功能模块指南/户型图集成指南.md)**：户型图功能的集成和使用指南。
- **[标尺显隐集成指南](docs/guides/功能模块指南/标尺显隐集成指南.md)**：标尺功能的集成和使用指南。
- **[导览集成指南](docs/guides/功能模块指南/导览集成指南.md)**：导览功能的集成和使用指南。
- **[AI讲房集成指南](docs/guides/功能模块指南/AI讲房集成指南.md)**：AI讲房功能的集成和使用指南。
- **[房源详情集成指南](docs/guides/功能模块指南/房源详情集成指南.md)**：房源详情集成指南。

### 开发文档

- **[二次开发规范指南](docs/guides/二次开发规范指南/二次开发规范指南.md)**：目录职责、命名与编码规范、Store 划分、SDK 事件桥接、新增功能的标准流程、开发命令与快速参考表。


---

## 版本与许可

- 版本记录见 `versions/` 目录。
- 本仓库为众趣科技提供的示例与指导项目，使用与许可请以众趣科技官方说明为准。
