docs(api): 同步多语言筛选与转码通知契约
This commit is contained in:
Zhou Weidong committed
1 parent
1d34e47673
commit
50b3dd4a8e
1 file changed
+53
-2
+53
-2
@@ -168,10 +168,30 @@ app.register.max-per-device-per-day
|
||||
| GET | `/app/home/feed` | 首页：轮播 + 分区，卡片带 `preview` 可播预览集与 `language` 语种 |
|
||||
| GET | `/app/discover/feed` | 发现页分区 |
|
||||
| GET | `/app/feed?types=ANIME,LIVE&categoryId=7&cursor=&size=20` | 推荐流；支持内容类型与分类叠加过滤，游标翻页 |
|
||||
| GET | `/app/categories` | 分类列表 |
|
||||
| GET | `/app/categories` | 已启用首页分类。`name` 为中文，`locales` 为 `{zh,en,id}` |
|
||||
| GET | `/app/categories/{id}/dramas?pageIndex=&pageSize=` | 分类下已上线短剧，分页。`pageIndex` 默认 1，`pageSize` 默认 20、最大 50 |
|
||||
| GET | `/app/drama-categories` | 已启用类型。`locales` 为 `{zh,en,id}` |
|
||||
| GET | `/app/tags` | 已启用标签。`locales` 为 `{zh,en,id}` |
|
||||
| POST | `/app/dramas/page` | 全部短剧分页。请求体 `pageIndex`（默认 1）、`pageSize`（默认 20、最大 50）、`categoryIds`、`classificationIds`、`tagIds`。id 用 JSON 数组，不放查询串。同一组多选为或，组与组之间为且 |
|
||||
| GET | `/app/playlists?pageIndex=&pageSize=` | 已启用剧单列表，分页。`pageIndex` 默认 1，`pageSize` 默认 10、最大 20 |
|
||||
| GET | `/app/playlists/{id}?pageIndex=&pageSize=` | 剧单详情。短剧按页返回。`pageIndex` 默认 1，`pageSize` 默认 20、最大 50。下架或不存在返回 `200002` |
|
||||
| GET | `/app/dramas/{id}` | 详情（含剧集列表，免费集带**已签名**播放地址） |
|
||||
| GET | `/app/search?keyword=&pageIndex=&pageSize=` | **匿名**。搜索已上线短剧：按标题/简介模糊匹配，分页返回卡片列表 |
|
||||
|
||||
`POST /app/dramas/page` 请求体：
|
||||
|
||||
```json
|
||||
{
|
||||
"pageIndex": 1,
|
||||
"pageSize": 20,
|
||||
"categoryIds": ["2112443900437336065"],
|
||||
"classificationIds": ["2112807182243336193"],
|
||||
"tagIds": ["2113500000000000002"]
|
||||
}
|
||||
```
|
||||
|
||||
省略的 id 数组表示这一组不筛选。`pageIndex` 小于 1 按 1，`pageSize` 小于 1 按 1，大于 50 按 50。响应仍是 `{total, list}`，卡片结构与首页一致。
|
||||
|
||||
> 卡片（`AppDramaCardVO`）统一新增 `language` 字段（取值如 `zh-CN` / `id`），
|
||||
> 首页、发现页、分类、收藏、搜索等所有下发卡片的场景都带该字段，客户端可据此做语言筛选。
|
||||
>
|
||||
@@ -180,9 +200,21 @@ app.register.max-per-device-per-day
|
||||
> `drama_episode.like_count` 与 `content_comment.episode_id` 统计（排除逻辑删除与 `status = 'deleted'`）；
|
||||
> `viewCount` 热度仍取整部剧。首页、发现、分类、收藏、搜索等列表卡片结构一致。
|
||||
>
|
||||
> 卡片文案只放语言表：`titleLocales`、`synopsisLocales`、`types`、`tagLocales`。
|
||||
> `tagColor` 是标签背景色。中文取各表的 `zh`。
|
||||
>
|
||||
> 卡片新增 `dramaType`：`ANIME` 表示漫剧，`LIVE` 表示真人剧。
|
||||
> 客户端字段仍返回主内容类型；后台多选值保存在 `drama.drama_types`，
|
||||
> App 类型筛选按逗号列整词匹配，因此 `ANIME,LIVE` 多标签剧可被任一类型命中。
|
||||
>
|
||||
> `GET /app/playlists` 与 `GET /app/playlists/{id}` 匿名可访问。列表返回 `{total, list}`。
|
||||
> 列表项与详情的名称在 `locales`，描述在 `descriptionLocales`，key 为 `zh` / `en` / `id`。
|
||||
> `name` 与 `description` 等于中文。客户端按当前语言取对应 key，没有则用 `zh`。
|
||||
> 其余字段：`id`、`dramaCount`（已上线短剧条数），
|
||||
> 列表里每条剧单的 `list` 只是短剧第 1 页、每页 10 条。短剧翻页走详情：
|
||||
> `pageIndex`、`pageSize` 会原样回在详情里，`dramaCount` 是短剧总数，`list` 是当前页卡片。
|
||||
> 只返回 `status = 1` 的剧单，排序与后台剧单排序一致，卡片顺序与后台关联顺序一致。
|
||||
> 剧单列表越界页返回空 `list`，`total` 仍是全部剧单数。详情越界页同样返回空 `list`。
|
||||
|
||||
#### 推荐类型流（`GET /app/feed`）
|
||||
|
||||
@@ -356,6 +388,11 @@ app.register.max-per-device-per-day
|
||||
"dramaId": "12",
|
||||
"episodeId": "88",
|
||||
"dramaTitle": "替嫁新娘：总裁的掌心宠",
|
||||
"titleLocales": {
|
||||
"zh": "替嫁新娘：总裁的掌心宠",
|
||||
"en": "The Stand-in Bride: The CEO's Beloved",
|
||||
"id": "Pengantin Pengganti: Kesayangan Presiden Direktur"
|
||||
},
|
||||
"dramaCover": "/files/drama_cover/12.jpg",
|
||||
"episodeNumber": 6,
|
||||
"totalEpisodes": 68,
|
||||
@@ -377,7 +414,8 @@ app.register.max-per-device-per-day
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| `dramaTitle` | string / null | 短剧标题 |
|
||||
| `dramaTitle` | string / null | 短剧中文标题，旧客户端回退用 |
|
||||
| `titleLocales` | object / null | 短剧标题语言表，key 为 `zh` / `en` / `id`。客户端按当前语言取，没有对应语言时回退 `zh` |
|
||||
| `dramaCover` | string / null | 短剧封面 |
|
||||
| `episodeNumber` | int / null | 当前续看集号 `ep_no` |
|
||||
| `totalEpisodes` | int / null | 短剧总集数 |
|
||||
@@ -656,6 +694,16 @@ GET /app/notices?pageIndex=1&pageSize=20
|
||||
- 列表响应返回 `dramaTypes[]`、`categoryIds[]` 与按选中顺序映射的 `categoryNames[]`；
|
||||
分类名缺失时回退 `genre`。
|
||||
- 后台与 App 过滤均使用 `(',' || column || ',') LIKE '%,value,%'` 整词匹配。
|
||||
- 短剧另有单选标签 `tagId`。不传保持原值，传 `0` 清空。列表返回 `tagId`、`tagName`、`tagNameEn`、`tagNameId`。后台编辑不再提交内容类型。
|
||||
|
||||
**标签**
|
||||
|
||||
| 方法 | 路径 | 权限点 | 说明 |
|
||||
| --- | --- | --- | --- |
|
||||
| GET | `/admin/content-tags?enabledOnly=` | `drama:list` | 标签列表。`enabledOnly=true` 只返回启用项 |
|
||||
| POST | `/admin/content-tags` | `drama:create` | 新建。`locales` 勾选语言，中文必填，英文和印尼语可选 |
|
||||
| PUT | `/admin/content-tags/{id}` | `drama:update` | 编辑 |
|
||||
| DELETE | `/admin/content-tags/{id}` | `drama:delete` | 删除，并清空已选该标签的短剧 |
|
||||
|
||||
**剧集**
|
||||
|
||||
@@ -827,6 +875,7 @@ GET /app/notices?pageIndex=1&pageSize=20
|
||||
| --- | --- | --- | --- |
|
||||
| GET | `/admin/dashboard/overview` | `dashboard:view` | 总览：用户 / 内容 / 播放 / 收入 / 成本 |
|
||||
| GET | `/admin/dashboard/transcode` | `dashboard:view` | 转码队列积压与失败任务明细（含 `errorMsg` / `retryCount`） |
|
||||
| GET | `/admin/notifications/transcode` | `drama:list` | 转码通知：`running` / `success` / `failed` 角标，以及各状态最近 20 条（含 `dramaTitle`、`episodeNo`、`episodeTitle`） |
|
||||
|
||||
**口径（与代码注释一致，前端 tooltip 可直接复用）**
|
||||
|
||||
@@ -834,6 +883,8 @@ GET /app/notices?pageIndex=1&pageSize=20
|
||||
| --- | --- | --- |
|
||||
| 用户 | `total` / `newToday` / `new7d` | `app_user` 未删除总数；按 `created_at` 落在当天 / 近 7 天 |
|
||||
| 用户 | `active7d` | `last_login_at` 在近 7 天内。**不是 DAU**，日活需要逐日登录快照，当前无产出 |
|
||||
| 用户 | `androidActive7d` / `iosActive7d` | `app_user_device` 中 `status=active` 且 `last_seen_at` 在近 7 天的去重设备，平台分别为 `ANDROID` / `IOS` |
|
||||
| 用户 | `retention1d` / `retention7d` | 次日留存：昨日注册且今天仍登录的比例。7 日留存：8 至 14 天前注册、近 7 天仍登录的比例。队列为空返回 `null`，取值 0 到 1 |
|
||||
| 用户 | `banned` / `limited` / `deactivated` | 按 `status` 计数 |
|
||||
| 内容 | `drama*` | 短剧按 `status` 计数（`reviewing` 为待审、`published` 为已上线） |
|
||||
| 内容 | `episodeTotal` / `Published` / `WithMedia` | 剧集总数 / 已上线数 / `video_url` 非空数（均排除逻辑删除） |
|
||||
|
||||
Reference in new issue
Block a user