diff --git a/.agents/skills/shenzhen-natural-museum-dev/SKILL.md b/.agents/skills/shenzhen-natural-museum-dev/SKILL.md new file mode 100644 index 0000000..1a67a22 --- /dev/null +++ b/.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. diff --git a/.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml b/.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml new file mode 100644 index 0000000..9de2fa5 --- /dev/null +++ b/.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." diff --git a/README.md b/README.md index b667c4a..d47839a 100644 --- a/README.md +++ b/README.md @@ -115,6 +115,10 @@ pnpm build:h5 pnpm build:mp-weixin ``` +## 部署 + +H5 线上部署、Nginx 配置、模型资源校验和回滚步骤见 [docs/H5_DEPLOYMENT_GUIDE.md](docs/H5_DEPLOYMENT_GUIDE.md)。 + ## 功能特性 - ✅ 地图导览（楼层切换、POI 标记） diff --git a/docs/H5_DEPLOYMENT_GUIDE.md b/docs/H5_DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..65d00b0 --- /dev/null +++ b/docs/H5_DEPLOYMENT_GUIDE.md @@ -0,0 +1,204 @@ +# H5 部署说明 + +最后更新：2026-06-10 + +## 目标环境 + +- 域名：https://guide.whaoyue.com/ +- SSH 连接别名：`自然博物馆-测试服务器` +- 服务器 IP：`1.92.206.90` +- 站点宿主目录：`/dmdata/nginx/html/guide` +- Nginx 配置：`/dmdata/nginx/conf.d/guide.whaoyue.com.conf` +- Nginx 容器：`nginx-server` +- H5 构建目录：`dist/build/h5` + +说明：Nginx 容器内站点根目录为 `/usr/share/nginx/html/guide`，宿主机对应目录为 `/dmdata/nginx/html/guide`。 + +## 本地构建 + +在项目根目录执行： + +```powershell +pnpm install +pnpm type-check +pnpm build:h5 +``` + +`pnpm build:h5` 会先执行 `uni build -p h5`，再执行 `scripts/copy-h5-nav-assets.cjs`，把 `static/nav-assets` 复制到 `dist/build/h5/static/nav-assets`。 + +构建后重点检查： + +```powershell +Get-ChildItem -LiteralPath 'dist\build\h5\static\nav-assets\app_nav_assets_v2_clean_20260609_075339' -Recurse -File | + Measure-Object Length -Sum | + Select-Object Count,Sum +``` + +当前导航模型资源包应包含 `25` 个文件，文件总字节数约 `26811587`。 + +## 部署步骤 + +生成部署包： + +```powershell +New-Item -ItemType Directory -Force -Path '.tmp' | Out-Null +$archive = '.tmp\museum-guide-h5.tar.gz' +if (Test-Path -LiteralPath $archive) { Remove-Item -LiteralPath $archive -Force } +tar -C 'dist\build\h5' -czf $archive . +``` + +上传到服务器： + +```powershell +scp -o BatchMode=yes '.tmp\museum-guide-h5.tar.gz' '自然博物馆-测试服务器:/tmp/museum-guide-h5.tar.gz' +``` + +替换线上站点： + +```powershell +ssh -o BatchMode=yes '自然博物馆-测试服务器' 'set -e +SITE=/dmdata/nginx/html/guide +ARCHIVE=/tmp/museum-guide-h5.tar.gz +TS=$(date +%Y%m%d%H%M%S) +BACKUP_DIR=/dmdata/nginx/html/_backups +[ "$SITE" = "/dmdata/nginx/html/guide" ] +test -f "$ARCHIVE" +mkdir -p "$SITE" "$BACKUP_DIR" +tar -C "$SITE" -czf "$BACKUP_DIR/guide-before-deploy-$TS.tar.gz" . +find "$SITE" -mindepth 1 -maxdepth 1 ! -name ".well-known" -exec rm -rf -- {} + +tar -C "$SITE" -xzf "$ARCHIVE" +mkdir -p "$SITE/.well-known/acme-challenge" +chown -R root:root "$SITE" +docker exec nginx-server nginx -t +docker exec nginx-server nginx -s reload +printf "backup=%s\n" "$BACKUP_DIR/guide-before-deploy-$TS.tar.gz" +printf "files=%s\n" "$(find "$SITE" -type f | wc -l)" +' +``` + +## Nginx 关键配置 + +`/static/nav-assets/` 必须独立配置，避免模型、manifest、楼层数据缺失时落入 SPA 的 `/index.html` 回退。 + +```nginx +location ^~ /static/nav-assets/ { + types { + application/json json; + model/gltf-binary glb; + model/gltf+json gltf; + text/csv csv; + text/markdown md; + } + default_type application/octet-stream; + expires 30d; + add_header Cache-Control "public"; + try_files $uri =404; +} + +location / { + try_files $uri $uri/ /index.html; +} +``` + +每次修改配置后执行： + +```powershell +ssh -o BatchMode=yes '自然博物馆-测试服务器' 'docker exec nginx-server nginx -t && docker exec nginx-server nginx -s reload' +``` + +## 部署后验证 + +公网资源响应： + +```powershell +curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/app_nav_manifest.json +curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/models_by_floor/L1.glb +curl.exe -I --max-time 30 https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/models_by_floor/MISSING.glb +``` + +预期结果： + +- `app_nav_manifest.json`：`200`，`Content-Type: application/json` +- `models_by_floor/L1.glb`：`200`，`Content-Type: model/gltf-binary` +- 缺失 GLB：`404`，不能返回 `index.html` + +### 域名根目录校验文件 + +如第三方平台要求在域名根目录放置 TXT 校验文件，可上传到站点宿主目录： + +```powershell +scp -o BatchMode=yes 'E:\MyWork\深圳自然馆\服务器信息\对接文档\gpL0svkeao.txt' '自然博物馆-测试服务器:/dmdata/nginx/html/guide/gpL0svkeao.txt' +``` + +验证： + +```powershell +curl.exe -L --max-time 30 https://guide.whaoyue.com/gpL0svkeao.txt +``` + +当前 `gpL0svkeao.txt` 预期返回： + +```text +b772216640a14171ba5655085c8523be +``` + +页面验证： + +- 打开 https://guide.whaoyue.com/#/ +- 切换到 `室内3D` +- 首次进入应加载当前楼层模型，而不是先加载全馆 overview 模型 +- 不应出现 `Unexpected token '<', " 点击搜索框 -> 搜索页 | 成功进入 `/pages/search/index` | 搜索页默认关键词为“卫生间”。 | +| 搜索页 -> 结果卡片“查看” -> 路线页 | 最终可渲染路线详情页 | 首次进入时出现过短暂空白，后续编译完成后恢复。 | +| 路线页 -> 查看室外地图 -> 返回预览 | 可切换到 `outdoor-preview`，并通过按钮回到 `preview` | `handleViewOutdoorMap` 与 `handleReturnToPreview` 有明确状态切换。 | +| 搜索页 -> 设施卡片 -> 设施详情 -> 浏览器返回 | 可回到搜索页 | 测试中搜索筛选状态保留，例如“无障碍”过滤未丢失。 | +| 首页室内 3D 主 CTA | 已从“开始馆内导航”调整为“选择目标地点”并跳搜索页 | 避免直接进入未完成的路线规划态。 | + +## 浏览器验证问题 + +### P1：自定义导航页面缺少页面级返回/取消闭环 + +用户路径：搜索页 -> 设施详情页 / 路线详情页 +观察结果：页面使用自定义导航后，顶部统一展示“导览 / 讲解”切换，但详情和路线页没有清晰的页面级返回、关闭或取消入口；测试中主要依赖浏览器或系统返回恢复。 +期望闭环：二级页应在顶部或内容区提供明确的“返回上一页/取消本次选择/回到搜索结果”路径，并保留搜索关键词、筛选、目标对象和预览状态。 +影响：用户可以进入详情或路线页，但如果没有浏览器返回习惯，容易认为流程已卡死；在 H5 壳或嵌入式容器里，这个风险更高。 +源码证据： + +- `src/pages.json:11` 至 `src/pages.json:47`：搜索、设施详情、路线详情等页面均配置 `navigationStyle: "custom"`。 +- `src/components/navigation/GuidePageFrame.vue:3` 至 `src/components/navigation/GuidePageFrame.vue:9`：页面框架只注入 `GuideTopTabs` 和内容 slot，没有返回/关闭能力。 +- `src/components/navigation/GuideTopTabs.vue:3` 至 `src/components/navigation/GuideTopTabs.vue:12`：顶部控件只渲染全局 tab。 +- `src/utils/guideTopTabs.ts:14` 至 `src/utils/guideTopTabs.ts:17`：tab 切换使用 `uni.reLaunch` 回首页 tab，不是页面返回。 + +建议：保留全局 `GuideTopTabs`，但在 `GuidePageFrame` 增加可选页面级 back/cancel 插槽或 props。搜索、设施详情、路线详情应显式提供返回上一页；路线/起点选择等多步骤页还应提供“取消本次导航/重置目标”。 + +### P1：搜索结果页不能重新输入或重置搜索 + +用户路径：首页导览 -> 搜索框 -> 搜索页 -> 点击搜索页顶部搜索框 +观察结果：点击搜索页顶部搜索框后只保持当前页，未打开输入框、搜索弹层或清空/重搜流程。 +期望闭环：用户应能在搜索结果页继续编辑关键词、清空关键词、提交新搜索，并能保留或重置筛选条件。 +影响：搜索是导览任务的主要入口。如果用户第一次默认进入“卫生间”结果后想改搜展厅、入口或设施，目前只能绕路返回首页再进，任务链路被打断。 +源码证据： + +- `src/pages/search/index.vue:94`：默认 `searchKeyword` 为“卫生间”。 +- `src/pages/search/index.vue:153` 至 `src/pages/search/index.vue:157`：路由参数可覆盖关键词并加载结果。 +- `src/pages/search/index.vue:160` 至 `src/pages/search/index.vue:162`：`handleSearchTap` 仅 `console.log('保持搜索结果页')`。 +- `src/pages/search/index.vue:168` 至 `src/pages/search/index.vue:177`：结果卡片和“查看”可以继续跳详情/路线，但搜索本身没有再输入闭环。 + +建议：搜索页顶部搜索框应进入真实输入态。最小修复可以是打开一个输入面板，支持确认搜索、清空关键词和取消；更完整的方案是把首页搜索和搜索页搜索抽成同一套搜索组件。 + +### P1：路线页“查看目标位置”没有形成下一步 + +用户路径：搜索页 -> 结果“查看” -> 路线详情页 -> 点击“查看目标位置” +观察结果：按钮只显示“正式路线数据尚未接入，可先查看馆内三维位置”的提示，没有切换到目标位置高亮、POI 卡片、3D 定位或可恢复状态。 +期望闭环：在真实路线数据未接入前，按钮文案和行为应稳定落到“位置预览”：例如高亮目标 POI、展示楼层/区域/说明、提供返回搜索和查看室外参考入口。 +影响：用户已经选择目标，但点击后没有获得更多可操作信息，会误以为目标定位失败或导航不可用。 +源码证据： + +- `src/services/navAssets.ts:3`：路线不可用提示为“正式路线数据尚未接入，可先查看馆内三维位置”。 +- `src/pages/route/detail.vue:333` 至 `src/pages/route/detail.vue:338`：`handleShowTargetLocation` 仅 `uni.showToast`。 +- `src/pages/route/detail.vue:329` 至 `src/pages/route/detail.vue:341`：室外预览有状态切换和返回，但目标位置按钮没有同等状态落点。 +- `src/pages/route/detail.vue:84`：室外预览文案说明真实馆内路线需等待 `route_graph/nav_data` 接入。 + +建议：短期把该动作改为“高亮目标位置/查看位置详情”，并切换到明确的 preview 子状态；中期接入 POI 坐标后，在 3D 视图中定位目标点；正式导航能力上线前，不使用“开始导航/路线规划已完成”等表述。 + +### P1：设施详情“选择起点”没有起点选择流程 + +用户路径：搜索页 -> 设施详情 -> 点击“选择起点” +观察结果：按钮只显示“请选择当前位置”，没有进入定位、手动选点、取消、确认或重置流程。 +期望闭环：起点选择应至少包含“使用当前位置 / 手动选择 / 取消”的状态，并把起点写入路线页参数或共享状态；失败时应说明原因和恢复路径。 +影响：用户无法完成“从哪里到目标设施”的前置步骤。即使之后点击查看位置/路线页，也只是目标预览，不是起点到终点的闭环。 +源码证据： + +- `src/pages/facility/detail.vue:118` 至 `src/pages/facility/detail.vue:123`：`handleChooseStart` 仅 `uni.showToast`。 +- `src/pages/facility/detail.vue:125` 至 `src/pages/facility/detail.vue:129`：主按钮直接进入路线 `state=preview`，没有携带起点。 +- `src/pages/route/detail.vue:348` 至 `src/pages/route/detail.vue:352`：路线页手动选择也只是 `toast`。 + +建议：先把“选择起点”改造成受控步骤：进入 `selecting-start` 状态，显示取消、确认和手动位置候选；没有定位能力时明确禁用真实起点选择，并提供“只查看目标位置”。 + +### P2：首次进入路线页可能出现短暂空白，应有加载/降级态 + +用户路径：搜索页 -> 第一个结果“查看” -> 路线详情页 +观察结果：浏览器测试中首次进入路线页有过短暂空白，之后页面完成渲染。该现象在开发服务中可能由 Vite 首次编译或异步资源加载造成。 +期望闭环：即使在首次加载、资源未就绪或 3D 资源较慢时，也应显示稳定的页面骨架、加载中、失败重试和返回路径。 +影响：移动端网络或 WebGL 资源加载慢时，用户可能在白屏阶段退出；如果没有错误恢复，路线页会被认为不可用。 +源码证据： + +- `src/pages/route/detail.vue:2` 至 `src/pages/route/detail.vue:96`：路线页主要内容挂在 `GuidePageFrame` 内，当前浏览器现象需要后续用生产构建验证加载态是否足够。 +- `src/components/navigation/GuidePageFrame.vue:35` 至 `src/components/navigation/GuidePageFrame.vue:60`：框架是满屏布局，内容未就绪时需要页面自身提供可见占位。 + +建议：路线页增加首屏 loading skeleton 和错误 fallback；对 3D/静态资源加载失败要给“重试 / 返回搜索 / 仅查看文字位置”的降级路径。此项需要用 `pnpm build:h5` 后的 H5 预览再验证一次。 + +### P2：全局顶部 tab 切换会重启首页，可能丢失当前二级流程 + +用户路径：设施详情或路线页 -> 点击顶部“讲解/导览” +观察结果：顶部 tab 是全局切换，调用 `uni.reLaunch` 进入首页指定 tab。它适合全局入口切换，但不保留当前搜索、设施或路线流程。 +期望闭环：全局顶部菜单可以保持全局跳转，但二级流程页应同步提供独立返回/取消；如果用户正在多步骤任务中，切走前可考虑确认或保存上下文。 +影响：用户误触顶部 tab 后，当前目标、筛选和路线预览上下文可能被抛弃。 +源码证据： + +- `src/utils/guideTopTabs.ts:12` 至 `src/utils/guideTopTabs.ts:17`：所有 tab 切换都 `reLaunch` 到首页。 +- `src/components/navigation/GuidePageFrame.vue:3` 至 `src/components/navigation/GuidePageFrame.vue:6`：所有使用该框架的页面都会显示顶部 tab。 + +建议：将顶部 tab 定义为全局主导航；把“返回/取消/继续当前任务”定义为页面导航。二者不要混用。对路线、起点选择、搜索结果这类有上下文的页面，增加页面内保护和恢复。 + +## 源码侧风险补充 + +| 风险 | 当前证据 | 处理建议 | +| --- | --- | --- | +| 路线能力仍是预览态 | `src/services/navAssets.ts:3` 保留正式路线未接入提示；`src/pages/route/detail.vue:84` 明确等待 `route_graph/nav_data` | 所有 UI 文案统一为“位置预览/查看位置”，避免“真实导航”承诺。 | +| 搜索默认词会影响用户意图 | `src/pages/search/index.vue:94` 默认“卫生间” | 默认结果可以保留，但必须允许立即编辑、清空和重新搜索。 | +| 起点未写入路线参数 | `src/pages/facility/detail.vue:125` 至 `src/pages/facility/detail.vue:129` 只传 `facilityId/target/state` | 增加 start 参数或共享状态，并定义取消/重置。 | +| 顶部菜单不是返回按钮 | `src/utils/guideTopTabs.ts:14` 至 `src/utils/guideTopTabs.ts:17` 使用 `reLaunch` | 继续作为全局菜单使用，同时给页面加 back/cancel。 | + +## 建议修复顺序 + +1. P1：给 `GuidePageFrame` 增加页面级返回/取消能力，并在搜索、设施详情、路线详情启用。 +2. P1：补齐搜索页顶部搜索框的输入、清空、取消、重新提交。 +3. P1：把设施详情“选择起点”改为明确的起点选择步骤；未接定位时使用禁用态或预览态文案。 +4. P1：把路线页“查看目标位置”落到真实 preview 子状态，不再只是 toast。 +5. P2：给路线页和 3D/位置预览增加加载、失败、重试、返回搜索的降级 UI。 +6. P2：为全局顶部 tab 切换和二级流程上下文定义保存或确认策略。 + +## 回归测试用例 + +| 用例 | 操作 | 预期 | +| --- | --- | --- | +| 搜索页重搜 | 首页 -> 搜索 -> 点击搜索页搜索框 -> 输入新关键词 -> 确认 | 结果按新关键词刷新，可清空，可取消回原结果。 | +| 搜索筛选保留 | 搜索页选择“无障碍” -> 打开设施详情 -> 返回 | 回到搜索页后筛选和关键词保持。 | +| 设施起点取消 | 设施详情 -> 选择起点 -> 取消 | 返回设施详情，不丢失目标设施。 | +| 设施起点确认 | 设施详情 -> 选择起点 -> 确认 -> 查看位置 | 路线页能读取目标和起点；未接真实路线时明确展示预览态。 | +| 路线目标预览 | 搜索结果“查看” -> 路线页 -> 查看目标位置 | 页面出现目标位置高亮或目标卡片，不只 toast。 | +| 路线室外返回 | 路线页 -> 查看室外地图 -> 返回预览/返回室内 3D | 状态回到室内预览，目标对象不丢失。 | +| 二级页返回 | 搜索 -> 设施详情/路线页 -> 点击页面返回 | 返回上一页，搜索关键词和筛选保留。 | +| 顶部 tab 误触 | 路线页 -> 点击“讲解” -> 再回导览 | 行为符合产品定义；若会丢失路线上下文，应有明确提示或可恢复路径。 | +| 首次加载路线 | 清缓存或首次打开 -> 搜索结果“查看” -> 路线页 | 不出现无反馈白屏；至少显示 loading、失败重试和返回。 | + +## 本次测试边界 + +- 本报告接续旧会话的浏览器自动化结果，没有在当前会话重新启动 H5 服务或重复跑全量点击。 +- 本报告只覆盖 H5 用户逻辑闭环，不覆盖 mp-weixin。 +- 真实室内路线规划、定位、到达判定不在当前已验证能力内；需等待 `route_graph/nav_data` 接入并完成独立验证。 +- 当前文档只新增测试报告，不修改业务实现。 diff --git a/docs/SHENZHEN_NATURAL_MUSEUM_DEV_SKILL_USAGE.md b/docs/SHENZHEN_NATURAL_MUSEUM_DEV_SKILL_USAGE.md new file mode 100644 index 0000000..cc285ab --- /dev/null +++ b/docs/SHENZHEN_NATURAL_MUSEUM_DEV_SKILL_USAGE.md @@ -0,0 +1,132 @@ +# shenzhen-natural-museum-dev Skill 使用说明 + +本文档说明项目专用 Codex skill `shenzhen-natural-museum-dev` 的使用方式、触发场景和维护规则。该 skill 用于固化深圳自然博物馆 `frontend-miniapp` 项目的导览、三维模型、腾讯地图、静态资源、历史 demo 数据和 H5 质量标准。 + +## Skill 位置 + +- Skill 主文件：`.agents/skills/shenzhen-natural-museum-dev/SKILL.md` +- Skill 展示元数据：`.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml` + +说明文档放在 `docs/` 下，而不是放进 skill 目录。skill 目录应保持精简，只保留 AI 执行任务所需的必要文件。 + +## 什么时候使用 + +处理以下任务时应使用该 skill： + +- 导览模块页面、组件、交互或数据流调整 +- 室内三维导览、Three.js、GLB/GLTF 模型加载、WebGL 性能问题 +- 腾讯地图、室外导览、地图 SDK 或地图标记逻辑调整 +- `static/nav-assets/app_nav_assets_v2_clean_20260609_075339` 资源包相关工作 +- `src/services/navAssets.ts` 导览数据服务相关工作 +- `src/assets/data` 历史 demo 数据清理、隔离或迁移 +- `route_graph`、`nav_data`、POI 坐标、路线规划能力判断 +- H5 适配、移动端遮挡、构建和质量门禁 +- 导览模块专项架构审计或上线风险审查 + +默认只关注 H5 模式。除非任务明确提到“小程序”“mp-weixin”或“小程序构建”，否则不要把小程序兼容作为默认目标。 + +## 如何触发 + +在 Codex 任务中可以显式写明： + +```text +请使用 shenzhen-natural-museum-dev skill，检查导览模块的 Three.js 模型加载问题。 +``` + +也可以在任务描述里包含明确上下文，Codex 应能自动匹配： + +```text +帮我修复室内三维导览切换后顶部菜单被遮挡的问题。 +``` + +```text +请检查腾讯地图和室内 3D 是否有耦合风险。 +``` + +```text +帮我清理导览模块里依赖 src/assets/data 的旧 demo 数据。 +``` + +## Skill 固化的核心规则 + +- 导览业务数据必须优先走 `src/services/navAssets.ts`。 +- 当前干净导览资源包为 `static/nav-assets/app_nav_assets_v2_clean_20260609_075339`。 +- `src/assets/data` 是历史 demo 数据区域，不应再作为当前导览模块的数据源。 +- 在 `route_graph` 和 `nav_data` 未准备并验证前，不应声明“真实馆内导航”或启用真实路线规划。 +- POI 坐标只能作为展示或位置预览候选，不能当作已认证导航锚点。 +- Three.js / GLB 室内三维逻辑应与腾讯地图 / 室外导览逻辑隔离。 +- Three.js/WebGL 当前按 H5 能力处理；不要默认增加小程序 fallback 或 mp-weixin 兼容工作。 +- 移动端顶部菜单、搜索、卡片、按钮和楼层控件不能被 3D canvas 遮挡。 +- 不做无关重构，不直接删除历史数据；先盘点引用、隔离影响，再按确认范围清理。 + +## 推荐任务写法 + +导览功能开发： + +```text +请使用 shenzhen-natural-museum-dev skill，基于当前 clean nav assets 修改导览搜索结果跳转逻辑，不能依赖 src/assets/data 旧数据。 +``` + +三维模型问题： + +```text +请使用 shenzhen-natural-museum-dev skill，排查室内 3D 模型加载失败，并保证 H5 有加载中和失败兜底。 +``` + +腾讯地图问题： + +```text +请使用 shenzhen-natural-museum-dev skill，检查腾讯地图逻辑是否被室内导览改动影响，只读审计并给出证据文件。 +``` + +历史数据清理： + +```text +请使用 shenzhen-natural-museum-dev skill，先只读盘点 src/assets/data 旧 demo 数据在项目中的引用，不要删除文件。 +``` + +架构审计： + +```text +请使用 shenzhen-natural-museum-dev skill，对导览、腾讯地图、Three.js、静态资源和 H5 构建做一次只读架构审计。 +``` + +## 验证要求 + +涉及代码修改时，优先根据风险运行以下检查： + +```powershell +pnpm type-check +pnpm lint +pnpm build:h5 +``` + +注意： + +- `pnpm build:*` 会写入 `dist`，如果任务是只读审计，应先说明风险再执行。 +- `pnpm lint` 即使命令成功，警告也应视为技术债。 +- 导览 UI 改动后，应额外做 H5 冒烟检查：顶部菜单、室内 3D、开始导航/位置预览、搜索结果、路线详情页。 +- 只有用户明确要求小程序/mp-weixin 时，才额外运行 `pnpm build:mp-weixin` 或处理小程序兼容。 + +## 维护方式 + +更新项目架构标准时，优先修改： + +```text +.agents/skills/shenzhen-natural-museum-dev/SKILL.md +``` + +修改后运行 skill 校验： + +```powershell +$env:PYTHONUTF8='1' +python C:\Users\Administrator\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents\skills\shenzhen-natural-museum-dev +``` + +如果展示名称、默认提示词或简短说明需要调整，再同步更新： + +```text +.agents/skills/shenzhen-natural-museum-dev/agents/openai.yaml +``` + +不要在 skill 目录下新增 README、CHANGELOG 或临时说明文件；团队说明文档统一放在 `docs/` 下。 diff --git a/docs/pdca/actions.md b/docs/pdca/actions.md new file mode 100644 index 0000000..9a0ae8d --- /dev/null +++ b/docs/pdca/actions.md @@ -0,0 +1,9 @@ +# PDCA 行动 + +| id | action | owner | due | status | source | +| --- | --- | --- | --- | --- | --- | +| A-001 | 对 guide.whaoyue.com 执行 fresh browser/真实设备室内 3D 冒烟测试 | TBD | 2026-06-11 | todo | C-008 / R-002 | +| A-002 | 将用户流程闭环审计拆成可执行修复任务并排期 | TBD | 2026-06-11 | todo | C-007 / R-001 | +| A-003 | 确认下一轮发布验收标准和负责人 | TBD | 2026-06-11 | todo | M-005 | +| A-004 | 监控模型资源缓存与 404 行为，确认无 ` + + + + + PDCA 项目进度驾驶舱 + + + +
+
+
+

