首页模块

首页接口用于加载推荐分类、轮播以及频道模块数据。建议的请求顺序为：先获取分类列表，再按分类获取详情。

获取分类

• Method：GET
• Path：/api/mobile/v1/home/type_List
• 说明：返回一级分类列表，后端会额外插入一个虚拟的“推荐”分类（typeId = 0）。
• 数据来源：mac_type 表中 type_pid = 0 且 type_status = 1 的记录。

响应字段

字段	类型	说明
typeId	number	分类 ID，0 表示推荐
typeName	string	分类名，用于顶部 Tab
typeSort	number	排序权重，数值越小越靠前
typePid	number	父级分类 ID，顶级为 0

如果后端在 AppConfig 中配置了 defaultTypeId，客户端可优先使用该分类作为首屏展示。

获取首页数据

• Method：GET
• Path：/api/mobile/v1/home
• Query：

参数	必填	类型	默认值	说明
typeId	否	number	0	分类 ID。0 代表推荐页，其余值对应子分类。

响应结构

{
  "code": 0,
  "message": "OK",
  "data": {
    "banner": [],
    "children": [],
    "modules": []
  }
}

• banner：轮播图数组，来自 vod 表的推荐内容。包含 vodId、vodName、vodPic、vodRemarks、vodActor、vodDirector、vodTag、vodTime 等字段，并且额外附带 typeName。
• children：若当前分类存在二级分类或快捷入口，会返回对应数组。opensFilter = true 表示点击后跳到筛选页而非重新请求首页。
• modules：主要展示内容，每个模块包含：
  • title：模块标题（通常与分类同名）。
  • typeId / typePid：模块归属分类。
  • vodList：视频数组（字段与轮播一致）。
  • more：是否展示“更多”入口，客户端可跳转到筛选页。

热播板块

当 typeId = 0 时，额外返回热播板块数据，其取数逻辑为：

• 根据 AppConfig 中的 hotLevel、hotNum 选择推荐影片。
• 返回字段与 vodList 相同。

缓存策略

• 当 AppConfig.data.redisStatus = true 时，接口会优先读取 Redis 缓存，键名格式为 ${redisKey}_homeData_${typeId}。
• 更新首页配置后，可通过后台管理关闭缓存或清除 Redis 对应键，避免旧数据继续命中。

调用示例

GET /api/mobile/v1/home?typeId=2 HTTP/1.1
Host: api.movie.example
User-Agent: movieapp/1.0 (Android)

响应示例（截断）：

{
  "code": 0,
  "data": {
    "banner": [
      {
        "vodId": 216862,
        "vodName": "三更雪",
        "vodPic": "https://cdn.example/banner1.jpg",
        "vodRemarks": "更新至第08集",
        "typeName": "国产剧"
      }
    ],
    "children": [
      { "typeId": 0, "typeName": "全部", "opensFilter": false },
      { "typeId": 2, "typeName": "更多", "opensFilter": true }
    ],
    "modules": [
      {
        "title": "国产剧",
        "vodList": [
          { "vodId": 213847, "vodName": "照镜辞", "vodRemarks": "更新至第10集" }
        ],
        "more": true
      }
    ]
  },
  "message": "OK"
}

建议客户端缓存首页数据并提供下拉刷新，避免短时间内重复命中后端。

配置与数据关系

• 一级/二级分类：直接读取 mac_type 表。后台管理 → 内容管理 / 分类 操作即写入该表。
• Banner：
  • bannerLevel：默认推荐等级数组，适用于全部分类。
  • bannerLevel_<typeId>：为指定分类覆盖默认等级，例如 bannerLevel_2 只对 typeId=2 生效。
  • bannerNum：每次拉取的轮播数量（建议 ≤9），用于 take。
  • 数据来源为 mac_vod，过滤条件为 vod_level ∈ bannerLevel*、vodStatus=1，并按 vodTime 倒序。
• 模块列表：
  • cateNum：每个分类模块展示的影片数；二级分类模式下取 cateNum * 2。
  • 模块标题与 typeName 来自 mac_type。
• 热播板块：
  • hotTitle：热播模块标题（默认“正在热播”）。
  • hotLevel：用于挑选热播影片的推荐等级。
  • hotNum：热播模块数量。
• 广告预留（type=Ads）：
  • status：广告系统总开关。
  • bannerStatus / banner：首页顶部广告状态与图片地址（https）。
  • indexCateStatus / indexCate：板块广告状态与素材地址。
  • 当前服务端未返回广告数据，若后续在首页接口中加入广告位，可依赖上述字段控制展示。
• 缓存：后台管理 → APP 管理 / 基础配置（type=AppConfig）中的 redisStatus、redisKey、redisTime 控制是否缓存首页数据及缓存前缀/有效期（秒）。

若首页展示与预期不符，排查顺序建议为：① 检查 app_config JSON → ② 核对 mac_vod / mac_type 数据 → ③ 查看 Redis 是否仍持有旧数据。