docs: update project documentation

README.md

@@ -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`