feat: refine guide explain UX and QA docs

src/pages/exhibit/detail.vue

@@ -6,60 +6,141 @@
   >
     <view class="detail-page">
       <scroll-view class="content" scroll-y>
-        <!-- 展品图片 -->
-        <view class="exhibit-hero">
-          <image class="hero-image" :src="exhibit.image" mode="aspectFill" />
-          <view class="audio-control" @tap="handlePlayAudio">
-            <text class="audio-icon">{{ isPlaying ? '⏸' : '▶' }}</text>
+        <view class="detail-hero">
+          <image
+            v-if="heroImage"
+            class="hero-image"
+            :src="heroImage"
+            mode="aspectFill"
+          />
+          <view v-else class="hero-placeholder">
+            <text class="hero-placeholder-text">讲解</text>
+          </view>
+          <view
+            v-if="exhibit.audio.status === 'playable'"
+            class="audio-control"
+            @tap="handlePlayAudio"
+          >
+            <svg v-if="!isPlaying" width="28" height="28" viewBox="0 0 24 24" fill="none">
+              <path d="M8 5V19L19 12L8 5Z" fill="currentColor"/>
+            </svg>
+            <svg v-else width="28" height="28" viewBox="0 0 24 24" fill="none">
+              <rect x="6" y="5" width="4" height="14" rx="1" fill="currentColor"/>
+              <rect x="14" y="5" width="4" height="14" rx="1" fill="currentColor"/>
+            </svg>
+          </view>
+          <view v-else class="audio-status">
+            <text class="audio-status-text">{{ audioStatusText }}</text>
           </view>
         </view>
 
-        <!-- 展品信息 -->
-        <view class="exhibit-info">
-          <text class="exhibit-title">{{ exhibit.name }}</text>
-          <text v-if="exhibit.artist" class="exhibit-artist">{{ exhibit.artist }}</text>
+        <view class="detail-info">
+          <text class="content-type">{{ contentTypeText }}</text>
+          <text class="detail-title">{{ exhibit.title }}</text>
+          <text v-if="exhibit.subtitle" class="detail-subtitle">{{ exhibit.subtitle }}</text>
 
-          <view class="info-grid">
-            <view v-if="exhibit.year" class="info-item">
-              <text class="info-label">创作年代</text>
-              <text class="info-value">{{ exhibit.year }}</text>
+          <view class="meta-grid">
+            <view class="meta-item">
+              <text class="meta-label">内容类型</text>
+              <text class="meta-value">{{ contentTypeText }}</text>
             </view>
-            <view v-if="exhibit.material" class="info-item">
-              <text class="info-label">材质</text>
-              <text class="info-value">{{ exhibit.material }}</text>
+            <view v-if="exhibit.hallName" class="meta-item">
+              <text class="meta-label">所属展厅</text>
+              <text class="meta-value">{{ exhibit.hallName }}</text>
             </view>
-            <view v-if="exhibit.size" class="info-item">
-              <text class="info-label">尺寸</text>
-              <text class="info-value">{{ exhibit.size }}</text>
+            <view v-if="exhibit.floorLabel" class="meta-item">
+              <text class="meta-label">所在楼层</text>
+              <text class="meta-value">{{ exhibit.floorLabel }}</text>
             </view>
-            <view v-if="exhibit.hall" class="info-item">
-              <text class="info-label">展厅位置</text>
-              <text class="info-value">{{ exhibit.hall }}</text>
+            <view class="meta-item">
+              <text class="meta-label">讲解状态</text>
+              <text class="meta-value">{{ audioStatusText }}</text>
             </view>
           </view>
 
