feat(ad): 膨胀弹窗改用服务端权威金额 + 本轮累计口径,下线 signin_boost (#154)

Co-authored-by: guke <guke@wonderable.ai>
Co-authored-by: 左辰勇 <exinglang@gmail.com>
Reviewed-on: #154
Co-authored-by: zuochenyong <zuochenyong@wonderable.ai>
Co-committed-by: zuochenyong <zuochenyong@wonderable.ai>

app/api/v1/ad.py

@@ -3,6 +3,8 @@
 路由前缀 `/api/v1/ad`:
   GET  /pangle-callback   穿山甲 S2S 发奖回调(**无 JWT,靠验签**),穿山甲服务器调
   GET  /reward-status     客户端查今日看广告发奖进度(Bearer)
+  GET  /reward-result/{ad_session_id}
+                          客户端按会话查本次广告实发金币(Bearer,只读,弹窗金额用)
 
 发奖走服务端:激励视频播完穿山甲回调本接口,验签通过后幂等发金币。客户端只负责
 看完后刷新余额,不参与发奖,被破解也刷不到钱。
@@ -13,7 +15,7 @@ import json
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Path, Request, status
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import rewards
@@ -25,8 +27,8 @@ from app.repositories import ad_feed_reward as crud_feed
 from app.repositories import ad_reward as crud_ad
 from app.repositories import ad_watch as crud_watch
 from app.repositories import app_config
-from app.repositories import signin as crud_signin
 from app.schemas.ad import (
+    AdRewardResultOut,
     AdRewardStatusOut,
     EcpmReportIn,
     EcpmReportOut,
@@ -52,11 +54,14 @@ REASON_BAD_PARAMS = 1  # 验签过但缺 trans_id / user_id 非数字
 REASON_UNKNOWN_USER = 2  # user_id 不存在(可能伪造)
 
 REWARD_SCENE_REWARD_VIDEO = "reward_video"
-REWARD_SCENE_SIGNIN_BOOST = "signin_boost"
 # 提现看视频:看完才能提现的「硬门槛」广告,**不发金币**,只记一条幂等记录(收益由 eCPM 上报口径
 # ad_type="withdrawal_video" 单独统计)。故意不放进 SUPPORTED_REWARD_SCENES——它不走发币分支。
 REWARD_SCENE_WITHDRAWAL_AD = "withdrawal_ad"
-SUPPORTED_REWARD_SCENES = {REWARD_SCENE_REWARD_VIDEO, REWARD_SCENE_SIGNIN_BOOST}
+# 2026-07 下线 signin_boost(签到膨胀):它按固定 3000 金币发,与广告实际收益脱钩,产品确认
+# 从来不是设计内的口径。签到弹窗里的「看广告膨胀」现在与福利页看视频走同一条 reward_video
+# 路径(按 eCPM 公式发),奖励只剩「签到」+「看视频」两种。历史发币流水(coin_transaction
+# .biz_type='signin_boost')保留不动——钱是真发过的,账必须留。
+SUPPORTED_REWARD_SCENES = {REWARD_SCENE_REWARD_VIDEO}
 
 
 def _parse_extra(raw_extra: str | None) -> dict[str, str]:
@@ -118,6 +123,11 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
         extra.update(_parse_extra(params.get(extra_key)))
     reward_scene = extra.get("reward_scene") or REWARD_SCENE_REWARD_VIDEO
     ad_session_id = extra.get("ad_session_id")
+    # 「这条广告属于哪一轮膨胀」。纯标签:不参与发奖判定,只让 reward-result 能把同一轮求和成
+    # 弹窗要显示的累计值(见 crud_ad.round_coin_total)。老客户端不带 → NULL → 累计值返 null。
+    boost_round_id = (extra.get("boost_round_id") or None)
+    if boost_round_id is not None:
+        boost_round_id = boost_round_id[:64]
     ecpm = params.get("ecpm")
 
     # 环境隔离:激励视频 mediaExtra 里带「这次观看属于哪个后端环境」(srv_env=dev/prod,客户端按
@@ -169,50 +179,11 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
                 user_id, trans_id, reward_scene,
             )
             return PangleCallbackOut(is_verify=False, reason=REASON_BAD_PARAMS)
-        if reward_scene == REWARD_SCENE_SIGNIN_BOOST:
-            try:
-                boost, _balance = crud_signin.boost_today_signin(
-                    db, user_id, ad_ref_id=trans_id, commit=False
-                )
-            except crud_signin.NotSignedTodayError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="not_signed",
-                )
-            except crud_signin.AlreadyBoostedError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="already_boosted",
-                )
-            except crud_signin.LastCycleDayBoostBlockedError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="last_day",
-                )
-            else:
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=boost.coin_awarded,
-                    reward_scene=reward_scene, ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    commit=False,
-                )
-                db.commit()
-                db.refresh(rec)
-        else:
-            rec = crud_ad.grant_ad_reward(
-                db, user_id, trans_id, ecpm=ecpm, ad_session_id=ad_session_id,
-                reward_scene=REWARD_SCENE_REWARD_VIDEO,
-                reward_name=params.get("reward_name"), raw=raw[:1024],
-            )
+        rec = crud_ad.grant_ad_reward(
+            db, user_id, trans_id, ecpm=ecpm, ad_session_id=ad_session_id,
+            reward_scene=REWARD_SCENE_REWARD_VIDEO, boost_round_id=boost_round_id,
+            reward_name=params.get("reward_name"), raw=raw[:1024],
+        )
     except crud_ad.UnknownUserError:
         logger.warning("pangle callback unknown user_id=%d trans_id=%s", user_id, trans_id)
         return PangleCallbackOut(is_verify=False, reason=REASON_UNKNOWN_USER)
