54 lines
6.6 KiB
Markdown
54 lines
6.6 KiB
Markdown
# 91av 页面接口对照
|
||
|
||
核对日期：2026-10-21。来源：[当前 Swagger](https://91av-wz.80sygtm.com/swagger/index.html)。上游地址通过 `API_BASE_URL` 配置，默认 `https://91av-wz.80sygtm.com`；下表省略 `/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 |
|
||
| 评论 | `comment/list`；`objectId,objectType,pageNum,pageSize,sortOrder`；整剧类型 10、章节类型 11 |
|
||
| 收藏、历史、已购 | `playlet/collect/list`、`playlet/history/list`、`playlet/bought/list`；`pageNum,pageSize`；服务端使用 `auth/getInfo` 恢复当前账号，直接输出列表 |
|
||
| 账号设置 | `auth/profile`；头像上传 `upload/image`，使用返回的 `sourceNameFs` |
|
||
| 充值、VIP | `recharge/package/list`；读取真实套餐金额（分）、金币及支付渠道；余额明细 `coin/trans/list` 使用 `page,pageSize,type` |
|
||
| 福利应用 | `applist/list?categoryId=…`；保留分类锚点及空分类隐藏逻辑 |
|
||
| 回家的路、独立导航 | `config/info` 的永久地址、备用线路、TG、App 链接；没有 App 地址时隐藏下载入口 |
|
||
| 关于等六个信息页 | 按既有要求保留 HTML 静态正文；联系我们使用配置中的商务 TG 与 TG 群，服务时间可取 `config/footer/info` |
|
||
|
||
## 写接口
|
||
|
||
2026-10-22 本项目（`JHA-1047`）调整内容地址：链接优先使用非空 slug，缺少时使用 ID，保留尾斜杠和独立分页。专题详情接口仍必填 ID，slug 路由先分页查询专题目录解析 ID，再读取详情；目录故障返回服务错误，不伪装成专题不存在。详情评论和推荐等只支持数字 ID 的接口在详情返回后使用真实 ID；支持 slug 的章节请求继续并行。canonical、面包屑、选集和 ItemList 使用对应主地址，旧 ID 地址不新增转向 slug 的重定向。
|
||
|
||
登录、绑定和找回密码使用 `auth/login`、`auth/register`、`auth/resetPassword`；凭证保存在 HttpOnly Cookie。整剧点赞/收藏传 `id` 和布尔状态，章节点赞/收藏只传 `chapterId` 和布尔状态。解锁传 `playletId,chapterId`，仍在用户确认后提交。评论发送、点赞、观看报告的字段按各自请求模型发送。
|
||
|
||
金币下单 `coin/buy`、VIP 下单 `vip/pay` 均使用 `packageId,payMode`，支付渠道只取套餐配置。没有在真实服务上创建订单、付费解锁、注册账号、发送评论或提交反馈。
|
||
|
||
反馈按 `proto.FeedbackReq` 模型：1 建议、2 Bug、3 体验、4 账号、5 其他；操作描述仍写旧的四类，与模型不一致，本次以请求模型为准。问题正文与附加环境信息合计最多 500 字，优先完整保留用户正文。
|
||
|
||
## 已移除的旧接口依赖
|
||
|
||
`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` 检查真实只读接口、游客握手及页面响应，凭证仅保存在进程内存。浏览器交互与真实扣费不包含在该脚本的验证范围内。
|