chore(alembic): merge comparison_milestone 和 savings_report_fields 两个 head (#11)

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

docs/api/compare-milestone-claim.md

@@ -2,9 +2,10 @@
 
 > 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
 
-领取某一档(第 `milestone` 次)的金币奖励,真实入账金币钱包。领取记录写
-`comparison_milestone_claim`((user_id, milestone) 唯一)+ `grant_coins` 同一事务原子提交,
-**每档只能领一次**。进度口径见 [milestones 进度接口](./compare-milestones.md)。
+领取某一档(第 `milestone` 次)。⚠️ **当前不真发金币**(产品定,后续整体删除该功能):仍写
+`comparison_milestone_claim`((user_id, milestone) 唯一)标记该档已领、**每档只能领一次**,但不调
+`grant_coins`、不写 `coin_transaction`,余额不变,`coin_awarded` 恒为 0。进度口径见
+[milestones 进度接口](./compare-milestones.md)。
 
 ## 入参
 - 路径参数 `milestone`(int):档位序号,1..6(= `RECORD_MILESTONES` 长度)。
@@ -15,11 +16,11 @@
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `milestone` | int | 本次领取的档位序号 |
-| `coin_awarded` | int | 本次发放金币 |
-| `coin_balance` | int | 领奖后金币余额 |
+| `coin_awarded` | int | 本次发放金币(当前恒为 `0`,暂不真发) |
+| `coin_balance` | int | 领奖后金币余额(当前不变) |
 
 ```json
-{ "milestone": 1, "coin_awarded": 120, "coin_balance": 29087 }
+{ "milestone": 1, "coin_awarded": 0, "coin_balance": 29087 }
 ```
 
 ## 错误
@@ -29,5 +30,5 @@
 - `409` 该档已领过(`milestone already claimed`)
 
 ## 说明
-- 领取金币后,客户端应刷新钱包余额([`GET /api/v1/wallet/account`](./wallet-account.md))与本档状态。
-- 幂等:重复领同一档返回 409 且**不会重复发金币**(唯一约束 + 领取前查重)。
+- 当前不发金币,客户端领取后只需把本档状态刷成 claimed 即可;若后续恢复发奖,再按 `coin_awarded` 刷新钱包余额([`GET /api/v1/wallet/account`](./wallet-account.md))。
+- 幂等:重复领同一档返回 409(唯一约束 + 领取前查重)。

docs/api/compare-milestones.md

@@ -8,6 +8,8 @@
 
 档位金额是**产品规则**,定义在后端 `app/core/rewards.py` 的 `RECORD_MILESTONES`(当前 `120/180/300/500/800/1200`),客户端**不要写死**,以本接口返回为准。
 
+> ⚠️ **当前领取暂不真发金币**(产品定,后续整体删除该功能):`coin` 仍返回产品规则值仅供展示,但 [claim 接口](./compare-milestone-claim.md) 实际 `coin_awarded` 恒为 0、余额不变。前端展示须与之对齐,勿让用户误以为领取可到账。
+
 ## 入参
 无(用户身份取自 Bearer token)。
 
@@ -25,7 +27,7 @@
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `milestone` | int | 档位序号(1-based),= 解锁所需的成功比价次数 |
-| `coin` | int | 该档奖励金币 |
+| `coin` | int | 该档**应发**金币额(产品规则值);⚠️ 当前领取不真发,见上方说明 |
 | `state` | string | `claimed`(已领) / `active`(已解锁可领) / `locked`(未解锁) |
 
 ```json

docs/api/compare-record-report.md

@@ -31,7 +31,9 @@
 
 **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) }`
+**Result（comparison_results 元素）**：`{ platform_id, platform_name, package, price(元,float\|null), is_source(bool), rank(int\|null), coupon_saved(元,float\|null) }`
+
+- `coupon_saved`：该平台本单**平台主优惠额**（元）——美团红包 / 淘宝平台红包 / 京东优惠券·百亿补贴，**只取那一笔**，不含配送费减免/共减总额。仅外卖目标平台带值，源平台/没用为 `null`，前端记录页据此展示**「已优惠 ¥X」**（null 不展示）。
 
 ## 服务端派生（客户端不用算）
 

docs/database/comparison_milestone_claim.md

@@ -10,7 +10,7 @@
 | `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 | 该档发放金币 |
+| `coin_awarded` | Integer | NOT NULL, default 0 | 该档应发金币额;⚠️ 当前产品定暂不真发,实际恒为 0 |
 | `claimed_at` | DateTime(tz) | server_default now() | 领取时间 |
 
 ## 索引与约束
@@ -22,5 +22,5 @@
 - 解锁进度依赖 `comparison_record`(`status='success'` 计数),本表不存进度本身。
 
 ## 说明
-- 发金币走 `wallet.grant_coins(biz_type='compare_milestone', ref_id=str(milestone))`,与本表写入同事务。
+- ⚠️ 当前 claim 仅写本表标记已领(去重),**不调 `grant_coins`、不写 `coin_transaction`,`coin_awarded` 恒为 0、余额不变**(产品定暂不真发金币,后续整体删除该功能)。
 - 领取校验:档位越界 404、未解锁(成功数 < milestone)409、已领 409。

docs/database/comparison_record.md

@@ -29,7 +29,7 @@
 | `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}]` |
+| `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank,coupon_saved}]`;`coupon_saved`=该平台主优惠额(元,美团红包/淘宝平台红包/京东优惠券·百亿补贴,只取那一笔,不含配送费/共减总额),各平台抠到红包即带值(2026-06 起源平台 Phase1 意图识别也抠,当前仅淘宝源),没用/没抠到为 null,前端展示「已优惠 ¥X」 |
 | `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 | 时间 |