Merge origin/main into feat/compare-record-backend-harvest

解决 compare.py 冲突 + 对齐 #113 邀请发奖口径:
- compare.py 冲突(#112 新增 /trace/epilogue vs 本分支 harvest 重写):保留 harvest
  全套,把 #112 的 /trace/epilogue 端点从已删除的 _passthrough 改写到 _forward
  (harvest_first_frame=False 纯透传,不建行/不落库——该 trace 记录已由 done/finalize 落终态)
- 对齐 #113(发奖从「比价」改「实际下单」):从 harvest_done 移除 try_reward_on_compare
  调用 + 其 import,发奖只保留在 order.py(#113 加)。否则比价先于下单 + try_reward
  幂等闸会把奖落在「比价」这步,架空 #113 的「下单才发奖」防刷。同步清理相关
  docstring/summary(price_step「+发奖」措辞、模块头「幂等发一次邀请奖」)

验证:本分支 harvest/proxy/milestone 测试全绿(44 passed);py_compile 通过;无残留冲突标记。
注:tests/test_invite.py::test_bind_flow_no_coins_either_side 在 pristine origin/main 上
即已红(#113 改 invite 行为但未随附测试更新),非本次合并引入,不在本分支职责内。

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

app/api/v1/compare.py

@@ -4,7 +4,8 @@
 在透传里直接落库比价记录**(不再靠客户端 POST /compare/record):
   - 帧0(客户端首帧不带 trace_id)→ app-server 用 uuid 签发 trace_id、注入转发 body、回给
     客户端;并按 trace_id 建 running 行(harvest_running)。
-  - 最终 done 帧 → 更新成 success/failed + 结果(harvest_done)+ **幂等发一次邀请奖**。
+  - 最终 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)。
@@ -34,7 +35,6 @@ 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
-from app.repositories import invite as crud_invite
 
 logger = logging.getLogger("shagua.compare")
 
@@ -80,16 +80,9 @@ def _harvest_done_blocking(
                    "best_platform": rec.best_platform_id, "newly_success": newly_success,
                    "user_id": user_id},
         )
-        # 本次**新**落成 success + 有登录用户 → 发一次邀请奖(try_reward 自身幂等,双保险)。
-        if newly_success and user_id is not None:
-            try:
-                crud_invite.try_reward_on_compare(db, user_id)
-                logger.info(
-                    "invite reward fired (user=%s)", user_id,
-                    extra={"phase": "reward", "user_id": user_id},
-                )
-            except Exception as e:  # noqa: BLE001 发奖失败不连累比价
-                logger.warning("harvest invite reward failed user=%s: %s", user_id, e)
+        # 不在此处发邀请奖:#113 已把发奖口径从「比价」移到「实际下单」(order.py),harvest
+        # 只记录比价、不发奖。否则比价先于下单 + try_reward 幂等闸会让奖落在「比价」这步,
+        # 架空 #113 的「下单才发奖」防刷意图(newly_success 仅留作日志观测)。
 
 
 def _harvest_abort_blocking(
@@ -223,10 +216,10 @@ async def intent_precoupon_step(request: Request, user: OptionalUser) -> dict[st
     return resp
 
 
-@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传 + done 落库 + 发奖)")
+@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 帧(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):
@@ -243,6 +236,19 @@ async def price_step(request: Request, user: OptionalUser) -> dict[str, Any]:
     return resp
 
 
+@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/api/v1/compare_record.py

@@ -19,16 +19,15 @@ 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.pricebot_llm_calls import fetch_llm_calls
 
 logger = logging.getLogger("shagua.compare_record")
 
@@ -51,18 +50,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,

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/repositories/invite.py

@@ -304,6 +304,9 @@ def get_invitees(
             "avatar_url": u.avatar_url or u.wechat_avatar_url or None,
             "coins": rel.inviter_coin,      # v3 起恒 0(邀请人收益改走邀请奖励金)
             "invited_at": rel.created_at,
+            # 是否已完成过一次比价(= 已发过邀请奖励金)。客户端据此:好友列表分"去提醒/邀请成功"、
+            # 在途列表只取未比价(is_compared=False)、算在途好友数与在途收益(未比价数×2元)。
+            "is_compared": bool(rel.compare_reward_granted),
         })
     has_more = offset + len(rows) < int(total)
     return items, int(total), has_more

app/repositories/wallet.py

@@ -296,6 +296,9 @@ def daily_auto_exchange(db: Session) -> dict:
     - **逐用户独立事务**:单个用户异常 rollback 不影响其他人;exchange_coins_to_cash 内部按用户 commit。
     返回统计 dict(scanned/converted/skipped_done/skipped_dust/failed/total_cents)。
     """
+    # ⚠️「今天」写死北京时(rewards.cn_today() = datetime.now(CN_TZ).date(), CN_TZ=+8),与服务器/用户
+    #   时区无关(用户 2026-07-01 硬约束:兑换一律北京 0 点日切)。**禁止**改成 date.today() / 裸
+    #   datetime.now().date()——那会跟随进程本地时区,服务器非 CST 时会在错误的"天"兑/重复兑。
     today = rewards.cn_today()
     stats = {
         "scanned": 0, "converted": 0, "skipped_done": 0,

app/schemas/invite.py

@@ -69,6 +69,7 @@ class InviteeItem(BaseModel):
     avatar_url: str | None = None   # 头像 URL;null = 前端画默认色块
     coins: int                      # 这次邀请给我(邀请人)发的金币
     invited_at: datetime            # 邀请绑定时间(前端转"今天/3天前")
+    is_compared: bool = False       # 该好友是否已完成过一次比价(好友列表分"去提醒/邀请成功";在途列表只取 False)
 
 
 class InviteeListOut(BaseModel):

deploy/daily-exchange.service

@@ -19,6 +19,9 @@ Type=oneshot
 User=root
 WorkingDirectory=/opt/shaguabijia-app-server
 Environment="PATH=/opt/shaguabijia-app-server/.venv/bin:/usr/bin:/bin"
+# 写死北京时:兑换的"当天/0 点"一律按北京时,不随服务器 OS 时区漂(用户 2026-07-01 硬约束)。
+# 脚本内的日期判断本就走 rewards.cn_today()(CN_TZ=+8),这里再把进程 TZ 也钉成北京,双保险。
+Environment="TZ=Asia/Shanghai"
 EnvironmentFile=/opt/shaguabijia-app-server/.env
 ExecStart=/opt/shaguabijia-app-server/.venv/bin/python -m scripts.daily_auto_exchange --once
 SyslogIdentifier=daily-exchange

deploy/daily-exchange.timer

@@ -4,8 +4,10 @@
 Description=Run daily auto-exchange coins->cash at midnight
 
 [Timer]
-# 每天 0 点跑。客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
-OnCalendar=*-*-* 00:00:00
+# 每天【北京时】0 点跑,写死时区(用户 2026-07-01 硬约束:兑换一律北京 0 点,不随服务器本地时区漂)。
+# systemd OnCalendar 支持尾缀时区;不写时区会按服务器 OS 本地时区触发 → 服务器非 CST 时会在错误时刻兑。
+# 客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
+OnCalendar=*-*-* 00:00:00 Asia/Shanghai
 # 服务器宕机/重启后,补跑错过的那一轮(而不是干等次日)。
 Persistent=true
 AccuracySec=1min