docs: update project documentation

2026-07-03 15:08:04 +08:00
parent 8fed715235
commit 940bbf4ec6
2 changed files with 236 additions and 306 deletions
--- a/PROJECT_REPORT.md
+++ b/PROJECT_REPORT.md
@@ -1,212 +1,105 @@
-# 项目完成报告
+# 项目当前状态报告
-## 📋 项目概述
+更新时间：2026-07-03
-**项目名称**: 深圳自然博物馆智能导览应用 v4.0  
+## 项目定位
 **技术栈**: uni-app + Vue 3 + TypeScript  
 **完成时间**: 2026-05-21  
---
+本项目是深圳自然博物馆移动 H5 智能导览前端。当前默认交付目标是 H5，核心业务为：
-## ✅ 完成的 7 个阶段
+- 馆内导览：馆外参考、馆内 3D 展示、楼层切换、POI 搜索、POI/展厅/设施位置预览。
 - 讲解：展厅/业务单元/讲解点选择，展品/讲解详情，音频播放信息解析，图文讲解与不可用状态展示。
-### 阶段 1: 分析设计稿 ✓
+微信小程序构建脚本仍保留，但当前开发规范和验证口径以 H5 为准。
 - 提取了 4 个 SVG 设计稿的设计规范
 - 识别颜色系统（主色 #E0E100、背景色、文字色等）
 - 提取圆角规范（32px/12px/8px/6px）
 - 分析间距和阴影系统
-### 阶段 2: 生成设计系统 ✓
+## 当前实现概览
 - 创建 App.vue 并定义完整的 CSS 变量系统
 - 建立颜色、圆角、间距、阴影、模糊效果规范
 - 创建全局样式和工具类
-### 阶段 3: 创建项目基础 ✓
+### H5 导览
 - 初始化 uni-app 项目结构
 - 配置 package.json、tsconfig.json、vite.config.ts
 - 创建 pages.json（路由配置）
 - 创建 manifest.json（应用配置）
 - 创建 main.ts（入口文件）
-### 阶段 4: 实现组件库 ✓
+- 首页入口：`src/pages/index/index.vue`
-创建了 7 个核心组件：
+- 页面框架：`GuidePageFrame`、`GuideMapShell`
-1. **BottomTabBar** - 底部导航栏
+- 馆外参考：`TencentMap`、`OutdoorNavigationPanel`
-2. **SearchBar** - 搜索输入框
+- 馆内 3D：`ThreeMap`，加载 `static/nav-assets` 下的模型和导览资源
-3. **FloorSelector** - 楼层选择器（3F/2F/1F/B1）
+- 导览数据：`GuideUseCase` -> `GuideRepository` -> static/SGS provider
-4. **POIMarker** - 地图标记点
+- 路线能力：`GuideRouteUseCase` 已有路线预览/面板能力，但 `NAV_ROUTE_GRAPH_READY = false`，因此用户侧应保持“位置预览/路线预览”口径
 5. **HallCard** - 展厅卡片
 6. **ExhibitCard** - 展品卡片
 7. **FacilityCard** - 设施卡片
-### 阶段 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 数据 ✓
+- 讲解列表页：`src/pages/explain/list.vue`
-创建了完整的 Mock 数据：
+- 首页讲解流：`ExplainHallSelect`
- **exhibits.json** - 5 件展品数据
+- 讲解列表：`ExplainList`
- **halls.json** - 5 个展厅数据
+- 音频播放：`AudioPlayer`、`FloatingAudioButton`
- **facilities.json** - 8 个设施数据
+- 数据边界：`ExplainUseCase`、`ExplainRepository`、`MediaRepository`、`AudioPlayInfoRepository`
- **floors.json** - 4 个楼层数据
+- 静态数据包：`static/guide-data`
- **routes.json** - 3 条推荐路线
+- 远程音频接口：通过 `VITE_AUDIO_API_BASE_URL` 和播放/文本信息仓库接入
 - **dataLoader.ts** - 数据加载工具
-### 阶段 7: 工具函数和类型定义 ✓
+### 数据源与 SDK
 - **types/index.ts** - 完整的 TypeScript 类型定义
 - **utils/format.ts** - 格式化工具函数
 - **utils/search.ts** - 搜索工具函数
 - **README.md** - 项目文档
---
+- 默认模式：`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 数据，推进到以下分层：
-```
+
-museum-guide-v4.0/
+```text
-├── src/
+Providers -> Adapters -> Repositories -> UseCases -> ViewModels/Page State -> Components
 │   ├── components/        # 7 个组件
 │   ├── pages/            # 6 个页面
 │   ├── assets/data/      # 5 个 JSON 数据文件
 │   ├── utils/            # 3 个工具文件
 │   ├── types/            # 1 个类型定义文件
 │   └── styles/           # 2 个样式文件
 ├── package.json
 ├── tsconfig.json
 ├── vite.config.ts
 └── README.md
 ```
