shaguabijia-app-server/app/repositories/ad_reward.py

"""看激励视频发奖 CRUD。

发奖三道闸(仿提现的资金安全思路):
  1. 验签不过 → API 层直接拒,不进这里。
  2. trans_id 唯一 → 同一交易号二次回调不重复发(穿山甲会重试)。
  3. 当日发奖次数 ≥ 上限 → 记一条 status='capped' 但不发金币。

发金币复用 `wallet.grant_coins`(biz_type='ad_reward', ref_id=trans_id),与发奖记录同事务,
保证"记一笔 + 加金币"原子化。单次金币 / 每日上限 / 每轮冷却 都从 app_config 读(运营后台可改)。
"""
from __future__ import annotations

from datetime import datetime, timezone

from sqlalchemy import func, select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.orm import Session

from app.core import rewards
from app.core.ad_cooldown import compute_cooldown
from app.core.rewards import DAILY_AD_WATCH_SECONDS_LIMIT, cn_today
from app.models.ad_reward import AdRewardRecord
from app.models.user import User
from app.repositories import wallet as crud_wallet
from app.repositories.ad_watch import watched_seconds_today


class UnknownUserError(Exception):
    """回调里的 user_id 不存在(可能是伪造)。"""


def _find_by_trans(db: Session, trans_id: str) -> AdRewardRecord | None:
    return db.execute(
        select(AdRewardRecord).where(AdRewardRecord.trans_id == trans_id)
    ).scalar_one_or_none()


def _granted_today(db: Session, user_id: int, reward_date: str) -> int:
    return db.execute(
        select(func.count())
        .select_from(AdRewardRecord)
        .where(
            AdRewardRecord.user_id == user_id,
            AdRewardRecord.reward_date == reward_date,
            AdRewardRecord.status == "granted",
        )
    ).scalar_one()


def grant_ad_reward(
    db: Session,
    user_id: int,
    trans_id: str,
    *,
    coin: int | None = None,
    reward_name: str | None = None,
    raw: str | None = None,
) -> AdRewardRecord:
    """看广告发奖(幂等 + 每日限额)。返回发奖记录(status=granted/capped)。

    coin 为本次发放金币(由调用方按穿山甲回调 reward_amount 解析,见
    rewards.resolve_ad_reward_coin);None → 读配置 get_ad_reward_coin(test-grant / 缺省场景)。
    user_id 不存在抛 UnknownUserError(不建账户,防伪造 user_id 刷出脏数据)。
    """
    # #2 幂等:同 trans_id 已处理过 → 原样返回,不重复发
    existing = _find_by_trans(db, trans_id)
    if existing is not None:
        return existing

    if db.get(User, user_id) is None:
        raise UnknownUserError

    today = cn_today().isoformat()

    # #3 每日上限:当前产品只保留发奖次数上限(默认 500 次)。旧的观看时长闸保留字段,
    # 但 DAILY_AD_WATCH_SECONDS_LIMIT=0 时视为停用,不能命中 capped。
    over_time = (
        DAILY_AD_WATCH_SECONDS_LIMIT > 0
        and watched_seconds_today(db, user_id, today=today) >= DAILY_AD_WATCH_SECONDS_LIMIT
    )
    over_count = _granted_today(db, user_id, today) >= rewards.get_ad_daily_limit(db)
    if over_time or over_count:
        rec = AdRewardRecord(
            trans_id=trans_id, user_id=user_id, coin=0, status="capped",
            reward_date=today, reward_name=reward_name, raw=raw,
        )
        return _commit_record(db, rec, trans_id)

    if coin is None:
        coin = rewards.get_ad_reward_coin(db)

    # 发金币 + 记一笔,同事务
    crud_wallet.grant_coins(
        db, user_id, coin,
        biz_type="ad_reward", ref_id=trans_id, remark="看视频奖励金币",
    )
    rec = AdRewardRecord(
        trans_id=trans_id, user_id=user_id, coin=coin, status="granted",
        reward_date=today, reward_name=reward_name, raw=raw,
    )
    return _commit_record(db, rec, trans_id)


def _commit_record(db: Session, rec: AdRewardRecord, trans_id: str) -> AdRewardRecord:
    """提交发奖记录;并发下同 trans_id 撞唯一约束时回滚并返回已存在的那条(幂等兜底)。"""
    db.add(rec)
    try:
        db.commit()
    except IntegrityError:
        db.rollback()
        existing = _find_by_trans(db, trans_id)
        if existing is not None:
            return existing
        raise
    db.refresh(rec)
    return rec


def _granted_times_today_desc(db: Session, user_id: int, reward_date: str) -> list[datetime]:
    """当日 status=granted 记录的 created_at,按时间倒序(最新在前)——冷却策略的输入数据。"""
    return list(
        db.execute(
            select(AdRewardRecord.created_at)
            .where(
                AdRewardRecord.user_id == user_id,
                AdRewardRecord.reward_date == reward_date,
                AdRewardRecord.status == "granted",
            )
            .order_by(AdRewardRecord.created_at.desc())
        ).scalars()
    )


def today_status(
    db: Session, user_id: int
) -> tuple[int, int, int, int, datetime | None, int, int]:
    """客户端查"今日看广告发奖"进度。

    返回 (今日已发次数, 每日次数上限, 单次金币, 本轮已看次数, 本轮冷却结束时间(UTC),
          今日已观看总秒数, 每日观看总时长上限(秒))。
    次数上限/单次金币/每轮次数/冷却秒 均从 app_config 读(运营后台可改);次数维度的"本轮已看
    几次 + 冷却到几点"委托 [app.core.ad_cooldown.compute_cooldown](纯函数);观看时长字段保留给
    旧客户端兼容,当前 DAILY_AD_WATCH_SECONDS_LIMIT=0 表示不启用时长闸。
    """
    today = cn_today().isoformat()
    granted_desc = _granted_times_today_desc(db, user_id, today)
    state = compute_cooldown(
        granted_desc,
        datetime.now(timezone.utc),
        round_size=rewards.get_ad_round_count(db),
        cooldown_seconds=rewards.get_ad_cooldown_sec(db),
    )
    return (
        len(granted_desc),
        rewards.get_ad_daily_limit(db),
        rewards.get_ad_reward_coin(db),
        state.round_count,
        state.cooldown_until,
        watched_seconds_today(db, user_id, today=today),
        DAILY_AD_WATCH_SECONDS_LIMIT,
    )