live-hub-py/web/backend/models.py

"""ORM 模型"""

from __future__ import annotations

from datetime import UTC, datetime

from sqlalchemy import (
    JSON,
    BigInteger,
    Boolean,
    Computed,
    ForeignKey,
    Index,
    Integer,
    String,
    Text,
    UniqueConstraint,
    text,
)
from sqlalchemy.orm import Mapped, mapped_column, relationship

from .crypto_storage import EncryptedText
from .database import Base, UTCDateTime
from .huya_defaults import (
    HUYA_DEFAULT_BIND_ACT_ID,
    HUYA_DEFAULT_OUTER_ACT_ID,
    HUYA_DEFAULT_PAY_CHANNEL,
    HUYA_DEFAULT_ROOM_PID,
    HUYA_DEFAULT_SID,
)


def _utcnow():
    """返回时区感知的 UTC 当前时间，替代 _utcnow()。"""
    return datetime.now(UTC)


class User(Base):
    """系统用户"""

    __tablename__ = "users"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    username: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    password_hash: Mapped[str] = mapped_column(String(256), nullable=False)
    role: Mapped[str] = mapped_column(
        String(32), nullable=False, default="support"
    )  # super_admin / operation / support
    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
    remark: Mapped[str] = mapped_column(String(256), default="")
    custom_permissions: Mapped[list[str] | None] = mapped_column(
        JSON, nullable=True, comment="自定义权限列表，null表示使用角色默认权限"
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )
    deleted_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True, index=True
    )
    deleted_username: Mapped[str] = mapped_column(String(64), default="")

    # ---- 安全登录（手机号 + 短信验证码 + DCAuth 设备签名）----
    phone: Mapped[str] = mapped_column(
        String(32), nullable=False, default="", server_default=""
    )
    phone_bound_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    phone_bound_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
    )
    # MySQL 不支持部分唯一索引：用生成列把「空手机号」变成 NULL，
    # 再对它建唯一索引，效果等同 PostgreSQL 的 `UNIQUE (phone) WHERE phone <> ''`。
    phone_unique: Mapped[str | None] = mapped_column(
        String(32),
        Computed("NULLIF(phone, '')", persisted=True),
        nullable=True,
    )

    __table_args__ = (Index("uq_users_phone_unique", "phone_unique", unique=True),)

    # 客服被分配的账号
    assigned_accounts: Mapped[list[Account]] = relationship(
        "Account", back_populates="assigned_user", foreign_keys="Account.assigned_to"
    )
    huya_accounts: Mapped[list[HuyaAccount]] = relationship(
        "HuyaAccount",
        back_populates="assigned_user",
        foreign_keys="HuyaAccount.assigned_to",
    )


class Account(Base):
    """斗鱼账号"""

    __tablename__ = "accounts"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    username: Mapped[str] = mapped_column(String(128), nullable=False)
    password: Mapped[str] = mapped_column(EncryptedText(), nullable=False)
    email: Mapped[str] = mapped_column(EncryptedText(), nullable=False)
    email_password: Mapped[str] = mapped_column(EncryptedText(), nullable=False)
    email_imap_server: Mapped[str] = mapped_column(String(128), default="")
    email_imap_port: Mapped[int] = mapped_column(Integer, default=993)
    email_imap_ssl: Mapped[bool] = mapped_column(Boolean, default=True)
    assigned_to: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )
    tag: Mapped[str] = mapped_column(String(64), default="")
    remark: Mapped[str] = mapped_column(String(256), default="")
    uid: Mapped[str] = mapped_column(String(32), default="", index=True)
    nickname: Mapped[str] = mapped_column(String(128), default="")
    points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    game_name: Mapped[str] = mapped_column(String(128), default="")
    game_channel: Mapped[str] = mapped_column(String(128), default="")
    gold_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    exchange_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # ⚠️ 已废弃的「垃圾场」列：曾混杂状态/动作/查询三种语义，覆盖式写入导致
    # 「到底绑没绑」查不出来。S6 起**不再有任何写入方**，绑定状态走下面三列。
    # 计划在 S8 连同其他历史包袱一起 drop（需先做备份）。
    bind_status: Mapped[str] = mapped_column(String(32), default="")
    # 精英宝典角色绑定：unknown / unbound / pending / bound（见 services/account_binding）
    role_bind_status: Mapped[str] = mapped_column(
        String(16), default="unknown", server_default="unknown"
    )
    # 一键查询得到的「该账号已兑换过的高价值套装名」列表（如 ["套装-兔兔白日梦"]）。
    #
    # 为什么单开一列、而不是让列表读 `overview_snapshot`：那份 JSON 有 1~2KB，
    # 账号列表是全站最热的接口之一，15000 个账号各带一份会把响应放大到几十 MB。
    # 这里只有几个短字符串。
    #
    # 兑换**条数**不存这里 —— 列表直接从官方事件聚合，不维护第二套计数。
    high_value_owned: Mapped[list | None] = mapped_column(JSON, nullable=True)
    # 最近一次「一键查询」的快照（结构化结果）。存在账号上而不是只留在任务里：
    # 任务会被保留策略清掉，而运营看的是"这个账号现在什么情况"。
    overview_snapshot: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    overview_queried_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    # 积分**到期时刻**（斗鱼在积分查询里给 `willExpireTime`，只有送礼后的那次查询才有）。
    # 积分到期是账号资产的真实减少，但斗鱼不会「通知」你 —— 所以这里记下到期时刻，
    # 由作业在到期后补记一条 `points_expire` 事件（否则这个减少在时间线上是空白）。
    points_expire_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    # 电竞手册是否已开通（与 elite_opened 对称）。
    # 以前这个状态**只寄生在 `esports_bind_status` 里**（取值 `esports_opened`）——
    # 那是「一列多义」的典型：同一个列既表示开通、又表示角色绑定、又表示查询痕迹。
    # S6 拆解时差点把这个信息丢掉，所以补成独立布尔列。
    esports_opened: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
    change_role_wait_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # 精英宝典开通状态（getUserInfo 的 manualType / expireTime）。
    # 光看积分区分不了「开通后积分花完」和「从未开通」，必须单独落库。
    elite_opened: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
    elite_expire_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    esports_points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    esports_game_name: Mapped[str] = mapped_column(String(128), default="")
    esports_game_channel: Mapped[str] = mapped_column(String(128), default="")
    esports_bind_status: Mapped[str] = mapped_column(
        String(16), default="unknown", server_default="unknown"
    )
    esports_change_role_wait_time: Mapped[int | None] = mapped_column(
        Integer, nullable=True
    )
    # 电竞手册**到期时间**（与 `elite_expire_time` 对称）。
    # 以前只在 `_refresh_esports_handbook` 的返回值里带着，没落库 ——
    # 于是界面上电竞只能显示"已开通"、看不到到期时间。
    esports_expire_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    esports_can_change_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    xpd_game_name: Mapped[str] = mapped_column(String(128), default="")
    xpd_openid: Mapped[str] = mapped_column(String(128), default="")
    # 自动化后门：false 时巡检与自动重登都跳过这个账号（特殊账号人工维护）。
    auto_managed: Mapped[bool] = mapped_column(
        Boolean, default=True, server_default="1"
    )
    xpd_role_id: Mapped[str] = mapped_column(String(64), default="")
    xpd_plat_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    xpd_area_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    xpd_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    xpd_fragments: Mapped[int | None] = mapped_column(Integer, nullable=True)
    xpd_bind_status: Mapped[str] = mapped_column(
        String(16), default="unknown", server_default="unknown"
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    # ── 登录态：CK 本体（账号自己的凭证，不再寄存在 login_tasks 上）──────────
    # 历史问题：CK 曾只存在于 login_tasks.cookie，删一条登录历史就等于删掉账号的
    # 登录态（2026-10-03 误删事故的根因）。CK 是**账号级凭证**，必须挂在账号上。
    # 注意：**不能给这列加 server_default** —— MySQL 不允许 TEXT/BLOB/JSON 列有默认值
    # （错误 1101）。已有行由 ALTER TABLE 隐式填 ''，新建行由 Python 侧 default 兜。
    cookie: Mapped[str] = mapped_column(EncryptedText(), nullable=False, default="")
    cookie_updated_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    # 这份 CK 是怎么来的：web / app / sms / import（空 = 历史回填，来源未知）
    cookie_source: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )

    # ── 登录态：CK 健康（巡检/人工检测的当前结论）──────────────────────────
    ck_check_status: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )  # valid / invalid / error / 空 = 未检测
    ck_check_result: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    ck_checked_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    # ── 登录态：自动重登的退避进度 ─────────────────────────────────────────
    relogin_attempts: Mapped[int] = mapped_column(
        Integer, nullable=False, default=0, server_default="0"
    )
    relogin_next_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    relogin_last_error: Mapped[str] = mapped_column(
        String(512), nullable=False, default="", server_default=""
    )
    # 失败分型：captcha / credential 转人工，email_code / email_quota /
    # interrupted / network 自动重试。空 = 没失败过。
    relogin_failure_kind: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )

    # ── 生命周期状态 ───────────────────────────────────────────────────────
    # 取值域见 docs/设计-账号全生命周期.md §3.4。**写入必须收口到
    # services/account_lifecycle.py**，禁止各处直接赋值 —— accounts.bind_status
    # 就是「谁都能写、语义没人管」的反面教材（36 种取值互相覆盖）。
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, default="imported", server_default="imported"
    )
    status_reason: Mapped[str] = mapped_column(
        String(64), nullable=False, default="", server_default=""
    )
    status_changed_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    disabled_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    archived_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    __table_args__ = (
        # 巡检按「最久没查的优先」选行
        Index("ix_accounts_ck_checked_at", "ck_checked_at"),
        # 重登按状态 + 退避时间选行
        Index("ix_accounts_status_relogin_next", "status", "relogin_next_at"),
        # 列表/统计按生命周期状态筛选
        Index("ix_accounts_status", "status"),
    )

    assigned_user: Mapped[User | None] = relationship(
        "User", back_populates="assigned_accounts", foreign_keys=[assigned_to]
    )
    login_tasks: Mapped[list[LoginTask]] = relationship(
        "LoginTask", back_populates="account"
    )
    douyu_tasks: Mapped[list[DouyuTask]] = relationship(
        "DouyuTask", back_populates="account"
    )


