219 lines
8.5 KiB
Markdown
219 lines
8.5 KiB
Markdown
# 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.4.1
|
||
VITE_SGS_H5_ENGINE_URL=/h5-sdk
|
||
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`、`/h5-sdk` 等路径。
|
||
|
||
更完整的部署说明见 `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`
|