chore: solidify guide P1 snapshot

.agents/skills/shenzhen-natural-museum-dev/SKILL.md

@@ -0,0 +1,211 @@
+---
+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.
+---
+
+# 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.
+
+## 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`.
+- 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.
+
+## Non-Negotiable 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 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.
+- 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.
+- Avoid unrelated refactors, broad file deletion, or data cleanup without explicit confirmation. Contain and mark legacy first; delete only when asked.
+
+## 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.
+   - 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.
+
+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 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`.
+
+## 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.
+- Prefer existing Three.js/GLTF patterns in the project. Add dependencies only when the repository lacks the needed loader/runtime.
+
+## 数据源标准
+
+- 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.
+
+## 三维导览数据审核模块
+
+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:
+
+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.
+
+2. Check professional 3D guide data 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 导览数据访问层 without rewriting page-level route/search/facility 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`.
+
+## Quality Gates
+
+Use these checks as the project baseline:
+
+```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 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.
+- 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/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.

.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml

@@ -0,0 +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."