Merge branch 'main' into feature/direct-vendor-push-main-20260702

2026-07-22 15:42:15 +08:00
parent 0a8cab9e7e 2eb36b44c8
commit 2461004aa5
67 changed files with 2521 additions and 526 deletions
@@ -82,7 +82,6 @@
 | **签到**（前缀 `/api/v1/signin`） |||
 | 25 | `GET /api/v1/signin/status` | Bearer | [详情](./signin/signin-status.md) |
 | 26 | `POST /api/v1/signin` | Bearer | [详情](./signin/signin-do.md) |
-| 26a | `POST /api/v1/signin/boost` | Bearer | [详情](./signin/signin-boost.md) |
 | **任务**（前缀 `/api/v1/tasks`） |||
 | 27 | `GET /api/v1/tasks` | Bearer | [详情](./tasks/tasks-list.md) |
 | 28 | `POST /api/v1/tasks/{task_key}/claim` | Bearer | [详情](./tasks/tasks-claim.md) |
@@ -93,6 +92,7 @@
 | **看广告发奖**（前缀 `/api/v1/ad`） |||
 | 32 | `GET /api/v1/ad/pangle-callback` | 验签 | [详情](./ad/ad-pangle-callback.md) |
 | 33 | `GET /api/v1/ad/reward-status` | Bearer | [详情](./ad/ad-reward-status.md) |
+| 33a | `GET /api/v1/ad/reward-result/{ad_session_id}` | Bearer | [详情](./ad/ad-reward-result.md)（本次实发金币 + 本轮膨胀累计 `round_coin`,弹窗数字用它） |
 | 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad/ad-test-grant.md) |
 | 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad/ad-ecpm-report.md) |
 | 35a | `POST /api/v1/ad/feed-reward` | Bearer | [详情](./ad/ad-feed-reward.md) |
@@ -133,6 +133,7 @@
 | 40a | `GET /api/v1/platform/flags` | 无 | [详情](./platform/platform-flags.md)（客户端运营 feature flag,比价/领券期广告开关等,拉取后缓存） |
 | 40b | `GET /api/v1/platform/ad-config` | 无 | [详情](./platform/platform-ad-config.md)（客户端拉广告配置:穿山甲 app_id+各位ID+各场景开关;不含验签密钥） |
 | 40c | `GET /api/v1/platform/app-version` | 无 | [详情](./platform/platform-app-version.md)（最新 App 版本,OTA 检查更新;与本机 versionCode 比） |
+| 40d | `GET /api/v1/platform/huawei-review` | 无 | [详情](./platform/platform-huawei-review.md)（华为审核开关:快速设置权限步能否被用户关闭;仅华为 ROM 客户端拉） |
 | **微信支付回调**（前缀 `/api/v1/wxpay`） |||
 | W1 | `POST /api/v1/wxpay/transfer-auth-notify` | 无 | 免确认收款授权结果通知（一期 stub:仅应答 200 不验签不改账,授权状态靠主动查询兜底)(无单独文档) |
 | **CPS 群发短链落地**（**无前缀**,挂域名根;公网不鉴权） |||
