388 lines
9.5 KiB
Markdown
388 lines
9.5 KiB
Markdown
# 小程序讲解接口测试结果记录
|
||
|
||
测试日期：2026-07-02
|
||
|
||
## 1. 测试目标
|
||
|
||
验证小程序讲解业务接口在不同基础地址下的可访问性、实际响应数据和当前失败原因，重点关注：
|
||
|
||
- 展厅列表
|
||
- 展厅导览点列表
|
||
- 讲解详情 `stop-info`
|
||
- 音频播放信息 `play-info`
|
||
- 讲解词正文 `text-info`
|
||
|
||
## 2. 测试基础地址
|
||
|
||
| 基础地址 | 测试结果 | 说明 |
|
||
| --- | --- | --- |
|
||
| `http://1.92.206.90:3001` | 可访问 | 当前公网可用的小程序接口入口 |
|
||
| `http://1.92.206.90:48080/yudao-server/` | 公网超时 | 外网访问 `48080` 连接超时 |
|
||
| `http://127.0.0.1:48080/yudao-server/` | 服务器本机可访问 | Java/Apusic 后端实际本机入口 |
|
||
| `https://guide.whaoyue.com/app-api` | 可访问 | 经 Nginx 转发到 `3001/app-api` |
|
||
| `https://guide.whaoyue.com/yudao-server/app-api` | 502 | Nginx 容器无法连接宿主 `48080` |
|
||
|
||
## 3. 实际后端路径判断
|
||
|
||
Java 后端实际上下文路径为：
|
||
|
||
```text
|
||
http://127.0.0.1:48080/yudao-server/app-api
|
||
```
|
||
|
||
公网当前稳定可用路径为：
|
||
|
||
```text
|
||
http://1.92.206.90:3001/app-api
|
||
https://guide.whaoyue.com/app-api
|
||
```
|
||
|
||
直接访问以下地址不可用：
|
||
|
||
```text
|
||
http://1.92.206.90:48080/yudao-server/app-api
|
||
```
|
||
|
||
表现为连接超时。
|
||
|
||
## 4. 测试接口与结果
|
||
|
||
本轮以 `http://1.92.206.90:3001` 为主要公网基础地址。
|
||
|
||
| 接口 | 测试 URL | HTTP | 业务结果 | 结论 |
|
||
| --- | --- | --- | --- | --- |
|
||
| 展厅列表 | `/app-api/gis/hall/list` | 200 | `code=0`，返回 8 个展厅 | 正常 |
|
||
| 宇宙厅导览点 | `/app-api/gis/sdk/halls/715792102100832258/guide-stops` | 200 | `code=0`，返回 2 个导览点 | 正常 |
|
||
| 展厅分区 | `/app-api/gis/zone/list-by-hall?hallId=715792102100832258` | 200 | `code=0`，返回空数组 | 接口正常，当前无数据 |
|
||
| 讲解详情 | `/app-api/gis/guide/stop/info?targetType=STOP&targetId=1823450596808612&lang=zh-CN` | 200 | `code=404`，接口不存在 | 异常 |
|
||
| 播放信息 | `/app-api/gis/guide/audio/play-info?targetType=STOP&targetId=1823450596808612&lang=zh-CN` | 200 | `code=0`，`playable=false`，`reason=TARGET_NOT_FOUND` | 路由存在，数据不可用 |
|
||
| 讲解词正文 | `/app-api/gis/guide/audio/text-info?targetType=STOP&targetId=1823450596808612&lang=zh-CN` | 200 | `code=0`，`available=false`，`reason=TARGET_NOT_FOUND` | 路由存在，数据不可用 |
|
||
|
||
## 5. 实际返回数据
|
||
|
||
### 5.1 展厅列表
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/hall/list"
|
||
```
|
||
|
||
核心响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": [
|
||
{ "id": "715792102100832258", "hallCode": "E1", "name": "宇宙厅" },
|
||
{ "id": "715792102100832257", "hallCode": "E2", "name": "地球厅" },
|
||
{ "id": "715792102100832259", "hallCode": "E3", "name": "演化厅" },
|
||
{ "id": "715792102100832260", "hallCode": "E4", "name": "恐龙厅" },
|
||
{ "id": "715792102100832256", "hallCode": "E5", "name": "人类厅" },
|
||
{ "id": "715792102100832261", "hallCode": "E6", "name": "生物厅" },
|
||
{ "id": "715792102100832262", "hallCode": "E7", "name": "生态厅" },
|
||
{ "id": "715792102100832263", "hallCode": "E8", "name": "家园厅" }
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.2 宇宙厅导览点
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/sdk/halls/715792102100832258/guide-stops"
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": [
|
||
{
|
||
"id": "1823450596808612",
|
||
"name": "古典星盘 讲解",
|
||
"type": "guide_stop",
|
||
"typeName": "讲解点",
|
||
"floorId": "2065808920714276866",
|
||
"position": {
|
||
"x": -107.86390357145089,
|
||
"y": 0.0,
|
||
"z": 42.1015203335146
|
||
},
|
||
"targetType": "GUIDE_STOP",
|
||
"targetId": "1823450596808612",
|
||
"audioUrl": null,
|
||
"coverImageUrl": null,
|
||
"description": null,
|
||
"status": "ACTIVE",
|
||
"located": true,
|
||
"hasAudio": false,
|
||
"poiId": null,
|
||
"outlineId": "7467940240901013505",
|
||
"outlineName": "第一单元：仰望苍穹——人类对宇宙认识的历程",
|
||
"hallId": "715792102100832258",
|
||
"hallName": "宇宙厅",
|
||
"sort": 0,
|
||
"routeId": null,
|
||
"routeName": null,
|
||
"seqOrder": null,
|
||
"stayMinutes": null
|
||
},
|
||
{
|
||
"id": "1823450596814245",
|
||
"name": "火星提森特陨石 讲解",
|
||
"type": "guide_stop",
|
||
"typeName": "讲解点",
|
||
"floorId": "2065808920714276866",
|
||
"position": {
|
||
"x": -94.37030868849183,
|
||
"y": 0.0,
|
||
"z": 41.8425968285253
|
||
},
|
||
"targetType": "GUIDE_STOP",
|
||
"targetId": "1823450596814245",
|
||
"audioUrl": null,
|
||
"coverImageUrl": null,
|
||
"description": null,
|
||
"status": "ACTIVE",
|
||
"located": true,
|
||
"hasAudio": false,
|
||
"poiId": null,
|
||
"outlineId": "7467940240901013507",
|
||
"outlineName": "第三单元：采石知天——行星科学与深空探测",
|
||
"hallId": "715792102100832258",
|
||
"hallName": "宇宙厅",
|
||
"sort": 0,
|
||
"routeId": null,
|
||
"routeName": null,
|
||
"seqOrder": null,
|
||
"stayMinutes": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.3 展厅分区
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/zone/list-by-hall?hallId=715792102100832258"
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": []
|
||
}
|
||
```
|
||
|
||
### 5.4 stop-info
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/guide/stop/info?targetType=STOP&targetId=1823450596808612&lang=zh-CN"
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"msg": "请求地址不存在:app-api/gis/guide/stop/info",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
文档样例 `targetType=ITEM&targetId=1001` 结果一致：
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"msg": "请求地址不存在:app-api/gis/guide/stop/info",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 5.5 play-info
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/guide/audio/play-info?targetType=STOP&targetId=1823450596808612&lang=zh-CN"
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"playable": false,
|
||
"targetType": "STOP",
|
||
"targetId": 1823450596808612,
|
||
"lang": "zh-CN",
|
||
"narrationTier": "STANDARD",
|
||
"audioId": null,
|
||
"title": null,
|
||
"duration": null,
|
||
"format": null,
|
||
"playUrl": null,
|
||
"expiresAt": null,
|
||
"subtitleUrl": null,
|
||
"hasText": false,
|
||
"fallback": false,
|
||
"fallbackReason": null,
|
||
"reason": "TARGET_NOT_FOUND"
|
||
}
|
||
}
|
||
```
|
||
|
||
文档样例 `targetType=ITEM&targetId=1001` 响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"playable": false,
|
||
"targetType": "ITEM",
|
||
"targetId": 1001,
|
||
"lang": "zh-CN",
|
||
"narrationTier": "STANDARD",
|
||
"audioId": null,
|
||
"title": null,
|
||
"duration": null,
|
||
"format": null,
|
||
"playUrl": null,
|
||
"expiresAt": null,
|
||
"subtitleUrl": null,
|
||
"hasText": false,
|
||
"fallback": false,
|
||
"fallbackReason": null,
|
||
"reason": "TARGET_NOT_FOUND"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.6 text-info
|
||
|
||
请求：
|
||
|
||
```bash
|
||
curl "http://1.92.206.90:3001/app-api/gis/guide/audio/text-info?targetType=STOP&targetId=1823450596808612&lang=zh-CN"
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"available": false,
|
||
"targetType": "STOP",
|
||
"targetId": 1823450596808612,
|
||
"lang": "zh-CN",
|
||
"narrationTier": "STANDARD",
|
||
"title": null,
|
||
"text": null,
|
||
"textLength": null,
|
||
"textHash": null,
|
||
"reason": "TARGET_NOT_FOUND"
|
||
}
|
||
}
|
||
```
|
||
|
||
文档样例 `targetType=ITEM&targetId=1001` 响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"msg": "",
|
||
"data": {
|
||
"available": false,
|
||
"targetType": "ITEM",
|
||
"targetId": 1001,
|
||
"lang": "zh-CN",
|
||
"narrationTier": "STANDARD",
|
||
"title": null,
|
||
"text": null,
|
||
"textLength": null,
|
||
"textHash": null,
|
||
"reason": "TARGET_NOT_FOUND"
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 服务器侧补充验证
|
||
|
||
服务器监听情况：
|
||
|
||
```text
|
||
3001 -> next-server
|
||
48080 -> Java/Apusic
|
||
80/443 -> Docker Nginx
|
||
```
|
||
|
||
Nginx 转发配置显示：
|
||
|
||
```text
|
||
/app-api/ -> http://172.17.0.1:3001/app-api/
|
||
/yudao-server/app-api/ -> http://172.17.0.1:48080/yudao-server/app-api/
|
||
```
|
||
|
||
但 Nginx 容器访问宿主 `48080` 失败，因此：
|
||
|
||
```text
|
||
https://guide.whaoyue.com/yudao-server/app-api/... -> 502
|
||
```
|
||
|
||
部署包检查显示当前 app 端存在：
|
||
|
||
```text
|
||
/gis/guide/audio/play-info
|
||
/gis/guide/audio/summary
|
||
/gis/guide/audio/text-info
|
||
```
|
||
|
||
未发现 app 端：
|
||
|
||
```text
|
||
/gis/guide/stop/info
|
||
```
|
||
|
||
后台管理端存在 `GuideStopController`，但映射为：
|
||
|
||
```text
|
||
/gis/guide-stop
|
||
```
|
||
|
||
并且属于后台权限接口，不等同于小程序 app 端 `stop-info`。
|
||
|
||
## 7. 结论
|
||
|
||
1. `http://1.92.206.90:3001` 是当前可用的小程序公网接口基础地址。
|
||
2. `http://1.92.206.90:48080/yudao-server/` 当前公网不可用，连接超时。
|
||
3. 展厅列表和导览点列表接口可正常返回实际数据。
|
||
4. 当前 `宇宙厅` 返回 2 个导览点，但 `hasAudio=false`。
|
||
5. `stop-info` 接口在当前后端部署中不存在，是讲解详情加载失败的直接原因。
|
||
6. `play-info` 和 `text-info` 路由存在，但对当前测试 ID 返回 `TARGET_NOT_FOUND`，没有可播放音频和讲解词正文。
|
||
|
||
## 8. 建议处理
|
||
|
||
1. 前端公网环境继续使用 `http://1.92.206.90:3001/app-api` 或域名 `/app-api` 通道。
|
||
2. 后端需要补充或重新部署 app 端 `GET /app-api/gis/guide/stop/info` 接口。
|
||
3. 如果文档中的 `stop-info` 已废弃，需要同步更新接口说明和前端调用逻辑。
|
||
4. 后端需要为至少一个真实导览点发布音频和讲解词，用于验证 `playable=true` 与 `available=true` 的正向链路。
|
||
5. 若计划开放 `48080/yudao-server` 公网访问，需要同步检查安全组、防火墙和 Nginx 容器到宿主 `48080` 的连通性。
|