MovieApp 开发文档

Appearance

筛选与搜索 ​

筛选系列接口用于构建分类筛选页，搜索接口用于模糊匹配影片名称。所有请求均为 GET 请求。

获取筛选配置 ​

  • Path：/api/mobile/v1/vod/filterList
  • 说明：返回分类树与对应可选过滤项。过滤项来源于后台管理 Cate 配置。
  • 数据来源：
    • 分类树：mac_type 表（递归构建）。
    • 过滤项：app_config 表中 type=Cate 的 JSON。每个一级分类都有一个 filter_<typeId> 对象。

响应示例（截断）：

json
[
  {
    "typeId": 1,
    "typeName": "电影",
    "typePid": 0,
    "typeEn": "movie",
    "children": [
      { "typeId": 101, "typeName": "动作片", "typePid": 1 }
    ],
    "filters": {
      "areaFilter": ["中国大陆", "中国香港", "美国"],
      "yearFilter": ["2025", "2024", "2023"],
      "plotFilter": ["剧情", "科幻"],
      "letterFilter": ["A", "B", "C"]
    }
  }
]

字段说明：

  • children：二级分类列表，可递归嵌套。
  • filters：仅当后台配置存在时返回，包含地区、年份、剧情、首字母等筛选条件。

获取筛选结果 ​

  • Path：/api/mobile/v1/vod/filter/list
  • Query：
参数必填类型说明
filterId是string当前筛选组 ID，后端用于日志定位。
page是string页码，从 1 开始。
pageSize是string每页条数。若后台配置了 pageNum，以后台为准。
sortId否string排序方式，可选 Time（最新）、Hits（热度）、Score（评分），默认为 Time。
filters[typeId_1]否string一级分类 ID。
filters[typeId]否string二级分类 ID。
filters[areaFilter]否string地区筛选，需与后台配置值一致。
filters[yearFilter]否string年份筛选，如 2024。
filters[plotFilter]否string剧情标签，多个值用逗号分隔。
filters[letterFilter]否string首字母筛选，单个字母。

响应结构：

json
{
  "page": 1,
  "pageSize": 20,
  "total": 145,
  "hasMore": true,
  "items": [
    {
      "vodId": 216862,
      "vodName": "三更雪",
      "vodPic": "https://cdn.example/xxx.jpg",
      "vodYear": "2025",
      "vodArea": "中国大陆",
      "vodRemarks": "更新至第08集",
      "typeId": 13,
      "vodActor": "何蓝逗, 邓孝慈"
    }
  ]
}

注意事项：

  • 排序字段将映射到数据表中的 vod{sortId} 列，例如 Time → vodTime。
  • 当 filters.plotFilter 为多个值时，后端会将其拆分为数组并使用 IN 查询。
  • 返回的 pageSize 以实际查询数量为准；若最后一页不足填满，pageSize 会小于入参。

搜索视频 ​

  • Path：/api/mobile/v1/vod/search
  • Query：
参数必填类型说明
keyword是string搜索关键字，后端按前缀匹配（vodName LIKE \${keyword}%``）。

响应示例：

json
[
  {
    "vodId": 31231,
    "vodName": "长风渡",
    "typeId": 1,
    "typeName": "电影",
    "vodPic": "https://cdn.example/poster.jpg",
    "vodRemarks": "已完结",
    "vodScore": 8.5,
    "vodArea": "中国大陆",
    "vodYear": "2023",
    "vodLang": "普通话",
    "vodDuration": "45分钟",
    "vodBlurb": "古装爱情剧",
    "vodActor": "罗云熙",
    "vodDirector": "尹涛"
  }
]

搜索接口不做分页处理，返回结果数量由数据库匹配数量决定。建议在客户端做节流处理（如 300ms）并限制关键字长度，避免过高的查询频率。

配置与数据关系 ​

  • 筛选条件维护：后台管理 → APP 管理 / 分类 编辑 type=Cate 配置。每个分类的筛选字段在 JSON 的 filter_<typeId> 下维护，例如：
    json
    {
  "filter_13": {
    "areaFilter": ["中国大陆", "中国香港"],
    "yearFilter": ["2025", "2024"]
  },
  "pageNum": 20
}
  • 分页：同一配置中的 pageNum 会覆盖客户端传入的 pageSize。
  • 排序：客户端传入 sortId 与 mobile.service.ts 中的白名单匹配；默认映射到 mac_vod 表的 vodTime、vodHits、vodScore。
  • 内容数据：所有筛选和搜索结果均来自 mac_vod，需要结合 mac_type 的 ID 进行过滤。若出现空列表，先确认 mac_vod 中是否存在满足条件的条目。
  • 过滤字段说明：plotFilter/areaFilter/yearFilter/languageFilter/letterFilter/sortFilter 均包含 { status: boolean, value: string, title: string }：
    • status：是否启用该筛选项。
    • value：逗号分隔的选项列表，移动端在展示前需要 split(',')。
    • title：推荐展示标题，可用于多语言或文案调整。
  • 搜索推荐配置：type=Search 中字段与页面对应关系如下：
    字段说明影响逻辑
    searchLikeLevel（或 searchLevel）“猜你想搜”推荐等级数组getSearchRecommend 选取影片时使用；若前端保存为 searchLikeLevel，后端会直接使用该字段。
    searchLikeNum（或 searchNum）“猜你想搜”展示数量控制推荐取数数量（默认 9）。
    searchResultLevel搜索结果中优先展示的等级（预留）当前移动端未消费，可用于扩展搜索结果排序。
  • 搜索推荐缓存：当 AppConfig.redisStatus=true 时，getSearchRecommend 结果会按 redisKey + '_searchRecommend' 缓存 redisTime 秒。