# 数据包部署指南

本文档说明如何部署众趣 VR 模型数据包到阿里云存储（oss），以实现静态资源的独立部署。

---

## 一、模型数据包结构

模型资源包由众趣侧编辑、制作产生，交付格式为 `{模型id}.zip`。解压后目录结构如下：

```text
{模型id}/                              # 模型数据主目录，名称为模型 ID
├── version.txt                        # 记录模型版本信息
├── background.jpg                     # 背景图
├── {版本时间戳}/                       # 模型版本目录，如 2025-06-11-13-26-28，一个模型可能存在多个版本号目录
│   ├── locations/                     # 全景切图资源
│   ├── pano_3k/                       # 3K（3000×1500）全景图资源
│   ├── resources/                     # 编辑产生的资源数据（标签、热点等）
│   ├── texture_high/                  # 高分辨率纹理文件（模型贴图）
│   └── {换装id}/                       # 换装资源目录（如有），存储换装切图
└── audio/                             # AI 讲房音频文件（如有）
```

### 目录说明

| 目录 | 说明 |
|------|------|
| `locations/` | 全景切图，用于全景漫游时的分块加载 |
| `pano_3k/` | 3K 分辨率全景图，用于快速预览或低带宽场景 |
| `resources/` | 编辑器产生的资源数据，包含标签、热点、导览路径等 |
| `texture_high/` | 高分辨率纹理，用于 Dollhouse 和户型图渲染 |
| `{换装id}/` | 换装资源，支持一键换装功能的全景图资源目录 |
| `audio/` | AI 讲房音频，支持智能讲房功能音频资源目录 |

### 目录截图示意
模型id目录
![模型id目录相关文件示意](../../screenshot/offine-package/模型id目录相关文件.png)

模型版本目录
![模型版本目录相关文件示意](../../screenshot/offine-package/模型版本目录相关文件.png)

模型版本目录其他文件相关说明
![模型版本-户型图图图片](../../screenshot/offine-package/模型版本目录-户型图图片.png)
![模型版本-其他资源](../../screenshot/offine-package/模型版本目录-其他相关资源.png)

---

## 二、部署方式

### 2.1 云存储部署（推荐）

将数据包上传至云存储（如阿里云OSS），保持原有目录结构：

```text
https://your-bucket.oss-cn-hangzhou.aliyuncs.com/
└── {模型id}/
    ├── version.txt
    ├── {版本号}/
    │   ├── locations/
    │   ├── pano_3k/
    │   └── ...
    └── audio/
```

### 2.2 company部署（仅需要部署一次即可）

需要额外上传一份{{your_host}}/company/company.txt的配置文件，用于zqsdk获取公司配置信息

众趣会提供一份公司配置文件夹， 这里包含了公司配置文件相关数据和目录：
company	公司相关资源文件夹
│ └─ resource	公司级资源文件夹，包含通用的加载动画、logo或视频素材
│   ├─ loading	loading资源文件
│   ├─ logo	logo资源文件
│   ├─ video	电视广告video资源文件
company.txt	记录公司级配置相关信息， 如UI展示权限配置，全景慢漫游参数配置等

<font color="red">注意： company.txt是您公司在众趣云平台侧配置的相关资源数据， 如loading资源，logo资源等文件。 如果是在您进行二次开发的情况下， 可以不关心resource文件夹数据（您可以使用任意的loading资源，logo资源），仅需要保证company.txt存在即可</font>


**注意事项**：

1. **CORS 配置**：需配置跨域访问，允许前端域名访问资源
2. **访问权限**：设置为公开读取或配置 CDN 加速（可选）
3. **目录结构**：必须保持与数据包一致，不可修改目录名称

---

## 三、SDK 配置

部署完成后，需在 SDK 初始化时配置资源路径前缀，使 SDK 从自有服务加载资源。

### 3.1 resourceRequestConf 参数说明

| 参数 | 说明 | 示例 |
|------|------|------|
| `resourceType` | 数据包资源类型-> zq_cloud: 众趣云平台资源  custom_host: 自定义域名资源 | `zq_cloud` |
| `customDomain` | 版本资源路径前缀 | `https://your_domain.com/` |

### 3.2 代码示例

```typescript
window.zqsdk.init({
  modelId: 'your_model_id',
  // (可选) 资源请求配置
  // 当众趣模型的静态资源需要在客户自己的服务器维护时使用
  // 需要设置资源请求的域名
  resourceRequestConf: {
      resourceType: 'custom_host', // zq_cloud: 众趣云平台资源  custom_host: 自定义域名资源， 当设置为zq_cloud时， customDomain的值无效， zqsdk会自动请求众趣云平台的资源
      customDomain: 'https://your_domain.com/',
  },
  complete: () => {
    // SDK 初始化完成
    window.housePlay.start()
  },
})
```

### 3.3 本仓库配置位置

在 `src/stores/vr.ts` 的 `initSdk` 函数中配置：

```typescript
window.zqsdk.init({
  modelId: id,
  // (可选) 资源请求配置
  // 当众趣模型的静态资源需要在客户自己的服务器维护时使用
  // 需要设置资源请求的域名
  resourceRequestConf: {
      resourceType: 'custom_host',
      customDomain: 'https://your_domain.com/',
  },
  complete: () => {
    // ...
  },
})
```

---

## 四、验证部署

1. **检查资源可访问**：在浏览器中直接访问资源 URL，确认可正常下载
   ```
   https://your-cdn.com/{模型id}/version.txt
   ```

2. **检查 CORS**：打开浏览器开发者工具，确认无跨域错误

3. **检查 SDK 加载**：在控制台查看网络请求，确认资源从配置的路径加载

---

## 五、常见问题

### 5.1 资源加载失败（404）

- 检查目录结构是否与数据包一致
- 检查 `resourceRequestConf.customDomain` 路径前缀是否正确
- 检查模型 ID 是否正确

### 5.2 跨域错误（CORS）

- 云存储需配置 CORS 规则，允许前端域名
- 自有服务器需添加 `Access-Control-Allow-Origin` 响应头

### 5.3 资源加载缓慢

- 建议使用 CDN 加速
- 开启 Gzip/Brotli 压缩
- 配置合理的缓存策略

---

## 六、相关文档

- [VR 初始化展示指南](../功能模块指南/VR初始化展示指南.md)
- [众趣 zqsdk 使用指南](../众趣zqsdk使用指南/众趣zqsdk使用指南.md)
