shaguabijia-app-server/docs/database/ad_reward_record.md

ad_reward_record — 看激励视频发奖记录(S2S 回调)

模型 app/models/ad_reward.py · 仓库 app/repositories/ad_reward.py · 接口 ad-pangle-callback / ad-reward-status / ad-test-grant · ← 索引 · 总览

每条 = 穿山甲一次服务端激励回调。trans_id 唯一做幂等键(穿山甲会重试,同号只处理一次)。reward_scene 区分普通激励视频、签到膨胀等场景;reward_date(北京时间日期串)给普通激励视频"每日上限"计数用。

用在哪 / 增删改查

• C(插入):POST /ad/pangle-callback(穿山甲 S2S,经 SHA256 验签;grant_ad_reward 或场景业务处理)或 POST /ad/test-grant(本地联调)。普通激励视频三道闸:① 验签不过 → API 层 403,不进库;② trans_id 已存在 → 原样返回不重复发;③ 当日发奖次数(DAILY_AD_REWARD_LIMIT,默认 500)到顶 → 记一行 status='capped'、coin=0、不发币。否则按 eCPM 公式发币。另:POST /ad/reward-noshow(record_reward_noshow,Bearer)在用户提前关/未发奖时记一行 status='closed_early'、coin=0 留痕(同 session 已 granted 则跳过)。
• U / D:无。
• R:GET /ad/reward-status(看广告页:今日已发次数/上限、单次金币、本轮已看/冷却结束、今日已看时长/上限);审计/对账整表回溯。

字段

列	类型	约束 / 默认	说明(取值 / join)
id	Integer	PK, autoincrement
trans_id	String(64)	UNIQUE, index, NOT NULL	穿山甲交易号(幂等键)。被 coin_transaction.ref_id 引用(biz_type=reward_video/signin_boost 等)。closed_early 留痕记录无 S2S 交易号,用合成键 noreward:{ad_session_id}
user_id	Integer	FK→user.id, index, NOT NULL	归属用户(回调 media_extra 带回;不存在抛 UnknownUserError)
reward_scene	String(32)	NOT NULL, default reward_video	奖励场景:reward_video 普通激励视频;signin_boost 签到膨胀
ad_session_id	String(64)	index, nullable	客户端广告会话 ID,来自 extra.ad_session_id;用于匹配 ad_ecpm_record
ecpm_raw	String(32)	nullable	本次发奖采用的 eCPM 原始值;可来自 S2S ecpm 或客户端上报
app_env	String(16)	nullable	来源应用 prod(傻瓜比价)/test(测试);S2S 不带,发奖时按 ad_session_id 匹配 ad_ecpm_record 回填,查不到 NULL。广告收益报表金币侧按它聚合
our_code_id	String(64)	nullable	我们配置的代码位 104xxx(同上回填)
coin	Integer	NOT NULL, default 0	实发金币;capped/ecpm_missing/closed_early/业务不满足时为 0
status	String(16)	NOT NULL, default granted	取值:granted(已发)/ capped(当日次数超限)/ ecpm_missing(缺 eCPM)/ closed_early(展示了但用户提前关/跳过,未发奖,客户端 reward-noshow 留痕)/ not_signed/already_boosted/last_day/ unknown_scene(回调 reward_scene 不在支持集合,只留痕不发)
reward_date	String(10)	index, NOT NULL	北京时间日期串 YYYY-MM-DD,按它等值统计当日发奖次数
reward_name	String(64)	nullable	穿山甲上报奖励名(参考,不作发奖依据)
raw	String(1024)	nullable	回调原始参数(审计排查)
created_at	DateTime(tz)	server_default now(), index	时间

关系 / Join Key

• user_id → user.id(多对一)。
• trans_id ← 被 coin_transaction.ref_id 引用(granted 那条发币流水);未发币状态无对应流水。
• ad_session_id → 可关联 ad_ecpm_record.ad_session_id。

索引与约束

• PK id;UNIQUE+index trans_id;index user_id、reward_date、created_at、ad_session_id。

注意

• 普通激励视频按 eCPM 公式发奖;若 S2S 与客户端会话上报都缺 eCPM,记录 status='ecpm_missing'、coin=0,不发币。
• 签到膨胀复用本表记录 S2S 幂等,实发固定 2000 金币由 signin_boost_record/coin_transaction.biz_type=signin_boost 承载。
• 并发同 trans_id 撞唯一约束 → catch IntegrityError 回滚返回已存在那条(幂等兜底)。