movies · 短剧

import { MoviesDomain } from '@hfyidu/api/movies'

短剧领域覆盖播放、微信剧场播放、推荐、解锁（含单集/批量/广告解锁）、剧集目录、点赞/转发、观看中/观看历史、收藏、分类、排行榜、推广挂包等全部短剧业务能力，服务前缀 theatre。

用例总览

用例	说明	请求方式
`MoviesDomain.cases.play`	播放剧集	`PUT theatre/play`
`MoviesDomain.cases.wxplayer`	微信小程序剧场播放初始化	`GET theatre/wxplayer/init`
`MoviesDomain.cases.adWxplayer`	广告场景微信小程序剧场初始化	`GET theatre/ad/wxplayer/init`
`MoviesDomain.cases.recommend`	获取推荐短剧	`GET theatre/recommend`
`MoviesDomain.cases.unlock`	解锁单集	`PUT theatre/unlock`
`MoviesDomain.cases.unlockBatch`	批量解锁剧集	`PUT theatre/unlocks`
`MoviesDomain.cases.catalogues`	剧集目录（分页）	`GET theatre/catalogues`
`MoviesDomain.cases.adPlay`	广告场景播放剧集	`PUT theatre/ad/play`
`MoviesDomain.cases.adUnlock`	广告场景解锁单集	`PUT theatre/ad/unlock`
`MoviesDomain.cases.adCatalogues`	广告场景剧集目录（分页）	`GET theatre/ad/catalogues`
`MoviesDomain.cases.like`	点赞	`POST theatre/like`
`MoviesDomain.cases.forwarded`	转发上报	`POST theatre/forwarded`
`MoviesDomain.cases.watching`	获取观看中的短剧	`GET theatre/watching`
`MoviesDomain.cases.history`	观看历史（分页）	`GET theatre/looks`
`MoviesDomain.cases.clearHistory`	清空观看历史	`DELETE theatre/looks`
`MoviesDomain.cases.favored`	收藏列表（分页）	`GET theatre/watches`
`MoviesDomain.cases.favor`	收藏短剧	`PUT theatre/watch`
`MoviesDomain.cases.unfavor`	取消收藏	`DELETE theatre/watch`
`MoviesDomain.cases.deleteHistory`	删除单条观看历史	`DELETE theatre/look`
`MoviesDomain.cases.classifyHead`	获取分类导航	`GET theatre/classifies`
`MoviesDomain.cases.classifyList`	分类下短剧列表（分页）	`GET theatre/class/list`
`MoviesDomain.cases.rankList`	排行榜（分页）	`GET theatre/list`
`MoviesDomain.cases.spreadBags`	推广挂包短剧列表（分页）	`GET theatre/bags`
`MoviesDomain.cases.playCopy`	播放剧集（静默副本）	`PUT theatre/play`
`MoviesDomain.cases.unlockCopy`	解锁单集（静默副本）	`PUT theatre/unlock`
`MoviesDomain.cases.unlockBatchCopy`	批量解锁剧集（静默副本）	`PUT theatre/unlocks`

关于「静默副本」用例

playCopy / unlockCopy / unlockBatchCopy 与对应的 play / unlock / unlockBatch 请求路径、参数、响应结构完全一致，区别仅在于内部请求携带 ignore: true（unlockCopy / unlockBatchCopy）——即请求失败时不会触发框架统一的 Toast 提示，由业务代码自行处理错误展示，适合用在需要静默重试或自定义错误 UI 的场景。playCopy 与 play 行为完全相同，只是路径拼接走的是另一个仓储方法，供业务侧按需选择调用入口。

`play` · 播放剧集

const { data } = await MoviesDomain.cases.play.run({
  theatre_id: 1001,
  spread_id: 0,
  collect_id: 2001,
  scene: 0,
})

console.log(data) // MoviesPlayDto

请求参数 `MoviesPlayBodyParams`

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	短剧 ID
`spread_id`	`number \| string`	是	推广 ID
`collect_id`	`number \| string`	是	剧集 ID
`scene`	`number`	是	场景值（0：应用进入，1：外推进入）
`not_is_auto`	`number \| string`	否	是否非自动播放下一集
`force_auto_unlock`	`number \| string`	否	是否强制自动解锁

响应 `MoviesPlayDto`

字段	类型	后台原始字段	说明
`id`	`number`	`theatre_id`	短剧 ID，必填
`collectId`	`number`	`id`	剧集 ID，必填
`src`	`string`	`spaced_url`	播放地址，默认 `''`
`name`	`string`	`theatre_title`	短剧名称
`collects`	`number`	`total_collect`	总剧集数
`duration`	`number`	`total_duration`	总时长
`number`	`number`	`number`	当前剧集序号，默认 `0`
`isAuto`	`number`	`is_auto`	是否自动播放，默认 `1`
`isCharge`	`boolean`	`is_charge`	是否付费
`isQuiet`	`boolean`	`is_quiet`	是否静默剧（免登录/免解锁）
`isUnlock`	`boolean`	`is_unlock`	当前剧集是否已解锁
`isLike`	`boolean`	`is_like`	是否已点赞
`isFavor`	`boolean`	`is_watch`	是否已收藏
`nextId`	`number`	`next_id`	下一集剧集 ID
`prevId`	`number`	`prev_id`	上一集剧集 ID
`forwardNum`	`number`	`forward_number`	转发数
`likeNum`	`number`	`like_number`	点赞数
`theatre`	`MoviesPlayDescDto`	—	短剧附加描述信息，默认新建一个 `MoviesPlayDescDto` 实例
`description`	`string`	—	只读 getter，等价于 `theatre.description`
`cover`	`string`	—	只读 getter，等价于 `theatre.cover`
`thumbnail`	`string`	—	只读 getter，等价于 `theatre.thumbnail`
`heat`	`number`	—	只读 getter，等价于 `theatre.heat`
`license`	`string`	—	只读 getter，等价于 `theatre.beian \|\| theatre.license`

