# H5 模型加载缓存 Network 验证记录

日期：2026-07-02

## 验证范围

- 项目：`frontend-miniapp`
- 数据源模式：`VITE_DATA_SOURCE_MODE=sdk`
- 渲染方式：H5 现有 ThreeMap 本地渲染
- 验证工具：Playwright + 本机 Chrome Network 请求监听
- 启动命令：`pnpm dev:h5`
- 访问地址：`http://localhost:5174/`（`5173` 被占用后由 Vite 自动切换）

本次验证未启用 SGS SDK iframe 渲染，SDK 仍只作为数据/API 来源。

## 操作路径

1. 首次进入馆内 3D，加载默认全楼/外观模型。
2. 点击“馆内”进入默认 1F 单楼层模型。
3. 从单楼层切换到多楼层。
4. 再切回 1F 单楼层。
5. 打开搜索页，选择“服务台”结果，进入设施详情并触发点位 focus。
6. 离开到“讲解”tab，再回到“馆内”地图。

## 问题复现

在 `GuideModelLoadManager` 默认 `maxEntries=4` 时，单层进入后再切换多层，已加载过的模型会被 LRU 提前淘汰，导致同一 GLB 再次请求：

| 模型 | 切多层前请求次数 | 切多层后请求次数 |
| --- | ---: | ---: |
| `L1_draco.glb` | 1 | 2 |
| `L1.5_draco.glb` | 1 | 2 |
| `L-1_draco.glb` | 1 | 2 |

根因分类：LRU source cache 容量过小。当前 SDK 数据包含 8 个可导览楼层，多层加载会顺序触达多个 GLB；`maxEntries=4` 无法覆盖单层、相邻预加载、多层展开和全楼模型的运行期复用需求。

## 修复

已在 `src/services/model/GuideModelLoadManager.ts` 将默认 source cache 容量调整为 `10`，用于覆盖：

- 当前 8 个可导览楼层模型；
- 全楼/外观模型；
- 相邻楼层预加载余量。

`ThreeMap.vue` 普通 `onUnmounted` / `disposeScene` 未调用 `guideModelLoadManager.clearAll()`，运行期组件重建不会清空全局 source cache。

## 修复后 Network 统计

修复后重新执行同一路径，关键 GLB 请求次数如下：

| 模型 URL | 进入单层后 | 切多层后 | 切回单层后 | 点位/详情 focus 后 | 讲解 tab 返回馆内后 |
| --- | ---: | ---: | ---: | ---: | ---: |
| `/museum-assets/optimized/20260617/draco_EXTERIOR.glb_1781708354536.glb` | 1 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L1_draco.glb` | 1 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L1.5_draco.glb` | 1 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L-1_draco.glb` | 1 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L5_draco.glb` | 0 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L4_draco.glb` | 0 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L3_draco.glb` | 0 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L2_draco.glb` | 0 | 1 | 1 | 1 | 1 |
| `/app-api/gis/sdk/minio/museum-assets/sgs-map/glb/1/V20260627093736_e73e3/models/L-2_draco.glb` | 0 | 1 | 1 | 1 | 1 |

结论：同一个实际 GLB 在运行期全局缓存有效范围内不再重复发起网络请求。

## 质量验证

- `pnpm type-check`：通过
- `pnpm lint`：通过
- `pnpm build:h5`：通过，仅有既有 Sass deprecation warnings

## 剩余风险

- 运行期内存缓存无法跨页面刷新；刷新页面后重新请求 GLB 属于预期行为。
- `maxEntries=10` 会比 `4` 保留更多 GLB source，移动端内存需在真机上继续观察。
- 如果 `/app-api/gis/sdk/minio/...` 或后端 `/gis/sdk/minio` 偶发 500，仍需继续排查 `smart-navigation-system` 的 MinIO 代理层。
- 本轮未新增 Service Worker / Cache-Control 持久缓存策略；如需跨刷新复用，应作为后续专项处理。