7.3 KiB
禁果短剧页面接口对照
核对日期：2026-10-26。来源：SGDJ 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 文档并运行本机测试，未对线上业务接口创建账号、订单、评论或解锁。