class LoginTask(Base):
    """单次登录任务"""

    __tablename__ = "login_tasks"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_id: Mapped[str] = mapped_column(
        String(64), nullable=False, index=True
    )  # 批次ID
    account_id: Mapped[int] = mapped_column(ForeignKey("accounts.id"), nullable=False)
    status: Mapped[str] = mapped_column(
        String(32), default="pending"
    )  # pending / running / success / failed / error
    cookie: Mapped[str] = mapped_column(EncryptedText(), default="")
    message: Mapped[str] = mapped_column(String(512), default="")
    created_by: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    # Cookie 有效性检测结果（持久化，刷新不丢失）
    ck_check_status: Mapped[str] = mapped_column(
        String(16), default=""
    )  # valid / invalid / 空=未检测
    ck_check_result: Mapped[dict | None] = mapped_column(
        JSON, nullable=True
    )  # {fish_ball, nickname, level, message}
    ck_checked_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    # 最近一次登录尝试的状态。批次只写 attempt_*，只有登录成功才会把新 CK
    # 写回 status/cookie/message，因此停止、失败、进程重启都不会破坏已有 CK。
    attempt_status: Mapped[str] = mapped_column(
        String(32), default="", server_default=""
    )  # pending / running / success / failed / stopped / 空=没有进行过的尝试
    attempt_message: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    attempt_batch_id: Mapped[str] = mapped_column(
        String(64), default="", server_default=""
    )
    attempt_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    # 自动重登（P1b）用的退避状态。P1a 的巡检不碰这几个字段。
    relogin_attempts: Mapped[int] = mapped_column(
        Integer, default=0, server_default="0"
    )  # 连续重登尝试次数，成功即清零
    relogin_next_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    relogin_last_error: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    # 失败分型：captcha / credential 转人工，email_code / email_quota /
    # interrupted / network 自动重试（见规划 §7.4.3）。空 = 没失败过。
    relogin_failure_kind: Mapped[str] = mapped_column(
        String(16), default="", server_default=""
    )

    account: Mapped[Account] = relationship("Account", back_populates="login_tasks")


class DouyuTask(Base):
    """斗鱼业务任务"""

    __tablename__ = "douyu_tasks"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    account_id: Mapped[int] = mapped_column(ForeignKey("accounts.id"), nullable=False)
    task_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    # 任务归属工作台；避免同一账号的精英/电竞/小店任务在前端串行展示或串弹二维码。
    handbook_scope: Mapped[str] = mapped_column(
        String(16), nullable=False, default="legacy", index=True
    )
    # 供应商直充的来源订单号，用于轮询与异步回调的幂等关联。
    supplier_out_order_id: Mapped[str | None] = mapped_column(
        String(64), nullable=True, unique=True, index=True
    )
    status: Mapped[str] = mapped_column(String(32), default="pending")
    message: Mapped[str] = mapped_column(String(512), default="")
    result: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    created_by: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    # 账号归属客服冗余字段，配合复合索引消除任务列表全表 filesort。
    account_assigned_to: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )

    __table_args__ = (
        Index(
            "ix_douyu_tasks_account_assigned_to_id",
            "account_assigned_to",
            "id",
        ),
        Index(
            "ix_douyu_tasks_assigned_scope_id",
            "account_assigned_to",
            "handbook_scope",
            "id",
        ),
    )

    account: Mapped[Account] = relationship("Account", back_populates="douyu_tasks")


class DouyuWorkbenchAccount(Base):
    """用户在指定斗鱼工作台中启用的账号，跨浏览器同步。"""

    __tablename__ = "douyu_workbench_accounts"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    handbook_scope: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
    account_id: Mapped[int] = mapped_column(
        ForeignKey("accounts.id"), nullable=False, index=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)

    __table_args__ = (
        UniqueConstraint(
            "user_id", "handbook_scope", "account_id", name="uq_douyu_workbench_account"
        ),
    )


class DouyuWorkbench(Base):
    """工作台配置哨兵，令空账号集合也能跨浏览器同步。"""

    __tablename__ = "douyu_workbenches"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    handbook_scope: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    __table_args__ = (
        UniqueConstraint("user_id", "handbook_scope", name="uq_douyu_workbench"),
    )


