feat(ad): eCPM 上报接口 + 冷却策略解耦纯函数 + savings JSONB 跨库修复 (#8)

- 新增 POST /api/v1/ad/ecpm-report:激励视频展示后客户端上报本次 eCPM,落 ad_ecpm_record 做内部收益统计(model/repository/schema/alembic 迁移 + 接口文档)
- 看广告冷却策略抽到 app/core/ad_cooldown.py 纯函数;ad_reward.today_status 只取数据,换策略只改这一处
- savings.dishes 改 JSON().with_variant(JSONB,"postgresql"):SQLite 无 visit_JSONB 会让 create_all 编译崩,修复后测试套件恢复

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

---------

Co-authored-by: OuYingJun1024 <1034284404@qq.com>
Reviewed-on: #8
Co-authored-by: ouzhou <ouzhou@wonderable.ai>
Co-committed-by: ouzhou <ouzhou@wonderable.ai>

docs/api/README.md

@@ -3,7 +3,7 @@
 > Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
 > 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
-> 最后更新:2026-05-31
+> 最后更新:2026-05-31（+ 比价战绩里程碑 12d/12e）
 > 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
 
 ---
@@ -26,6 +26,13 @@
 | **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend） |||
 | 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./compare-intent-recognize.md) |
 | 13 | `POST /api/v1/price/step` | 无 | [详情](./compare-price-step.md) |
+| **比价记录**（前缀 `/api/v1/compare`；按用户落库，**鉴权**，区别于上面不鉴权的透传） |||
+| 12a | `POST /api/v1/compare/record` | Bearer | [详情](./compare-record-report.md) |
+| 12b | `GET /api/v1/compare/records` | Bearer | [详情](./compare-records.md) |
+| 12c | `GET /api/v1/compare/records/{id}` | Bearer | [详情](./compare-record-detail.md) |
+| **比价战绩里程碑**（前缀 `/api/v1/compare`；福利页「记录比价战绩」,按成功比价数解锁逐档发金币） |||
+| 12d | `GET /api/v1/compare/milestones` | Bearer | [详情](./compare-milestones.md) |
+| 12e | `POST /api/v1/compare/milestones/{milestone}/claim` | Bearer | [详情](./compare-milestone-claim.md) |
 | **钱包 / 我的资产**（前缀 `/api/v1/wallet`） |||
 | 14 | `GET /api/v1/wallet/account` | Bearer | [详情](./wallet-account.md) |
 | 15 | `GET /api/v1/wallet/coin-transactions` | Bearer | [详情](./wallet-coin-transactions.md) |
@@ -52,6 +59,7 @@
 | 32 | `GET /api/v1/ad/pangle-callback` | 验签 | [详情](./ad-pangle-callback.md) |
 | 33 | `GET /api/v1/ad/reward-status` | Bearer | [详情](./ad-reward-status.md) |
 | 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad-test-grant.md) |
+| 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad-ecpm-report.md) |
 | **用户资料**（前缀 `/api/v1/user`） |||
 | 35 | `PATCH /api/v1/user/profile` | Bearer | [详情](./user-profile.md) |
 | 36 | `POST /api/v1/user/avatar` | Bearer | [详情](./user-avatar.md) |

docs/api/ad-ecpm-report.md

@@ -0,0 +1,36 @@
+# POST /api/v1/ad/ecpm-report — 上报本次广告展示的 eCPM（内部收益统计）
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+## 入参
+请求体:`EcpmReportIn`
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `ad_type` | str | 是 | 广告类型:`reward_video`(激励视频) / `draw`(Draw 信息流) 等 |
+| `ecpm` | str | 是 | 穿山甲 `getShowEcpm().getEcpm()` 原始字符串,**单位待确认(分/元)**,原样上报 |
+| `adn` | str\|null | 否 | 实际投放 ADN(`getSdkName`),如 `pangle` |
+| `slot_id` | str\|null | 否 | 实际展示代码位(底层 mediation rit,非客户端配置位) |
+
+`user_id` 不在 body 里——由 JWT 取(Bearer),防伪造。
+
+## 出参
+响应 `200`:`EcpmReportOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ok` | bool | 落库即 `true` |
+
+## 说明
+客户端在广告**展示后**(`onAdShow` 读 `getShowEcpm()`)调用,把本次展示的 eCPM 落库做**内部收益统计/对账**。
+
+- **best-effort**:客户端 fire-and-forget,丢一两条不影响业务;穿山甲后台报表是结算权威兜底。
+- 落 `ad_ecpm_record` 表,`report_date` 用北京时间当天,供「按用户/按天聚合」对账。
+- **与发奖是两条独立流**:发奖走 [ad-pangle-callback](./ad-pangle-callback.md)(穿山甲 S2S,有 `trans_id`、无 ecpm),本接口客户端上报(有 ecpm、无 `trans_id`)。两者无公共键,**不逐条一一对应**,只做按用户/按天聚合口径。
+- eCPM 是**每千次展示预估**,单条展示预估收益 ≈ `ecpm / 1000`,且为客户端预估口径,非最终结算。
+- ⚠️ eCPM **单位(分/元)截至 2026-05-31 未最终确认**,故 `ecpm_raw` 原样存字符串;确认后再加一列解析好的数值。
+- 限流:同 IP 120 次/分钟。
+
+## 相关
+- [ad-pangle-callback](./ad-pangle-callback.md) — 穿山甲 S2S 发奖回调
+- [ad-reward-status](./ad-reward-status.md) — 今日看广告发奖进度

docs/api/compare-milestone-claim.md

@@ -0,0 +1,33 @@
+# POST /api/v1/compare/milestones/{milestone}/claim — 领取比价战绩里程碑奖励
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+领取某一档(第 `milestone` 次)的金币奖励,真实入账金币钱包。领取记录写
+`comparison_milestone_claim`((user_id, milestone) 唯一)+ `grant_coins` 同一事务原子提交,
+**每档只能领一次**。进度口径见 [milestones 进度接口](./compare-milestones.md)。
+
+## 入参
+- 路径参数 `milestone`(int):档位序号,1..6(= `RECORD_MILESTONES` 长度)。
+
+## 出参
+响应 `200`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `milestone` | int | 本次领取的档位序号 |
+| `coin_awarded` | int | 本次发放金币 |
+| `coin_balance` | int | 领奖后金币余额 |
+
+```json
+{ "milestone": 1, "coin_awarded": 120, "coin_balance": 29087 }
+```
+
+## 错误
+- `401` 未鉴权
+- `404` 档位越界(`unknown milestone`,milestone < 1 或 > 档位总数)
+- `409` 该档还没解锁(`milestone locked`,成功比价次数 < milestone)
+- `409` 该档已领过(`milestone already claimed`)
+
+## 说明
+- 领取金币后,客户端应刷新钱包余额([`GET /api/v1/wallet/account`](./wallet-account.md))与本档状态。
+- 幂等:重复领同一档返回 409 且**不会重复发金币**(唯一约束 + 领取前查重)。

