展示展厅讲解对象编号

- 接入目录分页接口返回的 externalCode 字段 - 在讲解对象标题下方统一展示编号 - 保留空编号对象的原有布局并补充回归测试 Made-with: Proma
修复讲解语音切换后播放器未刷新
2026-08-27 11:31:10 +08:00 · 2026-08-27 11:00:45 +08:00
9 changed files with 158 additions and 27 deletions
--- a/src/components/explain/ExplainGuideStopCatalog.vue
+++ b/src/components/explain/ExplainGuideStopCatalog.vue
@@ -31,6 +31,7 @@
            </view>
            <view class="stop-copy">
              <text class="stop-name">{{ stop.name }}</text>
+              <text v-if="stop.externalCode" class="stop-code">编号：{{ stop.externalCode }}</text>
            </view>
            <view class="stop-status"><text class="stop-status-text">{{ availabilityLabel(stop) }}</text></view>
          </view>
@@ -54,6 +55,7 @@ import GuideLoadingState from '@/components/navigation/GuideLoadingState.vue'
 export interface ExplainGuideStopCatalogItem {
  id: string
  name: string
+  externalCode?: string
  hallId?: string
  hallName?: string
  floorId?: string
@@ -153,6 +155,6 @@ const handleScroll = (event: Event) => { const target = event.target as HTMLElem
 .header-back { position: absolute; left: 12px; top: 10px; width: 44px; height: 44px; display: flex; align-items: center; }.header-back-icon { width: 20px; height: 20px; position: relative; } .header-back-icon::before { content: ''; position: absolute; left: 3px; top: 4px; width: 10px; height: 10px; border-left: 1.5px solid #262421; border-bottom: 1.5px solid #262421; transform: rotate(45deg); }
 .header-back-text { display: none; }.header-title { max-width: calc(100% - 152px); padding: 0 8px; font-size: 18px; line-height: 26px; font-weight: 700; color: #262421; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
 .explain-scroll { height: 100%; padding: 80px 16px calc(16px + env(safe-area-inset-bottom)); box-sizing: border-box; background: #f7f9f2; }.host-navigation .explain-scroll { padding-top: 16px; }
-.stop-list { display: flex; width: 100%; min-width: 0; flex-direction: column; gap: 4px; }.stop-card { width: 100%; min-width: 0; height: 80px; padding: 8px 0; display: flex; align-items: center; gap: 12px; box-sizing: border-box; overflow: hidden; border: 0; border-bottom: 1px solid #dbded4; border-radius: 0; background: transparent; }.stop-card:active { background: rgba(227, 235, 201, 0.4); }.stop-cover { flex: 0 0 64px; width: 64px; height: 64px; overflow: hidden; border-radius: 6px; background: #f5f5ed; }.stop-cover-fallback { font-size: 22px; line-height: 28px; color: #a9b29b; }.stop-copy { min-width: 0; display: flex; flex: 1; overflow: hidden; }.stop-name { display: -webkit-box; max-height: 40px; font-size: 14px; line-height: 20px; font-weight: 700; color: #262421; overflow: hidden; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }.stop-status { flex: 0 0 44px; width: 44px; height: 24px; display: flex; align-items: center; justify-content: center; border-radius: 12px; background: #e3ebc9; }.stop-status-text { font-size: 11px; line-height: 16px; color: #262421; white-space: nowrap; }
+.stop-list { display: flex; width: 100%; min-width: 0; flex-direction: column; gap: 4px; }.stop-card { width: 100%; min-width: 0; min-height: 80px; padding: 8px 0; display: flex; align-items: center; gap: 12px; box-sizing: border-box; overflow: hidden; border: 0; border-bottom: 1px solid #dbded4; border-radius: 0; background: transparent; }.stop-card:active { background: rgba(227, 235, 201, 0.4); }.stop-cover { flex: 0 0 64px; width: 64px; height: 64px; overflow: hidden; border-radius: 6px; background: #f5f5ed; }.stop-cover-fallback { font-size: 22px; line-height: 28px; color: #a9b29b; }.stop-copy { min-width: 0; display: flex; flex: 1; flex-direction: column; justify-content: center; gap: 3px; overflow: hidden; }.stop-code { display: block; overflow: hidden; font-size: 11px; line-height: 16px; font-weight: 600; color: #68725d; text-overflow: ellipsis; white-space: nowrap; }.stop-name { display: -webkit-box; max-height: 40px; font-size: 14px; line-height: 20px; font-weight: 700; color: #262421; overflow: hidden; -webkit-line-clamp: 2; -webkit-box-orient: vertical; }.stop-name + .stop-code { margin-top: 1px; }.stop-status { flex: 0 0 44px; width: 44px; height: 24px; display: flex; align-items: center; justify-content: center; border-radius: 12px; background: #e3ebc9; }.stop-status-text { font-size: 11px; line-height: 16px; color: #262421; white-space: nowrap; }
 .state-block { margin: 34px 0; padding: 22px 16px; box-sizing: border-box; text-align: center; border: 1px solid #e4e6df; border-radius: 8px; background: #fff; }.state-block.error { border-color: #e5c2c2; background: #fff7f7; }.state-title,.state-desc { display: block; }.state-title { font-size: 15px; line-height: 21px; font-weight: 700; color: #141412; }.state-desc { margin-top: 6px; font-size: 12px; line-height: 18px; color: #68725d; }.state-retry { margin-top: 12px; padding: 0 14px; font-size: 13px; line-height: 32px; color: #141412; background: #e0df00; border: 0; border-radius: 6px; }.load-more-state { min-height: 52px; padding: 12px 16px calc(12px + env(safe-area-inset-bottom)); text-align: center; }
 </style>
--- a/src/composables/useGlobalAudioPlayer.ts
+++ b/src/composables/useGlobalAudioPlayer.ts
@@ -205,6 +205,31 @@ const toSwitchedAudioItem = (
  supportedLanguages: currentAudio.value?.supportedLanguages
 })

+const prepare = (audio: AudioItem, options: GlobalAudioPlayOptions = {}) => {
+  const preservedMode = options.displayMode || displayMode.value
+  stopAudioElement()
+  currentAudio.value = audio
+  currentSource.value = options.source || currentSource.value
+  retryOnError = options.retryOnError || retryOnError
+  visible.value = true
+  displayMode.value = preservedMode
+  playing.value = false
+  loading.value = false
+  error.value = audio.audioUrl ? '' : '当前语言暂无语音讲解'
+  currentTime.value = 0
+  duration.value = audio.duration || 0
+
+  if (audio.audioUrl) {
+    const element = ensureAudioElement()
+    if (element) {
+      element.src = audio.audioUrl
+      element.load()
+      element.playbackRate = playbackRate.value
+      element.muted = muted.value
+    }
+  }
+}
+
 const play = async (audio: AudioItem, options: GlobalAudioPlayOptions = {}) => {
  if (!audio.audioUrl) {
    const preservedMode = options.displayMode || displayMode.value
@@ -500,6 +525,7 @@ export const useGlobalAudioPlayer = () => ({
  closeVersion,
  hasAudio: computed(() => Boolean(currentAudio.value)),
  play,
+  prepare,
  pause,
  resume,
  stop,
--- a/src/data/adapters/backendExplainDataAdapter.ts
+++ b/src/data/adapters/backendExplainDataAdapter.ts
@@ -147,6 +147,8 @@ export interface BackendCatalogStopItem {
  mapX?: number | string | null
  mapY?: number | string | null
  name?: string | null
+  /** 馆方讲解编号，按字符串返回以保留前导零。 */
+  externalCode?: string | null
  guideLevel?: string | null
  description?: string | null
  sort?: number | null
@@ -350,6 +352,7 @@ export const toCatalogGuideStop = (
  return {
    id,
    name: firstText(source.name, `讲解点${id}`),
+    externalCode: firstText(source.externalCode) || undefined,
    hallId: hall?.id,
    hallName: hall?.name,
    floorId: stringifyId(source.floorId) || hall?.floorId,
--- a/src/domain/museum.ts
+++ b/src/domain/museum.ts
@@ -243,6 +243,8 @@ export interface MuseumExhibit {
 export interface ExplainGuideStop {
  id: string
  name: string
+  /** 馆方讲解编号，来自目录接口 externalCode，必须按字符串保留。 */
+  externalCode?: string
  hallId?: string
  hallName?: string
  floorId?: string
--- a/src/pages/exhibit/detail.vue
+++ b/src/pages/exhibit/detail.vue
@@ -695,10 +695,10 @@ const handleLanguageChange = async (lang: AudioLanguage, options: { syncAudio?:
      }
    }
    void loadFullDetailTextForLanguage(request, lang, exhibit.value)
-    if (shouldContinueAudio) {
-      // The player must become actionable before resuming with the new language track.
+    if (options.syncAudio !== false && isCurrentDetailAudioTarget.value) {
+      // 语言切换后立即刷新播放器；原先暂停时不会更新音轨，导致组件仍显示旧内容。
      languageSwitchLoading.value = false
-      await handlePlayAudio()
+      await handlePlayAudio({ autoplay: shouldContinueAudio })
    }
  } catch (error) {
    if (requestSequence !== languageSwitchSequence) return
@@ -730,11 +730,12 @@ const handleLanguageChange = async (lang: AudioLanguage, options: { syncAudio?:
 const handleToggleDetailAudioVoice = async () => {
  if (audioDockState.value !== 'playable' || !canSwitchDetailAudioVoice.value) return

-  const shouldContinueAudio = isCurrentDetailAudioTarget.value && globalAudioPlayer.playing.value
+  const hasCurrentDetailAudio = isCurrentDetailAudioTarget.value
+  const shouldContinueAudio = hasCurrentDetailAudio && globalAudioPlayer.playing.value
  selectedAudioGender.value = currentDetailAudioGender.value === 'male' ? 'female' : 'male'

-  if (shouldContinueAudio) {
-    await handlePlayAudio()
+  if (hasCurrentDetailAudio) {
+    await handlePlayAudio({ autoplay: shouldContinueAudio })
  }
 }

@@ -821,8 +822,7 @@ const refreshCurrentAudioOnce = async (message: string) => {
  return null
 }

-const playDetailAudio = async (audio: AudioItem) => {
-  await globalAudioPlayer.play(audio, {
+const detailAudioPlayOptions = (audio: AudioItem) => ({
  source: {
    exhibitId: exhibit.value.id,
    stopId: currentAudioTarget.value.stopId,
@@ -834,11 +834,18 @@ const playDetailAudio = async (audio: AudioItem) => {
    detailRoute: buildDetailRoute()
  },
  retryOnError: refreshCurrentAudioOnce,
-    displayMode: 'mini'
+  displayMode: 'mini' as const
 })
+
+const playDetailAudio = async (audio: AudioItem) => {
+  await globalAudioPlayer.play(audio, detailAudioPlayOptions(audio))
 }

-const handlePlayAudio = async (options: { forceRefresh?: boolean } = {}) => {
+const prepareDetailAudio = (audio: AudioItem) => {
+  globalAudioPlayer.prepare(audio, detailAudioPlayOptions(audio))
+}
+
+const handlePlayAudio = async (options: { forceRefresh?: boolean; autoplay?: boolean } = {}) => {
  if (audioDockState.value === 'unavailable' || audioDockState.value === 'loading') return

  if (audioDockState.value === 'failed' && !options.forceRefresh) {
@@ -859,7 +866,8 @@ const handlePlayAudio = async (options: { forceRefresh?: boolean } = {}) => {
    ? await refreshCurrentAudioOnce(globalAudioPlayer.error.value)
    : null
  if (refreshedAudio) {
-    await playDetailAudio(refreshedAudio)
+    if (options.autoplay === false) prepareDetailAudio(refreshedAudio)
+    else await playDetailAudio(refreshedAudio)
    return
  }

@@ -895,6 +903,10 @@ const handlePlayAudio = async (options: { forceRefresh?: boolean } = {}) => {
  const audio = toAudioItem(selection)
  if (!audio) return

+  if (options.autoplay === false) {
+    prepareDetailAudio(audio)
+    return
+  }
  await playDetailAudio(audio)
 }

--- a/src/pages/explain/guide-stop-list.vue
+++ b/src/pages/explain/guide-stop-list.vue
@@ -43,6 +43,7 @@ let disposed = false
 const toGuideStopItems = (stops: ExplainGuideStop[]): ExplainGuideStopCatalogItem[] => stops.map((stop) => ({
  id: stop.id,
  name: stop.name,
+  externalCode: stop.externalCode,
  hallId: stop.hallId,
  hallName: stop.hallName,
  floorId: stop.floorId,
--- a/tests/unit/BackendExplainContentProvider.spec.ts
+++ b/tests/unit/BackendExplainContentProvider.spec.ts
@@ -26,7 +26,7 @@ describe('BackendExplainContentProvider hall stop paging', () => {
        data: {
          total: 30,
          list: pageNo === '1'
-            ? [{ stopId: 'stop-1', name: '对象一', imageStatus: 'READY', coverImageUrl: '/one.jpg', outlineId: 'outline-1', linkedExhibits: [] }]
+            ? [{ stopId: 'stop-1', name: '对象一', externalCode: '0231', imageStatus: 'READY', coverImageUrl: '/one.jpg', outlineId: 'outline-1', linkedExhibits: [] }]
            : [{ stopId: 'stop-2', name: '对象二', imageStatus: 'MISSING', outlineId: 'outline-1', linkedExhibits: [] }]
        }
      }
@@ -38,7 +38,7 @@ describe('BackendExplainContentProvider hall stop paging', () => {
    ])

    expect(first).toMatchObject({ total: 30, pageNo: 1, pageSize: 20, hasMore: true })
-    expect(first.items[0]).toMatchObject({ id: 'stop-1', stopId: 'stop-1', hallName: '恐龙厅', outlineId: 'outline-1' })
+    expect(first.items[0]).toMatchObject({ id: 'stop-1', stopId: 'stop-1', externalCode: '0231', hallName: '恐龙厅', outlineId: 'outline-1' })
    expect(second.items.map((item) => item.id)).toEqual(['stop-2'])
    expect(requests.filter((url) => url.includes('/stops/page'))).toHaveLength(2)
    expect(requests.some((url) => url.includes('/outlines'))).toBe(false)
--- a/tests/unit/ExhibitDetailAudioFirst.spec.ts
+++ b/tests/unit/ExhibitDetailAudioFirst.spec.ts
@@ -12,6 +12,7 @@ const mocks = vi.hoisted(() => ({
  loadExplainDetailText: vi.fn(),
  selectAudioForExplainDetail: vi.fn(),
  play: vi.fn(),
+  prepare: vi.fn(),
  pause: vi.fn(),
  resume: vi.fn(),
  close: vi.fn(),
@@ -61,8 +62,15 @@ vi.mock('@/usecases/guideUseCase', () => ({
 vi.mock('@/composables/useGlobalAudioPlayer', () => ({
  useGlobalAudioPlayer: () => ({
    ...audioState,
-    isCurrentSource: () => false,
+    isCurrentSource: (source: { stopId?: string, lang?: string, channelCode?: string }) => Boolean(
+      audioState.currentAudio.value
+      && audioState.currentSource.value
+      && audioState.currentSource.value.stopId === source.stopId
+      && (!source.lang || audioState.currentSource.value.lang === source.lang)
+      && (!source.channelCode || audioState.currentSource.value.channelCode === source.channelCode)
+    ),
    play: mocks.play,
+    prepare: mocks.prepare,
    pause: mocks.pause,
    resume: mocks.resume,
    switchLanguage: vi.fn(),
@@ -346,6 +354,81 @@ describe('讲解详情音频优先布局', () => {
    }))
  })

+  it('暂停时切换语言立即刷新播放器但不自动播放', async () => {
+    const bilingualExhibit = {
+      ...exhibit,
+      audioLanguage: 'en-US',
+      audioOptions: [
+        { channelCode: 'standard.zh-CN.female', version: 'standard', languageCode: 'zh-CN', gender: 'female', playUrl: '/assets/zh-female.mp3', duration: 50 },
+        { channelCode: 'standard.en-US.female', version: 'standard', languageCode: 'en-US', gender: 'female', playUrl: '/assets/en-female.mp3', duration: 80 }
+      ]
+    }
+    mocks.enterExplainDetail.mockResolvedValue(bilingualExhibit)
+    mocks.selectAudioForExplainDetail.mockImplementation(async (data: { audioLanguage: string }) => {
+      const option = bilingualExhibit.audioOptions.find((item) => item.languageCode === data.audioLanguage)!
+      return {
+        playable: true,
+        exhibit: bilingualExhibit,
+        media: { id: option.channelCode, url: option.playUrl, duration: option.duration, language: option.languageCode },
+        playInfo: { title: exhibit.name }
+      }
+    })
+    audioState.currentAudio.value = { id: 'standard.en-US.female', audioUrl: '/assets/en-female.mp3' }
+    audioState.currentSource.value = { stopId: 'stop-1', lang: 'en-US', channelCode: 'standard.en-US.female' }
+    audioState.playing.value = false
+    const wrapper = mount(ExhibitDetail, {
+      global: { stubs: { GuidePageFrame: GuidePageFrameStub } }
+    })
+
+    await mocks.onLoadHandler?.({ id: exhibit.id, stopId: 'stop-1', lang: 'en-US' })
+    await flushPromises()
+    await wrapper.findAll('.language-option').find((button) => button.text() === '中文')!.trigger('tap')
+    await flushPromises()
+
+    expect(mocks.prepare).toHaveBeenCalledWith(
+      expect.objectContaining({ audioUrl: '/assets/zh-female.mp3', language: 'zh-CN', duration: 50 }),
+      expect.objectContaining({ source: expect.objectContaining({ lang: 'zh-CN', channelCode: 'standard.zh-CN.female' }) })
+    )
+    expect(mocks.play).not.toHaveBeenCalled()
+  })
+
+  it('暂停时切换男女声立即刷新播放器但不自动播放', async () => {
+    const voiceExhibit = {
+      ...exhibit,
+      audioOptions: [
+        { channelCode: 'standard.en-US.female', version: 'standard', languageCode: 'en-US', gender: 'female', playUrl: '/assets/en-female.mp3', duration: 80 },
+        { channelCode: 'standard.en-US.male', version: 'standard', languageCode: 'en-US', gender: 'male', playUrl: '/assets/en-male.mp3', duration: 75 }
+      ]
+    }
+    mocks.enterExplainDetail.mockResolvedValue(voiceExhibit)
+    mocks.selectAudioForExplainDetail.mockImplementation(async (_data: unknown, options: { voiceGender?: string }) => {
+      const option = voiceExhibit.audioOptions.find((item) => item.gender === options.voiceGender)!
+      return {
+        playable: true,
+        exhibit: voiceExhibit,
+        media: { id: option.channelCode, url: option.playUrl, duration: option.duration, language: option.languageCode },
+        playInfo: { title: exhibit.name }
+      }
+    })
+    audioState.currentAudio.value = { id: 'standard.en-US.female', audioUrl: '/assets/en-female.mp3' }
+    audioState.currentSource.value = { stopId: 'stop-1', lang: 'en-US', channelCode: 'standard.en-US.female' }
+    audioState.playing.value = false
+    const wrapper = mount(ExhibitDetail, {
+      global: { stubs: { GuidePageFrame: GuidePageFrameStub } }
+    })
+
+    await mocks.onLoadHandler?.({ id: exhibit.id, stopId: 'stop-1', lang: 'en-US' })
+    await flushPromises()
+    await wrapper.get('.detail-audio-voice').trigger('tap')
+    await flushPromises()
+
+    expect(mocks.prepare).toHaveBeenCalledWith(
+      expect.objectContaining({ audioUrl: '/assets/en-male.mp3', duration: 75 }),
+      expect.objectContaining({ source: expect.objectContaining({ voiceGender: 'male', channelCode: 'standard.en-US.male' }) })
+    )
+    expect(mocks.play).not.toHaveBeenCalled()
+  })
+
  it('播放器单行提供倍速循环和男女声切换', async () => {
    mocks.enterExplainDetail.mockResolvedValue({
      ...exhibit,
--- a/tests/unit/ExplainGuideStopCatalog.spec.ts
+++ b/tests/unit/ExplainGuideStopCatalog.spec.ts
@@ -5,7 +5,7 @@ import { describe, expect, it } from 'vitest'
 import ExplainGuideStopCatalog from '@/components/explain/ExplainGuideStopCatalog.vue'

 const stops = [
-  { id: 'ready', name: '一个很长很长很长很长很长的讲解对象名称', coverImageUrl: '/cover.jpg', audioStatus: 'READY', hasAudio: true, hasTextRecord: true },
+  { id: 'ready', name: '一个很长很长很长很长很长的讲解对象名称', externalCode: '0231', coverImageUrl: '/cover.jpg', audioStatus: 'READY', hasAudio: true, hasTextRecord: true },
  { id: 'text', name: '图文对象', hasTextRecord: true },
  { id: 'none', name: '无内容对象' }
 ]
@@ -22,6 +22,8 @@ describe('ExplainGuideStopCatalog', () => {
    expect(wrapper.findAll('.stop-status')).toHaveLength(3)
    expect(wrapper.text()).toContain('讲解')
    expect(wrapper.text()).toContain('图文')
+    expect(wrapper.get('.stop-code').text()).toBe('编号：0231')
+    expect(wrapper.findAll('.stop-code')).toHaveLength(1)
    expect(wrapper.text()).not.toContain('暂无内容')
    expect(wrapper.find('.hall-arrow').exists()).toBe(false)
    expect(wrapper.find('.stop-name').classes()).toContain('stop-name')