226 lines
8.0 KiB
Markdown
226 lines
8.0 KiB
Markdown
# Shenzhen Natural Museum Dev Skill 对话纪要
|
||
|
||
日期：2026-06-11
|
||
|
||
## 背景
|
||
|
||
本次对话围绕 `shenzhen-natural-museum-dev` skill 的定位、完整性和专业性展开。当前期望定位已明确为：
|
||
|
||
> 移动端自然博物馆三维导览 skill。
|
||
|
||
该 skill 应服务于移动端自然博物馆导览应用，重点覆盖 H5/移动端三维导览、馆内 3D 展示、POI/位置预览、楼层/全馆模型切换、数据 readiness、业务逻辑审核、工程架构审核和数据/展示层解耦。
|
||
|
||
## 当前 Skill 检查结论
|
||
|
||
已检查 `.agents/skills/shenzhen-natural-museum-dev/SKILL.md`。
|
||
|
||
结论：基础合格，但还不是完整的“移动端自然博物馆三维导览专业 skill”。
|
||
|
||
- 已通过 `skill-creator` 的 `quick_validate.py` 校验，输出为 `Skill is valid!`。
|
||
- 文件结构包含 `SKILL.md` 和 `agents/openai.yaml`。
|
||
- 现有内容已经覆盖 H5 导览、Three.js/GLB、Tencent Map、clean nav assets、导览数据访问层、数据 provider/adapter、三维导览数据审核、浏览器用户流审核、legacy demo data 边界等。
|
||
|
||
## 三类审核模块判断
|
||
|
||
### 数据审核模块
|
||
|
||
状态：合格。
|
||
|
||
证据：
|
||
|
||
- `SKILL.md` 中存在明确标题：`三维导览数据审核模块`。
|
||
- 模块覆盖 clean package、manifest、GLB/GLTF、POI index、floor definitions、connector data、`route_graph`、`nav_data`、`src/services/navAssets.ts`、导览数据访问层、Provider/Adapter、路线 readiness 等。
|
||
|
||
### 项目工程架构审核模块
|
||
|
||
状态：部分具备，但不完整。
|
||
|
||
现有内容：
|
||
|
||
- `数据源标准` 中已经有导览数据访问层、Provider、Adapter、静态数据源/API 数据源、领域模型边界等要求。
|
||
- `description` 中提到 architecture reviews。
|
||
|
||
不足：
|
||
|
||
- 没有独立的“项目工程架构审核模块”。
|
||
- 缺少针对页面层、组件层、数据服务层、ThreeMap 渲染层、状态管理、H5/mp 边界、canvas 层级、资源加载生命周期的工程架构审核清单。
|
||
|
||
### 业务审核模块
|
||
|
||
状态：部分具备，但不完整。
|
||
|
||
现有内容：
|
||
|
||
- `Browser User Flow Closure Testing` 可用于用户流程闭环测试。
|
||
- `3D Guide User Audit Module` 可用于移动端 3D 导览体验审核。
|
||
- 已覆盖真实用户任务、控件可见性、状态丢失、死路、伪导航文案、route readiness 边界等。
|
||
|
||
不足：
|
||
|
||
- 没有独立命名为“业务逻辑审核模块”的模块。
|
||
- 缺少固定的业务审核输出结构，例如 P1/P2/P3、源码审核/浏览器验证分离、已实现/部分实现/缺失/数据不足分离。
|
||
|
||
## 重新定位后的判断
|
||
|
||
如果定位为“深圳自然博物馆 frontend-miniapp H5 项目开发规范”，当前 skill 基本合格。
|
||
|
||
如果定位为“移动端自然博物馆三维导览 skill”，当前 skill 还需要加强：
|
||
|
||
- 移动端三维导览业务逻辑审核模块。
|
||
- 移动端三维导览工程架构审核模块。
|
||
- 自然博物馆导览专业语义模块。
|
||
- 数据层与展示层解耦的硬性架构红线。
|
||
|
||
## 数据层与展示层解耦原则
|
||
|
||
本对话明确提出：前端应用中数据层和前端展示层必须解耦。
|
||
|
||
该原则应作为 skill 的核心架构红线，而不是普通建议。
|
||
|
||
### 推荐分层
|
||
|
||
```text
|
||
数据源层
|
||
static nav-assets / CMS API / 后端 API / IMDF / BIM 导出
|
||
↓
|
||
Provider 数据源提供器
|
||
StaticProvider / ApiProvider / FutureImdfProvider
|
||
↓
|
||
Adapter 数据适配器
|
||
把原始字段转换成统一导览领域模型
|
||
↓
|
||
Guide Repository / Guide Data Access Layer
|
||
统一查询 floors、POI、模型、讲解、位置预览、route readiness
|
||
↓
|
||
Store / Composables / Use Cases
|
||
页面状态：当前楼层、全馆/单层、搜索词、选中 POI、是否可导航
|
||
↓
|
||
Presentation ViewModel
|
||
给页面和 ThreeMap 的轻量展示数据
|
||
↓
|
||
前端展示层
|
||
GuideMapShell / ThreeMap / Search / Cards / Floor Switcher
|
||
```
|
||
|
||
### 展示层不应直接依赖
|
||
|
||
- `static/nav-assets/*.json` 原始结构。
|
||
- 后端 API 原始字段。
|
||
- GLB manifest 的路径拼接规则。
|
||
- POI 原始坐标格式。
|
||
- `route_graph/nav_data` 是否存在的散落判断。
|
||
- 楼层 label / floorId 的重复转换逻辑。
|
||
|
||
### 展示层只应消费领域模型或 ViewModel
|
||
|
||
推荐领域模型包括：
|
||
|
||
- `GuideVenue`
|
||
- `GuideBuilding`
|
||
- `GuideFloor`
|
||
- `GuideSpace`
|
||
- `GuidePoi`
|
||
- `GuideCategory`
|
||
- `GuideModelAsset`
|
||
- `GuideConnector`
|
||
- `GuideLocationPreview`
|
||
- `GuideRouteReadiness`
|
||
- `GuideRouteGraph`
|
||
- `GuideExplainMedia`
|
||
|
||
### P1 级架构问题示例
|
||
|
||
- 页面或组件直接读取 `static/nav-assets/*.json`。
|
||
- 页面直接依赖后端 API 原始字段。
|
||
- 组件内部重复实现 POI、floor、category、model path 转换。
|
||
- 真实导航 readiness 判断散落在 UI 层。
|
||
- 展示层把预览 POI 当成真实导航锚点。
|
||
|
||
## 专业前端方案参考
|
||
|
||
本次联网查找后，较适合作为专业方案参考的方向包括：
|
||
|
||
- IMDF：OGC 馆内地图数据标准，强调馆内 orientation、navigation、discovery。
|
||
- ArcGIS Indoors：馆内设施、楼层、单元、路径等信息模型。
|
||
- Mappedin：商业馆内地图 SDK 的楼层、位置、空间数据模型。
|
||
- Khronos glTF：3D 资产传输和运行时加载标准。
|
||
- Vue Composables：封装可复用 stateful logic。
|
||
- Pinia：前端 store 的 state/getters/actions。
|
||
- TanStack Query：server state 缓存、请求状态、刷新、去重。
|
||
|
||
参考链接：
|
||
|
||
- https://docs.ogc.org/cs/20-094/index.html
|
||
- https://doc.esri.com/en/arcgis-pro/latest/help/data/indoors/arcgis-indoors-information-model.html
|
||
- https://www.khronos.org/gltf/
|
||
- https://vuejs.org/guide/reusability/composables
|
||
- https://pinia.vuejs.org/core-concepts/
|
||
- https://tanstack.com/query/latest
|
||
|
||
## 网上同类 Skill 查找结论
|
||
|
||
已查到的小程序相关 skill 多为泛小程序开发，而非自然博物馆三维导览垂直 skill。
|
||
|
||
代表性方向：
|
||
|
||
- TencentCloudBase `miniprogram-development`：偏微信小程序、CloudBase、预览部署、认证、AI 模型调用。
|
||
- `wechat-miniapp-factory`：偏小程序脚手架、校验、提交前预审。
|
||
- `wechat-miniprogram`：偏微信小程序官方文档、WXML/WXSS/WXS、API、组件、开放能力、性能优化。
|
||
- `wechat-devtools-diagnostics-skill`：偏 Windows 下微信开发者工具诊断。
|
||
|
||
结论：
|
||
|
||
- 暂未找到“自然博物馆 / 场馆导览 / 馆内 3D / POI / 路线数据审核”这种垂直专业 skill。
|
||
- 当前 `shenzhen-natural-museum-dev` 的价值在于项目垂直和三维导览垂直，应继续强化，而不是直接照搬泛小程序 skill。
|
||
|
||
## 建议后续补强方向
|
||
|
||
### 1. 增加移动端三维导览业务逻辑审核模块
|
||
|
||
建议覆盖：
|
||
|
||
- 初始馆外/馆内状态。
|
||
- 进入馆内后默认完整建筑模型。
|
||
- 全馆/单层切换。
|
||
- 楼层切换。
|
||
- POI 搜索和聚焦。
|
||
- 顶部“导览 / 讲解”切换。
|
||
- 搜索、卡片、工具按钮是否可见可点击。
|
||
- 伪导航、伪定位、伪路线承诺文案。
|
||
- 源码审核和浏览器交互验证必须分离标注。
|
||
- 输出 P1/P2/P3。
|
||
|
||
### 2. 增加移动端三维导览工程架构审核模块
|
||
|
||
建议覆盖：
|
||
|
||
- Page 层是否只组合业务状态，不直接解析数据源。
|
||
- GuideMapShell 是否只承担导览壳、控件承载、模式切换。
|
||
- ThreeMap 是否只承担 3D 渲染、相机、模型加载、POI 高亮，不承载业务数据转换。
|
||
- navAssets 或 successor service 是否作为唯一导览数据访问层。
|
||
- Provider/Adapter 是否隔离静态包和未来 API。
|
||
- H5 和 mp-weixin 是否清楚分界。
|
||
- 3D canvas 是否可能覆盖移动端 UI 控件。
|
||
- 资源加载、dispose、错误恢复是否具备。
|
||
|
||
### 3. 增加自然博物馆导览专业语义模块
|
||
|
||
建议明确自然博物馆导览中的业务对象：
|
||
|
||
- 展厅。
|
||
- 展项。
|
||
- 设施。
|
||
- 入口。
|
||
- 楼层。
|
||
- 展区。
|
||
- 讲解。
|
||
- 位置预览。
|
||
- 真实路线规划 readiness。
|
||
|
||
并明确当前阶段只能描述为：
|
||
|
||
> 馆内 3D 展示 + POI/位置预览。
|
||
|
||
除非 `route_graph/nav_data` 已接入并验证，否则不能宣称真实馆内导航、路线规划、到达引导或定位精度。
|
||
|