feat(account): 兑换记录列 + 修掉 source_ref NOT NULL 导致的事件静默丢失

三件事合成一次提交（按反馈不再一改一提交）。 ## ① 账号列表加「兑换记录」列次数 + 最近一次（商品名 + 日期），填上列表右侧的空档。数据源是**账号自己的事件流**（`account_events` 的 `exchange`），不是 `douyu_tasks` 的 JSON —— 后者是执行日志，S5 起业务事实已经在事件里了。性能上刻意**每页只跑两条聚合查询**（不是每行一条 N+1）：一条分组算 `count` + `max(occurred_at)`（走 `(account_id, event_type, occurred_at)` 复合索引），一条用窗口函数 `ROW_NUMBER()` 取每个账号最新那条的商品名。实测 6 个账号 3 条兑换事件，聚合与「最近」都正确。「兑换」前缀在前端剥掉（列头已经叫「兑换记录」，再带前缀是重复）。 ## ② 修掉一个静默丢事件的 bug（排查中发现的） **现象**：开发库上「状态变迁 / 分配 / 标签 / 备注 / CK 清除」这些事件**一条都没有**，而带幂等键的事件（业务事实、`ck_invalid`、`relogin_*`）照常写入 —— 时间线看起来有数据，只是恰好缺了某一类，**极难发现**。 **根因**：`source_ref` 是**可选**幂等键（模型与迁移文件都是 `nullable=True`， `emit()` 对没有天然幂等键的事件就传 `None`）。但早期那版迁移（重编号成 `0041` 之前的 `0040`）建的是 **NOT NULL**，而我后来只改了 **迁移文件**、没管**已建好的库** —— Alembic 只记版本号，不会重放已应用的脚本。 `__pycache__` 里那个 `20261002_0040_*.pyc` 就是旧版留下的痕迹。 **为什么静默**：`emit()` 按设计吞掉任何异常（事件是旁路，不能影响主流程），只记一条 warning，调用方也从不检查返回值。已实测复现： `emit(...)` 返回 `False` + warning，实际落库 `0` 条。 **修法**：迁移 `20261004_0045` 改回可空（`MODIFY`，**唯一索引保留**，幂等，生产若跑过旧版也一并修好）。修复后实测：`emit` 返回 `True`、落库 1 条。 ## ③ 补一条能防「未来」同类问题的守卫 `tests/test_migrations.py` 原本只比对「表/列/索引在不在」，**不比对可空性**。已加：迁移建出的列**不允许比模型更严**（模型说可空、库里 NOT NULL）。只查这个**危险方向**：反方向（模型 NOT NULL、库里允许 NULL）是无害的宽松，历史遗留里有 28 处，一并报出来只会制造噪声、逼人修没收益的东西。 > 这条守卫**有边界**，已在代码注释与设计文档 §3.5.1 写明： > 它在**全新库**上跑整链，只能防「未来的迁移建错」，**防不了已有库的历史漂移**。 > 已验证：临时禁用 `0045`，该用例仍通过（全新链本来就是对的）。 ## 验证 - `TZ=Asia/Shanghai`：**503 passed / 6 skipped**（+3 条兑换列用例） - `TZ=UTC`（迁移 + 列表相关）45 passed；ruff 全绿；前端 build 通过、lint 0 errors - 真实开发库：迁移已应用（head `20261004_0045`）， `source_ref` 现在 `IS_NULLABLE=YES` 且唯一索引仍在；不带幂等键的事件确实能落库；兑换聚合返回值正确注：验证时在开发库那个有 CK 的账号上留了 3 条 `exchange` 演示事件（兔兔白日梦 / 冠军鸡腿 / 烟花），是为了让列有数据可看，随时可删。
2026-10-04 17:25:40 +08:00
parent d3f5198227
commit 5ae5d92978
8 changed files with 283 additions and 2 deletions
@@ -854,3 +854,93 @@ class TestSummaryByStatus(_Base):
        summary = self._summary()
        assert summary["ck_invalid_count"] >= 1
        assert summary["no_cookie_count"] >= 1
