合并 main 并解决 API 文档冲突

app/api/v1/ad.py

@@ -286,6 +286,7 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
         ad_session_id=payload.ad_session_id,
         adn=payload.adn, slot_id=payload.slot_id,
         feed_scene=payload.feed_scene,
+        trace_id=payload.trace_id,
         app_env=payload.app_env, our_code_id=payload.our_code_id,
     )
     logger.info(

app/api/v1/analytics.py

@@ -6,13 +6,18 @@ POST /api/v1/analytics/events — 批量接收新手引导(及后续)埋点,appe
 """
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
 
 from app.api.deps import DbSession
 from app.repositories import analytics as analytics_repo
+from app.repositories import analytics_selfstat as selfstat_repo
 from app.schemas.analytics import AnalyticsBatchIn, AnalyticsIngestOut
+from app.schemas.analytics_selfstat import SelfStatBatchIn, SelfStatIngestOut
 
 router = APIRouter(prefix="/api/v1/analytics", tags=["analytics"])
+logger = logging.getLogger("shagua.analytics")
 
 
 def _client_ip(request: Request) -> str:
@@ -29,3 +34,13 @@ def ingest_events(
 ) -> AnalyticsIngestOut:
     n = analytics_repo.record_batch(db, batch, client_ip=_client_ip(request))
     return AnalyticsIngestOut(received=n)
+
+
+@router.post("/selfstat", response_model=SelfStatIngestOut, summary="上报自报计数快照")
+def ingest_selfstat(batch: SelfStatBatchIn, db: DbSession) -> SelfStatIngestOut:
+    try:
+        snap_id = selfstat_repo.record_selfstat(db, batch)
+    except Exception:  # noqa: BLE001 — 计数链路要稳,落库失败不裸奔 500,记日志回明确错误
+        logger.exception("selfstat ingest failed device=%s epoch=%s", batch.device_id, batch.epoch_id)
+        raise HTTPException(status_code=503, detail="selfstat ingest failed") from None
+    return SelfStatIngestOut(snapshot_id=snap_id)

app/api/v1/auth.py

@@ -12,19 +12,36 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, HTTPException, Request
+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, rate_limit
-from app.core.security import TokenError, decode_token, issue_token_pair
+from app.core.ratelimit import (
+    RateLimitRule,
+    check_rate_limits,
+    enforce_rate_limit,
+    record_rate_limits,
+)
+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 +49,13 @@ from app.schemas.auth import (
     TokenPair,
     TokenWithUser,
     UserOut,
+    WechatBindPhoneJverifyRequest,
+    WechatBindPhoneSmsRequest,
+    WechatBindResultResponse,
+    WechatConflictContinueRequest,
+    WechatConflictRebindRequest,
+    WechatLoginRequest,
+    WechatLoginResponse,
 )
 
 logger = logging.getLogger("shagua.auth")
@@ -40,9 +64,10 @@ router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 
 # 手机号登录防刷:同一设备(device_id) + 同一 IP 每小时最多的登录尝试次数(成功/失败都计)。
 SMS_LOGIN_MAX_PER_HOUR = 5
-# 发码防刷:同一设备(device_id) + 同一 IP 每小时最多的发码次数。
-# 堵「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞 —— 那两道是单号维度,一机换号能绕开。
-SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5
+# 发码防刷(同一设备 device_id + 同一 IP,**只按成功发码计数**;被单号 60s 冷却挡下的重发不占额度):
+# 堵「换手机号绕开单号 60s 冷却」的洞 —— 冷却是单号维度,一机换号能绕开。
+SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5     # 每小时上限
+SMS_SEND_MAX_PER_DAY_PER_DEVICE = 20     # 每天上限(再叠一层日封顶,挡低频长时间轰炸)
 
 
 def _login_response(
@@ -99,23 +124,26 @@ def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
         logger.info("test_account sms_send short-circuit (不真发)")
         return SmsSendResponse(sent=True, mock=True, cooldown_sec=0)
 
-    # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_SEND_MAX_PER_HOUR_PER_DEVICE 次发码。
-    # 补「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞(那两道是单号维度,一机换号能绕);设备维度按机器封顶,
-    # 挡短信轰炸/烧钱。放在真发(send_code)之前 → 超限直接拦下、不真发短信。与路由上 IP 维度(10次/分钟)互补。
-    enforce_rate_limit(
-        request,
-        scope="sms-send-device",
-        subject=req.device_id,
-        limit=SMS_SEND_MAX_PER_HOUR_PER_DEVICE,
-        window_sec=3600,
-        detail="操作过于频繁,请稍后再试",
-    )
+    # 发码防刷:同一设备(device_id) + 同一 IP,每小时 / 每天两道闸,**均只按成功发码计数**。
+    # 补「换手机号绕开单号 60s 冷却」的洞(冷却是单号维度,一机换号能绕);设备维度按机器封顶,挡短信轰炸/烧钱。
+    # 关键:被单号 60s 冷却挡下的重发是「没真发、没烧钱」→ 不该占额度。故 check(先判)放在真发之前
+    # (超限直接 429、不真发),record(计数)只在 send_code 成功后调 —— 冷却/供应商失败抛 429 时直接返回、不计数。
+    send_rules = [
+        RateLimitRule("sms-send-device", SMS_SEND_MAX_PER_HOUR_PER_DEVICE, 3600,
+                      "操作过于频繁,请稍后再试"),
+        RateLimitRule("sms-send-device-daily", SMS_SEND_MAX_PER_DAY_PER_DEVICE, 86400,
+                      "今日验证码发送次数过多,请明天再试"),
+    ]
+    check_rate_limits(request, subject=req.device_id, rules=send_rules)
 
     try:
         cooldown = send_code(req.phone)
     except SmsError as e:
         raise HTTPException(status_code=e.status_code, detail=str(e)) from e
 
+    # 发码成功 → 两道闸各 +1(被单号冷却挡下的重发走不到这里,故不占额度)
+    record_rate_limits(request, subject=req.device_id, rules=send_rules)
+
     from app.core.config import settings  # 局部 import 避免循环
 
     return SmsSendResponse(sent=True, mock=settings.SMS_MOCK, cooldown_sec=cooldown)
@@ -125,7 +153,6 @@ def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
     "/sms/login",
     response_model=TokenWithUser,
     summary="手机号+验证码登录",
-    dependencies=[Depends(rate_limit(20, 60, "sms-login"))],  # 防撞库爆破(另有单码失败次数上限)
 )
 def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWithUser:
     # 测试账号:免验证码登录 + 每日上限 + 每次都走新手引导(详见 app/core/test_account.py)。
@@ -143,7 +170,7 @@ def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWit
         return _login_response(user, onboarding_completed=False, force_onboarding=True)
 
     # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_LOGIN_MAX_PER_HOUR 次登录尝试。放在验证码校验
-    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破。与路由上 IP 维度的 sms-login 限流(同 IP)互补。
+    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破(另有单码失败 SMS_MAX_VERIFY_ATTEMPTS 次即作废兜底)。
     # ⚠️ 按设备而非手机号 → 一台机器换不同手机号刷登录也受限(防一机狂登多号);device_id 空(老客户端)时
     #    退化为该 IP 下所有空设备聚一桶,仍受限。
     enforce_rate_limit(
@@ -167,6 +194,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/compare.py

@@ -1,49 +1,114 @@
-"""外卖比价业务透传端点。
+"""外卖比价业务透传端点 + 后端 harvest 落库。
 
-把客户端的 POST /api/v1/intent/recognize 和 /api/v1/price/step 请求原样转发给
-pricebot-backend 的 /api/intent/recognize 和 /api/price/step。MVP 阶段**不鉴权**
-(同 coupon/step,见 docs/待办与技术债.md P1:device_id 透传区分设备,待补 JWT +
-device_id↔user_id 绑定后才能做用户级画像)。
+把客户端 POST /api/v1/intent/* 和 /api/v1/price/step 转发给 pricebot,同时**由 app-server
+在透传里直接落库比价记录**(不再靠客户端 POST /compare/record):
+  - 帧0(客户端首帧不带 trace_id)→ app-server 用 uuid 签发 trace_id、注入转发 body、回给
+    客户端;并按 trace_id 建 running 行(harvest_running)。
+  - 最终 done 帧 → 更新成 success/failed + 结果(harvest_done)。发奖不在这里:#113 已把
+    邀请奖口径从「比价」移到「实际下单」(order.py)。
+  - /trace/finalize(用户终止/Phase1 未识别,无 done)→ 更新成 cancelled/failed
+    (harvest_abort,**不降级 success**)。
+trace_url 从 pricebot 响应**顶层 trace_url** 取(pricebot 每帧都带,见其 goal_engine.process_step)。
 
-- Phase 1 /intent/recognize:从源平台(淘宝闪购/美团/京东外卖)购物车页识别店名+菜品+
-  价格,一次性。
-- Phase 2 /price/step:多轮循环,在目标平台复现订单读到手价,直到 done。
+鉴权:软鉴权(OptionalUser)——新客户端带 JWT → 绑 user_id;老客户端不带 → user_id 暂空,
+由其后续 /compare/record 上报补(灰度期两条写路径按 trace_id reconcile,success 不被降级)。
 
-真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口只是透传壳。
-电商(ecom)那两个端点 food MVP 暂不需要,以后放开 scene 时再加 /ecom/intent/recognize
-和 /ecom/step 两行即可。
-
-pricebot 协议文档:
-  pricebot-backend/docs/main/02_api_protocol.md
+真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口是透传壳 + 落库。
+pricebot 协议文档: pricebot-backend/docs/main/02_api_protocol.md
 """
 from __future__ import annotations
 
 import json
 import logging
+import time
+import uuid
 from typing import Any
 
 import httpx
 from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.concurrency import run_in_threadpool
 
+from app.api.deps import OptionalUser
 from app.core.config import settings
+from app.core.logging import trace_id_ctx
 from app.core.pricebot_client import get_pricebot_client
 from app.core.pricebot_router import pick_pricebot
+from app.db.session import SessionLocal
+from app.repositories import comparison as crud_compare
 
 logger = logging.getLogger("shagua.compare")
 
 router = APIRouter(prefix="/api/v1", tags=["compare"])
 
 
-async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
-    """把请求体原样转发给 pricebot-backend 的 {upstream_path}。
+# ============================================================
+# harvest 落库(阻塞 SQLAlchemy → run_in_threadpool,独立 SessionLocal,不阻塞事件循环;
+# 任何写库异常都吞掉、绝不连累比价透传返回 —— 同 coupon.py 现有 best-effort 写法)。
+# ============================================================
 
-    跟 coupon_step 同款透传壳:不鉴权、不做 schema 校验,仅读 device_id/trace_id/step
-    打日志。比价单帧是大上下文 / 逐帧 LLM,超时用 PRICEBOT_COMPARE_TIMEOUT_SEC(60s,
-    比领券的 30s 长)。
+
+def _harvest_running_blocking(
+    trace_id: str, user_id: int | None, business_type: str,
+    device_id: str | None, device_info: dict | None, trace_url: str | None,
+) -> None:
+    with SessionLocal() as db:
+        crud_compare.harvest_running(
+            db, trace_id=trace_id, user_id=user_id, business_type=business_type,
+            device_id=device_id, device_info=device_info, trace_url=trace_url,
+        )
+    logger.info(
+        "harvest running row (user=%s)", user_id,
+        extra={"phase": "harvest_running", "status": "running", "user_id": user_id},
+    )
+
+
+def _harvest_done_blocking(
+    trace_id: str, user_id: int | None, done_params: dict, business_type: str,
+    device_id: str | None, device_info: dict | None, trace_url: str | None,
+) -> None:
+    with SessionLocal() as db:
+        rec, newly_success = crud_compare.harvest_done(
+            db, trace_id=trace_id, user_id=user_id, done_params=done_params,
+            business_type=business_type, device_id=device_id,
+            device_info=device_info, trace_url=trace_url,
+        )
+        logger.info(
+            "harvest done → %s saved=%s newly=%s", rec.status,
+            rec.saved_amount_cents, newly_success,
+            extra={"phase": "harvest_done", "status": rec.status,
+                   "saved_cents": rec.saved_amount_cents,
+                   "best_platform": rec.best_platform_id, "newly_success": newly_success,
+                   "user_id": user_id},
+        )
+        # 不在此处发邀请奖:#113 已把发奖口径从「比价」移到「实际下单」(order.py),harvest
+        # 只记录比价、不发奖。否则比价先于下单 + try_reward 幂等闸会让奖落在「比价」这步,
+        # 架空 #113 的「下单才发奖」防刷意图(newly_success 仅留作日志观测)。
+
+
+def _harvest_abort_blocking(
+    trace_id: str, status_hint: str, reason: str | None, trace_url: str | None,
+) -> None:
+    with SessionLocal() as db:
+        rec = crud_compare.harvest_abort(
+            db, trace_id=trace_id, status=status_hint, reason=reason, trace_url=trace_url,
+        )
+    logger.info(
+        "harvest abort → %s", (rec.status if rec else "no-row"),
+        extra={"phase": "harvest_abort",
+               "status": (rec.status if rec else None), "reason": reason},
+    )
+
+
+async def _forward(
+    request: Request, upstream_path: str, user, *, harvest_first_frame: bool = True,
+) -> tuple[dict[str, Any], str, dict[str, Any]]:
+    """透传给 pricebot 的 {upstream_path},并 mint trace_id + 首帧建 running 行。
+    返回 (resp_json, trace_id, meta)。
+
+    - 客户端首帧不带 trace_id → app-server 用 uuid 签发、写进转发 body、回填进响应顶层
+      `trace_id`(客户端据此拿到后续帧都带上)。带了(老客户端 / 后续帧)→ 原样用、走原始 bytes 快路。
+    - 仅**本次 mint(=首帧)**建 running 行(idempotent);后续帧不再写库。
     """
-    # 读原始字节,避免"反序列化→再序列化"的双重 JSON(省 ~一半透传 CPU,让 app-server
-    # 单 worker 也扛得住高并发)。只 json.loads 一次拿 trace_id 做亲和 + 打日志,转发时
-    # 直接发原始 bytes(content=raw),不重新 dumps。
     raw = await request.body()
     try:
         meta = json.loads(raw)
@@ -52,26 +117,41 @@ async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
     if not isinstance(meta, dict):
         meta = {}
 
-    # 按 trace_id 一致性 hash 选 pricebot 实例(同一比价的所有帧落同一进程,内存维护 state)
-    base = pick_pricebot(meta.get("trace_id"))
+    trace_id = meta.get("trace_id")
+    minted = False
+    if not trace_id:
+        trace_id = str(uuid.uuid4())
+        meta["trace_id"] = trace_id
+        raw = json.dumps(meta).encode()  # 仅首帧重新序列化(注入 trace_id);后续帧走原始 bytes
+        minted = True
+
+    # 请求级 trace_id 贯穿:此后本请求(含 run_in_threadpool 里的 harvest)每行日志自动带 trace_id
+    trace_id_ctx.set(trace_id)
+
+    base = pick_pricebot(trace_id)
     url = f"{base.rstrip('/')}{upstream_path}"
     timeout = settings.PRICEBOT_COMPARE_TIMEOUT_SEC
+    step = meta.get("step")
 
     logger.info(
-        "compare %s device_id=%s trace_id=%s step=%s",
-        upstream_path,
-        meta.get("device_id"),
-        meta.get("trace_id"),
-        meta.get("step"),
+        "→ pricebot %s step=%s%s", upstream_path, step, " [mint]" if minted else "",
+        extra={"phase": "forward", "endpoint": upstream_path, "step": step,
+               "device_id": meta.get("device_id"), "minted": minted,
+               "query": meta.get("query"), "user_id": (user.id if user else None)},
     )
 
+    t0 = time.monotonic()
     try:
         client = get_pricebot_client()
         resp = await client.post(
             url, content=raw, headers={"Content-Type": "application/json"}, timeout=timeout
         )
     except httpx.RequestError as e:
-        logger.error("[pricebot] request failed: %s", e)
+        logger.error(
+            "← pricebot %s 不可达: %s", upstream_path, e,
+            extra={"phase": "resp", "endpoint": upstream_path, "step": step,
+                   "error": "upstream_unreachable"},
+        )
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
             detail=f"pricebot upstream unreachable: {e}",
@@ -79,49 +159,112 @@ async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
 
     if resp.status_code >= 500:
         logger.error(
-            "[pricebot] 5xx status=%d body=%s",
-            resp.status_code,
-            resp.text[:500],
+            "← pricebot %s 5xx=%d", upstream_path, resp.status_code,
+            extra={"phase": "resp", "endpoint": upstream_path, "step": step,
+                   "http_status": resp.status_code, "error": "upstream_5xx"},
         )
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
             detail=f"pricebot upstream returned {resp.status_code}",
         )
 
-    return resp.json()
+    resp_json = resp.json()
+    cost_ms = int((time.monotonic() - t0) * 1000)
+    if not isinstance(resp_json, dict):
+        return {}, trace_id, meta
+    # 回传 app-server 签发的 trace_id(新客户端首帧据此拿到,后续帧都带上它)
+    resp_json.setdefault("trace_id", trace_id)
+    _action = resp_json.get("action") or {}
+    logger.info(
+        "← pricebot %s cmd=%s cont=%s %dms", upstream_path,
+        _action.get("command"), resp_json.get("continue"), cost_ms,
+        extra={"phase": "resp", "endpoint": upstream_path, "step": step,
+               "command": _action.get("command"), "continue": resp_json.get("continue"),
+               "cost_ms": cost_ms},
+    )
+
+    # 首帧建 running 行(仅本次 mint;老客户端自带 trace_id → 不 mint → 由 done / 其 POST 建行)
+    if minted and harvest_first_frame:
+        try:
+            await run_in_threadpool(
+                _harvest_running_blocking, trace_id,
+                (user.id if user else None), "food",
+                meta.get("device_id"), meta.get("device_info"),
+                resp_json.get("trace_url"),
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning("harvest_running failed trace=%s: %s", trace_id, e)
+
+    return resp_json, trace_id, meta
 
 
-@router.post("/intent/recognize", summary="外卖比价 Phase 1 意图识别 (透传到 pricebot)")
-async def intent_recognize(request: Request) -> dict[str, Any]:
-    return await _passthrough(request, "/api/intent/recognize")
+@router.post("/intent/recognize", summary="外卖比价 Phase 1 意图识别 (透传 + 建 running 行)")
+async def intent_recognize(request: Request, user: OptionalUser) -> dict[str, Any]:
+    resp, _, _ = await _forward(request, "/api/intent/recognize", user)
+    return resp
 
 
-@router.post("/intent/step", summary="外卖比价 Phase 1 多帧意图识别 (透传到 pricebot, 仅淘宝源)")
-async def intent_step(request: Request) -> dict[str, Any]:
-    # 多帧版意图识别(展开+滚动采集→提取): 循环调用直到 done(done 帧顶层带
-    # result+calibration)。目前仅淘宝源走这条, 其它源走上面单次 /intent/recognize。
-    return await _passthrough(request, "/api/intent/step")
+@router.post("/intent/step", summary="外卖比价 Phase 1 多帧意图识别 (透传, 仅淘宝源)")
+async def intent_step(request: Request, user: OptionalUser) -> dict[str, Any]:
+    resp, _, _ = await _forward(request, "/api/intent/step", user)
+    return resp
 
 
-@router.post(
-    "/intent/precoupon/step",
-    summary="外卖比价 Phase 0 意图识别前先用券 (透传到 pricebot, 仅美团源)",
-)
-async def intent_precoupon_step(request: Request) -> dict[str, Any]:
-    # 美团源平台『意图识别前先用券』多帧循环: 客户端在调 /intent/recognize 之前先循环
-    # 调本端点到 done(continue=false)。订单页底部有『点击使用X红包』就自动选最大免费券
-    # 用上, 已用券/无券则首帧秒过。与 /intent/step 同属 intent 域, 复用同一透传壳。
-    return await _passthrough(request, "/api/intent/precoupon/step")
+@router.post("/intent/precoupon/step", summary="外卖比价 Phase 0 识别前先用券 (透传, 仅美团源)")
+async def intent_precoupon_step(request: Request, user: OptionalUser) -> dict[str, Any]:
+    resp, _, _ = await _forward(request, "/api/intent/precoupon/step", user)
+    return resp
 
 
-@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传到 pricebot)")
-async def price_step(request: Request) -> dict[str, Any]:
-    return await _passthrough(request, "/api/price/step")
+@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传 + done 落库)")
+async def price_step(request: Request, user: OptionalUser) -> dict[str, Any]:
+    resp, trace_id, meta = await _forward(request, "/api/price/step", user)
+    # 最终 done 帧(command=done 且 continue=false)→ harvest 更新成终态。
+    # (单平台中途 done 被 pricebot 改写成 wait+continue=true,不会命中这里,同 coupon 语义。)
+    action = resp.get("action") or {}
+    if action.get("command") == "done" and not resp.get("continue", True):
+        done_params = action.get("params") or {}
+        try:
+            await run_in_threadpool(
+                _harvest_done_blocking, trace_id, (user.id if user else None),
+                done_params, "food",
+                meta.get("device_id"), meta.get("device_info"),
+                resp.get("trace_url") or done_params.get("trace_url"),
+            )
+        except Exception as e:  # noqa: BLE001
+            logger.warning("harvest_done failed trace=%s: %s", trace_id, e)
+    return resp
 
 
-@router.post("/trace/finalize", summary="比价 trace 收尾上云 (透传到 pricebot, 终止/未识别拿 trace_url)")
-async def trace_finalize(request: Request) -> dict[str, Any]:
-    # 用户终止 / Phase1 未识别没走到 done 帧, pricebot 没上云也没回传 trace_url。客户端收尾时
-    # 打这个, _passthrough 按 trace_id 一致性 hash 落到处理这条 trace 的同一 pricebot 进程
-    # (dir_cache 在那, 才能算对 trace 目录), 由后者打包上云返回 {trace_url}。
-    return await _passthrough(request, "/api/trace/finalize")
+@router.post("/trace/epilogue", summary="比价结果页尾声帧 (透传到 pricebot, 用户视角截图入 trace)")
+async def trace_epilogue(request: Request, user: OptionalUser) -> dict[str, Any]:
+    # App 收到 done、渲染完结果页后,把自己页面的截图(base64)传给 pricebot 存进 trace
+    # 目录并触发重传 —— trace 里补上"用户实际看到的汇总页"(步骤帧只有目标 App 画面)。
+    # body ~几百 KB(截图 base64), 纯透传壳(harvest_first_frame=False:不建行/不落库,
+    # 该 trace 的记录已由 done/finalize 落终态)。#112 原走 _passthrough,合并到 harvest
+    # 分支后统一走 _forward(_passthrough 已并入它)。
+    resp, _, _ = await _forward(
+        request, "/api/trace/epilogue", user, harvest_first_frame=False,
+    )
+    return resp
+
+
+@router.post("/trace/finalize", summary="比价 trace 收尾上云 (透传 + 夭折落库)")
+async def trace_finalize(request: Request, user: OptionalUser) -> dict[str, Any]:
+    # 用户终止 / Phase1 未识别没到 done 帧: pricebot 打包半截上云返回 {trace_url};
+    # app-server 顺手把该 trace 的 running 行更新成夭折终态(**不降级 success**)。
+    # 客户端 finalize body 带 status(cancelled/failed)+ reason;老客户端只带 trace_id →
+    # 默认 cancelled,其后续 /compare/record 上报再补精确态。
+    resp, trace_id, meta = await _forward(
+        request, "/api/trace/finalize", user, harvest_first_frame=False,
+    )
+    try:
+        await run_in_threadpool(
+            _harvest_abort_blocking, trace_id,
+            (meta.get("status") or "cancelled"),
+            (meta.get("reason") or meta.get("information")),
+            (resp.get("trace_url") if isinstance(resp, dict) else None),
+        )
+    except Exception as e:  # noqa: BLE001
+        logger.warning("harvest_abort failed trace=%s: %s", trace_id, e)
+    return resp

app/api/v1/compare_record.py

@@ -1,15 +1,13 @@
-"""比价记录 endpoint(「我的比价记录」数据源)。
+"""比价记录 endpoint(「我的比价记录」+ admin 数据源)。
 
 路由前缀 `/api/v1/compare`:
-  POST /record         上报一次比价结果(幂等:同 user+trace_id 覆盖)
+  POST /record         (灰度期兼容)老客户端上报,按 **trace_id** 幂等 + 不降级 success
   GET  /records        比价记录列表(游标分页)
   GET  /records/{id}   单条详情(含 raw_payload 全量)
 
-**均需鉴权**(CurrentUser)——与同文件无关的不鉴权透传 `compare.py` 分开:那个是
-转发壳(MVP 不鉴权),这里是按用户维度落库的业务接口,必须有 user_id。
-
-注:本轮只做 server 端,客户端(android 仓)在 done 帧后调 POST /record 上报的改动
-另起一轮(见 app-server docs/待办与技术债.md P1)。
+**均需鉴权**(CurrentUser)。⚠️ 写路径现以 `compare.py` 透传壳的**后端 harvest** 为主
+(帧0 建 running 行 → done/finalize 落终态,新客户端不再 POST);本 POST /record 仅灰度期
+给老客户端用,与 harvest 按 trace_id reconcile。新版覆盖够高后可下线本 POST(阶段3)。
 """
 from __future__ import annotations
 
@@ -21,16 +19,16 @@ from app.api.deps import CurrentUser, DbSession
 from app.db.session import SessionLocal
 from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud_compare
-from app.repositories import invite as crud_invite
-from app.services.pricebot_llm_calls import fetch_llm_calls
 from app.schemas.compare_record import (
     CompareStatsOut,
     ComparisonRecordCreatedOut,
     ComparisonRecordDetailOut,
     ComparisonRecordIn,
-    ComparisonRecordPage,
     ComparisonRecordOut,
+    ComparisonRecordPage,
 )
+from app.services.llm_cost import compute_llm_cost, get_llm_prices
+from app.services.pricebot_llm_calls import fetch_llm_calls
 
 logger = logging.getLogger("shagua.compare_record")
 
@@ -53,18 +51,8 @@ def report_record(
     # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
     # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
     background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
-    # 邀请 v2 发奖:被邀请人完成一次【成功】比价 → 给邀请人发邀请奖励金(幂等,只发一次)。
-    # best-effort:发奖异常不影响比价上报本身(rec 已 commit),只 log;邀请人补偿靠后续对账。
-    if rec.status == "success":
-        try:
-            reward = crud_invite.try_reward_on_compare(db, user.id)
-            if reward.status == "granted":
-                logger.info(
-                    "invite compare reward granted inviter=%s invitee=%s cents=%s",
-                    reward.inviter_user_id, user.id, reward.reward_cents,
-                )
-        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞上报
-            logger.warning("invite compare reward failed invitee=%s: %s", user.id, e)
+    # 注:邀请发奖已从"比价成功"挪到"实际下单"(见 api/v1/order.py report_order)——
+    # 冰拍板:被邀请人完成比价并实际下单才算邀请成功,仅完成比价不再发奖。
     logger.info(
         "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
         user.id,
@@ -94,6 +82,8 @@ def _backfill_llm_calls(record_id: int, trace_id: str) -> None:
         # error 的调用 usage 可能为 None,or {} 兜底)
         rec.input_tokens = sum((c.get("usage") or {}).get("prompt_tokens") or 0 for c in calls)
         rec.output_tokens = sum((c.get("usage") or {}).get("completion_tokens") or 0 for c in calls)
+        # 本次比价 LLM 成本(元)+ 当时单价快照:按 app_config 现价逐模型算好冻结(services/llm_cost.py)。
+        rec.llm_cost_yuan, rec.llm_price_snapshot = compute_llm_cost(calls, get_llm_prices(db))
         db.commit()
         logger.info(
             "backfill llm_calls trace=%s n=%d in_tok=%d out_tok=%d",

app/api/v1/coupon.py

@@ -81,7 +81,16 @@ def _record_claims_blocking(
     device_id: str, user_id: int | None, trace_id: str | None, results: list[dict]
 ) -> None:
     with SessionLocal() as db:
-        coupon_repo.record_claims(db, device_id, user_id, trace_id, results)
+        # 取本次 session 环境,给 coupon_claim_record 打 app_env 标(每券成功率表按它过滤;设计 §13)。
+        app_env = coupon_repo.session_app_env(db, trace_id)
+        coupon_repo.record_claims(db, device_id, user_id, trace_id, results, app_env=app_env)
+        # 顺带把本帧「成功平台」并入 coupon_session.platform_success(admin 领券数据 ②整单/③点位成功率;
+        # 设计 route B,见 docs/guides/领券成功率指标-设计与埋点.md)。复用同一 SessionLocal、紧接 record_claims,
+        # 不新增连接;并集幂等(无新平台不写),trace_id 缺失或 session 行未落库则跳过。
+        if trace_id:
+            coupon_repo.merge_session_platform_success(
+                db, trace_id, coupon_repo.succeeded_platforms(results)
+            )
 
 
 def _mark_completed_blocking(

app/api/v1/meituan.py

@@ -25,9 +25,19 @@ from app.schemas.meituan import (
     ReferralLinkResponse,
     TopSalesRequest,
 )
+from app.utils.meituan_city import get_meituan_city
 
 logger = logging.getLogger("shagua.meituan")
 
+
+def _resolve_city_id(latitude: float, longitude: float) -> str:
+    """经纬度 → 美团城市 ID;解析失败返 ""（调用方应降级返空）。"""
+    try:
+        return get_meituan_city(latitude, longitude).get("city_id", "")
+    except Exception:
+        logger.exception("get_meituan_city 失败")
+        return ""
+
 router = APIRouter(prefix="/api/v1/meituan", tags=["meituan-cps"])
 
 
@@ -175,13 +185,19 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
         status = "degraded" if (not cards and wm_fail and dd_fail) else ("ok" if cards else "empty")
         return FeedResponse(items=cards, has_next=wm_hn or dd_hn, page=req.page, status=status)
 
-    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
+    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,按城市过滤,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
     # 实测库里佣金≥3% 去重后仅 ~578 条(几乎全是外卖;到店团购佣金普遍 <3%):实时按"同城热销榜单"
     # 拉既撞限流、又填不满(该榜单中位佣金 ~0.8%,筛完每页剩 0-1 条),故从库出。佣金阈值逻辑不变。
     if tab == "rec":
+        city_id = _resolve_city_id(lat, lon)
+        if not city_id:
+            return FeedResponse(items=[], has_next=False, page=req.page, status="degraded")
         PAGE = 20
         try:
-            base = select(MeituanCoupon).where(MeituanCoupon.commission_percent >= 3.0)
+            base = select(MeituanCoupon).where(
+                MeituanCoupon.commission_percent >= 3.0,
+                MeituanCoupon.city_id == city_id,
+            )
             deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
                 MeituanCoupon.dedup_key,
                 MeituanCoupon.commission_percent.desc(),
@@ -211,6 +227,9 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
                 card.distance_text = None
                 card.distance_meters = None
                 cards.append(card)
+        if not cards and req.page == 1:
+            # 命中城市却 0 券:该城确无 ≥3% 券,或 ETL 灌的 city_id 与 city_dict 口径不一致。
+            logger.info("[feed] rec city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
         return FeedResponse(items=cards, has_next=has_next, page=req.page,
                             status="ok" if cards else "empty")
 
@@ -254,14 +273,24 @@ def referral_link(req: ReferralLinkRequest) -> ReferralLinkResponse:
 
 
 @router.post("/top-sales", response_model=CouponListResponse,
-             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,不实时打美团)")
+             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,按城市过滤,不实时打美团)")
 def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponListResponse:
+    # 按设备经纬度定位城市,只查同城券;老客户端不带坐标 → 降级返空(不 422、不误返全城)。
+    if req.latitude is None or req.longitude is None:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+    city_id = _resolve_city_id(req.latitude, req.longitude)
+    if not city_id:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+
     # 去重 + 排序 + 分页全在 SQL 做,每页只取并解析当前页 ~20 条。
     # (之前实现每翻一页都全表拉取 + 全量 from_raw 解析,翻页慢 → 客户端滑动卡顿/翻不动。)
     # 库为空(prod 刚部署 / ETL 未跑完)时返空 + status=empty,不崩;库查询异常降级 degraded。
     try:
         # 1) DISTINCT ON (dedup_key):每个去重键(品牌|名|价)只留销量最高那条(同销量再按佣金)
-        base = select(MeituanCoupon).where(MeituanCoupon.sale_volume_num.isnot(None))
+        base = select(MeituanCoupon).where(
+            MeituanCoupon.sale_volume_num.isnot(None),
+            MeituanCoupon.city_id == city_id,
+        )
         if req.platform is not None:
             base = base.where(MeituanCoupon.platform == req.platform)
         deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
@@ -292,6 +321,14 @@ def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponList
         except Exception:  # noqa: BLE001
             continue
         if card.product_view_sign:
+            # 不显示距离:库里的距离是相对城市默认点的(对用户无意义、且误导)。
+            # 置空后前端"距离 店名"那行只剩店名、自动顶到最左(店名移到原距离的位置)。
+            # 逻辑与推荐流保持一致
+            card.distance_text = None
+            card.distance_meters = None
             cards.append(card)
+    if not cards and req.page == 1:
+        # 命中城市却 0 券:可能该城确无券,也可能 ETL 灌的 city_id 与 city_dict 口径不一致(静默降级的隐患)。
+        logger.info("[top-sales] city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
     return CouponListResponse(items=cards, has_next=has_next, search_id=None,
                               status="ok" if cards else "empty")

app/api/v1/order.py

@@ -1,9 +1,14 @@
+import logging
+
 from fastapi import APIRouter
 
 from app.api.deps import CurrentUser, DbSession
+from app.repositories import invite as crud_invite
 from app.repositories import savings as crud_savings
 from app.schemas.order import OrderReportOut, OrderReportRequest
 
+logger = logging.getLogger("shagua.order")
+
 router = APIRouter(prefix="/api/v1/order", tags=["order"])
 
 
@@ -15,6 +20,20 @@ router = APIRouter(prefix="/api/v1/order", tags=["order"])
 def report_order(req: OrderReportRequest, user: CurrentUser, db: DbSession) -> OrderReportOut:
     # 记账唯一真相表是 savings_record(source='compare')。
     rec, duplicated = crud_savings.create_from_report(db, user.id, req)
+    # 邀请 v2 发奖:被邀请人【实际下单】(而非仅完成比价)才给邀请人发邀请奖励金(幂等,只发一次)。
+    # 触发点从"比价成功上报"挪到这里(冰:完成比价并实际下单才算成功)。仅首次真实上报触发,
+    # 重复上报(duplicated)跳过。best-effort:发奖异常不影响订单上报本身(rec 已 commit),只 log;
+    # try_reward_on_compare 自带 compare_reward_granted 幂等闸,漏发靠后续对账补。
+    if not duplicated:
+        try:
+            reward = crud_invite.try_reward_on_compare(db, user.id)
+            if reward.status == "granted":
+                logger.info(
+                    "invite order reward granted inviter=%s invitee=%s cents=%s",
+                    reward.inviter_user_id, user.id, reward.reward_cents,
+                )
+        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞订单上报
+            logger.warning("invite order reward failed invitee=%s: %s", user.id, e)
     return OrderReportOut(
         id=rec.id,
         platform=rec.platform or req.platform,

app/api/v1/user.py

@@ -69,6 +69,18 @@ def complete_onboarding(
     return OkResponse()
 
 
+@router.post("/onboarding/reset", response_model=OkResponse, summary="重置新手引导(删该 设备+账号 完成标记,下次登录重走)")
+def reset_onboarding(
+    req: OnboardingCompleteRequest, user: CurrentUser, db: DbSession
+) -> OkResponse:
+    """删该 (当前账号, device_id) 的引导完成标记 → 下次登录 onboarding_completed=false,客户端重走。
+    与 /onboarding/complete 互逆。device_id 取客户端硬件级 ANDROID_ID(与登录/complete 一致)。
+    幂等:无记录也返回 ok。仅删自己(当前 JWT 用户)这台设备的记录,不影响别的账号/设备。"""
+    deleted = onboarding_repo.delete_completion(db, user_id=user.id, device_id=req.device_id)
+    logger.info("onboarding reset user_id=%d device_len=%d deleted=%d", user.id, len(req.device_id), deleted)
+    return OkResponse()
+
+
 @router.get(
     "/onboarding/status",
     response_model=OnboardingStatusResponse,

app/api/v1/wallet.py

@@ -43,6 +43,7 @@ from app.schemas.welfare import (
     WithdrawRequest,
     WithdrawResultOut,
     WithdrawStatusOut,
+    WithdrawTierOut,
 )
 
 logger = logging.getLogger("shagua.wallet")
@@ -173,8 +174,15 @@ def unbind_wechat(
     return UnbindWechatResultOut(bound=False)
 
 
-@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态/免确认开关")
-def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
+@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态/免确认开关/档位")
+def withdraw_info(
+    user: CurrentUser,
+    db: DbSession,
+    source: str = Query(
+        "coin_cash",
+        description="提现账户:coin_cash(福利页,下发 tiers 档位) / invite_cash(邀请页,tiers 为空走旧逻辑)",
+    ),
+) -> WithdrawInfoOut:
     u = db.get(User, user.id)
     # 顺带同步免确认授权状态(捕获首单确认后已生效的授权 pending→active),让开关展示实时
     auth = crud_wallet.sync_transfer_auth(db, user.id)
@@ -185,6 +193,7 @@ def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
         wechat_nickname=u.wechat_nickname if u else None,
         wechat_avatar_url=u.wechat_avatar_url if u else None,
         transfer_auth_enabled=bool(auth and auth.state == "active"),
+        tiers=[WithdrawTierOut(**t) for t in crud_wallet.withdraw_tier_states(db, user.id, source)],
     )
 
 
@@ -218,6 +227,9 @@ def withdraw(req: WithdrawRequest, user: CurrentUser, db: DbSession) -> Withdraw
             status_code=status.HTTP_409_CONFLICT,
             detail="已有提现申请正在审核或打款中,请处理完成后再申请",
         ) from e
+    except crud_wallet.WithdrawTierUnavailableError as e:
+        # 福利页档位闸(7-9):次数满/已选其他额度。正常客户端已按 tiers 预拦,此处兜底防绕过。
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="今日额度已达上限") from e
     except crud_wallet.InsufficientCashError as e:
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="现金余额不足") from e