# 数据包资源替换指南汇总

本文档说明在使用众趣 VR 模型**离线数据包**的场景下，当触发「一键换装」或「AI 讲房」相关异步任务后，如何将回调返回的增量资源正确替换到已部署的数据包中。

> **前置阅读**：请先阅读 [数据包部署指南](./数据包部署指南.md)，了解完整的数据包目录结构与部署方式。

---

## 一、背景说明

众趣模型离线数据包部署到您的服务器后，部分功能模块（一键换装、AI 讲房）可能会在后续产生**增量资源更新**。当您在众趣平台触发相关异步任务（如一键换装、AI讲房）后，任务完成时众趣会向您的服务器回调对应的增量数据包。您需要将这些增量数据包解压，并按照本文档说明的规则，替换到已部署的模型数据包对应目录中。

### 1.1 适用场景

| 场景 | 触发条件 | 回调内容 |
|------|----------|----------|
| 一键换装资源更新 | 在众趣平台对模型进行换装编辑并发布 | 换装相关配置文件与换装全景切图资源 |
| AI 讲房资源更新 | 在众趣平台对模型配置 AI 讲房数据并发布 | 讲房配置文件与音频资源 |

### 1.2 已部署数据包目录结构回顾

替换操作涉及的目录层级如下（完整结构请参阅 [数据包部署指南](./数据包部署指南.md)）：

```text
{模型id}/                              # 模型数据主目录
├── version.txt                        # 模型版本信息
├── audio/                             # AI 讲房音频文件目录
├── {版本时间戳}/                       # 模型版本目录（如 2025-06-11-13-26-28）
│   ├── settings.txt                   # 模型配置文件
│   ├── settings_local.txt             # 本地化配置文件
│   ├── panoDress.txt                  # 换装配置文件（换装场景）
│   ├── locations/                     # 全景切图资源
│   ├── pano_3k/                       # 3K 全景图资源
│   ├── resources/                     # 编辑产生的资源数据
│   ├── texture_high/                  # 高分辨率纹理文件
│   └── {换装id}/                       # 换装全景切图资源目录（换装场景）
└── ...
```

---

## 二、一键换装 — 离线数据包资源替换

当您在众趣平台对模型触发换装流程异步任务后，任务完成时众趣会回调「换装数据相关资源」的增量数据包。收到后需要解压并替换以下文件和目录。

### 2.1 需替换的文件清单

替换操作涉及**两个层级**的目录：

#### 模型 id 目录（`{模型id}/`）

| 序号 | 文件/目录 | 类型 | 说明 |
|------|-----------|------|------|
| 1 | `version.txt` | 单个文件 | 模型版本信息，换装发布后版本号会更新 |

#### 模型版本目录（`{模型id}/{版本时间戳}/`）

| 序号 | 文件/目录 | 类型 | 说明 |
|------|-----------|------|------|
| 1 | `settings.txt` | 单个文件 | 模型配置文件，包含换装相关配置数据 |
| 2 | `settings_local.txt` | 单个文件 | 本地化配置文件，包含换装本地化配置 |
| 3 | `panoDress.txt` | 单个文件 | 换装配置文件，记录换装方案与映射关系 |
| 4 | `{换装id}/` | **整个目录** | 换装全景切图资源目录，包含换装后的全景图切片 |

### 2.2 替换目录结构示意

```text
{模型id}/
├── version.txt                        ← 替换此文件
└── {版本时间戳}/
    ├── settings.txt                   ← 替换此文件
    ├── settings_local.txt             ← 替换此文件
    ├── panoDress.txt                  ← 替换此文件
    └── {换装id}/                       ← 替换整个目录
        ├── (换装全景切图文件...)
        └── ...
```

### 2.3 替换步骤

1. **接收回调数据包**：众趣异步任务完成后，会向您配置的回调地址推送换装增量数据包（压缩包格式）。
2. **解压数据包**：将收到的压缩包解压到临时目录。
3. **替换模型 id 目录文件**：
   - 将解压后的 `version.txt` 覆盖到 `{模型id}/version.txt`。
4. **替换模型版本目录文件**：
   - 将解压后的 `settings.txt` 覆盖到 `{模型id}/{版本时间戳}/settings.txt`。
   - 将解压后的 `settings_local.txt` 覆盖到 `{模型id}/{版本时间戳}/settings_local.txt`。
   - 将解压后的 `panoDress.txt` 覆盖到 `{模型id}/{版本时间戳}/panoDress.txt`。
5. **替换换装资源目录**：
   - 将解压后的 `{换装id}/` 整个目录覆盖到 `{模型id}/{版本时间戳}/{换装id}/`。
   - **注意**：如果该换装 id 目录已存在，建议先删除旧目录再复制新目录，确保不残留旧文件。