+
+
+class TestExchangeRecordColumn(_Base):
+    """「兑换记录」列：次数 + 最近一次（商品名 + 时间）。
+
+    数据源是**账号自己的事件流**（`account_events.exchange`），不是 `douyu_tasks`
+    的 JSON —— 后者是执行日志，S5 起业务事实已经在事件里了。
+    """
+
+    def _items(self, **kwargs):
+        from web.backend.routers.accounts import list_accounts
+
+        return list_accounts(
+            assigned_only=False,
+            tag="",
+            has_cookie=False,
+            search="",
+            page=1,
+            page_size=50,
+            include_sensitive=False,
+            status=kwargs.get("status", ""),
+            ck_status="",
+            bind_status="",
+            db=self.session,
+            current=self.user,
+        )["items"]
+
+    def _item(self, username: str):
+        for item in self._items():
+            if item.username == username:
+                return item
+        raise AssertionError(f"列表里没有 {username}")
+
+    def _exchange(self, account_id: int, name: str, *, days_ago: int = 0):
+        from datetime import timedelta
+
+        from web.backend.services.account_events_service import emit
+
+        emit(
+            self.session,
+            account_id=account_id,
+            event_type="exchange",
+            title=f"兑换 {name}",
+            category="business",
+            subject_key=name,
+            occurred_at=NOW - timedelta(days=days_ago),
+        )
+        self.session.commit()
+
+    def test_no_exchange_yields_zero(self):
+        self.make_account("noex")
+        item = self._item("noex")
+        assert item.exchange_count == 0
+        assert item.last_exchange_at is None
+        assert item.last_exchange_name == ""
+
+    def test_counts_and_keeps_latest_name(self):
+        account = self.make_account("hasex")
+        self._exchange(account.id, "兔兔白日梦", days_ago=3)
+        self._exchange(account.id, "冠军鸡腿", days_ago=1)
+        self._exchange(account.id, "烟花", days_ago=2)
+
+        item = self._item("hasex")
+        assert item.exchange_count == 3
+        # 「最近」按**事件 id** 取（同一天多次兑换时时间戳可能相同，靠 id 定序）
+        # 后端返回事件原始 title；剥掉「兑换 」前缀是前端展示层的事。
+        assert item.last_exchange_name == "兑换 烟花"
+
+    def test_only_exchange_events_count(self):
+        """别的类型（充值 / 登录 / 状态）不能混进兑换次数。"""
+        from web.backend.services.account_events_service import emit
+
+        account = self.make_account("mixed")
+        emit(
+            self.session,
+            account_id=account.id,
+            event_type="recharge",
+            title="充值 100",
+            category="business",
+            amount=100,
+        )
+        emit(
+            self.session,
+            account_id=account.id,
+            event_type="status_changed",
+            title="状态：未登录 → 正常",
+            category="lifecycle",
+        )
+        self.session.commit()
+        assert self._item("mixed").exchange_count == 0
@@ -26,7 +26,7 @@ TESTS_DIR = Path(__file__).resolve().parent
 PROJECT_ROOT = TESTS_DIR.parent
 VERSIONS_DIR = PROJECT_ROOT / "web" / "backend" / "migrations" / "versions"

-HEAD_REVISION = "20261004_0044"
+HEAD_REVISION = "20261004_0045"

 # 迁移新增、但不声明在模型里的复合查询索引。
 EXTRA_INDEXES = (
@@ -105,12 +105,32 @@ class TestMigrationSmoke:
            assert not missing_tables

            all_db_indexes = set()
+            nullability_mismatches: list[str] = []
            for name, table in model_tables.items():
-                db_columns = {column["name"] for column in inspector.get_columns(name)}
+                db_cols = inspector.get_columns(name)
+                db_columns = {column["name"] for column in db_cols}
                model_columns = set(table.columns.keys())
                missing_columns = model_columns - db_columns
                assert not missing_columns

+                # 可空性只查**危险的那个方向**：模型说可空、库里却是 NOT NULL。
+                # 那样带 NULL 的写入会**在运行时静默失败**（`emit()` 按设计吞异常），
+                # 正是 `account_events.source_ref` 那次事故的形态 ——
+                # 只比对「列在不在」是抓不到的。
+                #
+                # 反方向（模型 NOT NULL、库里允许 NULL）是**无害的宽松**：
+                # SQLAlchemy 总会写值，库里宽松一点不会丢数据。历史遗留里有不少，
+                # 一并报出来只会制造噪声、逼人去修没有收益的东西。
+                db_nullable = {c["name"]: c["nullable"] for c in db_cols}
+                for column in table.columns:
+                    if column.name not in db_nullable:
+                        continue
+                    if bool(column.nullable) and not bool(db_nullable[column.name]):
+                        nullability_mismatches.append(
+                            f"{name}.{column.name}: 模型说可空，"
+                            f"但迁移建成了 NOT NULL（带 NULL 的写入会静默丢失）"
+                        )
+
                db_indexes = set()
                for index in inspector.get_indexes(name):
                    index_name = index["name"]
@@ -121,6 +141,11 @@ class TestMigrationSmoke:
                missing_indexes = model_indexes - db_indexes
                assert not missing_indexes

+            assert not nullability_mismatches, (
+                "迁移建出的列比模型更严（会在运行期静默丢数据）：\n"
+                + "\n".join(nullability_mismatches)
+            )
+
            # 迁移新增的复合查询索引（不入模型，但应存在）。
            for index_name in EXTRA_INDEXES:
                assert index_name in all_db_indexes, f"迁移链未创建索引 {index_name}"