class YybRechargeTask(Base):
    """应用宝和平精英点券充值任务。

    YYB 登录身份与斗鱼账号无关，因此任务只关联创建者，不复用 Account。
    """

    __tablename__ = "yyb_recharge_tasks"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    # 唯一索引（uq_yyb_recharge_tasks_task_id）已覆盖 task_id 查询，无需重复普通索引；
    # 迁移 20260812_0020 也只建唯一索引，二者保持一致。
    task_id: Mapped[str] = mapped_column(String(64), unique=True, nullable=False)
    created_by: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    worker_job_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    provider: Mapped[str] = mapped_column(String(16), default="", nullable=False)
    platform: Mapped[str] = mapped_column(String(16), default="android", nullable=False)
    points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    product_id: Mapped[str] = mapped_column(String(128), default="")
    zone_id: Mapped[str] = mapped_column(String(64), default="")
    zone_name: Mapped[str] = mapped_column(String(128), default="")
    role_id: Mapped[str] = mapped_column(String(64), default="")
    role_name: Mapped[str] = mapped_column(String(128), default="")
    price_fen: Mapped[int | None] = mapped_column(Integer, nullable=True)
    status: Mapped[str] = mapped_column(
        String(32), default="created", nullable=False, index=True
    )
    phase: Mapped[str] = mapped_column(String(32), default="login", nullable=False)
    message: Mapped[str] = mapped_column(String(512), default="")
    result: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    login_qr_data: Mapped[str] = mapped_column(EncryptedText(), default="")
    payment_qr_data: Mapped[str] = mapped_column(EncryptedText(), default="")
    payment_started_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    payment_qr_created_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    payment_last_checked_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)


class DouyuConfig(Base):
    """斗鱼业务配置"""

    __tablename__ = "douyu_config"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    manual_id: Mapped[str] = mapped_column(String(64), default="G4KA4Qnz4LDp7")
    rid: Mapped[str] = mapped_column(String(64), default="9263298")
    bind_act_alias: Mapped[str] = mapped_column(String(64), default="20260120QYOOB")
    confirm_act_alias: Mapped[str] = mapped_column(String(64), default="20260120QYOOB")
    legacy_act_alias: Mapped[str] = mapped_column(String(64), default="cjm")
    room_id: Mapped[str] = mapped_column(String(64), default="9263298")
    elite_amount: Mapped[int] = mapped_column(Integer, default=3000)
    esports_manual_id: Mapped[str] = mapped_column(String(64), default="1W0yGkOdDbAXb")
    esports_act_alias: Mapped[str] = mapped_column(String(64), default="20260226ZMGDG")
    esports_amount: Mapped[int] = mapped_column(Integer, default=3000)
    esports_chicken_gift_id: Mapped[str] = mapped_column(String(64), default="24766")
    esports_chicken_skin_id: Mapped[str] = mapped_column(String(64), default="0")
    esports_firework_gift_id: Mapped[str] = mapped_column(String(64), default="24767")
    esports_firework_skin_id: Mapped[str] = mapped_column(String(64), default="3850")
    # 和平小店总开关。**默认关** —— 小店目前是关闭状态，关着时一键查询
    # 完全跳过它的所有请求（不再产生 100% 的 Livelink 报错噪音）。
    peace_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
    xpd_act_alias: Mapped[str] = mapped_column(String(64), default="20260623KDQFH")
    xpd_act_id: Mapped[str] = mapped_column(String(64), default="46195")
    xpd_rid: Mapped[str] = mapped_column(String(64), default="9263298")
    gold_pay_type: Mapped[int] = mapped_column(Integer, default=1)
    gold_recharge_channel: Mapped[str] = mapped_column(String(16), default="wechat_qr")
    gold_api_product_id: Mapped[str] = mapped_column(String(128), default="111570")
    gold_api_account_template_name: Mapped[str] = mapped_column(
        String(64), default="斗鱼昵称"
    )
    gift_id: Mapped[str] = mapped_column(String(64), default="23643")
    skin_id: Mapped[str] = mapped_column(String(64), default="2942")
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class DouyuGoodsSnapshot(Base):
    """斗鱼兑换商品快照"""

    __tablename__ = "douyu_goods_snapshot"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    commodity_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    name: Mapped[str] = mapped_column(String(256), default="")
    score: Mapped[int | None] = mapped_column(Integer, nullable=True)
    status: Mapped[str] = mapped_column(String(32), default="")
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class DouyuXpdGoodsSnapshot(Base):
    """斗鱼和平小店商品快照"""

    __tablename__ = "douyu_xpd_goods_snapshot"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    commodity_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    name: Mapped[str] = mapped_column(String(256), default="")
    price: Mapped[int | None] = mapped_column(Integer, nullable=True)
    org_price: Mapped[int | None] = mapped_column(Integer, nullable=True)
    category: Mapped[str] = mapped_column(String(32), default="")
    goods_left: Mapped[int | None] = mapped_column(Integer, nullable=True)
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class DouyuEsportsGoodsSnapshot(Base):
    """斗鱼电竞手册皮肤商城商品快照"""

    __tablename__ = "douyu_esports_goods_snapshot"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    commodity_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    name: Mapped[str] = mapped_column(String(256), default="")
    score: Mapped[int | None] = mapped_column(Integer, nullable=True)
    status: Mapped[str] = mapped_column(String(32), default="")
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class DouyuCollabShop(Base):
    """斗鱼外部单协作的店铺字典（新建单时点选，历史文本自动登记）。"""

    __tablename__ = "douyu_collab_shops"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    sort_order: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    is_active: Mapped[bool] = mapped_column(
        Boolean, default=True, server_default="1", index=True
    )
    remark: Mapped[str] = mapped_column(String(255), default="", server_default="")
    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    updated_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class DouyuExternalOrder(Base):
    """斗鱼外部单协作台账（一行 = 一单 = 一个内部斗鱼账号）。

    和虎牙外部 CK 台账的关键区别：**不复制 CK**。协作单只存 ``account_id``
    （可空，账号删除后置空）与用户名/UID 快照，任何查询都实时读
    ``accounts.cookie``。账号 CK 更新后，协作单自动使用最新凭据。
    """

    __tablename__ = "douyu_external_orders"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    order_no: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    shop: Mapped[str] = mapped_column(
        String(64), default="", server_default="", index=True
    )
    owner_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )

    # ---- 内部斗鱼账号（CK 不落本表）----
    account_id: Mapped[int | None] = mapped_column(
        ForeignKey("accounts.id", ondelete="SET NULL"), nullable=True, index=True
    )
    account_username: Mapped[str] = mapped_column(
        String(128), default="", server_default="", index=True
    )
    account_uid: Mapped[str] = mapped_column(String(32), default="", server_default="")
    account_nickname: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )

    # ---- 绑定角色只读快照（来自 memberthird/tencent/bindInfo）----
    bind_game_account: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_game_role: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_game_channel: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_snapshot_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )

    # ---- 订单资料 ----
    home_images: Mapped[list | None] = mapped_column(JSON, nullable=True)
    gift_name: Mapped[str] = mapped_column(String(128), default="", server_default="")
    commodity_id: Mapped[str] = mapped_column(String(64), default="", server_default="")
    required_points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    remark: Mapped[str] = mapped_column(String(512), default="", server_default="")

    # ---- 业务进度 ----
    status: Mapped[str] = mapped_column(
        String(16), default="incomplete", server_default="incomplete", index=True
    )
    recharged_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    scripted_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    done_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    void_reason: Mapped[str] = mapped_column(String(256), default="", server_default="")

    # ---- 鱼翅 / 积分 / 核账快照 ----
    fish_fin_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_required_total: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_surplus: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_threshold: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_checked_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    points_check_reason: Mapped[str] = mapped_column(
        String(16), default="", server_default=""
    )
    points_check_message: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    points_check_detail: Mapped[dict | None] = mapped_column(JSON, nullable=True)

    # ---- 归档 ----
    archived_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True, index=True
    )
    archived_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    archive_reason: Mapped[str] = mapped_column(
        String(256), default="", server_default=""
    )

    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )
    updated_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    version: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow, index=True
    )