docs/api/compare-milestones.md

@@ -0,0 +1,51 @@
+# GET /api/v1/compare/milestones — 比价战绩里程碑进度
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+福利页「记录比价战绩」的数据源。返回各档(第 1~6 次)解锁/领取状态。
+
+**解锁进度** = 当前用户 `comparison_record` 里 `status='success'` 的条数(只算成功比价,失败的不计入)。第 N 档在「成功比价次数 ≥ N」时解锁;每档领一次(领取见 [claim 接口](./compare-milestone-claim.md))。
+
+档位金额是**产品规则**,定义在后端 `app/core/rewards.py` 的 `RECORD_MILESTONES`(当前 `120/180/300/500/800/1200`),客户端**不要写死**,以本接口返回为准。
+
+## 入参
+无(用户身份取自 Bearer token)。
+
+## 出参
+响应 `200`：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `success_count` | int | 累计成功比价次数(解锁进度) |
+| `claimable_count` | int | 当前可领(state=active)的档数 |
+| `milestones` | Milestone[] | 各档状态,按 milestone 升序 |
+
+**Milestone**
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `milestone` | int | 档位序号(1-based),= 解锁所需的成功比价次数 |
+| `coin` | int | 该档奖励金币 |
+| `state` | string | `claimed`(已领) / `active`(已解锁可领) / `locked`(未解锁) |
+
+```json
+{
+  "success_count": 2,
+  "claimable_count": 1,
+  "milestones": [
+    {"milestone": 1, "coin": 120, "state": "claimed"},
+    {"milestone": 2, "coin": 180, "state": "active"},
+    {"milestone": 3, "coin": 300, "state": "locked"},
+    {"milestone": 4, "coin": 500, "state": "locked"},
+    {"milestone": 5, "coin": 800, "state": "locked"},
+    {"milestone": 6, "coin": 1200, "state": "locked"}
+  ]
+}
+```
+
+## 错误
+- `401` 未鉴权
+
+## 说明
+- 同时可有多档处于 `active`(如累计 3 次却一档没领,则前 3 档都可领),逐档调 claim。
+- 进度只增不减:领取不消耗成功次数,只是把对应档从 active→claimed。

docs/api/compare-record-detail.md

