feat(compare): 比价记录落库 + 战绩里程碑(真发金币)

- comparison_record 表 + 上报(幂等 user+trace)/列表/详情 接口;服务端派生
  best/saved/is_source_best/status + information(done 帧文案/失败具体原因)
- 战绩里程碑:comparison_milestone_claim 表 + 进度/领取接口,按成功比价次数
  解锁,复用 grant_coins 真发金币(RECORD_MILESTONES 120/180/300/500/800/1200)
- 迁移 record/information/milestone 三个,单 head;rewards.py 集中档位配置
- 测试 test_compare_record(8)+test_compare_milestone(7) 全绿;docs/api 12a-12e + 索引

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

app/api/v1/compare_milestone.py

@@ -0,0 +1,76 @@
+"""比价战绩里程碑 endpoint(福利页「记录比价战绩」)。
+
+路由前缀 `/api/v1/compare`:
+  GET  /milestones                进度与各档领取状态
+  POST /milestones/{milestone}/claim  领取某档奖励
+
+**均需鉴权**。解锁进度 = 该用户 status='success' 的 comparison_record 条数;每档领一次。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import comparison_milestone as crud_milestone
+from app.schemas.compare_record import (
+    MilestoneClaimResultOut,
+    MilestoneStateOut,
+    MilestoneStatusOut,
+)
+
+logger = logging.getLogger("shagua.compare_milestone")
+
+router = APIRouter(prefix="/api/v1/compare", tags=["compare-milestone"])
+
+
+@router.get(
+    "/milestones",
+    response_model=MilestoneStatusOut,
+    summary="比价战绩里程碑进度",
+)
+def get_milestones(user: CurrentUser, db: DbSession) -> MilestoneStatusOut:
+    st = crud_milestone.get_status(db, user.id)
+    return MilestoneStatusOut(
+        success_count=st.success_count,
+        claimable_count=st.claimable_count,
+        milestones=[
+            MilestoneStateOut(milestone=m.milestone, coin=m.coin, state=m.state)
+            for m in st.milestones
+        ],
+    )
+
+
+@router.post(
+    "/milestones/{milestone}/claim",
+    response_model=MilestoneClaimResultOut,
+    summary="领取比价战绩里程碑奖励",
+)
+def claim_milestone(
+    milestone: int, user: CurrentUser, db: DbSession
+) -> MilestoneClaimResultOut:
+    try:
+        coin, balance = crud_milestone.claim(db, user.id, milestone)
+    except crud_milestone.UnknownMilestoneError as e:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="unknown milestone"
+        ) from e
+    except crud_milestone.MilestoneLockedError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="milestone locked"
+        ) from e
+    except crud_milestone.AlreadyClaimedError as e:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT, detail="milestone already claimed"
+        ) from e
+
+    logger.info(
+        "compare milestone claimed user_id=%d milestone=%d coin=%d",
+        user.id,
+        milestone,
+        coin,
+    )
+    return MilestoneClaimResultOut(
+        milestone=milestone, coin_awarded=coin, coin_balance=balance
+    )

app/api/v1/compare_record.py

@@ -0,0 +1,86 @@
+"""比价记录 endpoint(「我的比价记录」数据源)。
+
+路由前缀 `/api/v1/compare`:
+  POST /record         上报一次比价结果(幂等:同 user+trace_id 覆盖)
+  GET  /records        比价记录列表(游标分页)
+  GET  /records/{id}   单条详情(含 raw_payload 全量)
+
+**均需鉴权**(CurrentUser)——与同文件无关的不鉴权透传 `compare.py` 分开:那个是
+转发壳(MVP 不鉴权),这里是按用户维度落库的业务接口,必须有 user_id。
+
+注:本轮只做 server 端,客户端(android 仓)在 done 帧后调 POST /record 上报的改动
+另起一轮(见 app-server docs/待办与技术债.md P1)。
+"""
+from __future__ import annotations
+
+import logging
+
+from fastapi import APIRouter, HTTPException, Query, status
+
+from app.api.deps import CurrentUser, DbSession
+from app.repositories import comparison as crud_compare
+from app.schemas.compare_record import (
+    ComparisonRecordCreatedOut,
+    ComparisonRecordDetailOut,
+    ComparisonRecordIn,
+    ComparisonRecordPage,
+    ComparisonRecordOut,
+)
+
+logger = logging.getLogger("shagua.compare_record")
+
+router = APIRouter(prefix="/api/v1/compare", tags=["compare-record"])
+
+
+@router.post(
+    "/record",
+    response_model=ComparisonRecordCreatedOut,
+    summary="上报一次比价结果(幂等)",
+)
+def report_record(
+    payload: ComparisonRecordIn, user: CurrentUser, db: DbSession
+) -> ComparisonRecordCreatedOut:
+    rec = crud_compare.upsert_record(db, user_id=user.id, payload=payload)
+    logger.info(
+        "compare record user=%s trace=%s biz=%s status=%s saved=%s",
+        user.id,
+        rec.trace_id,
+        rec.business_type,
+        rec.status,
+        rec.saved_amount_cents,
+    )
+    return ComparisonRecordCreatedOut(id=rec.id)
+
+
+@router.get(
+    "/records",
+    response_model=ComparisonRecordPage,
+    summary="比价记录列表(游标分页)",
+)
+def list_records(
+    user: CurrentUser,
+    db: DbSession,
+    limit: int = Query(20, ge=1, le=100),
+    cursor: int | None = Query(None, description="上一页末条 id"),
+) -> ComparisonRecordPage:
+    items, next_cursor = crud_compare.list_records(
+        db, user.id, limit=limit, cursor=cursor
+    )
+    return ComparisonRecordPage(
+        items=[ComparisonRecordOut.model_validate(it) for it in items],
+        next_cursor=next_cursor,
+    )
+
+
+@router.get(
+    "/records/{record_id}",
+    response_model=ComparisonRecordDetailOut,
+    summary="比价记录详情(含 raw_payload)",
+)
+def get_record(
+    record_id: int, user: CurrentUser, db: DbSession
+) -> ComparisonRecordDetailOut:
+    rec = crud_compare.get_record(db, user.id, record_id)
+    if rec is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="record not found")
+    return ComparisonRecordDetailOut.model_validate(rec)

app/core/rewards.py

@@ -58,6 +58,19 @@ TASK_REWARDS: dict[str, int] = {
 }
 
 
+# ===== 比价战绩里程碑(累计成功比价 N 次,逐档解锁领金币)=====
+# 第 1→6 次的金币奖励(1-based:第 N 次比价解锁第 N 档)。值沿用客户端原型档位。
+# 数据源是 comparison_record 里 status='success' 的条数;每档领一次,
+# comparison_milestone_claim 去重(仿一次性任务)。要调档位/金额直接改这里。
+RECORD_MILESTONES: tuple[int, ...] = (120, 180, 300, 500, 800, 1200)
+RECORD_MILESTONE_COUNT: int = len(RECORD_MILESTONES)
+
+
+def record_milestone_reward(milestone: int) -> int:
+    """第 milestone 档(1..RECORD_MILESTONE_COUNT)的金币。越界抛 IndexError。"""
+    return RECORD_MILESTONES[milestone - 1]
+
+
 # ===== 看激励视频发金币(穿山甲 S2S 服务端回调发奖)=====
 # 看完一个激励视频发的金币(100 金币 ≈¥0.01,汇率 10000 金币=1 元)。
 # 作用:① 回调缺/坏 reward_amount 时的回退值;② 客户端进度接口展示的"单次预告金币";

app/main.py

@@ -17,6 +17,8 @@ from fastapi.staticfiles import StaticFiles
 from app.api.v1.ad import router as ad_router
 from app.api.v1.auth import router as auth_router
 from app.api.v1.compare import router as compare_router
+from app.api.v1.compare_milestone import router as compare_milestone_router
+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.feedback import router as feedback_router
 from app.api.v1.meituan import router as meituan_router
@@ -74,6 +76,8 @@ app.include_router(user_router)
 app.include_router(feedback_router)
 app.include_router(coupon_router)
 app.include_router(compare_router)
+app.include_router(compare_record_router)
+app.include_router(compare_milestone_router)
 app.include_router(meituan_router)
 app.include_router(wallet_router)
 app.include_router(signin_router)

app/models/__init__.py

@@ -1,6 +1,8 @@
 """所有 ORM model 必须在这里 import 一次,Alembic / metadata 才能扫到。"""
 from app.models.ad_ecpm import AdEcpmRecord  # noqa: F401
 from app.models.ad_reward import AdRewardRecord  # noqa: F401
+from app.models.comparison import ComparisonRecord  # noqa: F401
+from app.models.comparison_milestone import ComparisonMilestoneClaim  # noqa: F401
 from app.models.feedback import Feedback  # noqa: F401
 from app.models.savings import SavingsRecord  # noqa: F401
 from app.models.signin import SigninRecord  # noqa: F401

app/models/comparison.py

@@ -0,0 +1,101 @@
+"""比价记录表。
+
+每完成一次比价(外卖/电商/领券),客户端在 done 帧后用带 JWT 的通道上报一条,落这里。
+是未来「我的比价记录」页的数据源,也沉淀用户级行为画像(哪个用户在哪两家之间比了什么)。
+
+与 savings_record 的区别:savings_record 是「省了多少钱」的视角(只有省到才有意义,当前由
+demo seeder 灌),本表是「每一次比价的完整明细」——不省钱、甚至失败的比价也照记一条。
+两表独立,互不影响。
+
+「越详细越好」的落地:结构化列给查询/排序/聚合用,raw_payload(JSONB)把客户端上报的
+原始 calibration + done.params 原样存一份,未来前端要展示什么都能拿到、不丢信息。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    JSON,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+# PG 上用 JSONB(可建 GIN 索引),SQLite(本地/测试)退化为通用 JSON——
+# 否则 SQLite 无 JSONB,Base.metadata.create_all 编译报错(同 savings_record.dishes)。
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class ComparisonRecord(Base):
+    __tablename__ = "comparison_record"
+    __table_args__ = (
+        # 同一用户同一次比价(trace_id)只存一条:客户端重试/误点重复上报时幂等覆盖。
+        UniqueConstraint("user_id", "trace_id", name="uq_comparison_user_trace"),
+    )
+
+    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
+    )
+    # 仍记录设备号(同一用户多设备的行为区分 / 与不鉴权期 device_id 数据对账)
+    device_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 业务类型:food(外卖,当前唯一接通)/ ecom(电商)/ coupon(领券)。预留扩展。
+    business_type: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="food", index=True
+    )
+    # pricebot 侧 trace_id:关联调试落盘 + 幂等去重键
+    trace_id: Mapped[str] = mapped_column(String(64), nullable=False)
+
+    # ===== 源平台(发起比价的那家)=====
+    source_platform_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    source_platform_name: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    source_package: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    source_price_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # ===== 最优结果(全平台最便宜的一家,= comparison_results 里 rank=1)=====
+    best_platform_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    best_platform_name: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    best_price_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 源价 - 最优价(可为 0 / 负:源平台本来就最便宜时没省到)
+    saved_amount_cents: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 源平台就是最便宜的一家(= 这次没省到钱)
+    is_source_best: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+
+    # ===== 订单概要 =====
+    store_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    total_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    skipped_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+
+    # success(拿到有效对比)/ failed(出错或没采到目标价)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="success")
+    # done 帧 information 文案。成功:"在美团找到同店,到手价 ¥X…";
+    # 失败:具体原因(如"美团、京东外卖均未找到该商品")。前端在比价失败时当原因展示。
+    information: Mapped[str | None] = mapped_column(String(256), nullable=True)
+
+    # ===== 明细(JSON,越详细越好)=====
+    # 下单菜品 [{name, qty, specs?}]
+    items: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 逐平台对比 [{platform_id, platform_name, package, price, is_source, rank}](price 单位:元,原样存)
+    comparison_results: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 目标平台未找到、跳过的菜名
+    skipped_dish_names: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 客户端上报的原始 payload(calibration + done.params 全量),未来取数兜底
+    raw_payload: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<ComparisonRecord id={self.id} user_id={self.user_id} "
+            f"trace_id={self.trace_id} status={self.status}>"
+        )

