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