docs: update project documentation

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: 分析设计稿 ✓
-- 提取了 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. 建立导览/讲解核心用户流的浏览器自动化烟测。