5.6 KiB
91av 页面接口对照
核对日期：2026-10-21。来源：当前 Swagger。上游地址通过 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 检查真实只读接口、游客握手及页面响应，凭证仅保存在进程内存。浏览器交互与真实扣费不包含在该脚本的验证范围内。