feat(ad): 信息流广告按条 segments 精确发奖 + 只读 preview 接口
- compute_feed_reward/preview_feed_reward: 逐条 (eCPM,秒) 跨条进位、每满 10s 一份、 每份用所在段 eCPM × LT，封顶 12 份/场；发奖与预览同一口径 - grant_feed_reward 改收 segments（旧 ecpm/duration 单段自动回退，兼容旧客户端） - 新增 POST /api/v1/ad/feed-reward/preview（只读不入账，给比价金币小球实时显示真实即将到账额） - schemas 加 FeedSegmentIn/FeedPreviewIn/FeedPreviewOut；docs/api 补 preview 文档 + 更新 feed-reward - tests: 按条结算/12份封顶/aborted/preview==grant 等 6 个用例 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
OuYingJun1024
@@ -63,6 +63,7 @@
|
||||
| 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad-test-grant.md) |
|
||||
| 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad-ecpm-report.md) |
|
||||
| 35a | `POST /api/v1/ad/feed-reward` | Bearer | [详情](./ad-feed-reward.md) |
|
||||
| 35a' | `POST /api/v1/ad/feed-reward/preview` | Bearer | [详情](./ad-feed-reward-preview.md)(播放中预演将发放金币,只读不入账,金币小球用) |
|
||||
| 35b | `POST /api/v1/ad/reward-noshow` | Bearer | [详情](./ad-reward-noshow.md)(激励视频提前关闭/未发奖留痕,只记原因不发币) |
|
||||
| **用户资料**（前缀 `/api/v1/user`） |||
|
||||
| 35 | `PATCH /api/v1/user/profile` | Bearer | [详情](./user-profile.md) |
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# POST /api/v1/ad/feed-reward/preview — 信息流播放中预演将发放的金币（只读）
|
||||
|
||||
比价 / 领券信息流广告**播放过程中**，查询「若此刻结束、整场将发放多少金币」。给金币小球实时显示**真实即将到账金额**用：与 [feed-reward](./ad-feed-reward.md) **同一计价口径**（同份数封顶 / 同 LT / 同 eCPM 钳），但**只读、不入账、不写库**。
|
||||
|
||||
客户端每满 10 秒观看（或换条 eCPM 变化）拉一次；两次之间用 `next_unit_coin × 本份进度` 在本地做平滑插值显示。
|
||||
|
||||
## 鉴权
|
||||
|
||||
需要 Bearer token。
|
||||
|
||||
## 请求体
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---:|---|
|
||||
| `segments` | array | 是 | 截至此刻的**逐条广告段**（时序，至少 1 项；含在播那条的部分秒数），每项 `{ecpm: string, seconds: int}` |
|
||||
|
||||
## 响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `coin` | int | 此刻结束将发放的累计金币（已满 10 秒的各份之和） |
|
||||
| `unit_count` | int | 已累计满的份数（封顶 12） |
|
||||
| `next_unit_coin` | int | 下一份（第 `unit_count+1` 份）的金币值，按当前在播段 eCPM 算；封顶后为 0。供小球在本份未满区间内平滑插值 |
|
||||
| `session_full` | bool | 是否已达单场份数上限（12）→ 小球应停涨 |
|
||||
| `would_status` | string | 若此刻结束的结算预判：`granted` / `too_short`(凑不满一份) / `daily_capped`(已达每日条数上限，整场将发 0) |
|
||||
|
||||
## 与 feed-reward 的关系
|
||||
|
||||
- 同样按 `segments` 跨条进位每满 10 秒一份、每份用所在段 eCPM 计价（详见 [feed-reward 计算口径](./ad-feed-reward.md#计算口径)）。
|
||||
- preview 的 `coin` 等于「用相同 segments 调 feed-reward 实发的 `coin`」——小球显示值即整场结束实发额（除非中途 `would_status` 提示 `daily_capped`，那种情况整场实发 0）。
|
||||
- preview **不消耗每日上限、不写任何表**，可高频调用（限流 600/分）。
|
||||
|
||||
## 限流
|
||||
|
||||
600 次 / 分钟（`ad-feed-preview`）。
|
||||
+19
-10
@@ -1,6 +1,8 @@
|
||||
# POST /api/v1/ad/feed-reward — 信息流广告完成后结算金币
|
||||
|
||||
点位 2：比价等待 / 领券信息流广告（轮播多条）。**整场比价全程不关广告才发**，金额按整场**总观看时长**折份（每 10 秒 1 份），结束时一次性入账。用户中途 ✕ 关闭则整场不发。
|
||||
点位 2：比价等待 / 领券信息流广告（轮播多条）。**整场比价全程不关广告才发**，金额按整场折份（每 10 秒 1 份），结束时一次性入账。用户中途 ✕ 关闭则整场不发。
|
||||
|
||||
播放过程中查询「此刻将发放多少金币」（金币小球实时显示用）见 [feed-reward/preview](./ad-feed-reward-preview.md)，与本接口同一计价口径但只读不入账。
|
||||
|
||||
## 鉴权
|
||||
|
||||
@@ -8,37 +10,44 @@
|
||||
|
||||
## 请求体
|
||||
|
||||
计价优先用 `segments` 逐条精确结算；未传 `segments` 时回退用 `ecpm` + `duration_seconds` 当**单段**（旧客户端兼容）。两者都不传 → 422。
|
||||
|
||||
| 字段 | 类型 | 必填 | 说明 |
|
||||
|---|---|---:|---|
|
||||
| `client_event_id` | string | 是 | 客户端生成的幂等事件 id，8-64 字符 |
|
||||
| `ad_session_id` | string\|null | 否 | 客户端生成的一次信息流广告会话 id，用于对账/排查 |
|
||||
| `ecpm` | string | 是 | 本场信息流 eCPM 代表值(穿山甲 getEcpm 原值)，按“分/千次展示”处理(非元) |
|
||||
| `duration_seconds` | int | 是 | **整场累计观看秒数**(轮播各条相加) |
|
||||
| `segments` | array\|null | 否* | **逐条广告段**（时序），每项 `{ecpm: string, seconds: int}`。新客户端传它做按条精确结算 |
|
||||
| `ecpm` | string\|null | 否* | **[回退]** 本场代表 eCPM(穿山甲 getEcpm 原值，分/千次展示，非元)；传了 `segments` 时仅作落库代表值 |
|
||||
| `duration_seconds` | int | 否 | **[回退]** 整场累计观看秒数；传了 `segments` 时忽略。默认 0 |
|
||||
| `adn` | string\|null | 否 | 实际投放 ADN(聚合后实际填充的子渠道) |
|
||||
| `slot_id` | string\|null | 否 | 实际展示代码位(底层 mediation rit) |
|
||||
| `app_env` | string\|null | 否 | **我们的**应用环境:`prod`(傻瓜比价正式) / `test`(测试应用) |
|
||||
| `our_code_id` | string\|null | 否 | **我们后台配置的**代码位 ID(104xxx,非底层 rit);供广告收益报表按代码位聚合金币 |
|
||||
| `aborted` | bool | 否 | 用户中途 ✕ 关闭广告(未走完比价):整场不发，仅记 `closed_early`。默认 `false` |
|
||||
|
||||
\* `segments` 与 `ecpm` 至少传其一。
|
||||
|
||||
## 响应
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `granted` | bool | 本次是否入账；未发(任一非 granted 状态)时为 `false` |
|
||||
| `status` | string | `granted`(已发) / `capped`(当日次数超限) / `too_short`(整场总时长<10s 凑不满一份) / `closed_early`(用户中途关闭) |
|
||||
| `status` | string | `granted`(已发) / `capped`(当日次数超限) / `too_short`(整场<10s 凑不满一份) / `closed_early`(用户中途关闭) |
|
||||
| `coin` | int | 本次发放金币；非 granted 为 0 |
|
||||
| `unit_count` | int | 按 10 秒折算出的奖励份数 |
|
||||
| `unit_count` | int | 折算出的奖励份数（封顶 12） |
|
||||
| `daily_limit` | int | 每日信息流展示次数上限，默认 500 |
|
||||
|
||||
## 计算口径
|
||||
|
||||
- 奖励份数：`整场总时长 // 10`。
|
||||
- 单份奖励：`eCPM / 1000 × 因子1(eCPM 档) × 因子2(当天累计份序号) × 10000`，四舍五入为整数金币。
|
||||
- eCPM 档：`0-100=0.1`，`101-200=0.3`，`201-400=0.4`，`>400=0.6`。
|
||||
- LT 档：第 1 份 `2.0`，第 2 份 `1.5`，第 3 份 `1.3`，第 4-10 份 `1.1`，第 11 份及以后 `1.0`。
|
||||
- **奖励份数（跨条进位）**：按 `segments` 时序遍历，维护一个连续秒数计数器，每满 10 秒结算一份；换条时不足一份的零头进位到下一条。份数封顶 **12 份/场**（防刷硬闸，替代旧的「单事件时长钳 120s」）。
|
||||
- **每份归属的 eCPM**：该份「满 10 秒那一刻正在播的那条广告」的 eCPM。
|
||||
- **单份奖励**：`eCPM / 1000 × 因子1(eCPM 档) × 因子2(账号累计份序号) × 10000`，四舍五入为整数金币。
|
||||
- eCPM 档：`0-100=0.1`，`101-200=0.3`，`201-400=0.4`，`>400=0.6`（eCPM 钳顶 ¥500 CPM）。
|
||||
- LT 档（按**账号累计已发份数**，不按天重置）：第 1 份 `2.0`，第 2 份 `1.5`，第 3 份 `1.3`，第 4-10 份 `1.1`，第 11 份及以后 `1.0`。
|
||||
- 旧客户端单段口径 `[(ecpm, duration_seconds)]` 是上述的特例，份数 = `min(duration//10, 12)`，结果与改造前一致。
|
||||
|
||||
## 数据写入
|
||||
|
||||
- `ad_feed_reward_record` 新增一行。
|
||||
- `ad_feed_reward_record` 新增一行（`ecpm_raw` 存代表 eCPM，通常为末段）。
|
||||
- 入账时 `coin_account` 增加余额。
|
||||
- 入账时 `coin_transaction` 写入 `biz_type=feed_ad_reward`。
|
||||
|
||||
Reference in New Issue
Block a user