@@ -171,6 +172,7 @@
 | A12 | `GET /admin/api/ad-revenue-report` | admin | [详情](./admin/ad/admin-ad-revenue-report.md)(广告收益报表:分页/场景/`app_env` 筛 + **DAU/ARPU** #120;真实收益侧接穿山甲日表 #92) |
 | A13 | `GET / PATCH /admin/api/ad-config` | operator/finance | 广告配置(穿山甲 ID/验签密钥/各场景开关;C 端只读版见 40b)(无单独文档,见 `app/admin/routers/ad_config.py`) |
 | A14 | `GET /admin/api/config`、`PATCH /config/{key}` | operator/finance | 运营可配置项([app_config](../database/app_config.md):奖励常量/提现地板价等;#117 修系统配置下发)(无单独文档,见 `app/admin/routers/config.py`) |
+| A16 | `GET / PATCH /admin/api/huawei-review` | operator/tech | 华为审核开关(快速设置权限步能否被用户关闭,落 `app_config.huawei_review`;C 端只读版见 40d)(无单独文档,见 `app/admin/routers/huawei_review.py`) |
 | **A·管理员与角色**(super_admin):`GET`/`POST` `/admins`、`PATCH`/`DELETE` `/admins/{id}`(#126 删除+`pages_override`)、`GET`/`POST` `/roles`、`GET /roles/catalog`、`PATCH`/`DELETE` `/roles/{id}`(#117/#126 自定义角色) ||| [列表](./admin/admins/admin-admins-list.md) / [建](./admin/admins/admin-admin-create.md) / [改+删](./admin/admins/admin-admin-update.md) / [角色](./admin/admin-roles.md) |
 | A15 | `GET /admin/api/audit-logs` | admin | [详情](./admin/admin-audit-logs.md) |
 | **A·CPS 运营台**:群/活动 CRUD、`POST /referral-links`、`POST /orders/reconcile`(美团+京东 #90)、`GET /orders`、`/stats`、群 `timeseries`/`daily`/`wx-users`/`day-users`(#79) ||| [详情](./admin/admin-cps.md) |
@@ -15,7 +15,15 @@ GroMore 以 GET 回调,关键参数:
 | `trans_id` | string | 交易号（**幂等键** + **唯一参与签名的字段**） |
 | `reward_name` | string | 奖励名（广告位配置,入库备注） |
 | `ecpm` | string\|null | GroMore 回调携带的 eCPM。普通激励视频优先用它计算金币 |
-| `extra` / `gromoreExtra` / `gromore_extra` | string | 客户端透传 JSON。支持 `ad_session_id`、`reward_scene`;`reward_scene=signin_boost` 表示签到膨胀 |
+| `extra` / `gromoreExtra` / `gromore_extra` | string | 客户端透传 JSON。支持 `ad_session_id`、`reward_scene`、`srv_env`、`boost_round_id` |
+
+### `extra` 里的 `boost_round_id`
+
+客户端生成的「这条广告属于哪一轮膨胀」标签(32 位十六进制,同 `ad_session_id` 格式),随发奖记录存进 `ad_reward_record.boost_round_id`。
+
+**它不参与任何发奖判定** —— 发多少、发不发完全不受影响,只是让 [`/ad/reward-result`](./ad-reward-result.md) 能把同一轮的 granted 记录求和成 `round_coin`(客户端「恭喜累计获得奖励」弹窗显示的数)。
+
+轮次边界由客户端定(只有它知道用户点没点「放弃赚钱」):点「去膨胀」新生成一个 → 点「继续看视频膨胀」复用同一个 → 点「放弃赚钱」/ ✕ / 返回 / 到每日上限 / 跨天 则丢弃。不带此字段(老客户端 / GroMore 偶发丢 extra)时存 NULL,`round_coin` 返 `null`。
 | `mediation_rit` | string | 代码位 ID（GroMore 带,目前仅入 raw 备查） |
 | `prime_rit` | string | 广告位 ID（同上） |
 | `adn_name` | string | 实际出广告的 ADN 名（同上,可用于收益分析） |
@@ -40,6 +48,6 @@ GroMore 以 GET 回调,关键参数:
 **发奖唯一可信入口**:验签 → 取 `user_id`/`extra` → 按 `reward_scene` 分流 → 幂等处理（按 `trans_id` 去重）。客户端不直接发奖,被破解也刷不到钱。

 - `reward_scene=reward_video` 或缺省:普通激励视频。金币按 `eCPM / 1000 * eCPM因子 * 当日次数因子 * 10000` 计算;若回调没有 `ecpm`,会按 `extra.ad_session_id` 查客户端 `/ad/ecpm-report` 的上报值;两边都没有 eCPM 时不发币,记录 `status=ecpm_missing`。
- `reward_scene=signin_boost`:签到膨胀。要求用户当天已签到且不是 Day14;看完视频固定发 `2000` 金币,写 `signin_boost_record` 与 `coin_transaction.biz_type=signin_boost`。
+- ~~`reward_scene=signin_boost`~~(签到膨胀):**2026-07 已下线**。它按固定 3000 金币发、与广告实际收益脱钩,产品确认非设计内口径。签到弹窗的「看广告膨胀」现与福利页看视频同走 `reward_video`。现在传 `signin_boost` 会落到「未知场景」分支(不发币,`status=unknown_scene`)。
 - 未知 `reward_scene`:不发币,记录 `status=unknown_scene`,返回 `is_verify=false/reason=1`。
 - 验签过但参数缺/坏或 user 不存在 → 不发（`is_verify=false` + `reason`）;granted / capped / ecpm_missing / 业务不满足已记录 → `is_verify=true` + `reason=0`。
@@ -0,0 +1,66 @@
+# GET /api/v1/ad/reward-result/{ad_session_id} — 查本次广告的权威发奖结果 + 本轮累计
+
+客户端看完激励视频后轮询本接口，拿**本次实发金币**和**本轮累计**用于「恭喜累计获得奖励」弹窗。不再用余额差 / `coin_per_ad` 估算。
+
+**纯只读**：发奖仍只由验签过的 S2S 回调完成，本接口不写库、不产生任何奖励。按 `user_id` 收窄，被刷也只能查到自己的记录。
+
+## 鉴权
+
+需要 Bearer token。
+
+## 路径参数
+
+| 参数 | 类型 | 约束 | 说明 |
+|---|---|---:|---|
+| `ad_session_id` | string | 长度 8~64 | 本次广告会话 id，客户端生成，与 `mediaExtra` / `ecpm-report` 同值 |
+
+## 响应
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `ad_session_id` | string | 回显请求值 |
+| `status` | string | `pending`(S2S 未到账，继续轮询) / `granted` / `capped`(当日超限) / `ecpm_missing` / `closed_early`(提前关闭) |
+| `coin` | int \| null | **本条**实发金币。granted 为真实到账额；未发奖的状态为 0；pending 为 `null` |
+| `round_coin` | int \| null | **本轮累计已发金币**(含本条) ← 弹窗显示的就是它 |
+
+```json
+{ "ad_session_id": "3f2a9c1b7e4d8a60", "status": "granted", "coin": 20, "round_coin": 60 }
+```
+
+### `round_coin` 的口径
+
+「轮」= 用户点「去膨胀」到点「放弃赚钱」之间连看的若干条广告，边界由客户端的 `boost_round_id` 定（见 [ad-pangle-callback](./ad-pangle-callback.md)）。
+
+```sql
+SELECT COALESCE(SUM(coin), 0) FROM ad_reward_record
+WHERE user_id = :user_id                        -- 恒带，轮 id 是客户端生成的不可跨用户信任
+  AND boost_round_id = :该会话记录的 boost_round_id
+  AND status = 'granted'
+```
+
+由服务端求和而非客户端自己累加：客户端进程被杀 / 低内存重建后本地累计会丢，发奖记录不会。
+
+**要守住的不变量：弹窗数字 == 本轮实际到账之和 == 用户看到的余额涨幅。** 三者对不上，用户就会认为少发了钱。
+
+| 情形 | `round_coin` |
+|---|---|
+| 本条 `granted` | 本轮累计（含本条） |
+| 本条 `capped` / `closed_early` / `ecpm_missing` | **仍返本轮累计**，该条按 0 计（撞上限那下的 toast 要能显示前几条的总额，不能是空） |
+| `status=pending`（没记录） | `null` —— 连属于哪一轮都不知道。**不是 0**，0 会被读成「本轮没赚到」 |
+| 该记录没有 `boost_round_id`（老客户端 / extra 丢失） | `null`，客户端退回只显示单条 `coin` |
+
+## 错误
+
+- `401`: 未登录
+- `422`: `ad_session_id` 长度不在 8~64
+
+**查不到记录不返 404**，而是 200 + `status="pending"`。404 只应表示路由不存在；两者混在一起客户端没法区分「后端没部署」和「再等等」。
+
+## 实现注意
+
+同一 `ad_session_id` 可能有多条记录，取值时**显式优先 `granted`**，不能只取最近一条：
+
+- 客户端先报 `closed_early`、S2S 随后姗姗来迟 → 两条，`granted` 反而是后写的
+- 本地联调重复调 `test-grant` → 同 session 多条 `granted`（`trans_id` 各不相同）
+
+都没有 `granted` 才取最近一条，让客户端知道没发的原因。
@@ -9,7 +9,8 @@

 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |---|---|---|---|---|
-| `reward_scene` | string | 否 | `reward_video` | 模拟发奖场景。`reward_video`=普通激励视频；`signin_boost`=签到膨胀 |
+| `reward_scene` | string | 否 | `reward_video` | 模拟发奖场景。当前**只支持** `reward_video`；`signin_boost`（签到膨胀）已于 2026-07 下线，传它返 `422` |
+| `boost_round_id` | string | 否 | `null` | 本次广告属于哪一轮膨胀。正式链路走 S2S 的 `mediaExtra`，本接口不经 S2S 拿不到 extra，故由 body 补。**不传的话 debug 包 `/ad/reward-result` 的 `round_coin` 恒为 `null`**，「弹窗 40 → 60 → toast +60」那套累计验收在本地跑不起来 |
 | `ad_session_id` | string(8~64) \| null | 否 | null | 本次广告会话 id(与 [ecpm-report](./ad-ecpm-report.md) 同值)。**仅 `reward_video` 场景生效**:据此查回客户端已上报的真实 eCPM,走与正式发奖相同的公式发奖;查不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍出非零金币 |

 ## 出参
@@ -33,4 +34,4 @@

 `reward_scene=reward_video` 时按上面 `ad_session_id` 查回的真实 eCPM 走金币公式发奖(取不到兜底 200)——便于本地用 [admin 金币审计](./admin-ad-coin-audit.md) 核对「看广告→金币」是否按公式计算。

-`reward_scene=signin_boost` 时复用签到膨胀业务规则:必须当天已签到、非第 14 天、当天未膨胀过,成功后写入 `signin_boost` 金币流水。它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
+它让已登录客户端能自助发奖 = 绕过反作弊,**严禁在生产开启**。
@@ -28,6 +28,8 @@
  | `user_id` | int | 全部 | 只看某用户;不传=所有用户 |
  | `ad_type` | string | 全部 | `reward_video` / `feed` / `draw`;不传=全部类型 |
  | `feed_scene` | string | 全部 | `comparison`(比价)/ `coupon`(领券)/ `welfare`(福利);**全局筛选**,同时作用于明细 / 合计 / `daily`·`hourly` 趋势;不传=全部场景 |
+  | `app_env` | string | 全部 | `prod`=正式应用 / `test`=测试应用;同时过滤客户端预估与穿山甲汇总 |
+  | `revenue_scope` | string | `all` | `business`=仅业务代码位,用于同口径对账 / `all`=应用全部代码位,包含广告测试等非业务曝光 |
  | `granularity` | string | `day` | `day`=按天 / `hour`=按小时(聚合键再加北京时间小时 0–23);**区间>1 天建议用 day** |
  | `limit` | int(1~1000) | 500 | **每页条数**(分页大小);`total`/`total_*`/`daily`/`hourly` 按全量统计不受分页影响 |
  | `offset` | int(≥0) | 0 | 分页偏移(已跳过条数)=(页码−1)×`limit` |
@@ -131,5 +133,5 @@
 - **历史 Draw 不可拆**:迁移(Draw→普通信息流)前,Draw 发奖混在 `ad_feed_reward_record` 且无类型标记,金币侧统一记 `feed`;迁移后 Draw 不再产生新数据。展示侧 `ad_type` 由客户端上报区分,故 `draw` 桶基本为空。
 - **来源字段从上线起齐全**:`app_env`/`our_code_id` 是本期新增列,历史记录为 NULL(报表来源列留空)。
 - **逐条/明细的收益是预估**:`items[].revenue_yuan` 基于客户端上报的 eCPM 折算,非穿山甲后台结算值。
- **穿山甲后台收益(汇总/趋势级)**:`total_pangle_revenue_yuan`(预估 `revenue`)与 `total_pangle_api_revenue_yuan`(收益Api `api_revenue`,更接近结算)来自穿山甲 **GroMore 数据 API**(`integrations/pangle_report` + `scripts/sync_pangle_revenue` 按天 T+1 拉取入 [ad_pangle_daily_revenue](../database/ad_pangle_daily_revenue.md))。穿山甲**不提供分用户/设备/类型/场景维度**(官方明确),最细到 日期×应用×代码位,故只用于汇总与按天趋势的对照,**不挂到逐条事件行**;且仅在全量视图(未按 user/类型/场景过滤)展示。配置见 `.env` 的 `PANGLE_REPORT_*`。
+- **穿山甲后台收益(汇总/趋势级)**:`total_pangle_revenue_yuan`(预估 `revenue`)与 `total_pangle_api_revenue_yuan`(收益Api `api_revenue`,更接近结算)来自穿山甲 **GroMore 数据 API**(`integrations/pangle_report` + `scripts/sync_pangle_revenue` 按天 T+1 拉取入 [ad_pangle_daily_revenue](../database/ad_pangle_daily_revenue.md))。穿山甲**不提供分用户/设备/类型/场景维度**(官方明确),最细到 日期×应用×代码位,故只用于汇总与按天趋势的对照,**不挂到逐条事件行**;且仅在未按 user/类型/场景过滤时展示。`app_env` 与 `revenue_scope` 会同时过滤客户端和穿山甲数据，其中 `business` 排除广告测试等非业务代码位。配置见 `.env` 的 `PANGLE_REPORT_*`。
 - **对账聚合级 + 逐条下钻**:行级 `matched` 给出该组(用户×类型×应用×代码位)应发是否==实发;**展开 `records` 即可看该组逐条明细**(eCPM/因子1/份数/LT/因子2/应发/实发/一致)定位到具体记录。独立逐条审计接口 [admin-ad-coin-audit](./admin-ad-coin-audit.md) 仍保留(同一复算口径,可全局按场景/只看不符筛选)。
@@ -37,8 +37,8 @@
 | `feed_ad_watch_count` | int | 信息流广告有效完成视频数(`ad_feed_reward_record.status=granted`) |
 | `signin_coin_total` | int | 签到累计发放金币(`biz_type=signin`) |
 | `signin_count` | int | 签到次数(`signin_record`) |
-| `signin_boost_coin_total` | int | 签到膨胀累计发放金币(`biz_type=signin_boost`) |
-| `signin_boost_watch_count` | int | 签到膨胀有效视频数(`signin_boost_record`) |
+| `signin_boost_coin_total` | int | **历史口径**:签到膨胀累计发放金币(`biz_type=signin_boost`)。功能已下线,数字不再增长,保留供对账 |
+| `signin_boost_watch_count` | int | **历史口径**:签到膨胀次数。膨胀 2026-07 已下线、`signin_boost_record` 表已 drop,改数 `coin_transaction.biz_type='signin_boost'` 的入账笔数(一次膨胀 = 一笔,与原口径等价),只会停在历史值不再增长 |

 **DashboardCash**
 | 字段 | 类型 | 说明 |
@@ -0,0 +1,36 @@
+# GET /api/v1/platform/huawei-review — 华为审核开关
+
+> 所属:Platform 组（前缀 `/api/v1/platform`） | 鉴权:无 | [← 返回 API 索引](../README.md)
+
+华为应用市场审核要求:新手引导的**「快速设置」权限步必须可被用户关闭**（引导视频页不在要求内）。本端点把运营后台配的开关下发给客户端,决定该步左上角是否出现退出按钮。
+
+**不鉴权**:引导页在登录之前就展示,此时客户端必然没有 token。
+
+值来自 `app_config` 表的 `huawei_review` 行（admin 页 `GET / PATCH /admin/api/huawei-review` 可改），空库回退 `default`。
+
+## 入参
+
+无。
+
+## 出参
+
+响应 `200`:`HuaweiReviewOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `mode` | string | `default`（强制展示,不可关闭 = 上线至今的现状）/ `review`（可关闭,过审用）。仅供排查时看后台切成了哪态 |
+| `onboarding_closable` | bool | 快速设置权限步是否允许用户退出（= `mode == "review"`）。**客户端只读这一个字段决策** |
+
+Mock 出参:
+```json
+{
+  "mode": "review",
+  "onboarding_closable": true
+}
+```
+
+## 说明
+- **只有华为 ROM 客户端会来拉**（HarmonyOS / EMUI；荣耀 MagicOS 不拉）。机型判断在客户端做（`OemDetector`），服务端不看 UA，也就不用维护机型名单。
+- 客户端在进新手引导前拉一次并本地缓存；请求失败/超时用上次缓存值，从未拉到过则按 `onboarding_closable=false`（宁可不给退出按钮，也不误放开）。
+- 脏值兜底:DB 里 `mode` 不在枚举内时服务端一律回退 `default`。
+- 切回 `default` 即可一键收回退出按钮（审核通过后无需发版）。
@@ -1,33 +0,0 @@
-# POST /api/v1/signin/boost — 签到后看广告膨胀金币
-
-用户 Day1-Day13 当天已签到后，看完一条激励视频，由穿山甲 S2S 回调固定补发 2000 金币。本接口只用于 S2S 发奖后的确认。
-
-## 鉴权
-
-需要 Bearer token。
-
-## 请求体
-
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---:|---|
-| `ad_ref_id` | string | 是 | 穿山甲 S2S 回调的 `trans_id`。回调需先以 `extra.reward_scene=signin_boost` 完成发奖 |
-
-## 响应
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `coin_awarded` | int | 本次膨胀补发金币 |
-| `coin_balance` | int | 补发后的金币余额 |
-| `signin_date` | string | 被膨胀的签到日期，格式 `YYYY-MM-DD` |
-
-## 错误
-
- `401`: 未登录
- `409`: 缺少/无效广告回调记录，非本人广告，回调未发奖，当天未签到，Day14，或当天已经膨胀过
-
-## 数据写入
-
- 本接口不直接发奖;实际写入发生在 `/ad/pangle-callback` 的 `reward_scene=signin_boost` 分支。
- 回调写 `signin_boost_record` 新增一行，用 `(user_id, signin_date)` 唯一约束防重复。
- 回调使 `coin_account` 增加固定 `2000` 金币。
- 回调写入 `coin_transaction.biz_type=signin_boost`。
@@ -35,7 +35,7 @@
 | 资产卡 / 钱包余额 | [`coin_account`](./coin_account.md) | 一用户一行的金币+现金余额快照 |
 | 金币明细 | [`coin_transaction`](./coin_transaction.md) | 每次金币变动一笔流水 |
 | 现金明细 | [`cash_transaction`](./cash_transaction.md) | 每次现金变动一笔流水(分) |
-| 每日签到 | [`signin_record`](./signin_record.md) + [`signin_boost_record`](./signin_boost_record.md) | 7 天循环发币;签到后看广告可膨胀一次 |
+| 每日签到 | [`signin_record`](./signin_record.md) | 7 天循环发币。签到弹窗的「看广告膨胀」2026-07 起走 `reward_video`(按 eCPM 发,记 `ad_reward_record`),不再有独立的膨胀表 |
 | 一次性任务(开消息提醒等) | [`user_task`](./user_task.md) | 领一次发币 |
 | 看激励视频赚金币 | [`ad_reward_record`](./ad_reward_record.md) + [`ad_watch_log`](./ad_watch_log.md) + [`ad_ecpm_record`](./ad_ecpm_record.md) | 独立数据流:发奖 / 旧版观看时长 / 收益对账 |
 | 信息流/Draw 广告结算 | [`ad_feed_reward_record`](./ad_feed_reward_record.md) | 每展示满 10 秒累计一份奖励,完成后一次性入账;`ad_type`(feed/draw)+`feed_scene`(compare/coupon)分形态/场景 |
@@ -102,12 +102,11 @@
 | 注销 `DELETE /user` | `user` | U(软删:`phone→deleted_<id>`、`status=deleted`) |
 | 绑/解绑微信 `POST /wallet/bind-wechat`、`/unbind-wechat` | `user`.wechat_* | U |
 | 签到 `POST /signin/do` | `signin_record`(C) + `coin_account`(U) + `coin_transaction`(C `signin`) | 同事务 |
-| 签到膨胀 `POST /signin/boost` | `signin_boost_record`(C) + `coin_account`(U) + `coin_transaction`(C `signin_boost`) | 同事务;同日一次 |
 | 领任务 `POST /tasks/claim` | `user_task`(C) + `coin_account`(U) + `coin_transaction`(C `task_<key>`) | 同事务 |
 | 金币兑现金 `POST /wallet/exchange` | `coin_account`(U) + `coin_transaction`(C `exchange_out` −) + `cash_transaction`(C `exchange_in` +) | 同事务 |
 | 发起提现 `POST /wallet/withdraw` | `withdraw_order`(C `reviewing`,记 `source`) + `coin_account`(U 按 source 扣对应余额) + 流水(C −:`cash_transaction.withdraw` 或 `invite_cash_transaction.invite_withdraw`) | 同事务,**不打款**;#121 按 `source` 分账 |
 | 查提现状态 / 用户取消 `GET /wallet/withdraw/status` | `withdraw_order`(U) + 失败→对应账本退款流水(C `withdraw_refund` / `invite_withdraw_refund` +) | |
-| 穿山甲发奖 S2S 回调 `POST /ad/pangle-callback` | `ad_reward_record`(C)+ granted→`coin_account`(U)+`coin_transaction`(C `reward_video`/`signin_boost`) | `trans_id` 幂等 |
+| 穿山甲发奖 S2S 回调 `POST /ad/pangle-callback` | `ad_reward_record`(C)+ granted→`coin_account`(U)+`coin_transaction`(C `reward_video`) | `trans_id` 幂等 |
 | 看广告时长上报 `POST /ad/watch-report` | `ad_watch_log`(C) | |
 | 广告 eCPM 上报 `POST /ad/ecpm-report` | `ad_ecpm_record`(C) | |
 | 信息流广告结算 `POST /ad/feed-reward` | `ad_feed_reward_record`(C)+ granted→`coin_account`(U)+`coin_transaction`(C `feed_ad_reward`) | `client_event_id` 幂等 |
@@ -175,7 +174,7 @@
 ## 三、表间关系 & Join Key

 ### 硬外键(数据库 FK 约束)
- **19 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`invite_cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`signin_record`、`signin_boost_record`、`user_task`、`comparison_record`(2026-07 起 `user_id` **可空**——harvest 帧0 建行时软鉴权可能拿不到)、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback`、`device_liveness`。
+- **18 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`invite_cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`signin_record`、`user_task`、`comparison_record`(2026-07 起 `user_id` **可空**——harvest 帧0 建行时软鉴权可能拿不到)、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback`、`device_liveness`。
 - `admin_audit_log.admin_id` → `admin_user.id`。
 - `price_report.comparison_record_id` → `comparison_record.id`(可空:关联记录被删后仍留上报历史)。
 - **邀请两表** → `user.id`:`invite_relation.inviter_user_id`、`invite_relation.invitee_user_id`(唯一)、`invite_fingerprint.inviter_user_id`——注意 FK 列名是 `inviter`/`invitee_user_id`,不是 `user_id`。
@@ -187,7 +186,7 @@
  | biz_type | ref_id 指向 | amount 符号 |
  |---|---|---|
  | `signin` | 当天日期串(= `signin_record.signin_date` 的 ISO `YYYY-MM-DD`) | + |
-  | `signin_boost` | 当天日期串(= `signin_boost_record.signin_date` 的 ISO `YYYY-MM-DD`) | + |
+  | `signin_boost`(**历史,2026-07 已下线**) | 当时的广告 `trans_id`,无则当天日期 ISO 串。不再产生新行,存量保留供对账 | + |
  | `task_<key>` | `user_task.task_key` | + |
  | `reward_video` / `ad_reward`(历史) | `ad_reward_record.trans_id` | + |
  | `feed_ad_reward` | `ad_feed_reward_record.client_event_id` | + |
@@ -225,7 +224,7 @@
 user ─1:1─ coin_account
 user ─1:1─ wechat_transfer_authorization
 user ─1:N─ { coin_transaction, cash_transaction, invite_cash_transaction, withdraw_order,
-            signin_record, signin_boost_record, user_task, comparison_record(user_id 可空),
+            signin_record, user_task, comparison_record(user_id 可空),
            comparison_milestone_claim, savings_record, ad_reward_record, ad_watch_log,
            ad_ecpm_record, ad_feed_reward_record, price_report, feedback, device_liveness }
                                             (device_liveness 硬 FK; (user_id,device_id) 唯一)
@@ -255,7 +254,7 @@ launch_confirm_sample                        (独立, 无硬 FK; 都上报不去

 1. **余额快照** `coin_account`:`coin_balance`(金币个数)+ `cash_balance_cents`(现金分)+ `invite_cash_balance_cents`(邀请奖励金分,#82),一用户一行,读取展示用。
 2. **流水账本** `coin_transaction` / `cash_transaction` / `invite_cash_transaction`:每次变动写一笔,`balance_after*` 记变动后余额,可逐笔回溯对账。**现金与邀请奖励金是两本物理隔离的账**——发放口径与提现对账各自独立。
-3. **唯一变动入口**:金币走 `repositories/wallet.grant_coins`,邀请奖励金走 `grant_invite_cash`——都是「更新快照 + 写流水,**不 commit**,由调用方同一事务 commit」。signin / signin_boost / task / ad_reward / feed_ad_reward / exchange / admin 走 `grant_coins`;`invite_reward` / admin 调整走 `grant_invite_cash`,靠 `biz_type` 区分来源。
+3. **唯一变动入口**:金币走 `repositories/wallet.grant_coins`,邀请奖励金走 `grant_invite_cash`——都是「更新快照 + 写流水,**不 commit**,由调用方同一事务 commit」。signin / task / ad_reward / feed_ad_reward / exchange / admin 走 `grant_coins`(`signin_boost` 2026-07 已下线,存量流水保留);`invite_reward` / admin 调整走 `grant_invite_cash`,靠 `biz_type` 区分来源。

 - **汇率**:`10000 金币 = 1 元 = 100 分`(`rewards.COIN_PER_YUAN`);兑换额必须是整分倍数。
 - **提现状态机**:`reviewing`(发起即原子扣款、待人工审核、**不打款**)→ 审核通过 `pending`(微信转账在途)→ `success` / `failed`(失败自动退款);审核拒绝 `rejected`(退款)。**按 `withdraw_order.source` 分账**(#121):`coin_cash` 单的扣款/退款写 `cash_transaction`,`invite_cash` 单写 `invite_cash_transaction`;`out_bill_no` 幂等,孤儿 pending 单由 `reconcile_pending_withdraws` 对账兜底,admin `withdraws/ledger-check` 分账校验「单 ↔ 流水」。
@@ -35,7 +35,6 @@
 | `withdraw_order` | 提现单(现金→微信零钱,含人工审核态;`source` 分账 coin_cash/invite_cash) | `models/wallet.py` | [详情](./withdraw_order.md) |
 | `wechat_transfer_authorization` | 微信免确认转账授权(一用户一行) | `models/wallet.py` | [详情](./wechat_transfer_authorization.md) |
 | `signin_record` | 签到记录(7 天循环) | `models/signin.py` | [详情](./signin_record.md) |
-| `signin_boost_record` | 签到后看广告膨胀记录 | `models/signin.py` | [详情](./signin_boost_record.md) |
 | `user_task` | 一次性任务领取去重 | `models/task.py` | [详情](./user_task.md) |
 | `ad_reward_record` | 看激励视频发奖记录(S2S 回调,trans_id 幂等) | `models/ad_reward.py` | [详情](./ad_reward_record.md) |
 | `ad_watch_log` | 看广告观看时长(旧版兼容字段) | `models/ad_watch_log.py` | [详情](./ad_watch_log.md) |
@@ -2,7 +2,7 @@

 > 模型 `app/models/ad_reward.py` · 仓库 `app/repositories/ad_reward.py` · 接口 [ad-pangle-callback](../api/ad-pangle-callback.md) / [ad-reward-status](../api/ad-reward-status.md) / [ad-test-grant](../api/ad-test-grant.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

-每条 = 穿山甲一次**服务端激励回调**。`trans_id` 唯一做幂等键(穿山甲会重试,同号只处理一次)。`reward_scene` 区分普通激励视频、签到膨胀等场景;`reward_date`(北京时间日期串)给普通激励视频"每日上限"计数用。
+每条 = 穿山甲一次**服务端激励回调**。`trans_id` 唯一做幂等键(穿山甲会重试,同号只处理一次)。`reward_scene` 区分普通激励视频、提现看视频等场景;`reward_date`(北京时间日期串)给普通激励视频"每日上限"计数用。

 ## 用在哪 / 增删改查
 - **C(插入)**:`POST /ad/pangle-callback`(穿山甲 S2S,经 SHA256 验签;`grant_ad_reward` 或场景业务处理)或 `POST /ad/test-grant`(本地联调)。普通激励视频三道闸:① 验签不过 → API 层 403,不进库;② `trans_id` 已存在 → 原样返回不重复发;③ **当日发奖次数(`DAILY_AD_REWARD_LIMIT`,默认 500)到顶** → 记一行 `status='capped'`、`coin=0`、不发币。否则按 eCPM 公式发币。另:`POST /ad/reward-noshow`(`record_reward_noshow`,Bearer)在用户提前关/未发奖时记一行 `status='closed_early'`、`coin=0` 留痕(同 session 已 granted 则跳过)。
@@ -13,15 +13,16 @@
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | |
-| `trans_id` | String(64) | UNIQUE, index, NOT NULL | 穿山甲交易号(幂等键)。**被 `coin_transaction.ref_id` 引用**(biz_type=reward_video/signin_boost 等)。`closed_early` 留痕记录无 S2S 交易号,用合成键 `noreward:{ad_session_id}` |
+| `trans_id` | String(64) | UNIQUE, index, NOT NULL | 穿山甲交易号(幂等键)。**被 `coin_transaction.ref_id` 引用**(biz_type=reward_video 等)。`closed_early` 留痕记录无 S2S 交易号,用合成键 `noreward:{ad_session_id}` |
 | `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户(回调 media_extra 带回;不存在抛 UnknownUserError) |
-| `reward_scene` | String(32) | NOT NULL, default `reward_video` | 奖励场景:`reward_video` 普通激励视频;`signin_boost` 签到膨胀 |
+| `reward_scene` | String(32) | NOT NULL, default `reward_video` | 奖励场景:`reward_video` 普通激励视频(当前唯一发币场景);`withdrawal_ad` 提现门槛视频(只留痕不发币);`signin_boost` **历史值,2026-07 已下线** |
 | `ad_session_id` | String(64) | index, nullable | 客户端广告会话 ID,来自 `extra.ad_session_id`;用于匹配 `ad_ecpm_record` |
+| `boost_round_id` | String(64) | nullable | 「这条广告属于哪一轮膨胀」,来自 `extra.boost_round_id`。一轮 = 用户点「去膨胀」到点「放弃赚钱」之间连看的若干条。**纯标签,不参与发奖判定**;仅供 `/ad/reward-result` 求和出 `round_coin`(弹窗显示的累计值)。老客户端 / extra 丢失时 NULL |
 | `ecpm_raw` | String(32) | nullable | 本次发奖采用的 eCPM 原始值;可来自 S2S `ecpm` 或客户端上报 |
 | `app_env` | String(16) | nullable | 来源应用 `prod`(傻瓜比价)/`test`(测试);S2S 不带,发奖时按 `ad_session_id` 匹配 `ad_ecpm_record` 回填,查不到 NULL。广告收益报表金币侧按它聚合 |
 | `our_code_id` | String(64) | nullable | 我们配置的代码位 104xxx(同上回填) |
 | `coin` | Integer | NOT NULL, default 0 | 实发金币;`capped`/`ecpm_missing`/`closed_early`/业务不满足时为 0 |
-| `status` | String(16) | NOT NULL, default `granted` | 取值:`granted`(已发)/ `capped`(当日次数超限)/ `ecpm_missing`(缺 eCPM)/ `closed_early`(展示了但用户提前关/跳过,未发奖,客户端 reward-noshow 留痕)/ `not_signed`/`already_boosted`/`last_day`/ `unknown_scene`(回调 `reward_scene` 不在支持集合,只留痕不发) |
+| `status` | String(16) | NOT NULL, default `granted` | 取值:`granted`(已发)/ `capped`(当日次数超限)/ `ecpm_missing`(缺 eCPM)/ `closed_early`(展示了但用户提前关/跳过,未发奖,客户端 reward-noshow 留痕)/ `unknown_scene`(回调 `reward_scene` 不在支持集合,只留痕不发) |
 | `reward_date` | String(10) | index, NOT NULL | 北京时间日期串 `YYYY-MM-DD`,按它等值统计当日发奖次数 |
 | `reward_name` | String(64) | nullable | 穿山甲上报奖励名(参考,不作发奖依据) |
 | `raw` | String(1024) | nullable | 回调原始参数(审计排查) |
@@ -34,8 +35,10 @@

 ## 索引与约束
 - PK `id`;UNIQUE+index `trans_id`;index `user_id`、`reward_date`、`created_at`、`ad_session_id`。
+- 复合 index `ix_ad_reward_user_boost_round` = `(user_id, boost_round_id)`:算「本轮累计已发」用。**求和恒带 `user_id`** —— `boost_round_id` 是客户端生成的,不带 `user_id` 等于让任何人拿别人的轮 id 查别人发了多少。

 ## 注意
 - 普通激励视频按 eCPM 公式发奖;若 S2S 与客户端会话上报都缺 eCPM,记录 `status='ecpm_missing'`、`coin=0`,不发币。
- 签到膨胀复用本表记录 S2S 幂等,实发固定 `2000` 金币由 `signin_boost_record`/`coin_transaction.biz_type=signin_boost` 承载。
+- 签到膨胀(`reward_scene=signin_boost`)2026-07 已下线,存量行保留供对账;签到弹窗的「看广告膨胀」现与福利页看视频同走 `reward_video`(按 eCPM 公式发)。
+- **膨胀轮累计**:`SUM(coin) WHERE user_id=? AND boost_round_id=? AND status='granted'`,由 `/ad/reward-result` 返回为 `round_coin`。客户端就算一直复用同一个轮 id,也只是把展示数字滚大 —— 求和的是**已发生**的发奖记录,不产生任何新入账,无资损风险。
 - 并发同 `trans_id` 撞唯一约束 → catch IntegrityError 回滚返回已存在那条(幂等兜底)。
@@ -14,7 +14,7 @@
 ## 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
 |---|---|---|---|
-| `key` | String(64) | **PK** | 配置标识,取值见 `config_schema.CONFIG_DEFS`:`signin_rewards` / `min_exchange_coin` / `withdraw_min_cents` / `withdraw_max_cents` / `task_rewards` / `record_milestones` / `ad_reward_coin` / `ad_daily_limit` / `ad_max_coin` / `ad_round_count` / `ad_cooldown_sec` / `signin_boost_coin` / `withdraw_auto_reconcile_enabled` / `comparing_ad_enabled` |
+| `key` | String(64) | **PK** | 配置标识,取值见 `config_schema.CONFIG_DEFS`:`signin_rewards` / `min_exchange_coin` / `withdraw_min_cents` / `withdraw_max_cents` / `task_rewards` / `record_milestones` / `ad_reward_coin` / `ad_daily_limit` / `ad_max_coin` / `ad_round_count` / `ad_cooldown_sec` / `withdraw_auto_reconcile_enabled` / `comparing_ad_enabled` |
 | `value` | JSON(PG: JSONB) | NOT NULL | 配置值,类型随 key(`int` / `int_list` 如签到 14 档 / `dict_str_int` 如 task_rewards / `bool` 如 withdraw_auto_reconcile_enabled / comparing_ad_enabled) |
 | `updated_by_admin_id` | Integer | nullable | 最后修改的管理员 id(= `admin_user.id`,软引用,无 FK) |
 | `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 最后修改时间 |
@@ -29,3 +29,12 @@
 ## 注意
 - 不缓存:配置读频率低(每次福利操作读一次,主键查极快),admin 改了立即生效、跨进程一致(多 worker 也对)。
 - 新增可配项 = 在 `CONFIG_DEFS` 加一条 + 业务处改用 `app_config.get_value(db, key)` 读;不需要建迁移(行是动态插的,表结构不变)。
+
+## 专用 key(借表不进 CONFIG_DEFS)
+有自己的语义与专用管理页的配置,复用本表但**不注册进 `CONFIG_DEFS`**——混进通用「系统配置」页只会显示成一个没头没尾的 on/off。它们各有一对 `get_*` / `set_*` 函数(仍在 `repositories/app_config.py`),`value` 存 dict,空行回退各自的模块内默认值。
+
+| key | 管理页 / admin 端点 | C 端读取 | 说明 |
+|---|---|---|---|
+| `ad_config` | `GET/PATCH /admin/api/ad-config` | `GET /api/v1/platform/ad-config`(去密钥) | 穿山甲 app_id / 各代码位 / 各场景开关 |
+| `app_version` | 内部写入(`X-Internal-Secret`) | `GET /api/v1/platform/app-version` | OTA 最新版本信息 |
+| `huawei_review` | `GET/PATCH /admin/api/huawei-review` | `GET /api/v1/platform/huawei-review` | 华为审核开关:`{"mode": "default"｜"review"}`,决定新手引导「快速设置」权限步能否被用户关闭。脏值/空行一律回退 `default`(不给退出按钮) |
@@ -10,7 +10,7 @@
  | 动作 / endpoint | `biz_type` | `amount` | `ref_id` 指向 |
  |---|---|---|---|
  | 签到 `POST /signin/do` | `signin` | + | 当天日期串(= `signin_record.signin_date` ISO) |
-  | 签到后看广告膨胀 `POST /signin/boost` | `signin_boost` | + | 广告 `trans_id`(= `signin_boost_record.ad_ref_id`);无 ad_ref_id 时回退当天日期 ISO 串 |
+  | ~~签到后看广告膨胀~~(**2026-07 已下线**) | `signin_boost` | + | 历史行:当时的广告 `trans_id`,无则当天日期 ISO 串。不再产生新行;签到弹窗的看广告改走 `reward_video` |
  | 领任务 `POST /tasks/claim` | `task_<key>`(如 `task_enable_notification`) | + | 一次性任务=`user_task.task_key`;可重复任务(`enable_notification`)=带序号 `task_key:N` |
  | 普通激励视频 S2S 回调 `POST /ad/pangle-callback` | `reward_video`(历史兼容:`ad_reward`) | + | `ad_reward_record.trans_id` |
  | 信息流广告结算 `POST /ad/feed-reward` | `feed_ad_reward` | + | `ad_feed_reward_record.client_event_id` |
@@ -36,7 +36,7 @@

 ## 关系 / Join Key
 - `user_id` → `user.id`(多对一)。
- `ref_id` 是**软关联**(无 FK),目标随 `biz_type`:`signin`→签到日(`signin_record.signin_date` ISO) / `signin_boost`→`signin_boost_record.ad_ref_id`(无则当天日期) / `task_<key>`→一次性任务=`user_task.task_key`、可重复任务=`task_key:N` / `reward_video`/`ad_reward`→`ad_reward_record.trans_id` / `feed_ad_reward`→`ad_feed_reward_record.client_event_id` / 其余 null。
+- `ref_id` 是**软关联**(无 FK),目标随 `biz_type`:`signin`→签到日(`signin_record.signin_date` ISO) / `signin_boost`(历史)→当时的广告 `trans_id`(无则当天日期) / `task_<key>`→一次性任务=`user_task.task_key`、可重复任务=`task_key:N` / `reward_video`/`ad_reward`→`ad_reward_record.trans_id` / `feed_ad_reward`→`ad_feed_reward_record.client_event_id` / 其余 null。

 ## 索引与约束
 - PK `id`;index `user_id`、`created_at`。
@@ -1,22 +0,0 @@
-# signin_boost_record — 签到膨胀记录
-
-App 用户当天签到后，看完激励视频可固定膨胀一次（默认 3000 金币，`rewards.SIGNIN_BOOST_COIN`，运营后台 `app_config.signin_boost_coin` 可改）。循环最后一天（`cycle_day == SIGNIN_CYCLE_LEN`，即 7 天循环的第 7 天）不展示也不允许膨胀。本表记录膨胀动作，并用唯一约束防重复补发。
-
-## 字段
-
-| 字段 | 类型 | 约束 | 说明 |
-|---|---|---|---|
-| `id` | Integer | PK | 自增主键 |
-| `user_id` | Integer | FK → `user.id`, index, NOT NULL | 用户 |
-| `signin_date` | Date | NOT NULL | 被膨胀的签到日期，北京时间 |
-| `coin_awarded` | Integer | NOT NULL | 本次补发金币,默认固定 3000(`rewards.get_signin_boost_coin`) |
-| `ad_ref_id` | String(64) | nullable | 穿山甲 S2S 回调 `trans_id` |
-| `created_at` | DateTime(tz) | server_default now(), NOT NULL | 创建时间 |
-
-## 约束
-
- `UNIQUE(user_id, signin_date)` = `uq_signin_boost_user_date`：同一用户同一天只能膨胀一次。
-
-## 关联
-
- 膨胀成功时写 `coin_transaction.biz_type=signin_boost`，`ref_id = ad_ref_id`(无 ad_ref_id 时回退当天日期 ISO 串)。
@@ -29,7 +29,7 @@
 | `last_login_at` | DateTime(tz) | 应用层 default utcnow | 最近登录时间(每次登录更新) |

 ## 关系 / Join Key
- **被引用方(本表是 1,对方是 N/1)**:`coin_account`、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`、`signin_record`、`signin_boost_record`、`user_task`、`comparison_record`、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback` 的 `user_id` 均 → `user.id`;`invite_relation` 的 `inviter_user_id` / `invitee_user_id` 均 → `user.id`。
+- **被引用方(本表是 1,对方是 N/1)**:`coin_account`、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`、`signin_record`、`user_task`、`comparison_record`、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback` 的 `user_id` 均 → `user.id`;`invite_relation` 的 `inviter_user_id` / `invitee_user_id` 均 → `user.id`。
 - 与 `admin_user` **无任何关联**(C 端用户 vs 后台管理员,两套体系)。

 ## 索引与约束
@@ -27,7 +27,6 @@
 | 钱包 | `withdraw_order` | 提现单 | 现金→微信零钱提现 |
 | 钱包 | `wechat_transfer_authorization` | 微信转账免确认授权 | 用户授权后转账免逐笔确认 |
 | 激励 | `signin_record` | 签到记录 | 每日签到 |
-| 激励 | `signin_boost_record` | 签到膨胀记录 | 签到后看广告翻倍补发 |
 | 激励 | `user_task` | 一次性任务完成 | 只能领一次的任务 |
 | 激励 | `comparison_milestone_claim` | 比价战绩领取 | 比价次数里程碑奖励 |
 | 比价 | `comparison_record` | 比价记录 | 用户视角「我的比价记录」 |
@@ -181,18 +180,6 @@ App 用户主表。两种登录（极光一键 / 短信验证码）都映射到
 | coin_awarded | 整数 | 本次发放金币 |
 | created_at | 时间 | 时间 |

-## `signin_boost_record` — 签到膨胀记录
-
-签到后看广告「膨胀」翻倍，一天最多一次，补发金额=当天签到原始奖励。
-
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| id | 整数 | **主键** |
-| user_id | 整数 | **外键→user** |
-| signin_date | 日期 | 与 user_id 组成**唯一**（防并发重复补发） |
-| coin_awarded | 整数 | 补发金币 |
-| ad_ref_id | 字符串 | 广告会话/交易号，可空 |
-| created_at | 时间 | 时间 |

 ## `user_task` — 一次性任务完成记录

@@ -379,7 +366,7 @@ profile「累计帮你省了」「省钱战绩」的唯一数据源。(user_id,
 | user_id | 整数 | **外键→user** |
 | coin | 整数 | 实发金币（超限为 0） |
 | status | 字符串 | granted（已发）/ capped（当日超限）/ ecpm_missing（缺 eCPM） |
-| reward_scene | 字符串 | reward_video（福利页看视频）/ signin_boost（签到膨胀） |
+| reward_scene | 字符串 | reward_video（福利页看视频，当前唯一发币场景）/ withdrawal_ad（提现门槛视频，不发币）/ signin_boost（**历史值，2026-07 已下线**） |
 | ad_session_id | 字符串 | 广告会话 id，可空 |
 | ecpm_raw | 字符串 | 本次发奖采用的 eCPM 原始值，可空 |
 | app_env | 字符串 | 应用环境 prod/test（回填），可空 |
@@ -70,7 +70,7 @@
 ## C. 部署 + 包名

 - [ ] **后端部署到公网**(由服务器管理员;`/opt/shaguabijia-app-server`,uvicorn 127.0.0.1:8770,nginx 反代)
- [ ] **跑迁移**:`alembic upgrade head`(包含 `ad_reward_record`、`signin_boost_record`、`ad_feed_reward_record` 等表)
+- [ ] **跑迁移**:`alembic upgrade head`(包含 `ad_reward_record`、`ad_feed_reward_record` 等表)
 - [ ] **包名定稿**:当前 `com.jishisongfu.shaguabijia`。穿山甲(APP_ID 5830519)、极光、微信都绑"包名 + 签名",定了再上,别再换
  - 微信提现链路当前因复用 elderhelper 的 appid + 包名切换已 dead,要恢复需申请傻瓜比价自己的微信 appid(另见客户端 build.gradle 注释)
 - [ ] (可选,提升真实填充)集成 **MSA OAID SDK**:申请证书(绑包名、审核几天)。App 侧当前 `getDevOaid=null`,有 OAID 后投放匹配 + 填充会明显改善
@@ -38,8 +38,8 @@

 | 决策点 | 结论 | 理由 |
 |---|---|---|
-| **活跃口径** | 与"用户管理"一致：`max(首页可见 show/home, 比价, 领券)`，**不含 last_login_at**；无任何信号时以 `created_at` 为非空基线 | 比价可从**浮窗**触发、不进首页；`last_login_at` 只在登录/换绑动作更新（re-login 也算），代表不了"在用 App"，故彻底排除 |
-| **"进首页"信号落地** | **方案 A：前端上报 `home_view` 埋点**（复用 `/analytics/events`），非新接口 | 三个活跃信号统一为同类埋点事件；零新接口零新列；与 admin 口径天然一致。B（鉴权接口 + 列）"更权威"的优势是假的——比价/领券仍是端上报事件，最弱环决定整体可信度 |
+| **活跃口径** | 与"用户管理"一致：`max(首页可见 home_visible, 比价, 领券)`，**不含 last_login_at**；无任何信号时以 `created_at` 为非空基线 | 比价可从**浮窗**触发、不进首页；`last_login_at` 只在登录/换绑动作更新（re-login 也算），代表不了"在用 App"，故彻底排除 |
+| **"进首页"信号落地** | **方案 A：前端上报 `home_visible` 埋点**（复用 `/analytics/events`），非新接口 | 三个活跃信号统一为同类埋点事件；零新接口零新列；与 admin 口径天然一致。B（鉴权接口 + 列）"更权威"的优势是假的——比价/领券仍是端上报事件，最弱环决定整体可信度 |
 | **清零范围** | **金币 + 折算现金**（**邀请现金不清**——产品红线，仅快照入审计） | 对应"账户里的金币和现金"；邀请奖励金与金币现金物理隔离、不可累加，见 `wallet.CoinAccount` 注释 |
 | **预警推送** | **可插拔通知器 + 日志占位**（v1），后续接 JPush/短信 | 现状无真实推送能力；先把清零主流程 + 审计做扎实，不阻塞 |
 | **预警时机** | **完全可配置**（提前天数列表 + 次数 + 执行点 + 通道） | R5 |
@@ -76,7 +76,7 @@ last_active = max(
 ### 模块内容

 - 常量：
-  - **首页可见活跃信号已定名：`event=show` + `page=home`**（前端确认，原占位 `home_view`；下文出现的 `home_view` 均指此信号）。活跃行为过滤见 `activity.active_event_condition()`：首页可见 ∪ 比价 `real_compare_start` ∪ 领券 `real_coupon_start`；`ACTIVE_EVENTS` 仅含后两个纯 event 名（首页可见是 event+page 组合、单列）。
+  - **首页可见活跃信号已定名：`event=home_visible`**（前端最终确认；曾用过渡期 `show`+`page=home` 组合，已废弃）。活跃行为过滤见 `activity.active_event_condition()`：首页可见 `home_visible` ∪ 比价 `real_compare_start` ∪ 领券 `real_coupon_start`——三者均为纯 event 名，全部收进 `ACTIVE_EVENTS`。
  - `ACTIVE_ENGAGE_TYPE = "claim_started"`
 - `last_active_subqueries(db)` —— 复刻现 admin `queries._last_active_parts()`：两个按 `user_id` 的 `GROUP BY max(created_at)` 聚合子查询。
 - `last_active_expr(base_col, ev_sub, eng_sub, dialect)` —— 生成 `greatest`/`max`（PG `func.greatest`／SQLite `func.max`）；子聚合缺失时 `coalesce(子聚合, User.created_at)` 兜底（注册基线恒非空，**替代原 last_login_at**）。
@@ -210,7 +210,7 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现

 ## 9. 幂等与重新活跃

- **重新活跃自动退出**：`inactive_days` 由 §4 口径**实时算**。用户一有 `home_view`/比价/领券（**登录本身不算**），`last_active` 前移，自动移出预警与清零队列。**无需**显式"重置标记"。
+- **重新活跃自动退出**：`inactive_days` 由 §4 口径**实时算**。用户一有 `home_visible`/比价/领券（**登录本身不算**），`last_active` 前移，自动移出预警与清零队列。**无需**显式"重置标记"。
 - **预警去重**：`inactivity_notification_log` 中存在 `stage==k 且 created_at > last_active` 的行 ⟹ 本 streak 已推过档 `k`，不重推。用户回归后 `last_active` 前移，旧预警行自然"失效"，开启新 streak。
 - **清零幂等**：阶段 B 只处理三桶非全 0 者；清完 = 0，次日不再匹配。worker 重启 / 多次唤醒 / 补跑均安全，不产生重复清零或重复流水。
 - **稳健补发**：worker 漏跑数天后，某用户可能同时满足多档；只补发**最紧急的未推档**（最小 `k`），避免一次刷屏。
@@ -221,7 +221,7 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现

 | 场景 | 处理 |
 |---|---|
-| 新用户 | `created_at` 作活跃基线（恒非空）→ 注册即"第 1 日活跃"；注册后连续 15 天无 home_view/比价/领券 才清 |
+| 新用户 | `created_at` 作活跃基线（恒非空）→ 注册即"第 1 日活跃"；注册后连续 15 天无 home_visible/比价/领券 才清 |
 | 在途提现 | 提现申请时现金已扣入 `WithdrawOrder`，当前余额已不含在途；只清当前余额、不动提现单。提现失败退款到已清账户 = 用户的钱，正常 |
 | 与 `daily_auto_exchange` 并存 | 各自逐用户幂等；金币多已日结折现金，三桶全清正好覆盖 |
 | 时区/日界 | 统一北京（`rewards.cn_today()`/`CN_TZ`）；**清零/预警按北京自然日 0 点对齐**（末次活跃记为第 1 日 → 第 16 日 0 点清零，见 §4），非滚动 24h；流水 `created_at` 沿用北京 wall-clock naive |
@@ -229,11 +229,11 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现

 ---

-## 11. 前端依赖：`home_view` 埋点（跨仓 — Android）
+## 11. 前端依赖：`home_visible` 埋点（跨仓 — Android）

- **Android 端**（`shaguabijia-app-android`）需在**首页可见**（`onResume`/Tab 切入）时，向现有 `POST /api/v1/analytics/events` 批量上报里加一条 `event=<首页可见事件名>`（名称明天加埋点时定，暂记 `"home_view"`） 的事件，**携带登录后的 `user_id`**。
+- **Android 端**（`shaguabijia-app-android`）需在**首页可见**（`onResume`/Tab 切入）时，向现有 `POST /api/v1/analytics/events` 批量上报里加一条 `event=home_visible`（前端已定名）的事件，**携带登录后的 `user_id`**。
 - 客户端按会话/前台去重即可（服务端只取 `max(created_at)`，多报无害）。
- **上线顺序依赖**：`home_view` 全量覆盖前，"进首页"信号缺失，只有比价/领券能推进活跃、其余落到 `created_at` 基线（"只开首页不操作"且注册满 15 天的用户会被误清）—— 故**开真清（`ENABLED=true`）必须待 `home_view` 铺满后再开**（§13）；dry-run 只记名单不动钱、可先开着看。
+- **上线顺序依赖**：`home_visible` 全量覆盖前，"进首页"信号缺失，只有比价/领券能推进活跃、其余落到 `created_at` 基线（"只开首页不操作"且注册满 15 天的用户会被误清）—— 故**开真清（`ENABLED=true`）必须待 `home_visible` 铺满后再开**（§13）；dry-run 只记名单不动钱、可先开着看。

 ---

@@ -241,25 +241,25 @@ INACTIVITY_RESET_CHECK_INTERVAL_SEC = 1800  # worker 唤醒间隔（可复用现

 - `app/admin/repositories/queries.py`：删本地 `_ACTIVE_EVENTS`/`_last_active_parts()`，改用 `activity.py` 的常量与子查询构造；`list_users` 的 `greatest(...)` 排序/筛选、`_attach_last_active` 均改走共享构造器。
 - `app/admin/repositories/stats.py`：`COMPARE_START_EVENT`/`COUPON_START_EVENT`/活跃用户集（`:138-146`）改用共享常量与口径。
- **行为变化（预期内、需产品知会）**：admin 的"最近活跃 / DAU"口径变化——**移除 `last_login_at`（登录不再计为活跃）、以 `created_at` 为基线、纳入 `home_view`**。net：`home_view` 铺满后更准（真正把"开首页"算进活跃）；铺满前"只登录不操作"的用户活跃度会下降。
- **回归底线**：现有 admin 用户列表 / stats 测试按新口径**更新预期**（last_login_at 移除 + created_at 基线 + home_view 纳入）；非活跃口径部分行为不变。
+- **行为变化（预期内、需产品知会）**：admin 的"最近活跃 / DAU"口径变化——**移除 `last_login_at`（登录不再计为活跃）、以 `created_at` 为基线、纳入 `home_visible`**。net：`home_visible` 铺满后更准（真正把"开首页"算进活跃）；铺满前"只登录不操作"的用户活跃度会下降。
+- **回归底线**：现有 admin 用户列表 / stats 测试按新口径**更新预期**（last_login_at 移除 + created_at 基线 + home_visible 纳入）；非活跃口径部分行为不变。

 ---

 ## 13. 灰度与上线顺序（安全优先）

 1. **后端先行**：合入共享模块 + 两表 + worker + 通知器，`INACTIVITY_RESET_ENABLED=False`；活跃口径以 `created_at` 为非空基线、**不含 last_login_at**。
-2. **Android 发版**：上报 `home_view`；观察 analytics 覆盖率。
+2. **Android 发版**：上报 `home_visible`；观察 analytics 覆盖率。
 3. **dry-run 灰度（默认即是）**：`INACTIVITY_RESET_ENABLED=False` 时 worker 常驻只写审计名单（`reason=inactive_Nd_dryrun`）、不动钱、不预警；核对名单准确。
 4. **开真清**：确认无误后置 `INACTIVITY_RESET_ENABLED=True`（转为真清 + 预警）。
-5. **收尾/监控**：持续观察 `home_view` 覆盖率与预警/清零名单；发现"活跃却被判不活跃"的漏报即回查埋点覆盖（口径已不含 last_login_at，登录不再兜底）。
+5. **收尾/监控**：持续观察 `home_visible` 覆盖率与预警/清零名单；发现"活跃却被判不活跃"的漏报即回查埋点覆盖（口径已不含 last_login_at，登录不再兜底）。

 ---

 ## 14. 测试计划

- **活跃口径（共享模块）**：`home_view`/比价/领券 各单独命中都算活跃；**纯登录不算**；无信号用户以 `created_at` 计；`max` 取最新；naive/aware 混算不崩。
- **admin 回归**：用户列表 / stats 按新口径更新预期（移除 last_login_at + created_at 基线 + home_view）。
+- **活跃口径（共享模块）**：`home_visible`/比价/领券 各单独命中都算活跃；**纯登录不算**；无信号用户以 `created_at` 计；`max` 取最新；naive/aware 混算不崩。
+- **admin 回归**：用户列表 / stats 按新口径更新预期（移除 last_login_at + created_at 基线 + home_visible）。
 - **不活跃判定**：`last_active` 分别 `<15d / =15d / >15d` × 有/无余额 的命中矩阵。
 - **清零**：三桶归零；`inactivity_reset_log` 清前值正确；三条流水 `biz_type=inactivity_reset`、`balance_after=0`、`ref_id=log.id`；`total_coin_earned` 不变。
 - **预警**：命中窗口调 notifier + 写 `notification_log`；同 streak 不重推；回归后 `last_active` 前移可再次预警；漏跑补发最紧急档。