frontend-miniapp/.claude/skills/shenzhen-natural-museum-dev/SKILL.md

---
name: shenzhen-natural-museum-dev
description: Shenzhen Natural Museum mobile H5 guide/explain architecture, indoor spatial rendering, content data, and client visual standards. Use in frontend-miniapp for guide/explain flows; visual styling, typography, hall icons, and homepage tabs; Three.js/GLB; unified guide-model initial state; deterministic overview/floor camera baselines; POI-detail return resets; async request invalidation; SGS Map SDK/iframe/postMessage integration; static/API data-source switching; POI/location previews; exhibit, hall, facility, audio, transcript, or media work; Tencent Map/outdoor logic; nav assets and data-layer architecture; route readiness; H5 browser-flow or business-logic audits; legacy-data cleanup; mobile canvas overlays; and quality gates. Treat mp-weixin as out of scope unless explicitly requested.
---

# Shenzhen Natural Museum Dev

Use this skill for the Shenzhen Natural Museum `frontend-miniapp` project. Treat the app as a mobile H5 spatial content guide platform, not as only an indoor 3D map.

The product has two first-class H5 businesses:

- `guide`: outdoor reference map, indoor 3D display, full-building/single-floor switching, POI search/focus, and POI/location preview. Real route planning requires verified `route_graph` and `nav_data`.
- `explain`: exhibit/hall content, audio explanation, transcript/chapters/media metadata, search/filtering, player state, and optional linkage from an explain item to a guide location preview.

## Project Ground Truth

- Main workspace: `E:\MyWork\深圳国际艺术馆\museum-guide\museum-guide-v4.0\frontend-miniapp`.
- Default runtime target: H5. Do not consider mini-program/mp-weixin constraints unless the user explicitly asks for them.
- Current clean nav asset package: `static/nav-assets/app_nav_assets_v2_clean_20260611_093623`.
- Current guide data boundary: `src/data/providers/staticNavAssetsProvider.ts` + `src/data/adapters/navAssetsAdapter.ts` + `src/repositories/GuideRepository.ts` / `src/repositories/GuideModelRepository.ts`.
- Current content/explain architecture is still transitional. Treat Provider / Adapter / Repository / UseCase as the current data boundary; do not reintroduce the retired legacy nav assets service.
- Legacy demo data area: `src/assets/data`. Treat it as historical/demo-only unless the user explicitly asks to inspect or migrate it.
- Current guide capability is indoor 3D display plus POI/location preview. Do not present it as certified real indoor navigation until `route_graph` and `nav_data` are available and verified.
- Current explain capability must be described as content/audio explanation only when real media data is available. Do not invent working audio, transcript, or exhibit data from placeholders.

## Client Visual Design Standards

Use `E:\MyWork\深圳国际艺术馆\museum-guide\docs\深圳自然博物馆0504-设计` as the primary client visual source when styling the Shenzhen Natural Museum H5 experience.

- Brand theme: follow "探索万物生息" and the creative idea "生物轨迹就是自然的地图".
- Visual language: prefer organic natural-history forms, biological traces, leaves, fossils, earth layers, micro-symbols, and clear educational structure over generic decorative gradients or unrelated illustration styles.
- Typography: use `鸿蒙黑体` first. Recommended CSS stack: `'鸿蒙黑体', 'HarmonyOS Sans SC', 'HarmonyOS Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif`.
- Color and surfaces: keep the existing light neutral system (`#FFFFFF`, `#F3F3F3`, `#F5F5ED`), near-black primary text (`#262421`), charcoal secondary text (`#424754`), and museum yellow-green accent `#E0E100` for selected/active states.
- Homepage top tabs: use `馆内` for the indoor guide field and `讲解` for the explain field.
- Hall identity: use the eight client-provided hall icons from `docs/深圳自然博物馆0504-设计/full.md`, stored in the H5 project under `static/icons/halls/`.

Hall icon mapping:

| Hall | H5 asset |
| --- | --- |
| 宇宙厅 | `/static/icons/halls/universe.jpg` |
| 地球厅 | `/static/icons/halls/earth.jpg` |
| 演化厅 | `/static/icons/halls/evolution.jpg` |
| 恐龙厅 | `/static/icons/halls/dinosaur.jpg` |
| 人类厅 | `/static/icons/halls/human.jpg` |
| 动物厅 | `/static/icons/halls/animal.jpg` |
| 生物厅 | `/static/icons/halls/biology.jpg` |
| 生态厅 | `/static/icons/halls/ecology.jpg` |
| 家园厅 | `/static/icons/halls/homeland.jpg` |

