Files
live-hub-py/web/backend/services/account_binding.py
T

405 lines
15 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""角色绑定状态:把三个「垃圾场」列收敛成明确枚举。
## 背景:`bind_status` 崩掉的方式
历史上账号的绑定状态存在**一个自由文本列** `accounts.bind_status` 里,写入方遍布
6 个文件、29 处,取值 20 多种,而且**语义混杂**:
- 真正的状态:`bind_confirmed` / `game_not_bound`
- 动作痕迹:`bind_qr_generated` / `goods_locked` / `elite_opened`
- 纯查询痕迹:`points_queried` / `change_time_queried` / `csrf_token_ready`
因为它是**覆盖式**的,`bind_confirmed` 会被之后任意一次查询(例如
`limited_goods_queried`)盖掉 —— 于是「这个账号到底绑没绑」查不出来。
`esports_bind_status` / `xpd_bind_status` 是同一个病。
## 收敛规则(设计文档 §3.6)
1. **状态列只放「现在是什么」**:`unknown` / `unbound` / `pending` / `bound`;
2. **动作与查询痕迹一律不再写状态列** —— 动作已经进 `account_events`
(S5 的直发事件),查询痕迹本来就不该是状态;
3. 三列各管一个作用域,**一列一义**:
| 列 | 作用域 |
| --- | --- |
| `accounts.role_bind_status` | 精英宝典角色绑定 |
| `accounts.esports_bind_status` | 电竞手册角色绑定 |
| `accounts.xpd_bind_status` | 和平小店角色绑定 |
> ⚠️ `pending` 的含义是「角色已就绪 / 二维码已出,但**还没确认生效**」。
> 斗鱼侧的疑点宁可为 `unknown`,也不要冒充 `bound`。
"""
from __future__ import annotations
from datetime import UTC, datetime, timedelta
from typing import Any
from ..models import Account
# ── 作用域 ──────────────────────────────────────────────
SCOPE_ELITE = "elite"
SCOPE_ESPORTS = "esports"
SCOPE_PEACE = "peace"
ALL_SCOPES = (SCOPE_ELITE, SCOPE_ESPORTS, SCOPE_PEACE)
# ── 取值域(**只有这四个**)────────────────────────────
BIND_UNKNOWN = "unknown" # 还没查过 / 旧数据不可信
BIND_UNBOUND = "unbound" # 明确没绑定
BIND_PENDING = "pending" # 角色就绪或二维码已出,尚未确认生效
BIND_BOUND = "bound" # 确认生效
ALL_BIND_STATES = (BIND_UNKNOWN, BIND_UNBOUND, BIND_PENDING, BIND_BOUND)
BIND_LABELS = {
BIND_UNKNOWN: "未知",
BIND_UNBOUND: "未绑定",
BIND_PENDING: "待确认",
BIND_BOUND: "已绑定",
}
#: 作用域 → `accounts` 上的列名
SCOPE_COLUMNS = {
SCOPE_ELITE: "role_bind_status",
SCOPE_ESPORTS: "esports_bind_status",
SCOPE_PEACE: "xpd_bind_status",
}
#: 作用域 → 接口载荷里的字段前缀。
#: ⚠️ **必须与列名一致**(`role_bind_status` / `esports_bind_status` / `xpd_bind_status`)。
#: 第一版这里按作用域名拼成了 `elite_bind_status` / `peace_bind_status`,
#: 与 schema 声明的字段名对不上 —— Pydantic 会静默用默认值,
#: 表现为「接口永远返回 unknown」,且**不报错**。有一条用例比对 schema 字段名。
SCOPE_PAYLOAD_PREFIX = {
SCOPE_ELITE: "role",
SCOPE_ESPORTS: "esports",
SCOPE_PEACE: "xpd",
}
SCOPE_LABELS = {
SCOPE_ELITE: "精英宝典角色",
SCOPE_ESPORTS: "电竞手册角色",
SCOPE_PEACE: "和平小店角色",
}
# ── 旧自由文本 → 新枚举 ─────────────────────────────────
#
# 只映射**无歧义**的取值;其余一律 `unknown`。判定标准是「这个旧值是不是
# 明确陈述了绑定关系」:
# - `bind_confirmed` 是「确认绑定成功」那一刻写的,而绑定不会被之后的查询撤销
# → 可以确信是 bound;
# - `game_not_bound` 明确说没绑 → unbound;
# - `bind_qr_generated` / `xpd_bind_qr_ready` 只是出了二维码 → pending;
# - `game_queried` / `points_queried` / `goods_locked` 之类**什么都没说**
# → unknown(设计文档 §5.5:不猜测性回填)。
#
# ⚠️ 这三张表**必须与迁移 `20261004_0044` 里的 CASE 逐字对应**,有一条用例
# 真跑那段 SQL 与它们比对(分叉了不会报错,只会让回填结果与运行时不一致)。
LEGACY_ROLE_BIND_MAP: dict[str, str] = {
"bind_confirmed": BIND_BOUND,
"bind_qr_generated": BIND_PENDING,
"game_not_bound": BIND_UNBOUND,
}
LEGACY_ESPORTS_BIND_MAP: dict[str, str] = {
"esports_bound": BIND_BOUND,
"esports_bind_ready": BIND_PENDING,
"esports_bind_confirming": BIND_PENDING,
"esports_qr_created": BIND_PENDING,
"esports_role_switching": BIND_PENDING,
# ⚠️ 这一条是**连生产库看真实数据**才发现的:电竞列里确实存在
# `game_not_bound`(生产 26 行)。漏了它就会被归成 `unknown`,
# 而它明明在说「没绑定」。教训:映射表必须拿**真实取值全集**核对,
# 不能只看文档里举的几个例子。
"game_not_bound": BIND_UNBOUND,
}
LEGACY_XPD_BIND_MAP: dict[str, str] = {
"xpd_bound": BIND_BOUND,
"xpd_bind_qr_ready": BIND_PENDING,
"xpd_not_bound": BIND_UNBOUND,
}
LEGACY_MAPS = {
SCOPE_ELITE: LEGACY_ROLE_BIND_MAP,
SCOPE_ESPORTS: LEGACY_ESPORTS_BIND_MAP,
SCOPE_PEACE: LEGACY_XPD_BIND_MAP,
}
def map_legacy_bind_status(scope: str, legacy: str | None) -> str:
"""旧自由文本 → 新枚举;认不出来就是 `unknown`(**不猜**)。"""
return LEGACY_MAPS.get(scope, {}).get((legacy or "").strip(), BIND_UNKNOWN)
def _assert_prefixes_match_columns() -> None:
"""自检:载荷前缀必须等于列名前缀(`role_bind_status` ↔ `role_bind_*`)。
这是被真实 bug 逼出来的 —— 前缀写错只会让接口静默返回默认值。
"""
for scope, column in SCOPE_COLUMNS.items():
expected = column.removesuffix("_bind_status")
assert SCOPE_PAYLOAD_PREFIX[scope] == expected, (
f"{scope}: 载荷前缀 {SCOPE_PAYLOAD_PREFIX[scope]!r} "
f"与列名 {column!r} 不一致"
)
_assert_prefixes_match_columns()
def get_bind_status(account: Account, scope: str) -> str:
column = SCOPE_COLUMNS.get(scope)
if not column:
raise ValueError(f"未知的绑定作用域: {scope}")
value = getattr(account, column, "") or ""
# 兼容:迁移之前的库或测试构造的对象可能还没有新列的值
return value if value in ALL_BIND_STATES else BIND_UNKNOWN
def set_bind_status(account: Account, scope: str, state: str) -> bool:
"""设置某个作用域的绑定状态,返回是否真的变化。
**这是三个绑定状态列的唯一写入口**(同 `account_lifecycle` 之于 `status`)。
`state` 必须是四个枚举值之一;传旧自由文本会直接报错,避免又把垃圾写回去。
"""
if state not in ALL_BIND_STATES:
raise ValueError(
f"绑定状态只能是 {ALL_BIND_STATES} 之一,收到 {state!r}。"
"动作/查询痕迹请进 account_events,不要写状态列。"
)
column = SCOPE_COLUMNS.get(scope)
if not column:
raise ValueError(f"未知的绑定作用域: {scope}")
if getattr(account, column, None) == state:
return False
setattr(account, column, state)
return True
def bind_payload(account: Account) -> dict[str, str]:
"""给接口/前端用的三列快照(值 + 中文标签)。"""
payload: dict[str, str] = {}
for scope in ALL_SCOPES:
prefix = SCOPE_PAYLOAD_PREFIX[scope]
state = get_bind_status(account, scope)
payload[f"{prefix}_bind_status"] = state
payload[f"{prefix}_bind_label"] = BIND_LABELS[state]
return payload
def derive_from_bind_info(info: dict | None) -> str | None:
"""从斗鱼腾讯绑定信息推导唯一业务状态。
最新抓包证明 `bindRole` 与 `bindAct` 不是同一阶段:
- 扫码选中角色后:`bindRole=1, bindAct=0`,此时应为 `pending`;
- 调用 `actBind` 后:`bindAct=1`,此时才是 `bound`;
- 两个标志都是 0:明确未绑定。
兼容旧接口:如果响应里完全没有 `is_bound_act`,才回退到
`is_bound_role` 判断。新接口始终会带上 `is_bound_act`。
"""
if not isinstance(info, dict):
return None
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
return None
def is_confirmed_binding(info: dict | None) -> bool:
"""是否已经完成最终绑定。
新接口以 `bindAct=1` 为准;旧接口缺少该字段时才回退到 `bindRole`。
"""
if not isinstance(info, dict):
return False
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,
baseline_info: dict | None = None,
) -> 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 ""
)
return bool(
same_alias and baseline_snapshot["is_bound_act"] and snapshot["need_bind_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:
return _explicit_flag(value) is True
def _to_int(value: Any) -> int | None:
try:
return int(float(value))
except (TypeError, ValueError):
return None