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

面向 **C 端 App 前端**。分支：`test-old`。  
管理端相关字段见 [admin_new_features_frontend.md](./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` | **只**出现在轮播，不要进板块列表 |

### 前端渲染规则

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 }` |

### 响应要点

```json
{
  "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 聊天 + 等级机器人

墨西哥站服务端会开：

```yaml
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 机器人**（可含历史等级机器人记录） |

### 请求示例

短剧栏：

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

AI 机器人栏：

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

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

---

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

### 每日柱状 / 日历点

| 项 | 值 |
|----|-----|
| Path | `/v1/income/distributed/get` |
| Body | 见下 |

```json
{
  "start_at": 1728604800,
  "end_at": 1729209599,
  "type": 1
}
```

| 字段 | 说明 |
|------|------|
| `start_at` / `end_at` | 本周起止 Unix 秒（按本地时区算） |
| `type` | `1` = 按天（`Granularity.Type_DAY`） |

响应：

```json
{
  "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

- [ ] 首页卡片：`score`、`views_trend`、轮播 / 板块拆分正确
- [ ] 详情页：`score`、`views_trend`、剧集、更多推荐
- [ ] 支持历史：短剧栏 `tips_method=1`，机器人栏 `=2`
- [ ] 周日历：7 天齐全（缺日补 0）
- [ ] OTP：解绑成功 / 错码 / 未绑定
- [ ] AI 聊天、等级机器人入口已隐藏；其它机器人可用
- [ ] 搜索历史仅本地；帮助中心可打开

---

## 相关文档

- 管理端： [admin_new_features_frontend.md](./admin_new_features_frontend.md)
- 支持等级枚举： [tips_level_frontend.md](./tips_level_frontend.md)
