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:
+10 -19
View File
@@ -9,7 +9,7 @@ from __future__ import annotations
from collections.abc import Callable
from dataclasses import dataclass
from datetime import UTC, datetime, timedelta
from datetime import UTC, datetime
from typing import Any
from sqlalchemy.orm import Session
@@ -19,8 +19,9 @@ from core.douyu import DouyuActivityClient
from ..models import Account
from .account_binding import (
SCOPE_ELITE,
derive_from_bind_info,
binding_snapshot,
is_role_change_cooling,
role_change_available_at,
set_bind_status,
)
from .account_lifecycle import on_ck_verdict
@@ -235,30 +236,20 @@ def _apply_bind_state(
*,
checked_at: datetime,
) -> datetime | None:
derived = derive_from_bind_info(bind_info)
snapshot = binding_snapshot(bind_info)
derived = snapshot["bind_status"]
if derived is not None:
set_bind_status(account, SCOPE_ELITE, derived)
role_name = str(bind_info.get("role_name") or bind_info.get("role") or "").strip()
role_name = snapshot["role_name"]
if role_name:
account.game_name = role_name[:128]
area_name = str(bind_info.get("area_name") or "").strip()
plat_name = str(bind_info.get("plat_name") or "").strip()
channel = " · ".join(item for item in (area_name, plat_name) if item)
channel = snapshot["game_channel"]
if channel:
account.game_channel = channel[:128]
account.game_channel = channel.replace(" / ", " · ")[:128]
wait_seconds = _to_int(bind_info.get("change_role_wait_time"))
can_change_time = _to_int(bind_info.get("can_change_time"))
account.change_role_wait_time = wait_seconds
if not is_role_change_cooling(bind_info):
available_at = None
elif can_change_time is not None and can_change_time > 0:
available_at = datetime.fromtimestamp(can_change_time, tz=UTC)
elif wait_seconds is not None and wait_seconds > 0:
available_at = checked_at + timedelta(seconds=wait_seconds)
else:
available_at = account.role_change_available_at
account.change_role_wait_time = snapshot["change_role_wait_time"]
available_at = role_change_available_at(bind_info, checked_at=checked_at)
account.role_change_available_at = available_at
return available_at
@@ -15,6 +15,7 @@ from typing import Any
from core.douyu import DouyuActivityClient
from core.douyu.cookie_utils import cookie_value
from .account_binding import binding_snapshot
from .douyu_goods_service import serialize_goods
ERROR_MAX_LENGTH = 240
@@ -275,6 +276,7 @@ def query_account_overview(
return {
"elite": elite,
"bind": bind,
"bind_snapshot": binding_snapshot(bind),
"gold": gold,
"goods": goods,
"serialized_goods": [serialize_goods(item) for item in goods],
+8 -5
View File
@@ -297,6 +297,7 @@ def _probe_with_client(
)
elite = overview["elite"]
bind = overview["bind"]
bind_snapshot = overview["bind_snapshot"]
gold = overview["gold"]
goods = overview["serialized_goods"]
error_labels = {
@@ -315,13 +316,13 @@ def _probe_with_client(
expire_time = _to_int(elite.get("expire_time"))
user_info = elite.get("user_info") or {}
profile = DouyuActivityClient.profile_from_cookie(str(account.cookie or ""))
bind_role = _text(bind.get("role_name"), max_length=128)
area_name = _text(bind.get("area_name"), max_length=64)
plat_name = _text(bind.get("plat_name"), max_length=64)
bind_role = _text(bind_snapshot["role_name"], max_length=128)
area_name = _text(bind_snapshot["area_name"], max_length=64)
plat_name = _text(bind_snapshot["plat_name"], max_length=64)
bind_channel = " · ".join(item for item in (area_name, plat_name) if item)
bind_account = _text(bind.get("nickname"), max_length=128)
bind_account = _text(bind_snapshot["nickname"], max_length=128)
ck_status = CK_VALID if (elite or bind) else CK_INVALID
ok = bool(bind_role) and not (elite == {} and bind == {})
ok = bool(bind_snapshot["bind_confirmed"]) and not (elite == {} and bind == {})
return {
"found": True,
@@ -340,6 +341,8 @@ def _probe_with_client(
"manual_score": manual_score,
"expire_time": expire_time,
"manual_opened": bool(manual_type is not None and manual_type >= 1),
"bind_status": bind_snapshot["bind_status"],
"bind_phase": bind_snapshot["bind_phase"],
"bind_game_account": bind_account,
"bind_game_role": bind_role,
"bind_game_channel": bind_channel,
+24 -88
View File
@@ -17,7 +17,11 @@ from .account_binding import (
BIND_UNBOUND,
SCOPE_ELITE,
SCOPE_ESPORTS,
binding_snapshot,
is_bound_act,
is_pending_binding_role,
is_role_change_cooling,
role_change_available_at,
set_bind_status,
)
from .business_events import record_bind
@@ -106,45 +110,9 @@ class BindMixin:
aliases.append(alias)
return aliases
@staticmethod
def _role_channel(bind_info: dict) -> str:
return " / ".join(
part
for part in [bind_info.get("area_name"), bind_info.get("plat_name")]
if part
)
@staticmethod
def _is_truthy_flag(value) -> bool:
if value is True:
return True
if value is False or value is None:
return False
text = str(value).strip().lower()
return text in {"1", "true", "yes", "y"}
@classmethod
def _is_bound_act(cls, bind_info: dict | None) -> bool:
if not bind_info:
return False
return cls._is_truthy_flag(bind_info.get("is_bound_act"))
@classmethod
def _can_change_role(cls, bind_info: dict | None) -> bool:
"""综合 can_change_role 与换绑倒计时判断是否允许换绑。"""
if not bind_info:
return True
if str(bind_info.get("api_version") or "") == "esports":
can_change_time = cls._to_int(bind_info.get("can_change_time"))
if can_change_time is not None:
return can_change_time <= int(datetime.now(UTC).timestamp())
wait_time = cls._to_int(bind_info.get("change_role_wait_time"))
if wait_time is not None and wait_time > 0:
return False
if bind_info.get("can_change_role") is not None:
return cls._is_truthy_flag(bind_info.get("can_change_role"))
# 已绑定但接口没给倒计时/开关时,默认允许(避免误杀首次绑定)
return True
return is_bound_act(bind_info)
@classmethod
def _is_change_cooling(cls, bind_info: dict | None) -> bool:
@@ -168,47 +136,14 @@ class BindMixin:
4. need_bind_act / need_bind_role 且角色相对 baseline 有变化,算 pending
5. 无 baseline 且未绑定但有角色,视为待确认残留
"""
if not bind_info:
return False
role_name = str(bind_info.get("role_name") or "").strip()
if not role_name:
return False
is_bound_act = cls._is_bound_act(bind_info)
need_bind_act = cls._is_truthy_flag(bind_info.get("need_bind_act"))
need_bind_role = cls._is_truthy_flag(bind_info.get("need_bind_role"))
role_changed = bool(baseline_role_name) and role_name != baseline_role_name
if is_bound_act:
# 已绑定:仅当相对 baseline 角色发生变化时才视为新扫码结果
return role_changed
if need_bind_act or need_bind_role:
if not baseline_role_name:
return True
return role_changed or baseline_is_bound_act
if not baseline_role_name:
return True
if role_changed:
return True
# 同一角色从已绑定变为未绑定
return baseline_is_bound_act
return is_pending_binding_role(
bind_info,
baseline_role_name=baseline_role_name,
baseline_is_bound_act=baseline_is_bound_act,
)
def _bind_snapshot(self, bind_info: dict | None) -> dict:
info = bind_info or {}
role_name = str(info.get("role_name") or "")
return {
"role_name": role_name,
"area_name": info.get("area_name") or "",
"plat_name": info.get("plat_name") or "",
"nickname": info.get("nickname") or "",
"is_bound_act": self._is_bound_act(info),
"is_bound_role": self._is_truthy_flag(info.get("is_bound_role")),
"is_bound_account": self._is_truthy_flag(info.get("is_bound_account")),
"need_bind_act": self._is_truthy_flag(info.get("need_bind_act")),
"need_bind_role": self._is_truthy_flag(info.get("need_bind_role")),
"change_role_wait_time": self._to_int(info.get("change_role_wait_time")),
"can_change_time": self._to_int(info.get("can_change_time")),
"can_change_role": self._can_change_role(info),
"bind_info": info,
}
return binding_snapshot(bind_info)
def _format_bind_summary(
self, bind_info: dict | None, *, pending: bool | None = None
@@ -241,12 +176,14 @@ class BindMixin:
(`query_game_name` 等)就该这样:它们**没有资格**改变绑定状态。
传值时只能是 `account_binding` 的四个枚举。
"""
role_name = str(bind_info.get("role_name") or "")
snapshot = binding_snapshot(bind_info)
role_name = snapshot["role_name"]
account.game_name = role_name or account.game_name
account.game_channel = self._role_channel(bind_info) or account.game_channel
account.change_role_wait_time = self._to_int(
bind_info.get("change_role_wait_time")
account.game_channel = (
snapshot["game_channel"].replace(" / ", " · ") or account.game_channel
)
account.change_role_wait_time = snapshot["change_role_wait_time"]
account.role_change_available_at = role_change_available_at(bind_info)
if state is not None:
set_bind_status(account, SCOPE_ELITE, state)
account.updated_at = datetime.now(UTC)
@@ -255,15 +192,15 @@ class BindMixin:
self, account: Account, bind_info: dict, state: str | None = None
) -> None:
"""将电竞手册角色状态写入专属字段,避免覆盖精英宝典数据。"""
role_name = str(bind_info.get("role_name") or "")
snapshot = binding_snapshot(bind_info)
role_name = snapshot["role_name"]
account.esports_game_name = role_name or account.esports_game_name
account.esports_game_channel = (
self._role_channel(bind_info) or account.esports_game_channel
snapshot["game_channel"].replace(" / ", " · ")
or account.esports_game_channel
)
account.esports_change_role_wait_time = self._to_int(
bind_info.get("change_role_wait_time")
)
account.esports_can_change_time = self._to_int(bind_info.get("can_change_time"))
account.esports_change_role_wait_time = snapshot["change_role_wait_time"]
account.esports_can_change_time = snapshot["can_change_time"]
if state is not None:
set_bind_status(account, SCOPE_ESPORTS, state)
account.updated_at = datetime.now(UTC)
@@ -278,12 +215,11 @@ class BindMixin:
activity_snapshot = self._bind_snapshot(activity_info)
esports_bound = activity_snapshot["is_bound_act"]
has_selected_role = bool(activity_snapshot["role_name"])
tx_act = activity_info.get("tx_act") or {}
return {
**activity_snapshot,
"is_bound_role": has_selected_role,
"act_alias": act_alias,
"game_id": tx_act.get("gameId") or "",
"game_id": activity_snapshot["game_id"],
"esports_bound": esports_bound,
"has_selected_role": has_selected_role,
"bind_ready_for_confirm": has_selected_role and not esports_bound,
+16 -10
View File
@@ -33,7 +33,7 @@ from sqlalchemy.orm import Session
from core.douyu import DouyuActivityClient
from ..models import Account, DouyuTask
from .account_binding import derive_from_bind_info, set_bind_status
from .account_binding import binding_snapshot, set_bind_status
from .business_events import record_official_exchange
from .douyu_activity_query import (
query_activity_goods,
@@ -367,8 +367,8 @@ class OverviewMixin:
#
# 这三个值以前**从来没人查过** —— 只是 S6 迁移时从旧的垃圾场列
# `bind_status` 能推的推、推不出的留 `unknown`,于是界面上 97% 显示"未知"。
# 实测校准:开发库 4 个账号里 3 个其实**已绑定**(`is_bound_role=True` 且有角色名),
# 全被 unknown 盖住了。
# 实测校准:最终绑定以 `bindAct=1` 为准;只识别到 `bindRole=1`
# 但尚未 actBind 的账号必须保持 pending。
# 和平小店总开关:关着时**完全跳过**它的所有请求。
# 小店目前是关闭状态,不跳过的话每个账号都会产生一条
# "Livelink登录态校验失败"(实测 200 个里失败 195 次,100%),
@@ -394,17 +394,23 @@ class OverviewMixin:
continue
try:
info = self._fetch_bind_info(client, scope, alias)
derived = derive_from_bind_info(info)
snapshot = binding_snapshot(info)
derived = snapshot["bind_status"]
# 把**明细**也带上:运营要看的是"绑的哪个角色、哪个区服、
# 什么时候能换绑",不是一个"已绑定"就完事。
overview["bind"][scope] = {
"derived": derived,
"role_name": str(info.get("role_name") or info.get("role") or ""),
"area_name": str(info.get("area_name") or ""),
"plat_name": str(info.get("plat_name") or ""),
"nickname": str(info.get("nickname") or ""),
"change_role_wait_time": _ts(info.get("change_role_wait_time")),
"can_change_time": _ts(info.get("can_change_time")),
"phase": snapshot["bind_phase"],
"role_name": snapshot["role_name"],
"area_name": snapshot["area_name"],
"plat_name": snapshot["plat_name"],
"nickname": snapshot["nickname"],
"game_id": snapshot["game_id"],
"game_name": snapshot["game_name"],
"is_change_cooling": snapshot["is_change_cooling"],
"can_change_role": snapshot["can_change_role"],
"change_role_wait_time": _ts(snapshot["change_role_wait_time"]),
"can_change_time": _ts(snapshot["can_change_time"]),
}
if derived is not None:
# 唯一写入者;推不出来(None)时**不动原值** —— 宁可留 unknown,