106 lines
3.8 KiB
Markdown
106 lines
3.8 KiB
Markdown
# 项目当前状态报告
|
||
|
||
更新时间：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. 建立导览/讲解核心用户流的浏览器自动化烟测。
|