# 任务体验币合计 / 机器人当日可领 — 前端对接

面向客户端。本次未提交改动里，**只有下面两类接口行为需要对接**；主从库、支付结算、Cron 锁等为后端内部，前端无接口变更。

业务日一律按 **东七区（UTC+7）**，与任务/机器人日切一致。不要用设备本地时区或 UTC 判断「当天」「中午 12 点」。

---

## 1. 新接口：当日任务体验硬币合计

用户当天通过 **手动领取任务奖励** 拿到的体验硬币合计。

| 项 | 值 |
|---|---|
| 方法 / 路径 | `POST /v1/task/consume_income/today/get` |
| RPC | `TaskService.GetTodayTaskConsumeIncome` |
| 鉴权 | 与其它 `/v1/task/*` 相同，需登录 |
| 请求体 | 空对象 `{}`（`google.protobuf.Empty`） |

### 响应

```json
{
  "amount": "12.5"
}
```

| 字段 | 类型 | 说明 |
|---|---|---|
| `amount` | string | 当日已领取体验硬币合计，十进制字符串。无记录为 `"0"` |

### 统计口径

只计入同时满足以下条件的积分流水：

- 流水类型 = `TYPE_TASK_INCOME`（任务领取）
- 硬币类型 = `TYPE_CONSUME`（体验硬币）
- `point > 0`
- `created_at` 落在东七区当天 `[00:00, 次日 00:00)`

**不会计入：**

- 通用硬币任务奖励（`TYPE_COMMON`）
- 新人任务完成时自动发放、流水类型不是 `TYPE_TASK_INCOME` 的记录（例如走 `TYPE_PACKAGE` 的自动发奖）

与领取接口对应关系：用户点「领奖」走 `POST /v1/task/income/get`，且该任务 `income_point_type = TYPE_CONSUME` 时，才会进入本合计。领奖成功后本接口金额应立即增加（若读从库有短暂延迟，可领奖成功后本地累加或稍后刷新）。

### 错误

| 场景 | 处理 |
|---|---|
| 未登录 | 与现有任务接口相同 |
| 查询失败 | 业务码 `CODE_DATABASE`，可提示稍后重试 |

### 建议用法

任务中心页、体验币说明弹层：展示「今日已领体验硬币 `amount`」。`amount` 用字符串小数展示，不要先转 `number` 再算（避免精度问题）。

---

## 2. 行为变更：机器人收益查询 / 领取

路径和响应结构 **不变**，只改「什么时候能看到、能领到」的规则。

| 接口 | 路径 | 响应 |
|---|---|---|
| 查询待领 | `POST /v1/robot/tips/income/get` | `{ "income": "1.23" }` |
| 领取 | `POST /v1/robot/tips/income/receive` | 空 |

鉴权与现网一致，需登录。请求体均为 `{}`。

### 新规则（按台机器人 / 下级返佣分别判断）

业务日、中午 12 点均按 **东七区**。

| 收益属于 | 东七区中午 12 点前 | 东七区中午 12 点及以后 |
|---|---|---|
| **当天新支持**（收益开始日 = 今天） | 可查询、可领取 | 可查询、可领取 |
| **次日及以后**（昨天或更早支持） | 不进入待领金额 | 可查询、可领取 |

以前：中午 12 点前整笔待领为 `0`，领取直接失败。  
现在：12 点前仍可能有待领金额（仅含「今天刚支持」的首日收益 + 对应下级返佣）。

冻结收益类机器人（过期返还 / AI 投资等）仍不走这两个手动接口，由后端自动结算，前端逻辑与现网一致。

### 查询 `income`

- 字符串，无待领为 `"0"`。
- 含本人直接收益 + 下级返佣（规则与现网相同，只是每条记录多了一层「现在能不能领」）。
- 当天已领过的台账不会再计入。
- `2026-04-28 00:00`（东七区）之前固定返回 `"0"`（现网已有门槛，未改日期）。

### 领取

| 结果 | 含义 | 前端建议 |
|---|---|---|
| 成功（空 body） | 已入账到可用硬币 | 刷新余额、再调一次查询，`income` 应为 `"0"` 或仅剩尚未到点的部分（12 点前领完首日后，次日收益仍要等 12 点） |
| `CODE_ARGUMENT` | 当前没有可领金额 | 12 点前：可能只有旧机器人、或首日已领完。文案不要再写「必须中午 12 点后才能领」；可区分「暂无可领」与「部分收益需 12 点后」 |
| 其它错误 | 与现网相同 | 按现有错误码提示 |

领取成功后，12 点前再查，`income` 可能仍大于 `0`（还有非首日收益未到点）。按钮文案建议：

- `income === "0"` 且东七区未到 12 点：可显示「部分收益 12:00 后可领」或禁用领取
- `income > 0`：可领取（即使未到 12 点）

### 时区注意

用东七区算「今天」和「是否已过 12:00」，不要用手机系统时区。例如用户在 UTC 时，本地 5:00 已是东七区 12:00，此时非首日收益应变为可领。

---

## 3. 联调清单

- [ ] 登录后调用新接口，无任务领取时 `amount` 为 `"0"`
- [ ] 领取一笔体验硬币任务后，`amount` 增加且等于该笔奖励（或当日多笔之和）
- [ ] 领取通用硬币任务后，`amount` **不变**
- [ ] 当天新买一台可手动领取的机器人，12 点前：查询 `income > 0`，领取成功
- [ ] 仅有昨天及更早的机器人，12 点前：查询 `income` 为 `"0"`，领取返回 `CODE_ARGUMENT`
- [ ] 同上用户，东七区 12 点后：查询有金额，领取成功
- [ ] 同一台机器人当天不可重复领取
- [ ] 12 点前先领完首日，再查：若还有旧机器人，`income` 仍为 `"0"` 直到 12 点

---

## 4. 推荐页视频：改为剧第一集

路径、响应结构与旧「推荐素材」接口相同，**不再使用后台上传的素材**。后台也不需要再维护推荐素材。

| 接口 | 路径 |
|---|---|
| 列表 | `POST /v1/playlet/material/list` |
| 上报已看 | `POST /v1/material/watch/history/create` |

每条 `materials[]`：

| 字段 | 现在的含义 |
|---|---|
| `id` | **第一集剧集 ID**（上报已看请传这个） |
| `playlet_id` | 剧 ID，点进播放页用这个 |
| `titles` / `playlet_titles` | 剧名（多语言） |
| `descriptions` | 剧简介（多语言） |
| `video_id` / `video_info` | 第一集视频；`play_url` 仍用返回的 `iv` 按现网规则解密 |
| `created_at` | 第一集创建时间 unix |

筛选、随机排序与旧推荐流一致。没有可播放第一集的剧不会出现。

**已看上报必须调** `POST /v1/material/watch/history/create`，传入本条 `id`。列表接口不再在下发时自动记已看。全部看完后再请求会清空已看并重新循环；仅分页 offset 超出时不会重置。

---

## 5. 本次无需对接

- 列表类接口切从库：路径、字段不变，数据可能有秒级延迟
- Monetapay / Apple / 订单结算：无新前端字段
- 管理端推荐素材上传：已下线，不要再调
- Cron：无客户端接口