6. **验证替换结果**：通过浏览器访问替换后的资源 URL，确认文件可正常加载。

### 2.4 截图示意

#### 模型 id 目录 — version.txt 文件位置

![换装离线数据包-模型id目录版本文件](../../screenshot/pano-dress/换装离线数据包模型版本文件.png)

#### 模型版本目录 — 需替换的文件与目录

![换装离线数据包-模型版本目录资源替换](../../screenshot/pano-dress/换装离线数据包-模型版本目录资源替换.png)

### 2.5 注意事项

1. **版本时间戳目录**：一个模型可能存在多个版本时间戳目录（如 `2025-06-11-13-26-28`），请确认替换到正确的版本目录中。可通过 `version.txt` 中记录的版本信息确定当前生效的版本目录。
2. **换装 id 目录**：换装 id 由众趣平台生成，每次换装任务可能产生不同的换装 id。请以回调数据包中的实际目录名为准。
3. **文件覆盖**：`settings.txt`、`settings_local.txt`、`panoDress.txt` 均为**整体覆盖**，不支持增量合并。
4. **目录完整性**：`{换装id}/` 目录需**整体替换或新增**，不要仅替换部分文件，否则可能导致换装全景图加载异常。

---

## 三、AI 讲房 — 离线数据包资源替换

当您在众趣平台对模型配置 AI 讲房数据并发布后，众趣推送的离线数据包中会包含 AI 讲房相关资源（如讲房音频文件、配置信息等）。收到后需要解压并替换以下文件和目录。

### 3.1 需替换的文件清单

替换操作同样涉及**两个层级**的目录：

#### 模型版本目录（`{模型id}/{版本时间戳}/`）

| 序号 | 文件/目录 | 类型 | 说明 |
|------|-----------|------|------|
| 1 | `settings.txt` | 单个文件 | 模型配置文件，包含 `vr_speak_data` 讲房配置数据 |
| 2 | `settings_local.txt` | 单个文件 | 本地化配置文件，包含讲房本地化配置 |

#### 模型 id 目录（`{模型id}/`）

| 序号 | 文件/目录 | 类型 | 说明 |
|------|-----------|------|------|
| 1 | `audio/` | **整个目录** | AI 讲房音频资源目录，包含各段落的讲解音频文件 |

### 3.2 替换目录结构示意

```text
{模型id}/
├── audio/                             ← 替换整个目录
│   ├── (讲房音频文件...)
│   └── ...
└── {版本时间戳}/
    ├── settings.txt                   ← 替换此文件
    └── settings_local.txt             ← 替换此文件
```

### 3.3 替换步骤

1. **接收回调数据包**：众趣异步任务完成后，会向您配置的回调地址推送讲房增量数据包（压缩包格式）。
2. **解压数据包**：将收到的压缩包解压到临时目录。
3. **替换模型版本目录文件**：
   - 将解压后的 `settings.txt` 覆盖到 `{模型id}/{版本时间戳}/settings.txt`。
   - 将解压后的 `settings_local.txt` 覆盖到 `{模型id}/{版本时间戳}/settings_local.txt`。
4. **替换音频资源目录**：
   - 将解压后的 `audio/` 整个目录覆盖到 `{模型id}/audio/`。
   - **注意**：如果 `audio/` 目录已存在，建议先删除旧目录再复制新目录，确保不残留旧的音频文件。
5. **验证替换结果**：通过浏览器访问替换后的音频资源 URL，确认文件可正常加载。

### 3.4 截图示意

#### 模型 id 目录 — audio 音频资源目录位置

![AI讲房音频文件在离线数据包位置](../../screenshot/introduce/AI讲房资源替换目录.png)

#### 模型版本目录 — settings.txt 与 settings_local.txt 文件位置

![AI讲房离线数据包setting替换示意](../../screenshot/introduce/AI讲房离线数据包setting替换示意.png)

### 3.5 注意事项

1. **audio 目录位置**：`audio/` 目录位于 `{模型id}/` 根目录下，与版本时间戳目录同级，**不在**版本时间戳目录内部。
2. **settings.txt/setting_local.txt 包含讲房配置**：`settings.txt` 中的 `vr_speak_data` 字段存储了讲房段落配置、房源信息等数据，是 SDK 判断模型是否支持讲房的关键依据。
3. **音频文件格式**：音频文件通常为 MP3 格式，文件名由众趣平台生成，请保持原文件名不变。
4. **目录完整性**：`audio/` 目录需**整体替换**，不要仅替换部分音频文件，否则可能导致讲房过程中部分段落无声音。

---

## 四、替换文件汇总对照表

以下汇总两个功能模块涉及的所有替换文件，便于快速查阅：

