接入编号讲解后端查询

- 使用真实讲解编号解析接口替换本地演示映射 - 成功后复用现有详情页并自动播放讲解 - 增加查询状态、业务错误提示和相关测试 Made-with: Proma
2026-08-25 18:00:52 +08:00
parent 00585a7b48
commit 130f155bdf
13 changed files with 490 additions and 13 deletions
--- a/.env.development
+++ b/.env.development
@@ -25,7 +25,7 @@ VITE_PUBLIC_LEGACY_AUDIO_HOST=

 # Vite 开发服务器代理目标，只由 vite.config.ts 读取。
 # /engine 由 public/engine 本地静态资源提供，保持和大屏端一致，不再代理到地图管理端。
-DEV_PROXY_APP_API_TARGET=http://localhost:48080
+DEV_PROXY_APP_API_TARGET=https://guide.whaoyue.com:4433
 DEV_PROXY_ENGINE_TARGET=
 DEV_PROXY_SDK_TARGET=
 DEV_PROXY_MUSEUM_ASSETS_TARGET=http://1.92.206.90:9000
--- a/src/components/explain/ExplainHallSelect.vue
+++ b/src/components/explain/ExplainHallSelect.vue
@@ -33,6 +33,24 @@
      </view>

      <template v-else>
+        <view v-if="stage === 'hall'" class="code-entry-section">
+          <button class="code-entry-button" @tap="openCodeEntry">
+            <view class="code-entry-icon" aria-hidden="true">
+              <view class="headphone-band" />
+              <view class="headphone-ear left" />
+              <view class="headphone-ear right" />
+            </view>
+            <view class="code-entry-copy">
+              <text class="code-entry-title">编号讲解</text>
+              <text class="code-entry-desc">输入展品旁的编号，直接收听讲解</text>
+            </view>
+          </button>
+        </view>
+
+        <view v-if="stage === 'hall'" class="hall-section-heading">
+          <text class="hall-section-title">按展厅选择</text>
+        </view>
+
        <view v-if="stage === 'hall' && filteredHalls.length" class="hall-list hall-overview-list">
          <view
            v-for="(hall, index) in filteredHalls"
@@ -178,6 +196,45 @@
        </view>
      </template>
    </scroll-view>
+
+    <view v-if="codeEntryVisible" class="code-entry-overlay" @tap="closeCodeEntry">
+      <view class="code-entry-sheet" @tap.stop>
+        <view class="code-entry-content">
+          <text class="code-entry-sheet-title">输入讲解编号</text>
+          <text class="code-entry-sheet-desc">请输入展品旁标注的 4 位编号</text>
+          <view class="code-digit-fields" :class="{ error: codeEntryError }">
+            <view
+              v-for="index in 4"
+              :key="index"
+              class="code-digit-cell"
+              :class="{ active: codeEntryValue.length === index - 1 }"
+            >
+              <text class="code-digit-value">{{ codeEntryValue[index - 1] || '' }}</text>
+            </view>
+            <input
+              v-if="codeEntryVisible"
+              class="code-entry-native-input"
+              :value="codeEntryValue"
+              type="number"
+              inputmode="numeric"
+              confirm-type="go"
+              maxlength="4"
+              :focus="codeEntryVisible && !codeSubmitting"
+              :disabled="codeSubmitting"
+              @input="handleCodeEntryInput"
+              @confirm="submitCodeEntry"
+            />
+          </view>
+          <text v-if="codeEntryError" class="code-entry-error">{{ codeEntryError }}</text>
+          <text v-else class="code-entry-hint">请输入展品标签上的四位编号</text>
+          <button
+            class="code-entry-action primary"
+            :disabled="codeEntryValue.length !== 4 || codeSubmitting"
+            @tap="submitCodeEntry"
+          >{{ codeSubmitting ? '正在查询' : '开始讲解' }}</button>
+        </view>
+      </view>
+    </view>
  </view>
 </template>