业务错误（劫持解锁提示）

当后台返回错误码 417001 / 417002 时（通常表示当前剧集需要解锁/需要看广告解锁），仓储层会将错误重新包装为一个附带 code 与 data（MoviesPlayDto 实例）的 Error 抛出，业务代码可结合快速开始 · 错误处理按 error.code 分支处理，并使用 error.data 直接渲染剧集信息。

MoviesPlayDescDto

字段	类型	后台原始字段	说明
`description`	`string`	`description`	剧情简介，默认 `''`
`cover`	`string`	`cover_url`	封面图，默认 `''`
`thumbnail`	`string`	`theatre_deputy_cover`	缩略图/横板封面，默认 `''`
`heat`	`number`	`heat`	热度，默认 `80`
`beian`	`string`	`drama_record_number`	备案号，默认 `''`
`license`	`string`	`online_drama_license`	发行许可证号，默认 `''`

`wxplayer` · 微信小程序剧场初始化

const { data } = await MoviesDomain.cases.wxplayer.run({
  theatre_id: 1001,
  wx_drama_id: 5001,
  number: 1,
})

console.log(data) // MoviesWxplayerDto

请求参数 `MoviesWxplayerQueryParams`

短剧 ID（theatre_id）与微信剧目 ID（wx_drama_id）需二者传其一（该接口 wx_drama_id 为必填，adWxplayer 接口该字段为选填，详见下方 adWxplayer）。

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	系统剧目 ID
`wx_drama_id`	`number \| string`	是	微信剧目 ID
`main_app_id`	`number \| string`	否	应用的系统 ID
`number`	`number \| string`	否	指定剧集序号
`collect_id`	`number \| string`	否	剧集 ID
`code`	`string`	否	微信 code

响应 `MoviesWxplayerDto`

字段	类型	后台原始字段	说明
`freeList`	`MoviesWxplayerFreeDto[]`	`free_list`	免费剧集区间列表，默认 `[]`
`playNumber`	`string`	`play_number`	当前可播放集数
`isWatch`	`boolean`	`is_watch`	是否已观看，默认 `false`
`encryptedData`	`string`	`data`	微信侧加密数据
`lockList`	`MoviesWxplayerLockDto[]`	`serial_map`	锁定剧集区间及解锁所需金额列表，默认 `[]`

MoviesWxplayerFreeDto

字段	类型	后台原始字段	说明
`start_serial_no`	`number`	`start_serial_no`	免费区间起始集数，默认 `1`
`end_serial_no`	`number`	`end_serial_no`	免费区间结束集数

MoviesWxplayerLockDto

字段	类型	后台原始字段	说明
`number`	`number`	`number`	锁定区间起始集数，默认 `1`
`amount`	`number`	`amount`	解锁所需金额

`adWxplayer` · 广告场景微信小程序剧场初始化

const { data } = await MoviesDomain.cases.adWxplayer.run({
  theatre_id: 1001,
  wx_drama_id: 5001,
})

console.log(data) // MoviesAdWxplayerDto

请求参数 `MoviesAdWxplayerQueryParams`

字段与 MoviesWxplayerQueryParams 基本一致，唯一区别是 wx_drama_id 在此为选填。

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	系统剧目 ID
`wx_drama_id`	`number \| string`	否	微信剧目 ID
`main_app_id`	`number \| string`	否	应用的系统 ID
`number`	`number \| string`	否	指定剧集序号
`collect_id`	`number \| string`	否	剧集 ID
`code`	`string`	否	微信 code

响应 `MoviesAdWxplayerDto`

字段结构与 MoviesWxplayerDto 完全一致（freeList / playNumber / isWatch / encryptedData / lockList），仅为独立的 DTO 类。

`recommend` · 获取推荐短剧

const { data } = await MoviesDomain.cases.recommend.run({
  page: 1,
})

console.log(data) // MoviesRecommendDto

请求参数 `MoviesRecommendQueryParams`

字段	类型	必填	说明
`page`	`string \| number`	是	推荐指定页

响应 `MoviesRecommendDto`

字段	类型	后台原始字段	说明
`id`	`string`	`id`	推荐短剧 ID，必填

`unlock` · 解锁单集

const { data } = await MoviesDomain.cases.unlock.run({
  theatre_id: 1001,
  collect_id: 2002,
  scene: 0,
})

console.log(data) // MoviesUnlockDto

请求参数 `MoviesUnlockBodyParams`

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	短剧 ID
`collect_id`	`number \| string`	否	剧集 ID
`spread_id`	`number \| string`	否	推广 ID
`number`	`number`	否	剧集序号
`scene`	`number \| string`	否	场景值
`is_auto`	`number \| string`	否	是否自动解锁
`ad_confirmed`	`number \| string`	否	是否已确认观看激励广告

响应 `MoviesUnlockDto | HttpBusinessError`

该用例声明的响应类型为 MoviesUnlockDto 与 HttpBusinessError 的联合类型，业务错误场景请结合快速开始 · 错误处理判断。

