@@ -0,0 +1,425 @@
# 账号能力中心与统一选号设计
更新时间:2026-11-21
状态:设计基线,后续代码按本文分阶段落地
## 目标
把账号管理、账号全生命周期、一键查询和直播账号履约选号统一到同一份本地账号数据上:
1. 斗鱼官网是外部账号事实的唯一权威来源;
2. 本地数据库保存当前投影、查询时间、历史事实和内部业务占用;
3. 查询官网后,以官网结果更新本地当前投影;
4. 账号管理筛选和自动选号直接查询本地数据库;
5. 只有最终候选账号在分配前做一次官网实时确认;
6. 官网查询失败时保留上一次有效结论,不把“没查到”写成“不可兑换”。
本文不把所有内部业务数据交给官网覆盖。租约、订单、协作单、归属和内部
365 天规则仍然以本地数据库为准。
## 现有基础
当前项目已经具备这套模型的主要组件:
- `accounts` :账号当前状态、CK、积分、宝典、角色和生命周期;
- `account_events` :不可变事件账本,记录兑换、充值、积分、开通、换绑和登录变化;
- `account_commodity_states` :账号 × 商品的当前兑换能力投影;
- `douyu_goods_snapshot` :斗鱼商品目录快照;
- `douyu_runner_overview` :官网一键查询和投影写入链;
- `platform_fulfillment.account_selector` :履约候选筛选和租约;
- `account_lifecycle` :账号生命周期状态的唯一推导和写入入口。
不需要另建一套账号系统。重点是补齐同步覆盖、明确数据语义,并让账号管理和自动选号
共享同一个数据库查询服务。
## 当前主要缺口
1. 商品能力覆盖不完整。有效 CK 账号和商品能力投影没有一一对应,一键查询过的账号
也可能没有写入商品状态。
2. 能力刷新作业从已有的 `account_commodity_states` 出发,无法主动发现从未建立商品
状态的新账号。
3. `valid_until` 同时承担“当前是否新鲜”和“是否还能查询”的职责,过期数据容易被
当成不存在。
4. 自动选号在能力索引没有严格候选时回退到实时扫描,并且只检查有限的低积分账号,
容易反复撞到同一批已限兑账号。
5. 账号管理、自动选号、履约详情各自组装筛选条件,口径不完全一致。
6. 官网当前结论与内部业务资格没有明确拆开,页面上容易把“官网可兑换”和“当前可分配”
混为一谈。
7. 每次同步的覆盖范围、成功时间、失败原因和官方原始版本没有统一台账。
## 2026-11-21 生产只读基线
以下数据用于说明改造规模,不代表固定业务量:
- 账号总数:约 31,150;
- CK 有效账号:4,848;
- 已做账号一键查询:17,068;
- 已有商品能力状态的账号:2,804;
- 有效 CK 账号中已有商品能力状态:2,775;
- 有效 CK 且已一键查询、但没有商品状态:1,073;
- 商品能力状态行数:75,527;
- 当前商品数量:60;
- 已覆盖账号平均每个只有约 26.9 个商品记录。
按 60 个商品计算,4,848 个有效账号的完整矩阵约 29 万行;即使覆盖全部 3 万账号,
理论规模约 187 万行。规模可控,但必须分批、幂等和限速同步。
## 数据分层
### 账号当前状态
`accounts` 回答“账号整体是什么状态”:
- CK 是否可用;
- 生命周期状态;
- 积分、鱼翅和精英宝典开通状态;
- 角色绑定、换绑冷却;
- 自动管理和归属;
- 最近一次账号资料查询时间。
账号生命周期写入继续遵守 `account_lifecycle` 的唯一写入口约束。
### 商品目录
商品目录回答“斗鱼当前有哪些商品、何时开放、需要多少积分、是否有库存”:
- `platform` 、`scope` 、`commodity_id` ;
- 商品名称、所需积分和平台状态;
- `timeLimited` 、`startTime/endTime` 、`specTimes` ;
- 库存、开放状态和目录观察时间。
商品目录是跨账号共享数据,不能在每个账号记录中重复保存商品名称和开放计划。
`douyu_goods_snapshot` 可以继续作为目录表来源,但应明确一个商品只有一条当前目录投影,
历史变化通过事件或同步记录保留。
### 账号商品能力
`account_commodity_states` 回答“这个账号对这个商品的官网结论是什么”:
- `availability` : `available / limited / no_stock / not_open / expired /
not_offered / unknown`;
- ` raw_status`:官网原始账号级状态;
- ` observed_at`:最近一次观察时间;
- ` valid_until`:当前结论的匹配有效期;
- ` next_check_at`:下次建议检查时间;
- ` available_from / available_until / schedule_json`:限时窗口;
- ` last_exchange_at / exchange_count_365d`:从事件账本派生的兑换摘要。
这张表保存的是当前投影,不是只用于 15 分钟缓存的临时数据。过期记录仍然可以被账号
管理查询和展示,只是不能直接作为自动分配依据。
### 事件账本
` account_events` 继续保存不可变事实:
- 本地实际兑换成功:` source=douyu_task`;
- 官网兑换记录补录:` source=official_sync`;
- 积分、鱼翅、开通、换绑、CK 和生命周期变化;
- 必要的商品能力状态转变。
兑换历史不另建重复台账。` account_events` 已经能够回答“兑换过什么、何时兑换、消耗多少
积分、来源是什么”。
官网记录可以通过 ` source_ref` 幂等去重。后续应优先使用官网记录 ID;没有记录 ID 时,
再使用账号、作用域、商品、时间、数量和原始记录哈希组合,避免同一秒多次兑换被合并。
### 同步运行与脏数据队列
建议后续补充两类基础设施:
1. ` account_sync_runs`:记录一次官网同步的账号、平台、作用域、同步类型、开始/结束时间、
成功/失败状态、写入数量、错误摘要和官方数据哈希。
2. 账号同步脏队列或等价字段:记录 ` dirty_reason`、` next_sync_at`、` last_success_at`、
` last_error`,用于登录成功、CK 恢复、兑换后核对、充值后刷新和订单需求触发。
没有同步台账时,只能知道“字段现在是什么”,无法可靠回答“什么时候查过、为什么没更新、
同一份官网数据是否已经处理过”。
## 三种“能换”必须分开
### 官网可兑换
` official_available` 只由斗鱼官网判断:
- 官方账号级 ` status=0`;
- 商品开放窗口有效;
- 官方库存和开放状态允许兑换;
- 没有明确限兑、无库存、未开放或已结束。
### 资源已就绪
` resource_ready` 表示账号自身资源是否足够:
- 精英宝典已开通;
- 积分达到订单要求;
- 角色状态满足后续兑换流程。
积分不足和未开通宝典是否阻止分配,由具体履约策略决定。当前直播履约把它们作为软条件,
允许先绑定角色,再充值或开通。
### 可分配
` allocatable` 表示账号现在能否分配给订单:
- 官网可兑换;
- 账号生命周期可用且允许自动管理;
- CK 检测新鲜;
- 没有有效租约;
- 没有活动外部协作单;
- 角色换绑冷却已结束;
- 归属符合账号池规则;
- 不违反内部 365 天不可重复使用规则;
- 满足当前订单的必要资源策略。
官网可兑换但已有租约时,账号必须在账号管理里显示为“官网可兑换,当前任务占用”,
不能因为官网结果而释放或覆盖本地租约。
## 事实源与冲突处理
| 数据 | 当前事实源 | 本地处理 |
| --- | --- | --- |
| 商品是否限兑 | 官网 | 官网结果覆盖当前能力投影 |
| 商品开放时间、库存 | 官网 | 更新商品目录和账号商品状态 |
| 积分、鱼翅、宝典状态 | 官网 | 官网结果覆盖账号当前字段 |
| 官方兑换记录 | 官网 | 幂等补入 ` account_events`,不删除历史 |
| 官网查询时间、失败原因 | 本地 | 写入同步运行记录 |
| CK、登录和重登过程 | 本地 | 由账号生命周期管理 |
| 租约、履约任务、协作单 | 本地 | 本地业务事实优先 |
| 账号归属和维护责任 | 本地 | 官网无权覆盖 |
| 内部 365 天规则 | 本地业务政策 | 独立于官网可兑换状态 |
冲突处理规则:
1. 官网明确返回新的当前状态时,更新本地当前投影;
2. 官网未返回、接口失败或结果不完整时,保留上一次有效结论;
3. 官网说“可兑换”,不能删除本地有效租约或其他内部占用;
4. 官网说“限兑”,应立即从自动选号候选中移除;
5. 本地有兑换事件但官网暂时没有记录时,保留本地事实并标记待核对;
6. 官网记录晚到后只补事实,不回滚已经完成的内部流程。
## 统一候选查询
账号管理和自动选号应调用同一个候选查询服务,输入至少包括:
- 平台和作用域;
- 商品 ID;
- 是否只允许自动管理;
- 是否允许过期能力复核;
- 是否要求积分足够或宝典已开通;
- 归属和客服范围;
- 是否包含已被租约或协作单占用的账号;
- 排序和分页。
基础候选条件:
` ``text
accounts.status 可用
AND accounts.auto_managed = 1
AND accounts.ck_check_status = 'valid'
AND CK 检测时间不早于 Cookie 更新时间
AND account_commodity_states.availability = 'available'
AND 商品时间窗口允许兑换
AND NOT EXISTS 有效账号租约
AND NOT EXISTS 活动外部协作单
AND 角色换绑冷却已结束
AND 归属符合账号池规则
AND 不违反内部兑换冷却
` ``
排序建议:
1. 新鲜 ` available`;
2. 过期但曾经 ` available`,允许官网复核;
3. 从未查询或 ` unknown`;
4. 已知 ` limited / no_stock / not_open / expired` 默认不进入候选。
候选结果必须同时返回阻塞诊断,例如:
- 官网限兑;
- 无库存;
- 未开放;
- CK 失效;
- 角色换绑冷却;
- 有效租约;
- 活动协作单;
- 归属不符合;
- 365 天内兑换过;
- 数据过期。
## 自动选号流程
1. 订单完成商品映射,得到 ` commodity_id`;
2. 查询本地统一候选服务,不直接发起大量官网请求;
3. 优先选择新鲜 ` available` 候选;
4. 没有新鲜候选时,触发对应账号的官网能力刷新;
5. 对排序最靠前的少量账号做官网实时确认;
6. 用官网结果更新 ` account_commodity_states`;
7. 官网确认仍可用后,依赖数据库唯一约束领取租约;
8. 分配成功后立即开始绑定流程;
9. 官网确认和本地状态不一致时记录诊断,并继续下一个候选。
禁止继续采用“只取前 20 个低积分账号逐个实时检查,全部失败后等待重试”的兜底方式。
已知限兑账号不应反复消耗外部请求,未知账号必须有分批补全机制。
### 并发与连接边界
自动选号和人工重试必须满足以下约束:
1. 同一个履约任务同一时间最多只有一个选号请求,重复点击应合并或返回“选号中”;
2. 前端按钮在请求完成前必须进入 loading/disabled 状态;
3. 候选数据库查询使用短事务,查询完成立即释放连接;
4. 外部账号检测属于长耗时 I/O,不得在整个检测期间一直持有一个 FastAPI 请求事务和
数据库连接;
5. 实时官网确认由独立 Worker 任务槽执行,请求只创建或唤醒任务,不同步占满 API
连接池;
6. 自动选号和人工重试共享同一把任务级互斥锁,不能因为两个入口并行而重复扫描;
7. 数据库连接池大小只是保护阈值,不能通过盲目扩大连接池掩盖请求风暴。
2026-11-21 生产只读检查发现,同一个“人工重试选号”请求在约 0.6 秒内重复进入
14 次。每次请求都会执行多账号实时检查,随后应用连接池达到 ` 20 + 20` 上限并持续
30 秒等待连接,健康检查因 5 秒超时转为 unhealthy。因此请求合并、Worker 隔离和
任务级互斥属于 P0,不是后续体验优化。
处理约定:
- 生产 ` docker-compose.yml` 默认使用 ` DB_POOL_MODE=null` 和
` WORKER_DB_POOL_MODE=null`,Session 关闭即断开物理连接;
- 本地开发可显式改为 ` queue`,保留连接池复用和更低连接建立开销;
- 应用退出时必须调用统一的 ` dispose_engines()`,确保 queue 模式也不会残留连接;
- 人工选号接口只做短数据库校验并写入后台队列,不再同步执行官网账号检测。
## 同步策略
### 触发时机
- 账号首次导入完成后;
- 登录或自动重登成功后;
- CK 从失效恢复为有效后;
- 有 pending 履约订单且对应商品能力过期时;
- 本地兑换成功后立即定向标脏并核对;
- 充值、赠送精英令或开通宝典后;
- 人工点击“立即同步”;
- 周期巡检到期时。
### 同步内容
一次斗鱼完整商品列表请求应更新该账号的全部商品能力,不按商品逐个请求。同步还应根据
配置和需要更新:
- CK 和活动登录态;
- 积分、鱼翅;
- 精英宝典开通和到期;
- 角色绑定与换绑冷却;
- 三个作用域的官方兑换记录;
- 高价值商品准入。
### 新鲜度
新鲜度按业务需求分级,不能所有字段统一使用一个 TTL:
- 有 pending 履约订单的商品:短周期刷新并优先调度;
- 无 pending 订单:慢速周期刷新;
- 兑换后:立即标脏;
- CK 失效:立即作废所有 ` available` 结论;
- 网络错误:保留旧状态,指数退避重试。
过期不等于不可查询。账号管理始终展示最后一次结论和过期状态,自动选号只把过期状态作为
“需要复核”,而不是直接删除。
## 兑换账本
兑换事实继续写入 ` account_events`:
- 实际兑换成功时立即写本地事件;
- 同时更新对应商品能力为 ` limited`;
- 后续官网核对成功时补写 ` official_sync` 事件;
- 官网查询失败或记录暂未出现时,不删除本地事件;
- 同一官网记录重复查询只保留一条;
- 列表和详情优先展示官方记录,同时保留本地执行来源。
兑换记录应支持:
- 按账号查询;
- 按商品反查;
- 按时间范围查询;
- 查看官方记录 ID;
- 查看本地执行时间与官网确认时间;
- 查看待核对、已核对和官网迟到状态。
## 账号管理页面
账号管理应成为账号能力中心的统一入口:
- 按商品筛选 ` available / limited / not_open / unknown`;
- 按商品和兑换时间筛选历史兑换;
- 显示最后官网确认时间和数据是否过期;
- 显示积分、宝典、换绑冷却和 CK 新鲜度;
- 显示当前租约和外部协作单占用;
- 区分“官网可兑换”“资源已就绪”“当前可分配”;
- 支持单账号立即同步;
- 支持针对 pending 商品批量补全能力。
账号详情中的商品能力矩阵和兑换时间线应直接读取本文定义的本地投影与事件账本。
## 代码边界
- 官网请求继续收口在 ` douyu_activity_query.py` 和现有 Runner;
- 官网结果写当前投影必须经过统一的 capability service;
- 兑换等业务事实继续经过 ` account_events_service` / ` business_events`;
- 生命周期状态继续只允许通过 ` account_lifecycle` 写入;
- 自动选号和账号管理必须共享同一个候选查询服务;
- 页面和履约服务不得各自实现一套能力判定。
相关入口:
- ` web/backend/models.py`
- ` web/backend/services/account_capability_service.py`
- ` web/backend/services/account_events_service.py`
- ` web/backend/services/business_events.py`
- ` web/backend/services/douyu_runner_overview.py`
- ` web/backend/services/platform_fulfillment/account_selector.py`
- ` web/backend/services/platform_fulfillment/service.py`
- ` web/backend/services/automation/jobs/account_capability_refresh.py`
## 分阶段落地
### P0:数据正确
1. 补齐有效账号的商品能力矩阵;
2. 修复能力刷新只处理已有商品状态账号的问题;
3. 将新鲜度与可查询性分开;
4. 建立官网同步运行记录;
5. 统一账号商品能力查询口径;
6. 自动选号移除无限实时扫描兜底;
7. 选号 API 增加任务级幂等、请求合并和前端 loading;
8. 外部官网检测迁移到独立 Worker,不长期占用 API 数据库连接。
### P1:业务统一
1. 账号管理和自动选号共享统一候选服务;
2. 增加商品维度筛选和能力诊断;
3. 兑换后自动标脏并核对;
4. 充值、开通、赠送后触发定向刷新;
5. 增加真正的指定账号人工分配能力。
### P2:运营增强
1. 商品能力覆盖率、新鲜度和同步失败率监控;
2. 候选成本排序和账号使用均衡;
3. 官网记录冲突队列;
4. 账号价值、维护成本和使用效率分析。
## 验收标准
1. 任意有效账号都能在本地查询到 60 个商品的最后已知状态或“未查询”;
2. 数据过期仍然可查,但不会直接参与自动分配;
3. 自动选号不再依赖固定的前 20 个低积分账号;
4. 已知限兑账号不会反复消耗实时查询请求;
5. 官网确认结果在一次事务中更新本地投影;
6. 官网失败不覆盖上一次有效结论;
7. 每笔兑换都能查询本地执行来源和官网补录记录;
8. 账号管理和自动选号对同一账号、同一商品给出相同资格结论;
9. 有效租约和协作单永远不会被官网“可兑换”结果覆盖;
10. 生产高峰期不再因为选号扫描产生大量重复外部请求和慢查询。