# Museum Guide v4.0 Frontend Miniapp

深圳自然博物馆移动 H5 智能导览前端。当前项目以 H5 为主要交付目标，围绕“馆内导览”和“讲解”两条业务线组织代码；微信小程序构建脚本仍保留，但不是当前默认验证范围。

## 当前能力

- 馆内/馆外导览首页：`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`

## 目录结构

```text
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
```

## 数据与架构边界

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

```text
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` 模式运行。常用变量如下：

```bash
# 导览数据/渲染模式：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?v=2.5.0
VITE_SGS_H5_ENGINE_URL=/engine/index.html
VITE_SGS_SDK_ORIGIN=
VITE_SGS_SDK_TIMEOUT_MS=5000
```

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

## 安装与运行

```bash
pnpm install

# H5 开发
pnpm dev:h5

# 类型检查
pnpm type-check

# ESLint
pnpm lint

# H5 构建
pnpm build:h5
```

保留的小程序命令：

```bash
pnpm dev:mp-weixin
pnpm build:mp-weixin
```

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

## H5 构建与部署

`pnpm build:h5` 会执行：

```bash
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`、`/engine` 等路径。`/engine/index.html` 必须是 SGS Map SDK Engine 2.5.x 的独立发布页面，且其资源路径可加载并能完成 `HELLO` -> `ENGINE_READY`；业务 SPA fallback 返回的 200 不是 Engine 健康。

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

## 质量门

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

```bash
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 边界为准。

## 相关文档

- H5 部署：`docs/H5_DEPLOYMENT_GUIDE.md`
- SGS SDK 数据层接入：`docs/Data/SGS_SDK_DATA_LAYER_INTEGRATION_GUIDE.md`
- 讲解静态数据：`static/guide-data/README.md`
- SDK 交付包：`static/sgs-map-sdk/README.md`
- 当前状态报告：`PROJECT_REPORT.md`