Use `生物厅` as the live-data alias for the sixth source-document hall (`动物厅`) until content taxonomy is reconciled. Render hall icons with `image` `mode="aspectFit"` so the client-provided art is not cropped, and fall back to a neutral placeholder only when no mapped asset exists.

## Non-Negotiable Architecture Rules

- Keep data and presentation decoupled. Pages and visual components must consume domain models or view models, not raw static package JSON, backend fields, GLB manifest details, or ad hoc demo arrays.
- Use this target layer shape for new or refactored work:

```text
Data Sources
static nav-assets / CMS API / backend API / IMDF / BIM export / media manifest
        ↓
Providers
StaticProvider / ApiProvider / CmsProvider / FutureImdfProvider
        ↓
Adapters
source-specific fields -> unified museum domain models
        ↓
Repositories / Data Access Layers
MuseumContentRepository / GuideRepository / ExplainRepository / MediaRepository
        ↓
Use Cases / Composables / Stores
guide session, explain session, search, selected target, player, route readiness
        ↓
Presentation ViewModels
lightweight props for pages, ThreeMap, ExplainList, cards, player, search
        ↓
Presentation Components
GuideMapShell / ThreeMap / ExplainList / AudioPlayer / Search / Cards
```

- Keep guide and explain coupled through stable IDs and domain relationships such as `poiId`, `exhibitId`, `hallId`, and `floorId`, not through component internals.
- Keep Tencent/outdoor map logic separate from indoor Three.js/GLB rendering. Do not make Tencent Map branches depend on indoor model state, and do not let indoor 3D changes alter outdoor map behavior.
- Keep `NAV_ROUTE_GRAPH_READY` false until real graph/nav data has been added, loaded, validated, and wired with smoke tests.
- Do not claim "开始馆内导航", route planning, arrival guidance, turn-by-turn navigation, or positioning accuracy unless route graph/nav data and runtime behavior are verified.
- Prefer "位置预览", "查看位置", "查看三维位置", or an explicitly disabled route state while route data is unavailable.
- Do not use placeholder media such as `example.com/audio.mp3` as a working explain capability. Show an unavailable state or load a real media asset through the media/explain data layer.
- Three.js/WebGL is H5-only for current project work. Do not add mini-program fallback or mp-weixin compatibility work unless specifically requested.
- Preserve mobile overlays: top tabs/menu/search/cards/floor controls/explain controls/audio player must remain visible and clickable above 3D canvas.
- Avoid unrelated refactors, broad file deletion, or data cleanup without explicit confirmation. Contain and mark legacy first; delete only when asked.

## Domain Model Standards

Use stable museum spatial content domain models when designing data services or audits:

- `MuseumVenue`, `MuseumBuilding`, `MuseumFloor`, `MuseumSpace`
- `MuseumPoi`, `MuseumHall`, `MuseumExhibit`, `MuseumFacility`, `MuseumCategory`
- `GuideModelAsset`, `GuideLocationPreview`, `GuideRouteReadiness`, `GuideRouteGraph`
- `ExplainTrack`, `ExplainMedia`, `ExplainTranscript`, `ExplainChapter`
- `MediaAsset`, `SearchIndexItem`, `UserCollection`, `VisitHistory`

Guide data and explain data may share the same exhibit/hall/POI IDs, but their use cases differ:

- Guide answers: Where is it, on which floor, what should the 3D/map preview show, is real routing ready?
- Explain answers: What is it, what should be played/read, what media/transcript is available, how can a visitor continue to a location preview?

## Development Workflow

1. Inspect before changing:
   - Use `rg`/`rg --files` to find guide, explain, audio, map, route, asset, and data references.
   - Check page entry points and shared shell components before editing behavior.
   - Read the local implementation instead of assuming the uni-app/Vue structure.

2. Scope changes tightly:
   - For guide work, start around `src/pages/index`, route/search/facility pages, `src/components/navigation`, `src/components/map`, `src/usecases/guideUseCase.ts`, and guide repositories/providers.
   - For explain work, start around `src/components/explain`, `src/components/audio`, exhibit/hall detail pages, top-tab routing, and the future content/explain repositories.
   - Do not touch legacy hall/exhibit/explain demo data unless the task is explicitly about migration, compatibility, or cleanup.

