4.4 KiB
4.4 KiB
H5 讲解接口只读审计
- 审计时间：2026-08-04（Asia/Shanghai）
- 目标：
https://guide.whaoyue.com:4433/app-api/gis/guide - 认证：无。五个正式
GET接口均可匿名访问。 - 数据安全：仅执行读取请求；未调用删除、覆盖、批量修改或其他写操作。
接口契约
| 接口 | 方法 | 必填项 | 可选项 | 预期响应 |
|---|---|---|---|---|
/catalog/halls |
GET | 无 | lang |
data 为展厅数组 |
/catalog/halls/{hallId}/outlines |
GET | hallId |
lang |
data 为一级单元数组 |
/catalog/outlines/{outlineId}/stops |
GET | outlineId |
lang |
data 为讲解点摘要数组 |
/catalog/halls/{hallId}/stops/page |
GET | hallId |
pageNo、pageSize、lang |
data.list、data.total 分页对象 |
/stops/{stopId} |
GET | stopId |
version（standard / extended，缺省 standard） |
统一详情及当前版本的 textVariants、audioTracks |
执行记录
| 接口 | 场景 / 关键参数 | 预期 | 实际（状态码 / 业务 code / 摘要 / 耗时） | 结论 |
|---|---|---|---|---|
| 展厅列表 | 正常：lang=zh-CN |
8 个展厅摘要 | 200 / 0 / array:8 / 263ms |
通过 |
| 展厅列表 | 缺少可选 lang |
使用默认语言并返回数组 | 200 / 0 / array:8 / 115ms |
通过 |
| 展厅列表 | 非法语言：lang=ja-JP |
文档未明确错误口径 | 200 / 0 / array:8 / 108ms |
通过；服务端宽松接受，需补充文档 |
| 一级单元 | 正常：hallId=715792102100832258、lang=zh-CN |
一级单元数组 | 200 / 0 / array:3 / 95ms |
通过 |
| 一级单元 | 错误非数值 hall ID | 参数错误 | 200 / 400 / 参数类型错误 / 110ms |
通过 |
| 单元讲解点 | 文档示例单元：outlineId=7467940240901013505 |
单元讲解点数组 | 200 / 0 / array:0 / 97ms |
通过；该一级单元当前无讲解点 |
| 单元讲解点 | 详情所属单元：outlineId=865546627916591104 |
包含当前讲解点的数组 | 200 / 0 / array:39 / 132ms |
通过 |
| 单元讲解点 | 错误非数值 outline ID | 参数错误 | 200 / 400 / 参数类型错误 / 113ms |
通过 |
| 展厅讲解点分页 | 正常：pageNo=1&pageSize=20&lang=zh-CN |
分页摘要 | 200 / 0 / list:20,total:39 / 197ms |
通过 |
| 展厅讲解点分页 | 缺少可选分页参数 | 默认 pageNo=1&pageSize=20 |
200 / 0 / list:20,total:39 / 101ms |
通过 |
| 展厅讲解点分页 | 边界：pageNo=999&pageSize=100 |
空页 | 200 / 0 / list:0,total:39 / 171ms |
通过 |
| 展厅讲解点分页 | 非法：pageNo=-1&pageSize=0 |
文档未明确错误口径 | 200 / 0 / list:20,total:39 / 113ms |
通过；服务端回退默认值 |
| 展厅讲解点分页 | 超文档上限：pageSize=101 |
文档声明最大 100 | 200 / 0 / list:39,total:39 / 120ms |
偏差：服务端未限制 |
| 统一详情 | 正常：stopId=865546647764037632&version=standard |
标准版完整详情、正文与音轨 | 200 / 0 / version:standard,textVariants:3,audioTracks:5,recommendedTrackCode:standard.zh-CN.female / 150ms |
通过 |
| 统一详情 | 版本边界：version=extended |
拓展版当前版本详情 | 200 / 0 / version:extended,textVariants:0,audioTracks:0 / 107ms |
通过；该讲解对象暂无拓展版内容 |
| 统一详情 | 缺少可选版本 | 按 standard 返回 |
200 / 0 / version:standard,textVariants:3,audioTracks:5 / 110ms |
通过 |
| 统一详情 | 非法版本：version=unsupported |
业务错误，不静默降级 | 200 / 1020005006 / 讲解点详情版本仅支持 standard / extended / 118ms |
通过 |
| 统一详情 | 非数值错误 ID | 参数错误 | 200 / 400 / 参数类型错误 / 93ms |
通过 |
| 统一详情 | 数值但不存在 ID：999999999999999999 |
GUIDE_STOP_NOT_EXISTS 业务错误 |
200 / 1020005000 / 导览讲解点不存在 / 117ms |
通过 |
数据关联结论
展厅的 3 个一级单元当前均为 stopCount=0，而详情讲解点 865546647764037632 实际属于单元 865546627916591104，该单元可返回 39 条讲解点。这说明一级单元目录与讲解点关联仍存在后端数据不一致。H5 主流程保持为 展厅 -> 讲解对象 -> 统一详情，不以一级单元作为主导航。
统一详情即使参数错误也使用 HTTP 200，客户端必须结合业务 code 判断结果。语言和性别均由当前版本的详情数组在本地切换；切换标准版与拓展版时才重新请求统一详情并传入 version。