feat(account): S6 bind_status 三列拆解 —— 四值枚举、唯一写入口、前端改读账号
`accounts.bind_status` 是个**语义垃圾场**:一个自由文本列,6 个文件、**29 处写入**、
20 多种取值,混了三种东西 —— 真状态(`bind_confirmed`)、动作痕迹(`goods_locked`)、
纯查询痕迹(`points_queried`)。它是**覆盖式**的,所以 `bind_confirmed` 会被之后
任意一次查询盖掉 —— 「这个账号到底绑没绑」根本查不出来。
`esports_bind_status` / `xpd_bind_status` 是同一个病。
## 收敛成四值 + 三列一义
`unknown` / `unbound` / `pending` / `bound`,每个作用域一列:
| 列 | 作用域 |
| --- | --- |
| `accounts.role_bind_status`(**新增**) | 精英宝典角色 |
| `accounts.esports_bind_status`(收敛) | 电竞手册角色 |
| `accounts.xpd_bind_status`(收敛) | 和平小店角色 |
- 新增 `services/account_binding.py`:唯一写入口 `set_bind_status()`,
传旧自由文本直接 `ValueError`(否则垃圾会被写回去);`map_legacy_bind_status()` 负责旧值映射。
- **29 处自由文本写入全部删除或改走枚举**:真状态走枚举,动作/查询痕迹**不再写状态列**
(动作已由 S5 的直发事件记录,查询痕迹本来就不该是状态)。
- `accounts.bind_status` 保留原值便于比对,**已无任何写入方**,待 S8 drop。
- 一条**源码扫描用例**禁止任何地方再出现 `account.bind_status = "..."` 这类写入。
## 回填不猜(设计文档 §5.5)
只映射**明确陈述了绑定关系**的取值(`bind_confirmed`/`esports_bound`/`xpd_bound` → bound,
`*_qr_*`/`*_ready` → pending,`game_not_bound`/`xpd_not_bound` → unbound),
**其余一律 unknown**。因为列是覆盖式的,「最后一件事是查询」并不代表没绑定。
迁移 SQL 与 Python 映射有一致性用例:**解析迁移源码里的 CASE 逐条比对**
(已反向验证:故意改错一条映射,用例立刻红)。
## ⚠️ 顺带救回一个差点被我自己丢掉的状态
「**电竞手册是否已开通**」以前**只寄生在 `esports_bind_status` 的 `esports_opened`
取值里**(`elite_opened` 有独立布尔列,电竞没有)。归一化会把那个取值抹成 `unknown`
→ **静默丢状态**。所以:
- 新增 `accounts.esports_opened` 布尔列(与 `elite_opened` 对称),开通任务成功时置位;
- 迁移里**必须先 `save_esports_opened()` 再归一化**,顺序用例钉住;
- 详情页「电竞手册」开通状态改读 `esports_opened`。
## 前端不再从任务日志反推账号状态
工作台原来从**当前加载的那一页任务**里挑每个账号最新的一条来推绑定状态
(`latestConfirmBindTaskByAccount` 等)。两个问题:① 支撑任务一旦翻出窗口,
**显示的状态就是错的**;② 这让任务日志变成「账号状态库」,于是它永远不敢清理。
现在状态读账号字段,任务日志只补「扫码流程中的瞬时信息」(如确认前的
`pending_role_name`)。删掉了两个不再需要的派生与对应的 `clearPending` 绕行逻辑。
## 踩到并修掉的东西
- **模型与迁移不一致**:我把模型收窄成 `String(16)`,迁移却留着 `String(32)` ——
测试库按模型建、生产按迁移建,两边列宽不同。已让迁移也收窄,且**收窄必须在
归一化之后**(旧取值最长 19 字符,先收窄会截断成废值)。downgrade 也补齐了反向操作,
已实测 `downgrade -1 && upgrade head` 干净。
- **parity 用例第一版是抄了一份 SQL**(迁移改了用例也不会红,等于没测)——
改成解析迁移源码;后来又因为列已收窄、19 字符的旧值塞不进测试库,
干脆改成源码级解析比对(不造数据)。
## 验证
- `TZ=Asia/Shanghai`:**490 passed / 6 skipped**(S5 后 450 → 净增 40)
- `TZ=UTC`(相关文件)106 passed;迁移链 3 passed;ruff 全绿
- 前端 `tsc -b && vite build` 通过、`npm run lint` **0 errors**
- 真实开发库:迁移重放后三列均为 `varchar(16) NOT NULL DEFAULT 'unknown'`;
12 个账号的旧值 `elite_status_queried`(纯查询痕迹)→ **unknown**(没有猜成 bound)
未做(后续):S6 的**账号页重构**(列表关键列 / 生命周期主页)保留;
`bind_status` 旧列待 S8 drop;保留策略里「状态派生类查询」现在技术上可下探到 7 天档,
保守起见留待确认(影响的是在用页面显示,不是历史)。
This commit is contained in:
+55
-10
@@ -301,16 +301,57 @@ CREATE INDEX ix_account_events_ledger
|
||||
|
||||
### 3.6 `bind_status` 的拆解(旧列 → 新字段)
|
||||
|
||||
| 旧取值族 | 新归属 |
|
||||
| --- | --- |
|
||||
| `bind_confirmed` / `bind_qr_generated` / `game_queried` / `change_time_queried` / `game_not_bound` | `accounts.role_bind_status`(**明确的当前值**:`unbound`/`bound`/`pending`)<br>动作痕迹进 `account_events`,不占状态列 |
|
||||
| `gold_qr_created` / `gold_recharged` / `gold_balance_queried` | 充值流水进 `account_events`;余额进 `gold_balance` |
|
||||
| `elite_qr_created` / `elite_opened` / `elite_status_queried` | `elite_opened` + `elite_expire_time` 已有;开通时间进 `account_events.elite_opened` |
|
||||
| `esports_*` | `accounts.esports_bind_status` 收敛为明确值;其余进事件流 |
|
||||
| `xpd_*` | 同上 |
|
||||
| `points_queried` / `limited_goods_queried` / `exchange_records_queried` / `csrf_token_ready` / `goods_refreshed` | **直接删除** —— 这些是「跑过一个查询任务」,不是账号状态 |
|
||||
> **S6 已落地(2026-10-04)**,实现见 `web/backend/services/account_binding.py`,
|
||||
> 迁移 `20261004_0044`。
|
||||
|
||||
**规则**:状态列只放「现在是什么」,动作痕迹一律进 `account_events`(要查随时能查,且不会被覆盖)。
|
||||
**它烂掉的方式**:一个自由文本列,**6 个文件、29 处写入、20 多种取值**,
|
||||
而且混了三种语义 —— 真状态(`bind_confirmed`)、动作痕迹(`goods_locked`)、
|
||||
纯查询痕迹(`points_queried`)。因为它是**覆盖式**的,`bind_confirmed` 会被之后
|
||||
任意一次查询盖掉,于是「这个账号到底绑没绑」查不出来。
|
||||
`esports_bind_status` / `xpd_bind_status` 是同一个病。
|
||||
|
||||
**收敛成四个值**:`unknown` / `unbound` / `pending` / `bound`,
|
||||
三列各管一个作用域(**一列一义**):
|
||||
|
||||
| 列 | 作用域 |
|
||||
| --- | --- |
|
||||
| `accounts.role_bind_status`(**新增**) | 精英宝典角色绑定 |
|
||||
| `accounts.esports_bind_status`(收敛) | 电竞手册角色绑定 |
|
||||
| `accounts.xpd_bind_status`(收敛) | 和平小店角色绑定 |
|
||||
|
||||
**写入收口**:只有 `account_binding.set_bind_status()` 能写;
|
||||
传旧自由文本直接 `ValueError`(否则垃圾又会被写回去)。
|
||||
有一条**源码扫描用例**禁止任何地方再出现自由文本写入。
|
||||
|
||||
**回填不猜**(§5.5):只映射明确陈述绑定关系的取值
|
||||
(`bind_confirmed`/`esports_bound`/`xpd_bound` → `bound`,`*_qr_*`/`*_ready` → `pending`,
|
||||
`game_not_bound`/`xpd_not_bound` → `unbound`),**其余一律 `unknown`**。
|
||||
迁移的 CASE 与 Python 映射有一致性用例(解析迁移 SQL 源码比对)。
|
||||
|
||||
**动作与查询痕迹一律不再写状态列**:动作已由 S5 的直发事件记录,
|
||||
查询痕迹本来就不该是状态。
|
||||
|
||||
#### S6 顺带救回一个差点丢掉的状态
|
||||
|
||||
「**电竞手册是否已开通**」以前**只寄生在 `esports_bind_status` 的 `esports_opened`
|
||||
取值里**(`elite_opened` 有独立布尔列,电竞没有)。归一化会把那个取值抹成 `unknown`
|
||||
—— 于是迁移里必须先 `save_esports_opened()` 把它救进新增的 `accounts.esports_opened`
|
||||
列,**再**归一化。顺序用例钉住了这一点(`upgrade()` 里 `save_esports_opened`
|
||||
必须早于 `normalise_esports_bind_status`)。
|
||||
|
||||
> `accounts.bind_status` 列**保留原值不动**(便于人工比对),但已无任何写入方,
|
||||
> 计划 S8 一并 drop。`role_bind_status`/`esports_bind_status`/`xpd_bind_status`
|
||||
> 三列收窄成 `String(16)` + `server_default='unknown'`,与模型一致;
|
||||
> ⚠️ 收窄**必须放在归一化之后**(旧取值最长 19 字符,先收窄会截断成废值)。
|
||||
|
||||
#### 前端不再从任务日志反推账号状态
|
||||
|
||||
工作台原来从**当前加载的任务列表**里挑每个账号最新的一条来推绑定状态
|
||||
(`latestConfirmBindTaskByAccount` 等)—— 只看得见这一页的任务,支撑任务一旦翻出
|
||||
窗口显示的状态就是**错的**;而且这让任务日志变成了「账号状态库」,于是它永远不敢清理。
|
||||
|
||||
现在**状态读账号字段**,任务日志只用来补「扫码流程中的瞬时信息」
|
||||
(如扫码后、确认前的 `pending_role_name`)。
|
||||
|
||||
### 3.7 `login_tasks` 瘦身:退化为登录尝试历史
|
||||
|
||||
@@ -353,6 +394,10 @@ CREATE INDEX ix_account_events_ledger
|
||||
> 这是历史包袱(与 `bind_status` 同源:账号的「现在是什么」存在执行日志里),
|
||||
> §3.6 的状态列拆解才是根治;在拆解完成前,这类查询保守留长。
|
||||
>
|
||||
> **S6 之后**:前端已不再用任务日志推账号状态,因此「状态派生依赖」那几类查询
|
||||
> **理论上可以下探到 7 天档**(只剩扫码流程的瞬时提示会看不到)。这一步保守起见
|
||||
> 留待确认后再做 —— 它影响的是在用页面的显示,不是历史。
|
||||
>
|
||||
> `account_events` 独立长期保留(体量小:每天数百条,一年 10 万条以内)。
|
||||
> 注:`DELETE` 只让 InnoDB 的空间**可复用**,文件不会自动缩 —— 要缩需在维护窗口
|
||||
> `OPTIMIZE TABLE`。
|
||||
@@ -463,7 +508,7 @@ WHERE a.cookie <> src.cookie;
|
||||
| **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** ✅ | 业务事实直发事件(**已完成 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 |
|
||||
| **S6** ◐ | `bind_status` 三列拆解(**已完成 2026-10-04**):新增 `services/account_binding.py`(四值枚举 + 唯一写入口 + 旧值映射)、迁移 `0044`(新增 `role_bind_status` 与 `esports_opened`、归一化三列、收窄列宽)、删除全部 29 处自由文本写入、前端改为读账号字段(不再从任务日志反推状态)、详情页显示三列绑定状态。**账号页重构(列表关键列 / 生命周期主页)尚未做**,`bind_status` 旧列待 S8 drop | 账号管理真正独立 | S3、S5 |
|
||||
| **S7** | 账号检测并入账号域(`account-check` 从「粘贴文本」改为「按账号选」,结果落事件) | 检测不再是孤岛 | S6 |
|
||||
| **S8** | 清理:drop `login_tasks` 旧列与 `accounts` 三个 `*_bind_status` 列(**不可逆,前置:每日备份 + 反向回填脚本**) | 包袱丢干净 | S6 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user