class DouyuExternalOrderMetric(Base):
    """斗鱼协作单的鱼翅/积分/兑换记录快照（只追加，不存 CK）。"""

    __tablename__ = "douyu_external_order_metrics"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    order_id: Mapped[int] = mapped_column(
        ForeignKey("douyu_external_orders.id", ondelete="CASCADE"), index=True
    )
    order_no: Mapped[str] = mapped_column(String(64), default="", server_default="")
    account_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    account_username: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    fish_fin_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_required_total: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_surplus: Mapped[int | None] = mapped_column(Integer, nullable=True)
    records_total: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    records_matched: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    verdict: Mapped[str] = mapped_column(
        String(16), default="unknown", server_default="unknown", index=True
    )
    message: Mapped[str] = mapped_column(String(512), default="", server_default="")
    source: Mapped[str] = mapped_column(
        String(16), default="manual", server_default="manual"
    )
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, index=True
    )


class LoginSmsCode(Base):
    """登录短信验证码。

    只存 sha256(code)，不存明文；一条记录只能消费一次，连续输错 5 次即作废。
    """

    __tablename__ = "login_sms_codes"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
    )
    phone: Mapped[str] = mapped_column(String(32), nullable=False, default="")
    purpose: Mapped[str] = mapped_column(
        String(16), nullable=False, default="login", server_default="login"
    )
    code_hash: Mapped[str] = mapped_column(String(64), nullable=False)
    expires_at: Mapped[datetime] = mapped_column(UTCDateTime, nullable=False)
    consumed_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    failed_attempt_count: Mapped[int] = mapped_column(
        Integer, nullable=False, default=0, server_default="0"
    )
    request_ip: Mapped[str] = mapped_column(
        String(64), nullable=False, default="", server_default=""
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)

    __table_args__ = (
        Index("ix_login_sms_codes_user_created", "user_id", "purpose", "created_at"),
        Index("ix_login_sms_codes_phone_created", "phone", "created_at"),
    )


class UserDevice(Base):
    """账号绑定的 DCAuth 设备（只存 deviceId 与 Ed25519 公钥）。

    MySQL 用函数索引 ``UNIQUE ((CASE WHEN status='active' THEN user_id END))``
    等价于 PostgreSQL 的部分唯一索引 ``UNIQUE (user_id) WHERE status='active'``。
    不用生成列，是因为 MySQL 不允许“生成列依赖的基列”上挂 ON DELETE CASCADE 外键。
    """

    __tablename__ = "user_devices"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id", ondelete="CASCADE"), nullable=False
    )
    device_id: Mapped[str] = mapped_column(String(96), nullable=False)
    public_key: Mapped[str] = mapped_column(String(128), nullable=False)
    client_version: Mapped[str] = mapped_column(
        String(32), nullable=False, default="", server_default=""
    )
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, default="active", server_default="active"
    )
    bound_at: Mapped[datetime] = mapped_column(UTCDateTime, nullable=False)
    last_used_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    revoked_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    revoked_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    __table_args__ = (
        Index(
            "uq_user_devices_active_user",
            text("(CASE WHEN status = 'active' THEN user_id ELSE NULL END)"),
            unique=True,
        ),
        Index("ix_user_devices_device_id", "device_id"),
    )


class DeviceChallenge(Base):
    """DCAuth challenge → authorized → ticket_issued → consumed 状态机。

    所有状态推进都带 ``status`` 与 ``expires_at`` 条件做原子 UPDATE，
    保证 challenge / ticket 只能被消费一次。
    """

    __tablename__ = "device_challenges"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    challenge_id: Mapped[str] = mapped_column(String(64), nullable=False)
    app: Mapped[str] = mapped_column(String(32), nullable=False)
    purpose: Mapped[str] = mapped_column(
        String(16), nullable=False, default="login", server_default="login"
    )
    challenge: Mapped[str] = mapped_column(String(128), nullable=False)
    poll_token_hash: Mapped[str] = mapped_column(String(64), nullable=False)
    status: Mapped[str] = mapped_column(
        String(16), nullable=False, default="pending", server_default="pending"
    )
    user_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id", ondelete="SET NULL"), nullable=True
    )
    device_id: Mapped[str] = mapped_column(
        String(96), nullable=False, default="", server_default=""
    )
    public_key: Mapped[str] = mapped_column(
        String(128), nullable=False, default="", server_default=""
    )
    client_version: Mapped[str] = mapped_column(
        String(32), nullable=False, default="", server_default=""
    )
    device_ticket_hash: Mapped[str] = mapped_column(
        String(64), nullable=False, default="", server_default=""
    )
    expires_at: Mapped[datetime] = mapped_column(UTCDateTime, nullable=False)
    authorized_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    ticket_issued_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    consumed_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    __table_args__ = (
        UniqueConstraint("challenge_id", name="uq_device_challenges_challenge_id"),
        Index("ix_device_challenges_expires", "expires_at"),
        Index("ix_device_challenges_user", "user_id", "created_at"),
    )


class HuyaAccount(Base):
    """虎牙账号"""

    __tablename__ = "huya_accounts"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    uid: Mapped[str] = mapped_column(String(32), default="", index=True)
    yyuid: Mapped[str] = mapped_column(String(32), default="", index=True)
    username: Mapped[str] = mapped_column(String(128), default="")
    account_password: Mapped[str] = mapped_column(EncryptedText(), default="")
    nickname: Mapped[str] = mapped_column(String(128), default="")
    cookie: Mapped[str] = mapped_column(EncryptedText(), nullable=False)
    # App 登录原始凭据（16 字段 udb_*，不含本地随机生成的网页设备字段）。
    # 网页运行 ck（cookie 列）含 guid/_qimei_uuid42 等设备快照，若被风控标记
    # 可从 raw_cookie 重建；也用于审计/复核登录有效性。
    raw_cookie: Mapped[str] = mapped_column(EncryptedText(), nullable=False, default="")
    tag: Mapped[str] = mapped_column(String(64), default="")
    remark: Mapped[str] = mapped_column(String(256), default="")
    status: Mapped[str] = mapped_column(String(32), default="imported")
    # 上次成功登录渠道: web=旧版Web协议 / app=App协议(推荐) / sms=短信; 空=仅导入Cookie
    login_channel: Mapped[str] = mapped_column(String(16), default="", index=True)
    points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    game_name: Mapped[str] = mapped_column(String(128), default="")
    game_channel: Mapped[str] = mapped_column(String(64), default="")
    game_phone: Mapped[str] = mapped_column(String(64), default="")
    # 精英宝典开通状态（积分中心 getRedeemNeedGoods 的 tag5；NULL = 还没查过）。
    # 光看积分区分不了「开通后花完」和「从没开通」，必须单独落库。
    elite_opened: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
    # 最近一次宝典订单的支付时间（Unix 秒；与斗鱼 elite_expire_time 同一约定）。
    elite_open_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # 宝典有效期（Unix 秒）：取积分中心页面配置里本赛季的结束时间（福利季 Q4 → 12-31）。
    elite_expire_time: Mapped[int | None] = mapped_column(Integer, nullable=True)
    sms_url: Mapped[str] = mapped_column(Text, default="")
    assigned_to: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    assigned_user: Mapped[User | None] = relationship(
        "User", back_populates="huya_accounts", foreign_keys=[assigned_to]
    )
    tasks: Mapped[list[HuyaTask]] = relationship("HuyaTask", back_populates="account")


