# 项目当前状态报告

更新时间：2026-07-03

## 项目定位

本项目是深圳自然博物馆移动 H5 智能导览前端。当前默认交付目标是 H5，核心业务为：

- 馆内导览：馆外参考、馆内 3D 展示、楼层切换、POI 搜索、POI/展厅/设施位置预览。
- 讲解：展厅/业务单元/讲解点选择，展品/讲解详情，音频播放信息解析，图文讲解与不可用状态展示。

微信小程序构建脚本仍保留，但当前开发规范和验证口径以 H5 为准。

## 当前实现概览

### H5 导览

- 首页入口：`src/pages/index/index.vue`
- 页面框架：`GuidePageFrame`、`GuideMapShell`
- 馆外参考：`TencentMap`、`OutdoorNavigationPanel`
- 馆内 3D：`ThreeMap`，加载 `static/nav-assets` 下的模型和导览资源
- 导览数据：`GuideUseCase` -> `GuideRepository` -> static/SGS provider
- 路线能力：`GuideRouteUseCase` 已有路线预览/面板能力，但 `NAV_ROUTE_GRAPH_READY = false`，因此用户侧应保持“位置预览/路线预览”口径

### 讲解

- 讲解列表页：`src/pages/explain/list.vue`
- 首页讲解流：`ExplainHallSelect`
- 讲解列表：`ExplainList`
- 音频播放：`AudioPlayer`、`FloatingAudioButton`
- 数据边界：`ExplainUseCase`、`ExplainRepository`、`MediaRepository`、`AudioPlayInfoRepository`
- 静态数据包：`static/guide-data`
- 远程音频接口：通过 `VITE_AUDIO_API_BASE_URL` 和播放/文本信息仓库接入

### 数据源与 SDK

- 默认模式：`VITE_DATA_SOURCE_MODE=static`
- API 模式：`VITE_DATA_SOURCE_MODE=api`
- SDK 模式：`VITE_DATA_SOURCE_MODE=sdk`，当前切换到 SGS 数据仓库；SDK renderer 尚未作为页面渲染组件落地
- 配置入口：`src/config/dataSource.ts`
- 导览仓库工厂：`src/repositories/createGuideRepository.ts`
- SGS SDK 资料：`static/sgs-map-sdk`

## 架构状态

当前代码已从早期页面直读 Mock 数据，推进到以下分层：

```text
Providers -> Adapters -> Repositories -> UseCases -> ViewModels/Page State -> Components
```

已落地的关键边界：

- 静态导览资源读取：`StaticNavAssetsProvider`
- SGS 后端导览数据读取：`SgsSdkApiProvider`
- 导览领域模型适配：`navAssetsAdapter`、`sgsSdkGuideAdapter`
- 内容/讲解静态数据读取：`staticGuideDataProvider`、`staticMuseumContentProvider`
- 讲解播放信息读取：`AudioPlayInfoRepository`

仍需注意的迁移风险：

- `src/assets/data` 为历史/demo 区域，不应再作为当前权威数据源。
- Three.js 渲染器仍承担部分过渡期渲染和点位表现逻辑，后续可继续收敛到更清晰的 renderer 边界。
- 正式室内导航仍依赖 `route_graph`、`nav_data` 的加载、校验和浏览器闭环验证。

## 运行命令

```bash
pnpm install
pnpm dev:h5
pnpm type-check
pnpm lint
pnpm build:h5
```

保留命令：

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

## 推荐验收范围

常规变更：

- `pnpm type-check`
- `pnpm lint`
- `pnpm build:h5`

导览/讲解 UI 或数据变更：

- H5 浏览器打开首页。
- 检查馆外 2D、馆内 3D、楼层切换、POI 选择、搜索、位置预览。
- 检查讲解展厅/业务单元/讲解点进入详情。
- 检查音频可播放、不可用和图文讲解状态。
- 检查移动端覆盖层不被 3D canvas 或 SDK iframe 遮挡。

## 后续工作

1. 补齐并验证正式 `route_graph`、`nav_data`，通过 readiness gate 后再开放正式路线规划/室内导航文案。
2. 继续收敛 Three.js/SDK renderer 边界，避免页面和通用组件感知源数据或 SDK 原始协议。
3. 完成讲解远程内容源 `remote` 模式，减少开发 mock 的使用范围。
4. 对 H5 首屏、GLB 加载、字体和图片资源做移动端性能审计。
5. 建立导览/讲解核心用户流的浏览器自动化烟测。