From 127461dd6005e5f2a530b60ff227b2dd178f174a Mon Sep 17 00:00:00 2001
From: lyf <2514544224@qq.com>
Date: Sun, 19 Jul 2026 15:46:51 +0800
Subject: [PATCH] =?UTF-8?q?=E4=BF=AE=E5=A4=8D=E5=B1=95=E5=8E=85=E5=88=97?=
 =?UTF-8?q?=E8=A1=A8=E5=B5=8C=E5=85=A5=E8=BF=94=E5=9B=9E=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/components/explain/ExplainHallSelect.vue |  8 ++--
 src/pages/explain/list.vue                   |  1 +
 tests/e2e/explain-hall-page.spec.ts          | 49 ++++++++++++++++++++
 tests/unit/ExplainHallSelect.spec.ts         | 38 +++++++++++++--
 tests/unit/ExplainListNavigation.spec.ts     | 19 ++++++++
 5 files changed, 109 insertions(+), 6 deletions(-)

diff --git a/src/components/explain/ExplainHallSelect.vue b/src/components/explain/ExplainHallSelect.vue
index 1164920..3564ff8 100644
--- a/src/components/explain/ExplainHallSelect.vue
+++ b/src/components/explain/ExplainHallSelect.vue
@@ -1,5 +1,5 @@
 <template>
-  <view class="explain-hall-select" :class="{ 'host-navigation': shouldUseHostNavigation }">
+  <view class="explain-hall-select" :class="{ 'host-navigation': shouldUseHostNavigation && !showInternalHeader }">
     <view v-if="showInternalHeader" class="explain-page-header">
       <view class="header-back" @tap="handleBack">
         <text class="header-back-icon">‹</text>
