# 小程序导览接口对接说明

> 统一维护约定：本文档是小程序对接的固定主文档。后续新增小程序 API、展示、播放、讲解词、异常处理和联调说明时，统一修订本文档，不再按单个功能新建小程序对接文档。

## 0. 快速接入

小程序导览页使用 3 个接口：

| 场景 | 接口 | 用途 |
| --- | --- | --- |
| 进入讲解页 | `stop-info` | 获取标题、简介、图片、绑定展品、当前语言音频/正文状态 |
| 点击播放 | `play-info` | 获取唯一可播放 `playUrl` |
| 展开正文 | `text-info` | 按需获取讲解词全文 |

推荐顺序：

1. 页面进入先调 `stop-info`。
2. 根据 `stop-info.audioStatus` 决定播放按钮是否可点。
3. 用户点击播放时再调 `play-info`。
4. 用户展开正文时再调 `text-info`。

## 1. 通用参数

三个接口都使用同一组参数：

| 参数 | 是否必填 | 取值 | 说明 |
| --- | --- | --- | --- |
| `targetType` | 是 | `ITEM` / `STOP` | `ITEM` 表示展品入口，`STOP` 表示讲解点入口 |
| `targetId` | 是 | number | 必须和 `targetType` 匹配 |
| `lang` | 否 | `zh-CN` / `en-US` | 不传默认 `zh-CN` |

调用示例：

```http
GET /app-api/gis/guide/stop/info?targetType=ITEM&targetId=1001&lang=zh-CN
GET /app-api/gis/guide/audio/play-info?targetType=ITEM&targetId=1001&lang=zh-CN
GET /app-api/gis/guide/audio/text-info?targetType=ITEM&targetId=1001&lang=zh-CN
```

注意：

- `targetType=ITEM` 时，`targetId` 传展品 ID。
- `targetType=STOP` 时，`targetId` 传讲解点 ID。
- 小程序建议始终显式传 `lang`，语言切换后所有请求使用新的 `lang`。
- 不要传 `standard`、`extended`、`businessId`、MinIO 路径或四通道音频 URL。

## 2. stop-info：讲解页展示信息

```http
GET /app-api/gis/guide/stop/info?targetType=ITEM&targetId=1001&lang=zh-CN
```

成功响应：

```json
{
  "code": 0,
  "data": {
    "available": true,
    "targetType": "ITEM",
    "targetId": 1001,
    "resolvedStopId": 2001,
    "lang": "zh-CN",
    "title": "青铜神树",
    "description": "本讲解点介绍三星堆出土的青铜神树……",
    "coverImageUrl": "https://cdn.example.com/cover.jpg",
    "galleryUrls": "[\"https://cdn.example.com/a.jpg\",\"https://cdn.example.com/b.jpg\"]",
    "imageStatus": "READY",
    "imageSource": "STOP",
    "linkedExhibits": [
      {
        "id": 1001,
        "name": "青铜神树",
        "nameEn": "Bronze Sacred Tree",
        "exhibitCode": "EX-001",
        "coverImageUrl": "https://cdn.example.com/exhibit-cover.jpg"
      }
    ],
    "playTargetType": "STOP",
    "playTargetId": 2001,
    "hasAudio": true,
    "hasText": true,
    "supportedLanguages": ["zh-CN", "en-US"],
    "audioStatus": "READY",
    "reason": null
  }
}
```

不可用响应仍返回 `code=0`：

