docs: 更新正式环境部署手册

修复首页快捷入口与三维点位同步
修复导览点位可见性与构建门禁
2026-07-21 15:31:21 +08:00 · 2026-07-21 00:40:06 +08:00 · 2026-07-20 23:54:19 +08:00
22 changed files with 777 additions and 186 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,7 +32,7 @@ jobs:
        run: pnpm lint

      - name: Build H5
-        run: pnpm build:h5
+        run: pnpm build:test:h5

      - name: Build WeChat Mini Program
        run: pnpm build:mp-weixin
--- a/docs/PRODUCTION_MOBILE_DEPLOYMENT_RUNBOOK.md
+++ b/docs/PRODUCTION_MOBILE_DEPLOYMENT_RUNBOOK.md
@@ -1,6 +1,6 @@
 # frontend-miniapp 正式环境部署手册

-最后更新：2026-07-15
+最后更新：2026-07-21

 ## 适用范围

@@ -35,6 +35,7 @@ git remote -v
 正式环境当前依赖一组本地生产补丁，拉取远程代码前必须保护。常见补丁文件包括：

 ```text
+.env.development
 .env.production
 src/config/dataSource.ts
 src/data/adapters/guideDataAdapter.ts
@@ -49,19 +50,34 @@ static/guide-data/guide-stops.json
 static/guide-data/manifest.json
 ```

+这些文件中的改动属于正式环境本地补丁，拉取远程代码时不要直接丢弃。当前正式环境相关配置要点：
+
+- `VITE_PUBLIC_SAME_ORIGIN_ASSET_HOST=172.20.14.21`，避免正式包混入测试服务器 `1.92.206.90`。
+- `VITE_EXPLAIN_ALLOW_STATIC_FALLBACK=true`，讲解数据接口异常时允许使用静态兜底数据。
+- `VITE_SGS_SDK_ORIGIN=https://guide.sznhmuseum.org.cn`，正式域名不再使用 `:4430`。
+- `static/guide-data/manifest.json` 中 `sourceHost` 应为 `172.20.14.21`。
+- 腾讯地图正式 key 只通过环境变量 `VITE_TENCENT_MAP_KEY` 注入，不能写入文档或提交记录。
+
 ## 拉取远程最新代码

 先临时保存本地生产补丁：

 ```powershell
 $stamp = Get-Date -Format 'yyyyMMddHHmmss'
-$msg = "pre-deploy-local-prod-fixes-$stamp"
+$msg = "pre-deploy-prod-local-fixes-$stamp"
 if (git status --porcelain) {
  git stash push -u -m $msg
  Write-Output "STASHED=$msg"
 }
 ```

+执行成功时会看到类似输出，表示本地补丁已 stash：
+
+```text
+Saved working directory and index state On master: pre-deploy-prod-local-fixes-YYYYMMDDHHmmss
+STASHED=pre-deploy-prod-local-fixes-YYYYMMDDHHmmss
+```
+
 拉取远程最新代码：

 ```powershell
@@ -83,6 +99,8 @@ git status --short --branch --untracked-files=all

 如出现冲突，先解决冲突并重新确认生产配置，再继续构建。

+恢复后重点检查 `.env.production`、`static/guide-data/manifest.json` 和 `src/utils/publicUrl.ts`，确认正式环境仍指向 `172.20.14.21` 和 `https://guide.sznhmuseum.org.cn`。
+
 ## 本地构建

 安装依赖并做类型检查：
@@ -447,3 +465,4 @@ https://guide.sznhmuseum.org.cn/ HTTP 200
 - 2026-07-13：确认 `pnpm build:h5` 在 terser 阶段可能 OOM，正式部署可使用 `build:h5:no-minify` 兜底。
 - 2026-07-13：新增并验证 `static/icons/poi/shortcut-icons.svg` 线上可访问。
 - 2026-07-15：排查并修复页面 200 但空白问题。根因为 PowerShell 手工替换构建 JS 时破坏 UTF-8，已新增 `scripts/finalize-h5-build.cjs` 统一处理资源复制、腾讯地图 key 替换、JS 语法校验和正式环境字符串扫描。
+- 2026-07-20：拉取远程最新代码前已执行 `git stash push -u -m pre-deploy-prod-local-fixes-20260720232941`，确认“本地补丁已 stash”；随后快进到 `735c5cd`，执行 `git stash pop` 恢复正式环境补丁，无冲突。构建入口为 `assets/index-CsFOrYfU.js`，主节点备份为 `/data/nginx/html/_backups/mobile-before-deploy-20260720233343.tar.gz`，同步脚本最终输出 `All frontend worker nodes synced.`。
--- a/scripts/finalize-h5-build-policy.cjs
+++ b/scripts/finalize-h5-build-policy.cjs
@@ -0,0 +1,61 @@
+const { loadEnv } = require('vite')
+
+const tencentMapKeyPlaceholder = '__REPLACE_WITH_TENCENT_MAP_WEB_KEY__'
+const tencentMapKeyPattern = /^[A-Z0-9]{5}(?:-[A-Z0-9]{5}){4,6}$/i
+
+const isUsableTencentMapKey = (value) => (
+  tencentMapKeyPattern.test(value)
+  && value !== tencentMapKeyPlaceholder
+)
+
+const resolveH5BuildPolicy = ({
+  args = [],
+  projectRoot,
+  environment = process.env,
+  loadProductionEnv = (root) => loadEnv('production', root, '')
+}) => {
+  const flags = new Set(args)
+  const requireTencentMapKey = flags.has('--require-tencent-map-key')
+  const allowPlaceholder = flags.has('--allow-placeholder')
+
+  if (requireTencentMapKey && allowPlaceholder) {
+    throw new Error('H5 build cannot require a Tencent map key and allow its placeholder at the same time.')
+  }
+
+  if (!requireTencentMapKey) {
+    return {
+      allowPlaceholder,
+      requireTencentMapKey,
+      tencentMapKey: ''
+    }
+  }
+
+  const productionEnv = loadProductionEnv(projectRoot)
+  const tencentMapKey = (
+    environment.VITE_TENCENT_MAP_KEY
+    || productionEnv.VITE_TENCENT_MAP_KEY
+    || ''
+  ).trim()
+
+  if (!isUsableTencentMapKey(tencentMapKey)) {
+    throw new Error([
+      'Production H5 build requires a well-formed non-placeholder VITE_TENCENT_MAP_KEY.',
+      'Inject it through CI or an ignored .env.production.local file.'
+    ].join(' '))
+  }
+
+  return {
+    allowPlaceholder,
+    requireTencentMapKey,
+    tencentMapKey
+  }
+}
+
+const isTextBuildFile = (filePath) => /\.(?:js|mjs|html|json|css|txt|svg|xml|map)$/i.test(filePath)
+
+module.exports = {
+  isTextBuildFile,
+  isUsableTencentMapKey,
+  resolveH5BuildPolicy,
+  tencentMapKeyPlaceholder
+}
--- a/scripts/finalize-h5-build.cjs
+++ b/scripts/finalize-h5-build.cjs
@@ -1,29 +1,36 @@
 const fs = require('node:fs')
 const path = require('node:path')
 const { spawnSync } = require('node:child_process')
-
-require('./copy-h5-nav-assets.cjs')
+const {
+  isTextBuildFile,
+  resolveH5BuildPolicy,
+  tencentMapKeyPlaceholder
+} = require('./finalize-h5-build-policy.cjs')

 const projectRoot = path.resolve(__dirname, '..')
 const h5Root = path.join(projectRoot, 'dist', 'build', 'h5')
-const placeholder = '__REPLACE_WITH_TENCENT_MAP_WEB_KEY__'
+const placeholder = tencentMapKeyPlaceholder
 const badPatterns = [
  'http://1.92.206.90:9000',
  '1.92.206.90',
  'guide.whaoyue.com',
  placeholder
 ]
-const args = new Set(process.argv.slice(2))
-const requireTencentMapKey = args.has('--require-tencent-map-key')
-const allowPlaceholder = args.has('--allow-placeholder')
-const tencentMapKey = (process.env.VITE_TENCENT_MAP_KEY || '').trim()
+const {
+  allowPlaceholder,
+  requireTencentMapKey,
+  tencentMapKey
+} = resolveH5BuildPolicy({
+  args: process.argv.slice(2),
+  projectRoot
+})
+
+require('./copy-h5-nav-assets.cjs')

 if (!fs.existsSync(h5Root)) {
  throw new Error(`H5 build output not found: ${h5Root}`)
 }

