"""新手引导视频播放记录(领券浮层前 N 次用它替代广告)。

产品规则(2026-07 拍板):新用户点「一键自动领取」后的等候浮层,**前 3 次**不放广告,
改放运营后台上传的引导视频;每次固定 120 金币,中途关闭也算看完照发。

口径:
- **计次按账号**(user_id),与设备无关 —— 换设备不重新送 3 次。
- **开播即计数**:客户端每次要展示浮层时调 `/api/v1/guide-video/start`,服务端当场
  写一行(status='playing')并返回 play_token;`COUNT(*)` 即已用次数。用户中途 kill
  App 也算用掉一次(产品选定口径,防反复进出刷金币)。
- **发币幂等**靠 play_token 定位 + `status='playing'` 条件更新:并发两次上报只有一次
  改到行(另一次 rowcount=0),所以只发一次币。光有 play_token 唯一键挡不住 —— 发币走的是
  UPDATE,不 INSERT,撞不到任何唯一键。
- **次数上限**靠 (user_id, seq) 唯一键兜底,防并发 /start 绕过 COUNT 判定(见下)。

与广告收益(ad_feed_reward_record)彻底分离:引导视频不是广告,不该进广告收益报表。
"""
from __future__ import annotations

from datetime import datetime

from sqlalchemy import DateTime, ForeignKey, Index, Integer, String, UniqueConstraint, func
from sqlalchemy.orm import Mapped, mapped_column

from app.db.base import Base


class GuideVideoPlay(Base):
    """一次引导视频播放一行。开播时建(status='playing'),发币后置 'granted'。"""

    __tablename__ = "guide_video_play"
    __table_args__ = (
        # 客户端幂等键:同一次播放重复上报奖励只发一次。
        UniqueConstraint("play_token", name="uq_guide_video_play_token"),
        # 次数上限的**硬约束**:start_play 是无锁 check-then-insert(读 COUNT 算 seq 再插),
        # N 个并发 /start 会都读到同一个已用次数、算出同一个 seq,不拦就能各拿一个 token、
        # 各发一次金币,3 次上限形同虚设(改包即可无限刷)。seq 唯一 → 并发同 seq 必撞,
        # start_play 捕获 IntegrityError 降级成"这次不放视频"。
        # 用 unique Index 而非 UniqueConstraint:与迁移里的 create_index 对齐(SQLite 加约束
        # 要整表重建),autogenerate 才不会每次报一条假 diff。
        Index("uq_guide_video_play_user_seq", "user_id", "seq", unique=True),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        Integer, ForeignKey("user.id"), index=True, nullable=False
    )
    # 服务端生成下发给客户端的幂等键(uuid hex)。
    play_token: Mapped[str] = mapped_column(String(64), nullable=False)
    # 触发场景:目前只有 coupon(领券等候浮层);留字段以便日后比价等场景复用。
    scene: Mapped[str] = mapped_column(String(16), nullable=False, default="coupon")
    # 本账号第几次(1-based),= 建行时已有行数 + 1。日常判定仍以 COUNT 为准,但 (user_id, seq)
    # 唯一键让并发 /start 只能成一个 —— 见 __table_args__。
    seq: Mapped[int] = mapped_column(Integer, nullable=False, default=1)
    # 当次下发的视频地址(运营换片后能回溯用户当时看的是哪支)。
    video_url: Mapped[str | None] = mapped_column(String(512), nullable=True)
    # 实发金币;未发时 0。
    coin: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
    # playing(已开播未发币) / granted(已发币)。
    status: Mapped[str] = mapped_column(String(16), nullable=False, default="playing")
    # 客户端上报时是否播完(true=自然播完 / false=中途关闭)。仅留痕:两者都发币。
    completed: Mapped[int] = mapped_column(Integer, nullable=False, default=0)

    started_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
    )
    granted_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)

    def __repr__(self) -> str:  # pragma: no cover
        return (
            f"<GuideVideoPlay user={self.user_id} seq={self.seq} "
            f"{self.status} coin={self.coin}>"
        )