馆内/馆外导览首页：src/pages/index/index.vue
- 馆外 2D 参考地图：腾讯地图容器、主入口参考、来馆参考面板。
- 馆内 3D 展示：基于 Three.js/GLB 的 H5 三维模型渲染、全楼/单楼层切换、楼层选择、POI 点击和高亮。
- POI 搜索与位置预览：通过导览用例读取楼层、POI、位置预览数据。
- 路线状态：当前 NAV_ROUTE_GRAPH_READY = false，产品口径为“位置预览/路线预览”，不声明正式室内导航、实时定位或到达引导。
讲解业务
- 讲解入口：首页“讲解”业务流和 src/pages/explain/list.vue。
- 展厅、业务单元、讲解点选择：ExplainHallSelect、ExplainList、展品/展厅详情页。
- 音频与图文讲解：通过 ExplainUseCase、AudioPlayInfoRepository、MediaRepository 读取播放信息、讲解词和不可用状态；无真实音频时显示图文/不可用口径。
- 讲解到导览的位置联动：通过稳定的 poiId、hallId、floorId 等领域 ID 解析位置预览目标。
数据源切换
- static：默认模式，读取本地 static/nav-assets 和 static/guide-data。
- api：读取 SGS 后端 API 的楼层、POI、空间、导航目的地等数据，仍可使用本地渲染边界。
- sdk：当前代码会切到 SGS 后端数据仓库，并保留 SDK/H5 地图基座配置；实际 SDK renderer 仍需通过独立渲染边界落地。

技术栈

uni-app + Vue 3 + TypeScript
Vite
Three.js
SCSS / CSS Variables
pnpm 9
Node.js >=20 <25

目录结构

frontend-miniapp/
├── src/
│   ├── App.vue
│   ├── main.ts
│   ├── pages.json
│   ├── manifest.json
│   ├── components/
│   │   ├── audio/              # 音频播放器与悬浮播放入口
│   │   ├── content/            # 展品、展厅、设施卡片
│   │   ├── explain/            # 讲解列表、展厅/单元/讲解点选择
│   │   ├── map/                # TencentMap、ThreeMap、楼层/标记面板
│   │   ├── navigation/         # 导览页面框架、顶部业务切换、导览 Shell、路线面板
│   │   └── search/             # 搜索栏与搜索面板
│   ├── config/                 # 数据源、SDK、音频接口等运行配置
│   ├── data/
│   │   ├── adapters/           # 静态包/API/SDK 响应 -> 领域模型
│   │   ├── providers/          # 静态资源、SGS API、讲解内容提供者
│   │   └── mock/               # 显式开发 mock 数据
│   ├── domain/                 # 博物馆导览/讲解领域模型与 readiness gate
│   ├── repositories/           # Guide、Route、Explain、Media、Audio 数据访问边界
│   ├── services/               # 第三方运行时服务封装
│   ├── usecases/               # guide/explain/route 业务用例
│   ├── utils/
│   └── view-models/
├── static/
│   ├── guide-data/             # 当前讲解/内容静态数据包
│   ├── nav-assets/             # H5 三维导览 GLB/manifest/POI/route 数据包
│   └── sgs-map-sdk/            # SGS Map SDK 交付文档与静态 SDK 包
├── public/static/Fonts/        # H5 字体资源
├── docs/                       # 数据接入、部署、QA、UX、PDCA 等文档
├── package.json
└── README.md

数据与架构边界

当前代码遵循以下数据流：

static nav-assets / static guide-data / SGS API / audio API
原始数据源：本地导览资源包、讲解静态数据、SGS 后端接口、音频播放接口
        ↓
Providers
数据提供层：负责读取静态文件或请求后端接口，处理加载、缓存、错误和基础可用性
        ↓
Adapters
数据适配层：把不同来源的字段、ID、楼层和分类转换成统一的博物馆领域模型
        ↓
Repositories
数据访问边界：向业务用例暴露稳定查询能力，隐藏静态包、API、SDK 响应差异
        ↓
UseCases
业务用例层：组织导览、讲解、搜索、位置预览、路线 readiness 和音频选择等业务规则
        ↓
ViewModels / Page State
页面状态/视图模型层：把领域数据整理成页面和组件可直接渲染的轻量结构
        ↓