字段	类型	后台原始字段	说明
`id`	`number`	`theatre_id`	短剧 ID，必填
`collectId`	`number`	`id`	剧集 ID，必填
`src`	`string`	`spaced_url`	播放地址，默认 `''`
`name`	`string`	`theatre_title`	短剧名称
`collects`	`number`	`total_collect`	总剧集数
`duration`	`number`	`total_duration`	总时长
`number`	`number`	`number`	当前剧集序号，默认 `0`
`isAuto`	`number`	`is_auto`	是否自动播放，默认 `1`
`isCharge`	`boolean`	`is_charge`	是否付费
`isQuiet`	`boolean`	`is_quiet`	是否静默剧
`isUnlock`	`boolean`	`is_unlock`	当前剧集是否已解锁
`isLike`	`boolean`	`is_like`	是否已点赞
`isFavor`	`boolean`	`is_watch`	是否已收藏
`nextId`	`number`	`next_id`	下一集剧集 ID
`prevId`	`number`	`prev_id`	上一集剧集 ID
`forwardNum`	`number`	`forward_number`	转发数
`likeNum`	`number`	`like_number`	点赞数
`theatre`	`MoviesPlayDescDto`	—	短剧附加描述信息，默认新建一个 `MoviesPlayDescDto` 实例
`description`	`string`	—	只读 getter，等价于 `theatre.description`
`cover`	`string`	—	只读 getter，等价于 `theatre.cover`
`thumbnail`	`string`	—	只读 getter，等价于 `theatre.thumbnail`
`heat`	`number`	—	只读 getter，等价于 `theatre.heat`
`license`	`string`	—	只读 getter，等价于 `theatre.beian \|\| theatre.license`

`unlockBatch` · 批量解锁

const { data } = await MoviesDomain.cases.unlockBatch.run({
  theatre_id: 1001,
  collect_ids: '1,2,3,4',
  scene: 0,
})

console.log(data) // MoviesUnlockBatchDto

请求参数 `MoviesUnlockBatchBodyParams`

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	短剧 ID
`collect_ids`	`string`	否	剧集 ID 集合，半角逗号连接（如 `1,2,3,4`），不传则默认解锁短剧下的所有剧集
`scene`	`number`	是	场景值（0：应用进入，1：外推进入）

响应 `MoviesUnlockBatchDto`

字段	类型	说明
`coin`	`number`	本次解锁消耗的金币数，默认 `0`
`state`	`string`	解锁结果状态

`catalogues` · 剧集目录（分页）

