feat(coin): 金币数值体系二期——看广告按 eCPM 发奖 + ad_session_id 幂等 + 签到膨胀固定金币 (#28)

- rewards: 激励视频实发改按 calculate_ad_reward_coin(eCPM, 当日第N次) 公式;AD_REWARD_COIN/MAX_AD_REWARD_COIN 降为历史兼容口径;新增 SIGNIN_BOOST_COIN=2000 - 签到膨胀: Day1-13 看完激励视频额外发固定金币、Day14 不允许 (signin.py / signin-boost) - ad_session_id 幂等: ad_ecpm/ad_reward/ad_feed_reward 记录加 ad_session_id 列 + 唯一索引(新迁移 coin_reward_phase2 / ad_feed_reward_session) - ad.py + schemas + repositories: ecpm-report / feed-reward / reward-status / test-grant 改造;config_schema 增 signin_boost_coin;admin stats overview 补充 - 同步 docs/api + docs/database + docs/integrations/pangle 及 tests(test_ad_reward / test_welfare) Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> --------- Co-authored-by: OuYingJun1024 <1034284404@qq.com> Reviewed-on: #28 Co-authored-by: ouzhou <ouzhou@wonderable.ai> Co-committed-by: ouzhou <ouzhou@wonderable.ai>
2026-06-09 01:56:47 +08:00
parent 6432497af1
commit d7c29c0883
33 changed files with 650 additions and 154 deletions
@@ -8,7 +8,8 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `ad_type` | str | 是 | 广告类型:`reward_video`(激励视频) / `draw`(Draw 信息流) 等 |
-| `ecpm` | str | 是 | 穿山甲 `getShowEcpm().getEcpm()` 原始字符串,**单位待确认(分/元)**,原样上报 |
+| `ad_session_id` | str\|null | 否 | 客户端生成的广告会话 ID;需和穿山甲 `extra.ad_session_id` 一致,用于 S2S 缺 eCPM 时匹配 |
+| `ecpm` | str | 是 | 穿山甲 `getShowEcpm().getEcpm()` 原始字符串,后端按“元/千次展示”参与金币公式 |
 | `adn` | str\|null | 否 | 实际投放 ADN(`getSdkName`),如 `pangle` |
 | `slot_id` | str\|null | 否 | 实际展示代码位(底层 mediation rit,非客户端配置位) |

@@ -24,7 +25,8 @@
 ## 说明
 客户端在广告**展示后**(`onAdShow` 读 `getShowEcpm()`)调用,把本次展示的 eCPM 落库做**内部收益统计/对账**。

- **best-effort**:客户端 fire-and-forget,丢一两条不影响业务;穿山甲后台报表是结算权威兜底。
+- 普通激励视频发奖会先用 S2S 回调自带 `ecpm`;若缺失,再按 `ad_session_id` 读取本接口上报的 eCPM;两边都没有则不发并记录异常。
+- **best-effort**:客户端 fire-and-forget,但普通激励视频若 S2S 缺 eCPM,这条上报会成为发奖依据。
 - 落 `ad_ecpm_record` 表,`report_date` 用北京时间当天,供「按用户/按天聚合」对账。
 - **与发奖是两条独立流**:发奖走 [ad-pangle-callback](./ad-pangle-callback.md)(穿山甲 S2S,有 `trans_id`、无 ecpm),本接口客户端上报(有 ecpm、无 `trans_id`)。两者无公共键,**不逐条一一对应**,只做按用户/按天聚合口径。
 - eCPM 是**每千次展示预估**,单条展示预估收益 ≈ `ecpm / 1000`,且为客户端预估口径,非最终结算。
@@ -11,6 +11,7 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---:|---|
 | `client_event_id` | string | 是 | 客户端生成的幂等事件 id，8-64 字符 |
+| `ad_session_id` | string\|null | 否 | 客户端生成的一次信息流广告会话 id，用于对账/排查 |
 | `ecpm` | string | 是 | 本条信息流广告 eCPM，按“元/千次展示”处理 |
 | `duration_seconds` | int | 是 | 实际展示/播放秒数 |
 | `adn` | string\|null | 否 | 实际投放 ADN |
@@ -14,8 +14,8 @@ GroMore 以 GET 回调,关键参数:
 | `user_id` | string | 客户端 `setUserID` 传入的用户标识（须为数字 = 本系统 user.id） |
 | `trans_id` | string | 交易号（**幂等键** + **唯一参与签名的字段**） |
 | `reward_name` | string | 奖励名（广告位配置,入库备注） |
-| `reward_amount` | int | 奖励数量（广告位配置）→ **本次发放金币**。缺/坏/≤0 回退 `AD_REWARD_COIN`,超 `MAX_AD_REWARD_COIN` 夹紧 |
-| `extra` | string | 客户端透传的 customData（可空,入库备注） |
+| `ecpm` | string\|null | GroMore 回调携带的 eCPM。普通激励视频优先用它计算金币 |
+| `extra` / `gromoreExtra` / `gromore_extra` | string | 客户端透传 JSON。支持 `ad_session_id`、`reward_scene`;`reward_scene=signin_boost` 表示签到膨胀 |
 | `mediation_rit` | string | 代码位 ID（GroMore 带,目前仅入 raw 备查） |
 | `prime_rit` | string | 广告位 ID（同上） |
 | `adn_name` | string | 实际出广告的 ADN 名（同上,可用于收益分析） |
@@ -37,4 +37,9 @@ GroMore 以 GET 回调,关键参数:
 - `503` 回调未配置（`pangle_callback_configured=false`）

 ## 说明
-**发奖唯一可信入口**:验签 → 取 `user_id` → 按 `reward_amount` 解析金币 → 幂等发金币（按 `trans_id` 去重 + 每日上限）。客户端不参与发奖,被破解也刷不到钱。验签过但参数缺/坏或 user 不存在 → 不发（`is_verify=false` + `reason`）;granted / capped → `is_verify=true` + `reason=0`。
+**发奖唯一可信入口**:验签 → 取 `user_id`/`extra` → 按 `reward_scene` 分流 → 幂等处理（按 `trans_id` 去重）。客户端不直接发奖,被破解也刷不到钱。
+
+- `reward_scene=reward_video` 或缺省:普通激励视频。金币按 `eCPM / 1000 * eCPM因子 * 当日次数因子 * 10000` 计算;若回调没有 `ecpm`,会按 `extra.ad_session_id` 查客户端 `/ad/ecpm-report` 的上报值;两边都没有 eCPM 时不发币,记录 `status=ecpm_missing`。
+- `reward_scene=signin_boost`:签到膨胀。要求用户当天已签到且不是 Day14;看完视频固定发 `2000` 金币,写 `signin_boost_record` 与 `coin_transaction.biz_type=signin_boost`。
+- 未知 `reward_scene`:不发币,记录 `status=unknown_scene`,返回 `is_verify=false/reason=1`。
+- 验签过但参数缺/坏或 user 不存在 → 不发（`is_verify=false` + `reason`）;granted / capped / ecpm_missing / 业务不满足已记录 → `is_verify=true` + `reason=0`。
@@ -13,7 +13,7 @@
 | `used_today` | int | 今日已成功发奖次数 |
 | `daily_limit` | int | 每日发奖次数上限 |
 | `remaining` | int | 今日剩余可领次数 |
-| `coin_per_ad` | int | 看完一个激励视频发的金币 |
+| `coin_per_ad` | int | 历史兼容字段;正式发放按 eCPM 动态计算,当前返回 0 |
 | `round_count` | int | 本轮已看次数;当前 `round_size=1`,广告关闭后进入短冷却 |
 | `cooldown_until` | datetime\|null | 3 秒短冷却结束时间(UTC ISO);null 表示不在冷却 |
 | `watched_seconds_today` | int | 今日已上报的激励视频观看秒数;当前仅兼容/排查用 |
@@ -22,7 +22,7 @@

 ## 说明
 福利页「看视频赚金币」用:
- 展示「今日还能看 N 次」「看一次得 M 金币」(`remaining`/`coin_per_ad`)
+- 展示「今日还能看 N 次」(`remaining`);单次金币正式按 eCPM 动态计算,不再用 `coin_per_ad` 预估
 - 任务行 CTA 4 态推导:`adLoading` → Loading;`remaining==0` → Capped("明天再来");`cooldown_until` 在未来 → CoolingDown(显示 MM:SS 倒计时,不可点);否则 Normal("去赚取")
 - 弹窗 limit note:`used_today >= daily_limit` 显示「今日视频已到限额，明天再来」;`cooldown_until!=null` 显示「广告冷却中，3秒后再来」

@@ -5,7 +5,11 @@
 > ⚠️ **仅本地联调**,受 `AD_REWARD_TEST_GRANT_ENABLED` 开关控制,**生产必须关闭**（默认 False → 一律 404）。

 ## 入参
-无（用户由 token 确定）。
+请求体可省略；用户由 token 确定。
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `reward_scene` | string | 否 | `reward_video` | 模拟发奖场景。`reward_video`=普通激励视频；`signin_boost`=签到膨胀 |

 ## 出参
 响应 `200`:`TestGrantOut`
@@ -13,15 +17,17 @@
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `granted` | bool | 本次是否真发了金币（达每日上限则 false） |
-| `status` | string | `granted` / `capped`（达上限） |
+| `status` | string | `granted` / `capped`（达上限） / `not_signed` / `already_boosted` / `last_day` / `unknown_scene` |
 | `coin` | int | 本次发放金币（capped 时 0） |
 | `used_today` | int | 今日已成功发奖次数 |
 | `daily_limit` | int | 每日发奖次数上限 |
 | `remaining` | int | 今日剩余可领次数 |
-| `coin_per_ad` | int | 看完一个激励视频发的金币 |
+| `coin_per_ad` | int | 历史兼容字段;正式发放按 eCPM 动态计算,当前返回 0 |

 ## 错误码
 - `404` 开关未开（伪装不存在） / 用户不存在

 ## 说明
-没公网、穿山甲 S2S 回调打不到本地时,debug 客户端看完广告后调它,直接走与 [ad-pangle-callback](./ad-pangle-callback.md) 相同的发奖逻辑（每次新 `trans_id`,幂等 + 每日上限）。它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
+没公网、穿山甲 S2S 回调打不到本地时,debug 客户端看完广告后调它,直接走与 [ad-pangle-callback](./ad-pangle-callback.md) 相同的发奖逻辑（每次新 `trans_id`,幂等 + 每日上限/今日膨胀一次）。
+
+`reward_scene=signin_boost` 时复用签到膨胀业务规则:必须当天已签到、非第 14 天、当天未膨胀过,成功后写入 `signin_boost` 金币流水。它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
@@ -31,6 +31,14 @@
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `granted_total` | int | 累计发放金币(coin_transaction 中所有 `amount > 0` 之和;负数兑换/扣减不计) |
+| `reward_video_coin_total` | int | 普通激励视频累计发放金币(`biz_type=reward_video/ad_reward`) |
+| `reward_video_watch_count` | int | 普通激励视频有效发奖视频数(`ad_reward_record.reward_scene=reward_video,status=granted`) |
+| `feed_ad_coin_total` | int | 信息流广告累计发放金币(`biz_type=feed_ad_reward`) |
+| `feed_ad_watch_count` | int | 信息流广告有效完成视频数(`ad_feed_reward_record.status=granted`) |
+| `signin_coin_total` | int | 签到累计发放金币(`biz_type=signin`) |
+| `signin_count` | int | 签到次数(`signin_record`) |
+| `signin_boost_coin_total` | int | 签到膨胀累计发放金币(`biz_type=signin_boost`) |
+| `signin_boost_watch_count` | int | 签到膨胀有效视频数(`signin_boost_record`) |

 **DashboardCash**
 | 字段 | 类型 | 说明 |
@@ -64,6 +72,6 @@
 ## 说明
 - 全部为全局只读聚合(count / sum / DAU / 成功率),不改任何数据。
 - `new_today` / `dau` 按**北京时区**(UTC+8)切天,其余金额/计数无时区概念。
- 金额单位:`*_cents` 为分;金币(`granted_total`)为个数。
+- 金额单位:`*_cents` 为分;金币(`*_coin_total`/`granted_total`)为个数。
 - CPS 收入数据源未接入(referral-link 只换链接,转化/佣金未回收),`cps` 恒为 `{available:false, note:...}`,前端显示"待接入"。
 - 关联表:[user](../database/user.md) / [coin_transaction](../database/coin_transaction.md) / [withdraw_order](../database/withdraw_order.md) / [comparison_record](../database/comparison_record.md) / [feedback](../database/feedback.md)。
@@ -1,6 +1,6 @@
 # POST /api/v1/signin/boost — 签到后看广告膨胀金币

-用户当天已签到后，看完一条激励视频，补发一笔等额签到金币。
+用户 Day1-Day13 当天已签到后，看完一条激励视频，由穿山甲 S2S 回调固定补发 2000 金币。本接口只用于 S2S 发奖后的确认。

 ## 鉴权

@@ -10,7 +10,7 @@

 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---:|---|
-| `ad_ref_id` | string\|null | 否 | 广告会话/交易号。当前开发期可空，后续接 S2S 后可回填 |
+| `ad_ref_id` | string | 是 | 穿山甲 S2S 回调的 `trans_id`。回调需先以 `extra.reward_scene=signin_boost` 完成发奖 |

 ## 响应

@@ -23,10 +23,11 @@
 ## 错误

 - `401`: 未登录
- `409`: 当天未签到，或当天已经膨胀过
+- `409`: 缺少/无效广告回调记录，非本人广告，回调未发奖，当天未签到，Day14，或当天已经膨胀过

 ## 数据写入

- `signin_boost_record` 新增一行，用 `(user_id, signin_date)` 唯一约束防重复。
- `coin_account` 增加余额。
- `coin_transaction` 写入 `biz_type=signin_boost`。
+- 本接口不直接发奖;实际写入发生在 `/ad/pangle-callback` 的 `reward_scene=signin_boost` 分支。
+- 回调写 `signin_boost_record` 新增一行，用 `(user_id, signin_date)` 唯一约束防重复。
+- 回调使 `coin_account` 增加固定 `2000` 金币。
+- 回调写入 `coin_transaction.biz_type=signin_boost`。