@@ -0,0 +1,25 @@
+# GET /api/v1/compare/records/{record_id} — 比价记录详情
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+单条比价记录详情，在列表项基础上额外带 `raw_payload`（客户端上报的原始全量），供未来 UI 展示任意细节。
+
+## 入参（path）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `record_id` | int | 记录 id |
+
+## 出参
+响应 `200`：**ComparisonRecordDetailOut** = [ComparisonRecordOut](./compare-records.md#出参) 全部字段 + 下列：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `raw_payload` | object \| null | 客户端上报的原始 body 全量（calibration + done.params） |
+
+## 错误
+- `401` 未鉴权
+- `404` 记录不存在，或不属于当前用户（限本人，避免越权读他人记录）
+
+## 说明
+`404` 同时覆盖「id 不存在」和「id 属于他人」两种情况——不区分以免泄露他人记录是否存在。

docs/api/compare-record-report.md

@@ -0,0 +1,57 @@
+# POST /api/v1/compare/record — 上报一次比价结果(幂等)
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+比价 `done` 帧后,客户端用**带 JWT 的通道**上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。
+
+> ⚠️ 与不鉴权的透传端点 [`/api/v1/price/step`](./compare-price-step.md) 不同：那是转发壳，本接口按用户维度落库，**必须鉴权**。
+> 本轮只做 server 端；客户端在 done 帧后调本接口的改动另起一轮（见 [待办与技术债.md](../待办与技术债.md) P1）。
+
+## 入参（JSON body）
+
+字段刻意对齐 pricebot 协议（[02_api_protocol.md](../../../pricebot-backend/docs/main/02_api_protocol.md) 的 `calibration` + `done.params`），客户端把 Phase1 的 calibration 和 done 帧 params **零翻译**映射上来即可。
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `trace_id` | string | ✅ | — | pricebot 侧 trace_id。**幂等键**：同用户同 trace_id 重复上报覆盖、返回同一 id |
+| `business_type` | string | ❌ | `food` | `food`(外卖,当前唯一接通) / `ecom`(电商) / `coupon`(领券) |
+| `device_id` | string \| null | ❌ | null | 设备号 |
+| `store_name` | string \| null | ❌ | null | 店铺名（外卖,来自 calibration.result） |
+| `source_platform_id` | string \| null | ❌ | null | 源平台代号，如 `taobao_flash` |
+| `source_platform_name` | string \| null | ❌ | null | 源平台中文名 |
+| `source_package` | string \| null | ❌ | null | 源平台 Android 包名 |
+| `source_price` | float \| null | ❌ | null | 源平台到手价（**元**） |
+| `items` | Item[] | ❌ | [] | 下单菜品，`{name, qty, specs?}` |
+| `comparison_results` | Result[] | ❌ | [] | 逐平台对比，见下表（price 单位**元**） |
+| `skipped_dish_count` | int \| null | ❌ | null | 目标平台未找到、跳过的菜品数 |
+| `skipped_dish_names` | string[] | ❌ | [] | 被跳过的菜名 |
+| `total_dish_count` | int \| null | ❌ | null | 原始菜品总数 |
+| `information` | string \| null | ❌ | null | done 帧文案(成功摘要 / 失败具体原因),持久化为列并在列表/详情返回,前端失败时当原因展示 |
+| `status` | string \| null | ❌ | null | `success` / `failed`。**不传则服务端派生** |
+
+**Item**：`{ name: string, qty: int=1, specs: string[]\|null }`
+
+**Result（comparison_results 元素）**：`{ platform_id, platform_name, package, price(元,float\|null), is_source(bool), rank(int\|null) }`
+
+## 服务端派生（客户端不用算）
+
+从 `comparison_results` 派生并落结构化列：
+
+- `best_*`：取最便宜的一家（按 `rank` 升序、再按 `price`），写 `best_platform_id/name/best_price_cents`
+- `source_price_cents`：优先用 `source_price`，缺失则取 `comparison_results` 里 `is_source=true` 行的价
+- `saved_amount_cents` = `源价 − 最优价`（可为 0 / 负：源平台本来就最便宜）
+- `is_source_best`：最便宜的一家是否为源平台（= 这次没省到）
+- `status`（未显式传时）：存在「非源且有价」的结果 → `success`，否则 → `failed`
+- 金额一律 `round(元 × 100)` 存**分**
+
+`comparison_results` / `items` / `skipped_dish_names` 原样存 JSON；完整上报 body 另存 `raw_payload`（详情接口可取回）。
+
+## 出参
+响应 `200`：`{ "id": int }`（写入或已存在记录的 id）
+
+## 错误
+- `401` 未鉴权
+- `422` 缺 `trace_id` 或字段类型不符
+
+## 说明
+失败的比价（done 帧只有源/空 comparison_results）也会落一条 `status=failed`——「越详细越好」，是否在 UI 展示由前端过滤。

docs/api/compare-records.md

@@ -0,0 +1,47 @@
+# GET /api/v1/compare/records — 比价记录列表(游标分页)
+
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+
+「我的比价记录」列表页数据源。按 `id` 倒序（最新在前）。
+
+## 入参（query）
+
+| 字段 | 类型 | 必填 | 默认 | 说明 |
+|---|---|---|---|---|
+| `limit` | int | ❌ | 20 | 1–100 |
+| `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+
+## 出参
+响应 `200`：`{ items: ComparisonRecordOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+
+**ComparisonRecordOut**（列表项，不含 `raw_payload`，减小 payload）
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `id` | int | 记录 id（也是游标） |
+| `business_type` | string | `food` / `ecom` / `coupon` |
+| `trace_id` | string | pricebot trace_id |
+| `source_platform_id` | string \| null | 源平台代号 |
+| `source_platform_name` | string \| null | 源平台中文名 |
+| `source_package` | string \| null | 源平台包名 |
+| `source_price_cents` | int \| null | 源平台到手价（分） |
+| `best_platform_id` | string \| null | 最优平台代号 |
+| `best_platform_name` | string \| null | 最优平台中文名 |
+| `best_price_cents` | int \| null | 最优价（分） |
+| `saved_amount_cents` | int \| null | 省下（分，可 0/负） |
+| `is_source_best` | bool \| null | 源平台是否最便宜（= 没省到） |
+| `store_name` | string \| null | 店铺名 |
+| `total_dish_count` | int \| null | 菜品总数 |
+| `skipped_dish_count` | int \| null | 跳过菜品数 |
+| `status` | string | `success` / `failed` |
+| `information` | string \| null | done 帧文案。成功:"在美团找到同店,到手价 ¥X…";失败:具体原因(如"美团、京东外卖均未找到该商品"),前端在 `status=failed` 时当原因展示 |
+| `items` | object[] | 下单菜品 `{name, qty, specs?}` |
+| `comparison_results` | object[] | 逐平台对比（price 单位元，已按 rank 升序） |
+| `skipped_dish_names` | string[] | 被跳过的菜名 |
+| `created_at` | datetime | 时间 |
+
+## 错误
+- `401` 未鉴权
+
+## 说明
+只返回当前登录用户自己的记录。需要单条全量（含 `raw_payload`）走 [详情接口](./compare-record-detail.md)。

docs/database/README.md

@@ -0,0 +1,37 @@
+# 傻瓜比价 App 后端 — 数据库表文档(索引)
+
+> 数据库:SQLite 起步(`data/app.db`),生产可切 PostgreSQL(改 `DATABASE_URL`)。
+> ORM:SQLAlchemy 2.0(`app/models/`),迁移:Alembic(`alembic/versions/`,`render_as_batch` 兼容 SQLite)。
+> 金额字段一律存**整数**:金币=个数,现金=**分**(`*_cents`)。时间列 `DateTime(timezone=True)`。
+> 最后更新:2026-05-31
+
+---
+
+## 表总览
+
+| 表 | 用途 | 模型 | 关联模块 | 文档 |
+|---|---|---|---|---|
+| `user` | 用户(登录主体) | `models/user.py` | 登录/鉴权 | [详情](./user.md) |
+| `coin_account` | 金币+现金余额快照(一用户一行) | `models/wallet.py` | 钱包 | [详情](./coin_account.md) |
+| `coin_transaction` | 金币流水账本 | `models/wallet.py` | 钱包 | [详情](./coin_transaction.md) |
+| `cash_transaction` | 现金流水账本(分) | `models/wallet.py` | 钱包/提现 | [详情](./cash_transaction.md) |
+| `withdraw_order` | 提现单(现金→微信零钱) | `models/wallet.py` | 提现 | [详情](./withdraw_order.md) |
+| `signin_record` | 签到记录(7 天循环) | `models/signin.py` | 签到 | [详情](./signin_record.md) |
+| `user_task` | 一次性任务领取去重 | `models/task.py` | 任务 | [详情](./user_task.md) |
+| `savings_record` | 省钱记录(profile 省钱战绩源) | `models/savings.py` | 省钱 | [详情](./savings_record.md) |
+| `ad_reward_record` | 看激励视频发奖记录(S2S 回调) | `models/ad_reward.py` | 看广告发奖 | [详情](./ad_reward_record.md) |
+| `ad_ecpm_record` | 广告展示 eCPM 上报(收益对账) | `models/ad_ecpm.py` | 看广告 | [详情](./ad_ecpm_record.md) |
+| `feedback` | 用户帮助与反馈 | `models/feedback.py` | 反馈 | [详情](./feedback.md) |
+| `comparison_record` | 比价记录(每次比价完整明细) | `models/comparison.py` | 比价记录 | [详情](./comparison_record.md) |
+| `comparison_milestone_claim` | 比价战绩里程碑领取记录 | `models/comparison_milestone.py` | 比价记录/福利 | [详情](./comparison_milestone_claim.md) |
+
+---
+
+## 通用约定
+
+- **主键**:`id` Integer autoincrement(`coin_account` 例外:`user_id` 既是主键也是外键,一用户一行)。
+- **外键**:所有用户维度表 `user_id` → `user.id`,且建 index。
+- **金额**:整数;金币计数,现金/价格存「分」(`*_cents`)。
+- **时间**:`created_at` 等用 `DateTime(timezone=True)` + `server_default=func.now()`;业务"今天"按**北京时间**(见 `core/rewards.cn_today`),跨天计数用「日期串」列(如 `reward_date`/`report_date`)等值查,不在 SQL 里做跨时区 date 比较(SQLite 不可靠)。
+- **JSON 列**:用 `JSON().with_variant(JSONB(), "postgresql")` —— PG 上 JSONB(可建 GIN 索引),SQLite 退化为通用 JSON(否则 `create_all` 编译报错)。
+- **迁移**:改表必写 alembic 迁移并保持单 head;改表/建表同时更新本目录对应文档(一表一文件)。

docs/database/ad_ecpm_record.md

@@ -0,0 +1,26 @@
+# ad_ecpm_record — 广告展示 eCPM 上报(收益对账)
+
+> 模型 `app/models/ad_ecpm.py` | 关联接口 [ad-ecpm-report](../api/ad-ecpm-report.md) | [← 表索引](./README.md)
+
+每条 = 客户端一次广告展示(`onAdShow`)后读到的 eCPM。与发奖记录 `ad_reward_record` 是**两条独立数据流**(发奖走 S2S 有 trans_id 无 ecpm;eCPM 走客户端有 ecpm 无 trans_id),无公共键,只用于**按用户/按天聚合**收益对账,不做逐条精确关联。穿山甲后台报表才是结算权威。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `ad_type` | String(32) | NOT NULL | 广告类型:`reward_video`(激励视频)/ `draw`(Draw 信息流)等 |
+| `adn` | String(32) | nullable | 实际投放 ADN(`getSdkName`,如 pangle/gdt) |
+| `slot_id` | String(64) | nullable | 实际展示代码位(底层 mediation rit) |
+| `ecpm_raw` | String(32) | NOT NULL | 客户端上报的 eCPM 原始串(单位待确认,原样存) |
+| `report_date` | String(10) | index, NOT NULL | 北京时间日期串 `YYYY-MM-DD`,按它做按天聚合 |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`report_date`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- ⚠️ `ecpm_raw` 单位(分/元)截至 2026-05-31 未最终确认;确认后再加一列解析好的数值,在此之前对账按"待定单位"处理。

docs/database/ad_reward_record.md

@@ -0,0 +1,28 @@
+# ad_reward_record — 看激励视频发奖记录(S2S 回调)
+
+> 模型 `app/models/ad_reward.py` | 关联接口 [ad-pangle-callback](../api/ad-pangle-callback.md) / [ad-reward-status](../api/ad-reward-status.md) | [← 表索引](./README.md)
+
+每条 = 穿山甲一次发奖回调。`trans_id` 唯一做幂等键(穿山甲会重试,同号只发一次)。`reward_date`(北京时间日期串)给"每日上限"计数用,按日期串等值查。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `trans_id` | String(64) | UNIQUE, index, NOT NULL | 穿山甲交易号(幂等键) |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户(回调 media_extra 带回) |
+| `coin` | Integer | NOT NULL, default 0 | 实发金币(capped 时为 0) |
+| `status` | String(16) | NOT NULL, default `granted` | `granted`(已发)/ `capped`(当日超限未发) |
+| `reward_date` | String(10) | index, NOT NULL | 北京时间日期串 `YYYY-MM-DD`,按它统计当日次数 |
+| `reward_name` | String(64) | nullable | 穿山甲上报奖励名(参考,不作发奖依据) |
+| `raw` | String(1024) | nullable | 回调原始参数(审计排查) |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;UNIQUE + index: `trans_id`;index: `user_id`、`reward_date`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 三道闸:验签不过 403 → `trans_id` 唯一幂等(并发 catch IntegrityError)→ 当日次数 ≥ `DAILY_AD_REWARD_LIMIT` 记 `capped` 不发币。
+- 发币复用 `grant_coins(biz_type='ad_reward', ref_id=trans_id)`。

docs/database/cash_transaction.md

@@ -0,0 +1,26 @@
+# cash_transaction — 现金流水账本(分)
+
+> 模型 `app/models/wallet.py` | 关联接口 [wallet-cash-transactions](../api/wallet-cash-transactions.md) | [← 表索引](./README.md)
+
+现金每次变动一笔流水(单位:分)。金币兑现金、提现、提现退款都记这里。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `amount_cents` | Integer | NOT NULL | 正=入账(兑入),负=出账(提现) |
+| `balance_after_cents` | Integer | NOT NULL | 本笔变动后现金余额(分) |
+| `biz_type` | String(32) | NOT NULL | `exchange_in`(兑入)/ `withdraw`(提现出账)/ `withdraw_refund`(提现退回) |
+| `ref_id` | String(64) | nullable | 关联业务 id(如提现 `out_bill_no`) |
+| `remark` | String(128) | nullable | 用户可见备注(如"提现未成功,金额已退回") |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 提现失败/取消退款写 `withdraw_refund`(+X);退款流水 `remark` 是用户可见文案,技术原因记在 `withdraw_order.fail_reason`。

docs/database/coin_account.md

@@ -0,0 +1,24 @@
+# coin_account — 金币 + 现金余额快照
+
+> 模型 `app/models/wallet.py` | 关联接口 [wallet-account](../api/wallet-account.md) | [← 表索引](./README.md)
+
+一个用户一行的余额快照,供读取展示用;每次余额变动都另写流水(`coin_transaction` / `cash_transaction`)并记 `balance_after`,出问题逐笔回溯。`user_id` 既是主键也是外键。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `user_id` | Integer | PK, FK→user.id | 用户(一用户一行) |
+| `coin_balance` | Integer | NOT NULL, default 0 | 当前金币余额 |
+| `cash_balance_cents` | Integer | NOT NULL, default 0 | 当前现金余额(分) |
+| `total_coin_earned` | Integer | NOT NULL, default 0 | 累计赚取金币(只增不减) |
+| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 最后更新时间 |
+
+## 索引与约束
+- PK: `user_id`(同时是 FK→user.id)
+
+## 关系
+- `user_id` → `user.id`(一对一)
+
+## 说明
+- **唯一发金币入口** `wallet.grant_coins` 更新本表余额快照 + 写 `coin_transaction`,不 commit,由调用方同事务提交。
+- 提现扣现金用带条件 `UPDATE ... WHERE cash_balance_cents >= amount` 原子扣减,防并发超额。

docs/database/coin_transaction.md

@@ -0,0 +1,27 @@
+# coin_transaction — 金币流水账本
+
+> 模型 `app/models/wallet.py` | 关联接口 [wallet-coin-transactions](../api/wallet-coin-transactions.md) | [← 表索引](./README.md)
+
+金币每次变动一笔流水,记变动后余额,用于对账与「金币明细」展示。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `amount` | Integer | NOT NULL | 正=入账(赚),负=出账(花/兑换) |
+| `balance_after` | Integer | NOT NULL | 本笔变动后金币余额(对账用) |
+| `biz_type` | String(32) | NOT NULL | 业务类型:`signin` / `task_<key>` / `exchange_out` / `ad_reward` / `compare_milestone` … |
+| `ref_id` | String(64) | nullable | 关联业务 id(签到日期 / 任务 key / trans_id / 里程碑序号等) |
+| `remark` | String(128) | nullable | 备注 |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 明细接口按 `id` 倒序游标分页。
+- 各 `biz_type` 取值由各业务写入(签到/任务/兑换/看广告/比价里程碑),无独立枚举约束,靠写入方约定。

docs/database/comparison_milestone_claim.md

@@ -0,0 +1,26 @@
+# comparison_milestone_claim — 比价战绩里程碑领取记录
+
+> 模型 `app/models/comparison_milestone.py` | 关联接口 [compare-milestones](../api/compare-milestones.md) / [compare-milestone-claim](../api/compare-milestone-claim.md) | [← 表索引](./README.md)
+
+「记录比价战绩」每档(第 1~6 次)只能领一次,领取后写一行;解锁进度由 `comparison_record` 里 `status='success'` 的条数决定,本表只记"哪几档已领"。仿 `user_task` 的一次性领取模型。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `milestone` | Integer | NOT NULL | 档位序号(1-based),见 `rewards.RECORD_MILESTONES` |
+| `coin_awarded` | Integer | NOT NULL, default 0 | 该档发放金币 |
+| `claimed_at` | DateTime(tz) | server_default now() | 领取时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`
+- UNIQUE(`user_id`, `milestone`) = `uq_compare_milestone_user`(防同档重复领)
+
+## 关系
+- `user_id` → `user.id`(多对一)
+- 解锁进度依赖 `comparison_record`(`status='success'` 计数),本表不存进度本身。
+
+## 说明
+- 发金币走 `wallet.grant_coins(biz_type='compare_milestone', ref_id=str(milestone))`,与本表写入同事务。
+- 领取校验:档位越界 404、未解锁(成功数 < milestone)409、已领 409。

docs/database/comparison_record.md

@@ -0,0 +1,47 @@
+# comparison_record — 比价记录(每次比价完整明细)
+
+> 模型 `app/models/comparison.py` | 关联接口 [compare-record-report](../api/compare-record-report.md) / [compare-records](../api/compare-records.md) / [compare-record-detail](../api/compare-record-detail.md) | [← 表索引](./README.md)
+
+每完成一次比价(外卖/电商/领券),客户端 done 帧后用带 JWT 通道上报一条。「我的比价记录」页数据源,也是比价战绩里程碑解锁进度的计数源(`status='success'` 条数)。
+
+> 与 `savings_record` 的区别:本表是「每一次**比价行为**的完整明细」(不省钱、甚至失败也记);`savings_record` 是「真正**下单成交**省了多少」。两表独立、互不喂数据。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `device_id` | String(64) | nullable | 设备号 |
+| `business_type` | String(16) | NOT NULL, default `food`, index | `food`(当前唯一接通)/ `ecom` / `coupon` |
+| `trace_id` | String(64) | NOT NULL | pricebot 侧 trace_id(关联调试落盘 + 幂等键) |
+| `source_platform_id` | String(32) | nullable | 源平台代号 |
+| `source_platform_name` | String(32) | nullable | 源平台中文名 |
+| `source_package` | String(128) | nullable | 源平台 Android 包名 |
+| `source_price_cents` | Integer | nullable | 源平台到手价(分) |
+| `best_platform_id` | String(32) | nullable | 最优平台代号(= rank=1) |
+| `best_platform_name` | String(32) | nullable | 最优平台中文名 |
+| `best_price_cents` | Integer | nullable | 最优价(分) |
+| `saved_amount_cents` | Integer | nullable | 源价 − 最优价(可 0/负) |
+| `is_source_best` | Boolean | nullable | 源平台就是最便宜(= 没省到) |
+| `store_name` | String(128) | nullable | 店铺名 |
+| `total_dish_count` | Integer | nullable | 菜品总数 |
+| `skipped_dish_count` | Integer | nullable | 跳过(没找到)菜品数 |
+| `status` | String(16) | NOT NULL, default `success` | `success`(拿到有效对比)/ `failed`(出错/没采到目标价) |
+| `information` | String(256) | nullable | done 帧文案;成功=摘要,失败=具体原因(前端失败时当原因展示) |
+| `items` | JSON(PG: JSONB) | NOT NULL, default [] | 下单菜品 `[{name, qty, specs?}]` |
+| `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank}]` |
+| `skipped_dish_names` | JSON(PG: JSONB) | NOT NULL, default [] | 被跳过的菜名 |
+| `raw_payload` | JSON(PG: JSONB) | nullable | 客户端原始上报(calibration + done.params 全量) |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`business_type`、`created_at`
+- UNIQUE(`user_id`, `trace_id`) = `uq_comparison_user_trace`(同次比价重试/重复上报幂等覆盖)
+
+## 关系
+- `user_id` → `user.id`(多对一)
+- 被 `comparison_milestone_claim` 间接依赖:里程碑解锁进度 = 本表 `status='success'` 条数。
+
+## 说明
+- `best_*` / `saved_amount_cents` / `is_source_best` / `status` 由 `repositories/comparison.py:_derive` 从 `comparison_results` 派生,客户端不用自己算。
+- 4 个 JSON 列用 `JSON().with_variant(JSONB(),"postgresql")`(SQLite 退化 JSON)。金额结构化列存「分」,`comparison_results.price` 原样存「元」。

docs/database/feedback.md

@@ -0,0 +1,25 @@
+# feedback — 用户帮助与反馈
+
+> 模型 `app/models/feedback.py` | 关联接口 [feedback](../api/feedback.md) | [← 表索引](./README.md)
+
+每条 = 用户一次反馈提交。`content` 与 `contact` 必填,`images` 为可选截图 URL 列表。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 提交用户 |
+| `content` | Text | NOT NULL | 反馈正文 |
+| `contact` | String(128) | NOT NULL | 联系方式(微信/QQ/手机,便于回访) |
+| `images` | JSON | nullable | 截图 URL 列表(相对路径 `/media/feedback/...`);无图为 NULL |
+| `status` | String(16) | NOT NULL, default `new` | `new`(待处理)/ `handled`(已处理) |
+| `created_at` | DateTime(tz) | server_default now(), index | 提交时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- `images` 用通用 `JSON`(本表未用 JSONB variant);截图先经 `/media/feedback/` 上传拿到相对路径再随反馈提交。

docs/database/savings_record.md

@@ -0,0 +1,31 @@
+# savings_record — 省钱记录(profile 省钱战绩源)
+
+> 模型 `app/models/savings.py` | 关联接口 [savings-summary](../api/savings-summary.md) / [savings-battle](../api/savings-battle.md) / [savings-records](../api/savings-records.md) | [← 表索引](./README.md)
+
+profile 页「累计帮你省了 / 省钱战绩 / 省钱明细」的唯一数据源:**真正下单成交后**省了多少记一行。
+
+> ⚠️ **当前为 demo 假数据**:`crud/savings.py:ensure_seeded` 按 user_id 幂等灌 ~23 条(`source='demo'`),聚合(SUM/分组/连续天数)是生产级真实计算。真数据要靠**"用户真下单"信号**(app 目前无:AI 比价止于结算页/结果展示,付款用户手动)——**不是**把比价记录 `comparison_record` 喂过来(那是"比价行为",这是"成交省钱",两个维度)。详见 [[project_shaguabijia_app_server]]。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `order_amount_cents` | Integer | NOT NULL | 订单到手价(分) |
+| `saved_amount_cents` | Integer | NOT NULL | 本单省下(分,可为 0) |
+| `platform` | String(32) | nullable | 下单平台(美团外卖/淘宝闪购/京东外卖) |
+| `title` | String(128) | nullable | 标题 |
+| `shop_name` | String(128) | nullable | 店铺名 |
+| `dishes` | JSON(PG: JSONB) | NOT NULL, default [] | 菜名列表(前 2 道展示,其余"还有 N 道") |
+| `source` | String(16) | NOT NULL, default `compare` | 来源:`demo`(演示)/ `compare`(真实下单上报,待启用) |
+| `created_at` | DateTime(tz) | server_default now(), index | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- `dishes` 用 `JSON().with_variant(JSONB(),"postgresql")`(SQLite 退化 JSON)。
+- `beat_percent`(超过百分之多少用户)按各用户累计省下金额做真实分位;为有可比人群造了 5 个种子用户(`register_channel='seed'`)。

docs/database/signin_record.md

@@ -0,0 +1,26 @@
+# signin_record — 签到记录(7 天循环)
+
+> 模型 `app/models/signin.py` | 关联接口 [signin-status](../api/signin-status.md) / [signin-do](../api/signin-do.md) | [← 表索引](./README.md)
+
+每次签到一行,`(user_id, signin_date)` 唯一,天然防一天签两次。`cycle_day`(1..7)决定发多少金币(`rewards.SIGNIN_REWARDS`),断签重置回 1;`streak` 是连续签到天数(不封顶)用于展示。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `signin_date` | Date | NOT NULL | 签到日期(北京时间 date) |
+| `cycle_day` | Integer | NOT NULL | 7 天循环里今天第几档(1..7),决定发币 |
+| `streak` | Integer | NOT NULL | 连续签到天数(不封顶) |
+| `coin_awarded` | Integer | NOT NULL | 本次发放金币 |
+| `created_at` | DateTime(tz) | server_default now() | 时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`
+- UNIQUE(`user_id`, `signin_date`) = `uq_signin_user_date`(防一天签两次)
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 签到"今天"按北京时间 `cn_today()`(`CN_TZ=UTC+8`);发币与写本表记录同事务(`grant_coins(biz_type='signin', ref_id=日期)`)。