class HuyaRegisterBatch(Base):
    """虎牙自动注册批次（持久化元数据）"""

    __tablename__ = "huya_register_batches"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_id: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    tag: Mapped[str] = mapped_column(String(64), default="")
    created_by: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    concurrency: Mapped[int] = mapped_column(Integer, default=1)
    wait_seconds: Mapped[int] = mapped_column(Integer, default=180)
    poll_interval: Mapped[int] = mapped_column(Integer, default=5)
    password_prefix: Mapped[str] = mapped_column(String(16), default="hy")
    fixed_password: Mapped[str] = mapped_column(EncryptedText(), default="")
    use_proxy: Mapped[bool] = mapped_column(Boolean, default=False)
    status: Mapped[str] = mapped_column(String(32), default="pending", index=True)
    message: Mapped[str] = mapped_column(String(512), default="")
    total: Mapped[int] = mapped_column(Integer, default=0)
    success_count: Mapped[int] = mapped_column(Integer, default=0)
    failed_count: Mapped[int] = mapped_column(Integer, default=0)
    stopped_count: Mapped[int] = mapped_column(Integer, default=0)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    started_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    items: Mapped[list[HuyaRegisterItem]] = relationship(
        "HuyaRegisterItem", back_populates="batch", cascade="all, delete-orphan"
    )


class HuyaRegisterItem(Base):
    """虎牙自动注册批次内单条手机号状态"""

    __tablename__ = "huya_register_items"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_db_id: Mapped[int] = mapped_column(
        Integer, ForeignKey("huya_register_batches.id"), nullable=False, index=True
    )
    batch_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    line: Mapped[int] = mapped_column(Integer, nullable=False)
    phone: Mapped[str] = mapped_column(String(64), default="", index=True)
    provider: Mapped[str] = mapped_column(String(32), default="")
    sms_url: Mapped[str] = mapped_column(Text, default="")
    status: Mapped[str] = mapped_column(String(32), default="pending", index=True)
    message: Mapped[str] = mapped_column(String(512), default="")
    code: Mapped[str] = mapped_column(String(32), default="")
    change_code: Mapped[str] = mapped_column(String(32), default="")
    attempts: Mapped[int] = mapped_column(Integer, default=0)
    change_attempts: Mapped[int] = mapped_column(Integer, default=0)
    account_id: Mapped[int | None] = mapped_column(
        ForeignKey("huya_accounts.id"), nullable=True
    )
    username: Mapped[str] = mapped_column(String(128), default="")
    uid: Mapped[str] = mapped_column(String(32), default="")
    password: Mapped[str] = mapped_column(EncryptedText(), default="")
    password_changed: Mapped[bool] = mapped_column(Boolean, default=False)
    cookie: Mapped[str] = mapped_column(EncryptedText(), default="")
    started_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    batch: Mapped[HuyaRegisterBatch] = relationship(
        "HuyaRegisterBatch", back_populates="items"
    )


class HuyaRegisterSuccessLog(Base):
    """虎牙自动注册成功流水（只追加，供随时导出）"""

    __tablename__ = "huya_register_success_logs"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_id: Mapped[str] = mapped_column(String(64), default="", index=True)
    item_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    account_id: Mapped[int | None] = mapped_column(
        ForeignKey("huya_accounts.id"), nullable=True
    )
    phone: Mapped[str] = mapped_column(String(64), default="", index=True)
    username: Mapped[str] = mapped_column(String(128), default="")
    uid: Mapped[str] = mapped_column(String(32), default="")
    password: Mapped[str] = mapped_column(EncryptedText(), default="")
    sms_url: Mapped[str] = mapped_column(Text, default="")
    tag: Mapped[str] = mapped_column(String(64), default="", index=True)
    provider: Mapped[str] = mapped_column(String(32), default="")
    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, index=True
    )


class HuyaTask(Base):
    """虎牙业务任务"""

    __tablename__ = "huya_tasks"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    batch_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    account_id: Mapped[int] = mapped_column(
        ForeignKey("huya_accounts.id"), nullable=False
    )
    task_type: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    # 任务归属工作台；legacy 保留旧虎牙任务，elite 隔离精英宝典任务。
    handbook_scope: Mapped[str] = mapped_column(
        String(16), nullable=False, default="legacy", index=True
    )
    status: Mapped[str] = mapped_column(String(32), default="pending")
    message: Mapped[str] = mapped_column(String(512), default="")
    result: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    created_by: Mapped[int] = mapped_column(ForeignKey("users.id"), nullable=False)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    account: Mapped[HuyaAccount] = relationship("HuyaAccount", back_populates="tasks")


class HuyaWorkbenchAccount(Base):
    """用户在虎牙指定工作台中启用的账号。"""

    __tablename__ = "huya_workbench_accounts"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    handbook_scope: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
    account_id: Mapped[int] = mapped_column(
        ForeignKey("huya_accounts.id"), nullable=False, index=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)

    __table_args__ = (
        UniqueConstraint(
            "user_id",
            "handbook_scope",
            "account_id",
            name="uq_huya_workbench_account",
        ),
    )


class HuyaWorkbench(Base):
    """工作台配置哨兵，令空账号集合也能跨浏览器同步。"""

    __tablename__ = "huya_workbenches"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int] = mapped_column(
        ForeignKey("users.id"), nullable=False, index=True
    )
    handbook_scope: Mapped[str] = mapped_column(String(16), nullable=False, index=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )

    __table_args__ = (
        UniqueConstraint("user_id", "handbook_scope", name="uq_huya_workbench"),
    )


