适配讲解详情聚合接口

2026-07-22 19:40:17 +08:00
parent dd29ead041
commit 4d8cc55a5c
10 changed files with 440 additions and 152 deletions
--- a/src/composables/useGlobalAudioPlayer.ts
+++ b/src/composables/useGlobalAudioPlayer.ts
@@ -259,7 +259,7 @@ const resume = () => {
  })
 }

-const switchLanguage = async (lang: AudioLanguage) => {
+const switchLanguage = async (lang: AudioLanguage, localAudio?: AudioItem | null) => {
  if (pendingLanguage.value) {
    return false
  }
@@ -291,6 +291,35 @@ const switchLanguage = async (lang: AudioLanguage) => {
  }

  try {
+    if (localAudio?.audioUrl) {
+      currentSource.value = nextSource
+      return await play(localAudio, {
+        source: nextSource,
+        retryOnError: retryOnError || undefined,
+        displayMode: preservedMode
+      })
+    }
+
+    if (localAudio) {
+      stopAudioElement()
+      currentSource.value = nextSource
+      currentAudio.value = {
+        ...localAudio,
+        audioUrl: '',
+        duration: 0,
+        language: lang
+      }
+      visible.value = true
+      displayMode.value = preservedMode
+      playing.value = false
+      loading.value = false
+      currentTime.value = 0
+      duration.value = 0
+      error.value = '当前语言暂无语音讲解'
+      showToast(error.value)
+      return false
+    }
+
    const playInfo = await audioPlayInfoRepository.getPlayInfo({
      targetType: source.targetType,
      targetId: source.targetId,
--- a/src/data/adapters/guideStopInfoAdapter.ts
+++ b/src/data/adapters/guideStopInfoAdapter.ts
@@ -42,11 +42,31 @@ export interface BackendGuideStopInfo {
  hasText?: boolean
  supportedLanguages?: string[] | null
  audioStatus?: string | null
+  languageVariants?: BackendGuideStopLanguageVariant[] | null
  reason?: string | null
  linkedExhibitCount?: number | string | null
  isSharedStop?: boolean | null
 }

+export interface BackendGuideStopLanguageVariant {
+  lang?: string | null
+  enabled?: boolean | null
+  playable?: boolean | null
+  audioStatus?: string | null
+  playUrl?: string | null
+  duration?: number | string | null
+  format?: string | null
+  audioId?: string | number | null
+  narrationTier?: 'STANDARD' | 'EXTENDED' | string | null
+  hasText?: boolean | null
+  textAvailable?: boolean | null
+  text?: string | null
+  textLength?: number | string | null
+  textHash?: string | null
+  fallback?: boolean | null
+  reason?: string | null
+}
+
 export interface BackendAudioPlayInfo {
  playable?: boolean
  targetType?: string | null
@@ -90,6 +110,25 @@ export interface GuideStopLinkedExhibit {
  sortOrder?: number
 }

+export interface GuideStopLanguageVariant {
+  lang: GuideAudioLanguage
+  enabled: boolean
+  playable: boolean
+  audioStatus: 'READY' | 'MISSING' | string
+  playUrl?: string
+  duration?: number
+  format?: string
+  audioId?: string
+  narrationTier?: 'STANDARD' | 'EXTENDED'
+  hasText: boolean
+  textAvailable: boolean
+  text?: string
+  textLength?: number
+  textHash?: string
+  fallback: boolean
+  reason?: string
+}
+
 export interface GuideStopInfo {
  available: boolean
  targetType: AudioPlayTargetType
@@ -112,6 +151,7 @@ export interface GuideStopInfo {
  hasAudio: boolean
  hasText: boolean
  supportedLanguages: GuideAudioLanguage[]
+  languageVariants: Record<GuideAudioLanguage, GuideStopLanguageVariant>
  audioStatus: 'READY' | 'MISSING' | string
  reason?: string
  linkedExhibitCount?: number
@@ -177,16 +217,57 @@ export const normalizeGuideAudioLanguage = (
  return 'zh-CN'
 }

+const isSupportedGuideAudioLanguage = (value: string | null | undefined) => (
+  ['zh', 'zh-cn', 'en', 'en-us', 'yue', 'yue-cn', 'yue-hk'].includes(value?.trim().toLowerCase() || '')
+)
+
 const normalizeSupportedLanguages = (languages: string[] | null | undefined): GuideAudioLanguage[] => (
  Array.from(new Set((languages || [])
-    .map((language) => {
-      const normalized = language?.trim().toLowerCase()
-      if (!['zh', 'zh-cn', 'en', 'en-us', 'yue', 'yue-cn', 'yue-hk'].includes(normalized)) {
-        return null
-      }
-      return normalizeGuideAudioLanguage(language)
-    })
-    .filter(Boolean))) as GuideAudioLanguage[]
+    .filter(isSupportedGuideAudioLanguage)
+    .map(normalizeGuideAudioLanguage))) as GuideAudioLanguage[]
+)
+
+const normalizeLanguageVariants = (
+  variants: BackendGuideStopLanguageVariant[] | null | undefined
+): Record<GuideAudioLanguage, GuideStopLanguageVariant> => {
+  const normalizedVariants = {} as Record<GuideAudioLanguage, GuideStopLanguageVariant>
+
+  ;(variants || []).forEach((variant) => {
+    if (!isSupportedGuideAudioLanguage(variant.lang)) return
+
+    const lang = normalizeGuideAudioLanguage(variant.lang)
+    const playUrl = normalizeSameOriginPublicUrl(variant.playUrl) || undefined
+    const playable = variant.playable === true && Boolean(playUrl)
+    const text = variant.text?.trim() || undefined
+    const textAvailable = variant.textAvailable === true || Boolean(text)
+
+    normalizedVariants[lang] = {
+      lang,
+      enabled: variant.enabled === true,
+      playable,
+      audioStatus: variant.audioStatus || (playable ? 'READY' : 'MISSING'),
+      playUrl,
+      duration: normalizeNumber(variant.duration),
+      format: variant.format?.trim() || undefined,
+      audioId: stringifyId(variant.audioId) || undefined,
+      narrationTier: normalizeNarrationTier(variant.narrationTier),
+      hasText: variant.hasText === true || textAvailable,
+      textAvailable,
+      text,
+      textLength: normalizeNumber(variant.textLength),
+      textHash: variant.textHash?.trim() || undefined,
+      fallback: variant.fallback === true,
+      reason: variant.reason?.trim() || undefined
+    }
+  })
+
+  return normalizedVariants
+}
+
+const supportedLanguagesFromVariants = (variants: Record<GuideAudioLanguage, GuideStopLanguageVariant>) => (
+  (Object.values(variants) as GuideStopLanguageVariant[])
+    .filter((variant) => variant.enabled && (variant.playable || variant.textAvailable))
+    .map((variant) => variant.lang)
 )

 const parseGalleryUrls = (value: BackendGuideStopInfo['galleryUrls'] | BackendGuideStopLinkedExhibit['galleryUrls']) => {
@@ -255,6 +336,8 @@ export const toGuideStopInfo = (
  const coverImageUrl = canUseStopImages
    ? normalizeSameOriginPublicUrl(source.coverImageUrl) || undefined
    : undefined
+  const languageVariants = normalizeLanguageVariants(source.languageVariants)
+  const supportedLanguages = supportedLanguagesFromVariants(languageVariants)

  return {
    available: source.available === true,
@@ -277,7 +360,10 @@ export const toGuideStopInfo = (
    playTargetId,
    hasAudio: source.hasAudio === true,
    hasText: source.hasText === true,
-    supportedLanguages: normalizeSupportedLanguages(source.supportedLanguages),
+    supportedLanguages: supportedLanguages.length
+      ? supportedLanguages
+      : normalizeSupportedLanguages(source.supportedLanguages),
+    languageVariants,
    audioStatus: source.audioStatus || 'MISSING',
    reason: source.reason || undefined,
    linkedExhibitCount: normalizeNumber(source.linkedExhibitCount),
--- a/src/domain/museum.ts
+++ b/src/domain/museum.ts
@@ -182,10 +182,21 @@ export interface MuseumExhibit {
  audioVariants?: Record<string, {
    title?: string
    text?: string
+    textAvailable?: boolean
+    textLength?: number
+    textHash?: string
    audioUrl?: string
    audioDuration?: number
+    format?: string
+    audioId?: string
+    narrationTier?: 'STANDARD' | 'EXTENDED'
    hasText?: boolean
+    enabled?: boolean
+    playable?: boolean
    available?: boolean
+    audioStatus?: string
+    fallback?: boolean
+    reason?: string
  }>
  imageStatus?: string
  imageSource?: string
--- a/src/pages/exhibit/detail.vue
+++ b/src/pages/exhibit/detail.vue
@@ -160,7 +160,8 @@ import {
  type ExplainDetailPageViewModel
 } from '@/view-models/explainViewModels'
 import type {
-  AudioPlayTargetType
+  AudioPlayTargetType,
+  MuseumExhibit
 } from '@/domain/museum'
 import type {
  AudioLanguage
@@ -193,6 +194,7 @@ const defaultDetail: ExplainDetailPageViewModel = {
 }

 const exhibit = ref<ExplainDetailPageViewModel>(defaultDetail)
+const detailSource = ref<MuseumExhibit | null>(null)
 const detailState = ref<'idle' | 'loading' | 'ready' | 'missing' | 'error'>('idle')
 const detailStateMessage = ref('请检查链接后重试。')
 const globalAudioPlayer = useGlobalAudioPlayer()
@@ -201,7 +203,6 @@ const resolvedHallId = ref('')
 const retryingAudio = ref(false)
 const languageSwitchLoading = ref(false)
 const selectedAudioLanguage = ref<AudioLanguage>('zh-CN')
-let languageSwitchSequence = 0
 const detailEntryRequest = ref<{
  exhibitId: string
  targetType?: AudioPlayTargetType
@@ -217,16 +218,6 @@ const detailTextByLanguage = ref<Record<AudioLanguage, string>>({
  'yue-HK': '当前语言暂无讲解词。',
  'en-US': 'English narration text is not available yet.'
 })
-const detailTextLoadingByLanguage = ref<Record<AudioLanguage, boolean>>({
-  'zh-CN': false,
-  'yue-HK': false,
-  'en-US': false
-})
-const detailTextLoadedByLanguage = ref<Record<AudioLanguage, boolean>>({
-  'zh-CN': false,
-  'yue-HK': false,
-  'en-US': false
-})
 // 讲解详情页位置入口暂未开放，避免误导用户进入位置预览流程。
 const isLocationActionVisible = false
 const shouldUseHostNavigation = computed(() => isEmbeddedInWechatMiniProgram())
@@ -416,63 +407,22 @@ const applyDetailText = (lang: AudioLanguage, text?: string) => {
    ...detailTextByLanguage.value,
    [lang]: normalized || fallbackTextForLanguage(lang)
  }
-  detailTextLoadedByLanguage.value = {
-    ...detailTextLoadedByLanguage.value,
-    [lang]: true
-  }
 }

-const buildTextSourceFromViewModel = (viewModel: ExplainDetailPageViewModel) => ({
-  id: viewModel.id,
-  name: viewModel.title,
-  hallId: viewModel.hallId,
-  hallName: viewModel.hallName,
-  floorId: viewModel.floorId,
-  floorLabel: viewModel.floorLabel,
-  image: viewModel.coverImages[0],
-  description: viewModel.summary,
-  guideText: viewModel.summary,
-  audioLanguage: viewModel.audio.language,
-  audioHasText: viewModel.audio.hasText,
-  playTargetType: viewModel.audio.playTargetType,
-  playTargetId: viewModel.audio.playTargetId
-})
-
-const loadFullDetailTextForLanguage = async (
-  request: NonNullable<typeof detailEntryRequest.value>,
-  lang: AudioLanguage,
-  preferredViewModel?: ExplainDetailPageViewModel
-) => {
-  detailTextLoadingByLanguage.value = {
-    ...detailTextLoadingByLanguage.value,
-    [lang]: true
+const hydrateDetailTexts = (source: MuseumExhibit) => {
+  const nextTexts: Record<AudioLanguage, string> = {
+    'zh-CN': fallbackTextForLanguage('zh-CN'),
+    'yue-HK': fallbackTextForLanguage('yue-HK'),
+    'en-US': fallbackTextForLanguage('en-US')
  }

-  try {
-    const viewModel = preferredViewModel || toExplainDetailPageViewModel(await explainUseCase.enterExplainDetail({
-      ...request,
-      lang
-    }))
+  ;(['zh-CN', 'yue-HK', 'en-US'] as AudioLanguage[]).forEach((lang) => {
+    const variant = source.audioVariants?.[lang]
+    const text = variant?.text || (source.audioLanguage === lang ? source.guideText : undefined)
+    nextTexts[lang] = text?.trim() || fallbackTextForLanguage(lang)
+  })

-    if (viewModel.audio.hasText) {
-      const selection = await explainUseCase.loadExplainDetailText(buildTextSourceFromViewModel(viewModel))
-      if (selection.available) {
-        const nextViewModel = toExplainDetailPageViewModel(selection.exhibit)
-        applyDetailText(lang, nextViewModel.body || nextViewModel.summary)
-        return
-      }
-    }
-
-    applyDetailText(lang, viewModel.body || viewModel.summary)
-  } catch (error) {
-    console.warn('讲解正文加载失败:', lang, error)
-    applyDetailText(lang)
-  } finally {
-    detailTextLoadingByLanguage.value = {
-      ...detailTextLoadingByLanguage.value,
-      [lang]: false
-    }
-  }
+  detailTextByLanguage.value = nextTexts
 }

 const loadExplainDetail = async (
@@ -485,6 +435,8 @@ const loadExplainDetail = async (
    lang
  })

+  detailSource.value = exhibitData
+  hydrateDetailTexts(exhibitData)
  exhibit.value = toExplainDetailPageViewModel(exhibitData)
  const resolvedLanguage = resolveSupportedDetailLanguage(lang)
  selectedAudioLanguage.value = resolvedLanguage
@@ -494,12 +446,13 @@ const loadExplainDetail = async (
  }

  if (resolvedLanguage !== lang) {
+    const localizedExhibit = explainUseCase.selectExplainDetailLanguage(exhibitData, resolvedLanguage)
+    detailSource.value = localizedExhibit
+    exhibit.value = toExplainDetailPageViewModel(localizedExhibit)
+    selectedAudioLanguage.value = resolvedLanguage
    replaceDetailRouteLanguage(resolvedLanguage)
-    await loadExplainDetail(request, resolvedLanguage)
-    return
  }

-  void loadFullDetailTextForLanguage(request, resolvedLanguage, exhibit.value)
  detailState.value = 'ready'
 }

@@ -618,9 +571,7 @@ const splitDetailTextIntoParagraphs = (text: string): string[] => {

 const currentDetailText = computed(() => detailTextFor(selectedAudioLanguage.value))
 const currentDetailParagraphs = computed(() => splitDetailTextIntoParagraphs(currentDetailText.value))
-const currentDetailTextLoading = computed(() => (
-  languageSwitchLoading.value || detailTextLoadingByLanguage.value[selectedAudioLanguage.value]
-))
+const currentDetailTextLoading = computed(() => languageSwitchLoading.value)
 const detailLoadingMessage = computed(() => (
  languageSwitchLoading.value
    ? `正在切换到${audioLanguageLabel(selectedAudioLanguage.value)}`
@@ -648,62 +599,40 @@ const handleLanguageChange = async (lang: AudioLanguage, options: { syncAudio?:
    || (supportedDetailLanguages.value.length > 0 && !supportedDetailLanguages.value.includes(lang))
  ) return

+  const source = detailSource.value
+  if (!source) return
+
  const shouldSyncAudio = options.syncAudio !== false && isCurrentDetailAudioTarget.value
-  const request = detailEntryRequest.value
-  const requestSequence = ++languageSwitchSequence
+  const localizedExhibit = explainUseCase.selectExplainDetailLanguage(source, lang)
+  const localizedViewModel = toExplainDetailPageViewModel(localizedExhibit)
  selectedAudioLanguage.value = lang
+  detailSource.value = localizedExhibit
+  exhibit.value = localizedViewModel
+  applyDetailText(lang, localizedExhibit.audioText || localizedExhibit.guideText || localizedViewModel.body)
  replaceDetailRouteLanguage(lang)
+
+  if (localizedExhibit.hallId) {
+    resolvedHallId.value = localizedExhibit.hallId
+  }
+
+  if (!shouldSyncAudio || globalAudioPlayer.currentSource.value?.lang === lang) return
+
  languageSwitchLoading.value = true
-
-  const audioSwitch = shouldSyncAudio && globalAudioPlayer.currentSource.value?.lang !== lang
-    ? globalAudioPlayer.switchLanguage(lang)
-    : Promise.resolve(true)
-
  try {
-    if (!request) {
-      applyDetailText(lang)
-      await audioSwitch
-      return
-    }
-
-    const exhibitData = await explainUseCase.enterExplainDetail({
-      ...request,
-      lang
-    })
-    if (requestSequence !== languageSwitchSequence) return
-
-    const nextViewModel = toExplainDetailPageViewModel(exhibitData)
-    exhibit.value = nextViewModel
-    if (exhibitData.hallId) {
-      resolvedHallId.value = exhibitData.hallId
-    }
-
-    void loadFullDetailTextForLanguage(request, lang, nextViewModel)
-    await audioSwitch
-  } catch (error) {
-    if (requestSequence !== languageSwitchSequence) return
-
-    console.warn('讲解语言切换失败:', lang, error)
-    exhibit.value = {
-      ...exhibit.value,
-      audio: {
-        ...exhibit.value.audio,
-        status: 'unavailable',
-        url: undefined,
-        duration: undefined,
+    const nextAudio = localizedViewModel.audio.url
+      ? {
+        id: `stop-${localizedViewModel.audio.playTargetType || 'ITEM'}-${localizedViewModel.audio.playTargetId || localizedViewModel.id}-${lang}`,
+        name: localizedViewModel.title,
+        audioUrl: localizedViewModel.audio.url,
+        image: heroImage.value,
+        duration: localizedViewModel.audio.duration,
        language: lang,
-        unavailableReason: '讲解服务暂不可用，请稍后重试'
+        supportedLanguages: supportedDetailLanguages.value
      }
-    }
-    applyDetailText(lang)
-    uni.showToast({
-      title: '讲解语言切换失败，请稍后重试',
-      icon: 'none'
-    })
+      : null
+    await globalAudioPlayer.switchLanguage(lang, nextAudio)
  } finally {
-    if (requestSequence === languageSwitchSequence) {
-      languageSwitchLoading.value = false
-    }
+    languageSwitchLoading.value = false
  }
 }

--- a/src/repositories/AudioPlayInfoRepository.ts
+++ b/src/repositories/AudioPlayInfoRepository.ts
@@ -72,6 +72,7 @@ const reasonMessageMap: Record<string, string> = {
  NO_GUIDE_STOP: '该展品暂未配置语音讲解',
  NO_GUIDE_CONTENT: '该目标暂无讲解内容',
  NO_TEXT: '当前语言暂无讲解词',
+  LANGUAGE_DISABLED: '该语言暂未开放',
  UNSUPPORTED_LANGUAGE: '不支持该语言',
  UNSUPPORTED_TARGET_TYPE: '该目标类型暂不支持播放',
  TARGET_NOT_FOUND: '该讲解音频暂不可用，当前提供图文讲解',
--- a/src/usecases/explainUseCase.ts
+++ b/src/usecases/explainUseCase.ts
@@ -183,21 +183,29 @@ export class ExplainUseCase {
      }
    }

+    const playable = (variant.playable ?? variant.available) === true && Boolean(variant.audioUrl)
+    const textAvailable = variant.textAvailable ?? (variant.hasText === true || Boolean(variant.text))
+    const guideText = variant.text
+      || (language === 'yue-HK' ? mandarinText : undefined)
+      || `${this.languageLabel(language)}讲解词暂未配置。`
+
    return {
      ...exhibit,
      guideTitle: variant.title || exhibit.guideTitle,
-      guideText: language === 'yue-HK'
-        ? mandarinText || '当前讲解词暂未配置。'
-        : variant.text || `${this.languageLabel(language)}讲解词暂未配置。`,
-      audioUrl: variant.audioUrl,
+      guideText,
+      audioUrl: playable ? variant.audioUrl : undefined,
      audioDuration: variant.audioDuration,
      audioLanguage: language,
-      audioHasText: language === 'yue-HK' ? Boolean(mandarinText) : variant.hasText === true,
-      audioAvailable: variant.available === true && Boolean(variant.audioUrl),
-      audioStatus: variant.available && variant.audioUrl ? 'READY' : 'MISSING',
-      audioUnavailableReason: variant.available && variant.audioUrl
+      audioHasText: textAvailable,
+      audioText: variant.text || undefined,
+      audioTextLength: variant.textLength,
+      audioTextHash: variant.textHash,
+      audioNarrationTier: variant.narrationTier,
+      audioAvailable: playable,
+      audioStatus: variant.audioStatus || (playable ? 'READY' : 'MISSING'),
+      audioUnavailableReason: playable
        ? undefined
-        : `当前讲解暂无${this.languageLabel(language)}音频`,
+        : audioReasonToText(variant.reason || 'NO_PUBLISHED_AUDIO'),
      supportedLanguages
    }
  }
@@ -213,7 +221,27 @@ export class ExplainUseCase {
      : undefined
    const description = stopInfo.description || fallback?.description || '该讲解暂无简介。'
    const audioTarget = this.resolveStopInfoAudioTarget(stopInfo)
-    const audioAvailable = stopInfo.audioStatus === 'READY'
+    const audioVariants = Object.fromEntries(Object.values(stopInfo.languageVariants).map((variant) => [variant.lang, {
+      title: stopInfo.title,
+      text: variant.text,
+      textAvailable: variant.textAvailable,
+      textLength: variant.textLength,
+      textHash: variant.textHash,
+      audioUrl: variant.playUrl,
+      audioDuration: variant.duration,
+      format: variant.format,
+      audioId: variant.audioId,
+      narrationTier: variant.narrationTier,
+      hasText: variant.hasText,
+      enabled: variant.enabled,
+      playable: variant.playable,
+      available: variant.playable,
+      audioStatus: variant.audioStatus,
+      fallback: variant.fallback,
+      reason: variant.reason
+    }]))
+    const currentVariant = audioVariants[stopInfo.lang]
+    const audioAvailable = currentVariant?.playable === true && Boolean(currentVariant.audioUrl)

    return {
      ...(fallback || {}),
@@ -235,21 +263,22 @@ export class ExplainUseCase {
      size: fallback?.size,
      tags: fallback?.tags,
      guideTitle: stopInfo.title || fallback?.guideTitle,
-      guideText: stopInfo.description || fallback?.guideText || fallback?.description,
-      audioUrl: undefined,
-      audioDuration: undefined,
+      guideText: currentVariant?.text || stopInfo.description || fallback?.guideText || fallback?.description,
+      audioUrl: audioAvailable ? currentVariant?.audioUrl : undefined,
+      audioDuration: currentVariant?.audioDuration,
      audioLanguage: stopInfo.lang,
-      audioHasText: stopInfo.hasText,
-      audioText: undefined,
-      audioTextLength: undefined,
-      audioTextHash: undefined,
-      audioNarrationTier: undefined,
+      audioHasText: currentVariant?.textAvailable || stopInfo.hasText,
+      audioText: currentVariant?.text,
+      audioTextLength: currentVariant?.textLength,
+      audioTextHash: currentVariant?.textHash,
+      audioNarrationTier: currentVariant?.narrationTier,
      audioUnavailableReason: audioAvailable
        ? undefined
-        : audioReasonToText(stopInfo.reason || (stopInfo.audioStatus === 'MISSING' ? 'NO_PUBLISHED_AUDIO' : undefined)),
+        : audioReasonToText(currentVariant?.reason || stopInfo.reason || (stopInfo.audioStatus === 'MISSING' ? 'NO_PUBLISHED_AUDIO' : undefined)),
      audioAvailable,
-      audioStatus: stopInfo.audioStatus,
+      audioStatus: currentVariant?.audioStatus || stopInfo.audioStatus,
      supportedLanguages: stopInfo.supportedLanguages,
+      audioVariants,
      imageStatus: stopInfo.imageStatus,
      imageSource: stopInfo.imageSource,
      galleryUrls: stopInfo.imageStatus === 'READY' ? stopInfo.galleryUrls : [],
@@ -434,6 +463,10 @@ export class ExplainUseCase {
    throw stopInfoResult.error || new Error('讲解详情加载失败')
  }

+  selectExplainDetailLanguage(exhibit: MuseumExhibit, language: AudioLanguage) {
+    return this.applyLanguageVariant(exhibit, language)
+  }
+
  async loadExplainDetailText(exhibit: MuseumExhibit): Promise<ExplainTextSelection> {
    const targetType = exhibit.playTargetType || 'ITEM'
    const targetId = exhibit.playTargetId || exhibit.id