feat(huya): 协作台账状态机新口径（跳步/已确认绑定/兑换失败）+ 账号全生命周期快照（迁移 0059）

2026-10-16 22:00:34 +08:00
parent aac264b639
commit e8abd60734
11 changed files with 1897 additions and 84 deletions
@@ -1191,3 +1191,56 @@ class HuyaExternalOrder(Base):
    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`（接口没通或没可比的礼包名），**只有 success / failed 会去改业务状态**；
+    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
+    )