# 91av 页面接口对照

核对日期：2026-10-21。来源：[当前 Swagger](https://91av-wz.80sygtm.com/swagger/index.html)。上游地址通过 `UPSTREAM_API_URL` 配置，默认 `https://webhgcgapi.mfcg.me`；下表省略 `/api/app/` 前缀。

| 页面 | 接口及关键参数 |
| --- | --- |
| 顶部、侧栏和移动导航 | `navigation/header`；使用 `categoryList` 的顺序、`name,urlValue,icon,categoryType,translationList`。1 为 URL、2 为二级导航，3 不混入主导航；不生成固定菜单 |
| 首页 | `playlet/home`；轮播 `homeBannerData`，栏目 `homeConfigData`，广告 `advitise` |
| 短剧列表 | `playlet/all/list`；`pageNum,pageSize,sortType`，排序 1 最新、2 热播、3 独家、4 随机 |
| 三个排行榜 | `playlet/hot/rank/list`；`rankType` 分别为 1 热播、2 新剧、3 追剧，分页使用 `pageNum,pageSize` |
| 专题列表 | `playlet/topic/list`；`pageNum,pageSize`，没有专题分类和排序参数 |
| 专题详情、题材页 | `playlet/topic/detail`；`id,pageNum,pageSize`。当前服务的题材和专题使用同一 ID；不再向全量列表传会被忽略的 `themeId` |
| 标签页 | `playlet/tag/list`；`tagSlug` 或 `tagId`，以及 `pageNum,pageSize,sortType` |
| 首页“更多” | 优先使用 `moreUrl`，继续视为站内业务入口。未配置时使用 `/config/{slug或id}/`，从 `playlet/home.homeConfigData` 按 slug 或 ID 提取对应已启用栏目；只展示实际返回的条目，不伪造完整目录或后续分页 |
| 搜索结果 | `playlet/search`；`keyword,pageNum,pageSize`。无结果优先展示 `everyoneWatching`，缺少推荐时读取 `playlet/hot/list` |
| 搜索联想 | `playlet/search/suggest`；`keyword`，返回短剧对象，点击进入实际详情页；热搜词继续进入搜索页 |
| 搜索推荐换一批 | `playlet/all/list`；`sortType=4` 随机获取，避免缺少必填的短剧 ID |
| 短剧详情 | `playlet/detail` 传 `slug` 或 `id`；`playlet/chapter/list` 传 `playletSlug` 或 `playletId` |
| 详情推荐 | `playlet/guess-like/list`；必须传当前 `playletId`，不依赖详情中未定义的推荐字段 |
| 章节播放 | `playlet/chapter/detail`；`chapterId` 加 `playletSlug` 或 `playletId`，使用实时观看权限、费用、余额及视频地址。章节 SEO 优先于整剧 SEO |
| 福利应用 | `applist/list?categoryId=…`；保留分类锚点及空分类隐藏逻辑 |
| 回家的路、独立导航 | 站点地址固定 `https://huangguocg.com/`，联系方式固定官方 TG `@jbd125`；`config/info` 只提供导航介绍和 App 链接，没有 App 地址时隐藏下载入口 |
| 关于等六个信息页 | 按既有要求保留 HTML 静态正文；联系我们与 DMCA 只展示官方 TG `@jbd125` |

## 写接口

2026-10-22 本项目（`JHA-1047`）调整内容地址：链接优先使用非空 slug，缺少时使用 ID，保留尾斜杠和独立分页。专题详情接口仍必填 ID，slug 路由先分页查询专题目录解析 ID，再读取详情；目录故障返回服务错误，不伪装成专题不存在。详情评论和推荐等只支持数字 ID 的接口在详情返回后使用真实 ID；支持 slug 的章节请求继续并行。canonical、面包屑、选集和 ItemList 使用对应主地址，旧 ID 地址不新增转向 slug 的重定向。

只使用游客会话 `auth/guest`，凭证保存在 HttpOnly Cookie；登录、注册、找回密码、资料修改、充值/VIP 下单和章节解锁已删除，代理不再放行。整剧点赞/收藏传 `id` 和布尔状态，章节点赞/收藏只传 `chapterId` 和布尔状态。评论发送、点赞、观看报告的字段按各自请求模型发送。


## 已移除的旧接口依赖

`playlet/operate/list`、`playlet/home/config/detail/list`、`video/all/list` 在实际游客身份下返回 HTTP 404，且不在当前文档内。其余旧 `video/*`、`playlet/rank`、`playlet/today-update` 也不再开放代理。

当前文档没有独立视频列表和详情接口。按用户要求移除“剧集”的桌面、侧栏、移动导航入口及 `/series/`、`/video/{id}/` 路由（含分页）；旧地址直接返回 404，不转换或重定向。首页和结构化数据不再输出旧类型的独立视频栏目。短剧详情、选集和章节播放继续保留。

## 验证方式

页面请求采用服务端渲染：服务端先准备会话与当前页数据，再直接返回完整正文；列表、搜索、详情/播放、工具、账户和充值均不使用浏览器整页取数及加载占位。原生链接请求下一页，浏览器只绑定首屏数据对应的交互。搜索联想、用户主动操作、实时播放权限和显式余额刷新仍按需调用 API。

公共配置、页脚、导航、分类和标签选项缓存 60 秒，首页缓存 30 秒，按上游和查询参数隔离并合并并发读取。详情、章节、选集、评论及推荐并行准备；账户、余额、套餐和观看权限保持实时。公开配置及页脚以字段白名单随 HTML 传递，SDK 配置继续单独读取。可用 `PUBLIC_DATA_CACHE_TTL_MS=0` 关闭公共缓存用于排查；页面和鉴权响应继续禁止共享缓存。

`tests/fixtures/91av-app-contract.json` 保存本次核对的端点、方法、查询参数及请求字段，不包含配置或凭证。合同测试检查页面请求参数及代理白名单；本地模拟服务另验证 SSR、分页、权限、登录、解锁及支付交互。

`PREVIEW_URL=http://127.0.0.1:3107 npm run smoke:api` 检查真实只读接口、游客握手及页面响应，凭证仅保存在进程内存。浏览器交互与真实扣费不包含在该脚本的验证范围内。