Vue Components
展示组件层：只负责交互和呈现，不直接解析源数据、不直接调用后端或 SDK 原始协议

关键文件：

数据源配置：src/config/dataSource.ts
导览仓库选择：src/repositories/createGuideRepository.ts
导览用例：src/usecases/guideUseCase.ts
路线用例：src/usecases/guideRouteUseCase.ts
讲解用例：src/usecases/explainUseCase.ts
路线 readiness gate：src/domain/guideReadiness.ts
Three.js 渲染器：src/components/map/ThreeMap.vue
导览 Shell：src/components/navigation/GuideMapShell.vue

页面和组件不应直接解析静态资源包、后端响应字段或 SDK 原始事件；这些差异应留在 Provider/Adapter/Repository 层。

环境变量

默认可不配置 .env，项目会以 static 模式运行。常用变量如下：

# 导览数据/渲染模式：static | api | sdk
VITE_DATA_SOURCE_MODE=static

# 讲解内容模式：static | remote | mock
VITE_GUIDE_CONTENT_SOURCE_MODE=static
VITE_GUIDE_STATIC_DATA_BASE_URL=/static/guide-data

# 后端 API
VITE_API_BASE_URL=/app-api
VITE_SGS_API_BASE_URL=/app-api

# 音频接口
VITE_AUDIO_API_BASE_URL=/yudao-server
VITE_AUDIO_LANGUAGE=zh-CN

# SGS SDK/H5 地图基座配置；当前代码尚未把 SDK renderer 接入页面渲染
VITE_SGS_MAP_ID=1
VITE_SGS_SDK_SCRIPT_URL=/static/sgs-map-sdk/index.global.js
VITE_SGS_H5_ENGINE_URL=/h5-sdk
VITE_SGS_SDK_ORIGIN=
VITE_SGS_SDK_TIMEOUT_MS=5000

.env 已被 .gitignore 忽略，不要提交真实账号、token、内网密码或临时联调地址。

安装与运行

pnpm install

# H5 开发
pnpm dev:h5

# 类型检查
pnpm type-check

# ESLint
pnpm lint

# H5 构建
pnpm build:h5

保留的小程序命令：

pnpm dev:mp-weixin
pnpm build:mp-weixin

当前项目工作默认只验证 H5。只有明确处理小程序问题时，才把 mp-weixin 构建作为验收项。

H5 构建与部署

pnpm build:h5 会执行：

uni build -p h5 && node scripts/copy-h5-nav-assets.cjs

构建后需要确认：

dist/build/h5 存在应用产物。
H5 可访问 static/nav-assets/... 下的 GLB/GLTF/bin/texture/manifest 文件。
H5 可访问 static/guide-data 下的讲解和内容数据。
如启用 api 或 sdk 模式，Nginx/网关需代理 /app-api、/yudao-server、/h5-sdk 等路径。

更完整的部署说明见 docs/H5_DEPLOYMENT_GUIDE.md。

质量门

常规代码变更建议至少运行：

pnpm type-check
pnpm lint
pnpm build:h5

涉及导览/讲解交互时，还应在 H5 浏览器中检查：

顶部“馆内/讲解”业务切换。
馆外 2D 与馆内 3D 切换。
全楼/单楼层、楼层切换、POI 点击和搜索结果点击。
位置预览文案不误导为正式导航。
讲解列表、展厅/单元/讲解点进入详情。
音频可播放/不可用/图文讲解状态。
移动端覆盖层不被 WebGL canvas 或 SDK iframe 遮挡。

重要限制

当前正式能力是“馆内 3D 展示 + POI/位置预览 + 讲解内容/音频状态”，不是已认证的室内实时导航。
route_graph 和 nav_data 未通过 readiness gate 前，不要在页面文案或文档中宣称正式路线规划、实时定位、到达提醒或 turn-by-turn 导航。
src/assets/data 是历史/demo 数据区，不是当前导览和讲解的权威数据源。
mock 讲解数据只允许在开发环境显式启用。
SGS SDK 应通过服务/渲染边界接入，不应在页面和通用组件中直接调用 SGSMapSDK；当前仓库已有数据层准备，页面渲染仍以现有 H5 边界为准。

README.md Unescape Escape

Museum Guide v4.0 Frontend Miniapp

当前能力

技术栈