lyf/frontend-miniapp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs: update project documentation
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
lyf
2026-07-03 15:08:04 +08:00
parent 8fed715235
commit 940bbf4ec6
2 changed files with 236 additions and 306 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
PROJECT_REPORT.md
View File

@@ -1,212 +1,105 @@
# 项目完成报告
# 项目当前状态报告
## 📋 项目概述
更新时间：2026-07-03
**项目名称**: 深圳自然博物馆智能导览应用 v4.0
**技术栈**: uni-app + Vue 3 + TypeScript
**完成时间**: 2026-05-21
## 项目定位
---
本项目是深圳自然博物馆移动 H5 智能导览前端。当前默认交付目标是 H5，核心业务为：
## ✅ 完成的 7 个阶段
- 馆内导览：馆外参考、馆内 3D 展示、楼层切换、POI 搜索、POI/展厅/设施位置预览。
- 讲解：展厅/业务单元/讲解点选择，展品/讲解详情，音频播放信息解析，图文讲解与不可用状态展示。
### 阶段 1: 分析设计稿 ✓
- 提取了 4 个 SVG 设计稿的设计规范
- 识别颜色系统（主色 #E0E100、背景色、文字色等）
- 提取圆角规范（32px/12px/8px/6px）
- 分析间距和阴影系统
微信小程序构建脚本仍保留，但当前开发规范和验证口径以 H5 为准。
### 阶段 2: 生成设计系统 ✓
- 创建 App.vue 并定义完整的 CSS 变量系统
- 建立颜色、圆角、间距、阴影、模糊效果规范
- 创建全局样式和工具类
## 当前实现概览
### 阶段 3: 创建项目基础 ✓
- 初始化 uni-app 项目结构
- 配置 package.json、tsconfig.json、vite.config.ts
- 创建 pages.json（路由配置）
- 创建 manifest.json（应用配置）
- 创建 main.ts（入口文件）
### H5 导览
### 阶段 4: 实现组件库 ✓
创建了 7 个核心组件：
1. **BottomTabBar** - 底部导航栏
2. **SearchBar** - 搜索输入框
3. **FloorSelector** - 楼层选择器（3F/2F/1F/B1）
4. **POIMarker** - 地图标记点
5. **HallCard** - 展厅卡片
6. **ExhibitCard** - 展品卡片
7. **FacilityCard** - 设施卡片
- 首页入口：`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`，因此用户侧应保持“位置预览/路线预览”口径
### 阶段 5: 实现页面 ✓
创建了 6 个主要页面：
1. **index/index.vue** - 首页（地图导览）
2. **search/index.vue** - 搜索页面
3. **exhibit/detail.vue** - 展品详情
4. **hall/detail.vue** - 展厅详情
5. **facility/detail.vue** - 设施详情
6. **route/detail.vue** - 路线详情
### 讲解
### 阶段 6: 生成 Mock 数据 ✓
创建了完整的 Mock 数据：
- **exhibits.json** - 5 件展品数据
- **halls.json** - 5 个展厅数据
- **facilities.json** - 8 个设施数据
- **floors.json** - 4 个楼层数据
- **routes.json** - 3 条推荐路线
- **dataLoader.ts** - 数据加载工具
- 讲解列表页：`src/pages/explain/list.vue`
- 首页讲解流：`ExplainHallSelect`
- 讲解列表：`ExplainList`
- 音频播放：`AudioPlayer`、`FloatingAudioButton`
- 数据边界：`ExplainUseCase`、`ExplainRepository`、`MediaRepository`、`AudioPlayInfoRepository`
- 静态数据包：`static/guide-data`
- 远程音频接口：通过 `VITE_AUDIO_API_BASE_URL` 和播放/文本信息仓库接入
### 阶段 7: 工具函数和类型定义 ✓
- **types/index.ts** - 完整的 TypeScript 类型定义
- **utils/format.ts** - 格式化工具函数
- **utils/search.ts** - 搜索工具函数
- **README.md** - 项目文档
### 数据源与 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`
## 📊 项目统计
## 架构状态
### 文件结构
```
museum-guide-v4.0/
├── src/
│ ├── components/ # 7 个组件
│ ├── pages/ # 6 个页面
│ ├── assets/data/ # 5 个 JSON 数据文件
│ ├── utils/ # 3 个工具文件
│ ├── types/ # 1 个类型定义文件
│ └── styles/ # 2 个样式文件
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
当前代码已从早期页面直读 Mock 数据，推进到以下分层：
```text
Providers -> Adapters -> Repositories -> UseCases -> ViewModels/Page State -> Components
```
### 代码统计
- **组件**: 7 个 Vue 组件
- **页面**: 6 个页面
- **数据文件**: 5 个 JSON 文件
- **工具函数**: 3 个 TypeScript 文件
- **类型定义**: 完整的 TypeScript 类型系统
- **样式文件**: 2 个 SCSS 文件
已落地的关键边界：
---
- 静态导览资源读取：`StaticNavAssetsProvider`
- SGS 后端导览数据读取：`SgsSdkApiProvider`
- 导览领域模型适配：`navAssetsAdapter`、`sgsSdkGuideAdapter`
- 内容/讲解静态数据读取：`staticGuideDataProvider`、`staticMuseumContentProvider`
- 讲解播放信息读取：`AudioPlayInfoRepository`
## 🎨 设计系统
仍需注意的迁移风险：
### 颜色规范
- **主色调**: #E0E100（黄色强调色）
- **背景色**: #F3F3F3（浅灰）、#FFFFFF（白色）、#6D6D6D（地图背景）
- **文字色**: #262421（主）、#424754（次）、#333333（三级）
- **边框色**: #E5E5E5、#DEDEDE、#C2C6D6
- **辅助色**: #5ED0E4（POI 标记青色）
- `src/assets/data` 为历史/demo 区域，不应再作为当前权威数据源。
- Three.js 渲染器仍承担部分过渡期渲染和点位表现逻辑，后续可继续收敛到更清晰的 renderer 边界。
- 正式室内导航仍依赖 `route_graph`、`nav_data` 的加载、校验和浏览器闭环验证。
### 圆角规范
- 手机外框: 32px
- 卡片: 12px
- 按钮: 8px
- 小圆角: 6px
## 运行命令
### 间距规范
- xs: 4px
- sm: 8px
- md: 16px
- lg: 24px
- xl: 32px
---
## 🚀 功能特性
### 已实现功能
✅ 地图导览（楼层切换、POI 标记）
✅ 智能搜索（展品、展厅、设施）
✅ 展品详情（音频讲解、收藏、分享）
✅ 展厅浏览（展品列表、导航）
✅ 设施查询（洗手间、咖啡厅、商店等）
✅ 推荐路线（经典艺术之旅、印象派精选等）
✅ 响应式设计（适配多种屏幕尺寸）
✅ 毛玻璃效果（backdrop-filter）
✅ 流畅动画（transition）
---
## 📝 下一步工作
### 需要补充的内容
1. **静态资源**
- 展品图片（/static/exhibits/）
- 展厅图片（/static/halls/）
- 地图平面图（/static/map-placeholder.png）
- 音频讲解文件（/static/audio/）
2. **功能增强**
- 音频播放器组件实现
- 地图缩放和拖拽功能
- 路线导航实时指引
- 用户定位功能
- 离线数据缓存
3. **测试和优化**
- 安装依赖：`npm install`
- 类型检查：`npm run type-check`
- H5 开发：`npm run dev:h5`
- 性能优化
- 兼容性测试
---
## 🎯 项目亮点
1. **完整的设计系统** - 基于实际设计稿提取的 CSS 变量系统
2. **TypeScript 类型安全** - 完整的类型定义和类型检查
3. **组件化架构** - 可复用的组件库
4. **Mock 数据完整** - 包含展品、展厅、设施、路线等完整数据
5. **响应式设计** - 适配多种屏幕尺寸
6. **现代化技术栈** - Vue 3 + TypeScript + Vite
---
## 📖 使用说明
### 安装依赖
```bash
cd museum-guide-v4.0
pnpm install
```
### 开发运行
```bash
# H5 开发
pnpm dev:h5
# 微信小程序开发
pnpm dev:mp-weixin
# 类型检查
pnpm type-check
pnpm lint
pnpm build:h5
```
### 构建
```bash
# H5 构建
pnpm build:h5
保留命令：
# 微信小程序构建
```bash
pnpm dev:mp-weixin
pnpm build:mp-weixin
```
---
## 推荐验收范围
## ✨ 总结
常规变更：
项目已按照 7 个阶段的工作流程完整实现，包括：
- ✅ 设计稿分析和设计系统提取
- ✅ 完整的项目结构和配置
- ✅ 7 个核心组件
- ✅ 6 个主要页面
- ✅ 完整的 Mock 数据
- ✅ 工具函数和类型定义
- ✅ 项目文档
- `pnpm type-check`
- `pnpm lint`
- `pnpm build:h5`
项目代码遵循 uni-app 和 Vue 3 最佳实践，使用 TypeScript 确保类型安全，采用 `<script setup lang="ts">` 语法，具有良好的可维护性和扩展性。
导览/讲解 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. 建立导览/讲解核心用户流的浏览器自动化烟测。