docs/database/user.md

@@ -0,0 +1,32 @@
+# user — 用户(登录主体)
+
+> 模型 `app/models/user.py` | 关联接口 [auth-me](../api/auth-me.md) 等 auth 组 | [← 表索引](./README.md)
+
+登录主体。极光一键登录与短信登录都映射到同一行,以 `phone` 唯一索引;注册即登录(phone 不存在则 insert,存在则更新 `last_login_at`)。后续加微信/Apple 登录新增 oauth_account 表,本表不动。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | 用户主键 |
+| `phone` | String(20) | UNIQUE, index, NOT NULL | 手机号(登录主键;注销后置 `deleted_<id>` 释放唯一约束) |
+| `register_channel` | String(20) | NOT NULL, default `jverify` | 注册渠道:`jverify` / `sms` |
+| `nickname` | String(64) | nullable | 通用昵称(用户改资料设) |
+| `avatar_url` | String(512) | nullable | 通用头像相对 URL(`/media/avatars/...`) |
+| `wechat_openid` | String(64) | UNIQUE, index, nullable | 微信 openid(绑定后存,提现转账用);一微信一账号 |
+| `wechat_nickname` | String(64) | nullable | 微信昵称(绑定时拉,展示在提现绑定卡) |
+| `wechat_avatar_url` | String(512) | nullable | 微信头像 URL |
+| `status` | String(20) | NOT NULL, default `active` | `active` / `disabled` / `deleted` |
+| `created_at` | DateTime(tz) | server_default now() | 注册时间 |
+| `last_login_at` | DateTime(tz) | default utcnow(应用层) | 最近登录时间 |
+
+## 索引与约束
+- PK: `id`
+- UNIQUE + index: `phone`
+- UNIQUE + index: `wechat_openid`(允许多个 NULL = 多个未绑定用户)
+
+## 关系
+- 被引用方:`coin_account` / `coin_transaction` / `cash_transaction` / `withdraw_order` / `signin_record` / `user_task` / `savings_record` / `ad_reward_record` / `ad_ecpm_record` / `feedback` / `comparison_record` / `comparison_milestone_claim` 的 `user_id` 均 → `user.id`。
+
+## 说明
+- `nickname/avatar_url`(通用)与 `wechat_nickname/wechat_avatar_url`(微信)**分开存,不互相覆盖**。
+- 注销账号:phone 改占位串、status=deleted,不物理删行(保留外键完整性)。