class HuyaConfig(Base):
    """虎牙业务配置"""

    __tablename__ = "huya_config"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    room_pid: Mapped[str] = mapped_column(String(64), default=HUYA_DEFAULT_ROOM_PID)
    sid: Mapped[str] = mapped_column(String(32), default=HUYA_DEFAULT_SID)
    outer_act_id: Mapped[str] = mapped_column(
        String(32), default=HUYA_DEFAULT_OUTER_ACT_ID
    )
    bind_act_id: Mapped[str] = mapped_column(
        String(32), default=HUYA_DEFAULT_BIND_ACT_ID
    )
    pay_channel: Mapped[str] = mapped_column(
        String(16), default=HUYA_DEFAULT_PAY_CHANNEL
    )
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class HuyaGoodsSnapshot(Base):
    """虎牙兑换商品快照"""

    __tablename__ = "huya_goods_snapshot"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    account_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    sid: Mapped[int] = mapped_column(Integer, default=0, index=True)
    product_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    name: Mapped[str] = mapped_column(String(256), default="")
    price: Mapped[int | None] = mapped_column(Integer, nullable=True)
    remain_text: Mapped[str] = mapped_column(String(64), default="")
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class HuyaRechargeGoodsSnapshot(Base):
    """虎牙充值商品快照"""

    __tablename__ = "huya_recharge_goods_snapshot"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    account_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    sid: Mapped[int] = mapped_column(Integer, default=0, index=True)
    spu_id: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    sku_id: Mapped[str] = mapped_column(String(64), default="", index=True)
    name: Mapped[str] = mapped_column(String(256), default="")
    price: Mapped[int | None] = mapped_column(Integer, nullable=True)
    stock: Mapped[int | None] = mapped_column(Integer, nullable=True)
    buy_limit: Mapped[int | None] = mapped_column(Integer, nullable=True)
    icon: Mapped[str] = mapped_column(String(512), default="")
    description: Mapped[str] = mapped_column(String(512), default="")
    task_id: Mapped[str] = mapped_column(String(64), default="")
    task_name: Mapped[str] = mapped_column(String(256), default="")
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class ProxyConfig(Base):
    """代理配置（全局单条记录）"""

    __tablename__ = "proxy_config"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    enabled: Mapped[bool] = mapped_column(Boolean, default=False)
    api_url: Mapped[str] = mapped_column(EncryptedText(), default="")
    http: Mapped[str] = mapped_column(EncryptedText(), default="")
    https: Mapped[str] = mapped_column(EncryptedText(), default="")
    # 白名单
    whitelist_enabled: Mapped[bool] = mapped_column(Boolean, default=False)
    whitelist_platform: Mapped[str] = mapped_column(String(32), default="xiequ")
    whitelist_credentials: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    # 旧字段保留（向后兼容双写）
    whitelist_uid: Mapped[str] = mapped_column(EncryptedText(), default="")
    whitelist_ukey: Mapped[str] = mapped_column(EncryptedText(), default="")


class AuditLog(Base):
    """操作审计日志"""

    __tablename__ = "audit_logs"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    user_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    username: Mapped[str] = mapped_column(String(64), default="")
    action: Mapped[str] = mapped_column(String(128), nullable=False)
    target: Mapped[str] = mapped_column(String(256), default="")
    detail: Mapped[str] = mapped_column(Text, default="")
    # 账号相关操作用它关联到具体账号（旧记录为 NULL）。
    # target 是自由文本（用户名/批次号/整句话），不能可靠反查账号，所以单独存 id。
    account_id: Mapped[int | None] = mapped_column(Integer, nullable=True, index=True)
    # 旧记录未标记结果时为 NULL，避免把历史操作误判成失败。
    success: Mapped[bool | None] = mapped_column(Boolean, nullable=True, index=True)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)


class AccountEvent(Base):
    """账号事件流（append-only）。

    `accounts` 存**当前状态**，这张表存**发生过什么** —— 账号详情页的时间线就读它。
    状态字段都是覆盖式更新（积分、余额、开通标记），事件表补上「什么时候变成这样」。

    设计约定：
    - `occurred_at` 是**业务发生时间**（不是入库时间）；
    - `amount` 有符号（充值为正、兑换消耗为负），便于页面直接算累计；
    - `source_ref` 是幂等键，可空且唯一：收集器重跑、事件重复发射都靠它兜住；
    - `detail` 只存精简字段，不放原始大 JSON（那是 douyu_tasks 的包袱）。

    除了「时间线」，它还承担**业务台账**（开通 / 积分 / 兑换 / 充值记录）——
    查询靠 `(account_id, event_type, subject_key, occurred_at)` 复合索引，
    所以**有流程的东西才另建表**（如兑换工单），「事实」一律进这里。
    """

    __tablename__ = "account_events"

    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=True)
    # 不单独建 account_id 索引：迁移建的是 (account_id, occurred_at) 复合索引，
    # 前缀已覆盖按账号查，再单建一个纯属冗余。
    account_id: Mapped[int] = mapped_column(ForeignKey("accounts.id"), nullable=False)
    event_type: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
    # 粗分类：lifecycle（状态变迁）/ auth（登录与 CK）/ business（业务）/ ops（人工）
    category: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )
    occurred_at: Mapped[datetime] = mapped_column(UTCDateTime, nullable=False)
    title: Mapped[str] = mapped_column(String(256), default="", server_default="")
    amount: Mapped[int | None] = mapped_column(Integer, nullable=True)
    balance_after: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # 台账检索键：subject_type = commodity / skin / order / role，
    # subject_key = 斗鱼 commodity_id / 归一后的 skin_key / 订单号。
    # 只放**需要检索**的键，其余细节进 detail —— 别把这里变成第二个 detail。
    subject_type: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )
    subject_key: Mapped[str] = mapped_column(
        String(96), nullable=False, default="", server_default=""
    )
    detail: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    source: Mapped[str] = mapped_column(String(24), default="", server_default="")
    # 谁触发的：user / system / public（收集链接）
    actor_type: Mapped[str] = mapped_column(
        String(16), nullable=False, default="", server_default=""
    )
    actor_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # 幂等键：可空且唯一（MySQL 允许多个 NULL，便于「没有幂等键」的事件共存）
    source_ref: Mapped[str | None] = mapped_column(
        String(96), nullable=True, index=True, unique=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)

    __table_args__ = (
        # 台账查询：「该账号该事件类型该客体最近一次」——365 天同皮肤规则靠它。
        # 跨账号反查（「这件皮肤被谁兑过」）吃 event_type + subject_key 前缀。
        Index(
            "ix_account_events_ledger",
            "account_id",
            "event_type",
            "subject_key",
            "occurred_at",
        ),
    )


class AutomationJob(Base):
    """自动化作业定义。状态落库，进程重启不丢调度进度。"""

    __tablename__ = "automation_jobs"

    key: Mapped[str] = mapped_column(String(64), primary_key=True)
    title: Mapped[str] = mapped_column(String(128), default="")
    # 默认关闭：按「渐进上线」原则，先观察再打开。
    enabled: Mapped[bool] = mapped_column(Boolean, default=False, server_default="0")
    # **多久跑一次**（秒）。这是调度频率，与"同一行多久重检"是两回事。
    # 以前调度频率是**硬编码**的 JOB_INTERVAL_SECONDS（5 分钟），
    # UI 上那个"单账号重检间隔"其实是 `interval_seconds` ——
    # 两个概念挤在一个输入框里，很别扭（用户指出）。
    run_interval_seconds: Mapped[int] = mapped_column(
        Integer, default=300, server_default="300"
    )
    # 同一**行**（账号）多久重检一次（秒）—— 由作业自己的选行逻辑使用，
    # **不参与调度**。别和上面那个混。
    interval_seconds: Mapped[int] = mapped_column(
        Integer, default=21600, server_default="21600"
    )
    batch_size: Mapped[int] = mapped_column(Integer, default=200, server_default="200")
    concurrency: Mapped[int] = mapped_column(Integer, default=5, server_default="5")
    config: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    last_run_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    next_run_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    last_status: Mapped[str] = mapped_column(String(16), default="", server_default="")
    last_message: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class AutomationRun(Base):
    """自动化作业每一轮的执行记录，用于页面展示与排障。"""

    __tablename__ = "automation_runs"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    job_key: Mapped[str] = mapped_column(String(64), nullable=False, index=True)
    started_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    finished_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    status: Mapped[str] = mapped_column(
        String(16), default="running", server_default="running"
    )  # running / success / failed / skipped
    scanned: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    valid: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    invalid: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    relogin_started: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    relogin_success: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    skipped: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    message: Mapped[str] = mapped_column(String(512), default="", server_default="")
    detail: Mapped[dict | None] = mapped_column(JSON, nullable=True)