PDCA 项目进度驾驶舱

+

从 docs/pdca 生成的专业项目状态、风险和行动闭环面板

+
+
+
生成日期: 2026-06-10
+
项目: E:\MyWork\深圳国际艺术馆\museum-guide\museum-guide-v4.0\frontend-miniapp
+
Git： master@a90f63c · 变更文件数：22
+
+
+ + + +
+
+ + + +
+
+ + + + + + + 0/9 当前可见 + + + +
+
+ +
+
+
健康状态
+ 红色 +

2 个任务有阻塞/依赖说明（不等同硬阻塞）；2 个高影响风险仍开放；1 个决策待确认

+
+ +
+

任务完成率

+
+
78%
+
+

已完成: 7/9

+

进行中/待复核: 0 · 硬阻塞: 0

+
+
+
+ +
+

任务总览

+
+ +
+ 任务总览 + 9 +
+ + +
+ 已完成（有证据） + 7 +
+ + +
+ 完成但缺证据 + 0 +
+ + +
+ 进行中/待复核 + 0 +
+ + +
+ 硬阻塞 + 0 +
+ + +
+ 阻塞/依赖说明 + 2 +
+ + +
+ 风险 + 4 +
+ + +
+ 检查 + 通过 8 / 未通过 1 +
+ + +
+ 行动 + 5 +
+ + +
+ 里程碑 + 5 +
+ + +
+ 决策待确认 + 1 +
+ +
+
+ +
+