docs/database/user_task.md

@@ -0,0 +1,26 @@
+# user_task — 一次性任务领取去重
+
+> 模型 `app/models/task.py` | 关联接口 [tasks-list](../api/tasks-list.md) / [tasks-claim](../api/tasks-claim.md) | [← 表索引](./README.md)
+
+像"打开消息提醒"这类只能领一次的任务,完成后写一行,`(user_id, task_key)` 唯一防重复领奖。可循环领取的任务(签到)不走这张表,有专表 `signin_record`。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `task_key` | String(48) | NOT NULL | 任务标识,见 `rewards.TASK_REWARDS`(如 `enable_notification`) |
+| `status` | String(16) | NOT NULL, default `completed` | 任务状态 |
+| `coin_awarded` | Integer | NOT NULL, default 0 | 该任务发放金币 |
+| `completed_at` | DateTime(tz) | server_default now() | 完成/领取时间 |
+
+## 索引与约束
+- PK: `id`;index: `user_id`
+- UNIQUE(`user_id`, `task_key`) = `uq_task_user_key`(防重复领)
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 领取:写本表 + `grant_coins(biz_type='task_<key>', ref_id=task_key)` 同事务;重复领抛 409,未知 key 抛 404。
+- 比价战绩里程碑虽是"领一次"模型但**不复用本表**,另有 `comparison_milestone_claim`(因 task_key 是固定字典,里程碑是按次数解锁的序号)。