class ExternalOrderCache(Base):
    """order_site 订单快照（P0 适配层的本地缓存）。

    主键是 (platform_order_id, source_order_id) 两列：同一个订单号在 order_site
    里可能有两行（发货方内部行 + 真实店铺行，实测 541 组，见规划 §6.5.1），
    按订单号单列存会互相覆盖。

    只作快照与降级用，24 小时后重查；不参与任何写业务。
    """

    __tablename__ = "external_order_cache"

    platform_order_id: Mapped[str] = mapped_column(
        String(64), primary_key=True, index=True
    )
    source_order_id: Mapped[str] = mapped_column(String(64), primary_key=True)
    platform: Mapped[str] = mapped_column(String(32), default="", server_default="")
    provider: Mapped[str] = mapped_column(String(32), default="", server_default="")
    shop_id: Mapped[str] = mapped_column(String(64), default="", server_default="")
    order_status: Mapped[str] = mapped_column(String(32), default="", server_default="")
    sku_code: Mapped[str] = mapped_column(String(128), default="", server_default="")
    sku_name: Mapped[str] = mapped_column(String(512), default="", server_default="")
    seller_id: Mapped[str] = mapped_column(String(64), default="", server_default="")
    rel_item_id: Mapped[str] = mapped_column(String(64), default="", server_default="")
    rel_sku_id: Mapped[str] = mapped_column(String(64), default="", server_default="")
    sku_nick: Mapped[str] = mapped_column(String(512), default="", server_default="")
    item_title: Mapped[str] = mapped_column(String(512), default="", server_default="")
    quantity: Mapped[int | None] = mapped_column(Integer, nullable=True)
    route: Mapped[str] = mapped_column(String(32), default="", server_default="")
    payload: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    fetched_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, index=True
    )


class FileAsset(Base):
    """上传文件台账（对齐 order_site 的 ``file_assets``）。

    对象本体在对象存储里（内网 OSS），库中只留 key 与元数据 —— 图片一律经
    ``/api/files/object?key=...`` 由后端代理回读，不下发 OSS 直链、也不存签名 URL
    （签名链接会在入库时被原样存下来，过期后到处裂图）。

    变体 key 为空表示缩略图生成失败，回读接口会自动回退原图。
    """

    __tablename__ = "file_assets"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    object_key: Mapped[str] = mapped_column(
        String(512), unique=True, nullable=False, index=True
    )
    scene: Mapped[str] = mapped_column(
        String(32), default="misc", server_default="misc", index=True
    )
    original_filename: Mapped[str] = mapped_column(
        String(255), default="", server_default=""
    )
    content_type: Mapped[str] = mapped_column(String(64), default="", server_default="")
    size_bytes: Mapped[int] = mapped_column(BigInteger, default=0, server_default="0")
    thumbnail_object_key: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    medium_object_key: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    uploader_type: Mapped[str] = mapped_column(
        String(32), default="user", server_default="user"
    )
    uploader_id: Mapped[str] = mapped_column(
        String(64), default="", server_default="", index=True
    )
    status: Mapped[str] = mapped_column(
        String(16), default="active", server_default="active"
    )
    metadata_json: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class HuyaCollabShop(Base):
    """协作台账的**店铺字典**（新建协作单时点一下选，不用手打）。

    几个取舍，改之前先看：

    1. **订单里存的是店铺名字符串，不是 id**（`huya_external_orders.shop`）——
       历史 Excel 数据就是文本，改成外键要动所有读写与导入。代价：改名要么级联
       （`update_shop(..., rename_orders=True)`，默认开），要么只影响以后的单子；
    2. **订单里出现过的店铺名会自动登记**（新建/编辑/粘贴导入都走
       `ensure_shops_registered`），所以字典永远覆盖已有数据，筛选下拉不会漏；
    3. **停用（`is_active=0`）≠ 删除**：只是不再出现在新建的选择里，历史订单与筛选照旧；
    4. **不加乐观锁 version**：字典是十几行的低频维度，改名冲突靠审计看，不值得为它
       再加一套版本号（台账订单行才需要，见 `HuyaExternalOrder`）。
    """

    __tablename__ = "huya_collab_shops"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    name: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    # 越小越靠前（新建下拉、筛选下拉都按它排）。
    sort_order: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    is_active: Mapped[bool] = mapped_column(
        Boolean, default=True, server_default="1", index=True
    )
    remark: Mapped[str] = mapped_column(String(255), default="", server_default="")
    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    updated_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow
    )