app/models/comparison_milestone.py

@@ -0,0 +1,36 @@
+"""比价战绩里程碑领取记录表。
+
+「记录比价战绩」每档(第 1~6 次)只能领一次,领取后写一行,(user_id, milestone)
+唯一,防止重复领奖。解锁进度由 comparison_record 里 status='success' 的条数决定,
+不存进度本身——只在这里记"哪几档已领"。仿 user_task 的一次性领取模型。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Integer, UniqueConstraint, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class ComparisonMilestoneClaim(Base):
+    __tablename__ = "comparison_milestone_claim"
+    __table_args__ = (
+        UniqueConstraint("user_id", "milestone", name="uq_compare_milestone_user"),
+    )
+
+    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
+    )
+    # 档位序号(1-based),见 app.core.rewards.RECORD_MILESTONES
+    milestone: Mapped[int] = mapped_column(Integer, nullable=False)
+    coin_awarded: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+
+    claimed_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<ComparisonMilestoneClaim user_id={self.user_id} m={self.milestone}>"

app/repositories/comparison.py

@@ -0,0 +1,147 @@
+"""比价记录 CRUD:上报 upsert(按 user_id+trace_id 幂等) + 派生字段 + 明细分页。
+
+派生逻辑:best_* / saved_amount_cents / is_source_best 全部从 comparison_results 算出
+(协议保证已按 price 升序、rank=1 最便宜),客户端不用自己算、也不可信它算。
+"""
+from __future__ import annotations
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.comparison import ComparisonRecord
+from app.schemas.compare_record import ComparisonRecordIn
+
+
+def _yuan_to_cents(yuan: float | None) -> int | None:
+    """元(float)→ 分(int)。None 透传。"""
+    if yuan is None:
+        return None
+    return round(yuan * 100)
+
+
+def _derive(payload: ComparisonRecordIn) -> dict:
+    """从上报 payload 派生结构化列(best/saved/is_source_best/status)。"""
+    results = payload.comparison_results
+
+    # 最优 = rank 最小的一条;协议已升序,但不信顺序,显式按 rank/price 兜底取最小价。
+    best = None
+    priced = [r for r in results if r.price is not None]
+    if priced:
+        best = min(
+            priced,
+            key=lambda r: (r.rank if r.rank is not None else 10**9, r.price),
+        )
+
+    source_price_cents = _yuan_to_cents(payload.source_price)
+    if source_price_cents is None:
+        # 源价没单独给,从 comparison_results 里的 is_source 行兜底
+        src_row = next((r for r in results if r.is_source and r.price is not None), None)
+        if src_row is not None:
+            source_price_cents = _yuan_to_cents(src_row.price)
+
+    best_price_cents = _yuan_to_cents(best.price) if best else None
+
+    saved_amount_cents = None
+    if source_price_cents is not None and best_price_cents is not None:
+        saved_amount_cents = source_price_cents - best_price_cents
+
+    is_source_best = best.is_source if best is not None else None
+
+    # status:客户端显式给了就用;否则有"非源且有价"的结果=success,否则 failed
+    status = payload.status
+    if status is None:
+        has_valid_target = any(
+            (not r.is_source) and r.price is not None for r in results
+        )
+        status = "success" if has_valid_target else "failed"
+
+    return {
+        "source_price_cents": source_price_cents,
+        "best_platform_id": best.platform_id if best else None,
+        "best_platform_name": best.platform_name if best else None,
+        "best_price_cents": best_price_cents,
+        "saved_amount_cents": saved_amount_cents,
+        "is_source_best": is_source_best,
+        "status": status,
+    }
+
+
+def upsert_record(
+    db: Session, *, user_id: int, payload: ComparisonRecordIn
+) -> ComparisonRecord:
+    """按 (user_id, trace_id) 幂等写入:已存在则覆盖(更完整的重试上报胜出),否则新建。"""
+    derived = _derive(payload)
+    fields = dict(
+        device_id=payload.device_id,
+        business_type=payload.business_type,
+        store_name=payload.store_name,
+        source_platform_id=payload.source_platform_id,
+        source_platform_name=payload.source_platform_name,
+        source_package=payload.source_package,
+        information=payload.information,
+        total_dish_count=payload.total_dish_count,
+        skipped_dish_count=payload.skipped_dish_count,
+        items=[it.model_dump(exclude_none=True) for it in payload.items],
+        comparison_results=[r.model_dump() for r in payload.comparison_results],
+        skipped_dish_names=list(payload.skipped_dish_names),
+        raw_payload=payload.model_dump(),
+        **derived,
+    )
+
+    existing = db.execute(
+        select(ComparisonRecord).where(
+            ComparisonRecord.user_id == user_id,
+            ComparisonRecord.trace_id == payload.trace_id,
+        )
+    ).scalar_one_or_none()
+
+    if existing is not None:
+        for k, v in fields.items():
+            setattr(existing, k, v)
+        db.commit()
+        db.refresh(existing)
+        return existing
+
+    rec = ComparisonRecord(user_id=user_id, trace_id=payload.trace_id, **fields)
+    db.add(rec)
+    db.commit()
+    db.refresh(rec)
+    return rec
+
+
+def list_records(
+    db: Session,
+    user_id: int,
+    *,
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[ComparisonRecord], int | None]:
+    """比价记录分页(按 id 倒序,游标式)。"""
+    stmt = select(ComparisonRecord).where(ComparisonRecord.user_id == user_id)
+    if cursor is not None:
+        stmt = stmt.where(ComparisonRecord.id < cursor)
+    stmt = stmt.order_by(ComparisonRecord.id.desc()).limit(limit)
+
+    items = list(db.execute(stmt).scalars().all())
+    next_cursor = items[-1].id if len(items) == limit else None
+    return items, next_cursor
+
+
+def count_success(db: Session, user_id: int) -> int:
+    """该用户成功比价(status='success')的条数。比价战绩里程碑的解锁进度源。"""
+    return db.execute(
+        select(func.count(ComparisonRecord.id)).where(
+            ComparisonRecord.user_id == user_id,
+            ComparisonRecord.status == "success",
+        )
+    ).scalar_one()
+
+
+def get_record(db: Session, user_id: int, record_id: int) -> ComparisonRecord | None:
+    """取单条(限本人,避免越权读他人记录)。"""
+    return db.execute(
+        select(ComparisonRecord).where(
+            ComparisonRecord.id == record_id,
+            ComparisonRecord.user_id == user_id,
+        )
+    ).scalar_one_or_none()

app/repositories/comparison_milestone.py

@@ -0,0 +1,116 @@
+"""比价战绩里程碑 CRUD:进度查询 + 逐档领奖。
+
+进度 = comparison_record 里 status='success' 的条数(crud_compare.count_success)。
+第 N 档在"成功次数 >= N"时解锁;每档领一次,写 comparison_milestone_claim 去重 +
+grant_coins,同一事务 commit(领奖记录与加金币原子化)。仿一次性任务 (task.py)。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.core.rewards import (
+    RECORD_MILESTONE_COUNT,
+    RECORD_MILESTONES,
+    record_milestone_reward,
+)
+from app.models.comparison_milestone import ComparisonMilestoneClaim
+from app.repositories import comparison as crud_compare
+from app.repositories import wallet as crud_wallet
+
+
+class UnknownMilestoneError(Exception):
+    """档位序号越界(不在 1..RECORD_MILESTONE_COUNT)。"""
+
+
+class MilestoneLockedError(Exception):
+    """该档还没解锁(成功比价次数不够)。"""
+
+
+class AlreadyClaimedError(Exception):
+    """该档已经领过了。"""
+
+
+@dataclass
+class MilestoneState:
+    milestone: int  # 1-based 档位序号
+    coin: int
+    state: str  # claimed / active / locked
+
+
+@dataclass
+class MilestoneStatus:
+    success_count: int  # 累计成功比价次数(解锁进度)
+    claimable_count: int  # 当前可领(active)档数
+    milestones: list[MilestoneState]
+
+
+def _claimed_set(db: Session, user_id: int) -> set[int]:
+    rows = db.execute(
+        select(ComparisonMilestoneClaim.milestone).where(
+            ComparisonMilestoneClaim.user_id == user_id
+        )
+    ).scalars().all()
+    return set(rows)
+
+
+def get_status(db: Session, user_id: int) -> MilestoneStatus:
+    """各档领取状态:已领=claimed,已解锁未领=active(可领),未解锁=locked。"""
+    success_count = crud_compare.count_success(db, user_id)
+    claimed = _claimed_set(db, user_id)
+
+    milestones: list[MilestoneState] = []
+    claimable = 0
+    for m in range(1, RECORD_MILESTONE_COUNT + 1):
+        if m in claimed:
+            state = "claimed"
+        elif success_count >= m:
+            state = "active"
+            claimable += 1
+        else:
+            state = "locked"
+        milestones.append(
+            MilestoneState(milestone=m, coin=RECORD_MILESTONES[m - 1], state=state)
+        )
+
+    return MilestoneStatus(
+        success_count=success_count,
+        claimable_count=claimable,
+        milestones=milestones,
+    )
+
+
+def claim(db: Session, user_id: int, milestone: int) -> tuple[int, int]:
+    """领取第 milestone 档奖励。返回 (发放金币, 领奖后余额)。
+
+    越界抛 UnknownMilestoneError;未解锁抛 MilestoneLockedError;重复领抛 AlreadyClaimedError。
+    """
+    if milestone < 1 or milestone > RECORD_MILESTONE_COUNT:
+        raise UnknownMilestoneError
+
+    existing = db.execute(
+        select(ComparisonMilestoneClaim).where(
+            ComparisonMilestoneClaim.user_id == user_id,
+            ComparisonMilestoneClaim.milestone == milestone,
+        )
+    ).scalar_one_or_none()
+    if existing is not None:
+        raise AlreadyClaimedError
+
+    # 解锁校验:成功比价次数必须 >= 档位序号
+    if crud_compare.count_success(db, user_id) < milestone:
+        raise MilestoneLockedError
+
+    coin = record_milestone_reward(milestone)
+    db.add(
+        ComparisonMilestoneClaim(
+            user_id=user_id, milestone=milestone, coin_awarded=coin
+        )
+    )
+    acc, _ = crud_wallet.grant_coins(
+        db, user_id, coin, biz_type="compare_milestone", ref_id=str(milestone)
+    )
+    db.commit()
+    return coin, acc.coin_balance

