refactor(douyu): 统一腾讯角色绑定协议与状态判断

This commit is contained in:
yml
2026-11-18 10:59:20 +08:00
parent 9958e4ab7d
commit 8a58f2857d
14 changed files with 1681 additions and 215 deletions
+173 -59
View File
@@ -32,7 +32,7 @@
from __future__ import annotations
from datetime import UTC, datetime
from datetime import UTC, datetime, timedelta
from typing import Any
from ..models import Account
@@ -190,85 +190,199 @@ def bind_payload(account: Account) -> dict[str, str]:
def derive_from_bind_info(info: dict | None) -> str | None:
"""从斗鱼 `bind_info` 的返回推导绑定状态;**推导不出来时返回 None**。
"""从斗鱼腾讯绑定信息推导唯一业务状态。
返回 None 表示「这次查询没能得出可靠结论」—— 调用方应当**保持原值或写
unknown**,绝不要把它当成 `unbound`。"没查到"和"没绑定"必须分开。
最新抓包证明 `bindRole` 与 `bindAct` 不是同一阶段:
判定依据(字段含义见 `core/douyu/activity_client.py:_parse_bind_info`):
- 扫码选中角色后:`bindRole=1, bindAct=0`,此时应为 `pending`;
- 调用 `actBind` 后:`bindAct=1`,此时才是 `bound`;
- 两个标志都是 0:明确未绑定。
- `is_bound_role` 为真 → **bound**(已经绑了角色)
- `is_bound_role` 为假 → **unbound**(接口明确说了没绑)
- 缺失(接口没给 / 解析失败)→ **None**(推不出来,别猜)
⚠️ **只看 `is_bound_role`,不掺 `is_bound_act`。**
这一列问的是「**角色**绑没绑」,而**「活动是否开通/参与」和「是否绑定角色」
是两件独立的事**(用户明确指出的领域事实)。生产实测也印证了:
电竞 opened=False 且 bind=bound → 187 个账号
也就是说这 187 个账号**绑了角色、但手册压根没开通**。
曾经用 `is_bound_act` 做兜底("避免漏掉已绑但没回角色名的"),
那是把"活动维度"当成了"角色维度" —— 一旦有账号 `is_bound_act=True`
而角色未绑,就会报出"角色已绑定"的**错结论**。实测没触发过,
但语义是错的,所以去掉。(当时那些判为 bound 的账号 100% 都有角色名,
证明 `is_bound_role` 本身就够用。)
⚠️ 这里刻意**不产出 pending**:`pending` 描述的是"正在绑定/待确认"这种
**进行中的动作**(例如刚生成过绑定二维码),那是一次查询的**副作用**,
不是查询能观测到的状态。硬用查询结果去推 pending 就是编造。
兼容旧接口:如果响应里完全没有 `is_bound_act`,才回退到
`is_bound_role` 判断。新接口始终会带上 `is_bound_act`。
"""
if not isinstance(info, dict):
return None
def flag(key: str) -> bool | None:
value = info.get(key)
if value is None:
return None
if isinstance(value, bool):
return value
text = str(value).strip().lower()
if text in {"1", "true", "yes", "y"}:
return True
if text in {"0", "false", "no", "n", ""}:
return False
return None
bound_role = flag("is_bound_role")
bound_act = _explicit_flag(info.get("is_bound_act"))
bound_role = _explicit_flag(info.get("is_bound_role"))
role_name = _binding_role_name(info)
if bound_act is True:
return BIND_BOUND
if bound_act is False:
if bound_role is True or bool(role_name):
return BIND_PENDING
return BIND_UNBOUND
# 旧接口没有 is_bound_act,保留原行为。
if bound_role is True:
return BIND_BOUND
if bound_role is False:
return BIND_UNBOUND
# 接口没给结论:保持 unknown,别把"没查到"写成"没绑定"
return None
def is_role_change_cooling(info: dict | None) -> bool:
"""是否处于真实换绑冷却:已有绑定角色且当前不可换绑。"""
def is_confirmed_binding(info: dict | None) -> bool:
"""是否已经完成最终绑定。
新接口以 `bindAct=1` 为准;旧接口缺少该字段时才回退到 `bindRole`。
"""
if not isinstance(info, dict):
return False
role_name = str(info.get("role_name") or info.get("role") or "").strip()
if not role_name or not _truthy_flag(info.get("is_bound_act")):
return False
if str(info.get("api_version") or "") == "esports":
can_change_time = _to_int(info.get("can_change_time"))
if can_change_time is not None:
return can_change_time > int(datetime.now(UTC).timestamp())
bound_act = _explicit_flag(info.get("is_bound_act"))
if bound_act is not None:
return bound_act
return _explicit_flag(info.get("is_bound_role")) is True
def is_bound_act(info: dict | None) -> bool:
"""接口原始 `bindAct` 标志,仅供绑定状态机和候选筛选使用。"""
return isinstance(info, dict) and _explicit_flag(info.get("is_bound_act")) is True
def can_change_role(info: dict | None, *, now: datetime | None = None) -> bool:
"""是否允许换绑。未绑定状态永远不受接口倒计时影响。"""
if not is_confirmed_binding(info):
return True
assert isinstance(info, dict)
moment = now or datetime.now(UTC)
can_change_time = _to_int(info.get("can_change_time"))
if can_change_time is not None and can_change_time > 0:
return can_change_time <= int(moment.timestamp())
wait_time = _to_int(info.get("change_role_wait_time"))
if wait_time is not None and wait_time > 0:
return False
raw_can_change = _explicit_flag(info.get("can_change_role"))
if raw_can_change is not None:
return raw_can_change
return True
def is_role_change_cooling(
info: dict | None,
*,
now: datetime | None = None,
) -> bool:
"""是否处于真实换绑冷却:最终绑定已完成且当前不可换绑。"""
return is_confirmed_binding(info) and not can_change_role(info, now=now)
def role_change_available_at(
info: dict | None,
*,
checked_at: datetime | None = None,
) -> datetime | None:
"""统一的换绑可用时间;未确认绑定或没有冷却时返回 None。"""
if not is_role_change_cooling(info, now=checked_at):
return None
assert isinstance(info, dict)
moment = checked_at or datetime.now(UTC)
can_change_time = _to_int(info.get("can_change_time"))
if can_change_time is not None and can_change_time > 0:
return datetime.fromtimestamp(can_change_time, tz=UTC)
wait_time = _to_int(info.get("change_role_wait_time"))
if wait_time is not None and wait_time > 0:
return moment + timedelta(seconds=wait_time)
return None
def is_pending_binding_role(
info: dict | None,
*,
baseline_role_name: str = "",
baseline_is_bound_act: bool = False,
) -> bool:
"""是否出现了可确认的扫码角色。"""
if not isinstance(info, dict):
return False
snapshot = binding_snapshot(info)
role_name = snapshot["role_name"]
if not role_name:
return False
if snapshot["is_bound_act"]:
return bool(baseline_role_name) and role_name != baseline_role_name
if snapshot["need_bind_act"] or snapshot["need_bind_role"]:
if not baseline_role_name:
return True
return role_name != baseline_role_name or baseline_is_bound_act
if not baseline_role_name:
return True
if info.get("can_change_role") is not None:
return not _truthy_flag(info.get("can_change_role"))
return False
if role_name != baseline_role_name:
return True
return baseline_is_bound_act
def binding_channel(info: dict | None) -> str:
"""统一游戏渠道展示:区服 / 平台。"""
if not isinstance(info, dict):
return ""
return " / ".join(
part
for part in (
str(info.get("area_name") or "").strip(),
str(info.get("plat_name") or "").strip(),
)
if part
)
def binding_snapshot(info: dict | None) -> dict[str, Any]:
"""斗鱼腾讯绑定的唯一业务快照,供执行器、账号刷新和概览复用。"""
data = info if isinstance(info, dict) else {}
role_name = _binding_role_name(data)
bound_status = derive_from_bind_info(data)
phase = {
BIND_BOUND: "confirmed",
BIND_PENDING: "role_ready",
BIND_UNBOUND: "unbound",
}.get(bound_status or "", "unknown")
bound_act = _explicit_flag(data.get("is_bound_act")) is True
return {
"role_name": role_name,
"area_name": str(data.get("area_name") or "").strip(),
"plat_name": str(data.get("plat_name") or "").strip(),
"partition_name": str(data.get("partition_name") or "").strip(),
"game_channel": binding_channel(data),
"nickname": str(data.get("nickname") or "").strip(),
"account_type": str(data.get("account_type") or "").strip(),
"account_avatar": str(data.get("account_avatar") or "").strip(),
"is_bound_account": _truthy_flag(data.get("is_bound_account")),
"is_bound_role": _truthy_flag(data.get("is_bound_role")),
"is_bound_act": bound_act,
"need_bind_act": _truthy_flag(data.get("need_bind_act")),
"need_bind_role": _truthy_flag(data.get("need_bind_role")),
"change_role_wait_time": _to_int(data.get("change_role_wait_time")),
"can_change_time": _to_int(data.get("can_change_time")),
"can_change_role": can_change_role(data),
"is_change_cooling": is_role_change_cooling(data),
"bind_status": bound_status,
"bind_phase": phase,
"bind_confirmed": bound_status == BIND_BOUND,
"bind_ready_for_confirm": bound_status == BIND_PENDING and bool(role_name),
"game_id": str(data.get("game_id") or "").strip(),
"game_name": str(data.get("game_name") or "").strip(),
"tx_act_id": _to_int(data.get("tx_act_id")) or 0,
"bind_info": data,
}
def _binding_role_name(info: dict) -> str:
return str(info.get("role_name") or info.get("role") or "").strip()
def _explicit_flag(value: Any) -> bool | None:
if value is None or value == "":
return None
if isinstance(value, bool):
return value
text = str(value).strip().lower()
if text in {"1", "true", "yes", "y"}:
return True
if text in {"0", "false", "no", "n", ""}:
return False
return None
def _truthy_flag(value: Any) -> bool:
if value is True:
return True
if value is False or value is None:
return False
return str(value).strip().lower() in {"1", "true", "yes", "y"}
return _explicit_flag(value) is True
def _to_int(value: Any) -> int | None: