feat(onboarding): 新手引导完成按 设备+账号 去重(表/模型/仓储/端点/迁移/测试)

- onboarding_completion 表(user_id+device_id 唯一约束)+ model + repository
- POST /api/v1/user/onboarding/complete 标记完成;登录响应 TokenWithUser.onboarding_completed
  (按登录请求带的 device_id 判定是否已走过引导,跨卸载重装稳定)
- alembic 迁移 onboarding_completion(rebase 到最新 main 后已链在 coupon_daily_completion 之后,单 head)
- docs/database 文档 + tests/test_onboarding.py + run.bat(本地启动脚本)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

app/api/v1/auth.py

@@ -19,6 +19,7 @@ from app.core.ratelimit import rate_limit
 from app.core.security import TokenError, decode_token, issue_token_pair
 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 user as user_repo
 from app.schemas.auth import (
     JverifyLoginRequest,
@@ -37,12 +38,13 @@ logger = logging.getLogger("shagua.auth")
 router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 
 
-def _login_response(db, user) -> TokenWithUser:
-    """登录类接口共用的响应组装。"""
+def _login_response(user, *, onboarding_completed: bool) -> TokenWithUser:
+    """登录类接口共用的响应组装。onboarding_completed 据登录请求的 device_id 算好后传入。"""
     tokens = issue_token_pair(user.id)
     return TokenWithUser(
         **tokens,
         user=UserOut.model_validate(user),
+        onboarding_completed=onboarding_completed,
     )
 
 
@@ -66,8 +68,9 @@ def jverify_login(req: JverifyLoginRequest, db: DbSession) -> TokenWithUser:
     if user.status != "active":
         raise HTTPException(status_code=403, detail="account disabled")
 
-    logger.info("jverify_login ok user_id=%d phone=%s", user.id, mask_phone(phone))
-    return _login_response(db, user)
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("jverify_login ok user_id=%d phone=%s onboarded=%s", user.id, mask_phone(phone), completed)
+    return _login_response(user, onboarding_completed=completed)
 
 
 # ===================== 短信登录 =====================
@@ -103,8 +106,9 @@ def sms_login(req: SmsLoginRequest, db: DbSession) -> TokenWithUser:
     if user.status != "active":
         raise HTTPException(status_code=403, detail="account disabled")
 
-    logger.info("sms_login ok user_id=%d phone=%s", user.id, mask_phone(req.phone))
-    return _login_response(db, user)
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("sms_login ok user_id=%d phone=%s onboarded=%s", user.id, mask_phone(req.phone), completed)
+    return _login_response(user, onboarding_completed=completed)
 
 
 # ===================== Refresh =====================

app/api/v1/user.py

@@ -16,9 +16,10 @@ from fastapi import APIRouter, File, HTTPException, UploadFile
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import media
+from app.repositories import onboarding as onboarding_repo
 from app.repositories import user as user_repo
 from app.schemas.auth import UserOut
-from app.schemas.user import OkResponse, ProfileUpdateRequest
+from app.schemas.user import OkResponse, OnboardingCompleteRequest, ProfileUpdateRequest
 
 logger = logging.getLogger("shagua.user")
 
@@ -51,6 +52,17 @@ async def upload_avatar(
     return UserOut.model_validate(updated)
 
 
+@router.post("/onboarding/complete", response_model=OkResponse, summary="标记新手引导完成(按 设备+账号)")
+def complete_onboarding(
+    req: OnboardingCompleteRequest, user: CurrentUser, db: DbSession
+) -> OkResponse:
+    """走完新手引导时调一次。按 (当前账号, device_id) 落一条完成标记,跨卸载重装持久。
+    幂等:重复调用不报错。device_id 取客户端硬件级 ANDROID_ID,与登录请求一致。"""
+    onboarding_repo.mark_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("onboarding complete user_id=%d device_len=%d", user.id, len(req.device_id))
+    return OkResponse()
+
+
 @router.delete("", response_model=OkResponse, summary="注销账号(软删除)")
 def delete_account(user: CurrentUser, db: DbSession) -> OkResponse:
     media.delete_avatar(user.avatar_url)

app/models/__init__.py

@@ -16,6 +16,7 @@ from app.models.feedback import Feedback  # noqa: F401
 from app.models.invite import InviteRelation  # noqa: F401
 from app.models.invite_fingerprint import InviteFingerprint  # noqa: F401
 from app.models.meituan_coupon import MeituanCoupon  # noqa: F401
+from app.models.onboarding import OnboardingCompletion  # 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/onboarding.py

@@ -0,0 +1,40 @@
+"""新手引导完成标记(按 设备 + 账号 去重)。
+
+产品规则:同一台设备 + 同一个账号,新手引导只跑一次;卸载重装(同设备同账号)
+不再触发。本地标记(SharedPreferences)卸载即丢,所以"完成"必须落后端,按
+(user_id, device_id) 唯一一条。
+
+⚠️ device_id 这里用客户端的**硬件级稳定标识**(Android `Settings.Secure.ANDROID_ID`),
+同签名 app 卸载重装不变、仅恢复出厂才重置——区别于领券/比价用的 per-install device_id
+(见 coupon_state,存 SP、重装会变)。换新设备 → 无此行 → 重新走引导。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class OnboardingCompletion(Base):
+    """一台设备 + 一个账号 一条:走完新手引导即写入,登录时据此跳过引导。"""
+
+    __tablename__ = "onboarding_completion"
+    __table_args__ = (
+        # 同账号、同设备只一条:重复 mark / 并发提交靠它幂等。
+        UniqueConstraint("user_id", "device_id", name="uq_onboarding_user_device"),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 登录态用户。引导是登录后才走的,故必填(非空)、进唯一键。
+    user_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
+    # 硬件级稳定设备标识(ANDROID_ID),卸载重装不变。
+    device_id: Mapped[str] = mapped_column(String(64), nullable=False)
+    completed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<OnboardingCompletion user={self.user_id} device={self.device_id}>"

app/repositories/onboarding.py

@@ -0,0 +1,35 @@
+"""新手引导完成标记的读写(按 user_id + device_id 去重)。
+
+登录时 [is_completed] 判断该 (账号, 设备) 是否走过引导;走完引导时 [mark_completed] 写一条。
+device_id 为空(老客户端 / 取不到 ANDROID_ID)一律按"未完成"处理,即照常走引导,不误跳过。
+"""
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Session
+
+from app.models.onboarding import OnboardingCompletion
+
+
+def is_completed(db: Session, *, user_id: int, device_id: str) -> bool:
+    """该 (账号, 设备) 是否已完成新手引导。device_id 为空 → 一律 False。"""
+    if not device_id:
+        return False
+    stmt = select(OnboardingCompletion.id).where(
+        OnboardingCompletion.user_id == user_id,
+        OnboardingCompletion.device_id == device_id,
+    )
+    return db.execute(stmt).first() is not None
+
+
+def mark_completed(db: Session, *, user_id: int, device_id: str) -> None:
+    """走完引导时写入。device_id 为空忽略;同 (账号, 设备) 已存在则幂等(靠唯一约束兜并发)。"""
+    if not device_id:
+        return
+    db.add(OnboardingCompletion(user_id=user_id, device_id=device_id))
+    try:
+        db.commit()
+    except IntegrityError:
+        # 并发 / 重复提交撞唯一约束:已有行即视为成功。
+        db.rollback()

app/schemas/auth.py

@@ -41,6 +41,11 @@ class TokenPair(BaseModel):
 
 class TokenWithUser(TokenPair):
     user: UserOut
+    onboarding_completed: bool = Field(
+        False,
+        description="该 设备+账号 是否已走完新手引导(据登录请求里的 device_id 计算)。"
+        "true → 客户端登录后直接进首页,跳过引导。",
+    )
 
 
 # ===== 极光一键登录 =====
@@ -48,6 +53,10 @@ class TokenWithUser(TokenPair):
 class JverifyLoginRequest(BaseModel):
     login_token: str = Field(..., description="客户端 loginAuth 拿到的 loginToken", min_length=1)
     operator: str = Field("", description="CM/CU/CT,用于日志,可选")
+    device_id: str = Field(
+        "", max_length=64,
+        description="硬件级设备标识(Android ANDROID_ID),用于新手引导按 设备+账号 去重;空=按未完成处理",
+    )
 
 
 # ===== 短信验证码 =====
@@ -65,6 +74,10 @@ class SmsSendResponse(BaseModel):
 class SmsLoginRequest(BaseModel):
     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,
+        description="硬件级设备标识(Android ANDROID_ID),用于新手引导按 设备+账号 去重;空=按未完成处理",
+    )
 
 
 # ===== Refresh =====

app/schemas/user.py

@@ -16,5 +16,12 @@ class ProfileUpdateRequest(BaseModel):
         return v
 
 
+class OnboardingCompleteRequest(BaseModel):
+    device_id: str = Field(
+        ..., min_length=1, max_length=64,
+        description="硬件级设备标识(Android ANDROID_ID),与登录时一致,用于按 设备+账号 标记引导完成",
+    )
+
+
 class OkResponse(BaseModel):
     ok: bool = True