wip(coupon): 领券状态相关 server 改动 (本地快照, 非本次会话产出)

app/api/v1/coupon.py + repositories/coupon_state + schemas/coupon_state 进行中改动,
未经我 review, 配合 launch_confirm / 领券链路。

app/api/v1/coupon.py

@@ -18,7 +18,7 @@ import httpx
 from fastapi import APIRouter, HTTPException, Request, status
 from fastapi.concurrency import run_in_threadpool
 
-from app.api.deps import DbSession
+from app.api.deps import CurrentUser, DbSession
 from app.core.config import settings
 from app.core.pricebot_router import pick_pricebot
 from app.db.session import SessionLocal
@@ -28,6 +28,7 @@ from app.schemas.coupon_state import (
     CouponPromptDismissIn,
     CouponPromptShouldShowOut,
     CouponPromptShownIn,
+    CouponStatsOut,
 )
 
 logger = logging.getLogger("shagua.coupon")
@@ -268,3 +269,15 @@ def coupon_completed_today_reset(
     与 /prompt/reset 配套:开发设置「重置今日领券弹窗状态」一键把今日状态全清。MVP 不鉴权。"""
     coupon_repo.reset_today_completion(db, payload.device_id)
     return {"ok": True}
+
+
+@router.get(
+    "/stats",
+    response_model=CouponStatsOut,
+    summary="累计领券数(「我的」页战绩卡「领取优惠券 X 张」)",
+)
+def coupon_stats(user: CurrentUser, db: DbSession) -> CouponStatsOut:
+    """该登录用户累计领到的券数(SUM(claimed_count),口径见 coupon_repo.sum_claimed_count)。
+    **鉴权(CurrentUser)**——区别于同文件不鉴权的 /step 透传与 /prompt 频控(那些按 device_id):
+    个人战绩按 user_id 聚合,必须有登录态。"""
+    return CouponStatsOut(coupon_count=coupon_repo.sum_claimed_count(db, user.id))