专业状态维度

+
+ +
+ 进度 + 黄色 +

开放工作仍有截止日期待确认

+
+ + +
+ 范围 + 黄色 +

目标或里程碑仍待确认

+
+ + +
+ 风险 + 红色 +

高影响风险仍开放

+
+ + +
+ 证据 + 红色 +

存在未通过的验收检查

+
+ + +
+ 决策 + 黄色 +

需要干系人确认决策

+
+ +
+
+ +
+

核心工作包

+
+ +
+
+ 小程序前端 + 100% +
+
+
+ 已验证完成 6/6 + 阻塞 0 + 关注项 0 + 下一到期 待确认 + 分类：关键词推断 +
+
+ + +
+
+ 项目治理 + 33% +
+
+
+ 已验证完成 1/3 + 阻塞 0 + 关注项 2 + 下一到期 2026-06-11 + 分类：关键词推断 +
+
+ +
+
+ +
+

项目基线

+
+
+
目标
+
待确认
+
+
+
当前里程碑
+
待确认
+
+
+
+ +
+

里程碑

+
+ +
+
2026-06-10
+
+
+ H5 测试服务器可访问 +
+ M-001 + 已完成 + 负责人: Codex + 截止: 2026-06-10 + 证据: https://guide.whaoyue.com/ 已部署；Nginx reload 成功 +
+
+
+ + +
+
2026-06-10
+
+
+ 室内 3D 模型资源请求修复 +
+ M-002 + 已完成 + 负责人: Codex + 截止: 2026-06-10 + 证据: manifest 200 JSON；L1.glb 200 GLB；缺失 GLB 404 +
+
+
+ + +
+
2026-06-10
+
+
+ 部署说明与回滚流程沉淀 +
+ M-003 + 已完成 + 负责人: Codex + 截止: 2026-06-10 + 证据: `docs/H5_DEPLOYMENT_GUIDE.md` +
+
+
+ + +
+
待确认
+
+
+ H5 关键用户流程闭环 +
+ M-004 + 待办 + 负责人: 待确认 + 截止: 待确认 + 证据: `docs/QA/user-flow-closure-audit-2026-06-10.md` +
+
+
+ + +
+
待确认
+
+
+ 发布验收与交付确认 +
+ M-005 + 待办 + 负责人: 待确认 + 截止: 待确认 + +
+
+
+ +
+
+ +
+