@@ -242,6 +213,46 @@ def reward_status(user: CurrentUser, db: DbSession) -> AdRewardStatusOut:
     )
 
 
+@router.get(
+    "/reward-result/{ad_session_id}",
+    response_model=AdRewardResultOut,
+    summary="按 ad_session_id 查本次广告的权威发奖结果",
+    dependencies=[Depends(rate_limit(120, 60, "ad-reward-result"))],
+)
+def reward_result(
+    user: CurrentUser,
+    db: DbSession,
+    ad_session_id: str = Path(..., min_length=8, max_length=64, description="本次广告会话 id"),
+) -> AdRewardResultOut:
+    """客户端看完激励视频后轮询本接口拿**本次实发金币 + 本轮累计**用于弹窗,不再用余额差 /
+    coin_per_ad 估算(修「弹窗数值与真实金币对不上」)。
+
+    round_coin 是「恭喜累计获得奖励」弹窗真正显示的数:本轮(= 客户端的 boost_round_id)所有
+    granted 记录之和。由服务端求和而不是客户端自己累加——客户端进程被杀/重建后本地累计会丢,
+    发奖记录不会。取不到轮 id(pending / 老客户端 / extra 丢失)时为 null,客户端退回显示单条。
+
+    S2S 回调异步:查不到记录 = 回调还没到 → 返 200 + status='pending' 让客户端继续重试,
+    **不返 404**(404 只表示路由不存在)。纯只读:发奖仍只由验签过的 S2S 回调完成,
+    这里不写库、不产生任何奖励,被刷也只是查自己的记录。
+    """
+    rec = crud_ad.find_by_session(db, user.id, ad_session_id)
+    if rec is None:
+        # 连记录都没有 → 不知道属于哪一轮,round_coin 一并为 null(不是 0,0 会被当成"本轮没赚到")
+        return AdRewardResultOut(
+            ad_session_id=ad_session_id, status="pending", coin=None, round_coin=None,
+        )
+    # 本条不是 granted 时**仍返本轮累计**(这条按 0 计):第 3 条撞每日上限那下,客户端的限额
+    # toast 要显示的是前两条已到账的总额,不是空。
+    round_coin = (
+        crud_ad.round_coin_total(db, user.id, rec.boost_round_id)
+        if rec.boost_round_id
+        else None
+    )
+    return AdRewardResultOut(
+        ad_session_id=ad_session_id, status=rec.status, coin=rec.coin, round_coin=round_coin,
+    )
+
+
 @router.post(
     "/watch-report",
     response_model=WatchReportOut,
@@ -329,55 +340,27 @@ def test_grant(user: CurrentUser, db: DbSession, payload: TestGrantIn | None = N
     if reward_scene not in SUPPORTED_REWARD_SCENES:
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="bad reward_scene")
 
-    # 每次新 trans_id,模拟一次独立的穿山甲发奖回调(幂等键各不相同 → 每次都发,直到当日上限/今日膨胀一次)
+    # 每次新 trans_id,模拟一次独立的穿山甲发奖回调(幂等键各不相同 → 每次都发,直到当日上限)
     trans_id = f"test-{user.id}-{uuid.uuid4().hex}"
-    if reward_scene == REWARD_SCENE_SIGNIN_BOOST:
-        try:
-            boost, _balance = crud_signin.boost_today_signin(
-                db, user.id, ad_ref_id=trans_id, commit=False
-            )
-        except crud_signin.NotSignedTodayError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="not_signed",
-            )
-        except crud_signin.AlreadyBoostedError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="already_boosted",
-            )
-        except crud_signin.LastCycleDayBoostBlockedError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="last_day",
-            )
-        else:
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=boost.coin_awarded,
-                reward_scene=reward_scene, reward_name="测试签到膨胀",
-                raw="client debug test-grant signin_boost", commit=False,
-            )
-            db.commit()
-            db.refresh(rec)
-    else:
-        # 优先用客户端按 ad_session_id 上报的真实 eCPM(走与正式发奖相同的公式);
-        # 取不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍能验出非零金币。
-        ad_session_id = payload.ad_session_id if payload is not None else None
-        ecpm_val = "200"
-        if ad_session_id:
-            ecpm_rec = crud_ecpm.find_by_session(db, user_id=user.id, ad_session_id=ad_session_id)
-            if ecpm_rec is not None and rewards.parse_ecpm_fen(ecpm_rec.ecpm_raw) > 0:
-                ecpm_val = ecpm_rec.ecpm_raw
-        try:
-            rec = crud_ad.grant_ad_reward(
-                db, user.id, trans_id, ecpm=ecpm_val, ad_session_id=ad_session_id,
-                reward_name="测试发奖", raw=f"client debug test-grant ecpm={ecpm_val}",
-            )
-        except crud_ad.UnknownUserError as e:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user not found") from e
+    # 正式链路的轮次 id 走 S2S 的 mediaExtra;本接口不经 S2S,只能由 body 补,否则 debug 包
+    # 的 reward-result 恒返 round_coin=null,「弹窗 40 → 60」那套累计验收在本地跑不起来。
+    boost_round_id = (payload.boost_round_id if payload is not None else None) or None
+    # 优先用客户端按 ad_session_id 上报的真实 eCPM(走与正式发奖相同的公式);
+    # 取不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍能验出非零金币。
+    ad_session_id = payload.ad_session_id if payload is not None else None
+    ecpm_val = "200"
+    if ad_session_id:
+        ecpm_rec = crud_ecpm.find_by_session(db, user_id=user.id, ad_session_id=ad_session_id)
+        if ecpm_rec is not None and rewards.parse_ecpm_fen(ecpm_rec.ecpm_raw) > 0:
+            ecpm_val = ecpm_rec.ecpm_raw
+    try:
+        rec = crud_ad.grant_ad_reward(
+            db, user.id, trans_id, ecpm=ecpm_val, ad_session_id=ad_session_id,
+            boost_round_id=boost_round_id,
+            reward_name="测试发奖", raw=f"client debug test-grant ecpm={ecpm_val}",
+        )
+    except crud_ad.UnknownUserError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user not found") from e
 
     (used, limit, coin_per, round_count, cooldown_until,
      _watched, _watch_limit) = crud_ad.today_status(db, user.id)

