chore: solidify guide P1 snapshot

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 '<', "<!DOCTYPE "... is not valid JSON`
+
+## 常见问题
+
+### 模型请求返回 HTML
+
+现象：
+
+```text
+SyntaxError: Unexpected token '<', "<!DOCTYPE "... is not valid JSON
+```
+
+原因通常是 H5 产物缺少 `static/nav-assets`，或 Nginx 未对 `/static/nav-assets/` 使用 `try_files $uri =404`。
+
+处理：
+
+1. 确认 `pnpm build:h5` 已执行资源复制脚本。
+2. 确认服务器存在 `/dmdata/nginx/html/guide/static/nav-assets/app_nav_assets_v2_clean_20260609_075339`。
+3. 确认 Nginx `/static/nav-assets/` 配置生效。
+4. 强刷浏览器，避免继续使用旧 JS。
+
+### 室内 3D 首屏加载过慢
+
+导览页已配置为 `initial-view="floor"`，进入室内 3D 时优先加载当前楼层模型。不要在导览壳层中默认加载全馆 overview 模型，否则低性能设备可能长时间停留在 100% 或页面无响应。
+
+### 浏览器缓存旧包
+
+如果线上已经替换但页面仍异常，使用带参数的地址强制刷新：
+
+```text
+https://guide.whaoyue.com/?v=YYYYMMDDHHmm#/
+```
+
+## 回滚
+
+部署脚本会在 `/dmdata/nginx/html/_backups` 下生成备份包。回滚示例：
+
+```powershell
+ssh -o BatchMode=yes '自然博物馆-测试服务器' 'set -e
+SITE=/dmdata/nginx/html/guide
+BACKUP=/dmdata/nginx/html/_backups/guide-before-deploy-YYYYMMDDHHmmss.tar.gz
+[ "$SITE" = "/dmdata/nginx/html/guide" ]
+test -f "$BACKUP"
+find "$SITE" -mindepth 1 -maxdepth 1 ! -name ".well-known" -exec rm -rf -- {} +
+tar -C "$SITE" -xzf "$BACKUP"
+docker exec nginx-server nginx -t
+docker exec nginx-server nginx -s reload
+'
+```
+
+## 最近部署记录
+
+- 2026-06-10：补齐 H5 模型资源打包，新增 `/static/nav-assets/` Nginx 规则，修复模型资源请求返回 HTML 的问题。
+- 2026-06-10：室内 3D 默认加载当前楼层模型，减少首屏模型解析压力。线上备份：`/dmdata/nginx/html/_backups/guide-before-floor-first-20260610033959.tar.gz`。
+- 2026-06-10：上传域名根目录校验文件 `gpL0svkeao.txt`，公网验证地址为 `https://guide.whaoyue.com/gpL0svkeao.txt`。

docs/QA/user-flow-closure-audit-2026-06-10.md

@@ -0,0 +1,153 @@
+# 用户逻辑闭环浏览器测试报告
+
+日期：2026-06-10  
+项目：深圳自然博物馆智能导览应用 - frontend-miniapp  
+接续会话：`019eab78-f40b-72b1-9751-f8d4c4ff8fba`  
+测试地址：`http://192.168.0.112:5180/#/`  
+运行目标：H5  
+测试方式：浏览器自动化点击、DOM 状态观察、当前源码佐证  
+测试范围：导览首页、全局顶部菜单、搜索页、设施详情页、路线详情页、返回/取消/重置/状态保留
+
+## 结论
+
+本次测试确认：导览首页到搜索、搜索结果到设施详情/路线预览、路线页室外预览返回室内预览等主路径已经可以渲染，浏览器或系统返回也能在若干场景中恢复上一页；搜索筛选状态从设施详情返回后仍能保留，是一个正向结果。
+
+但用户逻辑闭环仍未完成。当前问题不是页面打不开，而是用户在进入二级页面后缺少稳定的页面级返回、取消、重置和继续路径；部分关键按钮只 `toast` 或 `console.log`，导致任务停在中间态。尤其是搜索页不能重新输入关键词、设施页不能真正选择起点、路线页不能继续到“目标位置确认/导航完成”，这些都属于闭环断点。
+
+需要特别说明：当前产品能力仍应表述为“室内 3D 展示 + POI/位置预览”。源码中的提示也明确指出正式路线数据尚未接入，不能把现有路径宣传为真实室内路线规划或实时导航。
+
+## 当前已验证正向路径
+
+| 路径 | 浏览器验证结果 | 备注 |
+| --- | --- | --- |
+| 首页导览 -> 点击搜索框 -> 搜索页 | 成功进入 `/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` 接入并完成独立验证。
+- 当前文档只新增测试报告，不修改业务实现。

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/` 下。

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 行为，确认无 `<!DOCTYPE` JSON 解析报错复发 | TBD | 2026-06-11 | todo | R-003 |
+| A-005 | 梳理当前工作区未提交改动，明确本轮交付边界 | TBD | 2026-06-11 | todo | R-004 |

docs/pdca/checks.md

@@ -0,0 +1,14 @@
+# PDCA 检查
+
+| id | check | result | date | evidence | notes |
+| --- | --- | --- | --- | --- | --- |
+| C-001 | H5 构建 | pass | 2026-06-10 | `pnpm build:h5` 通过，复制 `static/nav-assets` | Sass legacy API warning 不阻塞 |
+| C-002 | 类型检查 | pass | 2026-06-10 | `pnpm type-check` 通过 |  |
+| C-003 | Nginx 配置检查 | pass | 2026-06-10 | `docker exec nginx-server nginx -t` 通过 | 存在 http2 deprecated warning，不影响加载 |
+| C-004 | manifest 公网响应 | pass | 2026-06-10 | `curl -I https://guide.whaoyue.com/static/nav-assets/app_nav_assets_v2_clean_20260609_075339/app_nav_manifest.json` 返回 200 JSON |  |
+| C-005 | 楼层 GLB 公网响应 | pass | 2026-06-10 | `curl -I .../models_by_floor/L1.glb` 返回 200 `model/gltf-binary` |  |
+| C-006 | 缺失模型资源处理 | pass | 2026-06-10 | `curl -I .../models_by_floor/MISSING.glb` 返回 404 | 已避免 SPA fallback 返回 `index.html` |
+| C-007 | H5 用户流程闭环审计 | fail | 2026-06-10 | `docs/QA/user-flow-closure-audit-2026-06-10.md` | 搜索、路线、设施和详情页仍需闭环修复 |
+| C-008 | in-app browser fresh 3D 复测 | pending | 2026-06-10 |  | 浏览器插件初始化异常，需后续复测 |
+| C-009 | PDCA 报告与面板生成 | pass | 2026-06-10 | `docs/pdca/reports/2026-06-10.md`；`docs/pdca/dashboard.html`；`docs/pdca/dashboard.png` |  |
+| C-010 | 根目录 TXT 校验文件公网访问 | pass | 2026-06-10 | `curl -L https://guide.whaoyue.com/gpL0svkeao.txt` 返回 `b772216640a14171ba5655085c8523be` | 文件位于 `/dmdata/nginx/html/guide/gpL0svkeao.txt` |

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 审计显示关键任务闭环仍未完成 |

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 |

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 进度可审计。
+
+## 当前判断
+
+- 部署与模型请求修复已完成。
+- 项目整体仍有用户流程闭环风险，需在下一轮集中处理搜索、详情、路线、设施选择、返回/取消/重试等关键链路。

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 行为，确认无 `<!DOCTYPE` JSON 解析报错复发 | 待确认 | 2026-06-11 | R-003
+- A-005 | 梳理当前工作区未提交改动，明确本轮交付边界 | 待确认 | 2026-06-11 | R-004
+
+### 决策待确认
+
+- D-004 | 是否以用户流程闭环作为下一轮发布准入 | 待确认 | 2026-06-11 | 建议纳入准入
+

