@@ -10,7 +10,7 @@ Use this skill for the Shenzhen Natural Museum `frontend-miniapp` project. Treat
|
||||
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.
|
||||
- `explain`: hall catalog -> explain-object catalog -> detail, plus audio explanation, transcript/chapters/media metadata, search/filtering, player state, and optional linkage from an explain object to a guide location preview.
|
||||
|
||||
## Project Ground Truth
|
||||
|
||||
@@ -22,6 +22,9 @@ The product has two first-class H5 businesses:
|
||||
- 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.
|
||||
- Current explain information architecture is `讲解 -> 展厅列表 -> 讲解对象列表 -> 讲解详情`. Do not insert a business-unit/outline list between a hall and its explain objects, and do not expose an "未分配单元" group.
|
||||
- Use `讲解对象` in user-facing H5 titles, cards, loading/empty/error states, and acceptance criteria. Treat backend `guide stop` / `STOP` / `stopId` and existing `ExplainGuideStop` names as integration or internal-domain terms; do not leak `讲解点` into new presentation copy or perform a broad internal rename without a scoped migration reason.
|
||||
- Treat `E:\MyWork\深圳国际艺术馆\智慧导览\smart-navigation-system\doc\miniapp_integration.md` as the authoritative explain API contract. Load halls from `/app-api/gis/guide/catalog/halls`, then page hall objects from `/app-api/gis/guide/catalog/halls/{hallId}/stops/page`; treat outline and non-paged hall-stop endpoints as migration compatibility only.
|
||||
|
||||
## Client Visual Design Standards
|
||||
|
||||
@@ -79,6 +82,7 @@ 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 the explain presentation flow hall-based. Hall selection must navigate directly to a hall-scoped explain-object list; `outlineCount`, business-unit grouping, and legacy outline routes must not control the current UI hierarchy.
|
||||
- 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.
|
||||
@@ -112,7 +116,7 @@ Guide data and explain data may share the same exhibit/hall/POI IDs, but their u
|
||||
|
||||
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.
|
||||
- For explain work, start around `src/pages/explain`, `src/components/explain`, `src/components/audio`, exhibit/hall detail pages, top-tab routing, `ExplainRepository`, `explainUseCase`, and explain providers/adapters.
|
||||
- Do not touch legacy hall/exhibit/explain demo data unless the task is explicitly about migration, compatibility, or cleanup.
|
||||
|
||||
3. Protect the H5 boundary:
|
||||
@@ -134,6 +138,7 @@ Guide data and explain data may share the same exhibit/hall/POI IDs, but their u
|
||||
- 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.
|
||||
- Keep hall explain-object pagination behind the provider/repository/use-case boundary. Normalize `data.list` and `data.total`, preserve snowflake IDs as strings, and keep `pageNo`, `pageSize`, and `lang` out of presentation components except through a page/query view model.
|
||||
- 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;
|
||||
@@ -248,6 +253,9 @@ Use this workflow when the user asks to connect the SGS Map SDK to the H5 guide
|
||||
## Explain And Media Standards
|
||||
|
||||
- Treat explain as a first-class content/media business, not as a decorative tab on the guide page.
|
||||
- Enforce the two-list flow: the explain entry shows halls; tapping a hall opens that hall's paged explain-object list; tapping an object opens detail. Do not create, retain, or route through a business-unit list for the current product flow.
|
||||
- Use the paged hall endpoint as the primary catalog path. Do not build the new list from `/outlines`, `/outlines/{outlineId}/stops`, or the non-paged `/halls/{hallId}/stops` compatibility endpoints.
|
||||
- Render catalog labels as `讲解对象` while preserving `STOP` and `stopId` for detail, playback, and text API requests. Use catalog `playTargetType` and `playTargetId` when available.
|
||||
- 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.
|
||||
@@ -282,6 +290,8 @@ Guide audit checklist:
|
||||
Explain audit checklist:
|
||||
|
||||
- Explain tab entry, list loading, filters, search drawer, hot/history keyword behavior.
|
||||
- Hall click navigates directly to a hall-scoped `讲解对象` list; no business-unit page, outline grouping, or "未分配单元" appears.
|
||||
- Explain-object pagination avoids duplicate rows across pages, stops at `total`, preserves string IDs, and exposes loading, empty, error/retry, and load-more failure states.
|
||||
- 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.
|
||||
@@ -306,6 +316,7 @@ Check:
|
||||
- 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.
|
||||
- Explain routing: remove the legacy hall -> business unit -> stop dependency from current entry points, deep links, and back fallbacks. Object-list back returns to the hall list; detail back returns to the same hall/object-list context where feasible.
|
||||
- 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.
|
||||
@@ -413,7 +424,7 @@ Use this module when the user asks to test the H5 app through browser automation
|
||||
- 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.
|
||||
- Explain: tab switch, hall click -> paged explain-object list -> object detail -> back to the same list -> back to halls; also verify search, audio play/pause/close, missing audio fallback, direct-open behavior, and retry/load-more failure states.
|
||||
- Hall/exhibit detail: direct-open and in-flow-open behavior, visible back path, top-tab preservation, bottom action behavior.
|
||||
|
||||
3. Check closure risks:
|
||||
@@ -442,6 +453,7 @@ 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 explain hierarchy changes, add focused tests for hall -> object-list routing, paged repository/use-case loading, `讲解对象` copy, detail targets, deep links, and list/detail back behavior. Assert that current entry points do not navigate to a business-unit route.
|
||||
- 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.
|
||||
|
||||
@@ -449,6 +461,7 @@ pnpm build:h5
|
||||
|
||||
- `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.
|
||||
- `src/pages/explain/business-unit-list.vue`, business-unit routes, unit-stage UI, and `listGuideStopsByBusinessUnit` calls are legacy presentation debt for the current explain flow. Do not use them as the new hall entry path; retire or isolate them only within the requested implementation scope while preserving unrelated dirty work.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user