@@ -167,6 +167,7 @@ const props = withDefaults(defineProps<{
   hasMore?: boolean
   error?: string
   loadMoreError?: string
+  forceInternalHeader?: boolean
 }>(), {
   halls: () => [],
   guideStops: () => [],
@@ -176,7 +177,8 @@ const props = withDefaults(defineProps<{
   loadingMore: false,
   hasMore: false,
   error: '',
-  loadMoreError: ''
+  loadMoreError: '',
+  forceInternalHeader: false
 })
 
 const emit = defineEmits<{
@@ -218,7 +220,7 @@ const hallCardThemeMap: Record<string, { color: string; englishName: string }> =
 
 const filteredHalls = computed(() => props.halls)
 const shouldUseHostNavigation = computed(() => isEmbeddedInWechatMiniProgram())
-const showInternalHeader = computed(() => !shouldUseHostNavigation.value)
+const showInternalHeader = computed(() => props.forceInternalHeader || !shouldUseHostNavigation.value)
 const headerTitle = computed(() => {
   if (props.stage === 'stop') return props.selectedHallName || '讲解对象'
   return '展厅讲解'
diff --git a/src/pages/explain/list.vue b/src/pages/explain/list.vue
index 1695d4d..b04910e 100644
--- a/src/pages/explain/list.vue
+++ b/src/pages/explain/list.vue
@@ -10,6 +10,7 @@
       <ExplainHallSelect
         :halls="explainHallItems"
         stage="hall"
+        force-internal-header
         :loading="explainLoading"
         :error="explainError"
         @hall-click="handleExplainHallClick"
diff --git a/tests/e2e/explain-hall-page.spec.ts b/tests/e2e/explain-hall-page.spec.ts
index 90672a8..d773b2f 100644
--- a/tests/e2e/explain-hall-page.spec.ts
+++ b/tests/e2e/explain-hall-page.spec.ts
@@ -65,3 +65,52 @@ test('hall goes directly to paged guide objects without outline requests', async
   expect(requests.some((url) => url.includes('/outlines'))).toBe(false)
   expect(requests.filter((url) => url.includes('/stops/page')).map((url) => new URL(url).searchParams.get('pageNo'))).toEqual(['1', '2'])
 })
+
+test('embedded hall list exposes an H5 return control that keeps host markers', async ({ page }) => {
+  await page.route('**/app-api/gis/guide/catalog/**', async (route) => {
+    const url = route.request().url()
+    if (url.includes('/catalog/halls?')) {
+      await route.fulfill({ json: { code: 0, data: [{ id: 'hall-1', name: '恐龙厅', floorId: 'L1', stopCount: 1 }] } })
+      return
+    }
+    await route.fulfill({ json: { code: 0, data: {} } })
+  })
+
+  await page.goto('/#/pages/explain/list?embedded=wechat-mini-program&weapp=1')
+  const back = page.locator('.header-back')
+  await expect(back).toHaveCount(1)
+  await expect(back).toBeVisible()
+  await expect(page.locator('.hall-overview-card')).toHaveCount(1)
+  for (const width of [375, 390, 430]) {
+    await page.setViewportSize({ width, height: 844 })
+    const layout = await page.locator('.explain-hall-select').evaluate((container) => {
+      const header = container.querySelector<HTMLElement>('.explain-page-header')
+      const card = container.querySelector<HTMLElement>('.hall-overview-card')
+      if (!header || !card) throw new Error('missing header or hall card')
+      const headerRect = header.getBoundingClientRect()
+      const cardRect = card.getBoundingClientRect()
+      return {
+        clientWidth: container.clientWidth,
+        scrollWidth: container.scrollWidth,
+        headerBottom: headerRect.bottom,
+        cardTop: cardRect.top
+      }
+    })
+    expect(layout.scrollWidth).toBeLessThanOrEqual(layout.clientWidth)
+    expect(layout.cardTop).toBeGreaterThanOrEqual(layout.headerBottom)
+  }
+  await back.click()
+  await expect(page).toHaveURL(/#\/\?tab=guide&embedded=wechat-mini-program&weapp=1$/)
+})
+
+test('ordinary H5 hall list return reaches the guide home', async ({ page }) => {
+  await page.route('**/app-api/gis/guide/catalog/**', (route) => (
+    route.fulfill({ json: { code: 0, data: [] } })
+  ))
+
+  await page.goto('/#/pages/explain/list')
+  const back = page.locator('.header-back')
+  await expect(back).toHaveCount(1)
+  await back.click()
+  await expect(page).toHaveURL(/#\/\?tab=guide$/)
+})
diff --git a/tests/unit/ExplainHallSelect.spec.ts b/tests/unit/ExplainHallSelect.spec.ts
index d5bc072..46e22aa 100644
--- a/tests/unit/ExplainHallSelect.spec.ts
+++ b/tests/unit/ExplainHallSelect.spec.ts
@@ -1,14 +1,46 @@
 // @vitest-environment happy-dom
 
 import { mount } from '@vue/test-utils'
-import { describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import ExplainHallSelect from '@/components/explain/ExplainHallSelect.vue'
 
-vi.mock('@/utils/hostEnvironment', () => ({
-  isEmbeddedInWechatMiniProgram: () => false
+const hostEnvironmentMocks = vi.hoisted(() => ({
+  embeddedInWechatMiniProgram: false
 }))
 
+vi.mock('@/utils/hostEnvironment', () => ({
+  isEmbeddedInWechatMiniProgram: () => hostEnvironmentMocks.embeddedInWechatMiniProgram
+}))
+
+afterEach(() => {
+  hostEnvironmentMocks.embeddedInWechatMiniProgram = false
+})
+
 describe('讲解展厅选择列表', () => {
+  it('微信嵌入态独立页面可强制显示 H5 返回入口，且不使用宿主导航布局', async () => {
+    hostEnvironmentMocks.embeddedInWechatMiniProgram = true
+    const wrapper = mount(ExplainHallSelect, {
+      props: {
+        forceInternalHeader: true
+      }
+    })
+
+    expect(wrapper.findAll('.explain-page-header')).toHaveLength(1)
+    expect(wrapper.findAll('.header-back')).toHaveLength(1)
+    expect(wrapper.classes()).not.toContain('host-navigation')
+
+    await wrapper.get('.header-back').trigger('tap')
+    expect(wrapper.emitted('back')).toEqual([[]])
+  })
+
+  it('微信嵌入态未强制时保留宿主导航布局，保护首页讲解 Tab', () => {
+    hostEnvironmentMocks.embeddedInWechatMiniProgram = true
+    const wrapper = mount(ExplainHallSelect)
+
+    expect(wrapper.find('.explain-page-header').exists()).toBe(false)
+    expect(wrapper.classes()).toContain('host-navigation')
+  })
+
   it('展厅卡片只显示讲解对象数量，不暴露业务单元契约', async () => {
     const wrapper = mount(ExplainHallSelect, {
       props: {
diff --git a/tests/unit/ExplainListNavigation.spec.ts b/tests/unit/ExplainListNavigation.spec.ts
index 53846f7..be82d23 100644
--- a/tests/unit/ExplainListNavigation.spec.ts
+++ b/tests/unit/ExplainListNavigation.spec.ts
@@ -42,6 +42,9 @@ const GuidePageFrameStub = defineComponent({
 
 const ExplainHallSelectStub = defineComponent({
   name: 'ExplainHallSelect',
+  props: {
+    forceInternalHeader: Boolean
+  },
   emits: ['back'],
   template: '<button data-testid="explain-list-back" @click="$emit(\'back\')">返回</button>'
 })
@@ -103,6 +106,22 @@ describe('讲解展厅列表返回', () => {
     wrapper.unmount()
   })
 
+  it('独立页在微信嵌入态强制提供 H5 返回，并保留宿主识别参数', async () => {
+    hostEnvironmentMocks.embeddedInWechatMiniProgram = true
+    window.location.hash = '#/pages/explain/list?embedded=wechat-mini-program&weapp=1'
+    window.history.replaceState({}, '', window.location.href)
+    const wrapper = mountExplainList()
+
+    expect(wrapper.getComponent(ExplainHallSelectStub).props('forceInternalHeader')).toBe(true)
+    await wrapper.get('[data-testid="explain-list-back"]').trigger('click')
+
+    expect(uni.navigateBack).not.toHaveBeenCalled()
+    expect(uni.reLaunch).toHaveBeenCalledWith(expect.objectContaining({
+      url: '/pages/index/index?tab=guide&embedded=wechat-mini-program&weapp=1'
+    }))
+    wrapper.unmount()
+  })
+
   it('上一页不是首页时使用 reLaunch，避免回到不相关页面', async () => {
     vi.stubGlobal('getCurrentPages', vi.fn(() => [
       { route: 'pages/search/index', options: {} },