class HuyaExternalOrder(Base):
    """虎牙外部 CK 协作台账（替代 Excel 多人协同表）。

    **一行 = 一单 = 一个外部 CK**，设计见 ``docs/设计-虎牙外部CK协作台账.md``。

    两条边界（改动前先读设计文档 §2.3，别当成 bug 修）：

    1. **CK 独立存本表，刻意不写 ``huya_accounts``、不做外键**。同一个虎牙号可能同时
       存在于两处、各自过期，这是已知代价；本表的 CK 只在「协作单」语境里有效，
       需要拿去跑任务时人工到工作台重新导入，不自动同步。
    2. **不接任务执行器**：绑定/充值/上脚本都在别的工具里做，本表只记录结果。
       「一键送进工作台」是以后显式加的新动作。

    两套状态各管一摊，不要混：``status`` 是业务进度（一单卡在哪一步），
    ``ck_status`` 是凭据本身有没有失效。CK 失效**不会**自动改业务状态。
    """

    __tablename__ = "huya_external_orders"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    # Excel B 列：订单编号，台账内唯一（重复导入按「更新」处理）。
    order_no: Mapped[str] = mapped_column(
        String(64), unique=True, nullable=False, index=True
    )
    # Excel A 列：店铺。
    shop: Mapped[str] = mapped_column(
        String(64), default="", server_default="", index=True
    )
    # Excel C 列：负责人（共享表里只是筛选维度，不是权限边界）。
    owner_id: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )

    # ---- 外部 CK 本体（独立于 huya_accounts）----
    # uid 可空、**不再唯一**（2026-10-16 用户拍板）：同一个买家买两件常常继续用同一份 CK，
    # 唯一索引会让第二单直接插不进去（迁移 0058 把唯一索引降成普通索引）。
    # 「这个虎牙号还挂在哪些单上」只作为提示与审计信息，不做约束（见设计文档 §5.6）。
    uid: Mapped[str | None] = mapped_column(String(32), nullable=True, index=True)
    yyuid: Mapped[str] = mapped_column(String(32), default="", server_default="")
    hy_username: Mapped[str] = mapped_column(String(128), default="", server_default="")
    nickname: Mapped[str] = mapped_column(String(128), default="", server_default="")
    cookie: Mapped[str] = mapped_column(EncryptedText(), nullable=False, default="")
    # App 原始凭据：网页运行 CK 被风控标记时可由它重建（见 rebuild_web_cookie_from_raw）。
    raw_cookie: Mapped[str] = mapped_column(EncryptedText(), nullable=False, default="")
    ck_status: Mapped[str] = mapped_column(
        String(16), default="unverified", server_default="unverified", index=True
    )
    ck_checked_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    ck_check_message: Mapped[str] = mapped_column(
        String(256), default="", server_default=""
    )

    # ---- Excel D 列：绑定斗鱼号 ----
    bind_douyu_account: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_douyu_uid: Mapped[str] = mapped_column(
        String(32), default="", server_default=""
    )

    # ---- 探针读到的绑定对象（游戏账号 / 角色，**只读快照**）----
    # 2026-10-16 真机确认：`check_user_bind_game_account` 返回的是**绑定在该虎牙号上的
    # 游戏账号**（账号昵称 / 角色名 / 平台·区服）。「这单绑了哪个号、哪个角色」只有这里
    # 可信 —— 上面那个 `bind_douyu_account` 是人工填的自由文本，Excel 粘贴导入还在用它。
    # 四个列**由探针独占**：每次验证覆盖写入，读的时间看 `bind_snapshot_at`；人工不编辑。
    bind_game_account: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_game_role: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_game_channel: Mapped[str] = mapped_column(
        String(128), default="", server_default=""
    )
    bind_snapshot_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )

    # ---- Excel E/F 列：两张截图（存 OSS object_key，不存 URL —— URL 可推导，
    # 存 URL 会在换存储时全部失效）。数组，第一张作封面。
    bind_images: Mapped[list | None] = mapped_column(JSON, nullable=True)
    home_images: Mapped[list | None] = mapped_column(JSON, nullable=True)

    # ---- Excel G 列（表头写的「备注」，实际是礼包名）+ 自由备注 ----
    gift_name: Mapped[str] = mapped_column(String(128), default="", server_default="")
    # 购买该礼包所需积分快照（来自积分中心 queryAllocation 的 tag75.tag0.tag2）。
    # 积分会随活动/商品变化，必须在下单时存一份，不能每次按礼包名现查。
    required_points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    remark: Mapped[str] = mapped_column(String(512), default="", server_default="")

    # ---- 业务进度 ----
    status: Mapped[str] = mapped_column(
        String(16), default="incomplete", server_default="incomplete", index=True
    )
    bound_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    recharged_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    scripted_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    done_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)
    void_reason: Mapped[str] = mapped_column(String(256), default="", server_default="")

    # ---- 充值核账快照（按 bind_game_account 整组计算）----
    points_checked_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True
    )
    points_balance: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_required_total: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_surplus: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_threshold: Mapped[int | None] = mapped_column(Integer, nullable=True)
    points_check_reason: Mapped[str] = mapped_column(
        String(16), default="", server_default=""
    )
    points_check_message: Mapped[str] = mapped_column(
        String(512), default="", server_default=""
    )
    # 组内订单、各 CK 余额、缺口/多余等明细（JSON，只做展示与审计）
    points_check_detail: Mapped[dict | None] = mapped_column(JSON, nullable=True)

    # ---- 归档（与业务状态正交：归档后仍是「抢购成功」，只是默认不出现在主台账）----
    # NULL = 未归档；软隐藏不删数据，取消归档即可恢复。
    archived_at: Mapped[datetime | None] = mapped_column(
        UTCDateTime, nullable=True, index=True
    )
    archived_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    archive_reason: Mapped[str] = mapped_column(
        String(256), default="", server_default=""
    )

    # ---- 只读查询快照（不写 huya_accounts）----
    points: Mapped[int | None] = mapped_column(Integer, nullable=True)
    elite_opened: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
    snapshot_at: Mapped[datetime | None] = mapped_column(UTCDateTime, nullable=True)

    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True, index=True
    )
    # 最后修改人：协作表上要能一眼看出「这行刚被谁动过」。
    updated_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    # 乐观锁版本号：每次写入 +1。
    # **刻意不用 updated_at 当锁**：本项目的 UTCDateTime 落库是 MySQL DATETIME
    # （秒级精度），同一秒内的两次改动会得到完全相同的 updated_at，
    # 锁就形同虚设 —— Excel 那种「后保存的覆盖前一个」会原样复活。
    version: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    created_at: Mapped[datetime] = mapped_column(UTCDateTime, default=_utcnow)
    # 显示用（列表默认排序键）；并发保护靠上面的 version。
    updated_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, onupdate=_utcnow, index=True
    )


class HuyaExternalOrderMetric(Base):
    """虎牙外部订单的**账号全生命周期**快照：每查一次积分/兑换记录写一条。

    2026-10-16 用户需求：抢购完成后查兑换记录与积分，**每次积分变化都要落一条**，
    这样才能靠"兑换记录 + 积分变化"判断到底兑换成功没有。

    设计取舍：

    1. **只追加、不更新、不删除**（快照语义）：历史要能回放，改一行就等于毁证；
    2. **不存凭据**：`raw` 只放积分响应与兑换记录明细（里面没有 cookie），
       凭据永远只待在 `huya_external_orders.cookie`；
    3. `verdict`：`success`（兑换记录里有这一单的礼包）/ `failed`（接口通了但没记录）/
       `unknown`（查了兑换记录，但接口没通或没可比的礼包名）/**空串**（本次根本没查兑换记录，
       2026-10-17 拆出「只查积分」入口后才有），**只有 success / failed 会去改业务状态**；
       `raw.scope` 记着这条快照查了哪一半（`both` / `score` / `records`），前端据此取舍。
    4. 订单删掉时这条也跟着删（`ondelete="CASCADE"`）—— 它没有独立价值。
    """

    __tablename__ = "huya_external_order_metrics"

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    order_id: Mapped[int] = mapped_column(
        ForeignKey("huya_external_orders.id", ondelete="CASCADE"), index=True
    )
    # 冗余一份单号与 uid：订单被改单号后，历史快照仍然说得清"当时查的是谁"。
    order_no: Mapped[str] = mapped_column(String(64), default="", server_default="")
    uid: Mapped[str] = mapped_column(
        String(32), default="", server_default="", index=True
    )
    sid: Mapped[int | None] = mapped_column(Integer, nullable=True)
    # 积分快照（可用积分 / 累计获得 / 已消耗）—— 变化靠相邻两条相减就能看出来
    score: Mapped[int | None] = mapped_column(Integer, nullable=True)
    gained_score: Mapped[int | None] = mapped_column(Integer, nullable=True)
    used_score: Mapped[int | None] = mapped_column(Integer, nullable=True)
    records_total: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    records_matched: Mapped[int] = mapped_column(Integer, default=0, server_default="0")
    # success / failed / unknown（见类文档）＋ 一句人话结论
    verdict: Mapped[str] = mapped_column(
        String(16), default="unknown", server_default="unknown", index=True
    )
    message: Mapped[str] = mapped_column(String(512), default="", server_default="")
    # manual（人工点）/ batch（勾选批量）：出问题时能分清是谁按的
    source: Mapped[str] = mapped_column(
        String(16), default="manual", server_default="manual"
    )
    # 接口原始内容（积分响应 + 兑换记录明细；**不含凭据**）
    raw: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    created_by: Mapped[int | None] = mapped_column(
        ForeignKey("users.id"), nullable=True
    )
    created_at: Mapped[datetime] = mapped_column(
        UTCDateTime, default=_utcnow, index=True
    )