接入编号讲解后端查询

- 使用真实讲解编号解析接口替换本地演示映射
- 成功后复用现有详情页并自动播放讲解
- 增加查询状态、业务错误提示和相关测试

Made-with: Proma

.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

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
+  grid-template-rows: repeat(4, minmax(0, 1fr));
-  // fixed minimum row height for compact screens.
+  grid-auto-rows: minmax(0, 1fr);
-  grid-auto-rows: max(138px, calc((100vh - 148px) / 4));
+  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 {

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'

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">

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')

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 || '讲解点详情加载失败')
+        throw new GuideApiError(response.msg || '讲解点详情加载失败', response.code)
-        ;(error as Error & { code?: number }).code = response.code
-        throw error
       }
       const detail = toGuideStopDetail(response.data)
       if (epoch === this.epoch) this.setCached(normalizedStopId, version, detail)

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 不能为空')

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()}`
+}

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 }) => {

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' }

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')
+  })
+})

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)
   })

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' })