Files
live-hub-py/web/backend/services/automation/jobs/douyu_tasks_retention.py
T
yml2213 6e729e7a80 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` 旧凭据列。
2026-10-04 16:00:42 +08:00

208 lines
8.1 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""作业:清理 `douyu_tasks` 的历史任务日志。
## 为什么需要
`douyu_tasks` 是**执行日志**,不是账号历史。它按天增长(生产实测 222,679 行 /
687MB,且绝大多数是例行查询),而其中真正有长期价值的业务事实,S5 之后都会
由业务代码在发生那一刻写进 `account_events`(体量小几个数量级)。
所以这里只做一件事:**按任务类型的价值分档,把过期的执行日志删掉。**
## 分档依据(关键设计)
不是「按时间一刀切」,而是按「这条日志里的 `result` 还有没有人需要」分三档:
| 档 | 判定 | 默认保留 | 说明 |
| --- | --- | --- | --- |
| **噪声查询** | 只读、看一眼就走,且前端**不**用它的 `result` 派生账号状态 | 7 天 | 体量最大的就是这类(`query_limited_goods` 单类 6.7 万行) |
| **状态派生** | 前端从任务列表反推账号当前状态时要读它(`latest*ByAccount`) | 90 天 | 删早了工作台账号行的「已绑定/未绑定」会变成「未查」 |
| **业务事实** | 真花钱/花积分/改变账号归属的动作 | 90 天 | 90 天后仍有 `account_events` 兜底 |
⚠️ **为什么「状态派生」类不能按 7 天删**:工作台是从任务列表**反推**账号状态的
(`DouyuTasksPage` 的 `latestConfirmBindTaskByAccount` 等),而且明确要求
`task.result` 非空。这是历史包袱(和 `bind_status` 同源:账号的「现在是什么」
存在执行日志里),设计文档 §3.6 的状态列拆解才是根治。在拆解完成之前,
这里保守地把这类查询留长一点 —— 否则会把「当前显示」搞坏,那不是在清历史。
两类窗口都可以在 `/automation` 页面按作业改(`config.noise_days` /
`config.business_days`),不必发版。
## 安全约束
- **绝不删在途任务**(`planned` / `pending` / `running`)—— 批次线程可能正拿着它;
- 分批删(每批 `batch_size` 行、最多 `max_batches` 批),避免长事务长时间锁表;
- 不删行、只删「过期的整行」:不做「把 result 清空保留行」这种半吊子操作,
因为部分前端派生**明确要求 result 非空**,清空等于制造「有行但读不出状态」的
更隐蔽的坏状态;
- 作业**默认关闭**(`ensure_jobs` 建行时 enabled=False),由运维在页面上打开。
"""
from __future__ import annotations
import json
from datetime import UTC, datetime, timedelta
from typing import Any
from loguru import logger
from sqlalchemy import text
from sqlalchemy.orm import Session
from ....models import AutomationJob
JOB_KEY = "douyu_tasks_retention"
#: 只读、看一眼就走,且前端**不**拿它派生账号状态 → 短保留。
#: 体量最大的就在这一类(`query_limited_goods` / `query_change_bind_time`)。
NOISE_TASK_TYPES: tuple[str, ...] = (
"query_limited_goods",
"query_change_bind_time",
"query_gold_balance",
"query_xpd_balance",
"query_xpd_fragments",
"query_points",
"refresh_goods",
"refresh_esports_goods",
"refresh_xpd_goods",
"prefetch_csrf_token",
)
DEFAULT_NOISE_DAYS = 7
DEFAULT_BUSINESS_DAYS = 90
DEFAULT_BATCH = 2000
DEFAULT_MAX_BATCHES = 50
#: 在途任务绝不可删:批次线程正拿着这些行。
IN_FLIGHT_STATUSES = ("planned", "pending", "running")
def _load_config(job: AutomationJob) -> dict[str, Any]:
config = job.config
if isinstance(config, str):
try:
config = json.loads(config)
except ValueError:
config = {}
return dict(config) if isinstance(config, dict) else {}
def _positive_int(value: Any, default: int) -> int:
try:
parsed = int(value)
except (TypeError, ValueError):
return default
return parsed if parsed > 0 else default
def _delete_batch(
db: Session,
*,
task_types: tuple[str, ...],
cutoff: datetime,
batch: int,
negate: bool = False,
) -> int:
"""删一批过期行,返回删除条数。
`negate=True` 时语义变成「**除这些类型之外**的都在这一档」—— 长保留档就是这么
表达的。这样做有个重要的安全属性:**新增的任务类型默认落在长保留档**,
不会因为「忘了往某个列表里加」而在 7 天后被误删(收集器当年就是反过来,
忘了加 allowlist 就静默丢数据)。
`LIMIT` 让单条语句不会长时间持锁。
"""
if not task_types:
return 0
placeholders = ", ".join(f":t{i}" for i in range(len(task_types)))
status_placeholders = ", ".join(f":s{i}" for i in range(len(IN_FLIGHT_STATUSES)))
operator = "NOT IN" if negate else "IN"
params: dict[str, Any] = {
"cutoff": cutoff,
"limit": batch,
**{f"t{i}": t for i, t in enumerate(task_types)},
**{f"s{i}": s for i, s in enumerate(IN_FLIGHT_STATUSES)},
}
result = db.execute(
text(
f"""
DELETE FROM douyu_tasks
WHERE task_type {operator} ({placeholders})
AND status NOT IN ({status_placeholders})
AND created_at < :cutoff
LIMIT :limit
"""
),
params,
)
return int(result.rowcount or 0)
def run_douyu_tasks_retention(db: Session, job: AutomationJob) -> dict[str, Any]:
config = _load_config(job)
noise_days = _positive_int(config.get("noise_days"), DEFAULT_NOISE_DAYS)
business_days = _positive_int(config.get("business_days"), DEFAULT_BUSINESS_DAYS)
batch = _positive_int(job.batch_size, DEFAULT_BATCH)
max_batches = _positive_int(config.get("max_batches"), DEFAULT_MAX_BATCHES)
now = datetime.now(UTC)
# 传 naive UTC:created_at 是 UTCDateTime 列,裸 SQL 参数不经过类型转换,
# 带 tzinfo 会被驱动按本地时区处理(参见设计文档里那次 8 小时偏移事故)。
noise_cutoff = (now - timedelta(days=noise_days)).replace(tzinfo=None)
business_cutoff = (now - timedelta(days=business_days)).replace(tzinfo=None)
total_deleted = 0
batches = 0
# 两档:噪声查询只留 noise_days;**其余一切**(业务事实 + 前端状态派生依赖的
# 查询 + 以后新增的类型)留 business_days。
passes = (
(noise_cutoff, NOISE_TASK_TYPES, False, "noise"),
(business_cutoff, NOISE_TASK_TYPES, True, "rest"),
)
per_pass: dict[str, int] = {}
for cutoff, task_types, negate, label in passes:
deleted_this_pass = 0
while batches < max_batches:
deleted = _delete_batch(
db,
task_types=task_types,
cutoff=cutoff,
batch=batch,
negate=negate,
)
batches += 1
total_deleted += deleted
deleted_this_pass += deleted
db.commit()
if deleted < batch:
break
per_pass[label] = deleted_this_pass
# 注意措辞:这只说明「批次预算用光了」,**不等于**「确实还有积压」——
# 预算在上一档用完时,下一档根本没轮到执行,这里无法区分「没得删」和「没轮到」。
# 所以做成提示而非结论,措辞上也别谎称「仍有积压」。
batch_budget_exhausted = batches >= max_batches
if batch_budget_exhausted:
logger.warning(
"任务日志清理用光了批次预算({} 批,共删 {} 条);"
"若日志量持续很大,可调大 max_batches 或 batch_size",
max_batches,
total_deleted,
)
message = (
f"清理 {total_deleted} 条任务日志"
f"(噪声>{noise_days}天 / 其余>{business_days}天,{batches} 批)"
)
logger.info(message)
return {
"scanned": total_deleted,
"deleted": total_deleted,
"deleted_noise": per_pass.get("noise", 0),
"deleted_rest": per_pass.get("rest", 0),
"batches": batches,
"noise_days": noise_days,
"business_days": business_days,
"batch_budget_exhausted": batch_budget_exhausted,
"message": message,
}