3.8 KiB
3.8 KiB
项目当前状态报告
更新时间：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 数据，推进到以下分层：
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的加载、校验和浏览器闭环验证。
运行命令
pnpm install
pnpm dev:h5
pnpm type-check
pnpm lint
pnpm build:h5
保留命令：
pnpm dev:mp-weixin
pnpm build:mp-weixin
推荐验收范围
常规变更：
pnpm type-checkpnpm lintpnpm build:h5
导览/讲解 UI 或数据变更：
- H5 浏览器打开首页。
- 检查馆外 2D、馆内 3D、楼层切换、POI 选择、搜索、位置预览。
- 检查讲解展厅/业务单元/讲解点进入详情。
- 检查音频可播放、不可用和图文讲解状态。
- 检查移动端覆盖层不被 3D canvas 或 SDK iframe 遮挡。
后续工作
- 补齐并验证正式
route_graph、nav_data，通过 readiness gate 后再开放正式路线规划/室内导航文案。 - 继续收敛 Three.js/SDK renderer 边界，避免页面和通用组件感知源数据或 SDK 原始协议。
- 完成讲解远程内容源
remote模式，减少开发 mock 的使用范围。 - 对 H5 首屏、GLB 加载、字体和图片资源做移动端性能审计。
- 建立导览/讲解核心用户流的浏览器自动化烟测。