47 lines
4.4 KiB
Markdown
47 lines
4.4 KiB
Markdown
# 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`。
|