-          <view class="description-section">
-            <text class="section-title">作品介绍</text>
-            <text class="description-text">{{ exhibit.description }}</text>
+          <view v-if="exhibit.audio.status !== 'playable'" class="audio-note">
+            <text class="audio-note-title">音频待开放</text>
+            <text class="audio-note-desc">
+              {{ exhibit.audio.unavailableReason || '当前仅提供图文讲解，正式音频接入后将显示播放入口。' }}
+            </text>
+          </view>
+
+          <view class="content-section">
+            <text class="section-title">讲解摘要</text>
+            <text class="section-text">{{ exhibit.summary }}</text>
+          </view>
+
+          <view class="content-section">
+            <text class="section-title">讲解介绍</text>
+            <text class="section-text">{{ exhibit.body }}</text>
+          </view>
+
+          <view class="content-section">
+            <view class="section-header">
+              <text class="section-title">章节</text>
+              <text class="section-state">{{ exhibit.chapters.length ? `${exhibit.chapters.length} 段` : '待开放' }}</text>
+            </view>
+            <view v-if="exhibit.chapters.length" class="chapter-list">
+              <view
+                v-for="chapter in exhibit.chapters"
+                :key="chapter.id"
+                class="chapter-item"
+              >
+                <text class="chapter-title">{{ chapter.title }}</text>
+                <text v-if="typeof chapter.startTime === 'number'" class="chapter-time">
+                  {{ formatChapterTime(chapter.startTime) }}
+                </text>
+              </view>
+            </view>
+            <text v-else class="section-text muted">正式章节数据接入后将在这里展示。</text>
+          </view>
+
+          <view class="content-section">
+            <view class="section-header">
+              <text class="section-title">讲解文稿</text>
+              <text class="section-state">{{ exhibit.transcript ? '已接入' : '待开放' }}</text>
+            </view>
+            <text class="section-text muted">
+              {{ exhibit.transcript || '正式文稿数据接入后将在这里展示。' }}
+            </text>
+          </view>
+
+          <view v-if="exhibit.location" class="location-note">
+            <text class="location-title">位置说明</text>
+            <text class="location-desc">当前支持三维位置预览，馆内路线规划待开放。</text>
           </view>
         </view>
       </scroll-view>
 
-      <!-- 底部操作栏 -->
       <view class="action-bar">
-        <view class="action-btn-group">
-          <view class="action-btn" @tap="handleNavigate">
-            <text class="btn-icon">🗺️</text>
-            <text class="btn-text">查看位置</text>
-          </view>
-          <view class="action-btn" @tap="handleCollect">
-            <text class="btn-icon">{{ isCollected ? '❤️' : '🤍' }}</text>
-            <text class="btn-text">收藏</text>
-          </view>
-          <view class="action-btn" @tap="handleShare">
-            <text class="btn-icon">📤</text>
-            <text class="btn-text">分享</text>
-          </view>
+        <view
+          class="action-btn primary"
+          :class="{ disabled: !exhibit.location }"
+          @tap="handleNavigate"
+        >
+          <svg class="btn-icon" width="18" height="18" viewBox="0 0 24 24" fill="none">
+            <path d="M12 21C12 21 18 14.9 18 9.8C18 6.5 15.3 4 12 4C8.7 4 6 6.5 6 9.8C6 14.9 12 21 12 21Z" stroke="currentColor" stroke-width="1.7"/>
+            <circle cx="12" cy="10" r="2.2" stroke="currentColor" stroke-width="1.7"/>
+          </svg>
+          <text class="btn-text">{{ exhibit.location?.actionText || '暂无位置' }}</text>
+        </view>
+        <view class="action-btn" @tap="handleCollect">
+          <svg class="btn-icon" width="18" height="18" viewBox="0 0 24 24" fill="none">
+            <path
+              :fill="isCollected ? 'currentColor' : 'none'"
+              d="M12 20.2L10.8 19.1C6.4 15.1 3.5 12.5 3.5 9.2C3.5 6.6 5.6 4.5 8.2 4.5C9.7 4.5 11.1 5.2 12 6.3C12.9 5.2 14.3 4.5 15.8 4.5C18.4 4.5 20.5 6.6 20.5 9.2C20.5 12.5 17.6 15.1 13.2 19.1L12 20.2Z"
+              stroke="currentColor"
+              stroke-width="1.7"
+            />
+          </svg>
+          <text class="btn-text">收藏</text>
+        </view>
+        <view class="action-btn" @tap="handleShare">
+          <svg class="btn-icon" width="18" height="18" viewBox="0 0 24 24" fill="none">
+            <path d="M8 12H6.8C5.8 12 5 12.8 5 13.8V18.2C5 19.2 5.8 20 6.8 20H17.2C18.2 20 19 19.2 19 18.2V13.8C19 12.8 18.2 12 17.2 12H16" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>
+            <path d="M12 15V4M12 4L8.5 7.5M12 4L15.5 7.5" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>
+          </svg>
+          <text class="btn-text">分享</text>
         </view>
       </view>
     </view>