293
README.md
View File

@@ -1,174 +1,211 @@
# Museum Guide v4.0
# Museum Guide v4.0 Frontend Miniapp
深圳自然博物馆智能导览应用
深圳自然博物馆移动 H5 智能导览前端。当前项目以 H5 为主要交付目标，围绕“馆内导览”和“讲解”两条业务线组织代码；微信小程序构建脚本仍保留，但不是当前默认验证范围。
## 项目结构
## 当前能力
```
museum-guide-v4.0/
├── src/
│ ├── App.vue # 应用根组件（设计系统 CSS 变量）
│ ├── main.ts # 入口文件
│ ├── pages.json # 页面路由配置
│ ├── manifest.json # 应用配置
│ ├── components/ # 组件库
│ │ ├── navigation/ # 导航组件
│ │ │ └── BottomTabBar.vue
│ │ ├── search/ # 搜索组件
│ │ │ └── SearchBar.vue
│ │ ├── floor/ # 楼层组件
│ │ │ └── FloorSelector.vue
│ │ ├── poi/ # POI 标记组件
│ │ │ └── POIMarker.vue
│ │ └── content/ # 内容卡片组件
│ │ ├── HallCard.vue
│ │ ├── ExhibitCard.vue
│ │ └── FacilityCard.vue
│ ├── pages/ # 页面
│ │ ├── index/ # 首页（地图导览）
│ │ ├── search/ # 搜索页面
│ │ ├── exhibit/ # 展品详情
│ │ ├── hall/ # 展厅详情
│ │ ├── facility/ # 设施详情
│ │ └── route/ # 路线详情
│ ├── assets/ # 静态资源
│ │ └── data/ # Mock 数据
│ │ ├── exhibits.json
│ │ ├── halls.json
│ │ ├── facilities.json
│ │ ├── floors.json
│ │ └── routes.json
│ ├── utils/ # 工具函数
│ │ ├── dataLoader.ts # 数据加载
│ │ ├── format.ts # 格式化工具
│ │ └── search.ts # 搜索工具
│ ├── types/ # 类型定义
│ │ └── index.ts
│ └── styles/ # 样式文件
│ ├── variables.scss # CSS 变量
│ └── common.scss # 通用样式
├── package.json
├── tsconfig.json
├── vite.config.ts
└── README.md
```
- 馆内/馆外导览首页：`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
- **语法**: `<script setup lang="ts">`
- **构建工具**: Vite
- **样式**: SCSS + CSS Variables
- 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
```
- 主色调: `#E0E100` (黄色强调色)
- 背景色: `#F3F3F3` (浅灰), `#FFFFFF` (白色), `#6D6D6D` (地图背景)
- 文字色: `#262421` (主文字), `#424754` (次要文字), `#333333` (三级文字)
- 边框色: `#E5E5E5`, `#DEDEDE`, `#C2C6D6`
- 辅助色: `#5ED0E4` (POI 标记青色)
## 数据与架构边界
### 圆角规范
当前代码遵循以下数据流：
- 手机外框: `32px`
- 卡片: `12px`
- 按钮: `8px`
- 小圆角: `6px`
```text
static nav-assets / static guide-data / SGS API / audio API
↓
Providers
↓
Adapters
↓
Repositories
↓
UseCases
↓
ViewModels / Page State
↓
Vue Components
```
### 间距规范
关键文件：
- xs: `4px`
- sm: `8px`
- md: `16px`
- lg: `24px`
- xl: `32px`
- 数据源配置：`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
VITE_SGS_H5_ENGINE_URL=/h5-sdk
VITE_SGS_SDK_ORIGIN=
VITE_SGS_SDK_TIMEOUT_MS=5000
```
`.env` 已被 `.gitignore` 忽略，不要提交真实账号、token、内网密码或临时联调地址。
## 安装与运行
```bash
pnpm install
```
## 开发运行
```bash
# H5 开发
pnpm dev:h5
# 微信小程序开发
pnpm dev:mp-weixin
# 类型检查
pnpm type-check
```
## 构建
# ESLint
pnpm lint
```bash
# H5 构建
pnpm build:h5
```
# 微信小程序构建
保留的小程序命令：
```bash
pnpm dev:mp-weixin
pnpm build:mp-weixin
```
## 部署
当前项目工作默认只验证 H5。只有明确处理小程序问题时，才把 `mp-weixin` 构建作为验收项。
H5 线上部署、Nginx 配置、模型资源校验和回滚步骤见 [docs/H5_DEPLOYMENT_GUIDE.md](docs/H5_DEPLOYMENT_GUIDE.md)。
## H5 构建与部署
## 功能特性
`pnpm build:h5` 会执行：
- ✅ 地图导览（楼层切换、POI 标记）
- ✅ 智能搜索（展品、展厅、设施）
- ✅ 展品详情（音频讲解、收藏、分享）
- ✅ 展厅浏览（展品列表、导航）
- ✅ 设施查询（洗手间、咖啡厅、商店等）
- ✅ 推荐路线（经典艺术之旅、印象派精选等）
- ✅ 响应式设计（适配多种屏幕尺寸）
- ✅ 毛玻璃效果（backdrop-filter）
- ✅ 流畅动画（transition）
```bash
uni build -p h5 && node scripts/copy-h5-nav-assets.cjs
```
## 组件说明
构建后需要确认：
### 导航组件
- `BottomTabBar`: 底部导航栏
- `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` 等路径。
### 搜索组件
- `SearchBar`: 搜索输入框
更完整的部署说明见 `docs/H5_DEPLOYMENT_GUIDE.md`。
### 楼层组件
- `FloorSelector`: 楼层选择器（3F/2F/1F/B1）
## 质量门
### POI 组件
- `POIMarker`: 地图标记点
常规代码变更建议至少运行：
### 内容组件
- `HallCard`: 展厅卡片
- `ExhibitCard`: 展品卡片
- `FacilityCard`: 设施卡片
```bash
pnpm type-check
pnpm lint
pnpm build:h5
```
## 数据结构
涉及导览/讲解交互时，还应在 H5 浏览器中检查：
详见 `src/types/index.ts` 和 `src/assets/data/` 目录下的 JSON 文件。
- 顶部“馆内/讲解”业务切换。
- 馆外 2D 与馆内 3D 切换。
- 全楼/单楼层、楼层切换、POI 点击和搜索结果点击。
- 位置预览文案不误导为正式导航。
- 讲解列表、展厅/单元/讲解点进入详情。
- 音频可播放/不可用/图文讲解状态。
- 移动端覆盖层不被 WebGL canvas 或 SDK iframe 遮挡。
## 开发规范
## 重要限制
1. 使用 `<script setup lang="ts">` 语法
2. 组件使用 TypeScript 类型定义
3. 样式使用 SCSS 和 CSS Variables
4. 遵循 uni-app 开发规范
5. 保持代码简洁和可维护性
- 当前正式能力是“馆内 3D 展示 + POI/位置预览 + 讲解内容/音频状态”，不是已认证的室内实时导航。
- `route_graph` 和 `nav_data` 未通过 readiness gate 前，不要在页面文案或文档中宣称正式路线规划、实时定位、到达提醒或 turn-by-turn 导航。
- `src/assets/data` 是历史/demo 数据区，不是当前导览和讲解的权威数据源。
- `mock` 讲解数据只允许在开发环境显式启用。
- SGS SDK 应通过服务/渲染边界接入，不应在页面和通用组件中直接调用 `SGSMapSDK`；当前仓库已有数据层准备，页面渲染仍以现有 H5 边界为准。
## 注意事项
## 相关文档
- 图片资源需放置在 `static/` 目录下
- 音频资源需放置在 `static/audio/` 目录下
- 地图图片需要实际的场馆平面图
- 音频讲解需要录制实际的讲解内容
## License
MIT
- 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`