docs/pdca/risks.md

@@ -0,0 +1,8 @@
+# PDCA 风险
+
+| id | risk | probability | impact | status | mitigation | owner |
+| --- | --- | --- | --- | --- | --- | --- |
+| R-001 | H5 用户流程闭环仍有断点，影响真实到馆任务完成 | high | high | open | 按 `docs/QA/user-flow-closure-audit-2026-06-10.md` 拆分搜索、详情、路线、设施选择、返回/取消/重试任务 | TBD |
+| R-002 | fresh browser 复测未完成，可能漏掉真实设备上的 3D 渲染问题 | medium | medium | watch | 使用浏览器强刷、移动端视口和真实设备补测室内 3D；保留 HTTP 资源验证作为最低证据 | TBD |
+| R-003 | 模型静态资源缓存 30 天，错误资源上线后恢复慢 | medium | high | mitigating | 模型包路径带版本号；缺失资源返回 404；部署时使用 URL 参数强刷前端包 | Codex |
+| R-004 | 项目仍有多处未提交/未归属改动，发布边界可能不清 | medium | medium | watch | 发布前整理变更清单，确认哪些进入本轮交付，哪些留作后续 | TBD |

docs/pdca/tasks.md

@@ -0,0 +1,13 @@
+# PDCA 任务
+
+| id | title | phase | status | owner | due | evidence | blockers |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| T-001 | 配置 H5 模型资源打包 | do | done | Codex | 2026-06-10 | `package.json` build:h5 调用 `scripts/copy-h5-nav-assets.cjs`；`pnpm build:h5` 通过 |  |
+| T-002 | 修复 Nginx 模型静态资源规则 | do | done | Codex | 2026-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 | do | done | Codex | 2026-06-10 | 服务器备份 `/dmdata/nginx/html/_backups/guide-before-floor-first-20260610033959.tar.gz`；线上文件数 48 |  |
+| T-004 | 优化室内 3D 首屏加载策略 | do | done | Codex | 2026-06-10 | `src/components/navigation/GuideMapShell.vue` 传入 `initial-view="floor"` 和当前楼层 ID |  |
+| T-005 | 更新 H5 部署文档 | act | done | Codex | 2026-06-10 | `docs/H5_DEPLOYMENT_GUIDE.md`；`README.md` 已链接部署文档 |  |
+| T-006 | 生成并维护 PDCA 项目进度 | act | done | Codex | 2026-06-10 | `docs/pdca/reports/2026-06-10.md`；`docs/pdca/dashboard.html`；`docs/pdca/dashboard.png` |  |
+| T-007 | 浏览器 fresh load 复测室内 3D | check | todo | TBD | 2026-06-11 |  | 当前 in-app browser 调试通道初始化异常，需人工或恢复工具后复测 |
+| T-008 | 修复 H5 用户流程闭环 P0/P1 问题 | do | todo | TBD | TBD | `docs/QA/user-flow-closure-audit-2026-06-10.md` | 需确认优先级、负责人和截止日期 |
+| T-009 | 上传域名根目录校验文件 | do | done | Codex | 2026-06-10 | `https://guide.whaoyue.com/gpL0svkeao.txt` 返回 `b772216640a14171ba5655085c8523be` |  |