任务状态分布

+
+
+ 已完成 7 + 进行中 0 + 待复核 0 + 阻塞 0 + 待办 2 +
+
+ +
+

风险矩阵

+ +
+
+ 影响 ↑ + 概率 → +
+
+
低
中
高
+
高
中
低
+
+
+ + +
+ +
+

PDCA 阶段分布

+
+ +
+ 计划 + 0 + 已完成 0/0 +
+ + +
+ 执行 + 6 + 已完成 5/6 +
+ + +
+ 检查 + 1 + 已完成 0/1 +
+ + +
+ 行动 + 2 + 已完成 2/2 +
+ +
+
+ +
+

质量门禁

+ +
+
+
+ 上线测试准入判定 + No-Go +

基于硬阻塞、失败检查、逾期里程碑、高影响风险、证据缺口和待决策项自动判定。

+
+
+ 判定依据 +
    +
  • 1 个质量门禁未通过
  • 1 个检查待完成
  • 2 个高影响风险仍开放
  • 1 个决策待确认
    • +
+
+
+

最近检查

+ +
+ 通过 + 根目录 TXT 校验文件公网访问 + 2026-06-10 · C-010 +
+ +
+ 通过 + PDCA 报告与面板生成 + 2026-06-10 · C-009 +
+ +
+ 待检查 + in-app browser fresh 3D 复测 + 2026-06-10 · C-008 +
+ +
+ 未通过 + H5 用户流程闭环审计 + 2026-06-10 · C-007 +
+ +
+ 通过 + 缺失模型资源处理 + 2026-06-10 · C-006 +
+ +
+ 通过 + 楼层 GLB 公网响应 + 2026-06-10 · C-005 +
+ +
+ +
+ +
+

阻塞与逾期

+
+

暂无阻塞或逾期任务。

+
+
+ +
+

任务明细与完成判定

+

