feat(account): S5 业务事实直发事件 + 删掉收集器 + 任务日志保留策略
时间线从此覆盖**全部**业务事实,`douyu_tasks` 也有了可控的增长边界。
## 一、删掉收集器(它必然漏数据)
`jobs/account_events_collect.py` 连同 `_task_to_event` / `COLLECTED_TASK_TYPES` /
水位线一起删除,迁移 `20261004_0043` 清掉它的作业行。删除理由是实测出来的:
- **靠 allowlist 认业务类型,新增类型就静默丢**:原有名单只有 5 个,
而 `exchange_esports_goods`(电竞兑换)、`exchange_xpd_goods`(和平小店兑换)、
`pay_locked_order`(锁单支付)、`donate_esports_*`(电竞礼物积分)**从来没进过时间线**;
- **「任务 success」≠「业务真的发生了」**(见下);
- **字段路径靠抽样猜**:二维码充值的 `result` 里根本没有金额,收集器恒写
`amount=None`,`recharge_total` 系统性少计;
- 作业默认 `enabled=False`,生产上一直没跑。
历史**不回填**(既有结论不变):需要历史走斗鱼侧权威接口
(`query_exchange_records` / `query_xpd_purchase_records` / `query_points` 都是现成任务类型)。
## 二、业务事实直发:命名构造函数
新增 `services/business_events.py`:`record_recharge` / `record_exchange` /
`record_points_credit` / `record_bind`。每类事实的字段、标题、金额符号只定义一次
(与 S4 的 `record_account_action`、`on_ck_verdict` 同一套路)。
**9 处成功点接线**:`exchange_goods` 真兑换分支、`exchange_esports_goods`、
`exchange_xpd_goods`、`pay_locked_order`、`create_gold_qr`(二维码 + 供应商轮询 +
**供应商回调**三条路径)、`donate_elite_gift`、`donate_esports_gift`、
`confirm_bind`、`confirm_esports_bind`。
**只记真实事实**(按你的决定):`exchange_goods` 里「预约到货 / 已预兑 / 预兑确认」
三条 success 分支**不发事件** —— 它们不消耗积分也没换到东西,旧收集器只按 status
收集,于是每预约一次就生成一条金额为空的 `exchange` 把 `exchange_count` 灌大。
`confirm_bind` 里「检测到账号本来就已绑定」那条也跳过。
## 三、修掉两个真 bug(都是钱账)
1. **到账判据 `!=` → `>`**(`douyu_runner_gold.py`):余额**下降**也算「鱼翅已到账」。
批内并发(最高 10)时同账号送礼会消耗鱼翅,余额一变就被充值任务读成到账,
**往台账记一笔根本没发生的充值**。
2. **供应商回调晚于 runner 超时**:原来守卫是「任务状态没被改过才更新」,
于是 runner 先判 failed、回调随后说成功的那笔真金白银**永远不进时间线**。
改成按**回调自己的终态**判断,并补发事件。
## 四、发射顺序:一个会静默丢事件的坑
`_mark_task` 内部 `db.commit()`,而 `emit` 用 `db.begin_nested()` **只 RELEASE
SAVEPOINT、不提交外层事务**;runner 的 `finally` 只 `close()`(未提交即回滚)。
所以**在 `_mark_task` 之后发事件会被静默丢弃,且 `emit` 仍返回 True**。
所有接线一律紧贴 `_mark_task(success)` **之前**,并加了源码扫描用例钉住
(已反向验证:故意挪到之后,用例立刻报出 file:line)。
## 五、`douyu_tasks` 保留策略(新增作业,默认关闭)
`jobs/douyu_tasks_retention.py`,两档:
| 档 | 保留 |
| --- | --- |
| 噪声查询(只读看一眼就走,且前端不拿它派生账号状态) | **7 天** |
| 其余一切(业务事实 + 状态派生依赖的查询 + **以后新增的类型**) | **90 天** |
长保留档用 `task_type NOT IN (噪声名单)` 表达 → **新增类型默认长保留**,不会因为
「忘了加名单」被误删(正是收集器翻车的反面)。在途任务(planned/pending/running)
**绝不删**;分批删避免长锁;两个窗口都能在作业 `config` 里改,不必发版。
⚠️ 「前端从任务列表反推账号当前状态」那几类查询(`query_xpd_bind_info` /
`query_esports_game_name` 等)**故意留在长保留档** —— 删早了工作台账号行会变
「未查」,那是把**当前显示**搞坏。根治要靠 §3.6 的状态列拆解(后续阶段)。
作业默认 `enabled=False`,由运维决定何时打开。
## 验证
- `TZ=Asia/Shanghai`:**450 passed / 6 skipped**(S4 后 426 → 净增 24)
- `TZ=UTC`(相关文件)101 passed;ruff check/format 全绿
- 前端 build 通过、lint 0 errors
- 真实开发库:迁移已应用(head `20261004_0043`,孤儿作业行已清);
保留作业实跑确认「作业行默认关闭、SQL 在 MySQL 上正确、近期行不误删」
- **两处反向验证**:把 `record_bind` 挪到 `_mark_task` 之后 → 顺序用例报红;
修掉 `registered_jobs()` 那个**假绿用例**(它返回 dict,原来的集合推导式
遍历空字典恒成立),并在断言里加了反向确认
未做(后续):S6 账号页重构 + `bind_status` 三列拆解(做完才能把状态派生类查询
也纳入短保留)、S7 账号检测改账号维度、S8 丢 `login_tasks` 旧凭据列。
This commit is contained in:
+36
-15
@@ -266,11 +266,11 @@ CREATE INDEX ix_account_events_ledger
|
||||
| ops | `assigned` | 分配 / 取消分配 | `audit_service.record_account_action`、批量走 `emit_bulk` | — |
|
||||
| ops | `tag_changed` | 标签变更(detail 带 from/to) | 同上 | — |
|
||||
| ops | `remark_changed` | 备注变更(detail 带 from/to) | `accounts.set_account_remark`(单个) | — |
|
||||
| business | `recharge` | 充值到账 | 收集器(S5) | + ¥ |
|
||||
| business | `exchange` | 兑换(含消耗积分) | 收集器(S5) | − 积分 |
|
||||
| business | `points_credit` | 积分到账 | 收集器(S5) | + 积分 |
|
||||
| business | `recharge` | 充值到账 | `business_events.record_recharge`(二维码/供应商轮询/**供应商回调** 三条路径,同一 `task_ref` 去重) | + ¥ |
|
||||
| business | `exchange` | 兑换(含消耗积分) | `record_exchange`:`exchange_goods` 的真兑换分支、`exchange_esports_goods`、`exchange_xpd_goods`、`pay_locked_order` | − 积分/点券 |
|
||||
| business | `points_credit` | 积分到账(detail 带 `confirmed`) | `record_points_credit`:`donate_elite_gift`、`donate_esports_*` | + 积分 |
|
||||
| business | `elite_opened` / `esports_opened` | 开通精英宝典 / 电竞手册 | `douyu_runner_manual` | — |
|
||||
| business | `bind_ok` / `rebind` | 角色绑定 / 换绑 | 收集器(S5) | — |
|
||||
| business | `bind_ok`(detail 带 `rebind`) | 角色绑定 / 换绑 | `record_bind`:`confirm_bind` 的真回查分支、`confirm_esports_bind` | — |
|
||||
|
||||
> **只有一个不落表**:`imported` —— 导入时间直接读 `accounts.created_at`。
|
||||
>
|
||||
@@ -329,12 +329,33 @@ CREATE INDEX ix_account_events_ledger
|
||||
|
||||
### 3.8 `douyu_tasks` 降级:执行日志,不再是账号历史来源
|
||||
|
||||
- 职责收窄为**执行层**:二维码、轮询、锁单、支付、结果回传、WebSocket 推送;
|
||||
- 业务事实在任务成功时**同时**写入 `account_events`(而不是事后从 JSON 里挖);
|
||||
- 补保留策略:`query_*` / `refresh_*` 等**查询类任务保留 7 天**,业务类保留 90 天 —— 直接解决 687MB;
|
||||
- `account_events` 独立长期保留(体量小:实测每天数百条,一年 10 万条以内)。
|
||||
> **S5 已落地(2026-10-04)**。职责收窄为**执行层**:二维码、轮询、锁单、支付、
|
||||
> 结果回传、WebSocket 推送。业务事实由业务代码在发生那一刻**直接发事件**
|
||||
> (`services/business_events.py` 的命名构造函数),不再事后从 JSON 里挖。
|
||||
|
||||
---
|
||||
**收集器已删除**(`jobs/account_events_collect.py` 连同 `_task_to_event`、
|
||||
`COLLECTED_TASK_TYPES`、水位线一起删掉,迁移 `20261004_0043` 清掉作业行)。
|
||||
它必然漏数据:靠 allowlist 认业务类型,新增类型没人想起维护就**静默丢**
|
||||
(电竞兑换、和平小店兑换、锁单支付、电竞礼物积分因此从来没进过时间线)。
|
||||
|
||||
**保留策略**(`jobs/douyu_tasks_retention.py`,默认**关闭**,由运维打开):
|
||||
|
||||
| 档 | 判定 | 保留 |
|
||||
| --- | --- | --- |
|
||||
| 噪声查询 | 只读看一眼就走,且前端**不**拿它派生账号状态 | **7 天** |
|
||||
| 其余一切(业务事实 + 状态派生依赖的查询 + **以后新增的类型**) | — | **90 天** |
|
||||
|
||||
> 长保留档用 `task_type NOT IN (噪声名单)` 表达,于是**新增任务类型默认长保留**,
|
||||
> 不会因为「忘了加进某个列表」被误删 —— 正是收集器当年翻车的反面。
|
||||
>
|
||||
> ⚠️ **「状态派生依赖类的查询」不能按 7 天删**:工作台是从任务列表**反推**账号
|
||||
> 当前状态的(`DouyuTasksPage` 的 `latest*ByAccount`,且要求 `task.result` 非空)。
|
||||
> 这是历史包袱(与 `bind_status` 同源:账号的「现在是什么」存在执行日志里),
|
||||
> §3.6 的状态列拆解才是根治;在拆解完成前,这类查询保守留长。
|
||||
>
|
||||
> `account_events` 独立长期保留(体量小:每天数百条,一年 10 万条以内)。
|
||||
> 注:`DELETE` 只让 InnoDB 的空间**可复用**,文件不会自动缩 —— 要缩需在维护窗口
|
||||
> `OPTIMIZE TABLE`。
|
||||
|
||||
## 4. 数据源矩阵:记录从哪来
|
||||
|
||||
@@ -342,11 +363,11 @@ CREATE INDEX ix_account_events_ledger
|
||||
| --- | --- | --- |
|
||||
| 导入 | 导入动作本身 | — |
|
||||
| 登录 / CK / 失效 / 重登 | 登录批次、`ck_health`、`ck_relogin` 直接发事件 | — |
|
||||
| 开通(精英宝典 / 电竞手册) | 开通任务成功时发事件(`run` 内直发,不经 JSON 回捞) | 斗鱼侧状态查询可校正当前值 |
|
||||
| 充值鱼翅 | 充值任务成功时发事件 | 供应商回调 |
|
||||
| 积分到账 / 兑换 | 任务成功时发事件 | **斗鱼侧权威接口**:`exchange_records`(兑换)、`xpd_purchase_records`(小店)、`query_points`(积分) |
|
||||
| 角色绑定 / 换绑 | 绑定任务成功时发事件 | — |
|
||||
| 人工操作(分配 / 标签 / 停用) | 审计日志 + 直接发事件(需打通 `audit_logs.account_id`) | — |
|
||||
| 开通(精英宝典 / 电竞手册) | 开通任务成功时发事件(`run` 内直发) | 斗鱼侧状态查询可校正当前值 |
|
||||
| 充值鱼翅 | **任务成功或供应商回调**时发事件(三条路径同一 `task_ref` 去重) | — |
|
||||
| 积分到账 / 兑换 | 任务成功时发事件(**电竞与小店兑换、锁单支付也在内**) | **斗鱼侧权威接口**:`query_exchange_records`、`query_xpd_purchase_records`、`query_points` |
|
||||
| 角色绑定 / 换绑 | 确认接口成功 + 回查生效时发事件 | — |
|
||||
| 人工操作(分配 / 标签 / 备注 / 停用) | 审计日志 + 直接发事件(`audit_logs.account_id` 已打通) | — |
|
||||
|
||||
> **历史怎么办**:**不从 `douyu_tasks` 回填**(噪声大、结构靠猜)。
|
||||
> 需要历史时走**斗鱼侧权威接口按需同步**(如 `query_exchange_records`),
|
||||
@@ -441,7 +462,7 @@ WHERE a.cookie <> src.cookie;
|
||||
| **S2** | 读写一次切换:12 个文件、24 读点 / 10 写点全部改 `LoginTask.*` → `Account.*`;批次行复用逻辑重写;在途子查询 + 索引 | 登录记录与 CK 彻底解耦 | S1 |
|
||||
| **S3** ✅ | 状态收口(**已完成 2026-10-04**):`account_lifecycle` 提供 `derive_status()` / `sync_status()` / `set_manual_state()` / `on_login_success()`;9 处判据写入点全部接线;6 状态状态机上线;自动化选行排除 `disabled`/`archived`;新增 `account:manage` 权限与停用/归档/恢复接口;前端列表加状态列与筛选、详情页加状态卡与操作入口 | `status` 可信 | S2 |
|
||||
| **S4** ✅ | 事件发射点补齐(**已完成 2026-10-04**):`assigned` / `tag_changed` 接上(此前定义了却从没发过)、新增 `ck_cleared`、`ck_invalid` 改为只在转变时发;`audit_logs.account_id` 在分配/标签/检测/清 CK 处打通;新增 `emit_bulk`(批量操作逐账号写事件)与 `record_account_action`(审计+事件一次写完);时间线支持 `category` 筛选;前端补 `status_changed` / `ck_cleared` 样式与分类筛选;补上改备注接口 `PUT /api/accounts/{id}/remark`(`remark_changed` 从此有发射点)| 时间线完整 | S2 |
|
||||
| **S5** | 业务事实直发事件:开通 / 充值 / 积分 / 兑换 / 绑定在任务成功时写事件;`douyu_tasks` 加保留策略 | 台账可用,687MB 可控 | S4 |
|
||||
| **S5** ✅ | 业务事实直发事件(**已完成 2026-10-04**):新增 `services/business_events.py` 命名构造函数(`record_recharge` / `record_exchange` / `record_points_credit` / `record_bind`);9 处成功点直发(含**此前从未收录**的电竞兑换、和平小店兑换、锁单支付、电竞礼物积分);修掉「到账判据 `!=`」与「回调晚于超时」两个洞;幂等键 `douyu_task:{id}` 让直发与旧收集器/回调互相去重;**删除收集器**(含映射、水位线、测试,迁移 `0043` 清作业行);新增 `douyu_tasks` 保留策略作业(噪声 7 天 / 其余 90 天,默认关闭) | 台账可用,687MB 可控 | S4 |
|
||||
| **S6** | 账号页重构:列表加状态与关键列;详情页做成「生命周期主页」(状态卡 + 台账 + 时间线 + 操作);`bind_status` 三列拆解落地 | 账号管理真正独立 | S3、S5 |
|
||||
| **S7** | 账号检测并入账号域(`account-check` 从「粘贴文本」改为「按账号选」,结果落事件) | 检测不再是孤岛 | S6 |
|
||||
| **S8** | 清理:drop `login_tasks` 旧列与 `accounts` 三个 `*_bind_status` 列(**不可逆,前置:每日备份 + 反向回填脚本**) | 包袱丢干净 | S6 |
|
||||
|
||||
+24
-5
@@ -106,10 +106,29 @@ class AccountEvent(Base):
|
||||
| `esports_opened` | **电竞手册开通**(新增记录) | `douyu_runner_manual` |
|
||||
| `assigned` / `tag_changed` / `remark_changed` | 人工操作 | `audit_logs`(需补 account_id,见 §7) |
|
||||
|
||||
## 4. 业务事件怎么收录:增量收集器(不回填)
|
||||
## 4. 业务事件怎么收录:~~增量收集器~~ → 已改为**直发**(不回填)
|
||||
|
||||
既有历史**不导入**。业务事件(充值/兑换/积分到账/绑定)用**一个增量收集器**从 `douyu_tasks`
|
||||
往后提取 —— 好处是**完全不侵入 runner 代码**(不必改 8 个业务文件),且新老任务类型统一处理。
|
||||
> ## ⚠️ 本节已作废(2026-10-04,S5)
|
||||
>
|
||||
> 收集器方案**已放弃并删除代码**。原因(详见
|
||||
> [账号全生命周期设计](设计-账号全生命周期.md) §3.8):
|
||||
>
|
||||
> 1. **靠 allowlist 认业务类型必然漏**:新增类型没人想起维护名单就静默丢数据 ——
|
||||
> 电竞兑换、和平小店兑换、锁单支付、电竞礼物积分因此**从来没进过时间线**;
|
||||
> 2. **「任务 success」不等于「业务真的发生了」**:预约到货、已预兑、「检测到本来就
|
||||
> 已绑定」、积分未确认到账,都被标成 success,收集器照单全收写成事实;
|
||||
> 3. **字段路径靠抽样猜**:二维码充值的 `result` 里根本没有金额,收集器因此恒写
|
||||
> `amount=None`,`recharge_total` 系统性少计;
|
||||
> 4. 作业**默认关闭**,生产上它一直没跑。
|
||||
>
|
||||
> 现在业务代码在动作成功那一刻用 `services/business_events.py` 的命名构造函数直发
|
||||
> (幂等键 `douyu_task:{id}`,与旧收集器一致,迁移窗口内可互相去重)。
|
||||
>
|
||||
> 下文 §4.1 / §4.2 / §5.2 保留作为**历史记录**:其中的 `result` 字段实测结论仍然
|
||||
> 有价值(接入斗鱼侧接口时用得上),但**不要再按它实现收集器**。
|
||||
|
||||
既有历史**不导入**。业务事件(充值/兑换/积分到账/绑定)~~用**一个增量收集器**从 `douyu_tasks`
|
||||
往后提取 —— 好处是**完全不侵入 runner 代码**(不必改 8 个业务文件),且新老任务类型统一处理~~。
|
||||
|
||||
### 4.1 收集器设计
|
||||
|
||||
@@ -264,7 +283,7 @@ class AccountEvent(Base):
|
||||
| E1 | `feat(db): account_events 表 + audit_logs.account_id` | 无 |
|
||||
| E2 | `feat(events): 事件发射 helper + CK 事件(失效/登录/重登)` | **CK 解耦已完成**(否则写入点还会变) |
|
||||
| E3 | `feat(events): 开通事件(精英宝典 / 电竞手册)` | 无 |
|
||||
| E4 | `feat(events): douyu_tasks 增量收集器 + 水位线` | 无 |
|
||||
| ~~E4~~ | ~~`feat(events): douyu_tasks 增量收集器 + 水位线`~~ **已废弃**(S5 改为直发并删除) | 无 |
|
||||
| E5 | `feat(api): 账号事件与概览接口` | E1 |
|
||||
| E6 | `feat(ui): 账号详情页(状态卡 + 统计 + 时间线)` | E5 |
|
||||
| E7 | `docs: 落点与验收` | —— |
|
||||
@@ -282,7 +301,7 @@ class AccountEvent(Base):
|
||||
4. **发射事件是旁路**:必须保证 `emit()` 抛错不影响登录/兑换主流程(用 try 包住 + 记日志);
|
||||
5. **积分口径要先定**(决策 C):`accounts.points` 与 `donate_elite_gift` 的 `points_query.points`
|
||||
有不一致的情况(如兑换后 `points_query.points=0`),时间线显示哪个要明确;
|
||||
6. 绑定类任务的 `result` 结构**尚未抽样**(§4.2),收集器实现前先 dump 一条确认。
|
||||
6. ~~绑定类任务的 `result` 结构尚未抽样(§4.2),收集器实现前先 dump 一条确认。~~ **已随收集器一并作废**:直发不再需要解析 `result`。
|
||||
|
||||
## 10. 待确认的决策点
|
||||
|
||||
|
||||
Reference in New Issue
Block a user