diff --git a/docs/README.md b/docs/README.md index 26d21f7..5fbc547 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,8 @@ - [自动化与资料收集](自动化与资料收集.md):账号巡检、CK 自动重登、资料刷新、订单读取、文件存储的运行规则。 - [账号全生命周期](设计-账号全生命周期.md):斗鱼账号状态、CK、事件流和自动化边界。 -- [账号能力中心与统一选号](设计-账号能力中心与统一选号.md):官网事实同步、账号商品能力、兑换账本和履约选号的统一数据模型。 +- [账号能力中心与统一选号](斗鱼/设计-账号能力中心与统一选号.md):官网事实同步、账号商品能力、兑换账本和履约选号的统一数据模型。 +- [账号供给库存与 CK 生命周期](斗鱼/账号供给库存与CK生命周期.md):CK 7 天生命周期统计、账号库存目标、覆盖率、查询落库和防重复设计。 - [微博账号池、分配与个人工作台](微博/微博账号池与个人工作台-2026-11-08.md):微博 CK、账号归属、客服可见范围、分配管理和个人工作台。 - [虎牙外部 CK 协作台账](设计-虎牙外部CK协作台账.md):外部订单、CK、业务状态、核账、归档和权限规则。 - [虎牙 Cookie 路线状态](虎牙/HUYA_COOKIE路线状态.md):当前 Cookie 字段来源、已完成链路和已知边界。 @@ -21,6 +22,8 @@ - [直播账号履约工作台](直播账号履约工作台.md):order_site 人工订单、斗鱼账号租约、客户扫码绑定和人工兑换。 - [直播账号履约分类与映射规划](直播账号履约工作台分类与映射规划.md):斗鱼单平台阶段的预售/现货分类、工作队列、映射 CRUD 和分阶段 TODO。 - [斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md):斗鱼绑定、精英宝典、兑换、支付、多 alias 判定和排障日志的统一入口。 +- [斗鱼账号平台最终实施设计](斗鱼/斗鱼账号平台最终实施设计.md):统一查询、同步投影、工作队列、登录预算、供给库存和选号的最终实施主线。 +- [精英宝典商品资格与全量快照](斗鱼/精英宝典商品资格与全量快照.md):`storehome` 单账号全量商品列表、限兑字段、调用边界和抓包证据。 - [数据库迁移规范](数据库迁移规范.md):迁移文件不可变 manifest、启动校验、repair revision 和禁止 stamp 的规则。 ## 协议与逆向证据 diff --git a/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md b/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md index a1e7c1a..2ab34e5 100644 --- a/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md +++ b/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md @@ -5,6 +5,9 @@ 本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码 难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。 +后续模块重构和任务调度实施以 +[斗鱼账号平台最终实施设计](斗鱼账号平台最终实施设计.md) 为主线。 + ## 维护规则 每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文: @@ -180,13 +183,19 @@ docker compose logs douyu-login | grep '确认前状态' | 范围 | 关键接口 | | --- | --- | | 手册用户信息 | `/wgapi/ordnc/activity/peace/getUserInfo` | -| 商品列表 | `/wgapi/ordnc/activity/peace/storehome` | +| 商品列表 / 全量账号资格 | `/wgapi/ordnc/activity/peace/storehome` | | 商品详情 | `/wgapi/ordnc/activity/peace/storedetail` | +| 批量兑换上限 | `/wgapi/ordnc/activity/peace/batchExchangeLimit` | | 锁单 | `/wgapi/ordnc/activity/peace/createExchangeOrder` | | 支付锁单 | `/wgapi/ordnc/activity/peace/payExchangeOrder` | | 锁单列表 | `/wgapi/ordnc/activity/peace/getExchangeOrderList` | | 兑换记录 | `/wgapi/ordnc/activity/peace/exchangeList` | +`storehome` 一次返回当前活动完整商品列表,每项的账号级 `status` 已经表示该账号是否 +达到该商品限兑上限。账号商品资格刷新、限兑批量扫描和自动选号不得按礼包逐个调用 +`storedetail` 或 `batchExchangeLimit`。详细字段、分类顺序和抓包证据见 +[精英宝典商品资格与全量快照](精英宝典商品资格与全量快照.md)。 + 兑换成功的唯一业务收口必须是 `payExchangeOrder` 成功后写入兑换事件;预约到货、 预兑和等待开放即使返回 `success`,也不能当成真实兑换。 @@ -244,3 +253,4 @@ docker compose logs douyu-login | grep '确认前状态' | 日期 | 变更 | | --- | --- | | 2026-11-21 | 建立斗鱼协议总览;补充多 alias 职责、pending 真值表、结构化判定日志和同名 pending 修复记录 | +| 2026-11-21 | 补充 `storehome` 单账号全量商品资格、`storedetail`/`batchExchangeLimit` 边界和抓包证据入口 | diff --git a/docs/斗鱼/斗鱼账号平台最终实施设计.md b/docs/斗鱼/斗鱼账号平台最终实施设计.md new file mode 100644 index 0000000..d543e6c --- /dev/null +++ b/docs/斗鱼/斗鱼账号平台最终实施设计.md @@ -0,0 +1,578 @@ +# 斗鱼账号平台最终实施设计 + +更新时间:2026-11-21 + +状态:最终实施蓝图 + +本文是斗鱼账号平台后续实施的唯一主线。协议细节、字段真值和专项分析保留在其他 +文档中,但模块职责、数据流、调度和实施顺序以本文为准。 + +## 为什么重构 + +当前能力并不缺,主要问题是职责分散: + +- CK 巡检、自动重登、首次登录、资料查询和商品能力刷新各自维护候选条件; +- 很多查询只把结果写入 `douyu_tasks.result`,没有同步到账号数据库; +- `storehome` 已返回全部商品,部分入口却只使用一个商品或只保留限兑子集; +- 登录只有瞬时并发限制,没有每日预算和不可变尝试流水; +- `ck_health` 会重复扫描不应该自动巡检的失效账号; +- 多个自动化作业并行,却没有统一斗鱼请求预算; +- 新鲜度、覆盖率、商品可兑换性和当前可分配性混在不同查询中。 + +继续在现有 Runner 中分别打补丁会让规则更难追踪。最终方案要把平台请求、结果投影、 +账号状态、登录预算、供给目标、选号拆成明确层次。 + +## 最终目标 + +```text +账号导入 + -> 首次登录队列 + -> 获取有效 CK + -> 一次 storehome 全量商品同步 + -> 写账号状态、商品能力和业务事件 + -> 计算价值与有效供给库存 + -> 库存不足时定向补货 + -> 履约和日常任务查本地数据库选号 + -> 最终候选做一次官网复核 + -> CK 巡检 + -> 失效账号进入受预算控制的重登队列 + -> 重登成功后重新同步商品能力 +``` + +最终必须满足: + +1. 所有查询都有明确查询域和本地投影; +2. 任务 JSON 只做追踪,不作为业务数据库; +3. 同账号同查询域不重复并发请求; +4. 一次 `storehome` 更新全部商品; +5. 登录、重登、首次登录、账号检测统一限流; +6. 高价值和普通账号有最低有效库存目标; +7. 账号管理和自动选号共享同一个候选查询服务; +8. 官网失败不覆盖上一次有效状态。 + +## 文档关系 + +| 文档 | 职责 | +| --- | --- | +| 本文 | 模块边界、数据流、调度和实施顺序 | +| [斗鱼协议总览](DOUYU_PROTOCOL_OVERVIEW.md) | 接口、字段优先级和排障 | +| [商品资格与全量快照](精英宝典商品资格与全量快照.md) | `storehome` 协议和字段 | +| [账号能力中心与统一选号](设计-账号能力中心与统一选号.md) | 商品能力、候选和选号专项 | +| [账号供给库存与 CK 生命周期](账号供给库存与CK生命周期.md) | CK、库存、登录预算专项 | +| [账号全生命周期](../设计-账号全生命周期.md) | 账号状态和事件语义 | + +## 七个领域 + +### 1. 账号主数据 + +负责账号、生命周期、CK、积分、鱼翅、角色和价值分档。 + +- 权威表:`accounts`、`account_events` +- 生命周期唯一入口:`account_lifecycle` +- 网络错误、明确 CK 失效、人工停用必须分开。 + +### 2. 平台查询网关 + +统一入口建议为 `DouyuReadGateway`: + +- `probe_session` +- `fetch_storehome_snapshot` +- `fetch_points` +- `fetch_gold_balance` +- `fetch_role` +- `fetch_exchange_records` +- `fetch_goods_detail` +- `fetch_batch_exchange_limit` + +页面、Runner、自动化和履约不得各写一套斗鱼请求逻辑。`storehome` 每账号只请求一次; +`storedetail`、`batchExchangeLimit` 只用于明确单商品操作。 + +### 3. 同步与投影 + +统一入口建议为 `AccountSyncService`,流程: + +1. 检查查询域新鲜度; +2. 获取 single-flight 工作项; +3. 调用平台查询网关; +4. 解析字段; +5. 短事务写当前投影; +6. 写不可变事件; +7. 写同步运行记录; +8. 更新同步状态; +9. 提交后调度下游工作。 + +查询域至少包括: + +- `session` +- `storehome` +- `points` +- `gold` +- `role` +- `exchange_records` + +### 4. 商品能力 + +权威数据: + +- 商品目录:`douyu_goods_snapshot` +- 账号商品能力:`account_commodity_states` +- 兑换事实:`account_events` + +必须区分: + +```text +official_available = 官网当前允许该账号兑换 +resource_ready = 积分、宝典、角色等资源满足 +allocatable = 无租约、无协作单、无冷却,可立即分配 +``` + +`status=1` 只表示账号达到兑换上限。`eliteLimited`、`roomLimited`、库存、开放时间不能 +全部归为 `limited`。 + +### 5. 账号供给 + +回答: + +- 高价值和普通账号有多少; +- 每个商品有多少官网可兑换账号; +- 多少账号资源就绪; +- 多少账号可以立即分配; +- 距业务目标缺多少; +- 应补登录、补商品快照还是停止查询。 + +新增 `account_supply_targets`,按平台、作用域、商品、价值分类设置 covered、available、 +allocatable 和安全库存。 + +### 6. 登录与认证 + +负责首次登录、人工登录、账号检测和自动重登。 + +新增: + +- `login_attempts` +- `login_quota_settings` +- `login_quota_usage` + +所有完整认证流程必须先通过 `LoginQuotaService.reserve()`。同账号 single-flight, +人工和自动不能同时登录同一账号。 + +### 7. 履约与业务任务 + +- 选号先查本地统一候选服务; +- 只对最终候选做官网复核; +- 复核结果通过 `AccountSyncService` 回写; +- 租约和内部 365 天规则优先; +- 写操作使用独立任务槽和代理。 + +## 最终数据模型 + +复用: + +- `accounts` +- `account_events` +- `account_commodity_states` +- `douyu_goods_snapshot` +- `douyu_tasks` +- `login_tasks` +- `account_leases` +- `platform_fulfillment_tasks` + +新增: + +- `account_sync_states`:每账号每查询域当前新鲜度和最后成功时间 +- `account_sync_runs`:每次同步不可变运行记录 +- `account_supply_targets`:高价值、普通和商品库存目标 +- `login_attempts`:每次登录不可变流水 +- `login_quota_settings`:全局、小时、分类、单账号配额 +- `login_quota_usage`:数据库级原子用量 +- `account_work_items`:内部账号维护工作队列 + +## 账号工作队列 + +`account_work_items` 承载内部维护: + +- `ck_probe` +- `storehome_sync` +- `points_sync` +- `gold_sync` +- `role_sync` +- `exchange_records_sync` +- `login_onboarding` +- `login_relogin` + +关键字段: + +- `account_id` +- `work_type` +- `priority` +- `status` +- `due_at` +- `attempt_count` +- `max_attempts` +- `dedupe_key` +- `reason` +- `payload` +- `last_error` + +`dedupe_key` 在 pending/running 状态唯一,例如: + +```text +ck_probe:account_id +storehome:account_id +login:account_id +``` + +`douyu_tasks` 继续表示用户可见业务任务;内部巡检、同步和登录维护进入 +`account_work_items`。 + +## 查询同步契约 + +成功: + +```text +外部响应成功 + -> 归一化 + -> 差异比较 + -> 写当前投影 + -> 写事件 + -> 写 sync_run + -> 更新 sync_state + -> 提交 + -> 任务 success +``` + +失败: + +```text +外部响应失败 + -> 不覆盖业务状态 + -> 写 sync_run + -> 更新 next_retry_at + -> 任务 failed/retry +``` + +缓存复用: + +```text +sync_state 成功 +AND valid_until > now +AND 参数 hash 未变化 +AND force_refresh=false +=> 直接使用本地投影 +``` + +已有 pending/running 工作项时复用,不创建第二条。 + +## 商品快照 + +`StorehomeSnapshot` 至少包含: + +- `account_id` +- `manual_id` +- `rid` +- `observed_at` +- `items[]` +- `by_commodity` +- `limited_ids` +- `success` +- `raw` + +全部派生能力共享同一快照: + +- 限兑列表 +- 全部商品能力 +- 高价值状态 +- 自动选号资格 +- 商品目录 + +一次成功后批量差异 UPSERT,不逐商品请求,不因仅刷新 TTL 而重写全部 60 行。 + +## CK 生命周期 + +生产验证 CK 主寿命约 7 天,明确失效样本平均 7.38 天。 + +新增: + +- `ck_expected_expires_at` +- `ck_last_valid_at` +- `ck_invalid_detected_at` +- `ck_observed_lifetime_seconds` +- `ck_expiry_source` + +状态: + +```text +issued -> valid -> expiring -> invalid -> relogin -> valid + \-> manual +``` + +巡检规则: + +- 高价值 valid:6-12 小时 +- 临近 7 天:3-6 小时 +- 普通 valid:24 小时 +- invalid:进入重登队列,不再普通巡检 +- manual:停止自动处理 +- 登录在途:跳过巡检 + +## 登录预算 + +登录分类: + +- `manual_login` +- `onboarding` +- `relogin_high_value` +- `relogin_ordinary` +- `account_check` + +配额维度: + +- 全局每日/每小时 +- 单账号每日 +- 首次登录 +- 高价值重登 +- 普通重登 +- 人工保留 +- 邮箱验证码 + +优先级: + +1. 人工明确操作 +2. 高价值失效/即将失效 +3. 普通账号失效 +4. 从未登录首次接入 +5. 非紧急刷新 + +预算由库存和周期计算,不写死: + +```text +有效库存维持量 / 7.38 天 ++ 失效积压 / 恢复周期 ++ 未登录积压 / 接入周期 += 每日所需成功数 + +每日所需成功数 / 成功率 ++ 人工保留 += 每日尝试预算 +``` + +当前数据示例约为每天 1,400-1,600 次尝试,最终必须配置化。 + +## 登录成功联动 + +1. 写 `login_attempts` +2. 更新 CK 和预计过期时间 +3. 清重登退避 +4. 生成 `storehome_sync` +5. 标记商品能力待刷新 +6. 更新价值分档 +7. 重算供给库存 + +## 供给与补货 + +有效库存: + +```text +CK valid +AND CK 新鲜度满足 +AND 商品能力新鲜 +AND 官网可兑换 +AND 无租约 +AND 无活动协作单 +AND 角色冷却结束 +``` + +定时计算: + +- 高价值库存 +- 普通库存 +- 每商品 available +- resource_ready +- allocatable +- 未来 24/72 小时 CK 流失 +- 商品快照覆盖率 + +低于 `target + safety_buffer` 时生成补货工作: + +1. 高价值商品能力刷新 +2. 首次登录 +3. 普通商品能力刷新 +4. 达标后停止 +5. 多轮不足则告警 + +## 自动选号 + +统一使用 `AccountCandidateService`: + +```text +账号正常 +AND CK 有效 +AND 商品能力新鲜或可复核 +AND 官网 available +AND 无租约 +AND 无协作单 +AND 无角色冷却 +AND 不违反 365 天规则 +``` + +流程: + +1. 本地数据库筛选 +2. 新鲜 available 优先 +3. 过期但曾 available +4. unknown +5. 只复核最终少量候选 +6. 复核回写同步投影 +7. 唯一约束领取租约 + +禁止固定扫描前 20 个低积分账号。 + +## 自动化作业重构 + +- `ck_health`:只生成/执行 `ck_probe`,不处理 invalid/manual +- `ck_relogin`:读取 `login_relogin` 工作,受登录配额 +- `account_overview_refresh`:拆成 points/gold/role/exchange_records 同步域 +- `account_capability_refresh`:变为 `storehome_sync` 补货工作 +- `platform_fulfillment_lease_reaper`:保持独立 +- `douyu_tasks_retention`:保持独立 + +## 统一预算 + +任务槽仍由 `task_runtime` 管理,但增加持久化域预算: + +| 域 | 示例 | +| --- | --- | +| `auth_login` | 每日/小时登录 | +| `ck_probe` | CK 探针 | +| `storehome` | 商品快照 | +| `account_assets` | 积分/鱼翅/角色 | +| `business_write` | 兑换/支付/锁单/送礼 | + +Runner 启动前必须有预算 token;没有 token 时留在工作队列。 + +## 分阶段实施 + +### 阶段 0:止乱 + +- 危险自动作业保持关闭 +- 人工登录限制单批数量 +- 禁止新增直接斗鱼请求旁路 +- 标记所有未落库查询 + +### 阶段 1:同步基础 + +- 新表迁移 +- `DouyuReadGateway` +- `AccountSyncService` +- `StorehomeSnapshot` +- 查询任务迁移到统一入口 + +### 阶段 2:账号与 CK + +- CK 周期字段 +- invalid/manual 分流 +- `login_attempts` +- 配额服务 +- 所有登录入口接入 + +### 阶段 3:商品与供给 + +- 补齐有效账号商品快照 +- 商品覆盖率 +- 价值分档与库存目标 +- 补货 planner + +### 阶段 4:安全恢复自动化 + +- 自动重登小批量开启 +- 低并发验证 +- 逐步恢复资料同步 +- 按成功率和风控调整预算 + +### 阶段 5:清理旧逻辑 + +删除或降级: + +- Runner 内重复查询后写库 +- 弱投影的 `query_limited_goods` +- 只写全局快照的 `refresh_goods` +- 作业各自拼接候选条件 +- 自动选号 20 个账号实时扫描兜底 +- 绕过登录配额的自动入口 + +## 可观测性 + +必须监控: + +- 有效 CK 数和未来 24/72 小时到期 +- CK 寿命分布和重登成功率 +- 商品覆盖、新鲜度、available/limited/unknown +- 高价值和普通有效库存及目标缺口 +- 每日/小时登录尝试、成功、失败和配额使用 +- 各同步域成功率、耗时、缓存命中、single-flight +- 查询后落库比例和重复请求比例 + +## 最终验收 + +1. 每账号有最后已知商品状态 +2. 每商品状态有来源和观察时间 +3. 每次兑换可从事件账本查询 +4. 每次登录有不可变流水 +5. 每 CK 周期有寿命统计 +6. 一次 `storehome` 更新全部商品 +7. 同账号同查询域不重复并发 +8. 新鲜缓存不重复请求官网 +9. 失败不覆盖旧状态 +10. 任务清理后账号数据完整 +11. 日/小时登录量可限制 +12. 人工和自动登录有独立预算 +13. invalid 不再普通巡检 +14. 自动重登可安全恢复 +15. 选号优先查本地数据库 +16. 复核结果回写账号 +17. 高价值和普通库存有目标 +18. 库存不足能定向补货 +19. 高峰期不打满数据库连接 +20. 不按礼包逐个查询 + +## 不做的事情 + +- 不建第二套账号主表 +- 不把任务 JSON 当账号数据库 +- 不按礼包逐个查限兑 +- 不用 `storedetail` 做全量资格扫描 +- 不在 API 中同步探测几十个账号 +- 无预算不重启大规模自动重登 +- 不让作业自行决定并发和登录量 +- 不用扩大连接池掩盖请求风暴 +- 不盲目全库刷新 + +## 结论 + +最终要建立四层基础: + +```text +统一平台查询网关 ++ 统一账号同步投影 ++ 统一账号工作队列和全局预算 ++ 统一供给库存与候选查询 +``` + +保留现有账号生命周期、事件账本、商品能力表和履约租约。重做外部查询落库、工作生成、 +登录配额、商品能力维护、库存补货和候选查询。完成后 CK 巡检、自动重登、首次登录、 +商品同步、账号管理和履约选号才能协同运行。 + +## 相关文档 + +- [斗鱼协议总览](DOUYU_PROTOCOL_OVERVIEW.md) +- [精英宝典商品资格与全量快照](精英宝典商品资格与全量快照.md) +- [账号能力中心与统一选号](设计-账号能力中心与统一选号.md) +- [账号供给库存与 CK 生命周期](账号供给库存与CK生命周期.md) +- [账号全生命周期](../设计-账号全生命周期.md) +- [自动化与资料收集](../自动化与资料收集.md) + +## 变更记录 + +| 日期 | 变更 | +| --- | --- | +| 2026-11-21 | 建立斗鱼账号平台最终实施蓝图 | diff --git a/docs/斗鱼/精英宝典商品资格与全量快照.md b/docs/斗鱼/精英宝典商品资格与全量快照.md new file mode 100644 index 0000000..3625dc8 --- /dev/null +++ b/docs/斗鱼/精英宝典商品资格与全量快照.md @@ -0,0 +1,343 @@ +# 斗鱼精英宝典商品资格与全量快照 + +更新时间:2026-11-21 + +状态:已验证协议基线 + +本文记录斗鱼精英宝典商城 `storehome` 的全量商品资格接口、字段语义、抓包证据和项目 +写入约束。所有账号商品能力同步、限兑判断、自动选号和账号管理筛选都必须以本文定义 +的“单账号全量快照”为准。 + +整体同步、工作队列和登录供给架构见 +[斗鱼账号平台最终实施设计](斗鱼账号平台最终实施设计.md)。 + +## 核心结论 + +当前账号全部礼包的资格只需要一次请求: + +```text +每个账号请求一次 storehome + -> 返回当前活动的完整商品列表 + -> 每项自带当前账号的限兑状态、开放时间、库存、门槛和房间限制 + -> 一次写入该账号全部 account_commodity_states +``` + +禁止为了查询多个礼包是否限兑而: + +- 每个礼包调用一次 `storehome`; +- 每个礼包调用一次 `storedetail`; +- 每个礼包调用一次 `batchExchangeLimit`; +- 为每个礼包拆成独立斗鱼查询任务。 + +`storedetail` 和 `batchExchangeLimit` 只服务于用户明确打开或准备兑换某个礼包的操作, +不是账号商品资格扫描接口。 + +## 抓包证据 + +已核对的本地抓包: + +- `11.17-精英宝典活动-绑定后-换绑-确认绑定-活动信息.har` +- `11.18-套装-兔兔白日梦限兑.har` +- `11.19-网页幸运币兑换-2.har` +- `11.20-若若跑的贼快抓包.har` + +`11.19-网页幸运币兑换测试.har` 文件尾部不完整,JSON 在 EOF 处截断,未作为接口结论 +证据使用;同一时段以完整的 `11.19-网页幸运币兑换-2.har` 为准。 + +结果: + +| 抓包 | `storehome` | 返回商品数 | `status=1` 商品 | +| --- | ---: | ---: | --- | +| 11.17 | 1 次 | 60 | 0 | +| 11.18 | 1 次 | 60 | `20260120QYOOB_bag10` | +| 11.19 | 每次账号刷新 1 次 | 60 | `20260120QYOOB_bag5`、`20260120QYOOB_bag10` | +| 11.20 | 1 次 | 60 | `20260120QYOOB_bag5`、`20260120QYOOB_bag10` | + +11.18 中 `20260120QYOOB_bag10`(套装-兔兔白日梦)的 `status=1`,其余 59 个商品 +`status=0`。这直接证明账号限兑状态是商品列表的批量返回字段,不需要逐商品查询。 + +## 全量资格接口 + +```http +GET /wgapi/ordnc/activity/peace/storehome + ?manualID=<精英宝典 manualID> + &rid=<当前活动房间 rid> +``` + +### 请求约束 + +- Cookie、Origin、Referer 必须与当前精英宝典商城页面一致; +- `manualID` 使用精英宝典配置,不能使用电竞手册配置; +- `rid` 使用当前精英宝典活动配置; +- 查询属于只读请求,不走写操作代理; +- 仅整份接口成功时才允许覆盖本地商品资格。 + +### 响应结构 + +```json +{ + "error": 0, + "msg": "", + "data": { + "score": 0, + "list": [ + { + "commodityId": "...", + "commodityName": "...", + "score": 1280, + "status": 0, + "storeStatus": 1, + "openStatus": 1, + "count": 6000, + "startTime": "...", + "endTime": "...", + "timeLimited": 1, + "specTimes": [], + "eliteLimited": 1, + "roomLimited": 0, + "limitRoomType": 0, + "preExchange": {} + } + ] + } +} +``` + +`data.list` 是当前活动完整商品列表。一个账号一次响应即可形成该账号全部商品资格快照。 + +## 字段真值表 + +| 字段 | 语义 | 本地处理 | +| --- | --- | --- | +| `commodityId` | 商品唯一标识 | `account_commodity_states.commodity_id` | +| `commodityName` | 商品名 | `commodity_name` | +| `score` | 兑换所需积分 | 商品目录和资源判断 | +| `status=1` | 当前账号已达该商品兑换上限 | `availability=limited`,自动选号硬排除 | +| `status=0` | 当前账号未达兑换上限 | 仍需继续判断库存、时间和开放状态 | +| `storeStatus=0` | 官方商城当前不可售 | `availability=no_stock` | +| `openStatus=0` | 活动尚未开放 | `availability=not_open` | +| `count<=0` | 当前库存不足 | `availability=no_stock` | +| `startTime/endTime` | 商品外层开放窗口 | 与本地时间比较 | +| `timeLimited` | 是否限时开放 | `time_limited` | +| `specTimes` | 一天多场或分段开放计划 | `schedule_json` | +| `eliteLimited=1` | 商品要求精英手册资格 | 单独保存为门槛,不能写成账号限兑 | +| `roomLimited` | 是否限制直播间 | 保存房间限制 | +| `limitRoomType` | 房间限制类型 | 保存限制类型 | +| `limitRooms` | 可用直播间列表 | 按商品目录或原始快照保留 | +| `preExchange.isExists=1` | 当前账号已有预兑记录 | 表示预兑状态,不等于已兑换 | + +`count` 是商品库存,不是该账号还能兑换几次。抓包中存在 `status=1` 且 +`count` 仍为大量正数的情况,因此不能通过库存判断当前账号是否已限兑。 + +## 分类优先级 + +`storehome` 单项归一成本地 `availability` 时必须保持以下顺序: + +1. 时间窗口未开始:`not_open`; +2. 时间窗口已结束:`expired`; +3. `status=1`:`limited`; +4. `storeStatus=0`:`no_stock`; +5. `count<=0`:`no_stock`; +6. `openStatus=0`:`not_open`; +7. `status=0` 且以上条件均通过:`available`; +8. 缺少可判定字段:`unknown`。 + +`eliteLimited`、`roomLimited`、`limitRoomType` 和 `preExchange` 是附加门槛或状态, +不能在分类阶段无条件覆盖成 `limited`。 + +## storedetail 的边界 + +```http +GET /wgapi/ordnc/activity/peace/storedetail + ?manualID= + &commodityID=<单个商品 ID> + &rid= +``` + +该接口用于: + +- 用户打开某个商品详情; +- 兑换前检查指定商品的详细规则; +- 获取商品描述、`batchExchange`、`subscribeType` 等列表中没有的详情字段。 + +11.19 抓包中只对明确打开或兑换的商品 `20260120QYOOB_bag18` 调用了 `storedetail`, +没有遍历全部礼包。 + +禁止在账号资格刷新、批量限兑扫描或自动选号候选扫描中逐商品调用 `storedetail`。 + +## batchExchangeLimit 的边界 + +```http +POST /wgapi/ordnc/activity/peace/batchExchangeLimit +``` + +11.19 抓包示例返回: + +```json +{"error":0,"msg":"请求正常","data":{"limit":"10"}} +``` + +该接口表示“指定批量兑换商品本次可兑换的批量上限”,不是: + +- 当前账号是否已经拥有该套装; +- 当前账号是否达到该套装兑换上限; +- 全活动商品限兑列表; +- 可以批量遍历所有商品判断资格。 + +只在确定商品 `batchExchange=1` 且准备执行批量兑换时调用。 + +## 当前代码路径 + +### 单次 HTTP 入口 + +`core/douyu/activity_client.py`: + +- `list_goods()`:请求 `storehome` 并返回 `data.list`; +- `query_limited_goods()`:复用 `list_goods()`,从完整列表中筛出 `status=1`; +- `query_goods_detail()`:请求单个商品 `storedetail`; +- `batch_exchange_limit()`:请求单个商品批量兑换上限。 + +### 当前只读包装 + +`web/backend/services/douyu_activity_query.py` 当前有两个包装: + +- `query_activity_goods()`:返回完整商品列表; +- `query_limited_goods_result()`:返回受限商品和原始响应。 + +两者底层都是同一个 `storehome` 请求,但调用方可能在不同分支重复请求。 + +### 当前正确路径 + +`query_account_overview` 获取完整商品列表后调用 +`sync_account_goods_states()`,可一次写入全部商品状态。 + +### 当前缺口 + +1. `query_limited_goods` 任务拿到完整 `storehome` 响应,但目前只处理受限商品和 + 高价值套装,没有把全部商品写入 `account_commodity_states`。 +2. 履约实时检测 `refresh_douyu_account_state()` 请求了完整 `storehome`,但只提取 + `limited_ids`,仅为当前订单商品更新一条能力记录,其余商品状态被丢弃。 +3. `probe_account()` 的 `with_eligibility` 和 `with_goods` 是独立分支。未来同时开启 + 两者时,会各请求一次同一个 `storehome`。 +4. 没有统一的快照对象约束所有调用方共享一次响应。 + +## 目标快照契约 + +建议建立唯一快照入口: + +```text +fetch_storehome_snapshot(account, manual_id, rid) +``` + +快照至少包含: + +```text +account_id +manual_id +rid +observed_at +items[] +by_commodity{} +limited_ids +goods_query_ok +raw +``` + +以下能力全部从同一快照派生: + +- 完整商品列表; +- 限兑商品; +- 高价值商品状态; +- 自动选号商品能力; +- `account_commodity_states` 全量投影; +- 商品目录同步。 + +兼容函数 `query_activity_goods()` 和 `query_limited_goods_result()` 可以保留,但必须 +接受或返回同一个快照,不能再次发 HTTP。 + +## 数据库写入约束 + +一次 `storehome` 成功后: + +1. 解析全部 `data.list`; +2. 按商品 ID 去重; +3. 与本地当前投影比较; +4. 只对变化商品做批量 UPSERT; +5. 更新账号级商品目录同步时间; +6. 记录商品数量、限兑数量、活动窗口和失败原因; +7. 整份商品列表失败时不覆盖本地最后一次有效状态。 + +禁止因一次刷新把每行 `valid_until` 都更新而产生数十条无意义 `UPDATE`。新鲜度优先 +使用账号级同步时钟;商品行只记录状态和业务时间变化。 + +## 自动选号约束 + +对任意候选人执行一次实时检查时: + +```text +一次 storehome + -> 更新该账号全部商品状态 + -> 当前订单直接读取目标商品结果 + -> 后续其他订单复用本地结果 +``` + +不能出现: + +```text +订单商品 A -> 查一次账号 A 商品 A +订单商品 B -> 再查一次账号 A 商品 B +``` + +若本地快照仍新鲜,后续商品匹配直接查数据库;只有分配前最终复核才再次请求 +`storehome`。 + +## 日志与可观测性 + +每次账号商品快照同步建议记录: + +- `account_id` +- `manual_id` +- `rid` +- `item_count` +- `limited_count` +- `available_count` +- `not_open_count` +- `no_stock_count` +- `observed_at` +- `source` +- `duration_ms` +- 失败阶段和错误摘要 + +禁止记录 Cookie、CSRF、完整请求头或原始账号凭证。 + +## 回归测试 + +必须覆盖: + +1. `storehome` 一次返回 60 个商品时,只请求一次 HTTP; +2. 同时需要 eligibility 和 goods 时仍只请求一次; +3. `status=1` 准确归为 `limited`; +4. `status=0 + count>0 + 时间有效 + 开放有效` 归为 `available`; +5. `storeStatus=0` 和 `count<=0` 归为 `no_stock`; +6. 时间未到和已结束分别归为 `not_open/expired`; +7. `eliteLimited` 不会被误写成账号限兑; +8. 完整快照成功后一次批量更新全部商品; +9. 商品状态未变化时不产生无意义逐行更新; +10. `storedetail` 和 `batchExchangeLimit` 不会出现在全量资格扫描调用链中。 + +## 相关代码 + +- `core/douyu/activity_client.py` +- `web/backend/services/douyu_activity_query.py` +- `web/backend/services/douyu_account_probe.py` +- `web/backend/services/douyu_account_state.py` +- `web/backend/services/douyu_runner_overview.py` +- `web/backend/services/douyu_runner_goods.py` +- `web/backend/services/account_capability_service.py` +- `web/backend/services/platform_fulfillment/account_selector.py` + +## 变更记录 + +| 日期 | 变更 | +| --- | --- | +| 2026-11-21 | 根据 4 组有效抓包确认 `storehome` 为单账号全量商品资格接口,记录字段、边界、当前代码缺口和实施约束 | diff --git a/docs/设计-账号能力中心与统一选号.md b/docs/斗鱼/设计-账号能力中心与统一选号.md similarity index 95% rename from docs/设计-账号能力中心与统一选号.md rename to docs/斗鱼/设计-账号能力中心与统一选号.md index 7f5c9ca..ee4445f 100644 --- a/docs/设计-账号能力中心与统一选号.md +++ b/docs/斗鱼/设计-账号能力中心与统一选号.md @@ -4,6 +4,10 @@ 状态:设计基线,后续代码按本文分阶段落地 +最终模块边界和实施顺序以 +[斗鱼账号平台最终实施设计](斗鱼账号平台最终实施设计.md) 为准;本文保留商品能力和 +统一选号的专项设计。 + ## 目标 把账号管理、账号全生命周期、一键查询和直播账号履约选号统一到同一份本地账号数据上: @@ -80,6 +84,9 @@ 账号生命周期写入继续遵守 `account_lifecycle` 的唯一写入口约束。 +CK 生命周期、账号库存目标、覆盖率、查询同步契约和防重复查询的详细设计见 +[账号供给库存与 CK 生命周期](账号供给库存与CK生命周期.md)。 + ### 商品目录 商品目录回答“斗鱼当前有哪些商品、何时开放、需要多少积分、是否有库存”: @@ -315,6 +322,14 @@ AND 不违反内部兑换冷却 - 三个作用域的官方兑换记录; - 高价值商品准入。 +斗鱼精英宝典的 `storehome` 已验证为单账号全量商品资格接口:一次请求返回当前活动约 +60 个商品,每项都包含该账号的 `status`、库存、开放时间、精英手册门槛和房间限制。 +限兑列表、商品能力投影、高价值判断和自动选号必须消费同一份快照,不得按礼包调用 +`storedetail` 或 `batchExchangeLimit`。 + +详细协议、字段真值表、抓包证据和当前代码缺口见 +[精英宝典商品资格与全量快照](精英宝典商品资格与全量快照.md)。 + ### 新鲜度 新鲜度按业务需求分级,不能所有字段统一使用一个 TTL: diff --git a/docs/斗鱼/账号供给库存与CK生命周期.md b/docs/斗鱼/账号供给库存与CK生命周期.md new file mode 100644 index 0000000..f16995c --- /dev/null +++ b/docs/斗鱼/账号供给库存与CK生命周期.md @@ -0,0 +1,807 @@ +# 斗鱼账号供给库存与 CK 生命周期 + +更新时间:2026-11-21 + +状态:设计基线,待分阶段实现 + +## 目标 + +把斗鱼账号从“很多账号的集合”升级为可计算、可持续补货的账号供给池: + +1. 统计 CK 实际可存活时间,并记录每个账号当前 CK 的生命周期; +2. 区分高价值账号和普通账号,设置最低可用库存目标; +3. 记录每个账号当前能兑换的全部商品; +4. 持续补全 CK 有效账号的本地商品能力,避免选号时临时大量查询; +5. 保证每一次斗鱼查询都把有效结果投影回账号数据库; +6. 对相同账号、相同查询域复用新鲜结果,避免重复查询; +7. 当高价值或普通账号库存低于目标时,自动扩大覆盖和触发补货。 + +本文讨论的是账号内部维护、自动化和履约供给,不处理 order_site 订单本身。 + +## CK 生命周期统计 + +### 当前字段 + +`accounts` 当前已有: + +- `cookie_updated_at`:当前 CK 写入时间,可作为本轮生命周期起点; +- `ck_check_status`:`valid / invalid / error / 空`; +- `ck_checked_at`:最近一次形成 CK 结论的时间; +- `ck_check_result`:最近一次检测摘要; +- `relogin_attempts`、`relogin_next_at`、`relogin_failure_kind`:自动重登状态; +- `account_events.login_ok / relogin_ok / ck_invalid`:历史登录和失效事件。 + +### 2026-11-21 生产只读统计 + +当前有效 CK 的年龄分布: + +| 距 `cookie_updated_at` | 账号数 | +| --- | ---: | +| `<1 天` | 1,714 | +| `1-3 天` | 1,275 | +| `3-5 天` | 1,318 | +| `5-7 天` | 783 | +| `7-10 天` | 295 | +| `>=10 天` | 0 | + +近 180 天,排除网络超时后的明确登录失效事件: + +- 有效样本:17,295 次; +- 涉及账号:14,500 个; +- 从上一次 `login_ok/relogin_ok` 到首次检测为失效: + - 平均:7.38 天; + - 最短:0.48 天; + - 最长:15.86 天; + - `7-8 天`:16,929 次,占绝大多数; + - `8-10 天`:105 次; + - `>=10 天`:243 次; + - `<7 天`:18 次。 + +结论:斗鱼账号 CK 的主生命周期约为 7 天。当前巡检通常每 6 小时一次,因此 +`ck_invalid` 事件记录的是“首次检测到失效时间”,真实失效点通常早于事件时间, +不能把它当成精确到秒的官方过期时间。 + +### 不应混淆的 Cookie + +抓包中 `acf_ccn` 的 Set-Cookie 可能出现约 2 小时过期时间,这是活动 CSRF/会话辅助 +Cookie,不是整个斗鱼账号 CK 的 7 天生命周期。 + +不能使用 `acf_ccn` 的过期时间覆盖账号 CK 生命周期统计。 + +### 建议新增字段 + +在 `accounts` 保存当前 CK 周期的摘要: + +| 字段 | 含义 | +| --- | --- | +| `ck_expected_expires_at` | 根据历史统计预测的过期时间,默认约为签发后 7 天 | +| `ck_last_valid_at` | 最近一次明确检测有效的时间 | +| `ck_invalid_detected_at` | 当前 CK 首次被检测为失效的时间 | +| `ck_observed_lifetime_seconds` | `ck_invalid_detected_at - cookie_updated_at` | +| `ck_expiry_source` | `observed / predicted / provider_expiry` | +| `ck_last_success_sync_at` | 最近一次成功完成账号查询同步的时间 | + +历史周期不覆盖。完整生命周期继续由 `account_events` 记录: + +- CK 签发:`login_ok / relogin_ok` +- 首次失效:`ck_invalid` +- 后续恢复:新的 `relogin_ok` +- 网络超时:`query_failed` 或专用错误事件,不能写成 `ck_invalid` + +### 字段状态变化 + +登录成功: + +```text +cookie_updated_at = now +ck_check_status = 本次探针结果 +ck_last_valid_at = now(探针有效时) +ck_expected_expires_at = now + 7d(预测口径) +ck_invalid_detected_at = NULL +ck_observed_lifetime_seconds = NULL +``` + +检测有效: + +```text +ck_check_status = valid +ck_last_valid_at = checked_at +``` + +明确未登录: + +```text +ck_check_status = invalid +ck_invalid_detected_at = checked_at +ck_observed_lifetime_seconds = + checked_at - cookie_updated_at +``` + +网络超时/接口异常: + +```text +ck_check_status = error +ck_invalid_detected_at 不变 +ck_observed_lifetime_seconds 不变 +写查询失败记录,不写 CK 失效事件 +``` + +## 账号价值与供给分类 + +现有价值分档在 `account_value.py`: + +- 第 1 档:高价值套装两套都还能换; +- 第 2 档:还剩一套能换,或积分达到高价值阈值; +- 第 3 档:有鱼翅或精英宝典已开通; +- 第 4 档:查询过但无高价值信号; +- 第 5 档:尚未查询。 + +当前口径下第 1、2 档为高价值账号。 + +2026-11-21 有效且正常状态账号的只读统计: + +| 分类 | 账号数 | +| --- | ---: | +| 两套都可用 | 547 | +| 高价值第 2 档 | 2,247 | +| 普通账号 | 2,591 | + +业务需要为不同商品和账号类型设置最低供给量,不能只看账号总数。 + +## 账号库存目标 + +建议新增 `account_supply_targets`: + +| 字段 | 含义 | +| --- | --- | +| `platform` | `douyu` | +| `scope` | `elite` 等 | +| `commodity_id` | 目标商品;空表示账号类型总目标 | +| `value_class` | `high_value / ordinary` | +| `target_covered` | 至少需要多少账号有本地商品状态 | +| `target_official_available` | 至少多少账号官网仍可兑换 | +| `target_allocatable` | 至少多少账号可立即分配 | +| `safety_buffer` | 为 7 天 CK 流失和并发租约预留的缓冲 | +| `enabled` | 是否启用 | +| `updated_by / updated_at` | 配置审计 | + +目标必须使用“有效库存”,不能使用账号总行数: + +```text +有效库存 = + CK valid 且未超过新鲜阈值 + AND 商品状态新鲜 + AND 官网 status=0 且库存/时间/开放状态允许 + AND 无有效租约 + AND 无活动外部协作单 + AND 角色换绑冷却已结束 + AND 不属于停用/归档 +``` + +对于要求积分或精英宝典的商品,再区分: + +- `resource_ready`:积分足够且宝典已开通; +- `needs_recharge`:官网可兑换,但积分不足; +- `needs_open`:官网可兑换,但宝典未开通; +- `blocked`:官网限兑、无库存、未开放或冷却。 + +## 库存预警与补货 + +每日或每小时计算: + +```text +covered_count +fresh_count +official_available_count +resource_ready_count +allocatable_count +leased_count +expiring_ck_count +``` + +按商品、价值分类和目标比较: + +```text +shortage = max(0, target + safety_buffer - effective_available) +``` + +短缺时: + +1. 优先刷新从未查询或状态过期的高价值账号; +2. 再刷新普通账号; +3. 只查询 `storehome` 一次,写入全部商品状态; +4. 不因为一个商品而逐礼包请求; +5. 达到目标后停止补货,避免无意义扫库; +6. 连续多轮仍不足时告警,说明真实账号池不足或接口/风控异常。 + +## 覆盖率目标 + +建议分别监控: + +- CK 有效账号覆盖率; +- 最近一次完整商品快照覆盖率; +- 新鲜商品快照覆盖率; +- 每件商品的 `available / limited / unknown` 覆盖率; +- 高价值账号覆盖率和普通账号覆盖率。 + +2026-11-21 只读快照: + +- CK 有效且正常状态账号:5,385; +- 做过一键查询:4,420; +- 当前 15 分钟 TTL 内的新鲜能力账号:211。 + +15 分钟 TTL 只适合“能否立即分配”,不等于数据库覆盖。长期覆盖应使用“最后 +已知状态 + 新鲜度标记”,不能因为 TTL 过期就从账号数据库删除或忽略状态。 + +## 每一次查询都必须同步 + +查询任务结果不能只保存在 `douyu_tasks.result`。任务有保留期,清理后会导致账号 +数据库出现信息空洞。 + +每个查询域必须定义唯一投影: + +| 查询域 | 必须同步到 | +| --- | --- | +| CK/session 检测 | `accounts` CK 字段、`account_events` | +| `storehome` 商品列表 | 全部 `account_commodity_states`、高价值状态 | +| 积分 | `accounts.points`、积分事件/查询运行记录 | +| 鱼翅余额 | `accounts.gold_balance`、查询运行记录 | +| 游戏角色/换绑时间 | `accounts` 角色和冷却字段 | +| 官方兑换记录 | `account_events` 官方兑换事件 | +| 商品详情 | 指定商品补充字段或商品目录 | +| 批量兑换上限 | 查询运行记录;业务事实不因查询改变 | + +当前已识别的缺口: + +1. `query_limited_goods` 已取得完整 `storehome`,但没有同步全部 + `account_commodity_states`; +2. `query_exchange_records` 只把记录写进任务结果,没有幂等补入 + `account_events`; +3. `refresh_goods` 只更新全局商品快照和高价值状态,没有同步该账号全部商品能力; +4. 履约实时检测只为当前订单商品写一条能力,完整快照中的其余商品被丢弃; +5. 部分查询没有统一的最后成功时间和可复用判断。 + +## 查询同步状态 + +建议新增两类同步数据: + +### `account_sync_states` + +每个账号、平台、查询域一行: + +- `account_id` +- `platform` +- `domain` +- `last_attempt_at` +- `last_success_at` +- `valid_until` +- `next_retry_at` +- `last_error` +- `source` +- `payload_hash` + +用于判断能否复用本地结果。 + +### `account_sync_runs` + +每次查询尝试一行,只追加: + +- `account_id` +- `domain` +- `task_id` +- `started_at / finished_at` +- `status` +- `source` +- `item_count` +- `changed_count` +- `error_code / error_message` +- `official_observed_at` + +用于统计覆盖率、失败率、查询耗时和审计。 + +## 防重复查询 + +自动查询入口先检查 `account_sync_states`: + +```text +last_success_at 仍新鲜 +AND payload 参数未变 +AND 没有 force_refresh +=> 直接复用本地投影,不创建斗鱼任务 +``` + +以下条件允许强制刷新: + +- 用户明确点击刷新; +- 有 pending 订单且数据过期; +- 兑换、充值、开通、换绑后的定向刷新; +- CK 刚恢复; +- 商品开放窗口发生边界变化。 + +同一账号同一查询域必须有 single-flight: + +- 已有 pending/running 任务时复用该任务; +- 不重复创建第二把查询任务; +- 手动重复点击合并; +- 不同查询域可以并行,但同一域不能并发。 + +## 查询后写库顺序 + +一次成功查询: + +1. 解析官网响应; +2. 在短事务内写账号字段; +3. 写全部商品能力投影; +4. 幂等写业务事件; +5. 写 `account_sync_runs`; +6. 更新 `account_sync_states`; +7. 提交数据库; +8. 最后再更新任务为 success。 + +查询失败: + +1. 不覆盖账号和商品业务字段; +2. 写失败运行记录; +3. 更新 `next_retry_at` 和错误摘要; +4. 网络错误不能写成 CK invalid; +5. 任务失败保留可诊断原因。 + +## 推荐表结构 + +当前优先复用: + +- `accounts` +- `account_events` +- `account_commodity_states` +- `douyu_goods_snapshot` + +建议新增: + +- `account_sync_states` +- `account_sync_runs` +- `account_supply_targets` +- `login_attempts` +- `login_quota_settings` +- `login_quota_usage` + +暂不新增重复的“账号商品历史表”。商品状态变化写事件,当前状态继续使用 +`account_commodity_states`。 + +## 调度策略 + +把同步分成四条独立路径: + +1. CK 健康与重登:保障账号可用; +2. 商品资格同步:每账号一次 `storehome`,写全部商品; +3. 账号资料同步:积分、鱼翅、角色、兑换记录; +4. 供给补货:按库存目标选择账号,不按全库无条件刷新。 + +高价值账号: + +- 更频繁检查 CK; +- 库存短缺时优先补商品能力; +- 接近 7 天时进入重点观察; +- 失效后优先重登。 + +普通账号: + +- 正常周期巡检; +- 作为高价值库存不足时的后备供给; +- 仍保证完整商品快照,避免找号时临时查询。 + +## 斗鱼自动化全景 + +斗鱼相关自动化必须作为一个闭环管理,不能只分别调任务并发: + +```text +账号导入 + -> 首次登录 + -> CK 有效 + -> 商品能力同步 + -> 账号价值分档 + -> 供给库存统计 + -> 履约/日常任务选号 + -> CK 巡检 + -> 失效重登或补新号 + -> 重新同步商品能力 +``` + +### 当前自动化作业 + +截至 2026-11-21 生产状态: + +| 作业 | 状态 | 当前配置 | 作用 | +| --- | --- | --- | --- | +| `ck_health` | 开启 | 每 5 分钟一轮,每轮 200,并发 5 | 高价值账号约 6 小时重检,普通账号约 24 小时 | +| `account_capability_refresh` | 开启 | 每 5 分钟一轮,每轮 100,并发 3 | 刷新有 pending 履约商品能力的账号 | +| `account_overview_refresh` | 关闭 | 每轮 300,并发 3 | 曾因单轮 29 个账号全部失败并触发熔断 | +| `ck_relogin` | 关闭 | 每轮 30,并发 3 | 自动重登自 2026-10-06 后未再运行 | +| `douyu_tasks_retention` | 开启 | 每批 2000 | 清理斗鱼任务日志 | +| `points_expire_check` | 关闭 | 每天 | 积分到期补记 | +| `platform_fulfillment_lease_reaper` | 关闭 | 每 60 秒 | 回收过期履约租约 | + +### 当前账号状态 + +2026-11-21 生产只读快照: + +| 状态 | 数量 | +| --- | ---: | +| 账号总数 | 31,253 | +| 曾取得 Cookie | 25,569 | +| 从未登录 | 5,684 | +| CK 有效且正常 | 5,383 | +| CK 失效 | 19,987 | +| 待人工 | 199 | + +CK 有效账号中: + +- 6 天内:5,050; +- 6-7 天:40; +- 已超过 7 天但仍检测有效:293。 + +失效账号中当前可判断为高价值第 2 档的只有 133 个,绝大多数失效账号是 +`ordinary_or_unknown`。这不代表这些号没有价值,而是因为从未完成有效查询,本地无法分档。 + +### 当前登录量 + +最近 14 天账号事件中的成功登录/重登: + +- 2026-11-21:1,241 次普通登录成功、5 次重登成功; +- 2026-11-20:1,481 次普通登录成功、400 次重登成功; +- 2026-11-18:1,028 次普通登录成功、136 次重登成功。 + +说明生产高峰一天实际可发生约 1,800 次成功认证操作,目前没有每日或每小时硬上限。 + +## 当前登录控制缺口 + +### 只有并发,没有预算 + +当前登录控制主要是: + +- API 请求可以提交任意长度的 `account_ids`; +- 单批次并发限制在 1-10; +- 全局 `LOGIN` 任务槽 4 个 worker; +- 单账号默认最多重试 20 次; +- 自动重登每轮最多 30,并发最多 8; +- 没有每日、每小时、账号类型或来源维度的配额。 + +这意味着自动重登和人工批量登录同时运行时,只能靠任务槽限制瞬时并发,不能限制一整天的总量。 + +### 没有不可变登录尝试流水 + +`login_tasks` 会复用最近失败记录,`attempt_at` 只保留最近尝试。它能保护 CK +不被失败覆盖,但不能回答: + +- 某天到底发起了多少次登录; +- 每个账号今天登录尝试了几次; +- 自动和人工各占多少; +- 每种失败原因每天发生多少次; +- 当日配额还剩多少。 + +`account_events` 能记录明确的成功和账号级失败,但不是完整的发起、重试和中断流水。 + +### 巡检会重复检查失效账号 + +当前 `ck_health` 候选条件主要看是否有 Cookie、是否在途和检查时间,没有按生命周期状态 +把 `invalid/manual` 分流。失效账号可能继续进入 CK 巡检,但正确动作应该是进入重登队列或 +等待人工,而不是每天重复探针。 + +### 自动重登长期关闭 + +`ck_relogin` 当前关闭,CK 失效账号已经积压约 2 万。直接重新开启当前配置,可能每 5 分钟 +拉起最多 30 个账号,瞬时并发 3,形成不可控的连续登录。 + +### 账号资料刷新因熔断关闭 + +`account_overview_refresh` 曾因一轮 29 个账号全部失败而自动关闭。重新开启前必须先解决: + +- CK 质量筛选; +- 活动登录态与基础 CK 的区分; +- 并发和失败熔断; +- 轻量商品快照与完整资料同步的拆分。 + +## 登录工作分类 + +所有登录类操作必须先归类,不能共用一个无上限队列: + +| 类型 | 示例 | 是否计入登录预算 | +| --- | --- | --- | +| `manual_login` | 客服手动登录指定账号 | 计入,但有保留额度 | +| `onboarding` | 从未登录账号首次登录 | 计入 | +| `relogin_high_value` | 高价值账号失效重登 | 计入,高优先级 | +| `relogin_ordinary` | 普通账号失效重登 | 计入 | +| `account_check` | 使用完整凭据执行账号状态检测 | 计入登录类操作 | +| `ck_health` | 只访问已有 Cookie 的轻量探针 | 不计入登录,但计入 CK 巡检预算 | + +只有“读取当前 Cookie 判断是否仍登录”的轻量检测不算登录。只要执行账号密码、邮箱验证码、 +极验或完整认证链路,就必须进入登录配额。 + +## 每日登录预算 + +### 不能只设置一个死数字 + +每日预算应该由有效库存、CK 寿命、失效积压、未登录库存和补全周期共同计算: + +```text +retention_success_per_day = + ceil(target_valid_accounts / observed_lifetime_days) + +invalid_recovery_per_day = + ceil(invalid_backlog / recovery_days) + +onboarding_per_day = + ceil(never_logged_accounts / onboarding_days) + +required_success_per_day = + retention_success_per_day + + invalid_recovery_per_day + + onboarding_per_day + +attempt_budget = + ceil(required_success_per_day / expected_success_rate) + + manual_reserve +``` + +按当前数据做一个示例,不代表最终业务配置: + +```text +5,383 个有效账号 / 7.38 天 ≈ 730 个成功/天 +20,000 个失效账号 / 60 天 ≈ 333 个成功/天 +5,684 个未登录账号 / 60 天 ≈ 95 个成功/天 +合计约 1,158 个成功/天 +按 80% 成功率约需 1,448 次尝试/天 +``` + +因此可以设计每日登录尝试总预算约 1,400-1,600,但必须做成配置和动态计算,而不是写死。 + +### 多级配额 + +建议同时限制: + +- 全局每日尝试数; +- 全局每小时尝试数; +- 单账号每日尝试数; +- 单账号最短重试间隔; +- 自动重登每日上限; +- 未登录账号首次登录每日上限; +- 人工登录保留额度; +- 邮件验证码每日上限; +- 失败率熔断阈值。 + +例如可以按小时平滑,而不是凌晨一次跑完: + +```text +日预算 1,500 +小时预算 70-100 +允许短时 burst 120 +失败率超过 40% 自动暂停 +``` + +实际值必须结合代理池容量、邮箱取码能力和斗鱼风控反馈调整。 + +### 来源优先级 + +建议的统一优先级: + +1. 人工明确操作; +2. 高价值账号即将过期/已失效; +3. 普通账号已失效; +4. 从未登录账号首次接入; +5. 非紧急周期刷新。 + +每档都要有最大占比,避免高价值账号长期占满所有自动登录预算,也避免未登录补库挤掉 +正在履约的账号。 + +## 不可变登录尝试流水 + +建议新增 `login_attempts`: + +| 字段 | 含义 | +| --- | --- | +| `id` | 尝试流水 | +| `account_id` | 账号 | +| `batch_id` | 关联批次 | +| `category` | manual/onboarding/relogin/account_check | +| `trigger_source` | user/automation | +| `created_by` | 人工用户;自动为空 | +| `started_at / finished_at` | 尝试时间 | +| `status` | pending/running/success/failed/stopped/interrupted | +| `failure_kind` | captcha/credential/email_code/email_quota/network | +| `proxy_key` | 代理平台或脱敏代理标识 | +| `email_code_requested` | 是否请求过邮箱验证码 | +| `duration_ms` | 耗时 | +| `quota_day` | 按业务时区归档的日期 | + +`login_tasks` 继续表示账号当前尝试投影;`login_attempts` 保存不可变历史。 + +## 配额服务 + +所有登录入口必须先原子预占配额: + +```text +LoginQuotaService.reserve(account_id, category, source) +``` + +检查: + +- 全局日/小时预算; +- category 子预算; +- 单账号当日次数; +- 是否已有 pending/running 登录; +- 是否处于失败退避; +- 是否命中全局熔断。 + +预占成功后才创建 `login_attempts` 和启动登录 runner。达到上限时返回剩余时间和队列状态, +不能静默跳过,也不能让自动作业无限重试。 + +## 未登录账号接入 + +当前 5,684 个账号从未取得 Cookie,是重要的潜在供给,但不能一次全部登录。 + +建议接入流程: + +1. 按导入来源、标签、历史归属和人工优先级排序; +2. 每日分配固定 onboarding 配额; +3. 运行前检查是否已有在途登录; +4. 登录成功后立即触发一次 `storehome` 全量快照; +5. 更新价值分档和供给库存; +6. 登录失败按原因退避,不重复撞同一账号; +7. 极验、凭证、必须绑手机号直接转人工; +8. 邮箱验证码和邮箱配额单独限流。 + +这样首次登录不仅增加“有效 CK 数”,还同时增加“可兑换商品覆盖数”。 + +## CK 巡检配合优化 + +巡检必须感知账号生命周期: + +- `valid`:按预计到期时间安排探针; +- 接近预计到期:提高优先级; +- `invalid`:不再重复做普通巡检,进入重登候选; +- `manual`:不自动巡检/重登,等待人工; +- 登录在途:跳过巡检; +- 查询异常:短退避,不修改 CK 失效时间; +- 刚登录成功:立即形成一次有效结论。 + +建议调度: + +```text +高价值 valid:6-12 小时 +高价值临近 7 天:3-6 小时 +普通 valid:24 小时 +普通临近 7 天:6-12 小时 +invalid:进入 relogin 队列,不重复巡检 +manual:停止自动化 +``` + +## 登录成功后的联动 + +登录成功不能只结束任务,必须触发: + +1. 更新 `cookie_updated_at`、预计过期时间和 CK 周期; +2. 写入不可变登录成功流水; +3. 清除重登退避; +4. 将账号商品能力标脏; +5. 创建一次全量 `storehome` 同步; +6. 更新价值分档; +7. 重新计算商品和账号库存; +8. 反馈给登录配额和巡检调度。 + +登录失败也必须写流水和失败分型,但不能覆盖旧 CK 和旧商品能力。 + +## 全局限流与熔断 + +需要独立预算的斗鱼查询域: + +- 登录/重登/账号检测; +- CK 健康探针; +- `storehome` 商品快照; +- 积分、鱼翅和角色查询; +- 兑换记录; +- 兑换、支付、锁单等写操作。 + +任一域出现以下情况应自动暂停: + +- 连续网络失败; +- 活动接口大面积重定向登录; +- 登录成功率骤降; +- 验证码/极验验证比例骤升; +- 代理异常; +- 数据库锁等待或连接异常。 + +## 实施顺序 + +### P0:可观测与硬限流 + +1. 新增 `login_attempts`; +2. 新增配额配置和原子预占; +3. 人工登录、自动重登、账号检测统一接入; +4. `ck_health` 排除 invalid/manual; +5. 登录入口限制单批账号数; +6. 失败率熔断。 + +### P1:分优先级和安全开启重登 + +1. 高价值/普通/未登录三类队列; +2. 先以每日 30-50 个小批量开启 `ck_relogin`; +3. 监控成功率和失败分型; +4. 再逐步提升到计算预算; +5. 恢复账号资料刷新的小批量试运行。 + +### P2:供给库存驱动 + +1. 建立 `account_supply_targets`; +2. 计算高价值和普通有效库存; +3. 库存不足时触发定向登录和商品同步; +4. 库存满足时自动降低登录和查询频率。 + +## 建议统计指标 + +CK: + +- 各年龄段有效 CK 数量; +- 未来 24/72 小时预计到期数量; +- 实际失效周期平均值、7 天占比; +- 重登成功率、人工失败率; +- 网络错误与登录失效比例。 + +商品: + +- 每商品已覆盖账号数; +- 新鲜 `available / limited / unknown` 数; +- 资源就绪数; +- 当前租约占用数; +- 目标缺口和安全库存。 + +查询: + +- 每域查询次数; +- 缓存命中率; +- 重复任务合并次数; +- 查询成功率和平均耗时; +- 每种查询写回账号数据库的比例。 + +登录: + +- 每日/每小时尝试数、成功数、失败数; +- 各来源、各登录分类的配额使用率; +- 单账号重复尝试次数; +- 邮箱验证码请求量; +- 首次登录转化率和成本; +- 自动重登触发到成功的延迟; +- 因配额被延后的账号数和预计等待时间。 + +## 验收标准 + +1. 每个 CK 周期都有签发、有效、失效和观测寿命记录; +2. 网络错误和明确登录失效分开; +3. 可以统计 7 天到期占比和未来 24/72 小时到期量; +4. 可以按商品、账号价值、新鲜度统计有效库存; +5. 高价值和普通账号均可配置最低库存目标; +6. 每个 `storehome` 查询一次写入该账号全部商品; +7. 所有业务查询都有本地投影,不仅存在任务结果; +8. 查询域有最后成功时间和 TTL; +9. 新鲜数据不会重复创建官网查询任务; +10. 相同账号、相同查询域不会并发重复查询; +11. CK 即将到期时能提前预警; +12. 库存低于目标时能自动触发定向补货而非无脑全库刷新; +13. 每次登录类操作都有不可变流水; +14. 每日和每小时登录总量可配置且能原子限流; +15. 人工、自动重登、首次登录和账号检测有独立子预算; +16. 同一账号不会在多个入口并发登录; +17. `invalid/manual` 不再被普通 CK 巡检反复扫描; +18. 登录成功后自动触发商品能力和库存同步。 + +## 相关文档 + +- [斗鱼账号平台最终实施设计](斗鱼账号平台最终实施设计.md) +- [账号能力中心与统一选号](设计-账号能力中心与统一选号.md) +- [精英宝典商品资格与全量快照](精英宝典商品资格与全量快照.md) +- [账号全生命周期](../设计-账号全生命周期.md) +- [自动化与资料收集](../自动化与资料收集.md) + +## 变更记录 + +| 日期 | 变更 | +| --- | --- | +| 2026-11-21 | 根据生产 CK 事件和账号数据建立 CK 生命周期、供给目标、查询同步和防重复设计 | diff --git a/docs/直播账号履约工作台.md b/docs/直播账号履约工作台.md index 9603de1..a22b9e3 100644 --- a/docs/直播账号履约工作台.md +++ b/docs/直播账号履约工作台.md @@ -3,7 +3,7 @@ 更新时间:2026-11-20 账号能力同步、官网事实覆盖和统一候选账号查询的设计见 -[账号能力中心与统一选号](设计-账号能力中心与统一选号.md)。 +[账号能力中心与统一选号](斗鱼/设计-账号能力中心与统一选号.md)。 ## 目标 diff --git a/docs/设计-账号全生命周期.md b/docs/设计-账号全生命周期.md index 1e6949c..18749a9 100644 --- a/docs/设计-账号全生命周期.md +++ b/docs/设计-账号全生命周期.md @@ -199,7 +199,7 @@ CK 本体和健康结果都在账号上: ## 代码入口 账号商品能力、官网同步和履约选号的跨模块设计见 -[账号能力中心与统一选号](设计-账号能力中心与统一选号.md)。 +[账号能力中心与统一选号](斗鱼/设计-账号能力中心与统一选号.md)。 - `web/backend/models.py`:`Account`、`AccountEvent` - `web/backend/services/account_lifecycle.py`:状态推导与唯一写入口