docs/database/withdraw_order.md

@@ -0,0 +1,30 @@
+# withdraw_order — 提现单(现金 → 微信零钱)
+
+> 模型 `app/models/wallet.py` | 关联接口 [wallet-withdraw](../api/wallet-withdraw.md) / [wallet-withdraw-status](../api/wallet-withdraw-status.md) | [← 表索引](./README.md)
+
+提现状态机:`pending → success / failed`。扣现金 + 写 `cash_transaction(withdraw)` + 建本单在同一事务;失败/取消时退回现金并写 `cash_transaction(withdraw_refund)`。`wechat_state` 存微信侧原始状态,`status` 是归一化后的三态。
+
+## 字段
+| 列 | 类型 | 约束 / 默认 | 说明 |
+|---|---|---|---|
+| `id` | Integer | PK, autoincrement | |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
+| `out_bill_no` | String(64) | UNIQUE, index, NOT NULL | 商户单号(幂等键 + 微信查单);客户端可传,不传则服务端生成 |
+| `amount_cents` | Integer | NOT NULL | 提现金额(分) |
+| `status` | String(16) | NOT NULL, default `pending` | 归一化状态:`pending` / `success` / `failed` |
+| `wechat_state` | String(32) | nullable | 微信原始状态:`WAIT_USER_CONFIRM` / `SUCCESS` / `FAIL` / `CANCELLED` … |
+| `transfer_bill_no` | String(64) | nullable | 微信转账单号 |
+| `package_info` | String(512) | nullable | 待用户确认时返回 App 拉起确认页用 |
+| `fail_reason` | String(256) | nullable | 失败技术原因(不外露,用户只看流水 remark) |
+| `created_at` | DateTime(tz) | server_default now(), index | 发起时间 |
+| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 更新时间 |
+
+## 索引与约束
+- PK: `id`;UNIQUE + index: `out_bill_no`;index: `user_id`、`created_at`
+
+## 关系
+- `user_id` → `user.id`(多对一)
+
+## 说明
+- 资金安全:原子扣款 + `out_bill_no` 幂等 + 模糊失败先查单再决定(绝不盲目退款)+ 孤儿单对账 `reconcile_pending_withdraws`。详见 [[project_shaguabijia_app_server]] 提现段。
+- `WITHDRAW_MIN_CENTS=10`(0.1 元,微信地板)。