这是分页列表用例，返回结构为 { list: MoviesCataloguesDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

// 只 new 一次，复用同一实例
const cataloguesCase = MoviesDomain.cases.catalogues

await cataloguesCase.refresh({
  theatre_id: 1001,
  page: 1,
  limit: 20,
})

console.log(cataloguesCase.list) // MoviesCataloguesDto[]

请求参数 `MoviesCataloguesQueryParams`

字段	类型	必填	说明
`theatre_id`	`number`	是	短剧 ID
`page`	`number`	是	页码
`limit`	`number`	是	每页条数
`scene`	`0 \| 1`	否	场景值（0：应用进入，1：外推进入）

响应 `{ list: MoviesCataloguesDto[] }`

MoviesCataloguesDto

字段	类型	后台原始字段	说明
`id`	`number`	`id`	剧集 ID，必填
`amount`	`number`	`amount`	解锁所需金额，默认 `0`
`number`	`number`	`number`	剧集序号，默认 `1`
`poster`	`string`	`cover_url`	封面图，默认 `''`
`src`	`string`	`spaced_url`	播放地址，默认 `''`
`title`	`string`	`title`	标题，默认 `''`
`charge`	`boolean`	`is_charge`	是否付费
`quiet`	`boolean`	`is_quiet`	是否静默剧，默认 `false`
`unlock`	`boolean`	`is_unlock`	是否已解锁
`total_duration`	`number`	`total_duration`	总时长，默认 `0`
`isLike`	`boolean`	—	是否已点赞，默认 `false`
`duration`	`number`	—	只读 getter，`Math.floor(total_duration)`
`progress`	`number`	`progress`	播放进度，默认 `0`
`likes`	`string`	—	只读 getter，随机生成的格式化点赞数（仅前端展示用途，非真实后台数据）
`favors`	`string`	—	只读 getter，随机生成的格式化收藏数（仅前端展示用途，非真实后台数据）

`adPlay` · 广告场景播放剧集

const { data } = await MoviesDomain.cases.adPlay.run({
  theatre_id: 1001,
  collect_id: 2001,
  scene: 0,
})

console.log(data) // MoviesAdPlayDto

请求参数

复用 MoviesPlayBodyParams 类型（theatre_id / spread_id / collect_id / scene / not_is_auto / force_auto_unlock）。

TIP

包内另定义了一个 MoviesAdPlayBodyParams 接口（theatre_id / id? / collect_id? / spread_id? / scene? / force_auto_unlock? / not_is_auto?），但当前 adPlay 用例实际引用的是 MoviesPlayBodyParams，调用时以本节参数表为准。

响应 `MoviesAdPlayDto`

字段结构与 MoviesPlayDto 完全一致（id / collectId / src / name / collects / duration / number / isAuto / isCharge / isQuiet / isUnlock / isLike / isFavor / nextId / prevId / forwardNum / likeNum / theatre 及 description / cover / thumbnail / heat / license 只读 getter，均嵌套 MoviesPlayDescDto），仅为独立的 DTO 类。

业务错误

与 play 用例一致，后台返回 417001 / 417002 时会抛出附带 code / data（MoviesAdPlayDto）的错误。

`adUnlock` · 广告场景解锁单集

const { data } = await MoviesDomain.cases.adUnlock.run({
  theatre_id: 1001,
  collect_id: 2002,
  spread_id: 0,
  scene: 0,
  ad_confirmed: 1,
})

console.log(data) // MoviesUnlockDto

请求参数 `MoviesAdUnlockBodyParams`

字段	类型	必填	说明
`theatre_id`	`string \| number`	是	短剧 ID
`collect_id`	`string \| number`	是	剧集 ID
`spread_id`	`string \| number`	是	推广 ID
`number`	`number`	否	剧集序号
`scene`	`string \| number`	是	场景值
`is_auto`	`string \| number`	否	是否自动解锁
`ad_confirmed`	`string \| number`	是	是否已确认观看激励广告

响应

复用 MoviesUnlockDto 类型，字段结构完全一致。

`adCatalogues` · 广告场景剧集目录（分页）

这是分页列表用例，返回结构为 { list: MoviesAdCataloguesDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

const adCataloguesCase = MoviesDomain.cases.adCatalogues

await adCataloguesCase.refresh({
  theatre_id: 1001,
  page: 1,
  limit: 20,
  scene: 1,
})

console.log(adCataloguesCase.list) // MoviesAdCataloguesDto[]

请求参数 `MoviesAdCataloguesQueryParams`

字段与 MoviesCataloguesQueryParams 基本一致，区别是 scene 为必填。

字段	类型	必填	说明
`theatre_id`	`number`	是	短剧 ID
`page`	`number`	是	页码
`limit`	`number`	是	每页条数
`scene`	`0 \| 1`	是	场景值（0：应用进入，1：外推进入）

响应 `{ list: MoviesAdCataloguesDto[] }`

字段结构与 MoviesCataloguesDto 完全一致（id / amount / number / poster / src / title / charge / quiet / unlock / total_duration / isLike / duration / progress / likes / favors），仅为独立的 DTO 类。

`like` · 点赞

await MoviesDomain.cases.like.run({
  id: 2001,
})

请求参数 `MoviesLikeBodyParams`

字段	类型	必填	说明
`id`	`string \| number`	是	剧集 ID

响应

无格式化 DTO，请求成功即完成点赞，直接透传后台原始返回（void）。

`forwarded` · 转发上报

await MoviesDomain.cases.forwarded.run({
  collect_id: 2001,
})

请求参数 `MoviesForwardedBodyParams`

字段	类型	必填	说明
`collect_id`	`string \| number`	是	剧集 ID

响应

无格式化 DTO，请求成功即完成转发上报，直接透传后台原始返回（void）。

`watching` · 获取观看中的短剧

const { data } = await MoviesDomain.cases.watching.run({
  theatre_id: 1001,
})

console.log(data) // MoviesWatchingDto

请求参数 `MoviesWatchingQueryParams`

字段	类型	必填	说明
`theatre_id`	`string \| number`	否	指定短剧 ID，若不指定则返回最近观看的短剧剧集

响应 `MoviesWatchingDto`（不可变，`@Freeze`）

字段	类型	后台原始字段	说明
`id`	`string`	`id`	观看中剧集 ID，必填

`history` · 观看历史（分页）

这是分页列表用例，返回结构为 { list: MoviesHistoryDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

const historyCase = MoviesDomain.cases.history

await historyCase.refresh({
  page: 1,
  limit: 20,
})

console.log(historyCase.list) // MoviesHistoryDto[]

请求参数 `MoviesHistoryQueryParams`

字段	类型	必填	说明
`page`	`number`	否	页码
`limit`	`number`	否	每页条数

响应 `{ list: MoviesHistoryDto[] }`

MoviesHistoryDto

字段	类型	后台原始字段	说明
`id`	`string`	`id`	观看历史记录 ID，必填
`videoId`	`number`	`theatre_id`	短剧 ID，默认 `0`
`vodCateId`	`number`	`vod_cate_id`	视频分类 ID，默认 `0`
`title`	`string`	`theatre_title`	短剧名称，默认 `'未知剧名'`
`copyright`	`string`	`copyright`	版权方，默认 `''`
`cover`	`string`	`theatre_cover`	封面图，默认 `''`
`thumbnail`	`string`	`thumbnail_cover_url`	缩略图，默认 `''`
`deputyCover`	`string`	`deputy_cover_url`	横板封面，默认 `''`
`latest`	`number`	`look_collect_number`	最近观看到的剧集序号，默认 `1`
`isWatch`	`boolean`	`is_watch`	是否已收藏，默认 `false`
`collectId`	`number`	`look_collect_id`	最近观看的剧集 ID
`isAuto`	`number`	`is_auto`	是否自动播放
`createAt`	`string`	`created_at`	创建时间
`updateAt`	`string`	`updated_at`	更新时间

`clearHistory` · 清空观看历史

await MoviesDomain.cases.clearHistory.run(null)

请求参数 `MoviesClearHistoryBodyParams`

类型为 null，调用时直接传 null 即可，无需构造参数对象。

响应

无格式化 DTO，请求成功即清空全部观看历史，直接透传后台原始返回（void）。

`favored` · 收藏列表（分页）

这是分页列表用例，返回结构为 { list: MoviesFavoredDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

const favoredCase = MoviesDomain.cases.favored

await favoredCase.refresh({
  id: '1001',
  page: 1,
  limit: 20,
})

console.log(favoredCase.list) // MoviesFavoredDto[]

请求参数 `MoviesFavoredQueryParams`

继承自 PagedQueryParams（分页参数基类，提供 page/limit 等标准分页字段）。

字段	类型	必填	说明
`id`	`string`	是	查询标识（收藏列表定位参数）

响应 `{ list: MoviesFavoredDto[] }`

MoviesFavoredDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
`id`	`string`	`id`	收藏记录 ID，必填
`videoId`	`number`	`id`	短剧 ID，默认 `0`
`channel`	`number`	`channel`	频道，默认 `0`
`class_id`	`number`	`class_id`	分类 ID，默认 `0`
`title`	`string`	`title`	短剧名称，默认 `'未知剧名'`
`description`	`string`	`description`	简介，默认 `'无介绍'`
`keywords`	`string`	`keywords`	关键词
`cover`	`string`	`cover_url`	封面图，默认 `''`
`thumbnail`	`string`	`thumbnail_cover_url`	缩略图，默认 `''`
`deputyCover`	`string`	`deputy_cover_url`	横板封面，默认 `''`
`heat`	`number`	`heat`	热度，默认 `80`
`theatre_source_type`	`number`	`theatre_source_type`	来源类型，默认 `0`
`total_collect`	`number`	`total_collect`	总剧集数
`total_duration`	`number`	`total_duration`	总时长
`spread_id`	`number`	`spread_id`	推广 ID，默认 `0`
`lead_name`	`string`	`lead_name`	推荐名，默认 `'暂无'`
`last_collect_number`	`number`	`last_collect_number`	最新更新的剧集序号
`near`	`MoviesFavoredNearDto`	`near_collect`	最新一集附加信息，默认新建一个 `MoviesFavoredNearDto` 实例
`latest`	`number`	—	只读 getter，等价于 `near.numbers`
`forward`	`number`	—	只读 getter，等价于 `near.forwardNumbers`
`like`	`number`	—	只读 getter，等价于 `near.likeNumbers`
`updateAt`	`Date \| number`	—	只读 getter，`near.updateAt` 存在时转为 `Date`，否则为 `0`

MoviesFavoredNearDto

字段	类型	后台原始字段	说明
`likeNumbers`	`number`	`like_number`	点赞数，默认 `0`
`forwardNumbers`	`number`	`forward_number`	转发数，默认 `0`
`numbers`	`number`	`number`	最新一集序号，默认 `1`
`updateAt`	`string`	`watch_time`	观看/更新时间，默认 `''`

`favor` · 收藏短剧

await MoviesDomain.cases.favor.run({
  theatre_id: 1001,
})

请求参数 `MoviesFavorBodyParams`

字段	类型	必填	说明
`theatre_id`	`number \| string`	是	短剧 ID

响应

无格式化 DTO，请求成功即完成收藏，直接透传后台原始返回（void）。

`unfavor` · 取消收藏

await MoviesDomain.cases.unfavor.run({
  theatre_id: 1001,
})

请求参数 `MoviesUnfavorBodyParams`

字段	类型	必填	说明
`theatre_id`	`string \| number`	是	短剧 ID

响应

无格式化 DTO，请求成功即取消收藏，直接透传后台原始返回（void）。

`deleteHistory` · 删除单条观看历史

await MoviesDomain.cases.deleteHistory.run({
  look_id: 3001,
})

请求参数 `MoviesDeleteHistoryBodyParams`

字段	类型	必填	说明
`look_id`	`number`	是	要删除的观看记录 ID

响应

无格式化 DTO，请求成功即删除对应记录，直接透传后台原始返回（void）。

`classifyHead` · 获取分类导航

const { data } = await MoviesDomain.cases.classifyHead.run({
  page: 1,
  limit: 20,
})

console.log(data) // MoviesClassifyHeadDto[]

请求参数 `MoviesClassifyHeadQueryParams`

字段	类型	必填	说明
`class_id`	`number`	否	指定分类 ID，不填默认返回所有分类
`page`	`number`	否	页码
`limit`	`number`	否	每页条数

响应 `MoviesClassifyHeadDto[]`

MoviesClassifyHeadDto

字段	类型	后台原始字段	说明
`id`	`number`	`id`	分类 ID，必填
`name`	`string`	`class_name`	分类名称，默认 `''`
`sort`	`number`	`sort`	排序权重，默认 `0`

`classifyList` · 分类下短剧列表（分页）

这是分页列表用例，返回结构为 { list: MoviesClassifyListDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

const classifyListCase = MoviesDomain.cases.classifyList

await classifyListCase.refresh({
  class_id: 1,
  page: 1,
  limit: 20,
})

console.log(classifyListCase.list) // MoviesClassifyListDto[]

请求参数 `MoviesClassifyListQueryParams`

字段	类型	必填	说明
`class_id`	`number`	否	指定分类 ID，不填默认返回所有分类
`page`	`number`	是	页码
`limit`	`number`	是	每页条数

响应 `{ list: MoviesClassifyListDto[] }`

MoviesClassifyListDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
`id`	`number`	`id`	短剧 ID，必填
`cover`	`string`	`cover_url`	封面图，默认 `''`
`thumb`	`string`	`deputy_cover_url`	横板封面，默认 `''`
`title`	`string`	`title`	短剧名称，默认 `'无剧名'`
`adContentDeliver`	`number`	`ad_content_deliver`	广告内容投放策略，默认 `1`
`desc`	`string`	`description`	简介，默认 `''`
`videoSourceType`	`VideoSourceType`	`theatre_source_type`	短剧来源类型，默认 `VideoSourceType.SWTJ`
`adEffectLimit`	`number`	`ad_effect_limit`	广告效果限制，默认 `1`
`adUnlockStep`	`number`	`ad_unlock_step`	广告解锁步长，默认 `1`
`browseNumber`	`number`	`browse_num`	浏览数，默认 `0`
`channel`	`VideoChannel`	`channel`	短剧频道，默认 `VideoChannel.ALL`
`classId`	`number`	`class_id`	分类 ID，默认 `0`
`className`	`string`	`class_name`	分类名称，默认 `''`
`heat`	`number`	`heat`	热度，默认 `80`
`keywords`	`string`	`keywords`	关键词，默认 `''`
`leadName`	`string`	`lead_name`	推荐名，默认 `''`
`beian`	`string`	`drama_record_number`	备案号，默认 `''`
`license`	`string`	`online_drama_license`	发行许可证号，默认 `''`
`quiet_collect`	`number`	`quiet_collect`	静默剧集数，默认 `1`
`price`	`number`	`set_price`	单集售价，默认 `120`
`priceType`	`number`	`set_price_type`	售价类型，默认 `2`
`chargeType`	`number`	`charge_type`	付费类型，默认 `3`
`isRisk`	`number`	`is_risk`	是否风险剧，默认 `0`
`isSensitive`	`number`	`is_sensitive`	是否敏感剧，默认 `0`
`freeNumber`	`number`	`free_collect`	免费剧集数，默认 `20`
`lastCollectNumber`	`number`	`last_collect_number`	最新更新的剧集序号，默认 `0`
`createdAt`	`string`	`created_at`	创建时间，默认 `'2099-12-31'`
`updatedAt`	`string`	`updated_at`	更新时间，默认 `'2099-12-31'`
`totalCollect`	`number`	`total_collect`	总剧集数，默认 `0`
`totalDuration`	`number`	`total_duration`	总时长，默认 `0`
`previewUrl`	`string`	`trailer_url`	预告片地址，默认 `''`
`status`	`VideoUpdateStatus`	`update_status`	更新状态，默认 `VideoUpdateStatus.COMPLETED`
`near`	`MoviesCollectNearDto`	`near_collect`	最新一集信息，默认新建一个 `MoviesCollectNearDto` 实例
`vodCateId`	`number \| string`	`vod_cate_id`	视频分类 ID，默认 `0`
`copyright`	`string`	`copyright`	版权方
`fakeBrowseNumber`	`string`	—	只读 getter，随机生成的格式化浏览数（仅前端展示用途，非真实后台数据）

MoviesCollectNearDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
`collect_id`	`number`	`id`	最新一集的剧集 ID，默认 `0`
`title`	`string`	`title`	剧集标题，默认 `'第1集'`
`number`	`number`	`number`	剧集序号，默认 `1`
`id`	`number`	`theatre_id`	短剧 ID，默认 `0`
`cover`	`string`	`cover_url`	封面图，默认 `''`
`forward`	`number`	`forward_number`	转发数，默认 `0`
`isCharge`	`number`	`is_charge`	是否付费，默认 `0`

`rankList` · 排行榜（分页）

这是分页列表用例，返回结构为 { list: MoviesRankListDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

const rankListCase = MoviesDomain.cases.rankList

await rankListCase.refresh({
  page: 1,
  limit: 20,
  list_name: 'hot',
})

console.log(rankListCase.list) // MoviesRankListDto[]

请求参数 `MoviesRankListQueryParams`

字段	类型	必填	说明
`page`	`number`	否	页码
`limit`	`number`	否	每页条数
`list_name`	`string`	否	指定榜单名，不填默认返回所有榜单

响应 `{ list: MoviesRankListDto[] }`

MoviesRankListDto

字段	类型	后台原始字段	说明
`info`	`MoviesRankListInfoDto`	—	榜单基础信息，默认新建一个 `MoviesRankListInfoDto` 实例
`list`	`MoviesRankListDataDto[]`	—	榜单内短剧列表，默认 `[]`

MoviesRankListInfoDto

字段	类型	说明
`id`	`number \| string`	榜单 ID，必填
`channel`	`number`	榜单所属频道，默认 `0`
`code`	`string`	榜单代码，默认 `''`
`describe`	`string`	榜单说明，默认 `''`
`title`	`string`	榜单标题，默认 `''`

MoviesRankListDataDto

字段	类型	后台原始字段	说明
`videoId`	`number \| string`	`id`	短剧 ID，必填
`title`	`string`	`title`	短剧名称，默认 `''`
`description`	`string`	`description`	简介，默认 `''`
`cover`	`string`	`cover_url`	封面图，默认 `''`
`deputyCover`	`string`	`deputy_cover_url`	横板封面，默认 `''`
`thumbnail`	`string`	`thumbnail_cover_url`	缩略图，默认 `''`
`collects`	`number`	`total_collect`	总剧集数，默认 `0`
`trailSrc`	`string`	`trailer_url`	预告片地址，默认 `''`
`status`	`number`	`update_status`	更新状态，默认 `2`
`catalogName`	`string`	`class_name`	分类名称，默认 `'精选'`
`heat`	`number`	`heat`	热度，默认 `80`
`labels`	`string`	`keywords`	标签关键词，默认 `''`
`theatre_source_type`	`number`	`theatre_source_type`	来源类型，默认 `4`
`vodCateId`	`number`	`vod_cate_id`	视频分类 ID，默认 `0`
`statusTxt`	`string`	—	只读 getter，`status === 2` 时为 `'完结'`，否则为 `'连载中'`
`browse`	`string`	—	只读 getter，随机生成的格式化浏览数（仅前端展示用途，非真实后台数据）
`desc`	`string`	—	只读 getter，`description` 为空时返回占位文案 `'这个小主偷懒啦，还没有编辑剧情简介哦~~'`

`spreadBags` · 推广挂包短剧列表（分页）

这是分页列表用例，返回结构为 { list: MoviesSpreadBagsDto[] }，建议参考快速开始 · 分页列表请求的用法只 new 一次并复用实例。

TIP

该用例底层请求携带 ignore: true，请求失败时不会触发框架统一的 Toast 提示，需要业务代码自行处理错误展示。

const spreadBagsCase = MoviesDomain.cases.spreadBags

await spreadBagsCase.refresh({
  spread_id: 3001,
})

console.log(spreadBagsCase.list) // MoviesSpreadBagsDto[]

请求参数 `MoviesSpreadBagsQueryParams`

字段	类型	必填	说明
`spread_id`	`number \| string`	是	推广 ID

响应 `{ list: MoviesSpreadBagsDto[] }`

MoviesSpreadBagsDto（不可变，@Freeze）

字段	类型	后台原始字段	说明
`id`	`number \| string`	`id`	记录 ID，必填
`videoId`	`number`	`id`	短剧 ID，必填
`title`	`string`	`title`	短剧名称，默认 `''`
`copyright`	`string`	`copyright`	版权方，默认 `''`
`vodCateId`	`number`	`vod_cate_id`	视频分类 ID，默认 `0`
`desc`	`string`	`description`	简介，默认 `'暂无简介'`
`cover`	`string`	`cover_url`	封面图，默认 `''`
`thumb`	`string`	`thumbnail_cover_url`	缩略图，默认 `''`
`deputy`	`string`	`deputy_cover_url`	横板封面，默认 `''`
`status`	`VideoUpdateStatus`	`update_status`	更新状态，默认 `VideoUpdateStatus.COMPLETED`
`heat`	`number`	`heat`	热度，默认 `80`
`freeCollect`	`number`	`free_collect`	免费剧集数，默认 `20`
`totalCollect`	`number`	`total_collect`	总剧集数，默认 `0`
`totalDuration`	`number`	`total_duration`	总时长，默认 `0`
`keywords`	`string`	`keywords`	关键词，默认 `''`
`leadName`	`string`	`lead_name`	推荐名，默认 `''`

`playCopy` · 播放剧集（静默副本）

const { data } = await MoviesDomain.cases.playCopy.run({
  theatre_id: 1001,
  spread_id: 0,
  collect_id: 2001,
  scene: 0,
})

console.log(data) // MoviesPlayDto

请求参数

复用 MoviesPlayBodyParams 类型，字段完全一致。

响应

复用 MoviesPlayDto 类型，字段完全一致（与 play 请求路径、参数、响应结构完全相同）。

`unlockCopy` · 解锁单集（静默副本）

const { data } = await MoviesDomain.cases.unlockCopy.run({
  theatre_id: 1001,
  collect_id: 2002,
  scene: 0,
})

console.log(data) // MoviesPlayDto

TIP

该用例底层请求携带 ignore: true，请求失败时不会触发框架统一的 Toast 提示，需要业务代码自行处理错误展示。

请求参数

复用 MoviesUnlockBodyParams 类型，字段完全一致。

响应 `MoviesPlayDto | HttpBusinessError`

注意响应 DTO 与 unlock 不同

unlockCopy 声明的响应类型是 MoviesPlayDto（而不是 unlock 用例使用的 MoviesUnlockDto），字段结构参考 play 一节；业务错误场景同样参考快速开始 · 错误处理。

`unlockBatchCopy` · 批量解锁（静默副本）

const { data } = await MoviesDomain.cases.unlockBatchCopy.run({
  theatre_id: 1001,
  collect_ids: '1,2,3,4',
  scene: 0,
})

console.log(data) // MoviesUnlockBatchDto

TIP

该用例底层请求携带 ignore: true，请求失败时不会触发框架统一的 Toast 提示，需要业务代码自行处理错误展示。

请求参数

复用 MoviesUnlockBatchBodyParams 类型，字段完全一致。

响应 `MoviesUnlockBatchDto | HttpBusinessError`

复用 MoviesUnlockBatchDto 类型，字段完全一致；业务错误场景参考快速开始 · 错误处理。

枚举

`VideoChannel` 短剧频道

枚举成员	value	code	说明
`ALL`	0	`all`	通频
`MALE`	1	`male`	男频
`FEMALE`	2	`female`	女频

`VideoSourceType` 短剧来源类型

枚举成员	value	code	说明
`WTDJ`	1	`wtdj`	外推短剧
`WTGB`	2	`wtgb`	外推挂包
`NT`	3	`nt`	内推
`SWTJ`	4	`swtj`	首位推荐
`BDTJ`	5	`bdtj`	榜单推荐
`FL`	6	`fl`	分类
`SEARCH`	7	`search`	自搜索
`XTTS`	8	`xtts`	系统推送
`XSMF`	9	`xsmf`	限时免费
`SHARE`	10	`share`	分享
`OTHER`	99	`other`	其他

`VideoUpdateStatus` 短剧更新状态

枚举成员	value	code	说明
`ALL`	0	`all`	全部
`SERIALIZED`	1	`serialized`	更新中
`COMPLETED`	2	`completed`	完结

movies · 短剧 ​

用例总览 ​

play · 播放剧集 ​

请求参数 MoviesPlayBodyParams ​

响应 MoviesPlayDto ​

wxplayer · 微信小程序剧场初始化 ​

请求参数 MoviesWxplayerQueryParams ​

响应 MoviesWxplayerDto ​

adWxplayer · 广告场景微信小程序剧场初始化 ​

请求参数 MoviesAdWxplayerQueryParams ​

响应 MoviesAdWxplayerDto ​

recommend · 获取推荐短剧 ​

请求参数 MoviesRecommendQueryParams ​

响应 MoviesRecommendDto ​

unlock · 解锁单集 ​

请求参数 MoviesUnlockBodyParams ​

响应 MoviesUnlockDto | HttpBusinessError ​

unlockBatch · 批量解锁 ​

请求参数 MoviesUnlockBatchBodyParams ​

响应 MoviesUnlockBatchDto ​

catalogues · 剧集目录（分页） ​

请求参数 MoviesCataloguesQueryParams ​

响应 { list: MoviesCataloguesDto[] } ​

adPlay · 广告场景播放剧集 ​

请求参数 ​

响应 MoviesAdPlayDto ​

adUnlock · 广告场景解锁单集 ​

请求参数 MoviesAdUnlockBodyParams ​

响应 ​

adCatalogues · 广告场景剧集目录（分页） ​

请求参数 MoviesAdCataloguesQueryParams ​

响应 { list: MoviesAdCataloguesDto[] } ​

like · 点赞 ​

请求参数 MoviesLikeBodyParams ​

响应 ​

forwarded · 转发上报 ​

请求参数 MoviesForwardedBodyParams ​

响应 ​

watching · 获取观看中的短剧 ​

请求参数 MoviesWatchingQueryParams ​

响应 MoviesWatchingDto（不可变，@Freeze） ​

history · 观看历史（分页） ​

请求参数 MoviesHistoryQueryParams ​

响应 { list: MoviesHistoryDto[] } ​

clearHistory · 清空观看历史 ​

请求参数 MoviesClearHistoryBodyParams ​

响应 ​

favored · 收藏列表（分页） ​

请求参数 MoviesFavoredQueryParams ​

响应 { list: MoviesFavoredDto[] } ​

favor · 收藏短剧 ​

请求参数 MoviesFavorBodyParams ​

响应 ​

unfavor · 取消收藏 ​

请求参数 MoviesUnfavorBodyParams ​

响应 ​

deleteHistory · 删除单条观看历史 ​

请求参数 MoviesDeleteHistoryBodyParams ​

响应 ​

classifyHead · 获取分类导航 ​

请求参数 MoviesClassifyHeadQueryParams ​

响应 MoviesClassifyHeadDto[] ​

classifyList · 分类下短剧列表（分页） ​

请求参数 MoviesClassifyListQueryParams ​

响应 { list: MoviesClassifyListDto[] } ​

rankList · 排行榜（分页） ​

请求参数 MoviesRankListQueryParams ​

响应 { list: MoviesRankListDto[] } ​

spreadBags · 推广挂包短剧列表（分页） ​

请求参数 MoviesSpreadBagsQueryParams ​

响应 { list: MoviesSpreadBagsDto[] } ​

playCopy · 播放剧集（静默副本） ​

请求参数 ​

响应 ​

unlockCopy · 解锁单集（静默副本） ​

请求参数 ​

响应 MoviesPlayDto | HttpBusinessError ​

unlockBatchCopy · 批量解锁（静默副本） ​

请求参数 ​

响应 MoviesUnlockBatchDto | HttpBusinessError ​

movies · 短剧

用例总览

`play` · 播放剧集

请求参数 `MoviesPlayBodyParams`

响应 `MoviesPlayDto`

`wxplayer` · 微信小程序剧场初始化

请求参数 `MoviesWxplayerQueryParams`

响应 `MoviesWxplayerDto`

`adWxplayer` · 广告场景微信小程序剧场初始化

请求参数 `MoviesAdWxplayerQueryParams`

响应 `MoviesAdWxplayerDto`

`recommend` · 获取推荐短剧

请求参数 `MoviesRecommendQueryParams`

响应 `MoviesRecommendDto`

`unlock` · 解锁单集

请求参数 `MoviesUnlockBodyParams`

响应 `MoviesUnlockDto | HttpBusinessError`

`unlockBatch` · 批量解锁

请求参数 `MoviesUnlockBatchBodyParams`

响应 `MoviesUnlockBatchDto`

`catalogues` · 剧集目录（分页）

请求参数 `MoviesCataloguesQueryParams`

响应 `{ list: MoviesCataloguesDto[] }`

`adPlay` · 广告场景播放剧集

请求参数

响应 `MoviesAdPlayDto`

`adUnlock` · 广告场景解锁单集

请求参数 `MoviesAdUnlockBodyParams`

响应

`adCatalogues` · 广告场景剧集目录（分页）

请求参数 `MoviesAdCataloguesQueryParams`

响应 `{ list: MoviesAdCataloguesDto[] }`

`like` · 点赞

请求参数 `MoviesLikeBodyParams`

响应

`forwarded` · 转发上报

请求参数 `MoviesForwardedBodyParams`

响应

`watching` · 获取观看中的短剧

请求参数 `MoviesWatchingQueryParams`

响应 `MoviesWatchingDto`（不可变，`@Freeze`）

`history` · 观看历史（分页）

请求参数 `MoviesHistoryQueryParams`

响应 `{ list: MoviesHistoryDto[] }`

`clearHistory` · 清空观看历史

请求参数 `MoviesClearHistoryBodyParams`

响应

`favored` · 收藏列表（分页）

请求参数 `MoviesFavoredQueryParams`

响应 `{ list: MoviesFavoredDto[] }`

`favor` · 收藏短剧

请求参数 `MoviesFavorBodyParams`

响应

`unfavor` · 取消收藏

请求参数 `MoviesUnfavorBodyParams`

响应

`deleteHistory` · 删除单条观看历史

请求参数 `MoviesDeleteHistoryBodyParams`

响应

`classifyHead` · 获取分类导航

请求参数 `MoviesClassifyHeadQueryParams`

响应 `MoviesClassifyHeadDto[]`

`classifyList` · 分类下短剧列表（分页）

请求参数 `MoviesClassifyListQueryParams`

响应 `{ list: MoviesClassifyListDto[] }`

`rankList` · 排行榜（分页）

请求参数 `MoviesRankListQueryParams`

响应 `{ list: MoviesRankListDto[] }`

`spreadBags` · 推广挂包短剧列表（分页）

请求参数 `MoviesSpreadBagsQueryParams`

响应 `{ list: MoviesSpreadBagsDto[] }`

`playCopy` · 播放剧集（静默副本）

请求参数

响应

`unlockCopy` · 解锁单集（静默副本）

请求参数

响应 `MoviesPlayDto | HttpBusinessError`

`unlockBatchCopy` · 批量解锁（静默副本）

请求参数

响应 `MoviesUnlockBatchDto | HttpBusinessError`