refactor(dramas): 重构短剧预搜索功能，改为搜索短剧本身
1. 将预搜索接口从剧集维度改为短剧维度，移除剧集相关逻辑 2. 新增短剧列表按标题筛选的能力 3. 更新测试用例与接口文档，修正命名与逻辑
This commit is contained in:
590
docs/apifox-app-apis.openapi.json
Normal file
590
docs/apifox-app-apis.openapi.json
Normal file
@@ -0,0 +1,590 @@
|
||||
{
|
||||
"openapi": "3.0.3",
|
||||
"info": {
|
||||
"title": "CTH TK App APIs",
|
||||
"description": "Apifox import file for mini app drama and history APIs.",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"servers": [
|
||||
{
|
||||
"url": "http://localhost:3000",
|
||||
"description": "Local backend"
|
||||
}
|
||||
],
|
||||
"tags": [
|
||||
{
|
||||
"name": "App Dramas",
|
||||
"description": "Mini app drama APIs"
|
||||
},
|
||||
{
|
||||
"name": "App History",
|
||||
"description": "Mini app playback history APIs"
|
||||
}
|
||||
],
|
||||
"paths": {
|
||||
"/api/app/v1/dramas": {
|
||||
"get": {
|
||||
"tags": ["App Dramas"],
|
||||
"summary": "短剧列表",
|
||||
"operationId": "listAppDramas",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/Page" },
|
||||
{ "$ref": "#/components/parameters/PageSize10" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/AppDramaPage"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/app/v1/dramas/recommended": {
|
||||
"get": {
|
||||
"tags": ["App Dramas"],
|
||||
"summary": "推荐短剧列表",
|
||||
"operationId": "listRecommendedAppDramas",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/Page" },
|
||||
{ "$ref": "#/components/parameters/PageSize10" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/AppDramaPage"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/app/v1/dramas/presearch": {
|
||||
"get": {
|
||||
"tags": ["App Dramas"],
|
||||
"summary": "关键字预查询视频列表",
|
||||
"operationId": "presearchAppDramaVideos",
|
||||
"parameters": [
|
||||
{
|
||||
"name": "keyword",
|
||||
"in": "query",
|
||||
"description": "用户输入关键字；空值返回空列表",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "string"
|
||||
},
|
||||
"example": "skyline"
|
||||
},
|
||||
{ "$ref": "#/components/parameters/Page" },
|
||||
{ "$ref": "#/components/parameters/PageSize10" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/VideoPresearchPage"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/app/v1/dramas/{id}/episodes": {
|
||||
"get": {
|
||||
"tags": ["App Dramas"],
|
||||
"summary": "短剧剧集列表",
|
||||
"operationId": "listAppDramaEpisodes",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/DramaIdPath" },
|
||||
{ "$ref": "#/components/parameters/Page" },
|
||||
{ "$ref": "#/components/parameters/PageSize20" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/AppEpisodePage"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": { "$ref": "#/components/responses/ErrorResponse" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/app/v1/dramas/{id}": {
|
||||
"get": {
|
||||
"tags": ["App Dramas"],
|
||||
"summary": "短剧详情",
|
||||
"operationId": "getAppDrama",
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/DramaIdPath" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/AppDramaDetail"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"404": { "$ref": "#/components/responses/ErrorResponse" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"/api/app/v1/history": {
|
||||
"get": {
|
||||
"tags": ["App History"],
|
||||
"summary": "播放历史列表",
|
||||
"operationId": "listAppHistory",
|
||||
"security": [
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
],
|
||||
"parameters": [
|
||||
{ "$ref": "#/components/parameters/Page" },
|
||||
{ "$ref": "#/components/parameters/PageSize20" }
|
||||
],
|
||||
"responses": {
|
||||
"200": {
|
||||
"description": "OK",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/PlaybackHistoryPage"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"401": { "$ref": "#/components/responses/ErrorResponse" }
|
||||
}
|
||||
},
|
||||
"post": {
|
||||
"tags": ["App History"],
|
||||
"summary": "上报播放历史",
|
||||
"operationId": "upsertAppHistory",
|
||||
"security": [
|
||||
{
|
||||
"bearerAuth": []
|
||||
}
|
||||
],
|
||||
"requestBody": {
|
||||
"required": true,
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"$ref": "#/components/schemas/UpsertPlaybackHistoryRequest"
|
||||
},
|
||||
"example": {
|
||||
"episodeId": 123,
|
||||
"progressSeconds": 86,
|
||||
"completed": false,
|
||||
"occurredAt": "2026-07-02T10:00:00.000Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"201": {
|
||||
"description": "Created",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"data": {
|
||||
"$ref": "#/components/schemas/PlaybackHistoryRecord"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"400": { "$ref": "#/components/responses/ErrorResponse" },
|
||||
"401": { "$ref": "#/components/responses/ErrorResponse" },
|
||||
"404": { "$ref": "#/components/responses/ErrorResponse" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"components": {
|
||||
"securitySchemes": {
|
||||
"bearerAuth": {
|
||||
"type": "http",
|
||||
"scheme": "bearer",
|
||||
"bearerFormat": "JWT"
|
||||
}
|
||||
},
|
||||
"parameters": {
|
||||
"DramaIdPath": {
|
||||
"name": "id",
|
||||
"in": "path",
|
||||
"required": true,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"minimum": 1
|
||||
},
|
||||
"example": 1
|
||||
},
|
||||
"Page": {
|
||||
"name": "page",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"default": 1
|
||||
}
|
||||
},
|
||||
"PageSize10": {
|
||||
"name": "pageSize",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 10
|
||||
}
|
||||
},
|
||||
"PageSize20": {
|
||||
"name": "pageSize",
|
||||
"in": "query",
|
||||
"required": false,
|
||||
"schema": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 100,
|
||||
"default": 20
|
||||
}
|
||||
}
|
||||
},
|
||||
"responses": {
|
||||
"ErrorResponse": {
|
||||
"description": "Error response",
|
||||
"content": {
|
||||
"application/json": {
|
||||
"schema": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/ApiResponseBase" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"code": { "type": "integer", "example": 404 },
|
||||
"data": { "type": "object", "example": {} },
|
||||
"message": { "type": "string", "example": "Not found" }
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"schemas": {
|
||||
"ApiResponseBase": {
|
||||
"type": "object",
|
||||
"required": ["code", "data", "message", "timestamp", "requestId", "cost"],
|
||||
"properties": {
|
||||
"code": {
|
||||
"type": "integer",
|
||||
"description": "业务响应码；成功为 0，错误为 HTTP 状态码",
|
||||
"example": 0
|
||||
},
|
||||
"data": {
|
||||
"type": "object"
|
||||
},
|
||||
"message": {
|
||||
"type": "string",
|
||||
"example": "success"
|
||||
},
|
||||
"timestamp": {
|
||||
"type": "integer",
|
||||
"format": "int64",
|
||||
"example": 1782986400000
|
||||
},
|
||||
"requestId": {
|
||||
"type": "string",
|
||||
"example": "550e8400-e29b-41d4-a716-446655440000"
|
||||
},
|
||||
"cost": {
|
||||
"type": "string",
|
||||
"example": "12ms"
|
||||
}
|
||||
}
|
||||
},
|
||||
"Pagination": {
|
||||
"type": "object",
|
||||
"required": ["page", "pageSize", "total"],
|
||||
"properties": {
|
||||
"page": { "type": "integer", "example": 1 },
|
||||
"pageSize": { "type": "integer", "example": 10 },
|
||||
"total": { "type": "integer", "example": 100 }
|
||||
}
|
||||
},
|
||||
"AppDrama": {
|
||||
"type": "object",
|
||||
"required": ["id", "title", "coverUrl", "type", "tags", "status", "sortOrder", "isRecommended", "onlineVersion", "totalEpisodes", "publishedEpisodes", "createdAt", "updatedAt"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "example": 1 },
|
||||
"tiktokAlbumId": { "type": "string", "nullable": true },
|
||||
"title": { "type": "string", "example": "Published Drama" },
|
||||
"description": { "type": "string", "nullable": true },
|
||||
"coverId": { "type": "integer", "nullable": true },
|
||||
"coverUrl": { "type": "string", "example": "https://cdn.example.com/cover.jpg" },
|
||||
"type": { "type": "string", "example": "romance" },
|
||||
"tags": { "type": "array", "items": { "type": "string" } },
|
||||
"region": { "type": "string", "nullable": true },
|
||||
"language": { "type": "string", "nullable": true },
|
||||
"year": { "type": "integer", "nullable": true },
|
||||
"status": { "type": "string", "enum": ["draft", "scheduled", "published", "offline"], "example": "published" },
|
||||
"sortOrder": { "type": "integer", "example": 0 },
|
||||
"isRecommended": { "type": "boolean", "example": true },
|
||||
"onlineVersion": { "type": "integer", "example": 1 },
|
||||
"totalEpisodes": { "type": "integer", "example": 20 },
|
||||
"publishedEpisodes": { "type": "integer", "example": 10 },
|
||||
"createdAt": { "type": "string", "format": "date-time" },
|
||||
"updatedAt": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
},
|
||||
"AppDramaDetail": {
|
||||
"allOf": [
|
||||
{ "$ref": "#/components/schemas/AppDrama" },
|
||||
{
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"portraitCoverUrl": { "type": "string", "nullable": true },
|
||||
"landscapeCoverUrl": { "type": "string", "nullable": true }
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"AppDramaPage": {
|
||||
"type": "object",
|
||||
"required": ["list", "pagination"],
|
||||
"properties": {
|
||||
"list": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/components/schemas/AppDrama" }
|
||||
},
|
||||
"pagination": { "$ref": "#/components/schemas/Pagination" }
|
||||
}
|
||||
},
|
||||
"AppEpisode": {
|
||||
"type": "object",
|
||||
"required": ["id", "dramaId", "albumId", "episodeNo", "seq", "title", "coverUrl", "durationSeconds", "isPaid", "freeType", "price", "status", "reviewStatus", "publishStatus", "createdAt", "updatedAt"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "example": 1 },
|
||||
"dramaId": { "type": "integer", "example": 1 },
|
||||
"albumId": { "type": "integer", "example": 1 },
|
||||
"tiktokEpisodeId": { "type": "string", "nullable": true },
|
||||
"episodeNo": { "type": "integer", "example": 1 },
|
||||
"seq": { "type": "integer", "example": 1 },
|
||||
"title": { "type": "string", "example": "Episode 1" },
|
||||
"description": { "type": "string", "nullable": true },
|
||||
"byteplusVid": { "type": "string", "nullable": true },
|
||||
"coverId": { "type": "integer", "nullable": true },
|
||||
"coverUrl": { "type": "string", "example": "https://cdn.example.com/episode.jpg" },
|
||||
"videoUrl": { "type": "string", "nullable": true },
|
||||
"storageBucket": { "type": "string", "nullable": true },
|
||||
"objectKey": { "type": "string", "nullable": true },
|
||||
"trialDurationSeconds": { "type": "integer", "nullable": true },
|
||||
"durationSeconds": { "type": "integer", "example": 300 },
|
||||
"width": { "type": "integer", "nullable": true },
|
||||
"height": { "type": "integer", "nullable": true },
|
||||
"isPaid": { "type": "boolean", "example": false },
|
||||
"freeType": { "type": "string", "enum": ["free", "paid"], "example": "free" },
|
||||
"unlockPrice": { "type": "integer", "nullable": true },
|
||||
"price": { "type": "integer", "example": 0 },
|
||||
"publishAt": { "type": "string", "format": "date-time", "nullable": true },
|
||||
"nextReleaseAt": { "type": "string", "format": "date-time", "nullable": true },
|
||||
"status": { "type": "string", "enum": ["draft", "scheduled", "published", "offline"], "example": "published" },
|
||||
"reviewStatus": { "type": "string", "enum": ["not_submitted", "pending", "reviewing", "approved", "rejected"], "example": "approved" },
|
||||
"reviewMessage": { "type": "string", "nullable": true },
|
||||
"publishStatus": { "type": "string", "enum": ["draft", "scheduled", "published", "offline"], "example": "published" },
|
||||
"createdAt": { "type": "string", "format": "date-time" },
|
||||
"updatedAt": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
},
|
||||
"AppEpisodePage": {
|
||||
"type": "object",
|
||||
"required": ["list", "pagination"],
|
||||
"properties": {
|
||||
"list": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/components/schemas/AppEpisode" }
|
||||
},
|
||||
"pagination": { "$ref": "#/components/schemas/Pagination" }
|
||||
}
|
||||
},
|
||||
"VideoPresearchItem": {
|
||||
"type": "object",
|
||||
"required": ["id", "dramaId", "episodeNo", "title", "coverUrl", "durationSeconds", "freeType", "price", "dramaTitle", "dramaCoverUrl"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "example": 1 },
|
||||
"dramaId": { "type": "integer", "example": 1 },
|
||||
"episodeNo": { "type": "integer", "example": 1 },
|
||||
"title": { "type": "string", "example": "Pilot Video Match" },
|
||||
"description": { "type": "string", "nullable": true },
|
||||
"coverUrl": { "type": "string", "example": "https://cdn.example.com/episode.jpg" },
|
||||
"durationSeconds": { "type": "integer", "example": 180 },
|
||||
"byteplusVid": { "type": "string", "nullable": true },
|
||||
"videoUrl": { "type": "string", "nullable": true },
|
||||
"freeType": { "type": "string", "enum": ["free", "paid"], "example": "free" },
|
||||
"price": { "type": "integer", "example": 0 },
|
||||
"dramaTitle": { "type": "string", "example": "Skyline Keyword Saga" },
|
||||
"dramaCoverUrl": { "type": "string", "example": "https://cdn.example.com/drama.jpg" }
|
||||
}
|
||||
},
|
||||
"VideoPresearchPage": {
|
||||
"type": "object",
|
||||
"required": ["list", "pagination"],
|
||||
"properties": {
|
||||
"list": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/components/schemas/VideoPresearchItem" }
|
||||
},
|
||||
"pagination": { "$ref": "#/components/schemas/Pagination" }
|
||||
}
|
||||
},
|
||||
"UpsertPlaybackHistoryRequest": {
|
||||
"type": "object",
|
||||
"required": ["episodeId", "progressSeconds"],
|
||||
"properties": {
|
||||
"episodeId": { "type": "integer", "minimum": 1, "example": 123 },
|
||||
"progressSeconds": { "type": "integer", "minimum": 0, "example": 86 },
|
||||
"completed": { "type": "boolean", "example": false },
|
||||
"occurredAt": { "type": "string", "format": "date-time", "example": "2026-07-02T10:00:00.000Z" }
|
||||
}
|
||||
},
|
||||
"PlaybackHistoryRecord": {
|
||||
"type": "object",
|
||||
"required": ["id", "userId", "dramaId", "episodeId", "progressSeconds", "durationSeconds", "completed", "lastPlayedAt", "createdAt", "updatedAt"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "example": 1 },
|
||||
"userId": { "type": "integer", "example": 1 },
|
||||
"dramaId": { "type": "integer", "example": 1 },
|
||||
"episodeId": { "type": "integer", "example": 123 },
|
||||
"progressSeconds": { "type": "integer", "example": 86 },
|
||||
"durationSeconds": { "type": "integer", "example": 300 },
|
||||
"completed": { "type": "boolean", "example": false },
|
||||
"lastPlayedAt": { "type": "string", "format": "date-time" },
|
||||
"createdAt": { "type": "string", "format": "date-time" },
|
||||
"updatedAt": { "type": "string", "format": "date-time" }
|
||||
}
|
||||
},
|
||||
"PlaybackHistoryListItem": {
|
||||
"type": "object",
|
||||
"required": ["id", "dramaId", "episodeId", "episodeNo", "title", "coverUrl", "progressSeconds", "durationSeconds", "completed", "lastPlayedAt", "dramaTitle", "dramaCoverUrl"],
|
||||
"properties": {
|
||||
"id": { "type": "integer", "example": 1 },
|
||||
"dramaId": { "type": "integer", "example": 1 },
|
||||
"episodeId": { "type": "integer", "example": 123 },
|
||||
"episodeNo": { "type": "integer", "example": 1 },
|
||||
"title": { "type": "string", "example": "History Episode" },
|
||||
"coverUrl": { "type": "string", "example": "https://cdn.example.com/history-episode.jpg" },
|
||||
"progressSeconds": { "type": "integer", "example": 86 },
|
||||
"durationSeconds": { "type": "integer", "example": 300 },
|
||||
"completed": { "type": "boolean", "example": false },
|
||||
"lastPlayedAt": { "type": "string", "format": "date-time" },
|
||||
"dramaTitle": { "type": "string", "example": "History Drama" },
|
||||
"dramaCoverUrl": { "type": "string", "example": "https://cdn.example.com/history-drama.jpg" }
|
||||
}
|
||||
},
|
||||
"PlaybackHistoryPage": {
|
||||
"type": "object",
|
||||
"required": ["list", "pagination"],
|
||||
"properties": {
|
||||
"list": {
|
||||
"type": "array",
|
||||
"items": { "$ref": "#/components/schemas/PlaybackHistoryListItem" }
|
||||
},
|
||||
"pagination": { "$ref": "#/components/schemas/Pagination" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user