lyf/frontend-miniapp
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

chore: sync latest project updates
Some checks failed
CI / verify (push) Has been cancelled
Details

Browse Source
This commit is contained in:
lyf
2026-07-03 14:42:38 +08:00
parent 8b2c36677e
commit 8fed715235
106 changed files with 6030 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files

387
docs/QA/miniapp-guide-api-test-results-2026-07-02.md Normal file
View File

@@ -0,0 +1,387 @@
# 小程序讲解接口测试结果记录
测试日期：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` 的连通性。