3. Protect the H5 boundary:
   - Default to H5 behavior, H5 styling, and H5 validation.
   - Use conditional compilation only when existing code requires it or when the user explicitly asks about mini-program support.
   - Do not spend time preserving or testing mp-weixin behavior unless the task names mini-program/mp-weixin.

4. Verify after changes:
   - Run the smallest meaningful checks, then expand based on risk.
   - For frontend/UI guide or explain changes, prefer at least `pnpm type-check`, `pnpm lint`, and `pnpm build:h5`.
   - Run `pnpm build:mp-weixin` only when the user explicitly requests mini-program validation.
   - Mention before running build commands if the task is read-only, because builds write `dist`.

## Data Source Standards

- Use clean manifests and future CMS/API manifests as source inputs, not as page/component contracts.
- Keep static package fields and future API fields behind providers/adapters. Do not let pages depend on file paths, response field quirks, database IDs, or temporary migration aliases.
- Keep all guide data loading centralized through providers/adapters/repositories/use cases. Do not let pages or components import static-package readers directly.
- Introduce content/explain/media repositories before migrating explain pages out of hardcoded arrays.
- Do not duplicate parsed POI, floor, category, model path, explain media, transcript, or route readiness logic in page components.
- Use contract-first data evolution. Static packages, future APIs, and CMS data should expose compatible `schemaVersion`/dataset metadata and preserve stable domain models.
- Mark old demo compatibility explicitly when a temporary bridge is unavoidable.
- If cleaning old mock data, first inventory references with `rg`, then split work into:
  - guide-critical stale data that blocks current work;
  - explain/content demo data that needs repository migration;
  - 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.
- Initial indoor 3D entry should load the full building model when that is the product requirement; switch to a single floor only after zoom/focus/explicit floor action.
- Treat guide-model state restoration as one state-management contract, not as page-specific cleanup. Read and follow [references/guide-model-state-baseline.md](references/guide-model-state-baseline.md) whenever work touches initial model state, overview/floor camera baselines, POI focus, detail navigation/return, floor loading, reset behavior, or model async races.
- Keep `GUIDE_MODEL_INITIAL_STATE`, floor-view baselines, reset actions, and one-shot POI-detail return context behind the existing shared guide-model state boundary. Do not let search, map-click, hall, exhibit, or facility flows own separate reset behavior.
- Preserve the mounted `ThreeMap`, WebGL renderer, scene, and valid model cache during business-state reset. Never use reload, `reLaunch`, component keys, renderer recreation, or repeated cached GLB parsing as a reset mechanism.
- Provide side controls or equivalent for full-building/multi-floor versus single-floor views.
- Always provide loading, error, retry, and recovery paths for model loading.
- Keep canvas sizing constrained by the guide layout. It must not cover fixed navigation, cards, buttons, floor controls, search, top tabs, or explain/player controls.
- Avoid automatic page jumps when opening indoor 3D or clicking "start" actions. Explicit user intent should preview, route to search/detail, or show a disabled explanation.
- Watch GLB weight and runtime memory. Load only the primary model needed for the current view unless there is a product reason to load more.
- Prefer existing Three.js/GLTF patterns in the project. Add dependencies only when the repository lacks the needed loader/runtime.
- Keep `ThreeMap` focused on rendering, camera, model lifecycle, POI visual highlighting, and emitted interactions. Move manifest parsing, floor/POI adapters, and route readiness outside of the renderer when refactoring.

## Explain And Media Standards

- Treat explain as a first-class content/media business, not as a decorative tab on the guide page.
- Use explain/content repositories for exhibits, halls, tracks, transcripts, chapters, cover images, audio URLs, duration, language, and availability.
- Keep `ExplainList` focused on presentation, filtering controls, and emitted user actions. Do not keep long-lived mock exhibit arrays or search indexes in the component once repository data is available.
- Keep `AudioPlayer` focused on playback, progress, seek, pause/resume, error, and teardown. Do not fetch content, infer exhibit data, or decide guide location behavior inside the player.
- Let explain items reference guide context through IDs such as `poiId`, `floorId`, `hallId`, or `exhibitId`. Clicking "查看位置" should invoke a guide location preview use case, not fake navigation.
- Represent unavailable audio/transcripts explicitly. Do not silently replace missing media with placeholder URLs.
- Preserve player and top-tab state across common H5 flows when product expectations require it: explain list -> exhibit detail -> back, guide -> explain -> guide, and audio mini-player open/close.
- Audit exhibit/hall detail pages for historical demo content before treating them as current natural museum content.