app/schemas/compare_record.py

@@ -0,0 +1,125 @@
+"""比价记录上报 / 读取 schemas。
+
+约定同 welfare:字段 snake_case、金额存整数(分)、时间 ISO 8601。
+
+上报请求(ComparisonRecordIn)的字段刻意对齐 pricebot 协议
+(docs/main/02_api_protocol.md 的 calibration + done.params.comparison_results),
+让客户端把 Phase1 的 calibration 和 done 帧的 params 字段**零翻译**直接映射上来,
+server 端负责拆成结构化列(best_*/saved/is_source_best 由 comparison_results 派生)。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+# ===== 上报请求 =====
+
+class ComparisonItemIn(BaseModel):
+    """下单菜品(来自 calibration.items)。"""
+
+    name: str
+    qty: int = 1
+    specs: list[str] | None = None
+
+
+class ComparisonResultIn(BaseModel):
+    """逐平台对比项(来自 done.params.comparison_results)。price 单位:元。"""
+
+    platform_id: str | None = None
+    platform_name: str | None = None
+    package: str | None = None
+    price: float | None = None
+    is_source: bool = False
+    rank: int | None = None
+
+
+class ComparisonRecordIn(BaseModel):
+    # 幂等键:同一用户同一 trace_id 重复上报只保留一条(覆盖)
+    trace_id: str = Field(..., min_length=1, description="pricebot 侧 trace_id")
+    business_type: str = Field("food", description="food / ecom / coupon")
+    device_id: str | None = None
+
+    # 源平台(来自 calibration)
+    store_name: str | None = Field(None, description="店铺名(外卖)")
+    source_platform_id: str | None = None
+    source_platform_name: str | None = None
+    source_package: str | None = None
+    source_price: float | None = Field(None, description="源平台到手价(元)")
+
+    # 明细
+    items: list[ComparisonItemIn] = Field(default_factory=list)
+    comparison_results: list[ComparisonResultIn] = Field(default_factory=list)
+    skipped_dish_count: int | None = None
+    skipped_dish_names: list[str] = Field(default_factory=list)
+    total_dish_count: int | None = None
+
+    information: str | None = Field(None, description="done 帧文案,留存备查")
+    # 不传则服务端按 comparison_results 派生(有非源有效价=success,否则 failed)
+    status: str | None = Field(None, description="success / failed,可不传由服务端派生")
+
+
+# ===== 读取出参 =====
+
+class ComparisonRecordOut(BaseModel):
+    """列表项:结构化概要字段(不含 raw_payload,减小列表 payload)。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    business_type: str
+    trace_id: str
+    source_platform_id: str | None = None
+    source_platform_name: str | None = None
+    source_package: str | None = None
+    source_price_cents: int | None = None
+    best_platform_id: str | None = None
+    best_platform_name: str | None = None
+    best_price_cents: int | None = None
+    saved_amount_cents: int | None = None
+    is_source_best: bool | None = None
+    store_name: str | None = None
+    total_dish_count: int | None = None
+    skipped_dish_count: int | None = None
+    status: str
+    information: str | None = None
+    items: list = []
+    comparison_results: list = []
+    skipped_dish_names: list = []
+    created_at: datetime
+
+
+class ComparisonRecordDetailOut(ComparisonRecordOut):
+    """详情:在概要之上额外带 raw_payload 全量。"""
+
+    raw_payload: dict | None = None
+
+
+class ComparisonRecordPage(BaseModel):
+    items: list[ComparisonRecordOut]
+    next_cursor: int | None = Field(None, description="下一页游标(末条 id);为空表示到底")
+
+
+class ComparisonRecordCreatedOut(BaseModel):
+    id: int = Field(..., description="写入(或已存在)的记录 id")
+
+
+# ===== 比价战绩里程碑(福利页「记录比价战绩」)=====
+
+class MilestoneStateOut(BaseModel):
+    milestone: int = Field(..., description="档位序号 1-based(= 解锁所需的成功比价次数)")
+    coin: int = Field(..., description="该档奖励金币")
+    state: str = Field(..., description="claimed(已领) / active(可领) / locked(未解锁)")
+
+
+class MilestoneStatusOut(BaseModel):
+    success_count: int = Field(..., description="累计成功比价次数(解锁进度)")
+    claimable_count: int = Field(..., description="当前可领(active)档数")
+    milestones: list[MilestoneStateOut]
+
+
+class MilestoneClaimResultOut(BaseModel):
+    milestone: int = Field(..., description="本次领取的档位序号")
+    coin_awarded: int = Field(..., description="本次发放金币")
+    coin_balance: int = Field(..., description="领奖后金币余额")