lyf/frontend-miniapp

Fork 0

Files

lyf a7c1879f60 feat: refine guide explain UX and QA docs

2026-06-12 17:21:37 +08:00

23 KiB

Raw Blame History

name, description

name	description
shenzhen-natural-museum-dev	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.

name

description

shenzhen-natural-museum-dev

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.

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.

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:

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

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.
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.
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.
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.

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.
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.
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.

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:

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.
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.
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.