## Business Logic Audit Module

Use this module when the user asks for business review, cross-business review, P1/P2/P3 audit, Shenzhen Science and Technology Museum interaction comparison, or guide/explain user-flow logic review.

Report with:

- Priority: P1/P2/P3.
- Evidence: file path and line number.
- Status: `已实现`, `部分实现`, `缺失`, or `数据不足导致无法判断`.
- Evidence type: `源码审核`, `浏览器验证`, or both.
- Suggested repair order.

Guide audit checklist:

- Initial outdoor/indoor state.
- Indoor entry default full-building model when required.
- Full-building/multi-floor versus single-floor switching.
- Floor switching and floor state.
- POI search, highlight, and location preview.
- Route readiness and no false route/navigation claims.
- Top "导览 / 讲解" switching.
- Search, cards, floor controls, tool buttons, and top tabs visible/clickable above canvas.

Explain audit checklist:

- Explain tab entry, list loading, filters, search drawer, hot/history keyword behavior.
- Exhibit/hall detail transitions, return paths, and top-tab preservation.
- Audio play/pause/close, mini-player visibility, missing media fallback, playback state loss.
- Transcript/chapter/language availability if data claims them.
- "查看位置" or location actions must use location preview and must not promise real routing unless route data is verified.
- No hardcoded historical art-demo content should appear as current natural museum data unless explicitly marked as legacy.

## Engineering Architecture Audit Module

Use this module when the user asks whether frontend architecture follows the spatial content guide strategy.

Check:

- Page layer: pages should compose use cases and view models, not parse raw data or own long-lived source arrays.
- 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, 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

Use this module when the user asks for data review, nav data readiness, POI audit, route graph audit, GLB/3D guide data validation, or professional 3D guide industry review.

Audit the data as a spatial product, not just as JSON that parses:

1. Inventory authoritative sources:
   - Identify clean package files under `static/nav-assets/...`, manifest, GLB/GLTF assets, POI index, floor definitions, connector data, `route_graph`, `nav_data`, and code entry points.
   - Confirm runtime pages consume guide data through `GuideUseCase`, `GuideRepository`, `GuideModelRepository`, or approved data access successors rather than static-package files.
   - Flag any page, component, store, or utility that directly parses static-package files, directly depends on backend API response shapes, or duplicates source-specific transformation logic.
   - Mark `src/assets/data` as legacy/demo unless the task explicitly asks to migrate it.

2. Check professional guide readiness:
   - Coordinate system: every POI, floor, entrance, connector, and preview marker must declare or inherit the same coordinate space as the rendered GLB/GLTF.
   - Floor semantics: floor IDs, labels, order, elevation, and visible floor controls must match the model and UI.
   - POI quality: each POI needs stable `id`, display name, category, floor, source confidence, display coordinate, and enough context for search/detail/preview.
   - Topology: real navigation requires verified nodes, edges, weights, floor transitions, one-way/blocked paths, accessible routes, and vertical connectors.
   - Anchors: POI coordinates from detection or semantic extraction are preview candidates until human- or test-verified against accessible entrances and walkable surfaces.
   - Asset integrity: GLB/GLTF/bin/textures must preserve relative paths, load on H5, and have size/performance risk noted for mobile.
   - Indoor/outdoor separation: Tencent/outdoor entrance data must not be treated as indoor route graph data.

3. Gate route readiness:
   - Keep `NAV_ROUTE_GRAPH_READY` false until `route_graph` and `nav_data` exist, are loaded, and pass smoke tests.
   - Do not approve route planning if graph nodes are unreachable, connectors are missing, floors are misaligned, or POI anchors are not mapped to walkable graph nodes.
   - If only preview data exists, report the capability as "位置预览" and list missing data needed for real navigation.
   - Verify that phase 2 route data can be added through the data access layer without rewriting page-level route/search/facility/explain logic.

## Explain Content Data Audit Module

Use this module when the user asks for explain/audio/content readiness.

Check:

