@ (#111)

docs/api目录文档分类和补全 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #111
2026-07-03 15:00:37 +08:00
parent ee132aa93b
commit a563c1ca4b
102 changed files with 2418 additions and 217 deletions
@@ -0,0 +1,40 @@
+# POST /api/v1/ad/ecpm-report — 上报本次广告展示的 eCPM（内部收益统计）
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+## 入参
+请求体:`EcpmReportIn`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `ad_type` | str | 是 | 广告类型:`reward_video`(激励视频) / `feed`(信息流) / `draw`(历史 Draw 信息流) 等 |
+| `ad_session_id` | str\|null | 否 | 客户端生成的广告会话 ID;激励视频与穿山甲 `extra.ad_session_id` 一致,用于 S2S 缺 eCPM 时匹配。**信息流轮播每条展示用各自独立 id**(不复用比价会话 id,否则 `uq_ad_ecpm_record_session` 去重只留一条) |
+| `ecpm` | str | 是 | 穿山甲 `getShowEcpm().getEcpm()` 原始字符串,单位是**分/千次展示**(非元),后端 ÷100 转元参与金币公式 |
+| `adn` | str\|null | 否 | 实际投放 ADN(`getSdkName`),如 `pangle`(聚合后实际填充的子渠道) |
+| `slot_id` | str\|null | 否 | 实际展示代码位(底层 mediation rit,非客户端配置位) |
+| `app_env` | str\|null | 否 | **我们的**穿山甲应用环境:`prod`(傻瓜比价正式) / `test`(测试应用) |
+| `our_code_id` | str\|null | 否 | **我们后台配置的**代码位 ID(`AdConfig` 的 104xxx,**非** `slot_id` 的底层 rit) |
+
+`user_id` 不在 body 里——由 JWT 取(Bearer),防伪造。
+
+## 出参
+响应 `200`:`EcpmReportOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ok` | bool | 落库即 `true` |
+
+## 说明
+客户端在广告**展示后**(`onAdShow` 读 `getShowEcpm()`)调用,把本次展示的 eCPM 落库做**内部收益统计/对账**。激励视频每次展示上报一条;**信息流轮播每条展示各上报一条**(每条独立 `ad_session_id`),作为「广告收益报表」展示条数/收益的数据源(见 [admin-ad-revenue-report](./admin-ad-revenue-report.md))。`app_env` + `our_code_id` 供报表按「我们的应用 / 我们配置的代码位」聚合,与 `adn`/`slot_id`(底层填充渠道/rit)是两组不同口径。
+
+- 普通激励视频发奖会先用 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`,且为客户端预估口径,非最终结算。
+- ⚠️ eCPM **单位(分/元)截至 2026-05-31 未最终确认**,故 `ecpm_raw` 原样存字符串;确认后再加一列解析好的数值。
+- 限流:同 IP 120 次/分钟。
+
+## 相关
+- [ad-pangle-callback](./ad-pangle-callback.md) — 穿山甲 S2S 发奖回调
+- [ad-reward-status](./ad-reward-status.md) — 今日看广告发奖进度
@@ -0,0 +1,44 @@
+# POST /api/v1/ad/feed-reward — 信息流广告完成后结算金币
+
+点位 2：比价等待 / 领券信息流广告（轮播多条）。**整场比价全程不关广告才发**，金额按整场**总观看时长**折份（每 10 秒 1 份），结束时一次性入账。用户中途 ✕ 关闭则整场不发。
+
+## 鉴权
+
+需要 Bearer token。
+
+## 请求体
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `client_event_id` | string | 是 | 客户端生成的幂等事件 id，8-64 字符 |
+| `ad_session_id` | string\|null | 否 | 客户端生成的一次信息流广告会话 id，用于对账/排查 |
+| `ecpm` | string | 是 | 本场信息流 eCPM 代表值(穿山甲 getEcpm 原值)，按“分/千次展示”处理(非元) |
+| `duration_seconds` | int | 是 | **整场累计观看秒数**(轮播各条相加) |
+| `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` |
+
+## 响应
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `granted` | bool | 本次是否入账；未发(任一非 granted 状态)时为 `false` |
+| `status` | string | `granted`(已发) / `capped`(当日次数超限) / `too_short`(整场总时长<10s 凑不满一份) / `closed_early`(用户中途关闭) |
+| `coin` | int | 本次发放金币；非 granted 为 0 |
+| `unit_count` | int | 按 10 秒折算出的奖励份数 |
+| `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`。
+
+## 数据写入
+
+- `ad_feed_reward_record` 新增一行。
+- 入账时 `coin_account` 增加余额。
+- 入账时 `coin_transaction` 写入 `biz_type=feed_ad_reward`。
@@ -0,0 +1,45 @@
+# GET /api/v1/ad/pangle-callback — 穿山甲 GroMore 激励视频发奖回调(S2S)
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:**无 JWT,靠验签**（穿山甲 GroMore 服务器调用） | 限流:同 IP ≤300 次/分 | [← 返回 API 索引](../README.md)
+>
+> ⚠️ 我们客户端用 `useMediation(true)`(GroMore 融合),回调走 **GroMore 广告位层级**(规范见 supportcenter/26240),**不是**联盟代码位层级(5416)。两者密钥、响应格式都不同,别混。后台配置入口:**GroMore 聚合管理 → 搜广告位ID → 编辑 → 勾选「服务端激励回调」**(广告位层级配了就别再在代码位层级重复配,会冲突)。
+>
+> 集成实现:见 [integrations/pangle](../integrations/pangle.md)（验签算法、m-key 来源、设计动机）。
+
+## 入参（query，由 GroMore 拼装）
+GroMore 以 GET 回调,关键参数:
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `user_id` | string | 客户端 `setUserID` 传入的用户标识（须为数字 = 本系统 user.id） |
+| `trans_id` | string | 交易号（**幂等键** + **唯一参与签名的字段**） |
+| `reward_name` | string | 奖励名（广告位配置,入库备注） |
+| `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 名（同上,可用于收益分析） |
+| `ecpm` | string | 本次广告 eCPM（同上,可用于收益分析） |
+| `sign` | string | 签名,见下 |
+
+**验签**:`sign = SHA256("{m-key}:{trans_id}")` 十六进制（只签 `trans_id`，其余参数不参与）。多激励位共用同一回调 URL → 服务端把各位的 m-key 都配上,`verify_callback_sign_any` 逐个试、任一过即接受。算法细节、m-key 配置项(`PANGLE_REWARD_SECRET_TEST/_TEST_DEDICATED/_PROD`)、为什么这样设计 → 见集成文档 [integrations/pangle](../integrations/pangle.md)。
+
+## 出参
+响应 `200`,**响应体必须是 `{"is_verify": bool, "reason": int}`**（GroMore 规范）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `is_verify` | bool | `true`=校验通过、发放奖励（发奖成功 或 当日达上限,均算已处理、不重试） |
+| `reason` | int | `is_verify=false` 时的错误码,透传客户端 SDK:`1`=参数缺/坏,`2`=user 不存在;成功为 `0` |
+
+## 错误码
+- `403` 验签失败（`bad sign`,留给真请求重试）
+- `503` 回调未配置（`pangle_callback_configured=false`）
+
+## 说明
+**发奖唯一可信入口**:验签 → 取 `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`。
@@ -0,0 +1,41 @@
+# POST /api/v1/ad/reward-noshow — 激励视频提前关闭/未发奖留痕
+
+激励视频**展示了但用户提前关闭/跳过、未触发 S2S 发奖**时，客户端 best-effort 上报一条留痕记录，
+让运营后台「广告数据」能呈现「有展示、没发金币」的原因。**不发金币**。
+
+## 鉴权
+
+需要 Bearer token。`user_id` 由 JWT 取，不在 body。
+
+## 请求体
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---:|---|
+| `ad_session_id` | string | 是 | 本次展示会话 id(与 eCPM 上报、S2S `extra.ad_session_id` 一致)，8-64 字符 |
+| `watched_seconds` | int | 否 | 关闭前已观看秒数(仅留痕参考，**不入库**)。默认 0 |
+| `ecpm` | string\|null | 否 | 本次展示 eCPM(穿山甲 getEcpm 原值，分/千次展示) |
+| `adn` | string\|null | 否 | 实际投放 ADN(聚合后实际填充子渠道) |
+| `slot_id` | string\|null | 否 | 实际展示代码位(底层 mediation rit) |
+| `app_env` | string\|null | 否 | **我们的**应用环境:`prod`(傻瓜比价正式) / `test`(测试应用) |
+| `our_code_id` | string\|null | 否 | **我们后台配置的**代码位 ID(104xxx，非底层 rit) |
+
+## 响应
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ok` | bool | 是否处理成功(落库或幂等命中) |
+| `status` | string | `closed_early`(已留痕) / `granted`(该次其实已发奖，跳过未写) |
+
+## 说明
+
+- 在 `onAdClose` 时若本次**未触发发奖**(无 `onRewardVerify`/`onRewardArrived`)调用。
+- **幂等**:写入 `ad_reward_record`，`trans_id = noreward:{ad_session_id}`(每次展示唯一)，重试不重复。
+- **防与正常发奖重复**:若同一 `ad_session_id` 已有 `status='granted'` 记录(S2S 已发，说明用户其实看完了)，
+  则跳过不写，返回 `status='granted'`。
+- best-effort:客户端 fire-and-forget，失败只 log，不影响主流程。
+- 信息流的「用户中途关闭」走 [ad-feed-reward](./ad-feed-reward.md) 的 `aborted=true`（记 `closed_early`），不走本接口。
+
+## 数据写入
+
+- `ad_reward_record` 新增一行(`coin=0`、`status='closed_early'`、`reward_scene='reward_video'`)。
+- **不**写 `coin_account` / `coin_transaction`(不发币)。
@@ -0,0 +1,31 @@
+# GET /api/v1/ad/reward-status — 今日看广告发奖进度
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
+
+## 入参
+无（用户由 token 确定）。
+
+## 出参
+响应 `200`:`AdRewardStatusOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `used_today` | int | 今日已成功发奖次数 |
+| `daily_limit` | int | 每日发奖次数上限 |
+| `remaining` | 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 | 今日已上报的激励视频观看秒数;当前仅兼容/排查用 |
+| `watch_seconds_limit` | int | 每日观看总时长上限;当前默认 0 表示未启用时长闸 |
+| `watch_seconds_remaining` | int | 今日剩余可观看秒数;`watch_seconds_limit=0` 时客户端不据此拦截 |
+
+## 说明
+福利页「看视频赚金币」用:
+- 展示「今日还能看 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秒后再来」
+
+冷却派生算法:取当日 `status='granted'` 记录里**最近一个已完成轮**(当前每 N=1 条算一轮)末尾那次的 `created_at`,加 3 秒。若仍 > now → 返回;否则返回 null。**冷却是 UX 约束**,后端发奖(`/api/v1/ad/pangle-callback`)只看 daily_limit,冷却期间穿山甲回调照常发奖。
+
+真正发奖走 [ad-pangle-callback](./ad-pangle-callback.md)(穿山甲 S2S)。
@@ -0,0 +1,36 @@
+# POST /api/v1/ad/test-grant — [仅本地联调]模拟穿山甲回调发奖
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤60 次/分 | [← 返回 API 索引](../README.md)
+>
+> ⚠️ **仅本地联调**,受 `AD_REWARD_TEST_GRANT_ENABLED` 开关控制,**生产必须关闭**（默认 False → 一律 404）。
+
+## 入参
+请求体可省略；用户由 token 确定。
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `reward_scene` | string | 否 | `reward_video` | 模拟发奖场景。`reward_video`=普通激励视频；`signin_boost`=签到膨胀 |
+| `ad_session_id` | string(8~64) \| null | 否 | null | 本次广告会话 id(与 [ecpm-report](./ad-ecpm-report.md) 同值)。**仅 `reward_video` 场景生效**:据此查回客户端已上报的真实 eCPM,走与正式发奖相同的公式发奖;查不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍出非零金币 |
+
+## 出参
+响应 `200`:`TestGrantOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `granted` | bool | 本次是否真发了金币（达每日上限则 false） |
+| `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 | 历史兼容字段;正式发放按 eCPM 动态计算,当前返回 0 |
+
+## 错误码
+- `404` 开关未开（伪装不存在） / 用户不存在
+
+## 说明
+没公网、穿山甲 S2S 回调打不到本地时,debug 客户端看完广告后调它,直接走与 [ad-pangle-callback](./ad-pangle-callback.md) 相同的发奖逻辑（每次新 `trans_id`,幂等 + 每日上限/今日膨胀一次）。
+
+`reward_scene=reward_video` 时按上面 `ad_session_id` 查回的真实 eCPM 走金币公式发奖(取不到兜底 200)——便于本地用 [admin 金币审计](./admin-ad-coin-audit.md) 核对「看广告→金币」是否按公式计算。
+
+`reward_scene=signin_boost` 时复用签到膨胀业务规则:必须当天已签到、非第 14 天、当天未膨胀过,成功后写入 `signin_boost` 金币流水。它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
@@ -0,0 +1,46 @@
+# POST /api/v1/ad/watch-report — 上报激励视频观看时长
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤120 次/分 | [← 返回 API 索引](../README.md)
+
+客户端在激励视频关闭（onAdClose）后上报本次实际观看秒数，服务端累计到当日总时长。当前产品只保留每日 500 次上限，DAILY_AD_WATCH_SECONDS_LIMIT=0 表示时长闸不启用；该接口仍保留用于旧客户端兼容和排查观看时长。
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `seconds` | int | ✅ (≥0) | 本次观看秒数，服务端夹 [0, MAX_SINGLE_WATCH_SECONDS] |
+
+Mock 入参:
+```json
+{
+  "seconds": 28
+}
+```
+
+## 出参
+
+响应 `200`:`WatchReportOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `watched_seconds_today` | int | 今日累计观看秒数 |
+| `watch_seconds_limit` | int | 每日上限（秒）；0 表示当前未启用时长闸 |
+| `watch_seconds_remaining` | int | 今日剩余可观看秒数 |
+
+Mock 出参:
+```json
+{
+  "watched_seconds_today": 128,
+  "watch_seconds_limit": 0,
+  "watch_seconds_remaining": 0
+}
+```
+
+## 错误码
+- `401` 未鉴权 / token 失效
+- `422` `seconds` 缺或为负
+
+## 说明
+- 鉴权靠 Bearer，`user_id` 取自 JWT（不信 body）
+- 后端只做累计 + 上限裁切，不据此发奖（发奖靠 S2S 回调）
+- `watch_seconds_limit=0` 时客户端不据此拦截，按每日 500 次上限走