docs/后端技术实现.md

@@ -61,6 +61,7 @@ app/
 │       ├── feedback.py      # 帮助与反馈 1 端点(提交反馈含截图)
 │       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权)
 │       ├── compare.py       # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权)
+│       ├── compare_record.py# 比价记录 3 端点(上报 /compare/record + 列表 /compare/records + 详情;鉴权,区别于上面透传)
 │       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS),未配 MT_CPS 凭证降级返空
 │       ├── wallet.py        # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
 │       ├── signin.py        # 签到 2 端点(状态 / 执行签到)
@@ -73,6 +74,7 @@ app/
 │   ├── feedback.py          # 反馈出参(请求是 multipart,在 router 直接校验)
 │   ├── meituan.py
 │   ├── welfare.py           # 钱包/签到/任务/省钱 收发模型
+│   ├── compare_record.py    # 比价记录上报/列表/详情 收发模型(字段对齐 pricebot calibration + done.params)
 │   └── ad.py                # 看广告发奖收发模型
 ├── integrations/            # 外部服务/SDK 客户端(重逻辑:签名/加解密/外部 HTTP)
 │   ├── jiguang.py           # 极光 REST 验 token + RSA 解密(多 padding 试错)
@@ -94,6 +96,7 @@ app/
 │   ├── signin.py            # 签到记录 / 连续天数 / 档位
 │   ├── task.py              # 一次性任务领取
 │   ├── savings.py           # 省钱汇总 / 战绩 / 明细
+│   ├── comparison.py        # 比价记录 upsert(user_id+trace_id 幂等)+ best/saved/status 派生 + 分页
 │   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限 + 本轮冷却派生)
 ├── models/                  # ORM 表结构
 │   ├── user.py              # user(含微信 openid/nickname/avatar)
@@ -102,6 +105,7 @@ app/
 │   ├── signin.py            # 签到记录
 │   ├── task.py              # 任务领取记录
 │   ├── savings.py           # 省钱明细 / 店铺菜品 / dishes(PG 上 JSONB)
+│   ├── comparison.py        # 比价记录(完整明细;含 4 个 JSON(B) 列 + raw_payload;独立于 savings)
 │   └── ad_reward.py         # 看广告发奖记录
 └── db/
     ├── base.py              # DeclarativeBase
@@ -218,7 +222,7 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert
 
 ## 7. 数据模型
 
-10 张业务表 + `alembic_version` 框架表。生产 PG / 开发可回退 SQLite。
+业务表(下表)+ `alembic_version` 框架表。生产 PG / 开发可回退 SQLite。
 
 | 表 | models 文件 | 说明 |
 |---|---|---|
@@ -231,6 +235,7 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert
 | `signin_record` | `models/signin.py` | 签到记录(每日一行,索引 `(user_id, signin_date)`) |
 | `user_task` | `models/task.py` | 一次性任务领取记录 |
 | `savings_record` | `models/savings.py` | 省钱明细(`dishes` 在 PG 上为 JSONB,SQLite 上是 TEXT) |
+| `comparison_record` | `models/comparison.py` | 比价记录(每次比价完整明细;`(user_id, trace_id)` 唯一幂等;4 个 JSON(B) 列含 `raw_payload`;独立于 savings) |
 | `ad_reward_record` | `models/ad_reward.py` | 看广告发奖(`trans_id` 唯一,幂等) |
 
 **user 表字段速查**:

docs/待办与技术债.md

@@ -11,8 +11,8 @@
 
 - **现状**：agent 系列接口 MVP 阶段**全部不鉴权**。领券 `coupon/step` **已落地不鉴权**(✅ 已去掉 `CurrentUser` 依赖);比价 4 个(`intent/recognize`、`price/step`、`ecom/intent/recognize`、`ecom/step`)端点尚未建(见 P2),建时同样先不加鉴权。
 - **代价(为什么记这笔账)**：不验 JWT → 转发时 server 拿不到 `user_id` → agent 行为只能绑到 `device_id`(设备级)，**采集不到"哪个用户领了/买了什么"的用户级画像**。而精准人群画像、私域分群运营是商业模式的核心资产，靠的就是这份用户级行为数据。`device_id` 仍照传(后端按设备串领券队列够用)。
-- **待补**：① agent 接口加 JWT 鉴权；② 建立 `device_id ↔ user_id` 绑定(登录后上报一次即可)；③ 领券/比价记录按 user 维度落库。
-- **连带**：补鉴权后，客户端引擎 `ApiClient` 要接回 JWT(复用 app 现有 `AuthInterceptor` 思路：注入带鉴权头的 OkHttpClient)。
+- **待补**：① agent 接口加 JWT 鉴权；② 建立 `device_id ↔ user_id` 绑定(登录后上报一次即可)；③ ~~领券/比价记录按 user 维度落库~~ → **比价记录已落地**(见文末「已解决」)：走**独立的鉴权端点** `POST /api/v1/compare/record`,客户端在 done 帧后用带 JWT 的通道上报、不依赖透传链路。**所以透传端点本身仍不鉴权、本条 P1 主诉求(给透传链路补 JWT + device↔user 绑定)未解**;领券记录尚未落库。
+- **连带**：补鉴权后，客户端引擎 `ApiClient` 要接回 JWT(复用 app 现有 `AuthInterceptor` 思路：注入带鉴权头的 OkHttpClient)。比价记录上报已**先行复用**这套(`authedClient` 挂 `AuthInterceptor`+`RefreshAuthenticator`),可作透传链路补鉴权的参考样板。
 
 ---
 
@@ -87,6 +87,10 @@
 
 ## 已解决
 
+- ✅ **比价记录落库(server + client,2026-05-31)**:每次比价 done 后客户端上报、按 user 落库,作「我的比价记录」数据源 + 用户级画像沉淀。
+  - **server**(本仓):新表 `comparison_record`(独立于 `savings_record`;结构化列 + `items`/`comparison_results`/`skipped_dish_names`/`raw_payload` 四个 JSON(B) 列)+ 3 个**鉴权**端点 `POST /api/v1/compare/record`(`(user_id,trace_id)` 幂等 upsert,best/saved/is_source_best/status 服务端从 comparison_results 派生)/ `GET /api/v1/compare/records`(游标分页)/ `GET /records/{id}`(含 raw_payload);`models/comparison.py` + `repositories/comparison.py` + `schemas/compare_record.py` + `api/v1/compare_record.py` + 迁移 `comparison_record_table`(head `b2c3d4e5f6a7`)+ `tests/test_compare_record.py`(8 例全过)+ `docs/api/compare-record-*.md`。
+  - **client**(android 仓):`PriceBotService.runTask()` 比价 done 后(`lastDoneParams!=null`,成功/引擎失败都报)用独立 IO 协程尽力上报;`Protocol.CompareRecordRequest.fromComparison()` 从 calibration+done.params 零翻译组装;`ApiClient.reportCompareRecord()` 走新建的 `authedClient`(复用 `AuthInterceptor`+`RefreshAuthenticator`,自动 Bearer+401 刷新)。领券不报(非价格对比,本期范围只外卖)。
+  - **未做**:UI(「我的比价记录」页)等原型;真机端到端待验。
 - ✅ **领券链路接通**(阶段 1):首页「去领取」→ `CouponPromptDialog` → 权限检查 → `startCouponClaim` → 循环 `/api/v1/coupon/step`;Running 悬浮窗换皮(ComposeView 承载 `CouponProgressPanel`/AgentFloat,`OverlayLifecycleOwner` 撑 Compose)。
 - ✅ **coupon/step 去鉴权**:去掉 `CurrentUser`,MVP 不鉴权(device_id 透传)。
 - ✅ **ApiClient 改址**:`BuildConfig.BASE_URL` + `/api/v1/` 前缀。