修复点位楼层跳转并优化模型加载缓存

docs/QA/h5-model-cache-network-verification-2026-07-02.md

@@ -0,0 +1,76 @@
+# 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 持久缓存策略；如需跨刷新复用，应作为后续专项处理。