完成率统计口径：只有 status=done 且 evidence 非空的任务才计入完成率；标记完成但没有证据的任务会被列为证据缺口。

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
任务明细表，可搜索、筛选、排序；完成率只统计已完成且有证据的任务。
T-001配置 H5 模型资源打包执行已完成Codex2026-06-10`package.json` build:h5 调用 `scripts/copy-h5-nav-assets.cjs`；`pnpm build:h5` 通过待确认是
T-002修复 Nginx 模型静态资源规则执行已完成Codex2026-06-10`/dmdata/nginx/conf.d/guide.whaoyue.com.conf` 增加 `/static/nav-assets/`，`docker exec nginx-server nginx -t` 通过待确认是
T-003部署 H5 到 guide.whaoyue.com执行已完成Codex2026-06-10服务器备份 `/dmdata/nginx/html/_backups/guide-before-floor-first-20260610033959.tar.gz`；线上文件数 48待确认是
T-004优化室内 3D 首屏加载策略执行已完成Codex2026-06-10`src/components/navigation/GuideMapShell.vue` 传入 `initial-view="floor"` 和当前楼层 ID待确认是
T-005更新 H5 部署文档行动已完成Codex2026-06-10`docs/H5_DEPLOYMENT_GUIDE.md`；`README.md` 已链接部署文档待确认是
T-006生成并维护 PDCA 项目进度行动已完成Codex2026-06-10`docs/pdca/reports/2026-06-10.md`；`docs/pdca/dashboard.html`；`docs/pdca/dashboard.png`待确认是
T-007浏览器 fresh load 复测室内 3D检查待办待确认2026-06-11待确认当前 in-app browser 调试通道初始化异常，需人工或恢复工具后复测未完成
T-008修复 H5 用户流程闭环 P0/P1 问题执行待办待确认待确认`docs/QA/user-flow-closure-audit-2026-06-10.md`需确认优先级、负责人和截止日期未完成
T-009上传域名根目录校验文件执行已完成Codex2026-06-10`https://guide.whaoyue.com/gpL0svkeao.txt` 返回 `b772216640a14171ba5655085c8523be`待确认是
+
+ +
+ +
+

高影响风险

+
+ +
+ H5 用户流程闭环仍有断点，影响真实到馆任务完成 +
编号: R-001状态: 开放缓解措施: 按 `docs/QA/user-flow-closure-audit-2026-06-10.md` 拆分搜索、详情、路线、设施选择、返回/取消/重试任务负责人: 待确认
+
+ + +
+ 模型静态资源缓存 30 天，错误资源上线后恢复慢 +
编号: R-003状态: 缓解中缓解措施: 模型包路径带版本号；缺失资源返回 404；部署时使用 URL 参数强刷前端包负责人: Codex
+
+ +
+
+ +
+

下一步行动

+
+ +
+ 对 guide.whaoyue.com 执行 fresh browser/真实设备室内 3D 冒烟测试 +
编号: A-001负责人: 待确认截止日期: 2026-06-11来源: C-008 / R-002
+
+ + +
+ 将用户流程闭环审计拆成可执行修复任务并排期 +
编号: A-002负责人: 待确认截止日期: 2026-06-11来源: C-007 / R-001
+
+ + +
+ 确认下一轮发布验收标准和负责人 +
编号: A-003负责人: 待确认截止日期: 2026-06-11来源: M-005
+
+ + +
+ 监控模型资源缓存与 404 行为，确认无 `<!DOCTYPE` JSON 解析报错复发 +
编号: A-004负责人: 待确认截止日期: 2026-06-11来源: R-003
+
+ + +
+ 梳理当前工作区未提交改动，明确本轮交付边界 +
编号: A-005负责人: 待确认截止日期: 2026-06-11来源: R-004
+
+ +
+
+ +
+

决策待确认

+
+ +
+ 是否以用户流程闭环作为下一轮发布准入 +
编号: D-004负责人: 待确认需要日期: 2026-06-11建议: 建议纳入准入
+
+ +
+
+ +
+

缺少证据

+
+

暂无缺少证据的完成/复核状态任务。

