feat(auth): 微信登录与手机号绑定 / 占用冲突处理(M2 + M3 §10) (#139)

## 背景 / 需求新增「微信登录」链路:用户用微信授权登录 App。openid 已绑账号即直接登入; 未绑则走「绑手机号」建号,并处理「手机号已被别的账号占用」的冲突(M2), 以及绑微信后展示昵称/头像的替换策略(M3 §10)。关键取舍:微信登录**不套用**钱包提现里 bind-wechat 的「撞号即 409」逻辑 ——登录场景 openid 命中就应登入,不能因撞号把用户挡在门外。 ## 改动概览:新增 5 个端点(前缀 `/api/v1/auth`) | 方法 | 路径 | 作用 | |---|---|---| | POST | `/wechat-login` | code→openid。命中已绑用户→直接登入;未命中→签发 `bind_ticket`,返回 `need_bind_phone`(**此刻不建号**);未配 APP_ID/SECRET→503 | | POST | `/wechat/bind-phone/sms` | 持 `bind_ticket` + 手机号 + 短信码绑号 | | POST | `/wechat/bind-phone/jverify` | 持 `bind_ticket` + 极光本机号一键取号绑号 | | POST | `/wechat/conflict/continue` | 占用冲突·继续绑定=**登录老账号**(老号没绑微信则把 openid 绑上;已绑别的微信则只登入、丢弃本次 openid) | | POST | `/wechat/conflict/rebind` | 占用冲突·换绑=**单事务**注销老账号 X(腾号)+ 用该号重建新账号 Y + 写换绑台账;受 30 天限制 | 绑号两条取号路径(sms / jverify)尾段共用 `_finish_wechat_bind`: 手机号未注册→建微信账号(channel=wechat,昵称头像取微信)登入; 已被占用→返回 `phone_occupied`(带占用账号昵称/头像/注册时间/`has_wechat`、 `conflict_ticket`、`rebind_available`、`rebind_blocked_days`),交前端冲突页。冲突页三选一,后端提供 continue / rebind 两个动作(「取消」为前端本地行为)。 ## 关键设计 **两种短时令牌(`core/security.py`,复用 `JWT_SECRET_KEY`,靠 `typ` 区分):** - `bind_ticket`(typ=wechat_bind,sub=openid,附微信昵称/头像,TTL 10min): openid 未命中时下发,覆盖「授权→输手机号→收码→验码」整个绑定流程。 - `conflict_ticket`(typ=wechat_conflict):比 bind_ticket **多编码已验证的手机号**; 换绑 / 继续绑定只认票里的 phone,堵住「拿别人手机号去夺号」的接管漏洞。 **30 天换绑限制:** 新增台账表 `phone_rebind_log`(手机号级、渠道无关), 记录「腾号重建」这一破坏性事件,靠 `rebound_at` 算窗口; 阈值走配置 `PHONE_REBIND_LIMIT_DAYS`。命中限制的换绑请求返回 409。 **M3 §10 昵称/头像替换:** 绑微信默认用微信昵称/头像替换展示, 抽成共享 helper,登录绑号路径与钱包绑微信路径两处共用 (故 `wallet.py`、`tests/test_withdraw.py` 一并有改动)。 --------- Co-authored-by: guke <guke@autohome.com.cn> Reviewed-on: #139
2026-07-17 21:49:10 +08:00
parent b395648b7c
commit 061f6baaf1
13 changed files with 1185 additions and 1 deletions
@@ -87,6 +87,91 @@ def issue_token_pair(user_id: int) -> dict[str, Any]:
    }


+def create_bind_ticket(
+    *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None
+) -> str:
+    """微信登录未命中 openid 时,签发短时"待绑手机"令牌,承载 openid + 微信昵称头像。
+
+    typ='wechat_bind'、sub=openid;有效期 settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES 分钟。
+    与 access/refresh 用同一 JWT_SECRET_KEY 签名,靠 typ 区分,decode_bind_ticket 校验 typ。
+    """
+    now = _now()
+    expire = now + timedelta(minutes=settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES)
+    payload: dict[str, Any] = {
+        "sub": openid,
+        "typ": "wechat_bind",
+        "wnk": wechat_nickname,
+        "wav": wechat_avatar_url,
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+    }
+    return jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_bind_ticket(token: str) -> dict[str, Any]:
+    """解析"待绑手机"令牌,校验签名/过期/类型。失败抛 TokenError。
+
+    返回 {'openid': str, 'wnk': str|None, 'wav': str|None}。
+    """
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+    except jwt.ExpiredSignatureError as e:
+        raise TokenError("bind ticket expired") from e
+    except jwt.InvalidTokenError as e:
+        raise TokenError(f"invalid bind ticket: {e}") from e
+    if payload.get("typ") != "wechat_bind":
+        raise TokenError(f"wrong token type: want=wechat_bind got={payload.get('typ')}")
+    if "sub" not in payload:
+        raise TokenError("bind ticket missing sub")
+    return {"openid": payload["sub"], "wnk": payload.get("wnk"), "wav": payload.get("wav")}
+
+
+def create_conflict_ticket(
+    *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None, phone: str
+) -> str:
+    """手机号占用时签发的短时"冲突处理"令牌。
+
+    比 bind_ticket 多编码 **已验证的手机号 phone** —— 换绑/继续绑定只认它,证明"这对
+    openid/手机号刚在绑号时验证通过",免用户重输验证码,又堵住"拿自己 openid + 任意手机号
+    去夺号"的接管漏洞。typ='wechat_conflict';有效期复用 WECHAT_BIND_TICKET_EXPIRE_MINUTES。
+    """
+    now = _now()
+    expire = now + timedelta(minutes=settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES)
+    payload: dict[str, Any] = {
+        "sub": openid,
+        "typ": "wechat_conflict",
+        "wnk": wechat_nickname,
+        "wav": wechat_avatar_url,
+        "phn": phone,
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+    }
+    return jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_conflict_ticket(token: str) -> dict[str, Any]:
+    """解析"冲突处理"令牌,校验签名/过期/类型。失败抛 TokenError。
+
+    返回 {'openid': str, 'wnk': str|None, 'wav': str|None, 'phone': str}。
+    """
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+    except jwt.ExpiredSignatureError as e:
+        raise TokenError("conflict ticket expired") from e
+    except jwt.InvalidTokenError as e:
+        raise TokenError(f"invalid conflict ticket: {e}") from e
+    if payload.get("typ") != "wechat_conflict":
+        raise TokenError(f"wrong token type: want=wechat_conflict got={payload.get('typ')}")
+    if "sub" not in payload or "phn" not in payload:
+        raise TokenError("conflict ticket missing sub/phn")
+    return {
+        "openid": payload["sub"],
+        "wnk": payload.get("wnk"),
+        "wav": payload.get("wav"),
+        "phone": payload["phn"],
+    }
+
+
 # ===================== 密码 hash(admin 后台账号用)=====================
 # 用户侧是手机号+验证码登录,不存密码;仅 admin 账号用 username+password 登录。