-### 代码统计
+已落地的关键边界：
 - **组件**: 7 个 Vue 组件
 - **页面**: 6 个页面
 - **数据文件**: 5 个 JSON 文件
 - **工具函数**: 3 个 TypeScript 文件
 - **类型定义**: 完整的 TypeScript 类型系统
 - **样式文件**: 2 个 SCSS 文件
---
+- 静态导览资源读取：`StaticNavAssetsProvider`
 - SGS 后端导览数据读取：`SgsSdkApiProvider`
 - 导览领域模型适配：`navAssetsAdapter`、`sgsSdkGuideAdapter`
 - 内容/讲解静态数据读取：`staticGuideDataProvider`、`staticMuseumContentProvider`
 - 讲解播放信息读取：`AudioPlayInfoRepository`
-## 🎨 设计系统
+仍需注意的迁移风险：
-### 颜色规范
+- `src/assets/data` 为历史/demo 区域，不应再作为当前权威数据源。
- **主色调**: #E0E100（黄色强调色）
+- Three.js 渲染器仍承担部分过渡期渲染和点位表现逻辑，后续可继续收敛到更清晰的 renderer 边界。
- **背景色**: #F3F3F3（浅灰）、#FFFFFF（白色）、#6D6D6D（地图背景）
+- 正式室内导航仍依赖 `route_graph`、`nav_data` 的加载、校验和浏览器闭环验证。
 - **文字色**: #262421（主）、#424754（次）、#333333（三级）
 - **边框色**: #E5E5E5、#DEDEDE、#C2C6D6
 - **辅助色**: #5ED0E4（POI 标记青色）
-### 圆角规范
+## 运行命令
 - 手机外框: 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 个阶段的工作流程完整实现，包括：
+- `pnpm type-check`
- ✅ 设计稿分析和设计系统提取
+- `pnpm lint`
- ✅ 完整的项目结构和配置
+- `pnpm build:h5`
 - ✅ 7 个核心组件
 - ✅ 6 个主要页面
 - ✅ 完整的 Mock 数据
 - ✅ 工具函数和类型定义
 - ✅ 项目文档
-项目代码遵循 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. 建立导览/讲解核心用户流的浏览器自动化烟测。
--- a/README.md
+++ b/README.md
@@ -1,174 +1,211 @@
-# Museum Guide v4.0
+# Museum Guide v4.0 Frontend Miniapp
-深圳自然博物馆智能导览应用
+深圳自然博物馆移动 H5 智能导览前端。当前项目以 H5 为主要交付目标，围绕“馆内导览”和“讲解”两条业务线组织代码；微信小程序构建脚本仍保留，但不是当前默认验证范围。
-## 项目结构
+## 当前能力
-```
+- 馆内/馆外导览首页：`src/pages/index/index.vue`
-museum-guide-v4.0/
+  - 馆外 2D 参考地图：腾讯地图容器、主入口参考、来馆参考面板。
-├── src/
+  - 馆内 3D 展示：基于 Three.js/GLB 的 H5 三维模型渲染、全楼/单楼层切换、楼层选择、POI 点击和高亮。
-│   ├── App.vue                 # 应用根组件（设计系统 CSS 变量）
+  - POI 搜索与位置预览：通过导览用例读取楼层、POI、位置预览数据。
-│   ├── main.ts                 # 入口文件
+  - 路线状态：当前 `NAV_ROUTE_GRAPH_READY = false`，产品口径为“位置预览/路线预览”，不声明正式室内导航、实时定位或到达引导。
-│   ├── pages.json              # 页面路由配置
+
-│   ├── manifest.json           # 应用配置
+- 讲解业务
-│   ├── components/             # 组件库
+  - 讲解入口：首页“讲解”业务流和 `src/pages/explain/list.vue`。
-│   │   ├── navigation/         # 导航组件
+  - 展厅、业务单元、讲解点选择：`ExplainHallSelect`、`ExplainList`、展品/展厅详情页。
-│   │   │   └── BottomTabBar.vue
+  - 音频与图文讲解：通过 `ExplainUseCase`、`AudioPlayInfoRepository`、`MediaRepository` 读取播放信息、讲解词和不可用状态；无真实音频时显示图文/不可用口径。
-│   │   ├── search/             # 搜索组件
+  - 讲解到导览的位置联动：通过稳定的 `poiId`、`hallId`、`floorId` 等领域 ID 解析位置预览目标。
-│   │   │   └── SearchBar.vue
+
-│   │   ├── floor/              # 楼层组件
+- 数据源切换
-│   │   │   └── FloorSelector.vue
+  - `static`：默认模式，读取本地 `static/nav-assets` 和 `static/guide-data`。
-│   │   ├── poi/                # POI 标记组件
+  - `api`：读取 SGS 后端 API 的楼层、POI、空间、导航目的地等数据，仍可使用本地渲染边界。
-│   │   │   └── POIMarker.vue
+  - `sdk`：当前代码会切到 SGS 后端数据仓库，并保留 SDK/H5 地图基座配置；实际 SDK renderer 仍需通过独立渲染边界落地。
 │   │   └── 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
 ```
 ## 技术栈
