shaguabijia-app-server/app/schemas/ad.py

"""看激励视频发奖相关 schemas。

约定同其余模块:字段 snake_case、金额/次数存整数。
"""
from __future__ import annotations

from datetime import datetime

from pydantic import BaseModel, Field


class PangleCallbackOut(BaseModel):
    """回给穿山甲 GroMore 的回调响应。

    GroMore 服务端激励回调规范(supportcenter/26240)要求响应体为
    `{"is_verify": bool, "reason": int}`:
    - `is_verify=true` + `reason=0`:校验通过、发放奖励(发奖成功 或 当日已达上限均算"已处理")。
    - `is_verify=false`:不发放,`reason` 带错误码透传客户端 SDK(见 ad.py 的 REASON_*)。
    验签失败由 API 层直接返 403,不走这里。"""

    is_verify: bool = True
    reason: int = 0


class AdRewardStatusOut(BaseModel):
    """客户端查今日看广告发奖进度(福利页"看视频赚金币"用)。"""

    used_today: int = Field(..., description="今日已成功发奖次数")
    daily_limit: int = Field(..., description="每日发奖次数上限")
    remaining: int = Field(..., description="今日剩余可领次数")
    coin_per_ad: int = Field(..., description="历史兼容字段;正式发放按 eCPM 动态计算,当前返回 0")
    round_count: int = Field(
        ..., description="本轮已看次数,当前 round_size=1,客户端可由 cooldown_until 判断短冷却"
    )
    cooldown_until: datetime | None = Field(
        None,
        description="广告关闭后 3 秒短冷却结束时间(UTC ISO),null 表示不在冷却。"
        "冷却是 UX 约束,后端发奖不受影响,客户端 CTA 据此显示 MM:SS 倒计时且不可点",
    )
    # ===== 旧版每日观看总时长字段:当前产品仅保留每日 500 次上限,limit=0 表示未启用时长闸 =====
    watched_seconds_today: int = Field(0, description="今日已观看激励视频总秒数(前端累计上报)")
    watch_seconds_limit: int = Field(0, description="每日观看总时长上限(秒);0 表示当前未启用")
    watch_seconds_remaining: int = Field(0, description="今日剩余可观看秒数;limit=0 时客户端不据此拦截")


class EcpmReportIn(BaseModel):
    """客户端上报一次广告展示的 eCPM(内部收益统计/对账)。

    user_id 不在 body 里——由 JWT 取(Bearer),防伪造。ecpm 原样上报字符串,后端按分/千次展示处理(SDK getEcpm 原值,非元)。
    """

    ad_type: str = Field(..., description="广告类型:reward_video(激励视频) / draw(Draw 信息流) 等")
    ecpm: str = Field(..., description="穿山甲 getShowEcpm().getEcpm() 原始字符串,按分/千次展示处理(SDK getEcpm 原值,非元)")
    ad_session_id: str | None = Field(
        None, min_length=8, max_length=64,
        description="客户端生成的一次广告会话 id;激励视频 S2S extra 会透传同值",
    )
    adn: str | None = Field(None, description="实际投放 ADN(getSdkName),如 pangle")
    slot_id: str | None = Field(None, description="实际展示代码位(底层 mediation rit)")
    feed_scene: str | None = Field(
        None,
        max_length=16,
        description="点位场景:comparison(比价) / coupon(领券) / welfare(福利);激励视频为空",
    )


class EcpmReportOut(BaseModel):
    """eCPM 上报结果。best-effort,落库即 ok。"""

    ok: bool = True


class WatchReportIn(BaseModel):
    """客户端上报一次激励视频的实际观看时长(onAdClose 时,onAdShow→onAdClose 墙钟秒数)。

    user_id 由 JWT 取(Bearer),不在 body。seconds 服务端会夹 [0, MAX_SINGLE_WATCH_SECONDS]。
    """

    seconds: int = Field(..., ge=0, description="本次观看秒数")


class WatchReportOut(BaseModel):
    """上报后返回当日累计 + 剩余,客户端即时更新"今日还能看多久"。"""

    watched_seconds_today: int = Field(..., description="今日累计观看秒数")
    watch_seconds_limit: int = Field(..., description="每日上限(秒)")
    watch_seconds_remaining: int = Field(..., description="今日剩余可观看秒数")


class TestGrantIn(BaseModel):
    """[仅本地联调]模拟发奖入参。"""

    reward_scene: str = Field(
        "reward_video",
        description="模拟发奖场景:reward_video(普通激励视频) / signin_boost(签到膨胀)",
    )
    ad_session_id: str | None = Field(
        None, min_length=8, max_length=64,
        description="本次广告会话 id(与 ecpm-report 同值)。reward_video 场景下据此查回客户端"
        "已上报的真实 eCPM 来按公式发奖;查不到或 eCPM≤0 时兜底 200,保证本地联调仍出非零金币",
    )


class TestGrantOut(BaseModel):
    """[仅本地联调]模拟发奖结果。带上今日进度,客户端可直接据此刷新展示。"""

    granted: bool = Field(..., description="本次是否真的发了金币(达每日上限则 False)")
    status: str = Field(
        ..., description="granted / capped / not_signed / already_boosted / last_day / unknown_scene"
    )
    coin: int = Field(..., description="本次发放金币(capped 时为 0)")
    used_today: int = Field(..., description="今日已成功发奖次数")
    daily_limit: int = Field(..., description="每日发奖次数上限")
    remaining: int = Field(..., description="今日剩余可领次数")
    coin_per_ad: int = Field(..., description="历史兼容字段;正式发放按 eCPM 动态计算,当前返回 0")
    round_count: int = Field(..., description="本轮已看次数,详见 AdRewardStatusOut")
    cooldown_until: datetime | None = Field(
        None, description="本轮冷却结束时间(UTC),详见 AdRewardStatusOut"
    )


class FeedRewardIn(BaseModel):
    """信息流广告完成后结算奖励。

    每展示满 10 秒累计一份奖励,视频完成后一次性入账。client_event_id 用于客户端超时重试幂等。
    """

    client_event_id: str = Field(..., min_length=8, max_length=64, description="客户端生成的幂等事件 id")
    ad_session_id: str | None = Field(
        None, min_length=8, max_length=64, description="客户端生成的一次信息流广告会话 id"
    )
    ecpm: str = Field(..., description="本条信息流广告 eCPM,按分/千次展示处理(SDK getEcpm 原值,非元)")
    duration_seconds: int = Field(..., ge=0, description="本条广告实际展示/播放秒数")
    adn: str | None = Field(None, description="实际投放 ADN")
    slot_id: str | None = Field(None, description="实际展示代码位")


class FeedRewardOut(BaseModel):
    granted: bool = Field(..., description="本次是否入账。达上限时 false")
    status: str = Field(..., description="granted / capped")
    coin: int = Field(..., description="本次发放金币")
    unit_count: int = Field(..., description="按 10 秒折算出的奖励份数")
    daily_limit: int = Field(..., description="每日信息流展示次数上限")