提交室内导览交互与讲解优化
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: shenzhen-natural-museum-dev
|
||||
description: Shenzhen Natural Museum mobile H5 spatial content guide architecture standards. Use when working in this frontend-miniapp project on guide and explain businesses, indoor 3D/Three.js/GLB, POI/location preview, exhibit/hall/facility content, audio explanation, transcript/media data, Tencent Map/outdoor reference logic, static nav assets, Museum Content/Guide/Explain Data Access Layers, provider/adapter/repository architecture, route_graph/nav_data readiness, browser-simulated H5 user-flow audits, business-logic audits, engineering architecture reviews, legacy demo data cleanup, mobile overlay/canvas compatibility, and quality gates. Treat mini-program/mp-weixin as out of scope unless the user explicitly asks for it.
|
||||
description: Shenzhen Natural Museum mobile H5 spatial content guide architecture standards. Use when working in this frontend-miniapp project on guide and explain businesses, indoor 3D/Three.js/GLB, SGS Map SDK H5 integration, iframe/postMessage SDK rendering, API/static data-source switching, POI/location preview, exhibit/hall/facility content, audio explanation, transcript/media data, Tencent Map/outdoor reference logic, static nav assets, Museum Content/Guide/Explain Data Access Layers, provider/adapter/repository architecture, route_graph/nav_data readiness, browser-simulated H5 user-flow audits, business-logic audits, engineering architecture reviews, legacy demo data cleanup, mobile overlay/canvas compatibility, and quality gates. Treat mini-program/mp-weixin as out of scope unless the user explicitly asks for it.
|
||||
---
|
||||
|
||||
# Shenzhen Natural Museum Dev
|
||||
@@ -114,6 +114,95 @@ Guide data and explain data may share the same exhibit/hall/POI IDs, but their u
|
||||
- unrelated historical demo modules;
|
||||
- deletion candidates that need user approval.
|
||||
|
||||
## Multi-Source Data Strategy
|
||||
|
||||
Use this module when the guide data source must switch between the local static resource package, backend APIs, and the SGS Map SDK H5 renderer.
|
||||
|
||||
Supported H5 modes:
|
||||
|
||||
- `static`: current default. Use the static nav-assets package through `StaticNavAssetsProvider`, static adapters, `StaticGuideRepository`, and the existing Three.js/GLB renderer.
|
||||
- `api`: use backend GIS/map APIs for floors and POIs through an API provider and repository, while keeping the existing local/static renderer if SDK rendering is not enabled.
|
||||
- `sdk`: use backend GIS/map APIs for guide domain data and use SGS Map SDK as the indoor map renderer. Do not use SDK mode as a replacement for guide/explain repositories; it is a rendering/runtime service, not the page data contract.
|
||||
|
||||
Configuration rules:
|
||||
|
||||
- Prefer environment-driven switching, e.g. `VITE_DATA_SOURCE_MODE=static|api|sdk`, `VITE_API_BASE_URL`, `VITE_SGS_SDK_URL`, and `VITE_SGS_SDK_ORIGIN`.
|
||||
- Centralize mode parsing and validation in one config module such as `src/config/dataSource.ts`; pages and components must not read raw env vars directly.
|
||||
- Repository selection should be explicit:
|
||||
- `static` -> `StaticGuideRepository` + `StaticNavAssetsProvider`.
|
||||
- `api` -> `ApiGuideRepository` + `ApiNavAssetsProvider`.
|
||||
- `sdk` -> `ApiGuideRepository` + `ApiNavAssetsProvider`; SDK is selected only for renderer/service integration.
|
||||
- Renderer selection should be explicit:
|
||||
- `static` and `api` -> existing `ThreeMap`/local renderer path unless the product requires another renderer.
|
||||
- `sdk` -> `SgsMapRenderer` or equivalent SDK container component.
|
||||
- Keep the selected mode observable in diagnostics/logging so QA can tell which source and renderer are active.
|
||||
- The same domain models and view models must be consumed by the UI in all modes. If API fields differ from static package fields, normalize them in adapters.
|
||||
- Switching modes must not require changing page templates, business use cases, or explain components.
|
||||
|
||||
## SDK Integration Standards
|
||||
|
||||
Use this module when integrating the SGS Map SDK from `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system` into the H5 guide experience.
|
||||
|
||||
Treat the SDK as a black-box H5 map runtime:
|
||||
|
||||
- Do not let pages, route/detail pages, search pages, explain components, or generic guide components import or call `SGSMapSDK` directly.
|
||||
- Wrap the SDK instance behind a provider/service such as `SgsMapServiceProvider` that owns script availability, initialization, readiness, command calls, event listener registration, and teardown.
|
||||
- Use an adapter layer to translate SDK events and responses into guide-domain events and models. Examples: `poiClick` -> selected `MuseumPoi`/`GuideLocationPreview`, `floorChanged` -> guide floor state, route result -> route readiness/result domain model.
|
||||
- Keep SDK rendering separate from domain data loading. API-backed `GuideRepository` should still provide floors, POIs, search, and location previews.
|
||||
- Keep Tencent/outdoor map logic independent from SDK indoor map state.
|
||||
- Preserve mobile H5 overlays above the SDK iframe/canvas. The SDK container must not cover top tabs, search, cards, floor controls, explain controls, or audio player.
|
||||
|
||||
SGS Map SDK specific rules:
|
||||
|
||||
- Use a dedicated H5 renderer component, e.g. `SgsMapRenderer.vue`, for the iframe host and UI event emits.
|
||||
- Initialize SDK with explicit `container`, `sdkUrl`, initial `floorId`, `timeout`, and `targetOrigin` where available.
|
||||
- Use `targetOrigin` instead of `*` for deployed environments. If local development temporarily needs `*`, mark it as development-only.
|
||||
- Wait for the SDK `ready` event before sending commands that require `_postCommandAsync` readiness.
|
||||
- Bridge SDK command methods through a renderer/service interface: `changeFloor`, `focusTo`, `addMarker`, `clearMarkers`, `highlightPolygon`, `toggleLayer`, `planRoute`, `clearRoute`, `resetView`, `setViewMode`, and `getState`.
|
||||
- Call `destroy()` on component unmount or provider disposal to remove iframe, listeners, and pending promises.
|
||||
- Handle `ERR_NOT_READY`, `ERR_TIMEOUT`, `ERR_NO_PATH`, `ERR_FLOOR_NOT_FOUND`, `ERR_POI_NOT_FOUND`, `ERR_NETWORK`, `ERR_IFRAME_DEAD`, `ERR_UNAUTHORIZED`, `ERR_UNSUPPORTED`, and `ERR_FAILED` without leaving the user stuck.
|
||||
- Route planning through SDK can be enabled only when route graph/nav data and runtime behavior are verified. Until then, keep user-facing copy as location preview or experimental route preview, not certified navigation.
|
||||
|
||||
Recommended integration shape:
|
||||
|
||||
```text
|
||||
GuideRepository / GuideUseCase -> domain floors, POIs, search, location preview
|
||||
GuideMapShell / renderer switch -> chooses local ThreeMap or SgsMapRenderer
|
||||
SgsMapServiceProvider -> owns SGSMapSDK instance and lifecycle
|
||||
SgsMapEventAdapter -> SDK events/responses -> guide domain events
|
||||
```
|
||||
|
||||
## SDK Integration Workflow
|
||||
|
||||
Use this workflow when the user asks to connect the SGS Map SDK to the H5 guide app.
|
||||
|
||||
1. Interface abstraction:
|
||||
- Inventory current guide/map entry points, especially `GuideMapShell`, `ThreeMap`, `guideUseCase`, repositories, providers, and route/search pages.
|
||||
- Define or formalize a renderer boundary for guide map operations: floor change, POI focus, marker display, route preview/planning, view reset, and emitted interactions.
|
||||
- Keep current static/Three.js behavior as one implementation of that boundary; do not rewrite unrelated guide/explain logic.
|
||||
- Add a config module for `static|api|sdk` mode selection and validation.
|
||||
|
||||
2. API data layer:
|
||||
- Add an API provider for SGS Map backend endpoints such as floor list and POI-by-floor list.
|
||||
- Add adapters that normalize backend floor/POI response fields into `MuseumFloor`, `MuseumPoi`, and `GuideLocationPreview`.
|
||||
- Implement `ApiGuideRepository` behind the existing `GuideRepository` contract.
|
||||
- Verify that search, floor list, and location preview work in `static` and `api` modes before adding SDK rendering.
|
||||
|
||||
3. SDK renderer integration:
|
||||
- Source the browser SDK deliberately: copy/version `sgs-map-sdk.min.js` into this project only if that is the chosen deployment model, or load it from the SGS Map service if operations owns it there.
|
||||
- Add TypeScript declarations or a small wrapper type for the SDK API instead of scattering `any` across components.
|
||||
- Create `SgsMapServiceProvider` to load/instantiate/destroy SDK and expose typed operations.
|
||||
- Create `SgsMapRenderer.vue` to host the SDK container, pass initial floor/mode, emit normalized map events, and show loading/error/retry states.
|
||||
- Update the guide shell to choose `ThreeMap` or `SgsMapRenderer` by config, not by page-level conditionals.
|
||||
- Keep SDK-only code in H5-safe boundaries. Do not add mini-program/mp-weixin fallback work unless the user explicitly asks.
|
||||
|
||||
4. Validation:
|
||||
- Run at least `pnpm type-check`, `pnpm lint`, and `pnpm build:h5` after code changes.
|
||||
- Browser-test mode switching: `static` -> `api` -> `sdk`, confirming the active source/renderer is visible in logs or diagnostics.
|
||||
- Browser-test SDK lifecycle: mount, SDK `ready`, floor switch, POI focus/click, route preview if enabled, unmount, remount.
|
||||
- Browser-test error states: SDK URL unavailable, API unavailable, SDK not ready, command timeout, and route-not-ready.
|
||||
- Verify overlays remain clickable above the SDK iframe/canvas on a mobile viewport.
|
||||
|
||||
## Guide, Map, And 3D Standards
|
||||
|
||||
- Indoor 3D should load GLB/GLTF resources from the clean package under `static/nav-assets/...` while preserving texture/bin relationships.
|
||||
@@ -179,13 +268,64 @@ Check:
|
||||
- Shell layer: `GuidePageFrame`, top tabs, and shared navigation shell should handle layout and cross-business tab state without owning data conversion.
|
||||
- Guide shell: `GuideMapShell` should carry map/3D controls and mode switching without knowing static package internals beyond transitional props.
|
||||
- Renderer layer: `ThreeMap` should render model/POI/camera state, not own source-specific manifest/floor/POI adapters after migration.
|
||||
- SDK isolation: pages and generic guide/explain components must not import `SGSMapSDK`, access iframe `contentWindow`, or send raw `postMessage` commands directly.
|
||||
- Renderer abstraction: SDK mode should be selected through a renderer boundary or shell-level switch, not by scattering `if (mode === 'sdk')` branches across pages.
|
||||
- SDK provider encapsulation: SDK instance lifecycle, command queueing/readiness, target origin, and teardown must stay in a provider/service layer.
|
||||
- SDK event adapter: SDK `ready`, `poiClick`, `floorChanged`, route response, and error events must be converted into domain events or use-case calls before reaching presentation components.
|
||||
- Mode switching: `static`, `api`, and `sdk` modes must be selectable through centralized config and must preserve the same domain/view-model contracts.
|
||||
- Fallback strategy: SDK unavailable, iframe load failure, API failure, or command timeout must show recovery/fallback states; do not silently leave a blank map.
|
||||
- API dependency: SDK mode should pair with API-backed guide repositories for floor/POI domain data; static package data should not be mixed into SDK runtime unless explicitly marked as a migration bridge.
|
||||
- Explain layer: `ExplainList` should render repository/view-model data and emit actions; `AudioPlayer` should own only playback runtime.
|
||||
- Data layer: static package and future API/CMS loading must stay behind providers/adapters/repositories/use cases; pages and presentation components must not own source-specific loading.
|
||||
- Repository layer: `MuseumContentRepository`, `GuideRepository`, `ExplainRepository`, and `MediaRepository` should hide providers/adapters from UI.
|
||||
- State layer: guide session, explain session, player state, search state, selected target, and route readiness should live in composables/stores/use cases when shared across pages.
|
||||
- H5/mp boundary: H5 guide/explain behavior should not be constrained by mp-weixin unless requested.
|
||||
- Overlay safety: canvas must not capture or cover top tabs, search, cards, floor/full-building controls, explain controls, or audio player.
|
||||
- Lifecycle: models, audio contexts, network requests, and event listeners must clean up on unmount and recover from failures.
|
||||
- Overlay safety: canvas, WebGL layers, and SDK iframe must not capture or cover top tabs, search, cards, floor/full-building controls, explain controls, or audio player.
|
||||
- Lifecycle: models, SDK iframes, audio contexts, network requests, and event listeners must clean up on unmount and recover from failures.
|
||||
|
||||
## SDK Integration Audit Module
|
||||
|
||||
Use this module when reviewing or validating SGS Map SDK H5 integration.
|
||||
|
||||
1. SDK loading:
|
||||
- Confirm whether the SDK is loaded from this project, the SGS Map service, or another approved static host.
|
||||
- Verify `sgs-map-sdk.min.js` version and source path are documented and not duplicated accidentally.
|
||||
- Ensure TypeScript declarations or wrapper types cover the used API surface instead of leaking untyped globals through the app.
|
||||
- Check that SDK loading failures surface a visible error/retry/fallback state.
|
||||
|
||||
2. Lifecycle management:
|
||||
- SDK initialization should happen in `SgsMapServiceProvider`, `SgsMapRenderer`, or an equivalent H5 renderer boundary, not in pages.
|
||||
- `destroy()` must be called on unmount/dispose to remove iframe, message listeners, and pending promises.
|
||||
- Pending commands must be rejected or cancelled when the renderer unmounts.
|
||||
- Re-entering the guide page should not create duplicate iframes, duplicate listeners, or stale floor/POI state.
|
||||
|
||||
3. Event bridge:
|
||||
- `ready` should update map readiness and release queued/disabled UI actions.
|
||||
- `poiClick` should resolve to a stable guide domain POI or show a controlled unresolved-POI state.
|
||||
- `floorChanged` should sync the guide floor state and visible controls.
|
||||
- Route responses must respect route readiness gates and user-facing copy rules.
|
||||
- SDK errors should become use-case or view-model error states, not only console logs.
|
||||
|
||||
4. Security:
|
||||
- Use explicit `targetOrigin` in deployed environments.
|
||||
- Validate message origin and iframe source; do not accept arbitrary `postMessage` payloads.
|
||||
- Do not send tokens, private user data, or unrelated business payloads through the SDK message bridge.
|
||||
- If cross-origin SDK hosting is used, document CORS, CSP, and deployment assumptions.
|
||||
|
||||
5. Error handling:
|
||||
- Cover `ERR_NOT_READY`, timeout, iframe load failure, backend/network failure, unsupported command, unauthorized access, missing floor, missing POI, and no-path cases.
|
||||
- Provide retry/recovery for load failures and clear disabled states for unavailable route planning.
|
||||
- Do not allow a failed SDK command to desynchronize the selected POI, floor selector, search result, or explain location preview.
|
||||
|
||||
6. Performance and mobile H5 fit:
|
||||
- SDK iframe/model loading should show progress/loading UI and must not block the rest of the guide shell.
|
||||
- Floor changes and POI focus should avoid janky transitions that make overlay controls unresponsive.
|
||||
- Keep GLB/model memory and iframe lifecycle under control when switching tabs or leaving the guide page.
|
||||
- Validate small mobile viewport behavior: no horizontal overflow, overlay buttons remain tappable, and the iframe does not steal all gestures.
|
||||
|
||||
7. Cross-browser H5 validation:
|
||||
- Test at least Chromium-based H5 during development; add Safari/iOS WebView checks when production target includes iOS browsers.
|
||||
- Keep the test scope H5 unless the user explicitly asks for mini-program/mp-weixin.
|
||||
|
||||
## 3D Guide Data Audit Module
|
||||
|
||||
@@ -282,6 +422,10 @@ pnpm build:h5
|
||||
- Audio fallback URLs such as `example.com` are not valid explain capability.
|
||||
- `src/pages/route/detail.vue` may still contain historical navigation states such as planning/navigating/arrived/location-error. Keep them blocked unless real graph data exists.
|
||||
- Runtime static JSON loading through `uni.request` must be verified on H5 for current work; verify mp-weixin only when explicitly requested.
|
||||
- SGS Map SDK H5 integration depends on the sibling project `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system`, especially `sgs-frontend-map/sdk-src`, `public/sdk/sgs-map-sdk.min.js`, and `/h5-sdk`.
|
||||
- SGS Map SDK uses iframe + `postMessage`; target origin, iframe lifecycle, and event bridge errors are separate operational risks from local Three.js rendering.
|
||||
- SDK mode should not be treated as proof of certified indoor navigation unless route graph/nav data and runtime route behavior are verified.
|
||||
- Mixing static nav-assets POI IDs with backend SGS Map POI IDs can break search, focus, explain location previews, and route actions unless adapters normalize stable IDs deliberately.
|
||||
- Historical demo data remains outside the guide/explain production data boundary unless explicitly migrated.
|
||||
- Tencent Map SDK behavior, indoor Three.js behavior, and audio playback behavior are separate operational risks; test each after changes that touch shared shell UI.
|
||||
- Static asset size, GLB decode time, audio streaming, and image media size can affect mobile performance. Prefer lazy loading, caching, disposal, and unavailable states over loading unused assets.
|
||||
- Tencent Map SDK behavior, indoor Three.js/SGS Map SDK behavior, and audio playback behavior are separate operational risks; test each after changes that touch shared shell UI.
|
||||
- Static asset size, GLB decode time, SDK iframe/model startup, audio streaming, and image media size can affect mobile performance. Prefer lazy loading, caching, disposal, and unavailable states over loading unused assets.
|
||||
|
||||
Reference in New Issue
Block a user