@@ -67,15 +148,16 @@
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import { onLoad } from '@dcloudio/uni-app'
 import GuidePageFrame from '@/components/navigation/GuidePageFrame.vue'
 import {
   explainUseCase
 } from '@/usecases/explainUseCase'
 import {
-  toExplainDetailViewModel,
-  type ExplainDetailViewModel
+  toExplainDetailPageViewModel,
+  type ExplainContentType,
+  type ExplainDetailPageViewModel
 } from '@/view-models/explainViewModels'
 import {
   isGuideTopTab,
@@ -83,25 +165,53 @@ import {
   type GuideTopTab
 } from '@/utils/guideTopTabs'
 
-const exhibit = ref<ExplainDetailViewModel>({
+const defaultDetail: ExplainDetailPageViewModel = {
   id: '',
-  name: '展项内容',
-  hall: '展厅位置待补充',
-  image: '/static/exhibit-placeholder.jpg',
-  description: '该展项介绍待正式内容库补充。',
-  hasAudio: false,
-  audioUnavailableReason: '正式讲解音频尚未接入媒体仓储'
-})
+  title: '讲解内容',
+  subtitle: '位置待补充',
+  contentType: 'exhibit',
+  coverImages: ['/static/exhibit-placeholder.jpg'],
+  summary: '该讲解内容待正式内容库补充。',
+  body: '该讲解内容待正式内容库补充。',
+  audio: {
+    status: 'unavailable',
+    unavailableReason: '正式讲解音频尚未接入媒体仓储'
+  },
+  chapters: [],
+  relatedItems: []
+}
 
+const exhibit = ref<ExplainDetailPageViewModel>(defaultDetail)
 const isPlaying = ref(false)
 const isCollected = ref(false)
 const activeTopTab = ref<GuideTopTab>('guide')
 
+const heroImage = computed(() => exhibit.value.coverImages[0])
+const audioStatusText = computed(() => {
+  if (exhibit.value.audio.status === 'playable') {
+    return exhibit.value.audio.durationLabel || '可播放'
+  }
+  if (exhibit.value.audio.status === 'none') {
+    return '图文讲解'
+  }
+  return '音频待开放'
+})
+
+const contentTypeText = computed(() => {
+  const map: Record<ExplainContentType, string> = {
+    hall: '展厅讲解',
+    zone: '展区讲解',
+    exhibit: '讲解点',
+    theme: '主题讲解'
+  }
+  return map[exhibit.value.contentType]
+})
+
 onLoad(async (options: any) => {
   if (options.id) {
     const exhibitData = await explainUseCase.getExhibitById(options.id)
     if (exhibitData) {
-      exhibit.value = toExplainDetailViewModel(exhibitData)
+      exhibit.value = toExplainDetailPageViewModel(exhibitData)
     }
   }
 
@@ -111,35 +221,46 @@ onLoad(async (options: any) => {
   }
 })
 
+const formatChapterTime = (seconds: number) => {
+  const minute = Math.floor(seconds / 60)
+  const second = Math.floor(seconds % 60)
+  return `${minute}:${String(second).padStart(2, '0')}`
+}
+
 const handlePlayAudio = async () => {
   const selection = exhibit.value.id
     ? await explainUseCase.selectAudioForExhibit(exhibit.value.id)
     : null
 
-  uni.showToast({
-    title: selection?.unavailableMessage || exhibit.value.audioUnavailableReason || '该展项暂无讲解音频',
-    icon: 'none'
-  })
+  if (!selection?.playable || !selection.media?.url) {
+    uni.showToast({
+      title: selection?.unavailableMessage || exhibit.value.audio.unavailableReason || '该讲解暂无可播放音频',
+      icon: 'none'
+    })
+    return
+  }
+
+  isPlaying.value = !isPlaying.value
 }
 
 const handleNavigate = () => {
-  if (!exhibit.value.poiId) {
+  if (!exhibit.value.location?.poiId) {
     uni.showToast({
-      title: '该展项暂无三维位置数据',
+      title: '该讲解暂无三维位置数据',
       icon: 'none'
     })
     return
   }
 
   uni.navigateTo({
-    url: `/pages/route/detail?facilityId=${encodeURIComponent(exhibit.value.poiId)}&target=${encodeURIComponent(exhibit.value.name)}&state=preview`
+    url: `/pages/route/detail?facilityId=${encodeURIComponent(exhibit.value.location.poiId)}&target=${encodeURIComponent(exhibit.value.title)}&state=preview`
   })
 }
 
 const handleCollect = () => {
   isCollected.value = !isCollected.value
   uni.showToast({
-    title: isCollected.value ? '已收藏' : '已取消收藏',
+    title: isCollected.value ? '已加入本地收藏' : '已取消本地收藏',
     icon: 'none'
   })
 }
@@ -151,16 +272,17 @@ const handleShare = () => {
 const handleTopTabChange = (tab: GuideTopTab) => {
   navigateToGuideTopTab(tab)
 }
-
 </script>
 
 <style scoped lang="scss">
 .detail-page {
+  position: relative;
   width: 100%;
   height: 100%;
   background-color: var(--museum-bg-light);
   display: flex;
   flex-direction: column;
+  overflow: hidden;
 }
 
 .content {
@@ -168,147 +290,266 @@ const handleTopTabChange = (tab: GuideTopTab) => {
   overflow-y: auto;
 }
 
-.exhibit-hero {
+.detail-hero {
   position: relative;
   width: 100%;
-  height: 450px;
-  background-color: var(--museum-bg-map);
+  height: 250px;
+  background: #edf0ea;
 }
 
-.hero-image {
+.hero-image,
+.hero-placeholder {
   width: 100%;
   height: 100%;
 }
 
-.audio-control {
-  position: absolute;
-  bottom: 20px;
-  right: 20px;
-  width: 64px;
-  height: 64px;
-  background-color: var(--museum-accent);
-  border-radius: 50%;
+.hero-placeholder {
   display: flex;
   align-items: center;
   justify-content: center;
-  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
-  cursor: pointer;
-  transition: all 0.3s;
+  background: #e6eadf;
 }
 
-.audio-control:active {
-  transform: scale(0.95);
-}
-
-.audio-icon {
-  font-size: 28px;
-  color: var(--museum-text-primary);
-}
-
-.exhibit-info {
-  padding: 20px 16px 32px;
-  background-color: var(--museum-bg-surface);
-}
-
-.exhibit-title {
-  font-size: 26px;
+.hero-placeholder-text {
+  font-size: 18px;
   font-weight: 700;
-  color: var(--museum-text-primary);
-  margin-bottom: 6px;
-  display: block;
-  line-height: 1.3;
+  color: #67705f;
 }
 
-.exhibit-artist {
-  font-size: 15px;
-  color: var(--museum-text-secondary);
-  margin-bottom: 20px;
-  display: block;
-}
-
-.info-grid {
-  display: grid;
-  grid-template-columns: 1fr 1fr;
-  gap: 12px 16px;
-  margin-bottom: 20px;
-  padding: 16px;
-  background-color: var(--museum-bg-light);
-  border-radius: var(--radius-card);
-}
-
-.info-item {
+.audio-control {
+  position: absolute;
+  right: 20px;
+  bottom: 18px;
+  width: 58px;
+  height: 58px;
   display: flex;
-  flex-direction: column;
-  gap: 6px;
+  align-items: center;
+  justify-content: center;
+  background-color: var(--museum-accent);
+  border-radius: 50%;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.18);
+  color: #151713;
 }
 
-.info-label {
+.audio-status {
+  position: absolute;
+  right: 16px;
+  bottom: 16px;
+  height: 32px;
+  padding: 0 12px;
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  background: rgba(21, 23, 19, 0.86);
+  border-radius: 8px;
+}
+
+.audio-status-text {
   font-size: 12px;
-  color: var(--museum-text-disabled);
-  font-weight: 500;
+  font-weight: 600;
+  color: #ffffff;
 }
 
-.info-value {
+.detail-info {
+  padding: 22px 16px 116px;
+  box-sizing: border-box;
+}
+
+.content-type,
+.detail-title,
+.detail-subtitle,
+.section-title,
+.section-text,
+.audio-note-title,
+.audio-note-desc,
+.location-title,
+.location-desc {
+  display: block;
+}
+
+.content-type {
+  font-size: 12px;
+  line-height: 16px;
+  color: #68725d;
+}
+
+.detail-title {
+  margin-top: 4px;
+  font-size: 24px;
+  line-height: 32px;
+  font-weight: 700;
+  color: #151713;
+}
+
+.detail-subtitle {
+  margin-top: 6px;
   font-size: 14px;
-  color: var(--museum-text-primary);
-  font-weight: 400;
+  line-height: 20px;
+  color: #68725d;
 }
 
-.description-section {
-  margin-top: 20px;
+.meta-grid {
+  margin-top: 18px;
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+
+.meta-item {
+  min-height: 62px;
+  padding: 10px 12px;
+  box-sizing: border-box;
+  background: #f7f8f3;
+  border: 1px solid #ebece5;
+  border-radius: 8px;
+}
+
+.meta-label,
+.meta-value {
+  display: block;
+}
+
+.meta-label {
+  font-size: 12px;
+  line-height: 16px;
+  color: #818a7a;
+}
+
+.meta-value {
+  margin-top: 4px;
+  font-size: 14px;
+  line-height: 20px;
+  color: #151713;
+}
+
+.audio-note,
+.location-note {
+  margin-top: 14px;
+  padding: 12px;
+  box-sizing: border-box;
+  background: #f1f4ea;
+  border: 1px solid #e2e7d7;
+  border-radius: 8px;
+}
+
+.audio-note-title,
+.location-title {
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 700;
+  color: #151713;
+}
+
+.audio-note-desc,
+.location-desc {
+  margin-top: 4px;
+  font-size: 12px;
+  line-height: 18px;
+  color: #5d6656;
+}
+
+.content-section {
+  margin-top: 22px;
+}
+
+.section-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
 }
 
 .section-title {
   font-size: 17px;
-  font-weight: 600;
-  color: var(--museum-text-primary);
-  margin-bottom: 10px;
-  display: block;
+  line-height: 24px;
+  font-weight: 700;
+  color: #151713;
 }
 
-.description-text {
+.section-state {
+  font-size: 12px;
+  color: #818a7a;
+}
+
+.section-text {
+  margin-top: 10px;
   font-size: 14px;
-  line-height: 1.7;
-  color: var(--museum-text-secondary);
+  line-height: 24px;
+  color: #333a2f;
+}
+
+.section-text.muted {
+  color: #818a7a;
+}
+
+.chapter-list {
+  margin-top: 10px;
+}
+
+.chapter-item {
+  min-height: 44px;
+  padding: 0 12px;
+  margin-bottom: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  box-sizing: border-box;
+  background: #f7f8f3;
+  border-radius: 8px;
+}
+
+.chapter-title {
+  font-size: 14px;
+  color: #151713;
+}
+
+.chapter-time {
+  font-size: 12px;
+  color: #818a7a;
 }
 
 .action-bar {
-  background-color: var(--museum-bg-surface);
-  border-top: 1px solid var(--museum-border-light);
-  padding: 8px 16px;
-  padding-bottom: calc(8px + env(safe-area-inset-bottom));
-}
-
-.action-btn-group {
-  display: flex;
+  flex-shrink: 0;
+  padding: 10px 12px calc(10px + env(safe-area-inset-bottom));
+  display: grid;
+  grid-template-columns: 1.4fr 1fr 1fr;
   gap: 8px;
+  box-sizing: border-box;
+  background: rgba(255, 255, 255, 0.96);
+  border-top: 1px solid #e7e9e0;
 }
 
 .action-btn {
-  flex: 1;
+  height: 46px;
   display: flex;
-  flex-direction: column;
   align-items: center;
+  justify-content: center;
   gap: 6px;
-  padding: 10px 8px;
-  background-color: var(--museum-bg-light);
-  border-radius: var(--radius-button);
-  cursor: pointer;
-  transition: all 0.2s;
+  box-sizing: border-box;
+  background: #f7f8f3;
+  border: 1px solid #e5e8df;
+  border-radius: 8px;
+  color: #151713;
 }
 
-.action-btn:active {
-  background-color: var(--museum-border-light);
-  transform: scale(0.98);
+.action-btn.primary {
+  background: #151713;
+  border-color: #151713;
+  color: var(--museum-accent);
+}
+
+.action-btn.disabled {
+  background: #f1f3ed;
+  border-color: #e5e8df;
+  color: #8b9385;
 }
 
 .btn-icon {
-  font-size: 22px;
+  flex-shrink: 0;
 }
 
 .btn-text {
-  font-size: 11px;
-  color: var(--museum-text-secondary);
-  font-weight: 500;
+  font-size: 13px;
+  font-weight: 600;
+  color: currentColor;
 }
 </style>