mexico_c_end_frontend.md
XS450-墨西哥1.0(客户端、前端)/mexico_c_end_frontend.md · 7.2 KB · 2026-11-19 15:09:42
原始文件 下载

墨西哥 1.0 C 端 — 前端对接说明

面向 C 端 App 前端。分支:test-old。
管理端相关字段见 admin_new_features_frontend.md。

通用约定


需求一览(前端要做什么)

# 需求 前端动作 后端是否改
1 剧评分 首页 / 详情展示 score 已有字段
2 播放量升降 首页 / 详情按 views_trend 画箭头 新增字段
3 新增两个分组 首页原接口渲染即可(运营配置) 无
4 顶栏轮播分类 按 category / carousel_only 拆轮播与板块 已有字段
5 剧详情页 调详情接口做新页面 已有 + 补 trend
6 搜索历史 本地存储关键词 无接口
7 隐藏 AI 聊天 / 等级机器人 藏入口;其它机器人保留 配置开关
8 支持历史两栏 同一接口传不同 tips_method 新增筛选
9 周日历每日奖励 调分布接口 + 补齐 7 天 0 已有接口
10 自行解绑谷歌验证码 新解绑接口 新接口
11 帮助中心 静态 / CMS,自建页 无接口

1. 剧评分 score

项 说明
字段 playlet.score(string)
未填 "" → 不展示或显示「暂无」
有值 如 "8"、"8.5"(最多 1 位小数)

出现位置:


2. 播放量升降 views_trend

枚举

值 名 UI 建议
0 VIEWS_TREND_UNKNOWN 当持平
1 VIEWS_TREND_UP ↑ 上升
2 VIEWS_TREND_DOWN ↓ 下降
3 VIEWS_TREND_FLAT 持平 / 不显示箭头

哪里有

场景 Path 字段位置
首页 /v1/playlet/group/home/list 每条 playlet.views_trend
详情 /v1/playlet/details/page/list playlet.views_trend

搜索列表等其它接口本阶段没有此字段。
与展示用的 views 数字无关,只表示相对昨日升/降(日界按 UTC)。


3. 新增两个分组

运营在管理端创建两个首页分组即可,前端不用改接口。
继续用:POST /v1/playlet/group/home/list。


4. 分组一级分类 → 顶栏轮播

首页每个分组批次带:

字段 值 含义
category 1 CAROUSEL 轮播
category 2 HOME_SECTION 首页板块
category 3 TAG 标签
carousel_only true 只出现在轮播,不要进板块列表

前端渲染规则

  1. 顶栏轮播:category == 1(CAROUSEL),或 carousel_only == true
  2. 下方板块:category == 2(HOME_SECTION),且 carousel_only != true
  3. 标签类按产品需要决定是否展示

5. 剧详情页

项 值
Path /v1/playlet/details/page/list
Body { "playlet_id": 123 }

响应要点

{
  "playlet": {
    "id": 123,
    "score": "8.5",
    "views": 100000,
    "views_trend": 1,
    "titles": [...],
    "covers": [...]
  },
  "total": 80,
  "episodes": [...],
  "more_playlets": [...],
  "iv": "..."
}
字段 用途
playlet 封面、评分、播放量、升降、简介等
episodes 剧集列表
more_playlets 更多推荐
iv 播放解密用(沿用现有逻辑)

6. 搜索历史(纯前端)

项 值
Path /v1/playlet/search/list
Body { "keyword": "xxx", "offset": 0, "limit": 20 }

没有服务端搜索历史读写接口。


7. 隐藏 AI 聊天 + 等级机器人

墨西哥站服务端会开:

features:
  disable_ai_chat: true
  disable_tips_level_robot: true

前端必须做

直调接口时(防漏)

接口 行为
聊天 list(role / session / message) 空列表
聊天写(completion / create / remove / report) code = 11006 CODE_FORBIDDEN
等级机器人 list 空列表
等级机器人购买 11006

8. 支持历史:短剧 / AI 机器人两栏

项 值
Path /v1/tips/history/ledger/list
新增 tips_method
tips_method 栏
不传 / 0 全部(兼容旧版)
1 短剧
2 AI 机器人(可含历史等级机器人记录)

请求示例

短剧栏:

{ "offset": 0, "limit": 20, "tips_method": 1 }

AI 机器人栏:

{ "offset": 0, "limit": 20, "tips_method": 2 }

仍只返回「非生效中」的历史记录(与旧逻辑一致)。


9. 奖励明细 · 周日历每日数据

每日柱状 / 日历点

项 值
Path /v1/income/distributed/get
Body 见下
{
  "start_at": 1728604800,
  "end_at": 1729209599,
  "type": 1
}
字段 说明
start_at / end_at 本周起止 Unix 秒(按本地时区算)
type 1 = 按天(Granularity.Type_DAY)

响应:

{
  "items": [
    { "label": "10.13", "income": "12.5" },
    { "label": "10.14", "income": "3" }
  ]
}

重要:补 0

接口不会返回收益为 0 的日期。
前端按本周 7 天生成格子,对不上 label 的补 "0"。

本周分类汇总(可选)

仍用:POST /v1/income/details/get,传同一周的 start_at / end_at。


10. 用户自行解绑谷歌验证码(2FA)

项 值
Path /v1/user/otp/unbind
Body { "code": "123456" }
场景 业务 code 前端提示建议
成功 成功空 data 「已解绑」
未绑定 14036 「尚未绑定」
动态码错误 14016 「验证码错误」

绑定流程(不变)

  1. POST /v1/user/otp/generate → 拿二维码 / URI
  2. POST /v1/user/otp/bind → { "token", "code" }

管理端代解绑仍走管理接口,C 端不用管。


11. 帮助中心(纯前端)

本仓无新接口。静态页 / CMS / 多语言文案由前端自建。


联调 Checklist


相关文档