feat(auth): M2 POST /wechat/conflict/rebind(换绑=注销X重建Y,单事务)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

alembic/versions/bb47051068c8_device_table.py

@@ -1,59 +0,0 @@
-"""device table(设备档案 / 终端注册)
-
-Revision ID: bb47051068c8
-Revises: comparison_llm_cost
-Create Date: 2026-07-16 14:22:17.770307
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = 'bb47051068c8'
-down_revision: Union[str, Sequence[str], None] = 'comparison_llm_cost'
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    op.create_table(
-        'device',
-        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
-        sa.Column('device_id', sa.String(length=128), nullable=False),
-        sa.Column('user_id', sa.Integer(), nullable=True),
-        sa.Column('platform', sa.String(length=16), nullable=False),
-        sa.Column('oem', sa.String(length=32), nullable=True),
-        sa.Column('model', sa.String(length=64), nullable=True),
-        sa.Column('os_version', sa.String(length=32), nullable=True),
-        sa.Column('app_version', sa.String(length=32), nullable=True),
-        sa.Column('channel', sa.String(length=32), nullable=True),
-        sa.Column('screen', sa.String(length=32), nullable=True),
-        sa.Column('network', sa.String(length=16), nullable=True),
-        sa.Column('timezone', sa.String(length=64), nullable=True),
-        sa.Column('is_emulator', sa.Boolean(), nullable=True),
-        sa.Column('latitude', sa.Float(), nullable=True),
-        sa.Column('longitude', sa.Float(), nullable=True),
-        sa.Column('last_ip', sa.String(length=64), nullable=True),
-        sa.Column('status', sa.String(length=16), nullable=False),
-        sa.Column('last_active_at', sa.DateTime(timezone=True), nullable=True),
-        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
-        sa.Column('updated_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
-        sa.ForeignKeyConstraint(['user_id'], ['user.id'], ),
-        sa.PrimaryKeyConstraint('id'),
-    )
-    with op.batch_alter_table('device', schema=None) as batch_op:
-        batch_op.create_index(batch_op.f('ix_device_device_id'), ['device_id'], unique=True)
-        batch_op.create_index(batch_op.f('ix_device_last_active_at'), ['last_active_at'], unique=False)
-        batch_op.create_index(batch_op.f('ix_device_user_id'), ['user_id'], unique=False)
-
-
-def downgrade() -> None:
-    with op.batch_alter_table('device', schema=None) as batch_op:
-        batch_op.drop_index(batch_op.f('ix_device_user_id'))
-        batch_op.drop_index(batch_op.f('ix_device_last_active_at'))
-        batch_op.drop_index(batch_op.f('ix_device_device_id'))
-
-    op.drop_table('device')

alembic/versions/phone_rebind_log.py

@@ -0,0 +1,32 @@
+"""phone_rebind_log 表(M2 换绑 30 天限制台账)
+
+Revision ID: phone_rebind_log
+Revises: comparison_llm_cost
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "phone_rebind_log"
+down_revision = "comparison_llm_cost"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "phone_rebind_log",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("phone", sa.String(length=20), nullable=False),
+        sa.Column("old_user_id", sa.Integer(), nullable=True),
+        sa.Column("new_user_id", sa.Integer(), nullable=False),
+        sa.Column("source", sa.String(length=32), nullable=False, server_default="wechat_conflict"),
+        sa.Column("rebound_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_phone_rebind_log_phone", "phone_rebind_log", ["phone"])
+    op.create_index("ix_phone_rebind_log_rebound_at", "phone_rebind_log", ["rebound_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_phone_rebind_log_rebound_at", table_name="phone_rebind_log")
+    op.drop_index("ix_phone_rebind_log_phone", table_name="phone_rebind_log")
+    op.drop_table("phone_rebind_log")

app/admin/repositories/queries.py

@@ -20,7 +20,7 @@ from app.models.admin import AdminAuditLog
 from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
 from app.models.coupon_state import CouponPromptEngagement
-from app.models.device_liveness import DeviceLiveness
+from app.models.device import DeviceLiveness
 from app.models.feedback import Feedback
 from app.models.onboarding import OnboardingCompletion
 from app.models.price_report import PriceReport

app/api/v1/auth.py

@@ -13,18 +13,30 @@ from __future__ import annotations
 import logging
 
 from fastapi import APIRouter, HTTPException, Request, status
+from sqlalchemy.exc import IntegrityError
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import test_account
 from app.core.ratelimit import enforce_rate_limit
-from app.core.security import TokenError, decode_token, issue_token_pair
+from app.core.security import (
+    TokenError,
+    create_bind_ticket,
+    create_conflict_ticket,
+    decode_bind_ticket,
+    decode_conflict_ticket,
+    decode_token,
+    issue_token_pair,
+)
+from app.integrations import wxpay
 from app.integrations.jiguang import JiguangError, mask_phone, verify_and_get_phone
 from app.integrations.sms import SmsError, send_code, verify_code
 from app.repositories import onboarding as onboarding_repo
+from app.repositories import phone_rebind as rebind_repo
 from app.repositories import user as user_repo
 from app.schemas.auth import (
     JverifyLoginRequest,
     LogoutResponse,
+    OccupiedAccountInfo,
     RefreshRequest,
     SmsLoginRequest,
     SmsSendRequest,
@@ -32,6 +44,13 @@ from app.schemas.auth import (
     TokenPair,
     TokenWithUser,
     UserOut,
+    WechatBindPhoneJverifyRequest,
+    WechatBindPhoneSmsRequest,
+    WechatBindResultResponse,
+    WechatConflictContinueRequest,
+    WechatConflictRebindRequest,
+    WechatLoginRequest,
+    WechatLoginResponse,
 )
 
 logger = logging.getLogger("shagua.auth")
@@ -166,6 +185,261 @@ def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWit
     return _login_response(user, onboarding_completed=completed)
 
 
+# ===================== 微信登录 =====================
+
+@router.post(
+    "/wechat-login",
+    response_model=WechatLoginResponse,
+    summary="微信登录(openid 命中即登入,否则发绑号令牌)",
+)
+def wechat_login(req: WechatLoginRequest, db: DbSession) -> WechatLoginResponse:
+    from app.core.config import settings  # 局部 import,避免循环
+
+    # 微信登录只需 code→openid(sns/oauth2),不需要商户转账证书;故只校验 APP_ID/SECRET。
+    if not (settings.WECHAT_APP_ID and settings.WECHAT_APP_SECRET):
+        raise HTTPException(status_code=503, detail="wechat login not configured")
+
+    try:
+        info = wxpay.code_to_userinfo(req.code)  # {openid, nickname, avatar_url, raw};失败抛 ValueError
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    openid = info["openid"]
+    user = user_repo.get_user_by_wechat_openid(db, openid)
+    if user is not None:
+        # openid 命中 → 直接登入(绝不套用提现 bind-wechat 的"撞号即 409"逻辑)
+        if user.status != "active":
+            raise HTTPException(status_code=403, detail="account disabled")
+        user_repo.touch_last_login(db, user)
+        completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+        logger.info("wechat_login hit user_id=%d openid=%s*** onboarded=%s", user.id, openid[:6], completed)
+        return WechatLoginResponse(
+            status="logged_in",
+            token=_login_response(user, onboarding_completed=completed),
+        )
+
+    # 未命中 → 签发短时 bind_ticket,进手机号绑定流程(账号此刻还不建)
+    ticket = create_bind_ticket(
+        openid=openid,
+        wechat_nickname=info["nickname"],
+        wechat_avatar_url=info["avatar_url"],
+    )
+    logger.info("wechat_login new openid=%s*** issue bind_ticket", openid[:6])
+    return WechatLoginResponse(
+        status="need_bind_phone",
+        bind_ticket=ticket,
+        wechat_nickname=info["nickname"],
+        wechat_avatar_url=info["avatar_url"],
+    )
+
+
+def _finish_wechat_bind(
+    db,
+    *,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+    phone: str,
+    device_id: str,
+) -> WechatBindResultResponse:
+    """绑手机建号的公共尾段:手机号被占用 → 返回 phone_occupied(M2 处理 3 选 1);
+    未占用 → 新建微信账号(channel=wechat,昵称头像取微信)→ 签 token 登入。"""
+    existing = user_repo.get_user_by_phone(db, phone)
+    if existing is not None:
+        from app.core.config import settings  # 局部 import,避免循环
+
+        ticket = create_conflict_ticket(
+            openid=openid,
+            wechat_nickname=wechat_nickname,
+            wechat_avatar_url=wechat_avatar_url,
+            phone=phone,
+        )
+        blocked = rebind_repo.rebound_within_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+        logger.info(
+            "wechat bind phone occupied phone=%s by user_id=%d has_wechat=%s",
+            mask_phone(phone), existing.id, bool(existing.wechat_openid),
+        )
+        return WechatBindResultResponse(
+            status="phone_occupied",
+            occupied_account=OccupiedAccountInfo(
+                nickname=existing.nickname,
+                avatar_url=existing.avatar_url,
+                created_at=existing.created_at,
+                has_wechat=bool(existing.wechat_openid),
+            ),
+            conflict_ticket=ticket,
+            rebind_available=not blocked,
+            rebind_blocked_days=(
+                rebind_repo.remaining_block_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+                if blocked else 0
+            ),
+        )
+    user = user_repo.create_wechat_user(
+        db,
+        phone=phone,
+        openid=openid,
+        wechat_nickname=wechat_nickname,
+        wechat_avatar_url=wechat_avatar_url,
+    )
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=device_id)
+    logger.info("wechat bind ok user_id=%d phone=%s openid=%s*** onboarded=%s",
+                user.id, mask_phone(phone), openid[:6], completed)
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
+@router.post(
+    "/wechat/bind-phone/sms",
+    response_model=WechatBindResultResponse,
+    summary="微信登录·其他手机号(短信)绑定",
+)
+def wechat_bind_phone_sms(
+    req: WechatBindPhoneSmsRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_bind_ticket(req.bind_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="授权已过期,请重新用微信登录") from e
+
+    # 防刷:同 sms/login,按 设备+IP 每小时限流(放在验证码校验之前,失败也计数)
+    enforce_rate_limit(
+        request,
+        scope="wechat-bind-sms-device",
+        subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR,
+        window_sec=3600,
+        detail="登录尝试过于频繁,请稍后再试",
+    )
+
+    if not verify_code(req.phone, req.code):
+        raise HTTPException(status_code=400, detail="invalid sms code")
+
+    return _finish_wechat_bind(
+        db,
+        openid=claims["openid"],
+        wechat_nickname=claims["wnk"],
+        wechat_avatar_url=claims["wav"],
+        phone=req.phone,
+        device_id=req.device_id,
+    )
+
+
+@router.post(
+    "/wechat/bind-phone/jverify",
+    response_model=WechatBindResultResponse,
+    summary="微信登录·本机号(极光)绑定",
+)
+def wechat_bind_phone_jverify(
+    req: WechatBindPhoneJverifyRequest, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_bind_ticket(req.bind_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="授权已过期,请重新用微信登录") from e
+
+    try:
+        phone = verify_and_get_phone(req.login_token)
+    except JiguangError as e:
+        logger.error("[JG] verify+decrypt failed: %s", e, exc_info=True)
+        raise HTTPException(status_code=502, detail=f"jiguang verify failed: {e}") from e
+
+    return _finish_wechat_bind(
+        db,
+        openid=claims["openid"],
+        wechat_nickname=claims["wnk"],
+        wechat_avatar_url=claims["wav"],
+        phone=phone,
+        device_id=req.device_id,
+    )
+
+
+# ===================== 微信占用冲突(M2) =====================
+
+@router.post(
+    "/wechat/conflict/continue",
+    response_model=WechatBindResultResponse,
+    summary="微信占用冲突·继续绑定(登录老账号,能绑就绑)",
+)
+def wechat_conflict_continue(
+    req: WechatConflictContinueRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_conflict_ticket(req.conflict_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="操作超时,请重新用微信登录") from e
+
+    enforce_rate_limit(
+        request, scope="wechat-conflict-device", subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR, window_sec=3600, detail="操作过于频繁,请稍后再试",
+    )
+
+    user = user_repo.get_user_by_phone(db, claims["phone"])
+    if user is None:
+        # P 期间被腾空(老账号改号/注销)→ 前提已变,让前端重走
+        raise HTTPException(status_code=409, detail="账号状态已变化,请重新登录")
+    if user.status != "active":
+        raise HTTPException(status_code=403, detail="account disabled")
+
+    if user.wechat_openid is None:
+        try:
+            user_repo.attach_wechat_to_user(
+                db, user, openid=claims["openid"],
+                wechat_nickname=claims["wnk"], wechat_avatar_url=claims["wav"],
+            )
+        except IntegrityError:
+            db.rollback()  # openid 被别处绑走 → 只登入不绑
+            user_repo.touch_last_login(db, user)
+    else:
+        user_repo.touch_last_login(db, user)  # X 已绑别的微信 → 只登入,丢弃本次 openid
+
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("wechat conflict continue user_id=%d openid=%s***", user.id, claims["openid"][:6])
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
+@router.post(
+    "/wechat/conflict/rebind",
+    response_model=WechatBindResultResponse,
+    summary="微信占用冲突·换绑(注销老账号+用该号重建全新账号)",
+)
+def wechat_conflict_rebind(
+    req: WechatConflictRebindRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    from app.core.config import settings  # 局部 import,避免循环
+
+    try:
+        claims = decode_conflict_ticket(req.conflict_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="操作超时,请重新用微信登录") from e
+
+    enforce_rate_limit(
+        request, scope="wechat-conflict-device", subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR, window_sec=3600, detail="操作过于频繁,请稍后再试",
+    )
+
+    phone = claims["phone"]
+    if rebind_repo.rebound_within_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS):
+        days = rebind_repo.remaining_block_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+        raise HTTPException(status_code=409, detail=f"该手机号 {days} 天内已换绑过,暂不能再次换绑")
+
+    user = user_repo.rebind_account(
+        db, phone=phone, openid=claims["openid"],
+        wechat_nickname=claims["wnk"], wechat_avatar_url=claims["wav"],
+    )
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("wechat conflict rebind new_user_id=%d phone=%s openid=%s***",
+                user.id, mask_phone(phone), claims["openid"][:6])
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
 # ===================== Refresh =====================
 
 @router.post("/refresh", response_model=TokenPair, summary="用 refresh_token 换新 token 对")

app/api/v1/device_profile.py

@@ -1,51 +0,0 @@
-"""设备档案上报 endpoint(device 表)。
-
-POST /api/v1/device/report — 客户端上报设备当前信息,按 device_id upsert 到 device 表。
-软鉴权:带合法 Bearer → 设备关联到该用户;游客态(无 token)也接受,user_id 暂空。
-
-注意与 /api/v1/device/register(app/api/v1/device.py)区分:那个是无障碍存活注册,写
-device_liveness 表、硬鉴权;本端点是设备信息档案,写 device 表、软鉴权。
-"""
-from __future__ import annotations
-
-import logging
-
-from fastapi import APIRouter, Request
-
-from app.api.deps import DbSession, OptionalUser
-from app.repositories import device_profile as device_profile_repo
-from app.schemas.device_profile import DeviceReportOut, DeviceReportRequest
-
-logger = logging.getLogger("shagua.device_profile")
-
-router = APIRouter(prefix="/api/v1/device", tags=["device"])
-
-
-def _client_ip(request: Request) -> str | None:
-    """客户端 IP:生产经 nginx 反代优先 X-Forwarded-For 第一段,否则直连 IP。"""
-    xff = request.headers.get("x-forwarded-for")
-    if xff:
-        return xff.split(",")[0].strip()
-    return request.client.host if request.client else None
-
-
-@router.post("/report", response_model=DeviceReportOut, summary="上报设备信息(设备档案 upsert)")
-def report_device(
-    req: DeviceReportRequest,
-    request: Request,
-    user: OptionalUser,
-    db: DbSession,
-) -> DeviceReportOut:
-    device = device_profile_repo.upsert_device(
-        db,
-        req,
-        user_id=user.id if user else None,
-        last_ip=_client_ip(request),
-    )
-    logger.info(
-        "device report device_id=%s user_id=%s has_loc=%s",
-        req.device_id,
-        device.user_id,
-        req.latitude is not None,
-    )
-    return DeviceReportOut()

app/core/config.py

@@ -44,6 +44,11 @@ class Settings(BaseSettings):
     JWT_ALGORITHM: str = "HS256"
     JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 120
     JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+    # 微信登录未命中 openid 时签发的"待绑手机"令牌有效期(JWT_SECRET_KEY 签名,typ=wechat_bind;
+    # 见 security.create_bind_ticket)。需覆盖"授权→输手机号→收短信→输验证码"整个绑定流程。
+    WECHAT_BIND_TICKET_EXPIRE_MINUTES: int = 10
+    # 一个手机号 30 天内最多换绑一次(微信占用冲突页的"换绑"动作)。见 phone_rebind_log。
+    PHONE_REBIND_LIMIT_DAYS: int = 30
 
     # ===== Admin 后台 =====
     # admin 用独立 JWT secret(≠ JWT_SECRET_KEY),App 用户 token 无法越权访问后台。
@@ -81,6 +86,7 @@ class Settings(BaseSettings):
     SMS_SIGN_ID: int = 31729       # 极光短信签名 ID(非机密,可被 .env 覆盖)
     SMS_TEMPLATE_ID: int = 1       # 极光短信模板 ID(变量名 code,有效期 5 分钟)
     SMS_CODE_LENGTH: int = 6       # 验证码位数(本服务生成;前端 code 字段 4-8 位兼容)
+    SMS_DAILY_LIMIT_PER_PHONE: int = 10   # 单手机号每日发送上限(防刷 + 控费)
     SMS_MAX_VERIFY_ATTEMPTS: int = 5      # 单个验证码最多校验失败次数,超过即作废(防爆破)
 
     # ===== 测试账号(release 包全流程联调用)=====
@@ -106,6 +112,9 @@ class Settings(BaseSettings):
     # 美团调用走的代理。本机开发直连美团会 SSL EOF,需填 http://127.0.0.1:7897;
     # 线上国内服务器留空(=直连)。见 .env.example 与 integrations/meituan.py。
     MT_CPS_PROXY: str = ""
+    # 本地开发:开启后 /feed 接口直接返回 mock 数据,不调美团 API、不查离线库,
+    # 方便前端联调 feed 卡片样式、分页、距离排序等 UI。生产必须 false。
+    MT_CPS_MOCK_FEED: bool = True
 
     @property
     def mt_cps_configured(self) -> bool:

app/core/security.py

@@ -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 登录。
 

app/main.py

@@ -28,7 +28,6 @@ from app.api.v1.compare_record import router as compare_record_router
 from app.api.v1.coupon import router as coupon_router
 from app.api.v1.cps_redirect import router as cps_redirect_router
 from app.api.v1.device import router as device_router
-from app.api.v1.device_profile import router as device_profile_router
 from app.api.v1.feedback import router as feedback_router
 from app.api.v1.invite import router as invite_router
 from app.api.v1.meituan import router as meituan_router
@@ -121,7 +120,6 @@ app.include_router(analytics_router)
 app.include_router(invite_router)
 app.include_router(coupon_router)
 app.include_router(device_router)
-app.include_router(device_profile_router)
 app.include_router(compare_router)
 app.include_router(compare_record_router)
 app.include_router(compare_milestone_router)

app/models/__init__.py

@@ -19,8 +19,7 @@ from app.models.cps_link import CpsClick, CpsLink  # noqa: F401
 from app.models.cps_order import CpsOrder  # noqa: F401
 from app.models.cps_wx_user import CpsWxUser  # noqa: F401
 from app.models.comparison_milestone import ComparisonMilestoneClaim  # noqa: F401
-from app.models.device import Device  # noqa: F401
-from app.models.device_liveness import DeviceLiveness  # noqa: F401
+from app.models.device import DeviceLiveness  # noqa: F401
 from app.models.coupon_state import (  # noqa: F401
     CouponClaimRecord,
     CouponDailyCompletion,
@@ -33,6 +32,7 @@ from app.models.invite_fingerprint import InviteFingerprint  # noqa: F401
 from app.models.launch_confirm_sample import LaunchConfirmSample  # noqa: F401
 from app.models.meituan_coupon import MeituanCoupon  # noqa: F401
 from app.models.onboarding import OnboardingCompletion  # noqa: F401
+from app.models.phone_rebind_log import PhoneRebindLog  # noqa: F401
 from app.models.ops_marquee_seed import OpsMarqueeSeed  # noqa: F401
 from app.models.ops_stat_config import OpsStatConfig  # noqa: F401
 from app.models.price_observation import PriceObservation  # noqa: F401

app/models/device.py

@@ -1,71 +1,83 @@
-"""设备表(设备档案 / 终端注册)。
+"""设备表(无障碍保护存活检测 + 极光推送)。
 
-每条 = 一台设备,以客户端生成的 device_id 唯一标识(格式 device_<MODEL>_<8hex>,
-per-install;见 pricebot 客户端 PriceBotService.getOrCreateDeviceId)。登录前(游客态)
-即可建档,登录后回填 user_id ——单表只记「最近一个」登录用户,不保留一机多号历史。
+每条 = 一个用户的一台设备(per-install,device_id 由客户端 DeviceId.get() 生成)。
+客户端的无障碍服务存活时周期上报心跳刷新 last_heartbeat_at;App 前台/登录时上报
+registration_id(极光推送目标)。后端 heartbeat_monitor_worker 扫描「曾经保护过、
+现在心跳超时」的设备,通过极光推送提醒用户重开无障碍。
 
-字段采集来源(逐列见注释):
-  已在埋点 analytics_event 采集     : oem / os_version / model / app_version / channel / network
-  服务端补                          : last_ip(X-Forwarded-For)、last_active_at
-  客户端需「新增」上报(无需权限)   : timezone、is_emulator
-  客户端需「新增」上报 + 定位权限 + 隐私合规(PIPL 敏感信息): latitude / longitude
-
-与 device_liveness(无障碍存活/极光推送,见 device_liveness.py)是两张相互独立的表,
-靠同一个 device_id 关联,不要合并。
+liveness_state 状态机(防刷屏,一次掉线只推一条):
+  unknown → alive(收到 service 心跳)→ silent/notified(扫描发现超时并已推送)
+  心跳恢复时 handler 重置回 alive。
+见 spec: spec/accessibility-liveness-push.md。
 """
 from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import Boolean, DateTime, Float, ForeignKey, Integer, String, func
+from sqlalchemy import (
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    UniqueConstraint,
+    func,
+)
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
 
 
-class Device(Base):
-    __tablename__ = "device"
+class DeviceLiveness(Base):
+    # 表名不叫 device:device 易被当成「设备信息(品牌/型号/系统)」表;本表实为**无障碍存活监控状态**
+    # (心跳 last_heartbeat_at + liveness_state + kill_alert_pending + 推送目标 registration_id),故名 device_liveness。
+    __tablename__ = "device_liveness"
+    __table_args__ = (
+        UniqueConstraint("user_id", "device_id", name="uq_device_liveness_user_device"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-
-    # 客户端生成的设备唯一 ID(全局唯一);与 analytics_event / device_liveness 用同一个值
-    device_id: Mapped[str] = mapped_column(
-        String(128), unique=True, index=True, nullable=False
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
     )
-    # 关联用户:登录后回填「最近一次登录」的 user;游客态为空(可空 → 不阻塞未登录建档)
-    user_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("user.id"), index=True, nullable=True
+    # 客户端 DeviceId.get() 生成的 per-install id(如 device_Pixel_ab12cd34)
+    device_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
+    # 极光推送 registration id;拿到才填(JCollectionAuth 同意后才下发)
+    registration_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    platform: Mapped[str] = mapped_column(String(16), nullable=False, default="android")
+    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
+
+    # 收到过 service 心跳即 true(=该设备开过无障碍,功能对它有意义)
+    ever_protected: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
     )
-
-    # ---- 设备 / 系统信息(埋点已采集,注册/上报接口带过来即可) ----
-    platform: Mapped[str] = mapped_column(String(16), nullable=False, default="android")  # android/ios/harmony
-    oem: Mapped[str | None] = mapped_column(String(32), nullable=True)          # 厂商 Build.MANUFACTURER:xiaomi/huawei…
-    model: Mapped[str | None] = mapped_column(String(64), nullable=True)        # 型号 Build.MODEL,如 PJF110
-    os_version: Mapped[str | None] = mapped_column(String(32), nullable=True)   # 系统版本,如 "Android 13"
-    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)  # app 版本
-    channel: Mapped[str | None] = mapped_column(String(32), nullable=True)      # 安装渠道(应用市场)
-    screen: Mapped[str | None] = mapped_column(String(32), nullable=True)       # 分辨率 "1080x2400"
-    network: Mapped[str | None] = mapped_column(String(16), nullable=True)      # 最近网络类型 wifi/4g/5g
-
-    # ---- 需客户端「新增」上报的字段 ----
-    # 设备时区 TimeZone.getDefault().id,如 "Asia/Shanghai"(客户端需新增上报,无需权限)
-    timezone: Mapped[str | None] = mapped_column(String(64), nullable=True)
-    # 是否模拟器(客户端 Build 指纹判断后上报;NULL=未知,无需权限)
-    is_emulator: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
-    # 位置(经纬度):App 会申请定位权限,但可能拿不到(首次运行未授权 / 用户拒绝 / 关了 GPS)。
-    # 规则(leader 定):每次上报以实际为准——能拿到就写,拿不到就置 NULL 清空旧值。
-    # ⚠️ upsert 时 lat/lng 必须「整字段覆盖(含 None)」,不能像 model/oem 那样 COALESCE 保留旧值,
-    #    否则会留下一条早已离开该位置的陈旧坐标。
-    latitude: Mapped[float | None] = mapped_column(Float, nullable=True)
-    longitude: Mapped[float | None] = mapped_column(Float, nullable=True)
-
-    # ---- 上下文 / 状态(服务端维护) ----
-    last_ip: Mapped[str | None] = mapped_column(String(64), nullable=True)      # 最近一次上报 IP(服务端从 X-Forwarded-For 取)
-    status: Mapped[str] = mapped_column(String(16), nullable=False, default="normal")  # normal/banned(风控封设备)
-    # 最近活跃时间(设备维度 DAU / 留存统计用;updated_at 只在字段真变化时跳,故单列一个)
-    last_active_at: Mapped[datetime | None] = mapped_column(
+    # 首次开无障碍(首次收到 accessibility_enabled 心跳)的时刻;ever_protected 第一次翻 true 时记一次,
+    # 后续心跳不覆盖。老设备(迁移前已 protected)无此值 → NULL。
+    first_protected_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # 最近一次 service 心跳时间(存活证明);超时即视为保护掉线
+    last_heartbeat_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), index=True, nullable=True
     )
+    # 最近一次上报的无障碍开关状态(观测用)
+    last_report_protection_on: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
+    # unknown / alive / silent / notified
+    liveness_state: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="unknown"
+    )
+    # 最近一次推送告警时间
+    notified_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+    # 掉线告警「待客户端提醒」标记(后置检测 pull 版, 见 spec accessibility-liveness-pull-prompt.md)。
+    # 与 liveness_state 解耦: worker 检出掉线即置 True; touch_heartbeat(心跳恢复)不动它
+    # → 规避「服务随 App 重启先发心跳、state 被重置回 alive → 客户端进 App 漏看」竞态; 只由客户端 ack 清。
+    kill_alert_pending: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False
+    )
 
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), nullable=False
@@ -78,4 +90,7 @@ class Device(Base):
     )
 
     def __repr__(self) -> str:  # pragma: no cover
-        return f"<Device id={self.id} device_id={self.device_id} user_id={self.user_id}>"
+        return (
+            f"<DeviceLiveness id={self.id} user_id={self.user_id} "
+            f"device_id={self.device_id} state={self.liveness_state}>"
+        )

app/models/device_liveness.py

@@ -1,96 +0,0 @@
-"""设备表(无障碍保护存活检测 + 极光推送)。
-
-每条 = 一个用户的一台设备(per-install,device_id 由客户端 DeviceId.get() 生成)。
-客户端的无障碍服务存活时周期上报心跳刷新 last_heartbeat_at;App 前台/登录时上报
-registration_id(极光推送目标)。后端 heartbeat_monitor_worker 扫描「曾经保护过、
-现在心跳超时」的设备,通过极光推送提醒用户重开无障碍。
-
-liveness_state 状态机(防刷屏,一次掉线只推一条):
-  unknown → alive(收到 service 心跳)→ silent/notified(扫描发现超时并已推送)
-  心跳恢复时 handler 重置回 alive。
-见 spec: spec/accessibility-liveness-push.md。
-"""
-from __future__ import annotations
-
-from datetime import datetime
-
-from sqlalchemy import (
-    Boolean,
-    DateTime,
-    ForeignKey,
-    Integer,
-    String,
-    UniqueConstraint,
-    func,
-)
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.db.base import Base
-
-
-class DeviceLiveness(Base):
-    # 表名不叫 device:device 易被当成「设备信息(品牌/型号/系统)」表;本表实为**无障碍存活监控状态**
-    # (心跳 last_heartbeat_at + liveness_state + kill_alert_pending + 推送目标 registration_id),故名 device_liveness。
-    __tablename__ = "device_liveness"
-    __table_args__ = (
-        UniqueConstraint("user_id", "device_id", name="uq_device_liveness_user_device"),
-    )
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    user_id: Mapped[int] = mapped_column(
-        Integer, ForeignKey("user.id"), index=True, nullable=False
-    )
-    # 客户端 DeviceId.get() 生成的 per-install id(如 device_Pixel_ab12cd34)
-    device_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
-    # 极光推送 registration id;拿到才填(JCollectionAuth 同意后才下发)
-    registration_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
-    platform: Mapped[str] = mapped_column(String(16), nullable=False, default="android")
-    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
-
-    # 收到过 service 心跳即 true(=该设备开过无障碍,功能对它有意义)
-    ever_protected: Mapped[bool] = mapped_column(
-        Boolean, nullable=False, default=False
-    )
-    # 首次开无障碍(首次收到 accessibility_enabled 心跳)的时刻;ever_protected 第一次翻 true 时记一次,
-    # 后续心跳不覆盖。老设备(迁移前已 protected)无此值 → NULL。
-    first_protected_at: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), nullable=True
-    )
-    # 最近一次 service 心跳时间(存活证明);超时即视为保护掉线
-    last_heartbeat_at: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), index=True, nullable=True
-    )
-    # 最近一次上报的无障碍开关状态(观测用)
-    last_report_protection_on: Mapped[bool] = mapped_column(
-        Boolean, nullable=False, default=False
-    )
-    # unknown / alive / silent / notified
-    liveness_state: Mapped[str] = mapped_column(
-        String(16), nullable=False, default="unknown"
-    )
-    # 最近一次推送告警时间
-    notified_at: Mapped[datetime | None] = mapped_column(
-        DateTime(timezone=True), nullable=True
-    )
-    # 掉线告警「待客户端提醒」标记(后置检测 pull 版, 见 spec accessibility-liveness-pull-prompt.md)。
-    # 与 liveness_state 解耦: worker 检出掉线即置 True; touch_heartbeat(心跳恢复)不动它
-    # → 规避「服务随 App 重启先发心跳、state 被重置回 alive → 客户端进 App 漏看」竞态; 只由客户端 ack 清。
-    kill_alert_pending: Mapped[bool] = mapped_column(
-        Boolean, nullable=False, default=False
-    )
-
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=func.now(), nullable=False
-    )
-    updated_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True),
-        server_default=func.now(),
-        onupdate=func.now(),
-        nullable=False,
-    )
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return (
-            f"<DeviceLiveness id={self.id} user_id={self.user_id} "
-            f"device_id={self.device_id} state={self.liveness_state}>"
-        )

app/models/phone_rebind_log.py

@@ -0,0 +1,31 @@
+"""手机号换绑台账。
+
+记录"手机号从老账号被夺走、重建为新账号(X 注销 → Y)"这一破坏性事件,支撑"一个手机号
+30 天内最多换绑一次"的限制。手机号级、渠道无关(source 标来源);普通微信绑定不写此表。
+见 M2 spec §4.1。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class PhoneRebindLog(Base):
+    __tablename__ = "phone_rebind_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 被换绑的真实手机号(注意:存真实号,不是老账号被腾号后的 deleted_<id>)
+    phone: Mapped[str] = mapped_column(String(20), index=True, nullable=False)
+    # 被注销的老账号 X;P 换绑时已被腾空(极边界)则为空
+    old_user_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 换绑后新建的账号 Y
+    new_user_id: Mapped[int] = mapped_column(Integer, nullable=False)
+    # 换绑来源。手机号级配额、渠道无关,留字段给未来其他换绑路径共用同一份 30 天限制。
+    source: Mapped[str] = mapped_column(String(32), nullable=False, default="wechat_conflict")
+    rebound_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )

app/repositories/device.py

@@ -6,7 +6,7 @@ from datetime import datetime, timedelta, timezone
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app.models.device_liveness import DeviceLiveness
+from app.models.device import DeviceLiveness
 
 
 def _get(db: Session, *, user_id: int, device_id: str) -> DeviceLiveness | None:

app/repositories/device_profile.py

@@ -1,66 +0,0 @@
-"""device 表(设备档案)读写:按 device_id upsert。
-
-与 repositories/device.py(无障碍存活 DeviceLiveness)是不同的表:本文件写 device 表。
-"""
-from __future__ import annotations
-
-from datetime import datetime, timezone
-
-from sqlalchemy import select
-from sqlalchemy.orm import Session
-
-from app.models.device import Device
-from app.schemas.device_profile import DeviceReportRequest
-
-# 设备/系统信息:提供了(非 None)才覆盖,某次上报漏带不会把已有值冲掉
-_STICKY_STR_FIELDS = ("oem", "model", "os_version", "app_version", "channel", "screen", "network", "timezone")
-
-
-def upsert_device(
-    db: Session,
-    req: DeviceReportRequest,
-    *,
-    user_id: int | None,
-    last_ip: str | None,
-) -> Device:
-    """按 device_id upsert 一台设备的档案。
-
-    写入策略分三类:
-      - 设备/系统信息(_STICKY_STR_FIELDS + platform + is_emulator):非空才覆盖(sticky)。
-      - 位置 latitude/longitude:**整字段覆盖,含 None**——以本次上报实际为准,拿不到即清空
-        (leader 规则,见 model Device.latitude 注释;不能像上面那样 sticky)。
-      - user_id:仅登录态(user_id 非 None)回填为当前登录用户;游客态保留已有关联,不清空。
-    last_active_at / last_ip 每次刷新。
-    """
-    now = datetime.now(timezone.utc)
-    device = db.execute(
-        select(Device).where(Device.device_id == req.device_id)
-    ).scalar_one_or_none()
-    if device is None:
-        device = Device(device_id=req.device_id)
-        db.add(device)
-
-    # 设备/系统信息:非空才覆盖
-    if req.platform:
-        device.platform = req.platform
-    for field in _STICKY_STR_FIELDS:
-        val = getattr(req, field)
-        if val is not None:
-            setattr(device, field, val)
-    if req.is_emulator is not None:
-        device.is_emulator = req.is_emulator
-
-    # 位置:整字段覆盖(含 None),以本次实际为准
-    device.latitude = req.latitude
-    device.longitude = req.longitude
-
-    # 关联用户:仅登录态回填,游客态不动
-    if user_id is not None:
-        device.user_id = user_id
-
-    device.last_ip = last_ip
-    device.last_active_at = now
-
-    db.commit()
-    db.refresh(device)
-    return device

app/repositories/phone_rebind.py

@@ -0,0 +1,39 @@
+"""手机号换绑台账(phone_rebind_log)的查询与写入。见 M2 spec §4.1。"""
+from __future__ import annotations
+
+import math
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.phone_rebind_log import PhoneRebindLog
+
+
+def rebound_within_days(db: Session, phone: str, days: int) -> bool:
+    """该手机号在最近 days 天内是否换绑过(命中 → 禁止再次换绑)。"""
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    stmt = (
+        select(PhoneRebindLog.id)
+        .where(PhoneRebindLog.phone == phone, PhoneRebindLog.rebound_at >= since)
+        .limit(1)
+    )
+    return db.execute(stmt).first() is not None
+
+
+def remaining_block_days(db: Session, phone: str, days: int) -> int:
+    """距离该手机号可再次换绑还剩几天(向上取整;无记录返回 0)。"""
+    last = db.execute(
+        select(func.max(PhoneRebindLog.rebound_at)).where(PhoneRebindLog.phone == phone)
+    ).scalar_one_or_none()
+    if last is None:
+        return 0
+    if last.tzinfo is None:  # SQLite 取回 naive datetime,按 UTC 归一
+        last = last.replace(tzinfo=timezone.utc)
+    remaining = (last + timedelta(days=days) - datetime.now(timezone.utc)).total_seconds()
+    return max(0, math.ceil(remaining / 86400))
+
+
+def add_rebind_log(db: Session, *, phone: str, old_user_id: int | None, new_user_id: int, source: str) -> None:
+    """写一条换绑台账(**不 commit**,交给调用方 rebind_account 的单事务)。"""
+    db.add(PhoneRebindLog(phone=phone, old_user_id=old_user_id, new_user_id=new_user_id, source=source))

app/repositories/user.py

@@ -12,6 +12,7 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.models.user import User
+from app.repositories import phone_rebind
 
 
 # ===== 创建时分配的标识:用户名(对外展示账号 ID)+ 默认昵称 =====
@@ -86,6 +87,83 @@ def get_user_by_phone(db: Session, phone: str) -> User | None:
     return db.execute(stmt).scalar_one_or_none()
 
 
+def get_user_by_wechat_openid(db: Session, openid: str) -> User | None:
+    stmt = select(User).where(User.wechat_openid == openid)
+    return db.execute(stmt).scalar_one_or_none()
+
+
+def touch_last_login(db: Session, user: User) -> User:
+    """openid 命中登录时更新 last_login_at(手机号登录在 upsert_user_for_login 里已更新)。"""
+    user.last_login_at = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def attach_wechat_to_user(
+    db: Session, user: User, *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None
+) -> User:
+    """继续绑定:把微信 openid + 微信源字段并入已存在账号(调用方保证 user.wechat_openid 为空)。
+
+    **只写 wechat_openid / wechat_nickname / wechat_avatar_url,不动展示 nickname/avatar_url**
+    (完整 §10"默认则用微信、改过则保留"规则留 M3)。撞 openid 唯一约束(O 期间被别处绑走,
+    极罕见)时由调用方捕获 IntegrityError 兜底降级为"只登入不绑"。
+    """
+    user.wechat_openid = openid
+    user.wechat_nickname = wechat_nickname
+    user.wechat_avatar_url = wechat_avatar_url
+    user.last_login_at = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def _build_wechat_user(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+) -> User:
+    """构造并 db.add 一个微信账号行(register_channel='wechat',展示昵称头像取微信,缺则默认),
+    **不 commit**。create_wechat_user 与 rebind_account 共用,保证建号逻辑单一来源。"""
+    user = User(
+        phone=phone,
+        username=_gen_unique_username(db),
+        nickname=wechat_nickname or _gen_nickname(),
+        avatar_url=wechat_avatar_url,
+        register_channel="wechat",
+        wechat_openid=openid,
+        wechat_nickname=wechat_nickname,
+        wechat_avatar_url=wechat_avatar_url,
+        last_login_at=datetime.now(timezone.utc),
+    )
+    db.add(user)
+    return user
+
+
+def create_wechat_user(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+) -> User:
+    """微信登录新建账号(未占用分支)。见 _build_wechat_user。
+
+    openid 唯一约束是并发/重复绑定的最终防线(极罕见,openid 在 wechat-login 刚查过为空)。
+    """
+    user = _build_wechat_user(
+        db, phone=phone, openid=openid,
+        wechat_nickname=wechat_nickname, wechat_avatar_url=wechat_avatar_url,
+    )
+    db.commit()
+    db.refresh(user)
+    return user
+
+
 def upsert_user_for_login(
     db: Session,
     *,
@@ -154,3 +232,44 @@ def soft_delete_account(db: Session, user: User) -> None:
     # 释放邀请码唯一槽
     user.invite_code = None
     db.commit()
+
+
+def rebind_account(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+    source: str = "wechat_conflict",
+) -> User:
+    """换绑:**单事务内**注销老账号 X(腾出手机号)+ 用该号建全新微信账号 Y + 写换绑台账。
+
+    - 老账号可能已不存在(P 被腾空)→ old_user_id=None,直接建 Y(幂等更稳)。
+    - 手机号唯一约束靠时序:先把 X.phone 改名并 flush 腾号,再插 Y。
+    - 全程不中途 commit,任一步失败整体回滚,绝不出现"X 删了 Y 没建"。
+    X 的字段变更等价 soft_delete_account(软删 + 匿名化 + 释放 openid/邀请码唯一槽),但不在此 commit。
+    """
+    old = get_user_by_phone(db, phone)
+    old_id = old.id if old is not None else None
+    if old is not None:
+        old.status = "deleted"
+        old.phone = f"deleted_{old.id}"
+        old.nickname = None
+        old.avatar_url = None
+        old.wechat_openid = None
+        old.wechat_nickname = None
+        old.wechat_avatar_url = None
+        old.invite_code = None
+        db.flush()  # 先落 phone 改名,腾出手机号唯一约束,才能给 Y 用
+    new_user = _build_wechat_user(
+        db, phone=phone, openid=openid,
+        wechat_nickname=wechat_nickname, wechat_avatar_url=wechat_avatar_url,
+    )
+    db.flush()  # 拿 new_user.id
+    phone_rebind.add_rebind_log(
+        db, phone=phone, old_user_id=old_id, new_user_id=new_user.id, source=source
+    )
+    db.commit()
+    db.refresh(new_user)
+    return new_user

app/schemas/auth.py

@@ -102,3 +102,64 @@ class RefreshRequest(BaseModel):
 
 class LogoutResponse(BaseModel):
     ok: bool = True
+
+
+# ===== 微信登录 =====
+
+class WechatLoginRequest(BaseModel):
+    code: str = Field(..., min_length=1, description="微信 App 授权拿到的 code(单次有效)")
+    device_id: str = Field(
+        "", max_length=64,
+        description="硬件级设备标识(Android ANDROID_ID),用于新手引导按 设备+账号 去重;空=按未完成处理",
+    )
+
+
+class WechatLoginResponse(BaseModel):
+    # status="logged_in" → openid 命中,token 有值;"need_bind_phone" → 未命中,bind_ticket 有值
+    status: str
+    token: TokenWithUser | None = None
+    bind_ticket: str | None = None
+    wechat_nickname: str | None = None
+    wechat_avatar_url: str | None = None
+
+
+class OccupiedAccountInfo(BaseModel):
+    """手机号被占用时返回的原账号脱敏展示信息(供冲突页)。"""
+    nickname: str | None = None
+    avatar_url: str | None = None
+    created_at: datetime
+    has_wechat: bool = False
+
+
+class WechatBindResultResponse(BaseModel):
+    # status="logged_in" → 未占用,已建号登入,token 有值;
+    # "phone_occupied" → 手机号被占用,occupied_account + conflict_ticket 有值,token 为 None
+    status: str
+    token: TokenWithUser | None = None
+    occupied_account: OccupiedAccountInfo | None = None
+    conflict_ticket: str | None = None            # 占用时签发,换绑/继续绑定只认它
+    rebind_available: bool | None = None          # 该手机号 30 天内是否还能换绑(给换绑按钮预置禁用态)
+    rebind_blocked_days: int | None = None        # 被限时剩余天数(rebind_available=False 时>0)
+
+
+class WechatBindPhoneSmsRequest(BaseModel):
+    bind_ticket: str = Field(..., min_length=1)
+    phone: str = Field(..., min_length=11, max_length=11, pattern=r"^1\d{10}$")
+    code: str = Field(..., min_length=4, max_length=8)
+    device_id: str = Field("", max_length=64)
+
+
+class WechatBindPhoneJverifyRequest(BaseModel):
+    bind_ticket: str = Field(..., min_length=1)
+    login_token: str = Field(..., min_length=1, description="客户端 loginAuth 拿到的 loginToken")
+    device_id: str = Field("", max_length=64)
+
+
+class WechatConflictContinueRequest(BaseModel):
+    conflict_ticket: str = Field(..., min_length=1)
+    device_id: str = Field("", max_length=64)
+
+
+class WechatConflictRebindRequest(BaseModel):
+    conflict_ticket: str = Field(..., min_length=1)
+    device_id: str = Field("", max_length=64)

app/schemas/device_profile.py

@@ -1,35 +0,0 @@
-"""设备档案上报 schema(device 表)。
-
-与 schemas/device.py(无障碍存活 DeviceLiveness 的 register/heartbeat)是不同用途:
-本文件对应 device 表(设备信息/档案),schemas/device.py 对应 device_liveness 表。
-"""
-from __future__ import annotations
-
-from pydantic import BaseModel, Field
-
-
-class DeviceReportRequest(BaseModel):
-    """客户端上报的一台设备的当前信息(每次以实际为准)。"""
-
-    device_id: str = Field(max_length=128)
-    platform: str = Field(default="android", max_length=16)
-
-    # 设备 / 系统信息:提供了才覆盖(见 repo:非空 sticky)
-    oem: str | None = Field(default=None, max_length=32)
-    model: str | None = Field(default=None, max_length=64)
-    os_version: str | None = Field(default=None, max_length=32)
-    app_version: str | None = Field(default=None, max_length=32)
-    channel: str | None = Field(default=None, max_length=32)
-    screen: str | None = Field(default=None, max_length=32)
-    network: str | None = Field(default=None, max_length=16)
-    timezone: str | None = Field(default=None, max_length=64)
-    is_emulator: bool | None = None
-
-    # 位置:客户端每次带「本次实际」的经纬度,拿不到就传 null(或不传)→ 服务端清空。
-    # 见 model Device.latitude 注释:这两个字段整字段覆盖,不做 sticky。
-    latitude: float | None = None
-    longitude: float | None = None
-
-
-class DeviceReportOut(BaseModel):
-    ok: bool = True

docs/database/device_liveness.md

@@ -1,6 +1,6 @@
 # device_liveness — 无障碍存活监控(心跳 + 掉线召回)
 
-> 模型 `app/models/device_liveness.py`(`DeviceLiveness`) · 仓库 `app/repositories/device.py`(`register_or_update` / `touch_heartbeat` / `list_overdue` / `mark_notified` / `get_device` / `ack_kill_alert`) · 接口 用户 `POST /api/v1/device/register`、`POST /api/v1/device/heartbeat`、`GET /api/v1/device/liveness`、`POST /api/v1/device/liveness/ack`(`app/api/v1/device.py`);后台 worker `heartbeat_monitor_worker` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/device.py`(`DeviceLiveness`) · 仓库 `app/repositories/device.py`(`register_or_update` / `touch_heartbeat` / `list_overdue` / `mark_notified` / `get_device` / `ack_kill_alert`) · 接口 用户 `POST /api/v1/device/register`、`POST /api/v1/device/heartbeat`、`GET /api/v1/device/liveness`、`POST /api/v1/device/liveness/ack`(`app/api/v1/device.py`);后台 worker `heartbeat_monitor_worker` · [← 索引](./README.md) · [总览](./OVERVIEW.md)
 
 每行 = 一个用户的一台设备(per-install,`(user_id, device_id)` 唯一)。客户端无障碍服务存活时周期上报心跳刷新 `last_heartbeat_at`;App 前台/登录拿到极光 push token 时上报 `registration_id`。后端 `heartbeat_monitor_worker` 扫「曾保护过、现已心跳超时」的设备,推送(或本期仅终端打印)提醒用户重开无障碍。**表名不叫 `device`**:它存的不是设备信息(品牌/型号),而是**无障碍存活状态**。#65 新增。
 

tests/test_device_profile.py

@@ -1,98 +0,0 @@
-"""设备档案上报端点 /api/v1/device/report + upsert 测试。"""
-from __future__ import annotations
-
-from sqlalchemy import select
-
-from app.core.security import create_token
-from app.db.session import SessionLocal
-from app.models.device import Device
-from app.models.user import User
-
-
-def _payload(**over) -> dict:
-    base = {
-        "device_id": "dev-report-1",
-        "platform": "android",
-        "oem": "Xiaomi",
-        "model": "PJF110",
-        "os_version": "Android 14",
-        "app_version": "0.2.12(62)",
-        "channel": "yingyongbao",
-        "screen": "1080x2400",
-        "network": "wifi",
-        "timezone": "Asia/Shanghai",
-        "is_emulator": False,
-        "latitude": 31.23,
-        "longitude": 121.47,
-    }
-    base.update(over)
-    return base
-
-
-def _get(device_id: str) -> Device | None:
-    with SessionLocal() as db:
-        return db.execute(
-            select(Device).where(Device.device_id == device_id)
-        ).scalar_one_or_none()
-
-
-def test_report_creates_device_as_guest(client) -> None:
-    r = client.post("/api/v1/device/report", json=_payload(device_id="dev-guest"))
-    assert r.status_code == 200, r.text
-    assert r.json()["ok"] is True
-    d = _get("dev-guest")
-    assert d is not None
-    assert d.user_id is None  # 游客态:未绑用户
-    assert d.oem == "Xiaomi"
-    assert d.is_emulator is False
-    assert d.latitude == 31.23
-    assert d.last_active_at is not None
-
-
-def test_report_binds_user_when_authed(client) -> None:
-    with SessionLocal() as db:
-        u = User(phone="13800000001", username="20000000001")
-        db.add(u)
-        db.commit()
-        uid = u.id
-    token, _ = create_token(user_id=uid, token_type="access")
-    r = client.post(
-        "/api/v1/device/report",
-        json=_payload(device_id="dev-user"),
-        headers={"Authorization": f"Bearer {token}"},
-    )
-    assert r.status_code == 200, r.text
-    assert _get("dev-user").user_id == uid
-
-
-def test_report_clears_location_when_absent(client) -> None:
-    # 首次带位置
-    client.post(
-        "/api/v1/device/report",
-        json=_payload(device_id="dev-loc", latitude=10.0, longitude=20.0),
-    )
-    assert _get("dev-loc").latitude == 10.0
-    # 再次上报拿不到位置(lat/lng=None)→ 必须清空,不能保留旧坐标
-    r = client.post(
-        "/api/v1/device/report",
-        json=_payload(device_id="dev-loc", latitude=None, longitude=None, oem="HONOR"),
-    )
-    assert r.status_code == 200, r.text
-    d = _get("dev-loc")
-    assert d.latitude is None  # 位置以实际为准 → 清空
-    assert d.longitude is None
-    assert d.oem == "HONOR"  # 设备信息正常更新
-
-
-def test_report_sticky_fields_not_wiped_by_missing(client) -> None:
-    # 首次全量
-    client.post("/api/v1/device/report", json=_payload(device_id="dev-sticky"))
-    # 再次只带 device_id + 位置(不带 oem/model)→ 设备信息保留旧值(非空才覆盖)
-    client.post(
-        "/api/v1/device/report",
-        json={"device_id": "dev-sticky", "latitude": 1.0, "longitude": 2.0},
-    )
-    d = _get("dev-sticky")
-    assert d.oem == "Xiaomi"  # 未被漏带的 None 冲掉
-    assert d.model == "PJF110"
-    assert d.latitude == 1.0  # 位置按本次

tests/test_wechat_conflict.py

@@ -0,0 +1,211 @@
+"""微信登录 M2 测试:conflict_ticket 令牌、继续绑定(attach/只登入)、换绑(建号+软删+30天限)。
+
+沿用 tests/test_wechat_login.py 风格:HTTP 走 client;微信 code→openid 用 monkeypatch;
+短信走 SMS_MOCK(任意 6 位过)。数据变更用"再走一遍 wechat-login 看 openid 落在哪个账号"做行为断言。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.api.v1 import auth  # noqa: F401  (后续测试打桩 verify_and_get_phone 用)
+from app.core import security
+from app.integrations import wxpay
+from app.models.phone_rebind_log import PhoneRebindLog
+
+
+def _fake_userinfo(openid: str, nickname: str | None = "微信昵称", avatar: str | None = "http://x/a.png"):
+    def _f(code: str) -> dict:
+        return {"openid": openid, "nickname": nickname, "avatar_url": avatar, "raw": {}}
+    return _f
+
+
+def _sms_occupy(client, phone: str) -> int:
+    """用普通短信登录占用一个手机号(register_channel=sms),返回该账号 id。"""
+    assert client.post("/api/v1/auth/sms/send", json={"phone": phone}).status_code == 200
+    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    assert r.status_code == 200, r.text
+    return r.json()["user"]["id"]
+
+
+def _occupy_via_conflict(client, monkeypatch, openid: str, phone: str, device_id: str) -> dict:
+    """微信登录(新 openid)→ 绑同一手机号 → 返回 phone_occupied 的响应体(含 conflict_ticket)。"""
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo(openid))
+    ticket = client.post(
+        "/api/v1/auth/wechat-login", json={"code": "c", "device_id": device_id}
+    ).json()["bind_ticket"]
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/sms",
+        json={"bind_ticket": ticket, "phone": phone, "code": "123456", "device_id": device_id},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "phone_occupied"
+    return body
+
+
+# ===== Task 1: 模型可导入(建表由 conftest 的 create_all 完成) =====
+
+def test_phone_rebind_log_model_importable() -> None:
+    assert PhoneRebindLog.__tablename__ == "phone_rebind_log"
+
+
+# ===== Task 2: conflict_ticket 令牌 =====
+
+def test_conflict_ticket_roundtrip() -> None:
+    token = security.create_conflict_ticket(
+        openid="oid1", wechat_nickname="昵", wechat_avatar_url="http://a", phone="13900139000"
+    )
+    claims = security.decode_conflict_ticket(token)
+    assert claims["openid"] == "oid1"
+    assert claims["wnk"] == "昵"
+    assert claims["wav"] == "http://a"
+    assert claims["phone"] == "13900139000"
+
+
+def test_conflict_ticket_wrong_type_rejected() -> None:
+    # bind_ticket 冒充 conflict_ticket → TokenError(typ 不匹配)
+    bind = security.create_bind_ticket(openid="oid", wechat_nickname=None, wechat_avatar_url=None)
+    with pytest.raises(security.TokenError):
+        security.decode_conflict_ticket(bind)
+
+
+def test_conflict_ticket_expired_rejected(monkeypatch) -> None:
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    token = security.create_conflict_ticket(
+        openid="oid", wechat_nickname=None, wechat_avatar_url=None, phone="13900139000"
+    )
+    with pytest.raises(security.TokenError):
+        security.decode_conflict_ticket(token)
+
+
+# ===== Task 3: 占用响应扩展 =====
+
+def test_phone_occupied_returns_conflict_ticket_and_flags(client, monkeypatch) -> None:
+    phone = "13900139101"
+    _sms_occupy(client, phone)  # 老账号 X(sms,无微信)
+    body = _occupy_via_conflict(client, monkeypatch, "openid_occ_101", phone, "devO1")
+    assert body["conflict_ticket"]
+    assert body["rebind_available"] is True      # 首次,未换绑过
+    assert body["rebind_blocked_days"] == 0
+    assert body["occupied_account"]["has_wechat"] is False  # X 是 sms 账号
+
+
+# ===== Task 4: 继续绑定 =====
+
+def test_continue_attaches_wechat_and_logs_into_existing(client, monkeypatch) -> None:
+    """X 无微信 → 继续绑定并入 openid + 登入 X;之后同 openid 登录直接命中 X。"""
+    phone = "13900139201"
+    x_id = _sms_occupy(client, phone)  # X:sms 账号,无微信
+    body = _occupy_via_conflict(client, monkeypatch, "openid_cont_201", phone, "devC1")
+
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/continue",
+        json={"conflict_ticket": body["conflict_ticket"], "device_id": "devC1"},
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["status"] == "logged_in"
+    assert r.json()["token"]["user"]["id"] == x_id  # 登入的是老账号 X
+
+    # openid 现已并入 X:再走 wechat-login 直接命中 X
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devC1"})
+    assert r.json()["status"] == "logged_in"
+    assert r.json()["token"]["user"]["id"] == x_id
+
+
+def test_continue_when_existing_has_wechat_logs_in_and_discards_openid(client, monkeypatch) -> None:
+    """X 已绑别的微信 → 继续绑定只登入 X、丢弃本次 openid(不覆盖)。"""
+    phone = "13900139202"
+    # 先建一个已绑微信 O1 的账号 X(微信登录 O1 + 短信绑号)
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_o1_202"))
+    t = client.post("/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devC2"}).json()["bind_ticket"]
+    x = client.post(
+        "/api/v1/auth/wechat/bind-phone/sms",
+        json={"bind_ticket": t, "phone": phone, "code": "123456", "device_id": "devC2"},
+    ).json()
+    x_id = x["token"]["user"]["id"]
+
+    # 新 openid O2 撞同号 → 占用(has_wechat=True)→ 继续绑定
+    body = _occupy_via_conflict(client, monkeypatch, "openid_o2_202", phone, "devC2b")
+    assert body["occupied_account"]["has_wechat"] is True
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/continue",
+        json={"conflict_ticket": body["conflict_ticket"], "device_id": "devC2b"},
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["token"]["user"]["id"] == x_id  # 登入 X
+
+    # O2 被丢弃:再走 wechat-login(O2)→ 仍未命中(need_bind_phone)
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_o2_202"))
+    assert client.post(
+        "/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devC2b"}
+    ).json()["status"] == "need_bind_phone"
+
+
+def test_continue_expired_ticket_returns_401(client, monkeypatch) -> None:
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    expired = security.create_conflict_ticket(
+        openid="oid", wechat_nickname=None, wechat_avatar_url=None, phone="13900139209"
+    )
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/continue",
+        json={"conflict_ticket": expired, "device_id": "devC3"},
+    )
+    assert r.status_code == 401, r.text
+
+
+# ===== Task 5: 换绑 =====
+
+def test_rebind_creates_new_account_and_binds_openid(client, monkeypatch) -> None:
+    """换绑 → 建全新微信账号 Y(≠X)+ openid 落到 Y;老账号 X 被注销(手机号归 Y)。"""
+    phone = "13900139301"
+    x_id = _sms_occupy(client, phone)
+    body = _occupy_via_conflict(client, monkeypatch, "openid_rb_301", phone, "devR1")
+
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/rebind",
+        json={"conflict_ticket": body["conflict_ticket"], "device_id": "devR1"},
+    )
+    assert r.status_code == 200, r.text
+    y = r.json()["token"]["user"]
+    assert r.json()["status"] == "logged_in"
+    assert y["phone"] == phone
+    assert y["register_channel"] == "wechat"
+    assert y["id"] != x_id  # 是全新账号,不是老账号
+
+    # openid 落到 Y:再走 wechat-login 命中 Y
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devR1"})
+    assert r.json()["status"] == "logged_in"
+    assert r.json()["token"]["user"]["id"] == y["id"]
+
+
+def test_rebind_blocked_within_30_days(client, monkeypatch) -> None:
+    """同一手机号 30 天内二次换绑 → 409;占用响应 rebind_available=False。"""
+    phone = "13900139302"
+    _sms_occupy(client, phone)
+    body = _occupy_via_conflict(client, monkeypatch, "openid_rb_302a", phone, "devR2")
+    assert client.post(
+        "/api/v1/auth/wechat/conflict/rebind",
+        json={"conflict_ticket": body["conflict_ticket"], "device_id": "devR2"},
+    ).status_code == 200
+
+    # 第二次:新 openid 撞同号 → 占用响应此时 rebind_available=False
+    body2 = _occupy_via_conflict(client, monkeypatch, "openid_rb_302b", phone, "devR2b")
+    assert body2["rebind_available"] is False
+    assert body2["rebind_blocked_days"] >= 1
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/rebind",
+        json={"conflict_ticket": body2["conflict_ticket"], "device_id": "devR2b"},
+    )
+    assert r.status_code == 409, r.text
+
+
+def test_rebind_expired_ticket_returns_401(client, monkeypatch) -> None:
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    expired = security.create_conflict_ticket(
+        openid="oid", wechat_nickname=None, wechat_avatar_url=None, phone="13900139309"
+    )
+    r = client.post(
+        "/api/v1/auth/wechat/conflict/rebind",
+        json={"conflict_ticket": expired, "device_id": "devR3"},
+    )
+    assert r.status_code == 401, r.text

tests/test_wechat_login.py

@@ -0,0 +1,198 @@
+"""微信登录 M1 测试:bind_ticket 令牌、wechat-login(openid 命中/未命中)、
+bind-phone(建号/占用/令牌过期)。
+
+沿用 tests/test_auth.py 风格:HTTP 走 client fixture;微信 code→openid 用 monkeypatch
+拦掉(conftest 里 WECHAT_APP_ID/SECRET 是 dummy,不真连微信);短信走 SMS_MOCK(任意 6 位通过)。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.api.v1 import auth
+from app.core import security
+from app.integrations import wxpay
+
+
+def _fake_userinfo(openid: str, nickname: str | None = "微信昵称", avatar: str | None = "http://x/a.png"):
+    """返回一个可传给 monkeypatch 的假 code_to_userinfo(忽略 code,固定返回给定 openid)。"""
+    def _f(code: str) -> dict:
+        return {"openid": openid, "nickname": nickname, "avatar_url": avatar, "raw": {}}
+    return _f
+
+
+# ===== Task 1: bind_ticket 令牌 =====
+
+def test_bind_ticket_roundtrip() -> None:
+    token = security.create_bind_ticket(openid="oid1", wechat_nickname="昵", wechat_avatar_url="http://a")
+    claims = security.decode_bind_ticket(token)
+    assert claims["openid"] == "oid1"
+    assert claims["wnk"] == "昵"
+    assert claims["wav"] == "http://a"
+
+
+def test_bind_ticket_wrong_type_rejected() -> None:
+    # 用 access token 冒充 bind_ticket → TokenError(typ 不匹配)
+    access, _ = security.create_token(user_id=1, token_type="access")
+    with pytest.raises(security.TokenError):
+        security.decode_bind_ticket(access)
+
+
+def test_bind_ticket_expired_rejected(monkeypatch) -> None:
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    token = security.create_bind_ticket(openid="oid", wechat_nickname=None, wechat_avatar_url=None)
+    with pytest.raises(security.TokenError):
+        security.decode_bind_ticket(token)
+
+
+# ===== Task 2: wechat-login =====
+
+def test_wechat_login_new_openid_returns_bind_ticket(client, monkeypatch) -> None:
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_new_1", "小明", "http://x/m.png"))
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "wxcode1", "device_id": "devA"})
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "need_bind_phone"
+    assert body["bind_ticket"]
+    assert body["wechat_nickname"] == "小明"
+    assert body["wechat_avatar_url"] == "http://x/m.png"
+    assert body["token"] is None
+
+
+def test_wechat_login_invalid_code_returns_400(client, monkeypatch) -> None:
+    def _raise(code: str) -> dict:
+        raise ValueError("微信授权失败: invalid code")
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _raise)
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "bad", "device_id": "devA"})
+    assert r.status_code == 400, r.text
+
+
+# ===== Task 3: bind-phone/sms =====
+
+def test_wechat_bind_sms_creates_account_then_openid_logs_in(client, monkeypatch) -> None:
+    """未占用 → 建微信账号(channel=wechat,昵称头像取微信);再次同 openid 登录 → 直接登入同一账号。"""
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_flow_2", "阿花", "http://x/h.png"))
+    phone = "13900139002"
+
+    # 1) 微信登录 → 未命中 → 拿 ticket
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "c1", "device_id": "devB"})
+    ticket = r.json()["bind_ticket"]
+    assert ticket
+
+    # 2) 短信绑号(SMS_MOCK:任意 6 位通过)→ 建号 + 登入
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/sms",
+        json={"bind_ticket": ticket, "phone": phone, "code": "123456", "device_id": "devB"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "logged_in"
+    user = body["token"]["user"]
+    assert user["phone"] == phone
+    assert user["register_channel"] == "wechat"
+    assert user["nickname"] == "阿花"
+    assert user["avatar_url"] == "http://x/h.png"
+    uid = user["id"]
+
+    # 3) 再次微信登录(同 openid)→ 命中 → 直接登入同一账号
+    r = client.post("/api/v1/auth/wechat-login", json={"code": "c2", "device_id": "devB"})
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "logged_in"
+    assert body["token"]["user"]["id"] == uid
+
+
+def test_wechat_bind_sms_phone_occupied(client, monkeypatch) -> None:
+    """手机号已被其他账号占用 → 返回 phone_occupied + 原账号信息(不建号)。"""
+    phone = "13900139003"
+    # 先用普通短信登录占用该手机号(register_channel=sms)
+    assert client.post("/api/v1/auth/sms/send", json={"phone": phone}).status_code == 200
+    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    assert r.status_code == 200, r.text
+    occupied_nickname = r.json()["user"]["nickname"]
+
+    # 微信登录(新 openid)→ 未命中 → ticket
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_occ_3"))
+    ticket = client.post(
+        "/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devC"}
+    ).json()["bind_ticket"]
+
+    # 绑同一手机号 → 占用
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/sms",
+        json={"bind_ticket": ticket, "phone": phone, "code": "123456", "device_id": "devC"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "phone_occupied"
+    assert body["token"] is None
+    assert body["occupied_account"]["nickname"] == occupied_nickname
+    assert body["occupied_account"]["avatar_url"] is None  # 短信注册账号无头像 → 序列化为 null
+    assert body["occupied_account"]["created_at"]
+
+
+def test_wechat_bind_sms_expired_ticket_returns_401(client, monkeypatch) -> None:
+    """过期 bind_ticket → 401。"""
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    expired = security.create_bind_ticket(openid="openid_exp", wechat_nickname="x", wechat_avatar_url=None)
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/sms",
+        json={"bind_ticket": expired, "phone": "13900139009", "code": "123456", "device_id": "devD"},
+    )
+    assert r.status_code == 401, r.text
+
+
+# ===== Task 4: bind-phone/jverify =====
+
+def test_wechat_bind_jverify_creates_account(client, monkeypatch) -> None:
+    """本机号(极光)绑定路径:verify_and_get_phone 拦掉,未占用 → 建号登入。"""
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_jv_5", "极光用户", None))
+    phone = "13900139005"
+    # 极光 loginToken→手机号 在 auth 模块命名空间打桩(auth.py 顶部 from ...jiguang import verify_and_get_phone)
+    monkeypatch.setattr(auth, "verify_and_get_phone", lambda token: phone)
+
+    ticket = client.post(
+        "/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devE"}
+    ).json()["bind_ticket"]
+
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/jverify",
+        json={"bind_ticket": ticket, "login_token": "jgtoken", "device_id": "devE"},
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["status"] == "logged_in"
+    user = body["token"]["user"]
+    assert user["phone"] == phone
+    assert user["register_channel"] == "wechat"
+    assert user["nickname"] == "极光用户"
+    # 微信 userinfo 隐私脱敏 avatar=None → 头像为空(客户端兜底默认头像)
+    assert user["avatar_url"] is None
+
+
+def test_wechat_bind_jverify_expired_ticket_returns_401(client, monkeypatch) -> None:
+    """过期 bind_ticket → 401(极光绑号路径,decode 先于极光核验)。"""
+    monkeypatch.setattr(security.settings, "WECHAT_BIND_TICKET_EXPIRE_MINUTES", -1)
+    expired = security.create_bind_ticket(openid="openid_jv_exp", wechat_nickname="x", wechat_avatar_url=None)
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/jverify",
+        json={"bind_ticket": expired, "login_token": "jgtoken", "device_id": "devE"},
+    )
+    assert r.status_code == 401, r.text
+
+
+def test_wechat_bind_jverify_jiguang_error_returns_502(client, monkeypatch) -> None:
+    """极光核验失败(JiguangError)→ 502。"""
+    monkeypatch.setattr(wxpay, "code_to_userinfo", _fake_userinfo("openid_jv_err"))
+
+    def _raise(token: str) -> str:
+        raise auth.JiguangError("mock jg failure")
+
+    monkeypatch.setattr(auth, "verify_and_get_phone", _raise)
+    ticket = client.post(
+        "/api/v1/auth/wechat-login", json={"code": "c", "device_id": "devE"}
+    ).json()["bind_ticket"]
+    r = client.post(
+        "/api/v1/auth/wechat/bind-phone/jverify",
+        json={"bind_ticket": ticket, "login_token": "badtoken", "device_id": "devE"},
+    )
+    assert r.status_code == 502, r.text