```json
{
  "code": 0,
  "data": {
    "available": false,
    "targetType": "ITEM",
    "targetId": 9999,
    "lang": "zh-CN",
    "imageStatus": "MISSING",
    "imageSource": "NONE",
    "linkedExhibits": [],
    "hasAudio": false,
    "hasText": false,
    "supportedLanguages": [],
    "audioStatus": "MISSING",
    "reason": "NO_GUIDE_STOP"
  }
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `available` | 是否有可展示的讲解点 |
| `resolvedStopId` | 最终解析到的讲解点 ID |
| `coverImageUrl` | 讲解点封面图 |
| `galleryUrls` | 讲解点图集，JSON 字符串数组，客户端需安全解析 |
| `imageStatus` | `READY` / `MISSING` |
| `linkedExhibits` | 当前讲解点绑定的展品列表 |
| `playTargetType` / `playTargetId` | 调用 `play-info`、`text-info` 时推荐使用的目标 |
| `hasAudio` | 是否存在任一语言音频 |
| `supportedLanguages` | 有音频的语言列表 |
| `audioStatus` | 当前请求语言是否可播放：`READY` / `MISSING` |
| `hasText` | 当前语言是否有讲解词正文 |
| `reason` | 不可用原因 |

图片规则：

- `imageStatus=READY`：使用 `coverImageUrl` 和 `galleryUrls` 渲染讲解点图片。
- `imageStatus=MISSING`：展示占位图或隐藏图片区域。
- 不要用 `linkedExhibits[*].coverImageUrl` 兜底讲解点主图。

音频按钮规则：

- 播放按钮以 `audioStatus` 为准。
- `hasAudio=true` 只表示存在任一语言音频，不代表当前语言可播放。
- 如果 `audioStatus=MISSING`，当前语言播放按钮置灰。

## 3. play-info：音频播放

```http
GET /app-api/gis/guide/audio/play-info?targetType=STOP&targetId=2001&lang=zh-CN
```

可播放响应：

```json
{
  "code": 0,
  "data": {
    "playable": true,
    "targetType": "STOP",
    "targetId": 2001,
    "lang": "zh-CN",
    "narrationTier": "STANDARD",
    "audioId": 8912,
    "title": "青铜神树",
    "duration": 120,
    "format": "mp3",
    "playUrl": "https://cdn.museum.com/tts-audio/xxx.mp3",
    "expiresAt": null,
    "subtitleUrl": null,
    "hasText": true,
    "fallback": false,
    "fallbackReason": null,
    "reason": null
  }
}
```

不可播放响应仍返回 `code=0`：

```json
{
  "code": 0,
  "data": {
    "playable": false,
    "targetType": "STOP",
    "targetId": 2001,
    "lang": "en-US",
    "narrationTier": "STANDARD",
    "hasText": false,
    "fallback": false,
    "reason": "NO_PUBLISHED_AUDIO"
  }
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `playable` | 是否可播放 |
| `playUrl` | 可直接赋值给小程序音频组件的地址 |
| `expiresAt` | 播放地址过期时间；为空表示当前地址无短期过期限制 |
| `duration` | 音频时长，单位秒 |
| `format` | 音频格式 |
| `hasText` | 是否有同语言讲解词正文 |
| `reason` | 不可播放原因 |

播放失败处理：

- `playable=false`：不启动播放器，按 `reason` 展示提示。
- `playUrl` 播放失败、403、404 或疑似过期：重新请求一次 `play-info`。
- 请求英文没有音频时，不要自动播放中文音频。

## 4. text-info：讲解词正文

```http
GET /app-api/gis/guide/audio/text-info?targetType=STOP&targetId=2001&lang=zh-CN
```

可用响应：

```json
{
  "code": 0,
  "data": {
    "available": true,
    "targetType": "STOP",
    "targetId": 2001,
    "lang": "zh-CN",
    "narrationTier": "STANDARD",
    "title": "青铜神树",
    "text": "青铜神树是三星堆遗址出土的重要青铜器...",
    "textLength": 1200,
    "textHash": "0b32a4..."
  }
}
```

不可用响应仍返回 `code=0`：

```json
{
  "code": 0,
  "data": {
    "available": false,
    "targetType": "STOP",
    "targetId": 2001,
    "lang": "en-US",
    "narrationTier": "STANDARD",
    "reason": "NO_TEXT"
  }
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `available` | 是否有正文 |
| `text` | 讲解词正文 |
| `textLength` | 正文字数 |
| `textHash` | 正文版本标识，可用于本地缓存判断 |
| `reason` | 不可用原因 |

正文建议按需加载，不需要在页面进入时强制请求。

## 5. 页面推荐流程

```ts
async function enterGuidePage(targetType: "ITEM" | "STOP", targetId: number) {
  const lang = getGlobalLanguage() || "zh-CN"
  const stopInfo = await api.getGuideStopInfo({ targetType, targetId, lang })

  if (!stopInfo.available) {
    showStopUnavailable(stopInfo.reason)
    return
  }

  renderStopPage({
    title: stopInfo.title,
    description: stopInfo.description,
    cover: stopInfo.coverImageUrl,
    gallery: parseJsonArraySafely(stopInfo.galleryUrls),
    imageStatus: stopInfo.imageStatus,
    linkedExhibits: stopInfo.linkedExhibits
  })

  setPlayButtonEnabled(stopInfo.audioStatus === "READY")

  bindPlayButton(async () => {
    if (stopInfo.audioStatus !== "READY") {
      showToast("当前语言暂无可播放音频")
      return
    }

    const playInfo = await api.getAudioPlayInfo({
      targetType: stopInfo.playTargetType,
      targetId: stopInfo.playTargetId,
      lang
    })

    if (!playInfo.playable || !playInfo.playUrl) {
      showToast(reasonToText(playInfo.reason))
      return
    }

    audioContext.src = playInfo.playUrl
    audioContext.title = playInfo.title || ""
    audioContext.play()
  })

  bindExpandText(async () => {
    if (!stopInfo.hasText) return

    const textInfo = await api.getAudioTextInfo({
      targetType: stopInfo.playTargetType,
      targetId: stopInfo.playTargetId,
      lang
    })

    if (textInfo.available) {
      renderNarrationText(textInfo.text)
    }
  })
}
```

## 6. reason 处理建议

| reason | 建议提示 |
| --- | --- |
| `NO_GUIDE_STOP` | 该展品暂未配置讲解 |
| `NO_GUIDE_CONTENT` | 该讲解点暂无讲解内容 |
| `NO_PUBLISHED_AUDIO` | 当前语言暂无语音讲解 |
| `NO_TEXT` | 当前语言暂无讲解词 |
| `UNSUPPORTED_LANGUAGE` | 暂不支持该语言 |
| `UNSUPPORTED_TARGET_TYPE` | 暂不支持该目标类型 |
| `TARGET_NOT_FOUND` | 内容不存在或已下架 |

小程序可根据页面语气调整文案，但不要把以上业务空态当成系统异常弹窗。

## 7. 小程序本地缓存建议

播放信息：

- key：`targetType + targetId + lang`
- 语言切换后清理旧语言缓存。
- 播放失败、403、404 或 URL 过期时，重新请求一次 `play-info`。

讲解词正文：

- key：`targetType + targetId + lang`
- value：`text + textHash`
- 再次请求后如果 `textHash` 变化，替换本地正文。
- 不建议长期永久缓存正文。

## 8. 联调检查清单

- 不传 `lang`：三个接口默认按 `zh-CN` 返回。
- 进入讲解页：先调 `stop-info`，不要用 `play-info` 承担图片、简介、绑定展品展示。
- 图片存在：`imageStatus=READY`，使用讲解点图片渲染。
- 图片缺失：`imageStatus=MISSING`，展示占位或隐藏图片区。
- 当前语言可播放：`audioStatus=READY`，播放按钮可点。
- 只有其他语言音频：`hasAudio=true` 且 `audioStatus=MISSING`，当前语言播放按钮不可点。
- 点击播放：`play-info.playable=true` 时设置 `audio.src=playUrl`。
- 英文缺音频：返回 `NO_PUBLISHED_AUDIO`，不自动播放中文。
- 展开正文：`text-info.available=true` 时渲染正文。
- 英文缺正文：返回 `NO_TEXT`，不影响音频播放。
- 展品未绑定讲解点：返回 `NO_GUIDE_STOP`。
- 播放地址失效：重新请求一次 `play-info`。