- Content authority: exhibits, halls, facilities, themes, categories, and media must come from an approved content/explain repository or clearly marked legacy bridge.
- Media integrity: audio URLs, cover images, transcripts, chapter timings, duration, language, and availability must be real and loadable on H5.
- Cross-linking: explain tracks should link to exhibit/hall/POI/floor IDs that can resolve to content and optional location preview.
- Search quality: explain search should use the same normalized content/search index strategy as guide search where sensible.
- Truthfulness: UI must not claim audio, transcript, or guided explanation exists when the data is missing.
- Player lifecycle: audio context cleanup, error handling, seek/progress, pause/resume, and back/top-tab transitions must be tested.

## Browser User Flow Closure Testing

Use this module when the user asks to test the H5 app through browser automation, find user logic loops that do not close, audit dead ends, verify return behavior, or test guide/explain/search/detail flows.

1. Prepare the target:
   - If the user provides a URL, use it directly.
   - If the user says to use the actual project or a temporary service, inspect `package.json` and start the smallest H5 dev server command that matches the repo; report the local preview URL.
   - Treat browser simulation as the evidence baseline for user testing. Use real clicks/taps, DOM snapshots, viewport changes, browser back, refresh, and deep-link checks when a runnable H5 URL is available.
   - Use screenshots when visual layering, mobile fit, 3D canvas coverage, or map/audio overlay behavior matters.
   - If browser verification is impossible, label findings as `source-only risk`; do not present them as user-tested or browser-verified.
   - Keep the test scoped to H5 unless the user explicitly asks for mp-weixin.

2. Simulate real user tasks:
   - Home guide: outdoor map, indoor 3D switch, full-building/single-floor switch, primary guide CTA, search entry, recommended entrance flow.
   - Search: keyword entry or existing query, filters, result card click, result action click, browser/back navigation.
   - Facility/detail/route preview: choose target, view position, unavailable route state, return/reset/cancel.
   - Explain: tab switch, search drawer, hot/history keyword, result click, exhibit detail, audio play/pause/close, missing audio fallback.
   - Hall/exhibit detail: direct-open and in-flow-open behavior, visible back path, top-tab preservation, bottom action behavior.

3. Check closure risks:
   - Dead end after click: page stays stuck, white screen, missing content, or action only logs/toasts without a useful next step.
   - Interrupted task: button text promises navigation/search/audio/selection but there is no continuation, completion, or recovery instruction.
   - State loss: selected tab, 2D/3D mode, full-building/floor mode, filter, search keyword, target, preview mode, audio item/progress, or route step disappears after navigation, refresh, share/deep link, or browser back.
   - Missing return control: custom-navigation pages must provide a visible in-page back/cancel/close path, not only rely on browser/system back.
   - Multi-step trap: start/target/location/route/explain flows must have cancel, reset, retry, and completion or disabled states.

4. Validate against current product truth:
   - Treat guide capability as indoor 3D display plus POI/location preview until verified `route_graph` and `nav_data` exist.
   - Treat explain capability as content/audio playback only when real media data exists.
   - Flag UI that claims route planning, start navigation, arrival, certified guidance, audio, transcript, or explain content while data/runtime support is missing.
   - Flag old mock data when it changes the user's selected object or shows unrelated historical demo detail.
   - Keep Tencent/outdoor map, indoor Three.js, and audio player risks separate.

## Quality Gates

Use these checks as the project baseline for code changes:

```powershell
pnpm type-check
pnpm lint
pnpm build:h5
```

- Treat lint warnings as debt even if the command exits successfully.
- Add or run H5 smoke checks for top tabs, guide/explain tab switching, indoor 3D scene, full-building/single-floor control, search result click, route/detail preview, explain search, and audio play/pause/close when affected.
- For mobile risk, inspect small viewport behavior: overlays above canvas, no text/button overlap, no horizontal overflow, no accidental full-screen canvas capture, and no audio player overlap with critical controls.
- If the user explicitly asks for mini-program/mp-weixin, add `pnpm build:mp-weixin` as an extra check for that task only.

## Known Risk Radar

- `src/components/map/ThreeMap.vue` may still directly parse clean package manifest/floor/POI data. Treat this as transitional and flag it in architecture audits.
- `src/components/explain/ExplainList.vue`, exhibit detail, and hall detail may still contain hardcoded or historical demo data. Treat these as migration targets for content/explain repositories.
- 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 the independently deployed `/engine/index.html`. Treat an SPA fallback HTTP 200 as unhealthy; validate Engine title/assets and `HELLO` -> `ENGINE_READY`.
- 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/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.