app/api/v1/signin.py

@@ -1,9 +1,12 @@
 """签到 endpoint。
 
 路由前缀 `/api/v1/signin`:
-  GET  /status    今日签到状态 + 14 天档位
+  GET  /status    今日签到状态 + 7 天档位
   POST /          执行今日签到
-  POST /boost     签到后看广告膨胀金币
+
+2026-07 下线 `POST /boost`(签到膨胀):它按固定 3000 金币补发、与广告实际收益脱钩。
+签到弹窗里的「看广告膨胀」改与福利页看视频走同一条 reward_video 路径(按 eCPM 发,
+`/ad/pangle-callback` → `/ad/reward-result` 取金额),奖励只剩「签到」+「看视频」两种。
 """
 from __future__ import annotations
 
@@ -12,15 +15,8 @@ import logging
 from fastapi import APIRouter, HTTPException, status
 
 from app.api.deps import CurrentUser, DbSession
-from app.repositories import ad_reward as crud_ad
 from app.repositories import signin as crud_signin
-from app.repositories import wallet as crud_wallet
-from app.schemas.welfare import (
-    SigninBoostRequest,
-    SigninBoostResultOut,
-    SigninResultOut,
-    SigninStatusOut,
-)
+from app.schemas.welfare import SigninResultOut, SigninStatusOut
 
 logger = logging.getLogger("shagua.signin")
 
@@ -50,34 +46,3 @@ def do_signin(user: CurrentUser, db: DbSession) -> SigninResultOut:
         streak=record.streak,
         coin_balance=balance,
     )
-
-
-@router.post("/boost", response_model=SigninBoostResultOut, summary="签到后看广告膨胀金币")
-def boost_signin(
-    payload: SigninBoostRequest, user: CurrentUser, db: DbSession
-) -> SigninBoostResultOut:
-    if not payload.ad_ref_id:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="ad reward required")
-    ad_rec = crud_ad.find_by_trans(db, payload.ad_ref_id)
-    if (
-        ad_rec is None
-        or ad_rec.user_id != user.id
-        or ad_rec.reward_scene != "signin_boost"
-        or ad_rec.status != "granted"
-    ):
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="ad reward not verified")
-    record = crud_signin.boost_by_ad_ref(db, user.id, payload.ad_ref_id)
-    if record is None:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="signin boost not granted")
-    acc = crud_wallet.get_or_create_account(db, user.id)
-    balance = acc.coin_balance
-
-    logger.info(
-        "signin boost ok user_id=%d date=%s coin=%d",
-        user.id, record.signin_date, record.coin_awarded,
-    )
-    return SigninBoostResultOut(
-        coin_awarded=record.coin_awarded,
-        coin_balance=balance,
-        signin_date=record.signin_date.isoformat(),
-    )