-const isTextFile = (filePath) => /\.(?:js|mjs|html|json|css|txt|svg|xml)$/i.test(filePath)
-
 const walkFiles = (dir, files = []) => {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const filePath = path.join(dir, entry.name)
@@ -42,16 +49,21 @@ const walkFiles = (dir, files = []) => {
 }

 const allFiles = walkFiles(h5Root)
-const textFiles = allFiles.filter(isTextFile)
+const textFiles = allFiles.filter(isTextBuildFile)
 const placeholderFiles = textFiles.filter((file) => fs.readFileSync(file, 'utf8').includes(placeholder))
-const hasUsableTencentMapKey = tencentMapKey.length > 0 && tencentMapKey !== placeholder
+const hasUsableTencentMapKey = tencentMapKey.length > 0
+const missingTencentMapKeyMessage = [
+  'Production H5 build requires a well-formed non-placeholder VITE_TENCENT_MAP_KEY.',
+  'Inject it through CI or an ignored .env.production.local file.'
+].join(' ')
+
+if (requireTencentMapKey && !hasUsableTencentMapKey) {
+  throw new Error(missingTencentMapKeyMessage)
+}

 if (placeholderFiles.length > 0) {
  if (!hasUsableTencentMapKey) {
-    const message = [
-      'H5 build output still contains Tencent map key placeholder.',
-      'Please set VITE_TENCENT_MAP_KEY before production build.'
-    ].join(' ')
+    const message = `H5 build output still contains Tencent map key placeholder. ${missingTencentMapKeyMessage}`

    if (requireTencentMapKey && !allowPlaceholder) {
      throw new Error(message)
@@ -108,8 +120,8 @@ for (const file of textFiles) {
 }

 if (badMatches.length > 0) {
-  if (allowPlaceholder && badMatches.every((item) => item.pattern === placeholder)) {
-    console.warn('[finalize-h5-build] Tencent map key placeholder is allowed for this build.')
+  if (allowPlaceholder) {
+    console.warn('[finalize-h5-build] Test H5 build allows non-production source hosts and the Tencent map key placeholder.')
  } else {
    console.error(JSON.stringify(badMatches.slice(0, 20), null, 2))
    throw new Error('H5 build output contains forbidden test host, old domain, or placeholder.')
--- a/src/components/navigation/GuideMapShell.vue
+++ b/src/components/navigation/GuideMapShell.vue
@@ -583,17 +583,21 @@ const markFloorSwitchFailedIfUnrendered = (floorId: string, requestSeq: number)
  })
 }

-const handleFloorChange = (floor: { id: string; label: string }) => {
+const requestFloorSwitch = (
+  floor: { id: string; label: string },
+  options: { force?: boolean } = {}
+) => {
  const floorId = floor.id
-  if (!floorId || loadingFloorId.value) return
+  if (!floorId) return Promise.resolve()
+  if (loadingFloorId.value === floorId) return Promise.resolve()
  if (
-    floorId === renderedFloorId.value
+    !options.force && floorId === renderedFloorId.value
    && activeFloorId.value === floorId
    && props.indoorView === 'floor'
    && props.layerMode !== 'multi'
  ) {
    emit('floorChange', floorId)
-    return
+    return Promise.resolve()
  }

  requestedFloorId.value = floorId
@@ -607,7 +611,7 @@ const handleFloorChange = (floor: { id: string; label: string }) => {
    floorId,
    floorLabel: floor.label
  })
-  Promise.resolve(indoorRendererRef.value?.switchFloor?.(floorId))
+  return Promise.resolve(indoorRendererRef.value?.switchFloor?.(floorId))
    .then(() => {
      markFloorSwitchFailedIfUnrendered(floorId, requestSeq)
    })
@@ -623,6 +627,10 @@ const handleFloorChange = (floor: { id: string; label: string }) => {
    })
 }

+const handleFloorChange = (floor: { id: string; label: string }) => {
+  void requestFloorSwitch(floor)
+}
+
 const handleLayerModeChange = (mode: LayerDisplayMode) => {
  // 手动切换展示层数时使用统一的短保护期。
  indoorRendererRef.value?.disableAutoSwitchTemporarily?.(manualAutoSwitchPauseMs)
@@ -789,7 +797,11 @@ defineExpose({
    indoorRendererRef.value?.clearRoute?.()
  },
  // 仅发起切换；父级必须以 floor-change 作为已提交的唯一依据。
-  switchFloor: (floorId: string) => indoorRendererRef.value?.switchFloor?.(floorId),
+  switchFloor: (floorId: string) => {
+    const floor = findFloorItemById(floorId)
+    if (!floor) return Promise.resolve()
+    return requestFloorSwitch(floor, { force: true })
+  },
  showOverview: handleShowOverview,
  resetToViewBaseline: (options: {
    view: 'overview' | 'floor'
--- a/src/components/search/PoiSearchPanel.vue
+++ b/src/components/search/PoiSearchPanel.vue
@@ -248,6 +248,7 @@ import type {
  PoiCategoryResultState,
  PoiSearchContext
 } from '@/domain/poiSearch'
+import { nextHomeSearchResultVersion } from './homeSearchResultVersion'
 import { isEmbeddedInWechatMiniProgram } from '@/utils/hostEnvironment'

 const props = withDefaults(defineProps<{
@@ -397,7 +398,8 @@ const emitResultsState = () => {
  emit('results-change', {
    ...context,
    visiblePoiIds: active ? context.visiblePoiIds : [],
-    active
+    active,
+    requestId: props.variant === 'home' ? nextHomeSearchResultVersion() : undefined
  })
 }

@@ -411,7 +413,8 @@ const emitPendingHomeSearchResults = (floor?: Pick<MuseumFloor, 'id' | 'label'>)
    floorLabel: floor?.label || context.floorLabel,
    visiblePoiIds: [],
    active: true,
-    pending: true
+    pending: true,
+    requestId: nextHomeSearchResultVersion()
  })
 }

--- a/src/components/search/homeSearchResultVersion.ts
+++ b/src/components/search/homeSearchResultVersion.ts
@@ -0,0 +1,7 @@
+// This version survives a PoiSearchPanel remount, unlike its local request sequence.
+let latestHomeSearchResultVersion = 0
+
+export const nextHomeSearchResultVersion = () => {
+  latestHomeSearchResultVersion += 1
+  return latestHomeSearchResultVersion
+}
--- a/src/data/adapters/navAssetsAdapter.ts
+++ b/src/data/adapters/navAssetsAdapter.ts
@@ -10,6 +10,7 @@ import {
  isIndoorNavigableFloor
 } from '@/domain/guideFloor'
 import {
+  isVisitorRestrictedPlaceName,
  normalizePoiSemanticValue
 } from '@/domain/poiCategories'

@@ -193,6 +194,16 @@ const isPoiAccessible = (poi: StaticNavPoiPayload) => (
  || poi.categories?.some((category) => category.topCategory === 'accessibility_special_service') === true
 )

+const resolveStaticPoiVisitorVisible = (
+  poi: StaticNavPoiPayload,
+  semanticType: string
+) => (
+  typeof poi.visitorVisible === 'boolean'
+    ? poi.visitorVisible
+    : semanticType !== 'service_space'
+      && ![poi.name, poi.sourceObjectName].some(isVisitorRestrictedPlaceName)
+)
+
 export const toMuseumPoi = (poi: StaticNavPoiPayload): MuseumPoi => {
  const categoryFallbackIconType = poi.categories?.[0]?.iconType
  const iconType = getStaticPoiSemanticType(poi, poi.iconType || categoryFallbackIconType)
@@ -214,6 +225,7 @@ export const toMuseumPoi = (poi: StaticNavPoiPayload): MuseumPoi => {
    sourceObjectName: poi.sourceObjectName,
    sourceConfidence: poi.sourceConfidence,
    navigationReadiness: poi.navigationReadiness,
+    visitorVisible: resolveStaticPoiVisitorVisible(poi, iconType),
    accessible: isPoiAccessible(poi),
    kind,
    hallName: kind === 'hall' ? poi.name : undefined
--- a/src/data/adapters/sgsSdkGuideAdapter.ts
+++ b/src/data/adapters/sgsSdkGuideAdapter.ts
@@ -19,6 +19,7 @@ import {
  isIndoorNavigableFloor
 } from '@/domain/guideFloor'
 import {
+  isVisitorRestrictedPlaceName,
  isPoiSearchCategorySupported,
  normalizePoiSemanticValue
 } from '@/domain/poiCategories'
@@ -146,6 +147,7 @@ const spaceCategoryBySgsType: Record<string, MuseumCategory> = {
 const categoryBySgsType: Record<string, MuseumCategory & { accessible?: boolean }> = {
  exhibition_hall: hallCategory,
  theater: spaceCategoryBySgsType.theater,
+  service_space: spaceCategoryBySgsType.service_space,
  commercial: spaceCategoryBySgsType.commercial,
  restaurant: spaceCategoryBySgsType.restaurant,
  cafe: spaceCategoryBySgsType.cafe,
@@ -414,6 +416,25 @@ const categoryForBusinessType = (businessType?: string | null): MuseumCategory =
  }
 }

+const resolveSgsPoiVisitorVisible = (
+  source: {
+    visitorVisible?: boolean | null
+    name?: string | null
+    sourceNodeName?: string | null
+    anchorNodeName?: string | null
+  },
+  category: MuseumCategory
+) => (
+  typeof source.visitorVisible === 'boolean'
+    ? source.visitorVisible
+    : category.id !== 'space_service'
+      && ![
+        source.name,
+        source.sourceNodeName,
+        source.anchorNodeName
+      ].some(isVisitorRestrictedPlaceName)
+)
+
 interface SgsHallPoiBuildOptions {
  fallbackY?: number
 }
@@ -658,9 +679,10 @@ export const toMuseumPoiFromSgs = (
      }
    ],
    positionGltf: normalizePosition(poi),
-    sourceObjectName: poi.anchorNodeName || undefined,
+    sourceObjectName: poi.anchorNodeName || undefined,
    sourceConfidence: 'backend-sgs-sdk',
    navigationReadiness: '位置预览',
+    visitorVisible: resolveSgsPoiVisitorVisible(poi, category),
    accessible: category.accessible === true,
    kind,
    hallId: kind === 'hall' ? spatialAreaId || stringifyId(poi.id) : undefined,
@@ -825,6 +847,7 @@ export const toMuseumSpacePointFromSgs = (
    sourceObjectName: space.sourceNodeName || undefined,
    sourceConfidence: spacePosition.sourceConfidence,
    navigationReadiness: '位置预览',
+    visitorVisible: resolveSgsPoiVisitorVisible(space, category),
    accessible: false,
    kind: 'space',
    hallId: category.id === hallCategory.id ? spaceId : undefined,
@@ -895,8 +918,9 @@ const createSpaceFallbackHallPoi = (
    positionGltf: position,
    sourceObjectName: space.sourceNodeName || undefined,
    sourceConfidence: spacePosition.sourceConfidence,
-    navigationReadiness: '位置预览',
-    accessible: false,
+    navigationReadiness: '位置预览',
+    visitorVisible: resolveSgsPoiVisitorVisible(space, category),
+    accessible: false,
    kind: 'hall',
    hallId,
    hallName: normalizedText(space.name),
@@ -983,6 +1007,7 @@ export const toMuseumHallPoisFromSgs = (
        ? spacePosition?.sourceConfidence || sgsSpaceCenterConfidence
        : sgsHallEntranceConfidence,
      navigationReadiness: '位置预览',
+      visitorVisible: resolveSgsPoiVisitorVisible(matchedSpace, category),
      accessible: false,
      kind: 'hall',
      hallId,
--- a/src/data/providers/sgsSdkApiProvider.ts
+++ b/src/data/providers/sgsSdkApiProvider.ts
@@ -65,6 +65,7 @@ export interface SgsPoiPayload {
  y?: number | null
  z?: number | null
  status?: string | null
+  visitorVisible?: boolean | null
  anchorNodeName?: string | null
  description?: string | null
  iconUrl?: string | null
@@ -87,6 +88,7 @@ export interface SgsSpacePayload {
  center?: SgsPositionPayload | null
  sourceNodeName?: string | null
  status?: string | null
+  visitorVisible?: boolean | null
  colorHex?: string | null
 }

--- a/src/data/providers/staticNavAssetsProvider.ts
+++ b/src/data/providers/staticNavAssetsProvider.ts
@@ -27,6 +27,7 @@ export interface StaticNavPoiPayload {
  sourceObjectName?: string
  navigationReadiness?: string
  sourceConfidence?: string
+  visitorVisible?: boolean | null
 }

 export interface StaticNavManifestFloorModelPayload {
--- a/src/domain/museum.ts
+++ b/src/domain/museum.ts
@@ -96,6 +96,8 @@ export interface MuseumPoi {
  sourceObjectName?: string
  sourceConfidence?: string
  navigationReadiness?: string
+  /** Explicit visitor-search eligibility supplied by the source or adapter policy. */
+  visitorVisible?: boolean
  accessible: boolean
  kind?: MuseumPoiKind
  hallId?: string
--- a/src/domain/poiCategories.ts
+++ b/src/domain/poiCategories.ts
@@ -183,6 +183,7 @@ export type PoiCategorySource = Pick<
  | 'sourcePlaceId'
  | 'sourceSpaceId'
  | 'sourceObjectName'
+  | 'visitorVisible'
 >

 const normalizeValue = (value?: string | null) => (value || '')
@@ -192,6 +193,13 @@ const normalizeValue = (value?: string | null) => (value || '')
  .replace(/[\s-]+/g, '_')
  .replace(/^_+|_+$/g, '')

+const visitorRestrictedPlaceNamePattern = /(?:贵宾|vip|员工|职工|后勤|办公|行政|库房|仓库|机房|设备间|配电|弱电|强电|保洁|值班|消防控制|监控室|staff|employee|back[_ -]?of[_ -]?house|maintenance)/i
+
+/** Legacy sources without an explicit flag must not expose staff-only places. */
+export const isVisitorRestrictedPlaceName = (value?: string | null) => (
+  visitorRestrictedPlaceNamePattern.test(normalizeValue(value))
+)
+
 const poiSemanticAliases: Readonly<Record<string, string>> = {
  exhibition: 'exhibition_hall',
  exhibition_hall: 'exhibition_hall',
@@ -397,7 +405,7 @@ export const resolvePoiCategory = (poi: PoiCategorySource) => (
  POI_CATEGORIES.find((category) => matchesPoiCategory(poi, category)) || null
 )

-const hiddenVisitorPrimaryTypes = new Set([
+const hiddenVisitorTypes = new Set([
  'entrance_exit',
  'hall_entrance',
  'entrance_anchor',
@@ -406,7 +414,7 @@ const hiddenVisitorPrimaryTypes = new Set([
  'operation_experience'
 ])

-const primaryTypeValues = (poi: PoiCategorySource) => [
+const visitorTypeValues = (poi: PoiCategorySource) => [
  poi.primaryCategory.id,
  poi.primaryCategory.label,
  poi.primaryCategory.iconType || ''
@@ -414,10 +422,18 @@ const primaryTypeValues = (poi: PoiCategorySource) => [
  .map(normalizePoiSemanticValue)
  .filter(Boolean)

+const isHiddenVisitorType = (value: string) => {
+  const normalizedValue = normalizePoiSemanticValue(value)
+  const sourceWrappedValue = normalizedValue.replace(/^(?:space|poi|facility|business)_/, '')
+  return hiddenVisitorTypes.has(normalizedValue)
+    || hiddenVisitorTypes.has(sourceWrappedValue)
+}
+
 /** A visitor result must never be a guide point, door, entrance anchor, or route node. */
 export const isVisitorSearchPoi = (poi: PoiCategorySource) => {
+  if (poi.visitorVisible === false) return false
  if (poi.kind === 'guide' || poi.kind === 'hall_entrance') return false
-  return !primaryTypeValues(poi).some((value) => hiddenVisitorPrimaryTypes.has(value))
+  return !visitorTypeValues(poi).some(isHiddenVisitorType)
 }

 /** Default floor browse only contains canonical halls and valid destination spaces. */
@@ -516,8 +532,6 @@ export const getPoiDataIssues = (poi: MuseumPoi): PoiDataIssue[] => {
  } else if (!hasFinitePosition(poi.positionGltf)) {
    issues.push({ code: 'invalid-position', ...issueBase })
  }
-  if (!isPoiSearchCategorySupported(poi)) issues.push({ code: 'unsupported-category', ...issueBase })
-
  return issues
 }

@@ -548,6 +562,6 @@ export const warnPoiCollectionIssues = (source: string, pois: MuseumPoi[]) => {
  const inspection = inspectPoiCollection(pois)
  if (!inspection.issues.length && !inspection.duplicateIds.length) return

-  // 开发期集中输出数据契约问题，避免在页面组件中散落源数据校验。
-  console.warn(`[POI 数据校验] ${source}`, inspection)
+  // This is an aggregate development diagnostic, not a visitor-facing failure.
+  console.debug(`[POI 数据诊断] ${source}`, inspection)
 }
--- a/src/domain/poiSearch.ts
+++ b/src/domain/poiSearch.ts
@@ -28,6 +28,8 @@ export interface PoiSearchSelection {
 export interface PoiCategoryResultState extends PoiSearchContext {
  active: boolean
  pending?: boolean
+  /** Monotonic home-result event version used to reject stale cross-component state. */
+  requestId?: number
 }

 export type GuidePoiSearchMode = 'default' | 'category' | 'keyword'
--- a/src/pages/index/index.vue
+++ b/src/pages/index/index.vue
@@ -373,6 +373,8 @@ const requestedFloorId = ref('')
 const requestedFloorLabel = ref('')
 const loadingFloorId = ref('')
 const renderedFloorId = ref('')
+// Only GuideMapShell's floor-change confirms that the Three.js floor is usable.
+const committedFloorId = ref('')
 const failedFloorId = ref('')
 const selectedGuidePoi = ref<GuideRenderPoi | null>(null)
 const selectedGuidePoiDetailTarget = ref<PoiDetailTarget | null>(null)
@@ -432,6 +434,8 @@ const homeSearchExpanded = ref(false)
 const homeCategoryModeActive = ref(false)
 const searchVisiblePoiIds = ref<string[] | null>(null)
 const searchTargetFocusRequest = ref<TargetPoiFocusRequestViewModel | null>(null)
+const homeSearchMapState = ref<PoiCategoryResultState | null>(null)
+let latestHomeSearchMapRequestId = 0
 type PoiSearchOverlayHistoryState = {
  museumGuideOverlay?: 'poi-search'
  [key: string]: unknown
@@ -853,6 +857,9 @@ const handleTabChange = (tabId: GuideTopTab) => {
    }
  }

+  if (tabId !== currentTab.value) {
+    invalidateHomeSearchFloorCommit()
+  }
  currentTab.value = tabId
  syncTopTabToUrl(tabId)
  loadTopTabData(tabId)
@@ -875,6 +882,7 @@ const syncTopTabFromHash = () => {
    currentTab.value = tab
    loadTopTabData(tab)
    if (tabChanged) {
+      invalidateHomeSearchFloorCommit()
      showRoutePlanner.value = false
      isSimulatingRoute.value = false
      isPoiCardCollapsed.value = false
@@ -1000,11 +1008,19 @@ const handleFloorRequest = ({ floorId, floorLabel }: { floorId: string; floorLab
  requestedFloorLabel.value = floorLabel
  loadingFloorId.value = floorId
  failedFloorId.value = ''
+  if (homeSearchMapState.value?.active) {
+    searchVisiblePoiIds.value = []
+  }
 }

 const handleFloorChange = (floorId: string) => {
  activeGuideFloor.value = floorId
  renderedFloorId.value = floorId
+  committedFloorId.value = floorId
+  if (requestedFloorId.value === floorId) {
+    requestedFloorId.value = ''
+    requestedFloorLabel.value = ''
+  }
  if (loadingFloorId.value === floorId) {
    loadingFloorId.value = ''
  }
@@ -1014,6 +1030,7 @@ const handleFloorChange = (floorId: string) => {
  indoorView.value = 'floor'
  selectedGuidePoi.value = null
  isPoiCardCollapsed.value = false
+  syncHomeSearchMarkersForCommittedFloor(floorId)
  showIndoorHint(`已切换到 ${getGuideFloorLabel(floorId)}，单指平移、双指可缩放`, 3200)
  console.log('楼层渲染完成:', floorId)
 }
@@ -1023,6 +1040,13 @@ const handleFloorSwitchFailed = ({ floorId, floorLabel }: { floorId: string; flo
    loadingFloorId.value = ''
  }
  failedFloorId.value = floorId
+  if (requestedFloorId.value === floorId) {
+    requestedFloorId.value = ''
+    requestedFloorLabel.value = ''
+  }
+  if (homeSearchMapState.value?.floorId === floorId) {
+    searchVisiblePoiIds.value = []
+  }
  showIndoorHint(`${floorLabel || getGuideFloorLabel(floorId)} 加载失败，请稍后重试`, 3600)
  console.warn('楼层渲染失败:', floorId)
 }
@@ -1030,6 +1054,8 @@ const handleFloorSwitchFailed = ({ floorId, floorLabel }: { floorId: string; flo
 const handleIndoorViewChange = (view: GuideIndoorView) => {
  indoorView.value = view
  if (view !== 'floor') {
+    committedFloorId.value = ''
+    syncHomeSearchMarkersForCommittedFloor()
    selectedGuidePoi.value = null
    isPoiCardCollapsed.value = false
  }
@@ -1045,6 +1071,8 @@ const handleAutoSwitch = (event: { from: 'overview' | 'floor'; to: 'overview' |
  console.log('自动切换视图:', event)
  indoorView.value = event.to
  if (event.to !== 'floor') {
+    committedFloorId.value = ''
+    syncHomeSearchMarkersForCommittedFloor()
    selectedGuidePoi.value = null
    isPoiCardCollapsed.value = false
  }
@@ -1053,6 +1081,11 @@ const handleAutoSwitch = (event: { from: 'overview' | 'floor'; to: 'overview' |

 const handleInitialModelReady = (event: { view: GuideIndoorView; floorId?: string; elapsedMs?: number }) => {
  const readyFloorId = event.floorId || activeGuideFloor.value
+  indoorView.value = event.view
+  if (event.view !== 'floor') {
+    committedFloorId.value = ''
+    syncHomeSearchMarkersForCommittedFloor()
+  }
  if (event.view === 'overview' && readyFloorId) {
    activeGuideFloor.value = readyFloorId
    renderedFloorId.value = readyFloorId
@@ -1092,6 +1125,7 @@ const handleGuidePoiClick = (poi: GuideRenderPoi) => {
  isSimulatingRoute.value = false
  activeGuideFloor.value = poi.floorId
  renderedFloorId.value = poi.floorId
+  committedFloorId.value = poi.floorId
  showIndoorHint(`${poi.name} · ${getGuideFloorLabel(poi.floorId)}`, 3000)
 }

@@ -1519,6 +1553,7 @@ const resetGuideModelToFloorBaseline = async ({
  if (!guideModelState.isCurrentRequest(resetRequest.requestId)) return
  if (resetResult === 'applied') {
    renderedFloorId.value = activeGuideFloor.value
+    committedFloorId.value = activeGuideFloor.value
    guideModelState.completeViewBaselineReset(resetRequest)
    console.info('馆内三维模型已恢复楼层视觉基线:', { rendererReason })
  } else if (resetResult === 'not-ready' || resetResult === undefined) {
@@ -1589,12 +1624,20 @@ const clearHomeSearchMapState = () => {
  homeCategoryModeActive.value = false
  searchVisiblePoiIds.value = null
  searchTargetFocusRequest.value = null
+  homeSearchMapState.value = null
+}
+
+const invalidateHomeSearchFloorCommit = () => {
+  clearHomeSearchMapState()
+  committedFloorId.value = ''
+  indoorView.value = 'overview'
 }

 const handleHomeCategoryModeChange = (active: boolean) => {
  homeCategoryModeActive.value = active
  if (!active) {
    searchVisiblePoiIds.value = null
+    homeSearchMapState.value = null
    return
  }

@@ -1604,19 +1647,72 @@ const handleHomeCategoryModeChange = (active: boolean) => {
  selectedGuidePoi.value = null
  isPoiCardCollapsed.value = false
  is3DMode.value = true
-  indoorView.value = 'floor'
+  searchVisiblePoiIds.value = []
 }

-const handleHomeSearchResultsChange = (state: PoiCategoryResultState) => {
-  if (!state.active) {
-    searchVisiblePoiIds.value = null
+const isHomeSearchFloorCommitted = (floorId: string) => (
+  Boolean(floorId)
+  && committedFloorId.value === floorId
+  && indoorView.value === 'floor'
+)
+
+const requestHomeSearchFloor = (floorId: string, floorLabel = '') => {
+  if (!floorId || requestedFloorId.value === floorId || loadingFloorId.value === floorId) return
+
+  requestedFloorId.value = floorId
+  requestedFloorLabel.value = floorLabel || getGuideFloorLabel(floorId)
+  loadingFloorId.value = floorId
+  failedFloorId.value = ''
+  void Promise.resolve(guideMapShellRef.value?.switchFloor?.(floorId))
+    .catch((error) => {
+      console.error('快捷入口楼层切换失败:', error)
+    })
+}
+
+const syncHomeSearchMarkersForCommittedFloor = (floorId = committedFloorId.value) => {
+  const state = homeSearchMapState.value
+  if (
+    !state?.active
+    || state.pending
+    || state.floorId !== floorId
+    || indoorView.value !== 'floor'
+  ) {
+    searchVisiblePoiIds.value = state?.active ? [] : null
    return
  }

  searchVisiblePoiIds.value = [...state.visiblePoiIds]
-  if (state.floorId && !state.pending) {
-    activeGuideFloor.value = state.floorId
+}
+
+const handleHomeSearchResultsChange = (state: PoiCategoryResultState) => {
+  if (
+    typeof state.requestId === 'number'
+    && state.requestId < latestHomeSearchMapRequestId
+  ) return
+  if (typeof state.requestId === 'number') {
+    latestHomeSearchMapRequestId = state.requestId
  }
+
+  if (!state.active) {
+    clearHomeSearchMapState()
+    return
+  }
+
+  homeSearchMapState.value = {
+    ...state,
+    visiblePoiIds: [...state.visiblePoiIds]
+  }
+  if (state.pending) {
+    searchVisiblePoiIds.value = []
+  }
+
+  if (!isHomeSearchFloorCommitted(state.floorId)) {
+    searchVisiblePoiIds.value = []
+    requestHomeSearchFloor(state.floorId, state.floorLabel)
+    return
+  }
+
+  syncHomeSearchMarkersForCommittedFloor(state.floorId)
 }

 const handleHomeSearchResultTap = async (poi: MuseumPoi, context: PoiSearchContext) => {
@@ -1672,6 +1768,7 @@ const handleExplainHallClick = async (hallId: string) => {
 }

 const handleExplainBack = () => {
+  invalidateHomeSearchFloorCommit()
  currentTab.value = 'guide'
  syncTopTabToUrl('guide')
  loadTopTabData('guide')
--- a/src/repositories/GuideModelRepository.ts
+++ b/src/repositories/GuideModelRepository.ts
@@ -22,10 +22,7 @@ import {
 } from '@/domain/guideFloor'
 import {
  buildSgsFloorAliases,
-  createSgsHallPoiDiagnostics,
-  formatSgsFloorLabel,
-  toMuseumHallPoisFromSgs,
-  toMuseumPoiFromSgs
+  formatSgsFloorLabel
 } from '@/data/adapters/sgsSdkGuideAdapter'
 import {
  defaultSgsSdkApiProvider,
@@ -47,6 +44,9 @@ import {
 import type {
  GuideRepository
 } from '@/repositories/GuideRepository'
+import {
+  canonicalizeVisitorSearchPois
+} from '@/repositories/GuideRepository'
 import {
  guideRepository
 } from '@/repositories/createGuideRepository'
@@ -84,37 +84,6 @@ const toGuideRenderPoi = (poi: MuseumPoi): GuideRenderPoi => ({
  })
 })

-const toSgsRenderPoi = (poi: ReturnType<typeof toMuseumPoiFromSgs>) => toGuideRenderPoi(poi)
-
-const getRenderPoiDedupeKeys = (poi: GuideRenderPoi) => {
-  // A facility can be located inside the same spatial area as other facilities.
-  // That relationship must not collapse distinct visitor markers (for example,
-  // a restroom and an elevator in one service zone). Space identity is only a
-  // canonical-place key for halls, spaces, and business-place representations.
-  const canDedupeBySpace = poi.kind === 'hall'
-    || poi.kind === 'space'
-    || poi.primaryCategory === 'business_poi'
-  const stableKeys = [
-    poi.id ? `id:${poi.id}` : '',
-    canDedupeBySpace && poi.sourceSpaceId ? `space:${poi.floorId}:${poi.sourceSpaceId}` : '',
-    canDedupeBySpace && poi.spaceId ? `space:${poi.floorId}:${poi.spaceId}` : '',
-    poi.sourcePlaceId ? `place:${poi.floorId}:${poi.sourcePlaceId}` : ''
-  ].filter(Boolean)
-
-  if (stableKeys.length) return stableKeys
-  return poi.sourceObjectName ? [`object:${poi.floorId}:${poi.sourceObjectName}`] : []
-}
-
-const dedupeRenderPoisById = (pois: GuideRenderPoi[]) => {
-  const seen = new Set<string>()
-  return pois.filter((poi) => {
-    const keys = getRenderPoiDedupeKeys(poi)
-    if (!keys.length || keys.some((key) => seen.has(key))) return false
-    keys.forEach((key) => seen.add(key))
-    return true
-  })
-}
-
 const countByValue = <T>(
  items: T[],
  selector: (item: T) => string | number | null | undefined
@@ -124,17 +93,6 @@ const countByValue = <T>(
  return counts
 }, {})

-const countDroppedRenderPoiCategories = (
-  sourcePois: GuideRenderPoi[],
-  keptPois: GuideRenderPoi[]
-) => {
-  const keptIds = new Set(keptPois.map((poi) => poi.id))
-  return countByValue(
-    sourcePois.filter((poi) => !keptIds.has(poi.id)),
-    (poi) => poi.primaryCategory
-  )
-}
-
 const trimTrailingSlash = (value: string) => value.replace(/\/+$/, '')

 const resolveSgsAssetUrl = (url?: string | null) => {
@@ -234,20 +192,6 @@ const summarizeYValues = (pois: GuideRenderPoi[]) => {
  }
 }

-const getMedianPoiY = (pois: GuideRenderPoi[]) => {
-  const values = pois
-    .map((poi) => poi.positionGltf?.[1])
-    .filter((value): value is number => Number.isFinite(value))
-    .sort((left, right) => left - right)
-
-  if (!values.length) return undefined
-
-  const middle = Math.floor(values.length / 2)
-  return values.length % 2
-    ? values[middle]
-    : (values[middle - 1] + values[middle]) / 2
-}
-
 const getSgsFloorModelMatchKeys = (floor: SgsSdkFloorSummaryPayload, label: string) => (
  [
    String(floor.floorId),
@@ -442,7 +386,7 @@ export class SgsSdkGuideModelRepository implements GuideModelRepository {

    const resolvedFloorId = String(matchedFloor.floorId)
    const loadFloorData = async <T>(
-      endpoint: 'pois' | 'spaces' | 'navigablePlaces' | 'guidePois' | 'guideSpacePoints',
+      endpoint: 'guideSearch',
      loader: () => Promise<T[]>
    ) => {
      try {
@@ -457,88 +401,36 @@ export class SgsSdkGuideModelRepository implements GuideModelRepository {
      }
    }

-    const [pois, spaces, navigablePlaces, guidePois, guideSpacePoints] = await Promise.all([
-      loadFloorData('pois', () => this.provider.getFloorPois(resolvedFloorId)),
-      loadFloorData('spaces', () => this.provider.getFloorSpaces(resolvedFloorId)),
-      loadFloorData('navigablePlaces', () => this.provider.getNavigablePlaces(resolvedFloorId)),
-      loadFloorData('guidePois', () => this.guide.listPois()),
-      loadFloorData('guideSpacePoints', () => this.guide.listSpacePoints())
-    ])
-    const ordinaryPois = pois
-      .map((poi) => toMuseumPoiFromSgs(poi, manifest.floors))
-      .filter(isVisitorSearchPoi)
-      .map(toSgsRenderPoi)
-    const repositoryBusinessPois = guidePois
-      .filter((poi) => (
-        poi.floorId === resolvedFloorId
-        && poi.primaryCategory.id === 'business_poi'
-        && isVisitorSearchPoi(poi)
-      ))
+    const visitorSearchPois = await loadFloorData(
+      'guideSearch',
+      () => this.guide.searchPois('', resolvedFloorId)
+    )
+    const canonicalPois = canonicalizeVisitorSearchPois(visitorSearchPois)
+    const renderPois = canonicalPois
+      .filter((poi) => poi.floorId === resolvedFloorId)
      .map(toGuideRenderPoi)
-    const repositorySpacePois = guideSpacePoints
-      .filter((poi) => poi.floorId === resolvedFloorId && isVisitorSearchPoi(poi))
-      .map(toGuideRenderPoi)
-    const floorPoiMedianY = getMedianPoiY(ordinaryPois)
-    const museumHallPois = toMuseumHallPoisFromSgs(spaces, navigablePlaces, manifest.floors, resolvedFloorId, {
-      fallbackY: floorPoiMedianY
-    })
-    const hallDiagnostics = createSgsHallPoiDiagnostics(spaces, navigablePlaces, museumHallPois)
-
-    if (hallDiagnostics.eligibleSpaceCount > 0 && hallDiagnostics.hallPoiWithPositionCount === 0) {
-      warnSgsGuideModelDiagnostics('eligible hall spaces produced no renderable hall POIs', {
-        floorId: resolvedFloorId,
-        ...hallDiagnostics
-      })
-    }
-
-    const hallPois = museumHallPois
-      .filter(isVisitorSearchPoi)
-      .map(toSgsRenderPoi)
-    const adaptedPois = dedupeRenderPoisById([
-      ...hallPois,
-      ...ordinaryPois,
-      ...repositorySpacePois,
-      ...repositoryBusinessPois
-    ])
-    const floorMatchedPois = adaptedPois.filter((poi) => poi.floorId === resolvedFloorId)
-    const renderPois = floorMatchedPois
      .filter((poi) => Array.isArray(poi.positionGltf) && poi.positionGltf.length === 3)

    const renderHallPois = renderPois.filter((poi) => poi.kind === 'hall' || poi.primaryCategory === 'exhibition_hall')
    logSgsGuideModelDiagnostics('floor POI category diagnostics', {
      floorId: resolvedFloorId,
      floorCode: matchedFloor.floorCode,
-      rawPoiCount: pois.length,
-      rawRepositoryBusinessPoiCount: repositoryBusinessPois.length,
-      rawRepositorySpacePoiCount: repositorySpacePois.length,
-      rawPoiTypeCounts: countByValue(pois, (poi) => poi.type),
-      rawPoiGroupCounts: countByValue(pois, (poi) => poi.poiGroup),
-      adaptedPoiCount: adaptedPois.length,
-      adaptedCategoryCounts: countByValue(adaptedPois, (poi) => poi.primaryCategory),
-      adaptedPoiCategoryCount: adaptedPois.filter((poi) => poi.primaryCategory === 'poi').length,
+      canonicalPoiCount: canonicalPois.length,
+      canonicalCategoryCounts: countByValue(canonicalPois, (poi) => poi.primaryCategory.id),
+      canonicalPoiCategoryCount: canonicalPois.filter((poi) => poi.primaryCategory.id === 'poi').length,
      renderPoiCount: renderPois.length,
-      renderPoiCategoryCount: renderPois.filter((poi) => poi.primaryCategory === 'poi').length,
-      repositoryDroppedCategoryCounts: countDroppedRenderPoiCategories(adaptedPois, renderPois)
+      renderPoiCategoryCount: renderPois.filter((poi) => poi.primaryCategory === 'poi').length
    })
-    warnSgsGuideModelDiagnostics('floor render POI diagnostics', {
+    logSgsGuideModelDiagnostics('floor render POI diagnostics', {
      floorId: resolvedFloorId,
      floorCode: matchedFloor.floorCode,
      poiCount: renderPois.length,
      hallPoiCount: renderHallPois.length,
      hallPoiWithPositionCount: renderHallPois.filter((poi) => Boolean(poi.positionGltf)).length,
      poiY: summarizeYValues(renderPois),
-      hallPoiY: summarizeYValues(renderHallPois),
-      fallbackHallY: floorPoiMedianY ?? null
+      hallPoiY: summarizeYValues(renderHallPois)
    })

-    if (hallDiagnostics.hallPoiWithPositionCount > 0 && !renderHallPois.length) {
-      warnSgsGuideModelDiagnostics('render POI filter removed all hall POIs', {
-        floorId: resolvedFloorId,
-        ...hallDiagnostics,
-        renderPoiCount: renderPois.length
-      })
-    }
-
    return renderPois
  }
 }
--- a/src/repositories/GuideRepository.ts
+++ b/src/repositories/GuideRepository.ts
@@ -159,6 +159,17 @@ const isVisitorSearchResult = (poi: MuseumPoi) => (
  && hasRenderablePosition(poi)
 )

+// Explicitly hidden source records must still participate in canonical-place
+// merging so a private space cannot leak through an unflagged POI duplicate.
+const isCanonicalSearchCandidate = (poi: MuseumPoi) => (
+  isPoiOnIndoorNavigableFloor(poi)
+  && hasRenderablePosition(poi)
+  && isVisitorSearchPoi({
+    ...poi,
+    visitorVisible: true
+  })
+)
+
 const normalizePlaceName = (value: string) => value
  .trim()
  .normalize('NFKC')
@@ -188,6 +199,11 @@ const canonicalMergeKeys = (poi: MuseumPoi) => {
    keys.push(`space:${poi.floorId}:${linkedSpace}:${categoryId || 'other'}`)
  }

+  const sourcePlaceId = poi.sourcePlaceId?.trim()
+  if (sourcePlaceId) {
+    keys.push(`place:${poi.floorId}:${categoryId || 'other'}:${sourcePlaceId}`)
+  }
+
  const normalizedName = normalizePlaceName(poi.name)
  const location = positionKey(poi)
  // A space, regular POI, and business POI can describe the same visitor
@@ -246,7 +262,10 @@ const mergeCanonicalPoi = (left: MuseumPoi, right: MuseumPoi) => {
    spaceId: primary.spaceId || secondary.spaceId,
    sourceSpaceId: primary.sourceSpaceId || secondary.sourceSpaceId,
    sourcePlaceId: primary.sourcePlaceId || secondary.sourcePlaceId,
-    entrances: primary.entrances || secondary.entrances
+    entrances: primary.entrances || secondary.entrances,
+    visitorVisible: primary.visitorVisible === false || secondary.visitorVisible === false
+      ? false
+      : primary.visitorVisible ?? secondary.visitorVisible
  }
 }

@@ -254,11 +273,11 @@ const mergeCanonicalPoi = (left: MuseumPoi, right: MuseumPoi) => {
 * Search queries return a single map-renderable representation of each real
 * visitor place. Source collections remain intact for the renderer itself.
 */
-const mergeCanonicalSearchPois = (pois: MuseumPoi[]) => {
+export const canonicalizeVisitorSearchPois = (pois: MuseumPoi[]) => {
  const canonicalByKey = new Map<string, MuseumPoi>()

  pois
-    .filter(isVisitorSearchResult)
+    .filter(isCanonicalSearchCandidate)
    .forEach((poi) => {
      const keys = canonicalMergeKeys(poi)
      if (!keys.length) keys.push(`poi:${poi.id}`)
@@ -282,10 +301,11 @@ const mergeCanonicalSearchPois = (pois: MuseumPoi[]) => {
    })

  return dedupePoisById(Array.from(canonicalByKey.values()))
+    .filter(isVisitorSearchResult)
 }

 const mergeSearchablePois = (pois: MuseumPoi[], spacePoints: MuseumPoi[]) => (
-  mergeCanonicalSearchPois([
+  canonicalizeVisitorSearchPois([
    ...pois,
    ...spacePoints
  ])
@@ -426,7 +446,7 @@ export class StaticGuideRepository implements GuideRepository {
      this.listPois(),
      this.listSpacePoints()
    ])
-    this.visitorSearchPoolCache = mergeCanonicalSearchPois([
+    this.visitorSearchPoolCache = canonicalizeVisitorSearchPois([
      ...pois,
      ...spacePoints
    ])
@@ -470,8 +490,8 @@ export class StaticGuideRepository implements GuideRepository {
  }

  async getPoiById(id: string) {
-    const pois = await this.listPois()
-    return pois.find((poi) => poi.id === id) || findPoiByNavIdNameFallback(pois, id)
+    const visitorPois = (await this.listPois()).filter(isVisitorSearchPoi)
+    return visitorPois.find((poi) => poi.id === id) || findPoiByNavIdNameFallback(visitorPois, id)
  }

  async searchPois(keyword = '', floorId?: string) {
@@ -735,7 +755,7 @@ export class SgsSdkGuideRepository implements GuideRepository {
      sourceFailures.push(error)
    }

-    const searchPool = mergeCanonicalSearchPois([
+    const searchPool = canonicalizeVisitorSearchPois([
      ...pois,
      ...spacePoints
    ])
@@ -796,6 +816,7 @@ export class SgsSdkGuideRepository implements GuideRepository {
      ])
      const direct = directPois
        .map((poi) => toMuseumPoiFromSgs(poi, manifest.floors))
+        .filter(isVisitorSearchPoi)
        .find((poi) => poi.id === normalizedId || getPoiSourceLookupIdentity(normalizedId) === poi.spaceId || getPoiSourceLookupIdentity(normalizedId) === poi.sourceSpaceId)
      if (direct) return direct
    } catch (error) {
--- a/tests/unit/GuideRepositorySearch.spec.ts
+++ b/tests/unit/GuideRepositorySearch.spec.ts
@@ -5,7 +5,11 @@ import {
 } from '@/domain/poiCategories'
 import type { SgsSdkApiProvider, SgsSdkManifestPayload } from '@/data/providers/sgsSdkApiProvider'
 import type { StaticNavAssetsProvider } from '@/data/providers/staticNavAssetsProvider'
-import { SgsSdkGuideRepository, StaticGuideRepository } from '@/repositories/GuideRepository'
+import {
+  canonicalizeVisitorSearchPois,
+  SgsSdkGuideRepository,
+  StaticGuideRepository
+} from '@/repositories/GuideRepository'
 import {
  SgsSdkGuideModelRepository,
  StaticGuideModelRepository
@@ -40,7 +44,17 @@ const floorSpaces = [
  { id: 'space-hall', name: '地球展厅', type: 'exhibition_hall', floorId: 'L1', center: { x: 1, y: 12, z: 1 } },
  { id: 'space-cinema', name: '穹幕影院', type: 'theater', floorId: 'L1', center: { x: 2, y: 12, z: 2 } },
  { id: 'space-dining', name: '餐饮区', type: 'restaurant', floorId: 'L1', center: { x: 3, y: 12, z: 3 } },
-  { id: 'space-shopping', name: '文创商店', type: 'commercial', floorId: 'L1', center: { x: 4, y: 12, z: 4 } }
+  { id: 'space-shopping', name: '文创商店', type: 'commercial', floorId: 'L1', center: { x: 4, y: 12, z: 4 } },
+  { id: 'space-private-tea', name: '茶水间', type: 'service_space', floorId: 'L1', center: { x: 5, y: 12, z: 5 } },
+  { id: 'space-private-vip', name: '贵宾接待区', type: 'service_space', floorId: 'L1', center: { x: 6, y: 12, z: 6 } },
+  {
+    id: 'space-public-rest',
+    name: '游客休息区',
+    type: 'service_space',
+    floorId: 'L1',
+    center: { x: 7, y: 12, z: 7 },
+    visitorVisible: true
+  }
 ]

 const floorPois = [
@@ -120,17 +134,25 @@ describe('GuideRepository visitor search contracts', () => {
    const provider = createSgsProvider()
    const repository = new SgsSdkGuideRepository(provider)

-    const [defaultResults, availability] = await Promise.all([
+    const [defaultResults, availability, privateKeyword, publicKeyword] = await Promise.all([
      repository.listDestinationPois('L1'),
-      repository.getQuickFindCategoryAvailability('L1')
+      repository.getQuickFindCategoryAvailability('L1'),
+      repository.searchPois('茶水间', 'L1'),
+      repository.searchPois('游客休息区', 'L1')
    ])

    expect(defaultResults.map((poi) => poi.id)).toEqual(expect.arrayContaining([
      'hall-space-hall',
      'hall-space-cinema',
      'space-space-dining',
-      'space-space-shopping'
+      'space-space-shopping',
+      'space-space-public-rest'
    ]))
+    for (const privatePoiId of ['space-space-private-tea', 'space-space-private-vip']) {
+      expect(defaultResults.map((poi) => poi.id)).not.toContain(privatePoiId)
+    }
+    expect(privateKeyword).toEqual([])
+    expect(publicKeyword.map((poi) => poi.id)).toEqual(['space-space-public-rest'])
    expect(defaultResults.map((poi) => poi.id)).not.toEqual(expect.arrayContaining([
      'restroom',
      'elevator',
@@ -160,9 +182,13 @@ describe('GuideRepository visitor search contracts', () => {
    // survive model marker deduplication.
    expect(renderPoiIds.has('restroom')).toBe(true)
    expect(renderPoiIds.has('elevator')).toBe(true)
+    expect(renderPoiIds.has('space-space-public-rest')).toBe(true)
    for (const hiddenPoiId of ['door', 'anchor', 'route-node', 'guide-stop']) {
      expect(renderPoiIds.has(hiddenPoiId)).toBe(false)
    }
+    for (const privatePoiId of ['space-space-private-tea', 'space-space-private-vip']) {
+      expect(renderPoiIds.has(privatePoiId)).toBe(false)
+    }
    const quickResultIds = (await Promise.all(allQuickCategoryIds.map((categoryId) => (
      repository.listQuickFindPois(categoryId, 'L1')
    )))).flat().map((poi) => poi.id)
@@ -188,6 +214,115 @@ describe('GuideRepository visitor search contracts', () => {
    expect(hiddenKeyword).toEqual([])
  })

+  it('does not resolve private direct IDs outside the visitor search pool', async () => {
+    const repository = new SgsSdkGuideRepository(createSgsProvider({
+      queryPois: vi.fn().mockResolvedValue([{
+        id: 'private-direct-space',
+        name: '茶水间',
+        type: 'service_space',
+        floorId: 'L1',
+        visitorVisible: false,
+        position: { x: 30, y: 12, z: 30 }
+      }])
+    }))
+
+    await expect(repository.getPoiById('private-direct-space')).resolves.toBeNull()
+  })
+
+  it('keeps private and structural space duplicates out of search lists and map markers', async () => {
+    const provider = createSgsProvider({
+      getFloorPois: vi.fn().mockResolvedValue([
+        {
+          id: 'poi-private-dining',
+          name: '西侧餐饮区',
+          type: 'restaurant',
+          floorId: 'L1',
+          spatialAreaId: 'space-private-dining',
+          position: { x: 30, y: 12, z: 30 }
+        },
+        {
+          id: 'poi-service-space',
+          name: '服务空间',
+          type: 'service_space',
+          floorId: 'L1',
+          position: { x: 31, y: 12, z: 31 }
+        }
+      ]),
+      getFloorBusinessPois: vi.fn().mockResolvedValue([]),
+      getFloorSpaces: vi.fn().mockResolvedValue([
+        {
+          id: 'space-private-dining',
+          name: '西侧餐饮区',
+          type: 'restaurant',
+          floorId: 'L1',
+          visitorVisible: false,
+          center: { x: 30, y: 12, z: 30 }
+        },
+        {
+          id: 'space-private-cinema',
+          name: '私享影院',
+          type: 'theater',
+          floorId: 'L1',
+          visitorVisible: false,
+          center: { x: 32, y: 12, z: 32 }
+        },
+        {
+          id: 'space-route-node',
+          name: '导航区域',
+          type: 'navigable_place',
+          floorId: 'L1',
+          center: { x: 33, y: 12, z: 33 }
+        }
+      ]),
+      getNavigablePlaces: vi.fn().mockResolvedValue([])
+    })
+    const repository = new SgsSdkGuideRepository(provider)
+    const modelRepository = new SgsSdkGuideModelRepository(provider, repository)
+
+    const [defaultResults, dining, cinema, privateKeyword, serviceKeyword, structuralKeyword, renderPois] = await Promise.all([
+      repository.listDestinationPois('L1'),
+      repository.listQuickFindPois('dining', 'L1'),
+      repository.listQuickFindPois('cinema', 'L1'),
+      repository.searchPois('西侧餐饮区', 'L1'),
+      repository.searchPois('服务空间', 'L1'),
+      repository.searchPois('导航区域', 'L1'),
+      modelRepository.loadFloorPois('L1')
+    ])
+
+    expect(defaultResults).toEqual([])
+    expect(dining).toEqual([])
+    expect(cinema).toEqual([])
+    expect(privateKeyword).toEqual([])
+    expect(serviceKeyword).toEqual([])
+    expect(structuralKeyword).toEqual([])
+    expect(renderPois).toEqual([])
+  })
+
+  it('merges source-place duplicates before returning canonical visitor IDs', () => {
+    const basePoi = {
+      floorId: 'L1',
+      floorLabel: '1F',
+      primaryCategory: { id: 'space_restaurant', label: '餐饮', iconType: 'restaurant' },
+      categories: [{ id: 'space_restaurant', label: '餐饮', iconType: 'restaurant' }],
+      positionGltf: [40, 12, 40] as [number, number, number],
+      accessible: false,
+      kind: 'facility' as const,
+      sourcePlaceId: 'place-cafe'
+    }
+
+    const results = canonicalizeVisitorSearchPois([
+      { ...basePoi, id: 'poi-cafe-a', name: '中庭咖啡' },
+      {
+        ...basePoi,
+        id: 'poi-cafe-b',
+        name: '中庭咖啡取餐台',
+        positionGltf: [41, 12, 41]
+      }
+    ])
+
+    expect(results.map((poi) => poi.id)).toEqual(['poi-cafe-a'])
+  })
+
  it('deduplicates co-located sources when they do not provide a shared spatial area ID', async () => {
    const repository = new SgsSdkGuideRepository(createSgsProvider({
      getFloorPois: vi.fn().mockResolvedValue([{
@@ -348,6 +483,24 @@ describe('GuideRepository visitor search contracts', () => {
          primaryCategoryZh: '基础服务设施',
          iconType: 'restroom',
          positionGltf: position(4)
+        },
+        {
+          id: 'static-vip-reception',
+          name: '贵宾接待区',
+          floorId: 'L1',
+          primaryCategory: 'basic_service_facility',
+          primaryCategoryZh: '基础服务设施',
+          iconType: 'restroom',
+          positionGltf: position(5)
+        },
+        {
+          id: 'static-vip-restroom',
+          name: '贵宾卫生间',
+          floorId: 'L1',
+          primaryCategory: 'basic_service_facility',
+          primaryCategoryZh: '基础服务设施',
+          iconType: 'restroom',
+          positionGltf: position(6)
        }
      ])
    } as unknown as StaticNavAssetsProvider
@@ -362,6 +515,10 @@ describe('GuideRepository visitor search contracts', () => {
    await expect(repository.searchPois('洗手间', 'L1')).resolves.toMatchObject([
      { id: 'static-restroom' }
    ])
+    await expect(repository.searchPois('茶水间', 'L1')).resolves.toEqual([])
+    await expect(repository.searchPois('贵宾', 'L1')).resolves.toEqual([])
+    await expect(repository.getPoiById('static-tea-room')).resolves.toBeNull()
+    await expect(repository.getPoiById('static-vip-restroom')).resolves.toBeNull()
    await expect(repository.searchPois('服务', 'L1')).resolves.toEqual([
      expect.objectContaining({ id: 'static-service-desk' })
    ])
@@ -397,6 +554,24 @@ describe('GuideRepository visitor search contracts', () => {
          primaryCategoryZh: '讲解点',
          iconType: 'guide',
          positionGltf: position(2)
+        },
+        {
+          id: 'static-private-tea',
+          name: '茶水间',
+          floorId: 'L1',
+          primaryCategory: 'basic_service_facility',
+          primaryCategoryZh: '基础服务设施',
+          iconType: 'restroom',
+          positionGltf: position(3)
+        },
+        {
+          id: 'static-vip-restroom',
+          name: '贵宾卫生间',
+          floorId: 'L1',
+          primaryCategory: 'basic_service_facility',
+          primaryCategoryZh: '基础服务设施',
+          iconType: 'restroom',
+          positionGltf: position(4)
        }
      ])
    } as unknown as StaticNavAssetsProvider
--- a/tests/unit/IndexPoiSearchFlow.spec.ts
+++ b/tests/unit/IndexPoiSearchFlow.spec.ts
@@ -18,6 +18,7 @@ const testState = vi.hoisted(() => ({
  searchRestoreCount: 0,
  searchCollapseAfterDetailCount: 0,
  searchResetCount: 0,
+  floorSwitchRequests: [] as string[],
  onShowHandler: null as null | (() => Promise<void> | void),
  halls: [] as Array<{ id: string; poiId?: string; location?: { poiId?: string }; name: string }>,
  hallResolutionPromises: [] as Array<Promise<Array<{
@@ -102,7 +103,7 @@ const GuideMapShellStub = defineComponent({
    visiblePoiIds: { type: Array, default: null },
    targetFocusRequest: { type: Object, default: null }
  },
-  emits: ['floor-change', 'poi-click', 'selection-clear', 'indoor-view-change'],
+  emits: ['floor-change', 'floor-request', 'floor-switch-failed', 'initial-model-ready', 'poi-click', 'selection-clear', 'indoor-view-change'],
  setup() {
    onMounted(() => {
      testState.mapMountCount += 1
@@ -113,6 +114,10 @@ const GuideMapShellStub = defineComponent({
    return {}
  },
  methods: {
+    switchFloor(floorId: string) {
+      testState.floorSwitchRequests.push(floorId)
+      return Promise.resolve()
+    },
    resetToViewBaseline(options: {
      view: 'overview' | 'floor'
      floorId?: string
@@ -217,6 +222,7 @@ beforeEach(() => {
  testState.searchRestoreCount = 0
  testState.searchCollapseAfterDetailCount = 0
  testState.searchResetCount = 0
+  testState.floorSwitchRequests = []
  testState.onShowHandler = null
  testState.halls = []
  testState.hallResolutionPromises = []
@@ -355,7 +361,7 @@ describe('首页搜索与地图闭环', () => {
    expect(wrapper.findAll('.guide-quick-action')[0]?.text()).toBe('导览')
  })

-  it('向搜索面板传入当前楼层，并将分类结果 ID 精确传给地图', async () => {
+  it('等待渲染器提交目标楼层后，才将快捷分类结果 ID 传给地图', async () => {
    const wrapper = await mountIndex()
    const search = wrapper.getComponent(PoiSearchPanelStub)
    const map = wrapper.getComponent(GuideMapShellStub)
@@ -370,6 +376,13 @@ describe('首页搜索与地图闭环', () => {
    })
    await wrapper.vm.$nextTick()

+    expect(testState.floorSwitchRequests).toEqual(['L2'])
+    expect(map.props('activeFloor')).toBe('L1')
+    expect(map.props('visiblePoiIds')).toEqual([])
+
+    map.vm.$emit('floor-change', 'L2')
+    await wrapper.vm.$nextTick()
+
    expect(map.props('activeFloor')).toBe('L2')
    expect(map.props('indoorView')).toBe('floor')
    expect(map.props('visiblePoiIds')).toEqual(categoryContext.visiblePoiIds)
@@ -388,6 +401,78 @@ describe('首页搜索与地图闭环', () => {
    expect(map.props('visiblePoiIds')).toEqual([])
  })

+  it('三维模型重新以总览就绪后，不将旧单层状态误作楼层提交', async () => {
+    const wrapper = await mountIndex()
+    const search = wrapper.getComponent(PoiSearchPanelStub)
+    const map = wrapper.getComponent(GuideMapShellStub)
+
+    map.vm.$emit('floor-change', 'L1')
+    await wrapper.vm.$nextTick()
+    expect(map.props('indoorView')).toBe('floor')
+
+    map.vm.$emit('initial-model-ready', { view: 'overview', floorId: 'L1' })
+    await wrapper.vm.$nextTick()
+    expect(map.props('indoorView')).toBe('overview')
+
+    search.vm.$emit('category-mode-change', true)
+    search.vm.$emit('results-change', {
+      ...categoryContext,
+      floorId: 'L1',
+      floorLabel: '1F',
+      active: true,
+      requestId: 20
+    })
+    await wrapper.vm.$nextTick()
+
+    expect(testState.floorSwitchRequests).toEqual(['L1'])
+    expect(map.props('visiblePoiIds')).toEqual([])
+
+    map.vm.$emit('floor-change', 'L1')
+    await wrapper.vm.$nextTick()
+    expect(map.props('visiblePoiIds')).toEqual(categoryContext.visiblePoiIds)
+  })
+
+  it('忽略过期搜索结果，不允许旧楼层覆盖当前待提交地图状态', async () => {
+    const wrapper = await mountIndex()
+    const search = wrapper.getComponent(PoiSearchPanelStub)
+    const map = wrapper.getComponent(GuideMapShellStub)
+
+    search.vm.$emit('category-mode-change', true)
+    search.vm.$emit('results-change', { ...categoryContext, active: true, requestId: 8 })
+    search.vm.$emit('results-change', {
+      ...categoryContext,
+      floorId: 'L1',
+      floorLabel: '1F',
+      visiblePoiIds: ['stale-l1'],
+      active: true,
+      requestId: 7
+    })
+    await wrapper.vm.$nextTick()
+
+    expect(testState.floorSwitchRequests).toEqual(['L2'])
+    map.vm.$emit('floor-change', 'L2')
+    await wrapper.vm.$nextTick()
+    expect(map.props('visiblePoiIds')).toEqual(categoryContext.visiblePoiIds)
+  })
+
+  it('楼层切换失败时清空快捷分类标记，重试提交后恢复与列表一致的 ID', async () => {
+    const wrapper = await mountIndex()
+    const search = wrapper.getComponent(PoiSearchPanelStub)
+    const map = wrapper.getComponent(GuideMapShellStub)
+
+    search.vm.$emit('category-mode-change', true)
+    search.vm.$emit('results-change', { ...categoryContext, active: true, requestId: 12 })
+    await wrapper.vm.$nextTick()
+    map.vm.$emit('floor-switch-failed', { floorId: 'L2', floorLabel: '2F' })
+    await wrapper.vm.$nextTick()
+    expect(map.props('activeFloor')).toBe('L1')
+    expect(map.props('visiblePoiIds')).toEqual([])
+
+    map.vm.$emit('floor-change', 'L2')
+    await wrapper.vm.$nextTick()
+    expect(map.props('visiblePoiIds')).toEqual(categoryContext.visiblePoiIds)
+  })
+
  it('楼层数据按高到低返回时，首次进入仍将 1F 作为自动缩放的默认目标', async () => {
    const originalFloors = [...floors]
    floors.splice(0, floors.length,
@@ -417,6 +502,8 @@ describe('首页搜索与地图闭环', () => {
      ...categoryContext,
      active: true
    })
+    map.vm.$emit('floor-change', 'L2')
+    await wrapper.vm.$nextTick()
    search.vm.$emit('result-tap', poi, categoryContext)
    await flushPromises()

@@ -486,6 +573,8 @@ describe('首页搜索与地图闭环', () => {

    search.vm.$emit('category-mode-change', true)
    search.vm.$emit('results-change', { ...categoryContext, active: true })
+    map.vm.$emit('floor-change', 'L2')
+    await wrapper.vm.$nextTick()
    search.vm.$emit('result-tap', poi, categoryContext)
    await flushPromises()

--- a/tests/unit/PoiSearchPanel.spec.ts
+++ b/tests/unit/PoiSearchPanel.spec.ts
@@ -149,6 +149,7 @@ const lastResultState = (wrapper: ReturnType<typeof mount>) => (
    categoryId: string
    keyword: string
    pending?: boolean
+    requestId?: number
  }
 )

@@ -323,6 +324,36 @@ describe('PoiSearchPanel 搜索状态契约', () => {
    wrapper.unmount()
  })

+  it('首页分类结果在组件重挂载后仍发送递增的跨组件版本号', async () => {
+    const firstWrapper = mount(PoiSearchPanel, {
+      props: {
+        variant: 'home',
+        currentFloorId: 'floor-1',
+        currentFloorLabel: '1F'
+      }
+    })
+    await flushMountedSearch()
+    await firstWrapper.get('[data-testid="poi-category-restroom"]').trigger('tap')
+    await flushMountedSearch()
+    const firstRequestId = lastResultState(firstWrapper).requestId
+    firstWrapper.unmount()
+
+    const secondWrapper = mount(PoiSearchPanel, {
+      props: {
+        variant: 'home',
+        currentFloorId: 'floor-1',
+        currentFloorLabel: '1F'
+      }
+    })
+    await flushMountedSearch()
+    await secondWrapper.get('[data-testid="poi-category-restroom"]').trigger('tap')
+    await flushMountedSearch()
+
+    expect(firstRequestId).toEqual(expect.any(Number))
+    expect(lastResultState(secondWrapper).requestId).toBeGreaterThan(firstRequestId as number)
+    secondWrapper.unmount()
+  })
+
  it('首页快捷分类请求期间清空列表并下发 pending 空地图 ID', async () => {
    const initialState = createSearchState()
    const deferredCategory = createDeferred<GuidePoiSearchViewState>()
--- a/tests/unit/finalizeH5BuildPolicy.spec.ts
+++ b/tests/unit/finalizeH5BuildPolicy.spec.ts
@@ -0,0 +1,86 @@
+import { createRequire } from 'node:module'
+import { describe, expect, it, vi } from 'vitest'
+
+const require = createRequire(import.meta.url)
+const {
+  isTextBuildFile,
+  resolveH5BuildPolicy,
+  tencentMapKeyPlaceholder
+} = require('../../scripts/finalize-h5-build-policy.cjs') as {
+  isTextBuildFile: (filePath: string) => boolean
+  resolveH5BuildPolicy: (options: {
+    args?: string[]
+    projectRoot: string
+    environment?: Record<string, string | undefined>
+    loadProductionEnv?: (root: string) => Record<string, string | undefined>
+  }) => {
+    allowPlaceholder: boolean
+    requireTencentMapKey: boolean
+    tencentMapKey: string
+  }
+  tencentMapKeyPlaceholder: string
+}
+
+const projectRoot = 'C:/museum-guide'
+const validTencentMapKey = 'ABCDE-FGHIJ-KLMNO-PQRST-UVWXY-12345'
+
+describe('finalize H5 build policy', () => {
+  it('keeps test builds isolated from production map credentials', () => {
+    const loadProductionEnv = vi.fn(() => ({
+      VITE_TENCENT_MAP_KEY: validTencentMapKey
+    }))
+
+    expect(resolveH5BuildPolicy({
+      args: ['--allow-placeholder'],
+      projectRoot,
+      environment: { VITE_TENCENT_MAP_KEY: validTencentMapKey },
+      loadProductionEnv
+    })).toEqual({
+      allowPlaceholder: true,
+      requireTencentMapKey: false,
+      tencentMapKey: ''
+    })
+    expect(loadProductionEnv).not.toHaveBeenCalled()
+  })
+
+  it('loads a well-formed production key only for the production gate', () => {
+    const loadProductionEnv = vi.fn(() => ({
+      VITE_TENCENT_MAP_KEY: validTencentMapKey
+    }))
+
+    expect(resolveH5BuildPolicy({
+      args: ['--require-tencent-map-key'],
+      projectRoot,
+      environment: {},
+      loadProductionEnv
+    })).toEqual({
+      allowPlaceholder: false,
+      requireTencentMapKey: true,
+      tencentMapKey: validTencentMapKey
+    })
+    expect(loadProductionEnv).toHaveBeenCalledWith(projectRoot)
+  })
+
+  it('rejects conflicting flags, placeholders, and malformed production keys', () => {
+    expect(() => resolveH5BuildPolicy({
+      args: ['--allow-placeholder', '--require-tencent-map-key'],
+      projectRoot,
+      environment: {}
+    })).toThrow('cannot require a Tencent map key')
+
+    for (const key of ['', tencentMapKeyPlaceholder, 'fake-key']) {
+      expect(() => resolveH5BuildPolicy({
+        args: ['--require-tencent-map-key'],
+        projectRoot,
+        environment: { VITE_TENCENT_MAP_KEY: key },
+        loadProductionEnv: () => ({})
+      })).toThrow('well-formed non-placeholder')
+    }
+  })
+
+  it('scans source maps as text build artifacts', () => {
+    expect(isTextBuildFile('assets/index.js.map')).toBe(true)
+    expect(isTextBuildFile('assets/index.js')).toBe(true)
+    expect(isTextBuildFile('assets/model.glb')).toBe(false)
+  })
+})
--- a/tests/unit/navAssetsAdapter.spec.ts
+++ b/tests/unit/navAssetsAdapter.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { toMuseumPoi } from '@/data/adapters/navAssetsAdapter'
-import { resolvePoiCategory } from '@/domain/poiCategories'
+import { isVisitorSearchPoi, resolvePoiCategory } from '@/domain/poiCategories'
 import type { StaticNavPoiPayload } from '@/data/providers/staticNavAssetsProvider'

 const createStaticPoi = (name: string, iconType = 'elevator'): StaticNavPoiPayload => ({
@@ -52,10 +52,23 @@ describe('static nav POI adapter', () => {
    const serviceDesk = toMuseumPoi(createStaticPoi('服务台', 'restroom'))
    const locker = toMuseumPoi(createStaticPoi('存包处', 'restroom'))
    const teaRoom = toMuseumPoi(createStaticPoi('茶水间', 'restroom'))
+    const vipReception = toMuseumPoi(createStaticPoi('贵宾接待区', 'restroom'))
+    const vipRestroom = toMuseumPoi(createStaticPoi('贵宾卫生间', 'restroom'))

    expect(resolvePoiCategory(serviceDesk)?.id).toBe('service-center')
    expect(resolvePoiCategory(locker)?.id).toBe('service-center')
    expect(resolvePoiCategory(teaRoom)).toBeNull()
+    expect(teaRoom.visitorVisible).toBe(false)
+    expect(vipReception.visitorVisible).toBe(false)
+    expect(vipRestroom.visitorVisible).toBe(false)
+    expect(toMuseumPoi({
+      ...createStaticPoi('茶水间', 'restroom'),
+      visitorVisible: true
+    }).visitorVisible).toBe(true)
+    expect(toMuseumPoi({
+      ...createStaticPoi('贵宾卫生间', 'restroom'),
+      visitorVisible: true
+    }).visitorVisible).toBe(true)
  })

  it('splits generic touring fallback records into their visitor-facing semantic kinds', () => {
@@ -73,4 +86,19 @@ describe('static nav POI adapter', () => {
    })
    expect(resolvePoiCategory(ticketOffice)?.id).toBe('ticket-office')
  })
+
+  it('keeps a hall visible when its secondary category describes an entrance', () => {
+    const hall = toMuseumPoi(createTouringPoi('地球展厅'))
+    hall.kind = 'hall'
+    hall.categories = [
+      hall.primaryCategory,
+      {
+        id: 'exhibition_hall_entrance',
+        label: '展厅出入口',
+        iconType: 'hall_entrance'
+      }
+    ]
+
+    expect(isVisitorSearchPoi(hall)).toBe(true)
+  })
 })
Author	SHA1	Message	Date
cxk	dd29ead041	docs: 更新正式环境部署手册 Some checks are pending CI / verify (push) Waiting to run Details	2026-07-21 15:31:21 +08:00
cxk	b90c58451c	修复首页快捷入口与三维点位同步 Some checks failed CI / verify (push) Has been cancelled Details	2026-07-21 00:40:06 +08:00
cxk	1f89e8b3e0	修复导览点位可见性与构建门禁	2026-07-20 23:54:19 +08:00