+
+
+
+ + +
+ + + + diff --git a/docs/pdca/dashboard.png b/docs/pdca/dashboard.png new file mode 100644 index 0000000..c31bd71 Binary files /dev/null and b/docs/pdca/dashboard.png differ diff --git a/docs/pdca/dashboard.svg b/docs/pdca/dashboard.svg new file mode 100644 index 0000000..b9aca30 --- /dev/null +++ b/docs/pdca/dashboard.svg @@ -0,0 +1,56 @@ + + 深圳自然馆小程序 PDCA 可视化面板 + PDCA 可视化面板，包含健康状态、完成率、状态条、阶段分布、风险矩阵和下一步行动。 + + 深圳自然馆小程序 PDCA 可视化面板 + 生成: 2026-06-10 · 里程碑: TBD + + + 健康状态 + 红色 + 2 个任务有阻塞/依赖说明（不等同硬阻塞）；2 个高影响风险仍开放；1... + + + 完成率 + + + 78% + + + 关键指标 + 9 + 任务 + 4 + 风险 + 10 + 检查 + 5 + 行动 + 进度 黄范围 黄风险 红证据 红决策 黄 + + + 任务状态分布 + + + 已完成 7进行中 0待复核 0阻塞 0待办 2未知 0 + + + PDCA 四象限 + 计划0执行6检查1行动2 + + + 风险矩阵 + 影响 ↑概率 →R001R002R003R004 + 高影响风险: R-001 / R-003 + + + 下一步行动 + 1对 guide.whaoyue.com 执行 fresh brows...负责人: 待确认 · 截止日期: 2026-06-112将用户流程闭环审计拆成可执行修复任务并排期负责人: 待确认 · 截止日期: 2026-06-113确认下一轮发布验收标准和负责人负责人: 待确认 · 截止日期: 2026-06-114监控模型资源缓存与 404 行为，确认无 `<!DOCTYPE` J...负责人: 待确认 · 截止日期: 2026-06-115梳理当前工作区未提交改动，明确本轮交付边界负责人: 待确认 · 截止日期: 2026-06-11 + + + 任务明细与完成判定 + 计入完成率：状态为已完成且证据非空 + ID任务阶段状态负责人截止证据判定T-001配置 H5 模型资源打包执行已完成Codex2026-06-10`package.json`...计入T-002修复 Nginx 模型静态资源规则执行已完成Codex2026-06-10`/dmdata/nginx...计入T-003部署 H5 到 guide.whaoyue.com执行已完成Codex2026-06-10服务器备份 `/dmdata...计入T-004优化室内 3D 首屏加载策略执行已完成Codex2026-06-10`src/component...计入T-005更新 H5 部署文档行动已完成Codex2026-06-10`docs/H5_DEPLO...计入T-006生成并维护 PDCA 项目进度行动已完成Codex2026-06-10`docs/pdca/rep...计入T-009上传域名根目录校验文件执行已完成Codex2026-06-10`https://guide...计入T-007浏览器 fresh load 复测室内 3D检查待办待确认2026-06-11-未计入完整任务表见 dashboard.html · 9 total + + 由项目内 PDCA 进度工具生成 · 来源：项目管理目录 + diff --git a/docs/pdca/decisions.md b/docs/pdca/decisions.md new file mode 100644 index 0000000..fb6f4e7 --- /dev/null +++ b/docs/pdca/decisions.md @@ -0,0 +1,8 @@ +# PDCA 决策 + +| id | date | decision | status | owner | needed_by | recommendation | rationale | +| --- | --- | --- | --- | --- | --- | --- | --- | +| D-001 | 2026-06-10 | 当前线上部署目标使用 H5 模式 | accepted | Codex | | 使用 `pnpm build:h5` | 用户明确要求 H5 模式打包部署 | +| D-002 | 2026-06-10 | 导览模型资源通过 `/static/nav-assets/` 提供，并由 Nginx 对缺失资源返回 404 | accepted | Codex | | 保持专用 location | 避免资源缺失时返回 `index.html` 导致 JSON/GLB 解析错误 | +| D-003 | 2026-06-10 | 室内 3D 首屏默认加载当前楼层模型 | accepted | Codex | | 保持 `initial-view="floor"` | 降低首屏模型解析压力，导览页已有楼层切换上下文 | +| D-004 | 2026-06-10 | 是否以用户流程闭环作为下一轮发布准入 | needed | TBD | 2026-06-11 | 建议纳入准入 | 当前 QA 审计显示关键任务闭环仍未完成 | diff --git a/docs/pdca/milestones.md b/docs/pdca/milestones.md new file mode 100644 index 0000000..a451d95 --- /dev/null +++ b/docs/pdca/milestones.md @@ -0,0 +1,9 @@ +# PDCA 里程碑 + +| id | milestone | status | owner | due | evidence | notes | +| --- | --- | --- | --- | --- | --- | --- | +| M-001 | H5 测试服务器可访问 | done | Codex | 2026-06-10 | https://guide.whaoyue.com/ 已部署；Nginx reload 成功 | Now | +| M-002 | 室内 3D 模型资源请求修复 | done | Codex | 2026-06-10 | manifest 200 JSON；L1.glb 200 GLB；缺失 GLB 404 | Now | +| M-003 | 部署说明与回滚流程沉淀 | done | Codex | 2026-06-10 | `docs/H5_DEPLOYMENT_GUIDE.md` | Now | +| M-004 | H5 关键用户流程闭环 | todo | TBD | TBD | `docs/QA/user-flow-closure-audit-2026-06-10.md` | Next | +| M-005 | 发布验收与交付确认 | todo | TBD | TBD | | Later | diff --git a/docs/pdca/plan.md b/docs/pdca/plan.md new file mode 100644 index 0000000..2139ee5 --- /dev/null +++ b/docs/pdca/plan.md @@ -0,0 +1,34 @@ +# PDCA 计划 + +项目：深圳自然博物馆 H5 智能导览前端 + +当前目标：完成 `guide.whaoyue.com` H5 部署闭环，确保室内 3D 模型资源可稳定加载，并把上线验证、风险、后续用户流程闭环工作纳入可追踪进度。 + +## 范围 + +- H5 模式构建与部署。 +- Nginx、SSL、静态资源和模型资源服务配置。 +- 室内 3D 模型加载链路，包括 manifest、楼层 GLB、POI 数据和缺失资源处理。 +- 部署说明、验证记录、风险和后续行动管理。 + +## 暂不覆盖 + +- 微信小程序 `mp-weixin` 发布。 +- 真实内容数据最终验收。 +- 全量用户流程闭环修复，这部分当前作为后续行动和风险跟踪。 + +## 成功指标 + +- `pnpm build:h5` 成功，且 H5 产物包含 `static/nav-assets`。 +- `pnpm type-check` 成功。 +- Nginx 配置测试成功并 reload。 +- 线上 manifest 返回 `application/json`。 +- 线上 GLB 返回 `model/gltf-binary`。 +- 缺失模型资源返回 404，不返回 `index.html`。 +- 室内 3D 默认加载当前楼层模型，降低首屏解析压力。 +- 部署文档和 PDCA 进度可审计。 + +## 当前判断 + +- 部署与模型请求修复已完成。 +- 项目整体仍有用户流程闭环风险，需在下一轮集中处理搜索、详情、路线、设施选择、返回/取消/重试等关键链路。 diff --git a/docs/pdca/reports/2026-06-10.md b/docs/pdca/reports/2026-06-10.md new file mode 100644 index 0000000..def3825 --- /dev/null +++ b/docs/pdca/reports/2026-06-10.md @@ -0,0 +1,83 @@ +# PDCA 项目进度报告 - 2026-06-10 + +## 健康状态 + +- 状态：红色 +- 原因：2 个高影响风险仍开放；1 个决策待确认 +- 项目：`E:\MyWork\深圳国际艺术馆\museum-guide\museum-guide-v4.0\frontend-miniapp` +- Git：master@a90f63c，变更文件数：22 + +## 专业状态维度 + +| 维度 | 状态 | 原因 | +| --- | --- | --- | +| 进度 | 黄色 | 开放工作仍有截止日期待确认 | +| 范围 | 黄色 | 目标或里程碑仍待确认 | +| 风险 | 红色 | 高影响风险仍开放 | +| 证据 | 红色 | 存在未通过的验收检查 | +| 决策 | 黄色 | 需要干系人确认决策 | + +## 计划 + +- 查看 `docs/pdca/plan.md` 获取目标、里程碑、范围与成功指标。 +- 如果目标、里程碑、负责人或截止日期仍待确认，项目基线尚未完整。 + +### 里程碑 + +- M-001 | H5 测试服务器可访问 | 已完成 | Codex | 2026-06-10 +- M-002 | 室内 3D 模型资源请求修复 | 已完成 | Codex | 2026-06-10 +- M-003 | 部署说明与回滚流程沉淀 | 已完成 | Codex | 2026-06-10 +- M-004 | H5 关键用户流程闭环 | 待办 | 待确认 | 待确认 +- M-005 | 发布验收与交付确认 | 待办 | 待确认 | 待确认 + +## 执行 + +- 任务统计：已完成: 7, 待办: 2 +- 完成率口径：仅统计 `status=done` 且 `evidence` 非空的任务。 +- 已完成并有证据：7/9 +- 标记完成但缺少证据：0 +- T-001 | 配置 H5 模型资源打包 | 已完成 | Codex | 2026-06-10 +- T-002 | 修复 Nginx 模型静态资源规则 | 已完成 | Codex | 2026-06-10 +- T-003 | 部署 H5 到 guide.whaoyue.com | 已完成 | Codex | 2026-06-10 +- T-004 | 优化室内 3D 首屏加载策略 | 已完成 | Codex | 2026-06-10 +- T-005 | 更新 H5 部署文档 | 已完成 | Codex | 2026-06-10 +- T-006 | 生成并维护 PDCA 项目进度 | 已完成 | Codex | 2026-06-10 +- T-007 | 浏览器 fresh load 复测室内 3D | 待办 | 待确认 | 2026-06-11 +- T-008 | 修复 H5 用户流程闭环 P0/P1 问题 | 待办 | 待确认 | 待确认 +- T-009 | 上传域名根目录校验文件 | 已完成 | Codex | 2026-06-10 + +## 检查 + +### 阻塞 + +- 暂无阻塞记录。 + +### 逾期任务 + +- 未发现逾期任务。 + +### 逾期里程碑 + +- 未发现逾期里程碑。 + +### 缺少证据 + +- 完成/复核状态任务均有证据或暂无此类任务。 + +### 高影响开放风险 + +- R-001 | H5 用户流程闭环仍有断点，影响真实到馆任务完成 | 开放 | 按 `docs/QA/user-flow-closure-audit-2026-06-10.md` 拆分搜索、详情、路线、设施选择、返回/取消/重试任务 | 待确认 +- R-003 | 模型静态资源缓存 30 天，错误资源上线后恢复慢 | 缓解中 | 模型包路径带版本号；缺失资源返回 404；部署时使用 URL 参数强刷前端包 | Codex + +## 行动 + +- A-001 | 对 guide.whaoyue.com 执行 fresh browser/真实设备室内 3D 冒烟测试 | 待确认 | 2026-06-11 | C-008 / R-002 +- A-002 | 将用户流程闭环审计拆成可执行修复任务并排期 | 待确认 | 2026-06-11 | C-007 / R-001 +- A-003 | 确认下一轮发布验收标准和负责人 | 待确认 | 2026-06-11 | M-005 +- A-004 | 监控模型资源缓存与 404 行为，确认无 ` { + fs.mkdirSync(target, { recursive: true }) + + for (const entry of fs.readdirSync(source, { withFileTypes: true })) { + const sourcePath = path.join(source, entry.name) + const targetPath = path.join(target, entry.name) + + if (entry.isDirectory()) { + copyDirectory(sourcePath, targetPath) + continue + } + + if (entry.isFile()) { + fs.copyFileSync(sourcePath, targetPath) + } + } +} + +fs.rmSync(targetDir, { recursive: true, force: true }) +copyDirectory(sourceDir, targetDir) + +if (fs.existsSync(faviconSource)) { + fs.copyFileSync(faviconSource, faviconTarget) +} + +console.log(`Copied navigation assets to ${path.relative(projectRoot, targetDir)}`) diff --git a/src/components/map/ThreeMap.vue b/src/components/map/ThreeMap.vue index 3dd29b8..ad6df7d 100644 --- a/src/components/map/ThreeMap.vue +++ b/src/components/map/ThreeMap.vue @@ -101,6 +101,24 @@ interface CleanPoi { positionGltf?: [number, number, number] } +interface TargetPoiFocusRequest { + requestId: number | string + poiId: string + name?: string + floorId: string + floorLabel?: string + primaryCategoryZh?: string + positionGltf?: [number, number, number] +} + +interface TargetPoiFocusResult { + requestId: number | string + poiId: string + floorId: string + status: 'focused' | 'missing' | 'error' + message?: string +} + interface FloorPoiData { status: string floorId: string @@ -115,17 +133,20 @@ const props = withDefaults(defineProps<{ initialView?: ViewMode showControls?: boolean showPoi?: boolean + targetFocus?: TargetPoiFocusRequest | null }>(), { assetBaseUrl: NAV_ASSET_BASE_URL, initialFloorId: 'L1', initialView: 'overview', showControls: true, - showPoi: false + showPoi: false, + targetFocus: null }) const emit = defineEmits<{ floorChange: [floorId: string] poiClick: [poi: CleanPoi] + targetFocus: [result: TargetPoiFocusResult] }>() const containerRef = ref(null) @@ -136,6 +157,7 @@ const loadingMessage = ref('正在读取室内导览资源...') const activeView = ref(props.initialView) const currentFloor = ref(props.initialFloorId) const selectedPOI = ref(null) +const activeFocusPoiId = ref('') const floorIndex = ref([]) const floors = computed(() => ( @@ -146,6 +168,7 @@ const floors = computed(() => ( label: formatFloorLabel(floor.floorId) })) )) +const shouldRenderPoiMarkers = computed(() => props.showPoi || props.showControls || Boolean(props.targetFocus)) let manifest: CleanNavManifest | null = null let scene: THREE.Scene | null = null @@ -158,6 +181,8 @@ let poiGroup: THREE.Group | null = null let animationId = 0 let resizeObserver: ResizeObserver | null = null let isDisposed = false +let pendingTargetFocus: TargetPoiFocusRequest | null = null +let targetFocusQueue: Promise = Promise.resolve() const normalizeBaseUrl = (baseUrl: string) => baseUrl.replace(/\/+$/, '') @@ -410,7 +435,7 @@ const loadFloor = async (floorId: string) => { scene.add(activeModel) fitCameraToObject(activeModel) - if (props.showPoi || props.showControls) { + if (shouldRenderPoiMarkers.value) { await loadFloorPOIs(floor) } } @@ -463,20 +488,90 @@ const getPoiColor = (category: string) => { return colorMap[category] || '#1f2329' } +const getPoiMarkerSize = () => ( + activeModel + ? Math.max(new THREE.Box3().setFromObject(activeModel).getSize(new THREE.Vector3()).length() * 0.012, 2.4) + : 3 +) + +const setPoiSpriteFocusStyle = (sprite: THREE.Sprite, focused: boolean) => { + const baseScale = typeof sprite.userData.baseScale === 'number' + ? sprite.userData.baseScale + : sprite.scale.x + const scale = focused ? baseScale * 1.55 : baseScale + + sprite.scale.set(scale, scale, scale) + sprite.renderOrder = focused ? 20 : 10 + sprite.material.opacity = focused ? 1 : 0.78 +} + +const updatePoiMarkerFocus = () => { + if (!poiGroup) return + + poiGroup.children.forEach((child) => { + if (child instanceof THREE.Sprite) { + const poi = child.userData.poi as CleanPoi | undefined + setPoiSpriteFocusStyle(child, Boolean(poi && poi.id === activeFocusPoiId.value)) + } + }) +} + +const findPoiSprite = (poiId: string) => ( + poiGroup?.children.find((child): child is THREE.Sprite => ( + child instanceof THREE.Sprite && (child.userData.poi as CleanPoi | undefined)?.id === poiId + )) +) + +const findLoadedPoi = (poiId: string) => ( + findPoiSprite(poiId)?.userData.poi as CleanPoi | undefined +) + +const createPoiFromFocusRequest = (request: TargetPoiFocusRequest): CleanPoi | null => { + if (!request.positionGltf) return null + + return { + id: request.poiId, + name: request.name || '目标位置', + floorId: request.floorId, + primaryCategory: 'target_preview', + primaryCategoryZh: request.primaryCategoryZh || '位置预览', + iconType: 'target_preview', + positionGltf: request.positionGltf + } +} + +const addFocusMarkerFromRequest = (request: TargetPoiFocusRequest) => { + if (!poiGroup || findPoiSprite(request.poiId)) return findLoadedPoi(request.poiId) || null + + const poi = createPoiFromFocusRequest(request) + if (!poi?.positionGltf) return null + + const [x, y, z] = poi.positionGltf + const markerSize = getPoiMarkerSize() + const sprite = new THREE.Sprite(createPoiMaterial(poi)) + sprite.position.set(x, y + markerSize * 0.5, z) + sprite.userData.baseScale = markerSize + sprite.userData.poi = poi + setPoiSpriteFocusStyle(sprite, poi.id === activeFocusPoiId.value) + poiGroup.add(sprite) + + return poi +} + const loadFloorPOIs = async (floor: FloorIndexItem) => { if (!poiGroup) return const data = await fetchJson(assetUrl(floor.poiDataAsset)) const validPois = data.pois.filter((poi) => Array.isArray(poi.positionGltf) && poi.positionGltf.length === 3) - const markerSize = activeModel ? Math.max(new THREE.Box3().setFromObject(activeModel).getSize(new THREE.Vector3()).length() * 0.012, 2.4) : 3 + const markerSize = getPoiMarkerSize() validPois.forEach((poi) => { const [x, y, z] = poi.positionGltf! const sprite = new THREE.Sprite(createPoiMaterial(poi)) sprite.position.set(x, y + markerSize * 0.5, z) - sprite.scale.set(markerSize, markerSize, markerSize) - sprite.renderOrder = 10 + sprite.userData.baseScale = markerSize sprite.userData.poi = poi + setPoiSpriteFocusStyle(sprite, poi.id === activeFocusPoiId.value) poiGroup!.add(sprite) }) } @@ -495,10 +590,134 @@ const handlePointerDown = (event: PointerEvent) => { if (hits[0]?.object.userData.poi) { selectedPOI.value = hits[0].object.userData.poi as CleanPoi + activeFocusPoiId.value = selectedPOI.value.id + updatePoiMarkerFocus() emit('poiClick', selectedPOI.value) } } +const emitTargetFocus = ( + request: TargetPoiFocusRequest, + status: TargetPoiFocusResult['status'], + message?: string +) => { + emit('targetFocus', { + requestId: request.requestId, + poiId: request.poiId, + floorId: request.floorId, + status, + message + }) +} + +const clearTargetFocus = () => { + pendingTargetFocus = null + activeFocusPoiId.value = '' + selectedPOI.value = null + updatePoiMarkerFocus() +} + +const isSceneReadyForTargetFocus = () => ( + Boolean(scene && camera && controls && loader && floorIndex.value.length) + && !isLoading.value + && !loadError.value +) + +const focusCameraOnPoi = (poi: CleanPoi) => { + if (!camera || !controls || !poi.positionGltf) return + + const [x, y, z] = poi.positionGltf + const target = new THREE.Vector3(x, y, z) + const modelSize = activeModel + ? new THREE.Box3().setFromObject(activeModel).getSize(new THREE.Vector3()) + : new THREE.Vector3(80, 80, 80) + const maxDim = Math.max(modelSize.x, modelSize.y, modelSize.z, 1) + const distance = Math.min(Math.max(maxDim * 0.22, 28), Math.max(maxDim * 0.55, 80)) + const direction = new THREE.Vector3(0.72, 0.58, 1).normalize() + + camera.position.copy(target).add(direction.multiplyScalar(distance)) + camera.near = Math.max(0.1, maxDim / 1200) + camera.far = Math.max(10000, maxDim * 20) + camera.updateProjectionMatrix() + + controls.target.copy(target) + controls.minDistance = Math.max(2, maxDim * 0.025) + controls.maxDistance = Math.max(20, maxDim * 6) + controls.update() +} + +const focusTargetPoi = async (request: TargetPoiFocusRequest) => { + if (!request.poiId || !request.floorId) { + emitTargetFocus(request, 'missing', '目标位置数据不完整') + return false + } + + const floor = floorIndex.value.find((item) => item.floorId === request.floorId) + if (!floor) { + emitTargetFocus(request, 'missing', '目标楼层不在当前三维资源中') + return false + } + + activeFocusPoiId.value = request.poiId + + try { + if (activeView.value !== 'floor' || currentFloor.value !== request.floorId) { + isLoading.value = true + loadError.value = false + await loadFloor(request.floorId) + isLoading.value = false + emit('floorChange', request.floorId) + } else if (shouldRenderPoiMarkers.value && poiGroup && poiGroup.children.length === 0) { + await loadFloorPOIs(floor) + } + + const poi = findLoadedPoi(request.poiId) || addFocusMarkerFromRequest(request) || createPoiFromFocusRequest(request) + + if (!poi?.positionGltf) { + selectedPOI.value = null + updatePoiMarkerFocus() + emitTargetFocus(request, 'missing', '目标暂无三维坐标') + return false + } + + selectedPOI.value = poi + updatePoiMarkerFocus() + focusCameraOnPoi(poi) + emitTargetFocus(request, 'focused') + return true + } catch (error) { + console.error('目标 POI 聚焦失败:', error) + loadError.value = true + isLoading.value = false + setProgress(0, error instanceof Error ? error.message : '目标位置聚焦失败') + emitTargetFocus(request, 'error', error instanceof Error ? error.message : '目标位置聚焦失败') + return false + } +} + +const queueTargetFocus = (request: TargetPoiFocusRequest | null) => { + if (!request) { + clearTargetFocus() + return + } + + pendingTargetFocus = request + + if (!isSceneReadyForTargetFocus()) return + + const nextRequest = pendingTargetFocus + if (!nextRequest) return + + pendingTargetFocus = null + targetFocusQueue = targetFocusQueue + .then(() => focusTargetPoi(nextRequest)) + .finally(() => { + if (pendingTargetFocus) { + queueTargetFocus(pendingTargetFocus) + } + }) +} + const loadCleanPackage = async () => { setProgress(8, '正在读取室内导览资源...') manifest = await fetchJson(assetUrl('app_nav_manifest.json')) @@ -537,6 +756,7 @@ const init3DScene = async () => { setProgress(100, '室内三维模型加载完成') isLoading.value = false + queueTargetFocus(pendingTargetFocus || props.targetFocus || null) } catch (error) { console.error('室内 3D clean package 加载失败:', error) loadError.value = true @@ -564,6 +784,7 @@ const showOverview = async () => { try { isLoading.value = true loadError.value = false + activeFocusPoiId.value = '' await loadOverview() isLoading.value = false } catch (error) { @@ -613,8 +834,13 @@ const disposeScene = () => { defineExpose({ switchFloor: handleFloorChange, showOverview, + focusTargetPoi: (request: TargetPoiFocusRequest) => { + queueTargetFocus(request) + }, clearNavigation: () => { + activeFocusPoiId.value = '' selectedPOI.value = null + updatePoiMarkerFocus() } }) @@ -622,6 +848,13 @@ watch(() => props.assetBaseUrl, () => { init3DScene() }) +watch(() => props.targetFocus, (request) => { + queueTargetFocus(request || null) +}, { + deep: true, + immediate: true +}) + onMounted(() => { init3DScene() }) diff --git a/src/components/navigation/GuideMapShell.vue b/src/components/navigation/GuideMapShell.vue index e5c2b44..bf2ed91 100644 --- a/src/components/navigation/GuideMapShell.vue +++ b/src/components/navigation/GuideMapShell.vue @@ -7,7 +7,12 @@ ref="threeMapRef" class="indoor-three-map" :asset-base-url="indoorAssetBaseUrl" + :initial-floor-id="activeFloorId" + :initial-view="indoorInitialView" :show-controls="false" + :show-poi="shouldShowIndoorPois" + :target-focus="targetFocusRequest" + @target-focus="handleTargetFocus" /> @@ -77,6 +82,27 @@ + + + 全馆 + + + 楼层 + + + (), { searchText: '搜索设施、展厅、入口', activeMode: '3d', activeFloor: '1F', + indoorView: 'floor', + indoorInitialView: 'floor', searchTop: '16px', floorTop: '164px', + indoorViewToggleTop: '154px', toolsTop: '406px', tools: () => [] as string[], showSearch: true, showFloor: true, + showIndoorViewToggle: false, modeTop: '60px', modeLayout: 'full', modeStatus: '', @@ -151,7 +206,8 @@ const props = withDefaults(defineProps<{ mapType: 'indoor', outdoorVariant: 'home', indoorAssetBaseUrl: NAV_ASSET_BASE_URL, - dimmed: false + dimmed: false, + targetFocusRequest: null }) const emit = defineEmits<{ @@ -159,11 +215,18 @@ const emit = defineEmits<{ modeChange: [mode: '2d' | '3d'] floorChange: [floor: string] toolClick: [tool: string] + indoorViewChange: [view: IndoorViewMode] + targetFocus: [result: TargetPoiFocusResult] }>() -const threeMapRef = ref<{ switchFloor?: (floorId: string) => Promise | void } | null>(null) +const threeMapRef = ref<{ + switchFloor?: (floorId: string) => Promise | void + showOverview?: () => Promise | void +} | null>(null) const floors = NAV_FLOOR_OPTIONS.map((floor) => floor.label) +const activeFloorId = computed(() => navFloorIdFromLabel(props.activeFloor)) + const searchFieldStyle = computed(() => ({ top: props.searchTop })) @@ -172,6 +235,10 @@ const floorSwitcherStyle = computed(() => ({ top: props.floorTop })) +const indoorViewToggleStyle = computed(() => ({ + top: props.indoorViewToggleTop +})) + const modeRowStyle = computed(() => ({ top: props.modeTop })) @@ -180,6 +247,8 @@ const toolStackStyle = computed(() => ({ top: props.toolsTop })) +const shouldShowIndoorPois = computed(() => Boolean(props.targetFocusRequest)) + const handleSearchTap = () => { emit('searchTap') } @@ -191,12 +260,27 @@ const handleModeChange = (mode: '2d' | '3d') => { const handleFloorChange = (floor: string) => { const floorId = navFloorIdFromLabel(floor) void threeMapRef.value?.switchFloor?.(floorId) + emit('indoorViewChange', 'floor') emit('floorChange', floor) } +const handleIndoorViewChange = (view: IndoorViewMode) => { + if (view === 'overview') { + void threeMapRef.value?.showOverview?.() + } else { + void threeMapRef.value?.switchFloor?.(activeFloorId.value) + } + + emit('indoorViewChange', view) +} + const handleToolClick = (tool: string) => { emit('toolClick', tool) } + +const handleTargetFocus = (result: TargetPoiFocusResult) => { + emit('targetFocus', result) +} diff --git a/src/components/navigation/GuideTopTabs.vue b/src/components/navigation/GuideTopTabs.vue new file mode 100644 index 0000000..ee809dd --- /dev/null +++ b/src/components/navigation/GuideTopTabs.vue @@ -0,0 +1,90 @@ + + + + + diff --git a/src/components/navigation/LocationPreview.vue b/src/components/navigation/LocationPreview.vue new file mode 100644 index 0000000..3f295c8 --- /dev/null +++ b/src/components/navigation/LocationPreview.vue @@ -0,0 +1,212 @@ + + + + + diff --git a/src/pages/exhibit/detail.vue b/src/pages/exhibit/detail.vue index af4c460..3f03262 100644 --- a/src/pages/exhibit/detail.vue +++ b/src/pages/exhibit/detail.vue @@ -1,68 +1,80 @@ diff --git a/src/pages/hall/detail.vue b/src/pages/hall/detail.vue index 4f8e96e..6135e17 100644 --- a/src/pages/hall/detail.vue +++ b/src/pages/hall/detail.vue @@ -1,58 +1,72 @@ diff --git a/src/pages/route/detail.vue b/src/pages/route/detail.vue index cf0e519..6a1574d 100644 --- a/src/pages/route/detail.vue +++ b/src/pages/route/detail.vue @@ -1,191 +1,226 @@