diff --git a/docs/README.md b/docs/README.md index 5e61ecb..c0d887c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # 项目文档索引 -更新时间:2026-11-08 +更新时间:2026-11-21 本文只列当前仍有维护价值、能直接用于开发或排查的文档。已被代码实现取代的 一次性计划、事故经过和中间抓包记录已删除;需要追查历史时使用 Git 历史。 @@ -18,6 +18,7 @@ - [精英宝典 HAR 提取](虎牙/HAR提取CK与积分中心.md):HAR 中的完整 CK、积分中心和商品结构。 - [皮肤准入映射分析](皮肤准入映射分析.md):快手皮肤订单到斗鱼商品的覆盖与映射边界。 - [直播账号履约工作台](直播账号履约工作台.md):order_site 人工订单、斗鱼账号租约、客户扫码绑定和人工兑换。 +- [斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md):斗鱼绑定、精英宝典、兑换、支付、多 alias 判定和排障日志的统一入口。 ## 协议与逆向证据 diff --git a/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md b/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md new file mode 100644 index 0000000..4a84e5c --- /dev/null +++ b/docs/斗鱼/DOUYU_PROTOCOL_OVERVIEW.md @@ -0,0 +1,239 @@ +# 斗鱼协议总览 + +更新时间:2026-11-21 + +本文是斗鱼协议、状态判定和线上排障的统一入口。代码是最终依据;本文记录代码 +难以直接表达的协议语义、字段优先级、已验证边界和历史踩坑,避免重复分析。 + +## 维护规则 + +每次修改斗鱼协议相关代码时,同一个提交必须同步更新本文: + +1. 新增或修改字段时,补字段真值表和影响范围; +2. 新增 `actAlias`、接口或任务类型时,说明它在多渠道判定中的职责; +3. 修复线上问题时,在“踩坑记录”追加日期、现象、根因、判定变化和回归用例; +4. 抓包只能证明当时行为,不能直接覆盖已由代码和线上回归验证的结论; +5. CK、Cookie、手机号、订单号和完整设备标识不得写入本文。 + +## 权威代码入口 + +| 范围 | 唯一权威入口 | +| --- | --- | +| 斗鱼 HTTP 协议与原始字段解析 | `core/douyu/activity_client.py` | +| 绑定业务状态和 pending 判定 | `web/backend/services/account_binding.py` | +| 二维码、轮询、确认绑定状态机 | `web/backend/services/douyu_runner_bind.py` | +| 账号探针和多 alias 角色汇总 | `web/backend/services/douyu_account_probe.py` | +| 只读查询统一入口 | `web/backend/services/douyu_activity_query.py` | +| 任务类型和入口校验 | `web/backend/services/douyu_service.py` | +| 任务并发与任务槽 | `web/backend/services/task_runtime.py` | +| 履约投影和客户侧会话 | `web/backend/services/platform_fulfillment/` | + +页面、履约、外部单协作和自动化不得自行解释 `bindAct` / `needBindAct`,只能消费 +`binding_snapshot()`、`binding_pending_decision()` 及其派生结果。 + +## 凭证与请求约束 + +- 业务请求依赖斗鱼登录 Cookie;写请求还可能需要 `cvl_csrf_token` / `acf_ccn`。 +- 查询和绑定扫码任务直连,不走代理;兑换、支付、充值、开通和送礼等写操作按任务 + 从代理配置取代理。 +- `Origin`、`Referer` 必须与当前浏览器流程一致,不能只复制 URL。 +- 日志只记录脱敏状态,不记录 Cookie、CSRF、完整二维码签名或账号密码。 + +## 腾讯游戏角色绑定 + +### 接口 + +| 动作 | 方法 | 地址/常量 | 关键参数 | +| --- | --- | --- | --- | +| 查询绑定信息 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindInfo` | `actAlias` | +| 生成角色二维码 | GET | `/wgapi/ordnc/live/memberthird/tencent/bindRoleParam` | `actAlias` | +| 确认绑定 | POST multipart | `/wgapi/ordnc/live/memberthird/tencent/actBind` | `actAlias`、`acf_ccn` | + +### alias 职责 + +站内绑定信息不是单一数据源,`actAlias` 必须按职责区分: + +| 来源 | 典型值 | 职责 | 不能做什么 | +| --- | --- | --- | --- | +| 活动动作 alias | `20260120QYOOB` | 当前精英宝典二维码、待确认和最终确认的权威动作通道 | 不能被 legacy 的旧角色覆盖 | +| legacy 最新态 | `cjm` | 补充最新换绑/扫码角色,常更早暴露新角色 | 不能单独代表当前活动已确认;不能压掉活动 alias pending | +| 历史查询 alias | `20250213NQCYX` 等配置值 | 兼容旧活动查询 | 不作为当前动作主通道 | + +`query_act_aliases` 是“要查哪些来源”的集合;`action_act_aliases` 是“哪些来源可以 +执行确认”的集合。两者不能混用。查询顺序不是业务优先级;最终角色由 pending 判定 +和动作 alias 规则选出。 + +### 字段真值表 + +| 字段 | 语义 | +| --- | --- | +| `bindAccount=1` | 已绑定腾讯账号 | +| `bindRole=1` | 已选中游戏角色 | +| `bindAct=1` | 最终活动绑定已生效,这是唯一 `bound` 信号 | +| `bindAct=0 + bindRole=1` | 角色已选中但未确认,是 `pending` | +| `needBindAct=1` | 当前活动要求继续执行确认 | +| `needBindRole=1` | 当前流程仍需要角色选择/角色信息 | +| `changeRoleWaitTime` | 换绑倒计时;只有 `bindAct=1` 时才可能是真实冷却 | +| `canChangeTime` | 可换绑绝对时间;未确认绑定不能据此拦截 | +| `canChangeRole` | 页面/接口的换绑可用提示,必须结合 `bindAct` 解释 | + +绑定响应没有游戏 UID、角色 ID、OpenID。不要尝试从角色名推导稳定角色身份。 + +### pending 判定顺序 + +单个候选按以下顺序解释,详细结果由 `binding_pending_decision()` 返回: + +1. 没有角色名:不可确认; +2. 动作 alias 上 `bindAct=0 + needBindAct=1 + roleName`:可确认,原因 + `existing_actionable_pending`; +3. 没有扫码前 baseline:可确认,原因 `first_role_without_baseline`; +4. 角色名与 baseline 不同:可确认,原因 `role_changed`; +5. 角色名相同且 `bindAct=1`:已经绑定,不可重复确认; +6. 同 alias 从 `bindAct=1` 转为 `bindAct=0 + needBindAct=1`:可确认,原因 + `same_alias_after_bound_transition`; +7. 其他同名角色:视为旧残留,原因 `same_role_stale`。 + +规则 2 是 2026-11-21 线上修复:动作 alias 已经存在同名 pending 时,它仍是可执行 +确认的 pending,不应因为“角色名没变化”一直灰掉确认按钮。 + +### 完整流程 + +```text +查询所有 query_act_aliases + -> 找当前 bindAct=1(bound) + -> 找动作 alias 上的可确认 pending + -> 生成二维码 + -> 持久化 baseline、候选来源、判定原因 + -> binding_poll 每次只查一次角色 + -> 找到确认条件:任务 success + bind_ready_for_confirm=true + -> actBind + -> 回查 bindAct=1 + -> 写 accounts 当前角色和 role_bind_status=bound +``` + +二维码任务不能在 worker 内长时间阻塞;出码后写 `binding_poll`、`next_run_at` 和 +`run_deadline_at`,由数据库调度器继续轮询。 + +### 确认前保护 + +- 传 `expected_role_name` 时,回查角色变化必须失败,不能确认另一个角色。 +- 确认失败时保留 `before_bound` 的已生效角色,不能把待确认角色写入账号。 +- `bindAct=0` 时 `changeRoleWaitTime` 再大也不是真实换绑冷却。 +- 只有确认后的 `bindAct=1` 才允许写 `bound` 和 `role_change_available_at`。 + +## 诊断日志 + +### 多渠道判定 + +日志关键字:`绑定多渠道判定 |` + +每次输出一条 JSON,包含: + +- `task_id`、`stage`:任务和阶段,如 `qr_preflight`、`poll:N`、 + `query_game_name`、`confirm_precheck`; +- `action_aliases`:允许确认的活动来源; +- `baseline_alias`、`baseline_role`、`baseline_bind_act`; +- `selected_alias`; +- `candidates[]`:每个 alias 的角色、`bindAct`、`bindRole`、`needBindAct`、 + `needBindRole`、是否动作 alias、是否可确认以及原因。 + +### 其他绑定日志 + +- `绑定前状态`:二维码生成前所有 alias、baseline、cooldown 和 pending 命中情况; +- `轮询绑定#N`:每轮选中候选和摘要; +- `确认前状态`:确认目标、expected role 和候选摘要; +- `绑定判定`:确认/失败后的最终收敛。 + +任务结果持久化字段: + +- `action_act_aliases` +- `bind_decision` +- `bind_candidate_decisions` +- `pending_role_name` +- `bind_summary` + +建议的生产只读查询: + +```sql +SELECT id, task_type, status, message, created_at, finished_at, + JSON_EXTRACT(result, '$.bind_decision') AS decision, + JSON_EXTRACT(result, '$.bind_candidate_decisions') AS candidates, + JSON_EXTRACT(result, '$.bind_summary') AS summary +FROM douyu_tasks +WHERE account_id = ? +ORDER BY id DESC +LIMIT 20; +``` + +日志检索: + +```bash +docker compose logs douyu-login | grep '绑定多渠道判定' +docker compose logs douyu-login | grep '确认前状态' +``` + +## 精英宝典与兑换 + +当前精英宝典活动由 `manual_id`、`rid` 和配置中的活动 alias 共同确定。商品、积分、 +限兑、兑换记录和锁单查询统一走 `douyu_activity_query.py`。 + +| 范围 | 关键接口 | +| --- | --- | +| 手册用户信息 | `/wgapi/ordnc/activity/peace/getUserInfo` | +| 商品列表 | `/wgapi/ordnc/activity/peace/storehome` | +| 商品详情 | `/wgapi/ordnc/activity/peace/storedetail` | +| 锁单 | `/wgapi/ordnc/activity/peace/createExchangeOrder` | +| 支付锁单 | `/wgapi/ordnc/activity/peace/payExchangeOrder` | +| 锁单列表 | `/wgapi/ordnc/activity/peace/getExchangeOrderList` | +| 兑换记录 | `/wgapi/ordnc/activity/peace/exchangeList` | + +兑换成功的唯一业务收口必须是 `payExchangeOrder` 成功后写入兑换事件;预约到货、 +预兑和等待开放即使返回 `success`,也不能当成真实兑换。 + +## 鱼翅、积分与支付 + +- 鱼翅余额:`https://cz.douyu.com/item/gold/account` +- 钱包兑换余额:`https://www.douyu.com/wjapi/nc/exchange/fim` +- 支付码:`/japi/oms/web/pay/getQrCode` +- 供应商鱼翅直充按供应商协议执行;到账必须核对斗鱼余额相对下单前基线增加, + 供应商长期“待处理”不能覆盖实际到账事实。 +- 支付任务只负责出码和记录基线,到账轮询进入 `payment_poll` 独立任务槽。 + +## 电竞手册、和平小店与送礼 + +- 电竞手册绑定复用腾讯 `bindInfo` / `bindRoleParam` / `actBind`,但活动页、 + `manual_id`、`actAlias` 和账号字段必须独立,不能写成精英宝典数据。 +- 和平小店绑定和下单来自道聚城接口,确认逻辑仍遵守 + `bindAct=0` 为 pending、`bindAct=1` 为 bound。 +- 送礼是写操作,必须走写任务槽和代理;查询余额/积分不能替代送礼结果回查。 + +## 已知踩坑 + +### 2026-11-21:同名 pending 导致确认按钮一直灰 + +现象:二维码已出,界面显示“当前绑定”和角色,但 `pending=0`,确认按钮禁用。 + +生产证据:账号 `23385` 的二维码任务轮询 106 次后 `role_timeout`;`cjm` 与 +`20260120QYOOB` 返回同名角色,`cjm.needBindAct=0`, +`QYOOB.bindAct=0 + needBindAct=1`。旧逻辑只接受“角色名变化”或“同 alias 从 +`bindAct=1` 转为 pending”,把已经存在的活动 pending 误判成旧残留。 + +修复:动作 alias 已存在同名 pending 时直接视为可确认,原因 +`existing_actionable_pending`;二维码预检也会立即收敛为 `role_ready`。 + +回归:`tests/test_douyu_binding_state.py`、`tests/test_douyu_account_probe.py`、 +`tests/test_douyu_task_concurrency.py`。 + +### 历史固定规则 + +- 不要把 `bindRole=1` 当成已绑定; +- 不要把未确认时的换绑倒计时当成冷却; +- 不要用 `cjm` 的旧角色覆盖活动 alias pending; +- 不要在页面层重新实现 `bindAct/needBindAct` 判断; +- 不要把原始 `bind_summary` 当业务文案,它只用于排障。 + +## 变更记录 + +| 日期 | 变更 | +| --- | --- | +| 2026-11-21 | 建立斗鱼协议总览;补充多 alias 职责、pending 真值表、结构化判定日志和同名 pending 修复记录 | diff --git a/docs/直播账号履约工作台.md b/docs/直播账号履约工作台.md index b1cc9ab..f5453a4 100644 --- a/docs/直播账号履约工作台.md +++ b/docs/直播账号履约工作台.md @@ -49,6 +49,9 @@ - 绑定响应只有角色名、区服、平台、昵称和头像,没有游戏 UID / 角色 ID; - 未最终绑定时即使接口返回换绑倒计时,也不能当成真实冷却。 +完整的斗鱼绑定字段、`actAlias` 多来源规则、pending 判定原因和日志检索方式见 +[斗鱼协议总览](斗鱼/DOUYU_PROTOCOL_OVERVIEW.md)。 + 选号前会调用 `web/backend/services/douyu_account_state.py` 实时刷新账号: - 不依赖 `status`、`ck_check_status`、`elite_opened`、`points` 等缓存结论; diff --git a/tests/test_douyu_account_probe.py b/tests/test_douyu_account_probe.py index 394f888..60f3ecf 100644 --- a/tests/test_douyu_account_probe.py +++ b/tests/test_douyu_account_probe.py @@ -89,6 +89,23 @@ def test_role_resolver_uses_legacy_pending_role_when_current_is_empty(): assert result["source_alias"] == "cjm" +def test_role_resolver_prefers_existing_pending_on_action_alias_same_role(): + role = "忧郁情潇藏心中" + client = RoleClient( + { + "current-alias": _bind(role, bound_role=True, need_act=True), + "cjm": _bind(role, bound_role=True, need_act=False), + } + ) + + result = resolve_elite_role(client, CONFIG) + + assert result["status"] == ROLE_PENDING + assert result["role_name"] == role + assert result["source_alias"] == "current-alias" + assert result["decision"]["reason"] == "existing_actionable_pending" + + def test_role_resolver_partial_failure_does_not_claim_unbound(): client = RoleClient( { diff --git a/tests/test_douyu_binding_state.py b/tests/test_douyu_binding_state.py index 1d08db5..12e8db9 100644 --- a/tests/test_douyu_binding_state.py +++ b/tests/test_douyu_binding_state.py @@ -11,6 +11,7 @@ from web.backend.services.account_binding import ( BIND_BOUND, BIND_PENDING, BIND_UNBOUND, + binding_pending_decision, binding_role_from_result, binding_snapshot, derive_from_bind_info, @@ -39,6 +40,7 @@ def _role_candidate( role_name: str, *, bound_act: bool = False, + need_bind_act: bool = True, ) -> dict[str, Any]: return { "act_alias": alias, @@ -48,7 +50,7 @@ def _role_candidate( "is_bound_account": True, "is_bound_role": True, "is_bound_act": bound_act, - "need_bind_act": True, + "need_bind_act": need_bind_act, "need_bind_role": True, } @@ -193,6 +195,36 @@ def test_existing_pending_role_is_baseline_not_new_scan_result(): ) +def test_existing_action_alias_pending_is_confirmable_even_same_role(): + role = "忧郁情潇藏心中" + baseline = _role_candidate(ACT_ALIAS, role, need_bind_act=True) + legacy = _role_candidate(LEGACY_ALIAS, role, need_bind_act=False) + activity = _role_candidate(ACT_ALIAS, role, need_bind_act=True) + picker = _RolePicker() + + decision = binding_pending_decision( + activity, + baseline_role_name=role, + baseline_is_bound_act=False, + baseline_info=baseline, + actionable_aliases=[ACT_ALIAS], + ) + selected = picker._pick_bind_info( + [legacy, activity], + baseline_role_name=role, + baseline_is_bound_act=False, + baseline_info=baseline, + prefer_pending=True, + prefer_aliases=[LEGACY_ALIAS, ACT_ALIAS], + actionable_aliases=[ACT_ALIAS], + ) + + assert decision["confirmable"] is True + assert decision["reason"] == "existing_actionable_pending" + assert selected is not None + assert selected["act_alias"] == ACT_ALIAS + + def test_same_role_after_activity_bind_transition_is_pending(): old_role = "少和我较劲" baseline = _role_candidate(ACT_ALIAS, old_role, bound_act=True) diff --git a/tests/test_douyu_task_concurrency.py b/tests/test_douyu_task_concurrency.py index ba088fc..644fc50 100644 --- a/tests/test_douyu_task_concurrency.py +++ b/tests/test_douyu_task_concurrency.py @@ -398,6 +398,148 @@ def test_binding_poll_once_finishes_when_role_is_found(db, monkeypatch): assert task.result["bind_ready_for_confirm"] is True +def test_qr_preflight_accepts_existing_action_alias_pending_same_role( + db, monkeypatch +): + _, account, task = _fixtures(db, status="running") + role = "忧郁情潇藏心中" + legacy = { + "act_alias": "cjm", + "role_name": role, + "area_name": "微信", + "plat_name": "安卓(android)", + "is_bound_account": True, + "is_bound_role": True, + "is_bound_act": False, + "need_bind_act": False, + "need_bind_role": True, + "change_role_wait_time": 0, + "can_change_time": 0, + "can_change_role": True, + } + activity = { + **legacy, + "act_alias": "20260120QYOOB", + "need_bind_act": True, + "change_role_wait_time": 2_592_000, + } + client = type( + "Client", + (), + {"get_bind_qr": lambda self, _alias: {"url": "https://example.test/qr"}}, + )() + runner = DouyuBatchRunner( + db, + task.batch_id, + "get_bind_qr", + close_db=False, + ) + monkeypatch.setattr(runner, "_client", lambda _cookie: client) + monkeypatch.setattr( + runner, + "_fetch_bind_info_candidates", + lambda *_args: [legacy, activity], + ) + + runner._execute_get_bind_qr( + db, + task, + account, + "PHPSESSID=x", + { + "bind_act_alias": "20260120QYOOB", + "confirm_act_alias": "20260120QYOOB", + "legacy_act_alias": "cjm", + }, + ) + + db.refresh(task) + assert task.status == "success" + assert task.result["url"] == "https://example.test/qr" + assert task.result["pending_role_name"] == role + assert task.result["bind_ready_for_confirm"] is True + assert task.result["bind_decision"]["alias"] == "20260120QYOOB" + assert task.result["bind_decision"]["reason"] == "existing_actionable_pending" + + +def test_binding_poll_accepts_existing_action_alias_pending_same_role( + db, monkeypatch +): + """活动 alias 的同名待确认角色不能被 legacy(cjm) 的旧快照压掉。""" + _, account, task = _fixtures(db, status="running") + role = "忧郁情潇藏心中" + legacy = { + "act_alias": "cjm", + "role_name": role, + "area_name": "微信", + "plat_name": "安卓(android)", + "is_bound_account": True, + "is_bound_role": True, + "is_bound_act": False, + "need_bind_act": False, + "need_bind_role": True, + "change_role_wait_time": 0, + "can_change_time": 0, + "can_change_role": True, + } + activity = { + **legacy, + "act_alias": "20260120QYOOB", + "need_bind_act": True, + "change_role_wait_time": 2_592_000, + } + task.queue_lane = "binding_poll" + task.next_run_at = datetime.now(UTC) + task.run_deadline_at = datetime.now(UTC) + timedelta(minutes=10) + task.result = { + "url": "https://example.test/qr", + "query_act_aliases": ["cjm", "20260120QYOOB"], + "baseline_role_name": role, + "baseline_is_bound_act": False, + "before_bind_info": activity, + "bind_polling": True, + } + db.commit() + runner = DouyuBatchRunner( + db, + task.batch_id, + "get_bind_qr", + close_db=False, + ) + client = type("Client", (), {})() + monkeypatch.setattr(runner, "_client", lambda _cookie: client) + monkeypatch.setattr( + runner, + "_fetch_bind_info_candidates", + lambda *_args: [legacy, activity], + ) + + runner.poll_bind_role_once( + db, + task, + account, + { + "bind_act_alias": "20260120QYOOB", + "confirm_act_alias": "20260120QYOOB", + "legacy_act_alias": "cjm", + }, + ) + + db.refresh(task) + assert task.status == "success" + assert task.result["role_name"] == role + assert task.result["bind_ready_for_confirm"] is True + assert task.result["bind_decision"]["alias"] == "20260120QYOOB" + assert task.result["bind_decision"]["reason"] == "existing_actionable_pending" + assert { + row["alias"]: row["reason"] + for row in task.result["bind_candidate_decisions"] + } == { + "cjm": "same_role_stale", + "20260120QYOOB": "existing_actionable_pending", + } + + def test_active_task_budget_rejects_new_batch(db, monkeypatch): user = User(username="budget-user", password_hash="hash", role="operation") db.add(user) diff --git a/web/backend/services/account_binding.py b/web/backend/services/account_binding.py index 01ece2c..909062f 100644 --- a/web/backend/services/account_binding.py +++ b/web/backend/services/account_binding.py @@ -32,6 +32,7 @@ from __future__ import annotations +from collections.abc import Sequence from datetime import UTC, datetime, timedelta from typing import Any @@ -284,41 +285,129 @@ def role_change_available_at( return None +def binding_pending_decision( + info: dict | None, + *, + baseline_role_name: str = "", + baseline_is_bound_act: bool = False, + baseline_info: dict | None = None, + actionable_aliases: Sequence[str] = (), +) -> dict[str, Any]: + """解释一个绑定候选是否可进入确认阶段。 + + 角色名不是唯一事实:用户可能换绑到同名角色。判断还要对比扫码前后的 + 活动绑定状态,尤其是活动 alias 从 ``bindAct=1`` 转为 + ``bindAct=0 + needBindAct=1`` 的待确认转换。活动 alias 上已经存在的 + 同名 pending 也不是“旧角色残留”,它仍然可以调用确认接口。 + """ + result: dict[str, Any] = { + "alias": str((info or {}).get("act_alias") or ""), + "role_name": "", + "is_bound_act": False, + "is_bound_role": False, + "need_bind_act": False, + "need_bind_role": False, + "baseline_alias": str((baseline_info or {}).get("act_alias") or ""), + "baseline_role_name": str(baseline_role_name or "").strip(), + "baseline_is_bound_act": bool(baseline_is_bound_act), + "baseline_is_pending": False, + "same_alias": False, + "role_changed": False, + "actionable_alias": False, + "confirmable": False, + "reason": "no_candidate", + } + if not isinstance(info, dict): + return result + snapshot = binding_snapshot(info) + role_name = snapshot["role_name"] + alias = str(info.get("act_alias") or "") + aliases = {str(value or "").strip() for value in actionable_aliases} + baseline_alias = str((baseline_info or {}).get("act_alias") or "") + result.update( + { + "alias": alias, + "role_name": role_name, + "is_bound_act": bool(snapshot["is_bound_act"]), + "is_bound_role": bool(snapshot["is_bound_role"]), + "need_bind_act": bool(snapshot["need_bind_act"]), + "need_bind_role": bool(snapshot["need_bind_role"]), + "same_alias": bool(alias and alias == baseline_alias), + "actionable_alias": bool(alias and alias in aliases), + } + ) + if not role_name: + result["reason"] = "no_role" + return result + baseline = baseline_role_name.strip() + if not baseline: + if result["actionable_alias"] and snapshot["need_bind_act"]: + result.update( + { + "confirmable": True, + "reason": "existing_actionable_pending", + } + ) + return result + result.update({"confirmable": True, "reason": "first_role_without_baseline"}) + return result + if role_name.casefold() != baseline.casefold(): + result.update({"confirmable": True, "reason": "role_changed"}) + return result + if snapshot["is_bound_act"]: + result["reason"] = "already_bound" + return result + if not isinstance(baseline_info, dict): + result["reason"] = "same_role_without_baseline_info" + return result + + baseline_snapshot = binding_snapshot(baseline_info) + result["baseline_is_pending"] = bool( + baseline_snapshot["role_name"] + and not baseline_snapshot["is_bound_act"] + and baseline_snapshot["need_bind_act"] + ) + if ( + result["same_alias"] + and baseline_snapshot["is_bound_act"] + and snapshot["need_bind_act"] + ): + result.update( + { + "confirmable": True, + "reason": "same_alias_after_bound_transition", + } + ) + return result + if result["actionable_alias"] and snapshot["need_bind_act"]: + result.update( + { + "confirmable": True, + "reason": "existing_actionable_pending", + } + ) + return result + result["reason"] = "same_role_stale" + return result + + def is_pending_binding_role( info: dict | None, *, baseline_role_name: str = "", baseline_is_bound_act: bool = False, baseline_info: dict | None = None, + actionable_aliases: Sequence[str] = (), ) -> bool: - """是否出现了本次扫码产生的可确认角色。 - - 角色名不是唯一事实:用户可能换绑到同名角色。判断还要对比扫码前后的 - 活动绑定状态,尤其是活动 alias 从 ``bindAct=1`` 转为 - ``bindAct=0 + needBindAct=1`` 的待确认转换。 - """ - if not isinstance(info, dict): - return False - snapshot = binding_snapshot(info) - role_name = snapshot["role_name"] - if not role_name: - return False - baseline = baseline_role_name.strip() - if not baseline: - return True - if role_name.casefold() != baseline.casefold(): - return True - if snapshot["is_bound_act"]: - return False - if not isinstance(baseline_info, dict): - return False - - baseline_snapshot = binding_snapshot(baseline_info) - same_alias = str(info.get("act_alias") or "") == str( - baseline_info.get("act_alias") or "" - ) + """兼容布尔调用;详细原因统一由 :func:`binding_pending_decision` 给出。""" return bool( - same_alias and baseline_snapshot["is_bound_act"] and snapshot["need_bind_act"] + binding_pending_decision( + info, + baseline_role_name=baseline_role_name, + baseline_is_bound_act=baseline_is_bound_act, + baseline_info=baseline_info, + actionable_aliases=actionable_aliases, + )["confirmable"] ) @@ -340,11 +429,19 @@ def pending_binding_role_from_result(result: dict[str, Any] | None) -> str: baseline_info = result.get("before_bind_info") # 没有完整 before_bind_info 时无法证明同名角色发生过状态转换。 # 此时宁可先不展示,也不能把账号历史角色误报成本次绑定结果。 + action_aliases = [ + str(value or "").strip() + for value in (result.get("action_act_aliases") or []) + if str(value or "").strip() + ] + if not action_aliases and result.get("act_alias"): + action_aliases = [str(result["act_alias"])] if is_pending_binding_role( result, baseline_role_name=baseline, baseline_is_bound_act=bool(result.get("baseline_is_bound_act")), baseline_info=baseline_info, + actionable_aliases=action_aliases, ): return role_name return "" diff --git a/web/backend/services/douyu_account_probe.py b/web/backend/services/douyu_account_probe.py index d2e5835..12b44e4 100644 --- a/web/backend/services/douyu_account_probe.py +++ b/web/backend/services/douyu_account_probe.py @@ -29,10 +29,10 @@ from .account_binding import ( SCOPE_ELITE, SCOPE_ESPORTS, SCOPE_PEACE, + binding_pending_decision, binding_snapshot, derive_from_bind_info, is_bound_act, - is_pending_binding_role, role_change_available_at, set_bind_status, ) @@ -287,21 +287,25 @@ def resolve_elite_role( ), None, ) - pending_info = next( - ( - info - for alias in ordered_aliases - for info in candidates_info - if str(info.get("act_alias") or "") == alias - and is_pending_binding_role( + pending_info = None + pending_decision: dict[str, Any] | None = None + for alias in ordered_aliases: + for info in candidates_info: + if str(info.get("act_alias") or "") != alias: + continue + decision = binding_pending_decision( info, baseline_role_name=str((bound_info or {}).get("role_name") or ""), baseline_is_bound_act=is_bound_act(bound_info), baseline_info=bound_info, + actionable_aliases=action_aliases, ) - ), - None, - ) + if decision["confirmable"]: + pending_info = info + pending_decision = decision + break + if pending_info is not None: + break if bound_info is not None: return _role_result( status=ROLE_BOUND, @@ -318,7 +322,7 @@ def resolve_elite_role( bind_infos=candidates_info, ) if pending_info is not None: - return _role_result( + result = _role_result( status=ROLE_PENDING, bind_info=pending_info, candidates=candidates, @@ -326,6 +330,8 @@ def resolve_elite_role( errors=errors, bind_infos=candidates_info, ) + result["decision"] = pending_decision + return result if errors and not candidates_info: return _role_result( status=ROLE_ERROR, diff --git a/web/backend/services/douyu_runner_bind.py b/web/backend/services/douyu_runner_bind.py index 788fdea..e7c8665 100644 --- a/web/backend/services/douyu_runner_bind.py +++ b/web/backend/services/douyu_runner_bind.py @@ -2,6 +2,7 @@ from __future__ import annotations +import json import time from datetime import UTC, datetime, timedelta from typing import TYPE_CHECKING, Any @@ -17,6 +18,7 @@ from .account_binding import ( BIND_UNBOUND, SCOPE_ELITE, SCOPE_ESPORTS, + binding_pending_decision, binding_snapshot, is_bound_act, is_pending_binding_role, @@ -136,6 +138,7 @@ class BindMixin: baseline_role_name: str = "", baseline_is_bound_act: bool = False, baseline_info: dict | None = None, + actionable_aliases: tuple[str, ...] | list[str] = (), ) -> bool: """判断是否出现了可确认的扫码角色。 @@ -151,6 +154,7 @@ class BindMixin: baseline_role_name=baseline_role_name, baseline_is_bound_act=baseline_is_bound_act, baseline_info=baseline_info, + actionable_aliases=actionable_aliases, ) def _bind_snapshot(self, bind_info: dict | None) -> dict: @@ -178,6 +182,75 @@ class BindMixin: f"{pending_text}" ) + def _binding_candidate_decisions( + self, + candidates: list[dict], + *, + baseline_role_name: str = "", + baseline_is_bound_act: bool = False, + baseline_info: dict | None = None, + actionable_aliases: list[str] | tuple[str, ...] = (), + ) -> list[dict[str, Any]]: + """按同一规则解释每个 actAlias 候选,供任务结果和日志复盘。""" + return [ + binding_pending_decision( + info, + baseline_role_name=baseline_role_name, + baseline_is_bound_act=baseline_is_bound_act, + baseline_info=baseline_info, + actionable_aliases=actionable_aliases, + ) + for info in candidates + ] + + def _push_binding_decision_log( + self, + *, + task: DouyuTask, + stage: str, + candidates: list[dict], + decisions: list[dict[str, Any]], + selected: dict | None, + baseline_info: dict | None, + actionable_aliases: list[str] | tuple[str, ...], + ) -> None: + """输出一条可检索的多渠道判定日志,不包含 Cookie 等凭据。""" + compact = [ + { + "alias": item.get("alias") or "", + "role": item.get("role_name") or "", + "bind_act": 1 if item.get("is_bound_act") else 0, + "bind_role": 1 if item.get("is_bound_role") else 0, + "need_act": 1 if item.get("need_bind_act") else 0, + "need_role": 1 if item.get("need_bind_role") else 0, + "actionable_alias": bool(item.get("actionable_alias")), + "confirmable": bool(item.get("confirmable")), + "reason": item.get("reason") or "", + } + for item in decisions + ] + self._push_log( + "info", + "绑定多渠道判定 | " + + json.dumps( + { + "task_id": int(task.id), + "stage": stage, + "action_aliases": list(actionable_aliases), + "baseline_alias": str((baseline_info or {}).get("act_alias") or ""), + "baseline_role": str((baseline_info or {}).get("role_name") or ""), + "baseline_bind_act": 1 + if self._is_bound_act(baseline_info) + else 0, + "selected_alias": str((selected or {}).get("act_alias") or ""), + "candidate_count": len(candidates), + "candidates": compact, + }, + ensure_ascii=False, + separators=(",", ":"), + ), + ) + def _apply_bind_info_to_account( self, account: Account, bind_info: dict, state: str | None = None ) -> None: @@ -330,18 +403,24 @@ class BindMixin: extra_prefer_aliases=[primary_alias] if primary_alias else None, ) aliases = self._role_alias_priority(config, primary_alias) + actionable_aliases = self._action_act_aliases(config) if bound is not None: - changed_pending = self._pick_role_info_for_aliases( + changed_pending = self._pick_pending_role_info( candidates, - aliases, - pending_only=True, - exclude_role_name=str(bound.get("role_name") or ""), + prefer_aliases=aliases, + baseline_role_name=str(bound.get("role_name") or ""), + baseline_is_bound_act=self._is_bound_act(bound), + baseline_info=bound, + actionable_aliases=actionable_aliases, ) return changed_pending or bound - return self._pick_role_info_for_aliases( + return self._pick_pending_role_info( candidates, - aliases, - pending_only=True, + prefer_aliases=aliases, + baseline_role_name="", + baseline_is_bound_act=False, + baseline_info=None, + actionable_aliases=actionable_aliases, ) or self._pick_role_info_for_aliases(candidates, aliases) def _pick_bind_info( @@ -353,6 +432,7 @@ class BindMixin: baseline_info: dict | None = None, prefer_pending: bool = True, prefer_aliases: list[str] | None = None, + actionable_aliases: list[str] | tuple[str, ...] = (), ) -> dict | None: """从多个 alias 结果里挑最有用的绑定信息。 @@ -371,6 +451,7 @@ class BindMixin: baseline_role_name=baseline_role_name, baseline_is_bound_act=baseline_is_bound_act, baseline_info=baseline_info, + actionable_aliases=actionable_aliases, ) if pending is not None: return pending @@ -409,6 +490,7 @@ class BindMixin: baseline_role_name: str = "", baseline_is_bound_act: bool = False, baseline_info: dict | None = None, + actionable_aliases: list[str] | tuple[str, ...] = (), ) -> dict | None: """唯一的新角色候选选择入口。 @@ -421,6 +503,7 @@ class BindMixin: baseline_role_name=baseline_role_name, baseline_is_bound_act=baseline_is_bound_act, baseline_info=baseline_info, + actionable_aliases=actionable_aliases, ): return info return None @@ -496,6 +579,11 @@ class BindMixin: result["baseline_role_name"] = baseline_role_name result["baseline_is_bound_act"] = baseline_is_bound_act result["query_act_aliases"] = query_aliases + action_aliases = [ + str(value) + for value in (result.get("action_act_aliases") or []) + if str(value or "").strip() + ] self._push_log( "info", "开始轮询绑定角色 " @@ -529,6 +617,7 @@ class BindMixin: baseline_info=baseline_info, prefer_pending=True, prefer_aliases=query_aliases, + actionable_aliases=action_aliases, ) or candidates[0] ) @@ -538,6 +627,7 @@ class BindMixin: baseline_role_name=baseline_role_name, baseline_is_bound_act=baseline_is_bound_act, baseline_info=baseline_info, + actionable_aliases=action_aliases, ) query_alias = str(bind_info.get("act_alias") or "") summary = ( @@ -707,6 +797,7 @@ class BindMixin: baseline_info = result.get("before_bind_info") if not isinstance(baseline_info, dict): baseline_info = None + action_aliases = self._action_act_aliases(config) bind_info = ( self._pick_bind_info( candidates, @@ -715,21 +806,40 @@ class BindMixin: baseline_info=baseline_info, prefer_pending=True, prefer_aliases=query_aliases, + actionable_aliases=action_aliases, ) or candidates[0] ) snapshot = self._bind_snapshot(bind_info) - is_pending_role = self._is_pending_role( + candidate_decisions = self._binding_candidate_decisions( + candidates, + baseline_role_name=baseline_role_name, + baseline_is_bound_act=baseline_is_bound_act, + baseline_info=baseline_info, + actionable_aliases=action_aliases, + ) + selected_decision = binding_pending_decision( bind_info, baseline_role_name=baseline_role_name, baseline_is_bound_act=baseline_is_bound_act, baseline_info=baseline_info, + actionable_aliases=action_aliases, ) + is_pending_role = bool(selected_decision["confirmable"]) query_alias = str(bind_info.get("act_alias") or "") summary = ( f"act={query_alias or '-'} " f"{self._format_bind_summary(bind_info, pending=is_pending_role)}" ) + self._push_binding_decision_log( + task=task, + stage=f"poll:{int(result.get('poll_count') or 0) + 1}", + candidates=candidates, + decisions=candidate_decisions, + selected=bind_info, + baseline_info=baseline_info, + actionable_aliases=action_aliases, + ) if is_pending_role: task.queue_lane = "" @@ -743,8 +853,12 @@ class BindMixin: "bind_confirmed": False, "bind_phase": "role_ready", "bind_polling": False, + "pending_role_name": snapshot["role_name"], "poll_count": int(result.get("poll_count") or 0) + 1, "bind_summary": summary, + "action_act_aliases": action_aliases, + "bind_decision": selected_decision, + "bind_candidate_decisions": candidate_decisions, } ) account.updated_at = now @@ -782,6 +896,9 @@ class BindMixin: "bind_polling": True, "poll_count": int(result.get("poll_count") or 0) + 1, "bind_summary": summary, + "action_act_aliases": action_aliases, + "bind_decision": selected_decision, + "bind_candidate_decisions": candidate_decisions, } ) self._schedule_next_bind_poll( @@ -804,6 +921,7 @@ class BindMixin: client = self._client(cookie) qr_act_alias = self._bind_qr_act_alias(config) query_aliases = self._query_bind_act_aliases(config) + action_aliases = self._action_act_aliases(config) if not qr_act_alias and not query_aliases: self._mark_task(db, task, "failed", "请先配置绑定活动 actAlias") return @@ -826,12 +944,28 @@ class BindMixin: before_candidates, baseline_role_name=str(before.get("role_name") or ""), baseline_is_bound_act=self._is_bound_act(before), + baseline_info=before, prefer_pending=True, prefer_aliases=query_aliases, + actionable_aliases=action_aliases, ) or before or before_candidates[0] ) + candidate_decisions = self._binding_candidate_decisions( + before_candidates, + baseline_role_name=str(before.get("role_name") or ""), + baseline_is_bound_act=self._is_bound_act(before), + baseline_info=before, + actionable_aliases=action_aliases, + ) + pending_decision = binding_pending_decision( + pending_before, + baseline_role_name=str(before.get("role_name") or ""), + baseline_is_bound_act=self._is_bound_act(before), + baseline_info=before, + actionable_aliases=action_aliases, + ) before_snapshot = self._bind_snapshot(before) cooldown_snapshot = self._bind_snapshot(cooldown_info) current_role_name = before_snapshot["role_name"] or ( @@ -848,6 +982,15 @@ class BindMixin: f"pending_hit={pending_before.get('act_alias') or '-'} " f"{self._format_bind_summary(pending_before)}", ) + self._push_binding_decision_log( + task=task, + stage="qr_preflight", + candidates=before_candidates, + decisions=candidate_decisions, + selected=pending_before, + baseline_info=before, + actionable_aliases=action_aliases, + ) # 生成二维码前强制检查换绑冷却:冷却中直接失败,绝不发码 if self._is_change_cooling(cooldown_info): @@ -931,8 +1074,47 @@ class BindMixin: ).isoformat(), "baseline_role_name": current_role_name, "baseline_is_bound_act": before_snapshot["is_bound_act"], + "action_act_aliases": action_aliases, + "bind_decision": pending_decision, + "bind_candidate_decisions": candidate_decisions, "poll_count": 0, } + if pending_decision["confirmable"]: + pending_snapshot = self._bind_snapshot(pending_before) + pending_role = str(pending_snapshot["role_name"] or "") + pending_alias = str(pending_before.get("act_alias") or "") + pending_summary = ( + f"act={pending_alias or '-'} " + f"{self._format_bind_summary(pending_before, pending=True)}" + ) + result.update( + { + **pending_snapshot, + "act_alias": pending_alias, + "query_act_alias": pending_alias, + "pending_role_name": pending_role, + "bind_ready_for_confirm": True, + "bind_confirmed": False, + "bind_phase": "role_ready", + "bind_polling": False, + "bind_summary": pending_summary, + } + ) + account.updated_at = qr_generated_at + self._push_log( + "success", + "生成二维码前已发现活动 alias 待确认角色 " + f"act={pending_alias or '-'} role={pending_role or '-'} " + f"reason={pending_decision['reason']}", + ) + self._mark_task( + db, + task, + "success", + f"已识别现有待确认角色: {pending_role},待确认绑定", + result, + ) + return account.updated_at = datetime.now(UTC) task.queue_lane = "binding_poll" task.next_run_at = qr_generated_at + timedelta( @@ -955,6 +1137,7 @@ class BindMixin: client = self._client(cookie) confirm_alias = self._confirm_act_alias(config) query_aliases = self._query_bind_act_aliases(config) + action_aliases = self._action_act_aliases(config) if confirm_alias and confirm_alias not in query_aliases: query_aliases = [confirm_alias, *query_aliases] if not confirm_alias: @@ -993,6 +1176,22 @@ class BindMixin: ) before = before or before_bound or before_candidates[0] before_snapshot = self._bind_snapshot(before) + candidate_decisions = self._binding_candidate_decisions( + before_candidates, + baseline_role_name=str((before_bound or {}).get("role_name") or ""), + baseline_is_bound_act=self._is_bound_act(before_bound), + baseline_info=before_bound, + actionable_aliases=action_aliases, + ) + self._push_binding_decision_log( + task=task, + stage="confirm_precheck", + candidates=before_candidates, + decisions=candidate_decisions, + selected=before, + baseline_info=before_bound, + actionable_aliases=action_aliases, + ) role_name = before_snapshot["role_name"] query_alias = str(before.get("act_alias") or "") if expected_role_name and role_name.casefold() != expected_role_name.casefold(): @@ -1436,6 +1635,17 @@ class BindMixin: role_name = str(role.get("role_name") or "") pending_role = str(role.get("pending_role_name") or "") source_alias = str(role.get("source_alias") or "") + action_aliases = self._action_act_aliases(config) + raw_candidates = [ + item for item in (role.get("bind_infos") or []) if isinstance(item, dict) + ] + candidate_decisions = self._binding_candidate_decisions( + raw_candidates, + baseline_role_name=str(role_name or ""), + baseline_is_bound_act=status == ROLE_BOUND, + baseline_info=bind_info if isinstance(bind_info, dict) else None, + actionable_aliases=action_aliases, + ) summary = ( f"act={source_alias or '-'} {self._format_bind_summary(bind_info)}" if bind_info @@ -1448,6 +1658,15 @@ class BindMixin: f"status={status} source={source_alias or '-'} " f"{self._format_bind_summary(bind_info) if bind_info else 'role=- bound_act=-'}", ) + self._push_binding_decision_log( + task=task, + stage="query_game_name", + candidates=raw_candidates, + decisions=candidate_decisions, + selected=bind_info, + baseline_info=bind_info if isinstance(bind_info, dict) else None, + actionable_aliases=action_aliases, + ) persist_probe_result( db, account, @@ -1483,6 +1702,9 @@ class BindMixin: ), "bind_summary": summary, "bind_candidates": role.get("candidates") or [], + "action_act_aliases": action_aliases, + "bind_decision": role.get("decision") or {}, + "bind_candidate_decisions": candidate_decisions, "errors": role.get("errors") or [], } if pending_role: