feat: refine guide explain UX and QA docs
This commit is contained in:
@@ -1,43 +1,92 @@
|
||||
---
|
||||
name: shenzhen-natural-museum-dev
|
||||
description: Shenzhen Natural Museum frontend-miniapp H5 development standards. Use when working in this project on navigation, guide pages, indoor 3D/Three.js/GLB, Tencent Map/outdoor map logic, static nav assets, Guide Data Access Layer/导览数据访问层, data provider/adapter architecture, route_graph/nav_data readiness, 3D guide data audits, browser-simulated user-flow/user-acceptance audits, legacy demo data cleanup, mobile H5 compatibility, browser-based user flow testing, dead-end/return/state-loss/cancel-reset audits, quality gates, or architecture reviews for the museum guide H5 app. 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, 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 this repository's product work. The project may live under historical folder names, but the target product is the Shenzhen Natural Museum guide miniapp.
|
||||
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_20260609_075339`.
|
||||
- Current guide data service: `src/services/navAssets.ts`.
|
||||
- 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 and POI/location preview. Do not present it as certified real indoor navigation until `route_graph` and `nav_data` are available and verified.
|
||||
- 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 Rules
|
||||
## Non-Negotiable Architecture Rules
|
||||
|
||||
- Do not reintroduce business dependencies from the guide module to `src/assets/data/*.json`.
|
||||
- Keep guide data loading centralized through `src/services/navAssets.ts` or a deliberate successor service with the same clear boundary.
|
||||
- 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.
|
||||
- Treat POI coordinates from the clean package as display or preview candidates, not certified navigation anchors.
|
||||
- Keep `NAV_ROUTE_GRAPH_READY` false until real graph/nav data has been added, validated, and wired with tests or smoke verification.
|
||||
- Do not claim "开始馆内导航" or route planning is real unless the graph data exists. Prefer "位置预览", "查看位置", or an explicitly disabled state.
|
||||
- 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 must remain visible and clickable above the 3D canvas.
|
||||
- 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, map, route, asset, and data references.
|
||||
- Check routing/page entry points before editing UI behavior.
|
||||
- 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/guide`, `src/components/guide`, `src/services/navAssets.ts`, and related route/search/facility pages.
|
||||
- Do not touch hall/exhibit/explain demo modules unless the task is explicitly about legacy cleanup or cross-module data consistency.
|
||||
- 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.
|
||||
@@ -46,53 +95,111 @@ Use this skill for this repository's product work. The project may live under hi
|
||||
|
||||
4. Verify after changes:
|
||||
- Run the smallest meaningful checks, then expand based on risk.
|
||||
- For frontend/UI guide changes, prefer at least `pnpm type-check`, `pnpm lint`, and `pnpm build:h5`.
|
||||
- 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.
|
||||
- Always provide loading and error fallback states for model loading.
|
||||
- Keep canvas sizing constrained by the guide layout. It must not cover fixed navigation, cards, buttons, or floor controls.
|
||||
- Avoid automatic page jumps when opening the indoor 3D view or clicking "start" actions. Explicit user intent should route, preview, or show a disabled explanation.
|
||||
- Watch GLB weight and runtime memory. The clean package previously contained multiple GLBs totaling about 24 MB; load only the primary model needed for the current view unless there is a product reason to load more.
|
||||
- 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
|
||||
|
||||
- Use the clean manifest as the single guide data entry point.
|
||||
- If route/facility/search pages need POI data, consume normalized records from `src/services/navAssets.ts`.
|
||||
- Do not duplicate parsed nav data inside page components.
|
||||
- Use a Guide Data Access Layer/导览数据访问层 for all guide data. Pages and UI components must not bind directly to static JSON files or future backend API response shapes.
|
||||
- Treat `src/services/navAssets.ts` as the current 导览数据访问层 boundary. If it is replaced, the successor must keep the same boundary: pages consume normalized guide domain models, not raw static-package or API records.
|
||||
- Connect every data source through a Provider/Adapter architecture:
|
||||
- Static data packages use a Static Data Provider/静态数据源提供器.
|
||||
- Future backend APIs or database-backed services use an API Data Provider/接口数据源提供器.
|
||||
- Adapters/数据适配器 convert source-specific records into unified guide domain models such as floors, POIs, categories, model assets, connector endpoints, route previews, and future route graphs.
|
||||
- Keep current static-package fields and future API fields behind adapters. Do not let route/search/facility/detail pages depend on file paths, response field quirks, database IDs, or temporary migration aliases.
|
||||
- Use contract-first data evolution. Static packages and future APIs should expose compatible `schemaVersion`/dataset version metadata and preserve a stable domain model for `Floor`, `Poi`, `GuideAsset`, `ConnectorEndpoint`, `RoutePreview`, and future `RouteGraph`.
|
||||
- Keep phase boundaries explicit: phase 1 supports 3D display, POI search/filtering, and location preview; phase 2 route navigation requires `route_graph`, `nav_data`, verified anchors, and graph smoke tests.
|
||||
- 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;
|
||||
- unrelated historical demo modules;
|
||||
- deletion candidates that need user approval.
|
||||
- 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 navigation product, not just as JSON that parses:
|
||||
Audit the data as a spatial product, not just as JSON that parses:
|
||||
|
||||
1. Inventory the authoritative sources:
|
||||
- Identify clean package files under `static/nav-assets/...`, the manifest, GLB/GLTF assets, POI index, floor definitions, connector data, `route_graph`, `nav_data`, and code entry points that load them.
|
||||
- Confirm guide runtime pages consume data through `src/services/navAssets.ts` or an approved successor 导览数据访问层.
|
||||
- Treat 导览数据访问层 + 数据源提供器/数据适配器 as a required audit item. 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.
|
||||
- Check that static data packages and future API providers produce the same normalized guide domain models, or document the compatibility gap.
|
||||
- Mark `src/assets/data` as legacy/demo unless the task is explicitly about migrating it.
|
||||
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 3D guide data readiness:
|
||||
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.
|
||||
@@ -105,16 +212,57 @@ Audit the data as a navigation product, not just as JSON that parses:
|
||||
- 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 导览数据访问层 without rewriting page-level route/search/facility logic.
|
||||
- Verify that phase 2 route data can be added through the data access layer without rewriting page-level route/search/facility/explain logic.
|
||||
|
||||
4. Report data findings with evidence:
|
||||
- Separate `Verified data issue`, `Runtime integration issue`, and `Source-only risk`.
|
||||
- Include priority, affected asset/file, object IDs, observed mismatch, expected 3D guide standard, data-access-layer/provider/adapter impact, user impact, and suggested verification.
|
||||
- Save requested data-audit reports under `docs/QA/` using names like `3d-guide-data-audit-YYYY-MM-DD.md`.
|
||||
## 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:
|
||||
Use these checks as the project baseline for code changes:
|
||||
|
||||
```powershell
|
||||
pnpm type-check
|
||||
@@ -123,89 +271,17 @@ pnpm build:h5
|
||||
```
|
||||
|
||||
- Treat lint warnings as debt even if the command exits successfully.
|
||||
- Add or run H5 smoke checks for: top menu visibility, indoor 3D scene, "开始馆内导航"/preview action, search result click, and route/detail page.
|
||||
- For mobile risk, inspect small viewport behavior: overlays above canvas, no text/button overlap, no horizontal overflow, and no accidental full-screen canvas capture.
|
||||
- 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.
|
||||
|
||||
## Browser User Flow Closure Testing
|
||||
|
||||
Use this module when the user asks to test the Shenzhen Natural Museum guide app through browser automation, find user logic loops that do not close, audit dead ends, verify return behavior, or test multi-step guide/search/detail/route 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. If a runnable H5 URL or dev server is available, use the Browser in-app automation plugin with DOM snapshots, real clicks/taps, viewport changes, browser back, refresh, and deep-link checks.
|
||||
- Use screenshots when visual layering, mobile fit, 3D canvas coverage, or map 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, not just route URLs:
|
||||
- Home guide: outdoor map, indoor 3D 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: choose start, view position, search from detail, return from route.
|
||||
- Route detail: location preview, outdoor reference switch, target-location action, mode/floor/tool controls, browser reload.
|
||||
- Explain: tab switch, search drawer, hot/history keyword, result click, exhibit detail, audio/play/navigation actions.
|
||||
- Hall/exhibit detail: direct-open and in-flow-open behavior, visible back path, bottom action behavior.
|
||||
|
||||
3. Check these closure risks on every flow:
|
||||
- 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: route query, selected tab, 2D/3D mode, filter, search keyword, target, preview mode, 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 flows must have cancel, reset, retry, and completion paths.
|
||||
|
||||
4. Validate against current product truth:
|
||||
- Treat current capability as indoor 3D display plus POI/location preview until verified `route_graph` and `nav_data` exist.
|
||||
- Flag any UI that claims real route planning, start navigation, arrival, or certified guidance while `NAV_ROUTE_GRAPH_READY` is false.
|
||||
- Flag old mock data when it changes the user's selected object, e.g. a natural museum search result opens an unrelated historical demo detail.
|
||||
- Keep Tencent/outdoor map issues separate from indoor Three.js/GLB issues.
|
||||
|
||||
5. Report with evidence:
|
||||
- Separate browser-verified findings from source-only risks.
|
||||
- Mark a finding as browser-verified only when it was reproduced through actual browser steps. Source inspection can support evidence but cannot replace the browser user test.
|
||||
- For each finding include: priority, user path, observed behavior, expected closure, impact, and file/line evidence when available.
|
||||
- Mention positive paths that work, such as back buttons, close buttons, or state preservation.
|
||||
- If saving a report is requested, place it under `docs/QA/` using a date-based name such as `user-flow-closure-audit-YYYY-MM-DD.md`.
|
||||
|
||||
## 3D Guide User Audit Module
|
||||
|
||||
Use this module when the user asks for user review, usability audit, user acceptance testing, guided-path testing, or professional 3D guide user-flow review.
|
||||
|
||||
Audit whether a real visitor can complete the museum task, not only whether clicks fire:
|
||||
|
||||
1. Define visitor tasks before testing:
|
||||
- Find a facility or exhibit from the home guide.
|
||||
- Understand indoor vs outdoor context.
|
||||
- Preview a target location in 3D.
|
||||
- Recover from route unavailable, model load failure, search miss, location denial, or wrong target.
|
||||
- Switch between "导览" and "讲解" without losing necessary context.
|
||||
|
||||
2. Apply 3D guide UX standards:
|
||||
- Orientation: the user always knows current floor, map mode, target, and whether the view is indoor 3D or outdoor map.
|
||||
- Control visibility: top tabs/menu/search/cards/floor controls remain above canvas, tappable, and readable on mobile.
|
||||
- Flow closure: every start/target/search/preview route has visible back, cancel, reset, retry, and completion or disabled states.
|
||||
- Trust and truthfulness: labels must not promise real route planning, arrival guidance, turn-by-turn navigation, or positioning accuracy unless data and runtime support it.
|
||||
- Spatial feedback: selecting a POI should highlight or frame the location, not only show a toast.
|
||||
- Failure recovery: WebGL/model/network/location failures need fallback text, retry, and a route back to search or home.
|
||||
- Accessibility and comfort: avoid tiny touch targets, hidden controls, excessive motion, unreadable overlays, and ambiguous color-only state.
|
||||
|
||||
3. Test with realistic H5 paths:
|
||||
- Mobile viewport first; include a small-screen pass for overlay collisions and horizontal overflow.
|
||||
- Use real clicks/taps through Browser automation for user-audit conclusions whenever the H5 app can run. Do not substitute route-only checks, source reading, or static screenshots for simulated visitor behavior.
|
||||
- Screenshots are required when checking 3D/map layering, canvas coverage, mobile fit, or visual feedback after a POI/action click.
|
||||
- Test refresh/deep link/browser back for search result, facility detail, route preview, top tab switching, and unavailable route states.
|
||||
|
||||
4. Report user findings with evidence:
|
||||
- Separate browser-verified findings from source-only risks.
|
||||
- If a report could not run browser simulation, state that limitation at the top and avoid calling it a user test report.
|
||||
- Include priority, task, path, observed behavior, expected visitor outcome, impact, and file/line evidence when available.
|
||||
- Mention positive paths that work, especially preserved state, visible back/close controls, and useful fallbacks.
|
||||
- Save requested user-audit reports under `docs/QA/` using names like `3d-guide-user-audit-YYYY-MM-DD.md` or `user-flow-closure-audit-YYYY-MM-DD.md`.
|
||||
|
||||
## 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.
|
||||
- Historical demo data remains outside the guide module in areas such as hall, exhibit, and explain pages. Do not mix it back into the guide flow.
|
||||
- Tencent Map SDK behavior and indoor Three.js behavior are separate operational risks; test both after changes that touch shared guide shell UI.
|
||||
- Static asset size and GLB decode time can affect mobile performance. Prefer lazy loading, dispose Three.js resources on unmount, and avoid loading unused models.
|
||||
- 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.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "Shenzhen Natural Museum Dev"
|
||||
short_description: "H5 standards for guide, 导览数据访问层, 3D data audits, and user audits."
|
||||
default_prompt: "Use the Shenzhen Natural Museum frontend-miniapp H5 standards for guide, Three.js/GLB, Tencent Map, nav assets, 导览数据访问层 with data provider/adapter architecture, 三维导览数据审核, browser-simulated user-flow audits, legacy demo data, and H5 validation. Ignore mini-program/mp-weixin unless explicitly requested."
|
||||
short_description: "H5 spatial guide/explain architecture standards."
|
||||
default_prompt: "Use $shenzhen-natural-museum-dev to review or implement Shenzhen Natural Museum mobile H5 spatial content guide architecture, including guide, explain, data repositories, provider/adapter boundaries, browser user flows, and H5 quality gates."
|
||||
|
||||
Reference in New Issue
Block a user