- **框架**: uni-app
+- uni-app + Vue 3 + TypeScript
- **语言**: Vue 3 + TypeScript
+- Vite
- **语法**: `<script setup lang="ts">`
+- Three.js
- **构建工具**: Vite
+- SCSS / CSS Variables
- **样式**: 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`
+```text
- 卡片: `12px`
+static nav-assets / static guide-data / SGS API / audio API
- 按钮: `8px`
+        ↓
- 小圆角: `6px`
+Providers
        ↓
 Adapters
        ↓
 Repositories
        ↓
 UseCases
        ↓
 ViewModels / Page State
        ↓
 Vue Components
 ```
-### 间距规范
+关键文件：
- xs: `4px`
+- 数据源配置：`src/config/dataSource.ts`
- sm: `8px`
+- 导览仓库选择：`src/repositories/createGuideRepository.ts`
- md: `16px`
+- 导览用例：`src/usecases/guideUseCase.ts`
- lg: `24px`
+- 路线用例：`src/usecases/guideRouteUseCase.ts`
- xl: `32px`
+- 讲解用例：`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 标记）
+```bash
- ✅ 智能搜索（展品、展厅、设施）
+uni build -p h5 && node scripts/copy-h5-nav-assets.cjs
- ✅ 展品详情（音频讲解、收藏、分享）
+```
 - ✅ 展厅浏览（展品列表、导航）
 - ✅ 设施查询（洗手间、咖啡厅、商店等）
 - ✅ 推荐路线（经典艺术之旅、印象派精选等）
 - ✅ 响应式设计（适配多种屏幕尺寸）
 - ✅ 毛玻璃效果（backdrop-filter）
 - ✅ 流畅动画（transition）
-## 组件说明
+构建后需要确认：
-### 导航组件
+- `dist/build/h5` 存在应用产物。
- `BottomTabBar`: 底部导航栏
+- 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`。
 - `SearchBar`: 搜索输入框
-### 楼层组件
+## 质量门
 - `FloorSelector`: 楼层选择器（3F/2F/1F/B1）
-### POI 组件
+常规代码变更建议至少运行：
 - `POIMarker`: 地图标记点
-### 内容组件
+```bash
- `HallCard`: 展厅卡片
+pnpm type-check
- `ExhibitCard`: 展品卡片
+pnpm lint
- `FacilityCard`: 设施卡片
+pnpm build:h5
 ```
-## 数据结构
+涉及导览/讲解交互时，还应在 H5 浏览器中检查：
-详见 `src/types/index.ts` 和 `src/assets/data/` 目录下的 JSON 文件。
+- 顶部“馆内/讲解”业务切换。
 - 馆外 2D 与馆内 3D 切换。
 - 全楼/单楼层、楼层切换、POI 点击和搜索结果点击。
 - 位置预览文案不误导为正式导航。
 - 讲解列表、展厅/单元/讲解点进入详情。
 - 音频可播放/不可用/图文讲解状态。
 - 移动端覆盖层不被 WebGL canvas 或 SDK iframe 遮挡。
-## 开发规范
+## 重要限制
-1. 使用 `<script setup lang="ts">` 语法
+- 当前正式能力是“馆内 3D 展示 + POI/位置预览 + 讲解内容/音频状态”，不是已认证的室内实时导航。
-2. 组件使用 TypeScript 类型定义
+- `route_graph` 和 `nav_data` 未通过 readiness gate 前，不要在页面文案或文档中宣称正式路线规划、实时定位、到达提醒或 turn-by-turn 导航。
-3. 样式使用 SCSS 和 CSS Variables
+- `src/assets/data` 是历史/demo 数据区，不是当前导览和讲解的权威数据源。
-4. 遵循 uni-app 开发规范
+- `mock` 讲解数据只允许在开发环境显式启用。
-5. 保持代码简洁和可维护性
+- SGS SDK 应通过服务/渲染边界接入，不应在页面和通用组件中直接调用 `SGSMapSDK`；当前仓库已有数据层准备，页面渲染仍以现有 H5 边界为准。
-## 注意事项
+## 相关文档
- 图片资源需放置在 `static/` 目录下
+- H5 部署：`docs/H5_DEPLOYMENT_GUIDE.md`
- 音频资源需放置在 `static/audio/` 目录下
+- 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`
 ## License
 MIT