@@ -234,6 +291,7 @@ const props = withDefaults(defineProps<{
  error?: string
  loadMoreError?: string
  forceInternalHeader?: boolean
+  codeSubmitting?: boolean
 }>(), {
  halls: () => [],
  businessUnits: () => [],
@@ -245,11 +303,13 @@ const props = withDefaults(defineProps<{
  hasMore: false,
  error: '',
  loadMoreError: '',
-  forceInternalHeader: false
+  forceInternalHeader: false,
+  codeSubmitting: false
 })

 const emit = defineEmits<{
  hallClick: [hallId: string]
+  codeSubmit: [code: string]
  businessUnitClick: [unitId: string]
  guideStopClick: [stop: ExplainGuideStopSelectItem]
  back: []
@@ -261,6 +321,9 @@ const HALL_PREVIEW_BASE = '/static/icons/halls/portal-icons'
 const HALL_PREVIEW_EAGER_COUNT = 4
 const loadedHallPreviewIds = ref(new Set<string>())
 const failedHallPreviewIds = ref(new Set<string>())
+const codeEntryVisible = ref(false)
+const codeEntryValue = ref('')
+const codeEntryError = ref('')

 const hallPreviewMap: Record<string, string> = {
  宇宙厅: `${HALL_PREVIEW_BASE}/universe.png`,
@@ -292,6 +355,7 @@ const showInternalHeader = computed(() => props.forceInternalHeader || !shouldUs
 const headerTitle = computed(() => {
  if (props.stage === 'stop') return props.selectedHallName || '讲解对象'
  if (props.stage === 'unit') return props.selectedHallName || '讲解单元'
+  if (codeEntryVisible.value) return '编号讲解'
  return '免费讲解'
 })
 const loadingTitle = computed(() => {
@@ -355,6 +419,45 @@ const handleHallClick = (hallId: string) => {
  emit('hallClick', hallId)
 }

+const openCodeEntry = () => {
+  codeEntryError.value = ''
+  codeEntryVisible.value = true
+}
+
+const closeCodeEntry = () => {
+  codeEntryVisible.value = false
+  codeEntryValue.value = ''
+  codeEntryError.value = ''
+}
+
+const handleCodeEntryInput = (event: Event) => {
+  const inputEvent = event as Event & { detail?: { value?: string } }
+  codeEntryValue.value = (inputEvent.detail?.value || '')
+    .replace(/\D/g, '')
+    .slice(0, 4)
+  codeEntryError.value = ''
+}
+
+const submitCodeEntry = () => {
+  if (props.codeSubmitting) return
+  const code = codeEntryValue.value
+  if (code.length !== 4) {
+    codeEntryError.value = '请输入完整的 4 位讲解编号'
+    return
+  }
+  emit('codeSubmit', code)
+}
+
+const showCodeEntryError = (message: string) => {
+  codeEntryError.value = message
+}
+
+const completeCodeEntry = () => {
+  closeCodeEntry()
+}
+
+defineExpose({ showCodeEntryError, completeCodeEntry })
+
 const handleBusinessUnitClick = (unitId: string) => {
  emit('businessUnitClick', unitId)
 }
@@ -382,6 +485,10 @@ const handleScroll = (event: Event) => {
 }

 const handleBack = () => {
+  if (codeEntryVisible.value) {
+    closeCodeEntry()
+    return
+  }
  emit('back')
 }
 </script>
@@ -405,6 +512,64 @@ const handleBack = () => {
  padding: 76px 16px 16px;
 }

+.code-entry-section {
+  padding-bottom: 10px;
+}
+
+.code-entry-button {
+  position: relative;
+  width: 100%;
+  min-height: 82px;
+  margin: 0;
+  padding: 13px 72px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  box-sizing: border-box;
+  color: #171713;
+  border: 1px solid #cfd4c7;
+  border-radius: 8px;
+  background: #ffffff;
+  box-shadow: 0 3px 10px rgba(36, 49, 42, 0.06);
+}
+
+.code-entry-button::after { border: 0; }
+.code-entry-button:active { background: #f0f3e8; }
+.code-entry-icon { position: absolute; left: 28px; top: 50%; width: 44px; height: 44px; border-radius: 8px; background: #e0e100; transform: translateY(-50%); }
+.headphone-band { position: absolute; left: 10px; top: 9px; width: 24px; height: 23px; box-sizing: border-box; border: 3px solid #171713; border-bottom: 0; border-radius: 14px 14px 0 0; }
+.headphone-ear { position: absolute; top: 25px; width: 7px; height: 11px; border-radius: 3px; background: #171713; }
+.headphone-ear.left { left: 8px; }
+.headphone-ear.right { right: 8px; }
+.code-entry-copy { width: 100%; min-width: 0; text-align: center; }
+.code-entry-title, .code-entry-desc { display: block; }
+.code-entry-title { font-size: 17px; line-height: 23px; font-weight: 700; color: #171713; }
+.code-entry-desc { margin-top: 3px; font-size: 12px; line-height: 18px; color: #68725d; }
+
+.hall-section-heading { height: 30px; display: flex; align-items: center; justify-content: center; }
+.hall-section-title { font-size: 13px; line-height: 19px; font-weight: 600; color: #68725d; }
+
+.code-entry-overlay { position: absolute; z-index: 3000; top: 64px; right: 0; bottom: 0; left: 0; background: #f7f9f2; }
+.code-entry-sheet { position: absolute; inset: 0; padding: 24px 24px calc(24px + env(safe-area-inset-bottom)); box-sizing: border-box; background: #f7f9f2; }
+.code-entry-content { width: min(100%, 330px); min-height: 100%; margin: 0 auto; display: flex; flex-direction: column; align-items: center; justify-content: center; box-sizing: border-box; transform: translateY(-28px); }
+.code-entry-sheet-title, .code-entry-sheet-desc, .code-entry-error, .code-entry-demo { display: block; text-align: center; }
+.code-entry-sheet-title { font-size: 22px; line-height: 30px; font-weight: 700; color: #171713; }
+.code-entry-sheet-desc { margin-top: 8px; font-size: 14px; line-height: 20px; color: #68725d; }
+.code-entry-action::after { border: 0; }
+.code-digit-fields { position: relative; width: 100%; margin-top: 32px; display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px; }
+.code-digit-cell { height: 68px; display: flex; align-items: center; justify-content: center; box-sizing: border-box; border: 1.5px solid #aeb5a5; border-radius: 6px; background: #ffffff; }
+.code-digit-cell.active { border-color: #777d00; box-shadow: 0 0 0 1px #e0e100 inset; }
+.code-digit-fields.error .code-digit-cell { border-color: #b63f3f; }
+.code-digit-value { font-size: 30px; line-height: 36px; font-weight: 700; color: #171713; }
+.code-entry-native-input { position: absolute; inset: 0; width: 100%; height: 68px; opacity: 0.01; color: transparent; caret-color: transparent; }
+.code-entry-error, .code-entry-hint { min-height: 19px; margin-top: 10px; font-size: 12px; line-height: 19px; }
+.code-entry-error { color: #a62f2f; }
+.code-entry-hint { color: #7a8271; }
+.code-entry-action { width: 100%; height: 48px; margin: 28px 0 0; padding: 0 12px; font-size: 15px; line-height: 48px; font-weight: 700; border: 0; border-radius: 6px; }
+.code-entry-action.primary { color: #171713; background: #e0e100; }
+.code-entry-action.primary[disabled] { color: #909489; background: #e4e6df; opacity: 1; }
+
+.explain-hall-select.host-navigation .code-entry-overlay { top: 0; }
+
 .explain-scroll.stop-stage {
  padding-bottom: 0;
 }
@@ -906,13 +1071,23 @@ const handleBack = () => {
 }

 .explain-scroll.hall-stage {
-  padding: 88px 16px 24px;
+  padding: 88px 16px 12px;
+  overflow: hidden;
 }

 .hall-overview-list {
-  // Keep the eight-hall overview balanced on tall phones while preserving a
-  // fixed minimum row height for compact screens.
-  grid-auto-rows: max(138px, calc((100vh - 148px) / 4));
+  grid-template-rows: repeat(4, minmax(0, 1fr));
+  grid-auto-rows: minmax(0, 1fr);
+  height: calc(100vh - 222px);
+  gap: 10px 12px;
+}
+
+.hall-overview-card {
+  min-height: 0;
+}
+
+.explain-hall-select.host-navigation .hall-overview-list {
+  height: calc(100vh - 146px);
 }

 .hall-overview-card {
--- a/src/pages/exhibit/detail.vue
+++ b/src/pages/exhibit/detail.vue
@@ -246,6 +246,7 @@ const detailTextLoadedByLanguage = ref<Record<AudioLanguage, boolean>>({
  'en-US': false
 })
 const shouldUseHostNavigation = computed(() => isEmbeddedInWechatMiniProgram())
+const shouldAutoplayOnEntry = ref(false)

 const isAudioLanguage = (value: unknown): value is AudioLanguage => (
  value === 'zh-CN' || value === 'yue-HK' || value === 'en-US'
@@ -531,6 +532,8 @@ onLoad(async (options: any = {}) => {
    return
  }
  const rawLang = Array.isArray(options.lang) ? options.lang[0] : options.lang
+  const rawAutoplay = Array.isArray(options.autoplay) ? options.autoplay[0] : options.autoplay
+  shouldAutoplayOnEntry.value = rawAutoplay === '1' || rawAutoplay === 'true'
  const lang = typeof rawLang === 'string'
    ? normalizeGuideAudioLanguage(rawLang)
    : 'zh-CN'
@@ -545,6 +548,18 @@ onLoad(async (options: any = {}) => {
      poiId: Array.isArray(options.poiId) ? options.poiId[0] : options.poiId
    }
    await loadExplainDetail(detailEntryRequest.value, lang)
+    if (shouldAutoplayOnEntry.value) {
+      shouldAutoplayOnEntry.value = false
+      try {
+        await handlePlayAudio()
+      } catch (error) {
+        console.warn('自动播放讲解失败，将等待用户手动播放:', error)
+        uni.showToast({
+          title: '点击底部播放键开始讲解',
+          icon: 'none'
+        })
+      }
+    }
  } catch (error) {
    console.error('讲解详情加载失败:', error)
    detailState.value = 'error'
--- a/src/pages/explain/list.vue
+++ b/src/pages/explain/list.vue
@@ -8,11 +8,14 @@
  >
    <view class="explain-all-page">
      <ExplainHallSelect
+        ref="hallSelectRef"
        :halls="explainHallItems"
        stage="hall"
        :loading="explainLoading"
        :error="explainError"
+        :code-submitting="codeSubmitting"
        @hall-click="handleExplainHallClick"
+        @code-submit="handleExplainCodeSubmit"
        @retry="loadExplainHalls"
        @back="handleBack"
      />
@@ -41,12 +44,15 @@ import {
 } from '@/utils/guideTopTabs'
 import { isEmbeddedInWechatMiniProgram } from '@/utils/hostEnvironment'
 import { explainGuideStopListUrl } from '@/utils/explainNavigation'
+import { explainCodeDetailUrl, explainCodeErrorMessage } from '@/utils/explainCodeEntry'
 import { returnToWechatMiniProgram } from '@/services/WechatMiniProgramBridgeService'
 import { syncHostNavigationTitle } from '@/utils/hostNavigationTitle'

 const explainHallItems = ref<ExplainHallSelectItem[]>([])
 const explainLoading = ref(false)
 const explainError = ref('')
+const hallSelectRef = ref<InstanceType<typeof ExplainHallSelect> | null>(null)
+const codeSubmitting = ref(false)
 let explainLoadPromise: Promise<void> | null = null

 const normalizeExplainKeyword = (value?: string) => (value || '').trim().toLowerCase()
@@ -270,6 +276,20 @@ const handleExplainHallClick = (hallId: string) => {
  })
 }

+const handleExplainCodeSubmit = async (code: string) => {
+  if (codeSubmitting.value) return
+  codeSubmitting.value = true
+  try {
+    const target = await explainUseCase.resolveExplainCode(code)
+    hallSelectRef.value?.completeCodeEntry()
+    uni.navigateTo({ url: explainCodeDetailUrl(target) })
+  } catch (error) {
+    hallSelectRef.value?.showCodeEntryError(explainCodeErrorMessage(error))
+  } finally {
+    codeSubmitting.value = false
+  }
+}
+
 </script>

 <style scoped lang="scss">
--- a/src/pages/index/index.vue
+++ b/src/pages/index/index.vue
@@ -247,11 +247,14 @@

    <view v-else-if="currentTab === 'explain'" class="explain-page">
      <ExplainHallSelect
+        ref="explainHallSelectRef"
        :halls="explainHallItems"
        stage="hall"
        :loading="explainLoading"
        :error="explainError"
+        :code-submitting="codeSubmitting"
        @hall-click="handleExplainHallClick"
+        @code-submit="handleExplainCodeSubmit"
        @retry="loadExplainHalls"
        @back="handleExplainBack"
      />
@@ -308,6 +311,7 @@ import ExplainHallSelect, {
  type ExplainHallSelectItem
 } from '@/components/explain/ExplainHallSelect.vue'
 import { explainGuideStopListUrl } from '@/utils/explainNavigation'
+import { explainCodeDetailUrl, explainCodeErrorMessage } from '@/utils/explainCodeEntry'
 import {
  getLastGuideLocationPreviewUrl,
  isGuideTopTab,
@@ -1013,6 +1017,8 @@ const selectedGuidePoiActions = computed(() => {
 })

 const explainHallItems = ref<ExplainHallSelectItem[]>([])
+const explainHallSelectRef = ref<InstanceType<typeof ExplainHallSelect> | null>(null)
+const codeSubmitting = ref(false)
 const explainLoading = ref(false)
 const explainError = ref('')
 let explainLoadPromise: Promise<void> | null = null
@@ -2574,6 +2580,20 @@ const handleExplainHallClick = async (hallId: string) => {
  })
 }

+const handleExplainCodeSubmit = async (code: string) => {
+  if (codeSubmitting.value) return
+  codeSubmitting.value = true
+  try {
+    const target = await explainUseCase.resolveExplainCode(code)
+    explainHallSelectRef.value?.completeCodeEntry()
+    uni.navigateTo({ url: explainCodeDetailUrl(target) })
+  } catch (error) {
+    explainHallSelectRef.value?.showCodeEntryError(explainCodeErrorMessage(error))
+  } finally {
+    codeSubmitting.value = false
+  }
+}
+
 const handleExplainBack = () => {
  currentTab.value = 'guide'
  syncTopTabToUrl('guide')
--- a/src/repositories/AudioPlayInfoRepository.ts
+++ b/src/repositories/AudioPlayInfoRepository.ts
@@ -1,10 +1,13 @@
 import { dataSourceConfig } from '@/config/dataSource'
 import {
  toGuideStopDetail,
+  toGuideStopInfo,
  type BackendGuideStopDetail,
+  type BackendGuideStopInfo,
  type GuideAudioLanguage,
  type GuideAudioVersion,
-  type GuideStopDetail
+  type GuideStopDetail,
+  type GuideStopInfo
 } from '@/data/adapters/guideStopInfoAdapter'

 export type AudioLanguage = GuideAudioLanguage
@@ -16,6 +19,7 @@ export interface GetStopDetailOptions {

 export interface AudioPlayInfoRepository {
  getStopDetail(stopId: string, options?: GetStopDetailOptions): Promise<GuideStopDetail>
+  getStopInfoByCode(code: string, lang?: AudioLanguage): Promise<GuideStopInfo>
  clearCache(stopId?: string): void
 }

@@ -25,6 +29,19 @@ interface GuideStopDetailResponse {
  data?: BackendGuideStopDetail
 }

+interface GuideStopInfoResponse {
+  code: number
+  msg?: string
+  data?: BackendGuideStopInfo
+}
+
+export class GuideApiError extends Error {
+  constructor(message: string, readonly code?: number) {
+    super(message)
+    this.name = 'GuideApiError'
+  }
+}
+
 interface CacheEntry<T> {
  value: T
  expiresAt: number
@@ -119,6 +136,25 @@ export class DefaultAudioPlayInfoRepository implements AudioPlayInfoRepository {
    }
  }

+  async getStopInfoByCode(code: string, lang: AudioLanguage = dataSourceConfig.audioLanguage): Promise<GuideStopInfo> {
+    const normalizedCode = String(code || '').trim()
+    if (!normalizedCode) throw new GuideApiError('讲解编号不能为空', 1020007000)
+
+    const params = new URLSearchParams({ code: normalizedCode, lang })
+    const response = await requestJson<GuideStopInfoResponse>(
+      `${resolveAppApiBaseUrl()}/gis/guide/stop/info-by-code?${params.toString()}`
+    )
+    if (response.code !== 0 || !response.data) {
+      throw new GuideApiError(response.msg || '编号讲解查询失败', response.code)
+    }
+
+    return toGuideStopInfo(response.data, {
+      targetType: 'STOP',
+      targetId: '',
+      lang
+    })
+  }
+
  async getStopDetail(stopId: string, options: GetStopDetailOptions = {}): Promise<GuideStopDetail> {
    const normalizedStopId = String(stopId || '').trim()
    if (!normalizedStopId) throw new Error('讲解点 ID 不能为空')
@@ -137,9 +173,7 @@ export class DefaultAudioPlayInfoRepository implements AudioPlayInfoRepository {
      `${resolveAppApiBaseUrl()}/gis/guide/stops/${encodeURIComponent(normalizedStopId)}?${params.toString()}`
    ).then((response) => {
      if (response.code !== 0 || !response.data) {
-        const error = new Error(response.msg || '讲解点详情加载失败')
-        ;(error as Error & { code?: number }).code = response.code
-        throw error
+        throw new GuideApiError(response.msg || '讲解点详情加载失败', response.code)
      }
      const detail = toGuideStopDetail(response.data)
      if (epoch === this.epoch) this.setCached(normalizedStopId, version, detail)
--- a/src/usecases/explainUseCase.ts
+++ b/src/usecases/explainUseCase.ts
@@ -78,6 +78,11 @@ export interface ExplainHallSummary {
  guideStopCount: number
 }

+export interface ExplainCodeResolution {
+  code: string
+  stopId: string
+}
+
 export class ExplainUseCase {
  constructor(
    private readonly explain: ExplainRepository = explainRepository,
@@ -273,6 +278,15 @@ export class ExplainUseCase {
    })
  }

+  async resolveExplainCode(code: string, lang: AudioLanguage = dataSourceConfig.audioLanguage as AudioLanguage): Promise<ExplainCodeResolution> {
+    const stopInfo = await this.audioPlayInfo.getStopInfoByCode(code, lang)
+    const stopId = stopInfo.resolvedStopId || stopInfo.playTargetId || stopInfo.targetId
+    if (!stopInfo.available || !stopId) {
+      throw new Error('该编号的讲解内容暂不可用')
+    }
+    return { code: code.trim(), stopId }
+  }
+
  async enterExplainDetail(request: ExplainDetailEntryRequest) {
    const stopId = this.resolveDetailStopId(request)
    if (!stopId) throw new Error('讲解点 ID 不能为空')
--- a/src/utils/explainCodeEntry.ts
+++ b/src/utils/explainCodeEntry.ts
@@ -0,0 +1,31 @@
+export interface ExplainCodeEntryTarget {
+  code: string
+  stopId: string
+  hallName?: string
+}
+
+export const normalizeExplainCode = (code: string) => code.trim()
+
+export const explainCodeErrorMessage = (error: unknown) => {
+  const code = error && typeof error === 'object' && 'code' in error
+    ? Number((error as { code?: unknown }).code)
+    : undefined
+  if (code === 1020007000) return '请输入有效的 4 位讲解编号'
+  if (code === 1020007001) return '未找到该讲解编号，请确认后重试'
+  if (code === 1020007002) return '该编号的讲解内容暂不可用'
+  if (code === 429) return '查询过于频繁，请稍后再试'
+  return '编号查询失败，请检查网络后重试'
+}
+
+export const explainCodeDetailUrl = (target: ExplainCodeEntryTarget) => {
+  const params = new URLSearchParams({
+    id: target.stopId,
+    stopId: target.stopId,
+    tab: 'explain',
+    autoplay: '1',
+    entry: 'code',
+    guideCode: target.code
+  })
+  if (target.hallName) params.set('hallName', target.hallName)
+  return `/pages/exhibit/detail?${params.toString()}`
+}
--- a/tests/unit/AudioPlayInfoRepository.spec.ts
+++ b/tests/unit/AudioPlayInfoRepository.spec.ts
@@ -68,6 +68,58 @@ describe('DefaultAudioPlayInfoRepository unified stop detail', () => {
    expect(request).toHaveBeenCalledTimes(2)
  })

+  it('resolves a museum code through info-by-code and preserves the code string', async () => {
+    const requestUrls: string[] = []
+    vi.stubGlobal('uni', {
+      request: ({ url, success }: { url: string, success: (response: unknown) => void }) => {
+        requestUrls.push(url)
+        success({
+          statusCode: 200,
+          data: {
+            code: 0,
+            data: {
+              available: true,
+              targetType: 'STOP',
+              targetId: '865546652298080256',
+              resolvedStopId: '865546652298080256',
+              lang: 'zh-CN',
+              title: '手持折射望远镜',
+              imageStatus: 'READY',
+              playTargetType: 'STOP',
+              playTargetId: '865546652298080256',
+              hasAudio: true,
+              supportedLanguages: ['zh-CN', 'yue-HK'],
+              audioStatus: 'READY'
+            }
+          }
+        })
+      }
+    })
+    const repository = new DefaultAudioPlayInfoRepository()
+
+    const result = await repository.getStopInfoByCode('0101', 'zh-CN')
+
+    expect(requestUrls).toEqual([
+      '/app-api/gis/guide/stop/info-by-code?code=0101&lang=zh-CN'
+    ])
+    expect(result.resolvedStopId).toBe('865546652298080256')
+    expect(result.title).toBe('手持折射望远镜')
+  })
+
+  it('preserves info-by-code business error codes', async () => {
+    vi.stubGlobal('uni', {
+      request: ({ success }: { success: (response: unknown) => void }) => {
+        success({ statusCode: 200, data: { code: 1020007001, msg: '馆方讲解点编号不存在', data: null } })
+      }
+    })
+    const repository = new DefaultAudioPlayInfoRepository()
+
+    await expect(repository.getStopInfoByCode('9999')).rejects.toMatchObject({
+      message: '馆方讲解点编号不存在',
+      code: 1020007001
+    })
+  })
+
  it('surfaces a business missing-detail response as a detail error', async () => {
    vi.stubGlobal('uni', {
      request: ({ success }: { success: (response: unknown) => void }) => {
--- a/tests/unit/ExhibitDetailAudioFirst.spec.ts
+++ b/tests/unit/ExhibitDetailAudioFirst.spec.ts
@@ -256,6 +256,26 @@ describe('讲解详情音频优先布局', () => {
    }), expect.objectContaining({ displayMode: 'mini' }))
  })

+  it('编号入口加载详情后自动发起一次播放', async () => {
+    mount(ExhibitDetail, {
+      global: { stubs: { GuidePageFrame: GuidePageFrameStub } }
+    })
+
+    await mocks.onLoadHandler?.({
+      id: exhibit.id,
+      stopId: 'stop-1',
+      autoplay: '1',
+      entry: 'code'
+    })
+    await flushPromises()
+
+    expect(mocks.play).toHaveBeenCalledTimes(1)
+    expect(mocks.play).toHaveBeenCalledWith(
+      expect.objectContaining({ audioUrl: exhibit.audioUrl }),
+      expect.objectContaining({ displayMode: 'mini' })
+    )
+  })
+
  it('加载中使用同一高度底栏和不确定进度', async () => {
    audioState.currentAudio.value = { id: 'audio-1' }
    audioState.currentSource.value = { targetType: 'STOP', targetId: 'stop-1', lang: 'en-US' }
--- a/tests/unit/ExplainCodeEntry.spec.ts
+++ b/tests/unit/ExplainCodeEntry.spec.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+import {
+  explainCodeDetailUrl,
+  explainCodeErrorMessage,
+  normalizeExplainCode
+} from '@/utils/explainCodeEntry'
+
+describe('讲解编号入口', () => {
+  it('清理首尾空格但保留编号前导零', () => {
+    expect(normalizeExplainCode(' 0231 ')).toBe('0231')
+  })
+
+  it.each([
+    [1020007000, '请输入有效的 4 位讲解编号'],
+    [1020007001, '未找到该讲解编号，请确认后重试'],
+    [1020007002, '该编号的讲解内容暂不可用'],
+    [429, '查询过于频繁，请稍后再试']
+  ])('将业务错误码 %s 转换为明确提示', (code, message) => {
+    expect(explainCodeErrorMessage({ code })).toBe(message)
+  })
+
+  it('未知错误使用网络重试提示', () => {
+    expect(explainCodeErrorMessage(new Error('offline'))).toBe('编号查询失败，请检查网络后重试')
+  })
+
+  it('详情路由携带讲解点和自动播放意图', () => {
+    const url = explainCodeDetailUrl({ code: '1001', stopId: '865546652298080256' })
+    expect(url.split('?')[0]).toBe('/pages/exhibit/detail')
+    expect(url).toContain('stopId=865546652298080256')
+    expect(url).toContain('autoplay=1')
+    expect(url).toContain('entry=code')
+    expect(url).toContain('guideCode=1001')
+  })
+})
--- a/tests/unit/ExplainHallSelect.spec.ts
+++ b/tests/unit/ExplainHallSelect.spec.ts
@@ -67,6 +67,51 @@ describe('讲解展厅选择列表', () => {
    expect(wrapper.emitted('hallClick')).toEqual([['hall-evolution']])
  })

+  it('展厅阶段可输入讲解编号并保留前导零', async () => {
+    const wrapper = mount(ExplainHallSelect, {
+      props: { stage: 'hall' }
+    })
+
+    expect(wrapper.get('.code-entry-title').text()).toBe('编号讲解')
+    expect(wrapper.get('.hall-section-title').text()).toBe('按展厅选择')
+    expect(wrapper.find('.code-entry-arrow').exists()).toBe(false)
+
+    await wrapper.get('.code-entry-button').trigger('tap')
+    expect(wrapper.get('.header-title').text()).toBe('编号讲解')
+    expect(wrapper.find('.code-entry-close').exists()).toBe(false)
+    expect(wrapper.get('.code-entry-sheet-title').text()).toBe('输入讲解编号')
+    expect(wrapper.findAll('.code-digit-cell')).toHaveLength(4)
+    expect(wrapper.text()).toContain('请输入展品标签上的四位编号')
+
+    await wrapper.get('.code-entry-native-input').trigger('input', { detail: { value: '02a' } })
+    expect(wrapper.get('.code-entry-action.primary').attributes('disabled')).toBeDefined()
+    await wrapper.get('.code-entry-native-input').trigger('confirm')
+    expect(wrapper.get('.code-entry-error').text()).toBe('请输入完整的 4 位讲解编号')
+
+    await wrapper.get('.code-entry-native-input').trigger('input', { detail: { value: '0231' } })
+    expect(wrapper.findAll('.code-digit-value').map((item) => item.text())).toEqual(['0', '2', '3', '1'])
+    await wrapper.get('.code-entry-action.primary').trigger('tap')
+
+    expect(wrapper.emitted('codeSubmit')).toEqual([['0231']])
+    expect(wrapper.find('.code-entry-sheet').exists()).toBe(true)
+
+    await wrapper.setProps({ codeSubmitting: true })
+    expect(wrapper.get('.code-entry-native-input').attributes('disabled')).toBeDefined()
+    expect(wrapper.get('.code-entry-action.primary').text()).toBe('正在查询')
+
+    wrapper.vm.showCodeEntryError('未找到该讲解编号，请确认后重试')
+    await wrapper.vm.$nextTick()
+    expect(wrapper.get('.code-entry-error').text()).toBe('未找到该讲解编号，请确认后重试')
+
+    await wrapper.get('.header-back').trigger('tap')
+    expect(wrapper.find('.code-entry-sheet').exists()).toBe(false)
+    expect(wrapper.get('.header-title').text()).toBe('免费讲解')
+    expect(wrapper.emitted('back')).toBeUndefined()
+
+    await wrapper.get('.header-back').trigger('tap')
+    expect(wrapper.emitted('back')).toEqual([[]])
+  })
+
  it('展厅阶段使用完整展厅卡片资源', () => {
    const wrapper = mount(ExplainHallSelect, {
      props: {
@@ -84,9 +129,9 @@ describe('讲解展厅选择列表', () => {

    const card = wrapper.get('.hall-overview-card')
    expect(wrapper.get('.header-title').text()).toBe('免费讲解')
-    expect(card.attributes('style')).toContain('--hall-card-color: #d9b06c')
+    expect(card.attributes('style')).toContain('--hall-card-color: #bb965a')
    expect(card.get('.hall-full-card-image').attributes('src'))
-      .toBe('/static/icons/halls/custom-cards/dinosaur.png')
+      .toBe('/static/icons/halls/portal-icons/dinosaur.png')
    expect(card.find('.hall-overview-copy').exists()).toBe(false)
    expect(card.find('.hall-go-entry').exists()).toBe(false)
  })
--- a/tests/unit/ExplainUseCase.spec.ts
+++ b/tests/unit/ExplainUseCase.spec.ts
@@ -33,11 +33,28 @@ const createUseCase = (detail: GuideStopDetail) => {
    getExhibitById: vi.fn().mockResolvedValue(null),
    listExplainExhibits: vi.fn().mockResolvedValue([])
  } as unknown as ExplainRepository
-  const audio = { getStopDetail: vi.fn().mockResolvedValue(detail) } as unknown as AudioPlayInfoRepository
+  const audio = {
+    getStopDetail: vi.fn().mockResolvedValue(detail),
+    getStopInfoByCode: vi.fn().mockResolvedValue({
+      available: true,
+      resolvedStopId: 'resolved-stop-1',
+      playTargetId: 'resolved-stop-1',
+      targetId: 'resolved-stop-1'
+    })
+  } as unknown as AudioPlayInfoRepository
  return { useCase: new ExplainUseCase(explain, audio), explain, audio }
 }

 describe('ExplainUseCase unified stop detail', () => {
+  it('resolves the museum code to the backend stop ID', async () => {
+    const { useCase, audio } = createUseCase(createDetail())
+
+    const result = await useCase.resolveExplainCode('1001', 'zh-CN')
+
+    expect(audio.getStopInfoByCode).toHaveBeenCalledWith('1001', 'zh-CN')
+    expect(result).toEqual({ code: '1001', stopId: 'resolved-stop-1' })
+  })
+
  it('uses stopId once in remote mode without requesting a catalog fallback', async () => {
    const originalMode = dataSourceConfig.explainContentMode
    Object.assign(dataSourceConfig, { explainContentMode: 'remote' })