65 lines
7.3 KiB
Markdown
65 lines
7.3 KiB
Markdown
# 禁果短剧页面接口对照
|
||
|
||
核对日期：2026-10-26。来源：[SGDJ Swagger](https://sgdj-h5.80sygtm.com/swagger/index.html)，定义：[doc.json](https://sgdj-h5.80sygtm.com/swagger/doc.json)。本文省略 `/api/app/` 前缀。
|
||
|
||
运行上游由 `UPSTREAM_API_URL` 配置，兼容 `API_BASE_URL`。本地开发、测试环境使用 `http://172.104.181.99:26792`，生产环境使用 `http://139.162.49.252:21040`（H5 端口 `21042`，CDN `d23iqbsywbvs3m.cloudfront.net`）；应用及埋点 ID 保持 1050。
|
||
|
||
| 页面 | 接口及关键参数 |
|
||
| --- | --- |
|
||
| 顶部、侧栏和移动导航 | `navigation/header`；沿用 `categoryList` 的名称、顺序、图标、类型与二级导航 |
|
||
| 首页 | `playlet/home`；轮播 `homeBannerData`、公告 `announcements`、广告 `advitise`；栏目读取 `modules` |
|
||
| 首页短剧栏目 | `modules[].moduleType=1`，标题 `title`，条目 `list`；保留 slug、介绍和顺序 |
|
||
| 首页题材栏目 | `modules[].moduleType=2`，题材读取 `topicList`，题材卡片进入 `/theme/{slug或id}/` |
|
||
| 首页“更多” | `playlet/home-config/list`；`slug` 或 `id`，加 `pageNum,pageSize`；读取 `config`、`list/topicList` 和真实 `totalCount`，支持后续分页 |
|
||
| 短剧四种推荐 | `playlet/operate/list`；`type=1/2/3/4` 分别为最新、热播、独家、随机，分页使用 `pageNum,pageSize` |
|
||
| 题材短剧 | 先由 `theme/list` 核对题材名称与身份，再读取 `playlet/all/list`；使用 `themeSlug` 或 `themeId`，支持 `sortType=1/2/3` 和 `updateStatus=0/1/2` |
|
||
| 三个排行榜 | `playlet/hot/rank/list`；`rankType=1/2/3` 和 `pageNum,pageSize`，该接口仍在新文档中 |
|
||
| 专题列表 | `playlet/topic/list`；`pageNum,pageSize`；返回的 `list` 是专题区块，每个区块的 `list` 才是专题卡片 |
|
||
| 专题详情 | `playlet/topic/detail`；直接使用 `topicSlug` 或 `id`，加 `dataType=1`、`pageNum,pageSize,sortType`；不再扫描专题目录解析 slug |
|
||
| 标签短剧 | `playlet/tag/list`；`tagSlug` 或 `tagId`，加 `pageNum,pageSize,sortType` |
|
||
| 搜索 | `playlet/search`；`keyword,pageNum,pageSize`；无结果优先使用 `everyoneWatching`，不足时读取 `playlet/operate/list?type=2` |
|
||
| 联想与换一批 | `playlet/search/suggest?keyword=…` 返回短剧；换一批读取 `playlet/operate/list?type=4` |
|
||
| 短剧详情及推荐 | `playlet/detail` 使用 `slug` 或 `id`；推荐读取 `playlet/guess-like/list?playletId=…` |
|
||
| 章节和选集 | `playlet/chapter/list` 使用 `playletSlug/playletId`；`chapter/detail` 另外传 `chapterId`，实时读取观看权限与视频源 |
|
||
| 评论 | 详情页和播放页都评论整部短剧：`comment/list`、`comment/send` 使用短剧 `objectId` 与 `objectType=10`；列表另传 `pageNum,pageSize,sortOrder`（1 热门，2 最新）。回复传一级评论 `parentsId` 和实际回复 `replyCommentId`，一级评论两者为 0。`comment/like/set` 传 `commentId` 与布尔 `isLike`，返回状态 1 已点赞、2 未点赞 |
|
||
| 收藏、历史、点赞、已购 | 对应 `playlet/collect/list`、`history/list`、`like/list`、`bought/list`；使用当前账号及真实分页 |
|
||
| 账号设置 | `auth/profile`；头像通过 `upload/image` 的 multipart `file` 上传，使用返回的 `sourceNameFs` |
|
||
| 充值、VIP | `recharge/package/list` 读取套餐和支付渠道；余额明细 `coin/trans/list` 使用 `page,pageSize,type` |
|
||
| 福利应用、回家线路 | `applist/list`、`config/info` 与 `config/footer/info`，沿用现有配置读取 |
|
||
|
||
专题列表不再返回全局 totalCount：页面保留区块名称、介绍和各自卡片，使用区块 totalCount 的最大值计算共同分页边界，避免将各区块数量相加后生成不存在的页面。专题卡片和题材卡片分别使用 `/topics/` 和 `/theme/`，canonical、面包屑和 JSON-LD 同步区分。
|
||
|
||
首页优先使用新字段 modules；仅在响应没有该字段时兼容旧 homeConfigData 快照。明确返回空 modules 时不会恢复旧栏目。首页“更多”直接使用新分页接口，不再用首页预览条目伪造完整目录。
|
||
|
||
首页分类按 `modules[].style` 映射原 HTML 展示方式，兼容旧 `homeConfigData[].style`。布局仅由该字段决定，保留后台名称及条目顺序，不根据名称、位置或热度猜测。字符串会去除首尾空格并转为大写。
|
||
|
||
| style | 对应原稿分类 | 桌面展示 |
|
||
| --- | --- | --- |
|
||
| A | 热门推荐 | 竖版海报，5 列 |
|
||
| B | 猜你喜欢 | 竖版海报，6 列 |
|
||
| C | 最新短剧 | 左图右文，3 列；可显示后台 `label` |
|
||
| D | 热门好剧 | 带顺序编号的竖版海报，6 列 |
|
||
| E | 专题推荐 | 横版题材封面，4 列 |
|
||
|
||
A–D 用于短剧模块（`moduleType=1`），E 用于题材模块（`moduleType=2`）。缺失、未知、F–Z 预留或与内容类型不符的 style 沿用普通短剧/题材网格。
|
||
|
||
首页分类展示数量由 `modules[].limit` 控制，兼容旧 `homeConfigData[].limit`，所有 style（含默认网格）都使用同一规则：非负安全整数表示最多展示的条目数，`0` 显示空态；缺失或无效时展示全部有效返回条目。列表不足 limit 时按实际数量展示，保留接口顺序。`style` 仅控制卡片及列数，行数随 limit 自动增加。首页 HTML 和 JSON-LD 采用同一 limit；原始列表及“查看更多”的真实分页保持完整。
|
||
|
||
移动端 A、B、D 两列，C 单列图文卡，E 两列；B 在平板宽度为三列。各端均按 limit 展示全部预览条目，保留更多入口。D 的序号按列表顺序从 01 开始，手机端叠加在封面上。
|
||
|
||
## 写接口与请求头
|
||
|
||
新旧文档的登录、注册、资料、找回密码、支付、解锁、反馈和章节权限模型未发现字段变化。继续使用 `auth/login/register/resetPassword`；整剧点赞/收藏传 `id` 与布尔状态，章节操作传 `chapterId`，解锁传 `playletId,chapterId`。金币与 VIP 下单使用 `packageId,payMode`，渠道只取套餐配置；购买解锁继续由用户确认。
|
||
|
||
反馈按请求模型使用 1 建议、2 Bug、3 体验、4 账号、5 其他；正文和附加环境信息合计最多 500 字。上传请求不手动设置 multipart boundary。
|
||
|
||
原生 UA、X-User-Agent、X-Real-IP、SDK 快照与业务事件上下文沿用 JHA-1045 对齐后的转发规则。公开内容不附带账号凭证，私有接口使用 HttpOnly 会话，签名媒体不转发业务 Cookie 或 Authorization。
|
||
|
||
## 接口范围与验证
|
||
|
||
移除新文档中不存在的 `playlet/hot/list` 依赖。新文档虽然重新提供 video 系列接口，本站继续遵循此前移除独立剧集入口的要求，不恢复 `/series/`、`/video/` 或未使用的代理端点。`playlet/rank`、`playlet/today-update` 等没有对应现有页面的接口无需额外开放。
|
||
|
||
`tests/fixtures/sgdj-app-contract.json` 保存本次文档的端点、方法、参数、请求字段与原始定义 SHA-256。合同测试检查调用字段与代理白名单；本机模拟接口验证 SSR、专题分组、题材、更多分页、搜索、权限和支付交互，不提交真实业务写入。
|
||
|
||
`scripts/smoke-api.mjs` 已同步新端点和首页/专题结构，可由操作者指定 PREVIEW_URL 后执行；本次仅获取 Swagger 文档并运行本机测试，未对线上业务接口创建账号、订单、评论或解锁。
|