| 文件/目录 | 所在层级 | 一键换装 | AI 讲房 | 说明 |
|-----------|----------|:--------:|:-------:|------|
| `version.txt` | 模型 id 目录 | ✅ | — | 模型版本信息 |
| `audio/` | 模型 id 目录 | — | ✅ | 讲房音频资源（整个目录） |
| `settings.txt` | 模型版本目录 | ✅ | ✅ | 模型配置文件 |
| `settings_local.txt` | 模型版本目录 | ✅ | ✅ | 本地化配置文件 |
| `panoDress.txt` | 模型版本目录 | ✅ | — | 换装配置文件 |
| `{换装id}/` | 模型版本目录 | ✅ | — | 换装全景切图资源（整个目录） |

> **提示**：`settings.txt` 和 `settings_local.txt` 在两个功能模块中均需替换。如果同时收到换装和讲房的回调数据包，请注意替换顺序，以最新的回调数据包为准。

---

## 五、通用替换流程

无论是换装还是讲房的资源替换，建议遵循以下通用流程：

### 5.1 标准替换流程

```text
接收回调数据包 → 解压到临时目录 → 备份原文件 → 执行替换 → 验证资源可访问 → 清理临时文件
```

### 5.2 详细步骤

1. **接收回调**：在您的服务端配置回调接口，接收众趣推送的增量数据包。
2. **解压数据包**：将压缩包解压到服务器临时目录。
3. **备份原文件**（推荐）：在覆盖前，将原有文件备份到独立目录，便于出现问题时快速回滚。
4. **执行替换**：
   - 对于**单个文件**（如 `settings.txt`）：直接覆盖目标路径的同名文件。
   - 对于**整个目录**（如 `audio/`、`{换装id}/`）：先删除目标路径的旧目录，再将新目录复制到目标路径。
5. **验证资源**：替换完成后，通过浏览器或 curl 访问关键资源 URL，确认可正常加载。
6. **清理临时文件**：验证无误后，删除临时解压目录和备份文件（或按策略保留备份）。

### 5.3 注意事项

1. **CORS 配置**：替换后的资源需确保 CORS 配置正确，允许前端域名跨域访问。详见 [数据包部署指南 — 注意事项](./数据包部署指南.md)。
2. **CDN 缓存刷新**：如果使用了 CDN 加速，替换文件后需要**刷新 CDN 缓存**，否则用户可能仍加载到旧资源。
3. **并发替换**：如果同时收到多个回调（如同一模型的换装和讲房同时完成），建议按回调时间顺序串行处理，避免文件写入冲突。
4. **目录结构不可修改**：替换时必须保持原有目录结构和文件名，不可重命名或调整层级，否则 SDK 将无法正确加载资源。

---

## 六、常见问题

### 6.1 替换后换装功能不生效

- 检查 `panoDress.txt` 是否已正确替换到模型版本目录下。
- 检查 `{换装id}/` 目录是否完整复制，目录名是否与 `panoDress.txt` 中记录的换装 id 一致。
- 检查 `settings.txt` 是否已替换，其中应包含 `has_decoration` 相关配置。
- 检查 `version.txt` 是否已更新。

### 6.2 替换后讲房功能不生效

- 检查 `settings.txt` 是否已正确替换，其中应包含 `vr_speak_data` 字段。
- 检查 `audio/` 目录是否已完整替换到模型 id 目录下（注意：是模型 id 目录，不是版本目录）。
- 检查音频文件是否可正常访问，URL 路径是否正确。

### 6.3 替换后部分资源加载失败（404）

- 确认替换的目标目录路径正确，特别注意模型 id 目录与模型版本目录的区别。
- 确认文件名未被修改（包括大小写）。
- 确认云存储（如 OSS）上的文件已成功上传，可通过管理控制台核实。

### 6.4 替换后 CDN 仍返回旧资源

- 替换文件后需刷新 CDN 缓存，可通过云服务商控制台提交 URL 刷新或目录刷新。
- 建议对频繁更新的资源设置较短的缓存过期时间。

### 6.5 同时收到换装和讲房的回调数据包

- 两个功能模块的 `settings.txt` 和 `settings_local.txt` 可能存在重叠，请以**时间戳较新**的回调数据包中的文件为准。
- 建议按回调时间顺序串行处理，避免旧数据覆盖新数据。

---

## 七、相关文档

- [数据包部署指南](./数据包部署指南.md) — 完整的数据包结构与部署方式
- [一键换装集成指南](../功能模块指南/一键换装集成指南.md) — 换装功能的前端集成说明
- [AI 讲房集成指南](../功能模块指南/AI讲房集成指南.md) — 讲房功能的前端集成说明
