墨西哥 1.0 C 端 — 前端对接说明
面向 C 端 App 前端。分支:test-old。
管理端相关字段见 admin_new_features_frontend.md。
通用约定
- 接口均为
POST,JSON body - 时间字段:Unix 秒(
int64) - 评分 / 金额:十进制 string(空字符串
""= 未填) - 失败看响应业务
code(不是 HTTP status alone)
需求一览(前端要做什么)
| # | 需求 | 前端动作 | 后端是否改 |
|---|---|---|---|
| 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 位小数) |
出现位置:
- 首页:
POST /v1/playlet/group/home/list - 详情:
POST /v1/playlet/details/page/list→playlet.score
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 |
只出现在轮播,不要进板块列表 |
前端渲染规则
- 顶栏轮播:
category == 1(CAROUSEL),或carousel_only == true - 下方板块:
category == 2(HOME_SECTION),且carousel_only != true - 标签类按产品需要决定是否展示
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
前端必须做
- 隐藏 AI 聊天 全部入口
- 隐藏 等级机器人 入口(列表 / 购买)
- 保留其它智能支持机器人、礼券、弹幕
直调接口时(防漏)
| 接口 | 行为 |
|---|---|
| 聊天 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 |
「验证码错误」 |
绑定流程(不变)
POST /v1/user/otp/generate→ 拿二维码 / URIPOST /v1/user/otp/bind→{ "token", "code" }
管理端代解绑仍走管理接口,C 端不用管。
11. 帮助中心(纯前端)
本仓无新接口。静态页 / CMS / 多语言文案由前端自建。
联调 Checklist
- [ ] 首页卡片:
score、views_trend、轮播 / 板块拆分正确 - [ ] 详情页:
score、views_trend、剧集、更多推荐 - [ ] 支持历史:短剧栏
tips_method=1,机器人栏=2 - [ ] 周日历:7 天齐全(缺日补 0)
- [ ] OTP:解绑成功 / 错码 / 未绑定
- [ ] AI 聊天、等级机器人入口已隐藏;其它机器人可用
- [ ] 搜索历史仅本地;帮助中心可打开
相关文档
- 管理端: admin_new_features_frontend.md
- 支持等级枚举: tips_level_frontend.md