fix(ad-revenue): 报表收益按满额钳顶 + 新增 app_env 过滤 (#93)

广告收益报表两处隐患修复(admin/repositories/ad_revenue.py + routers/ad_revenue.py):

- 收益钳顶:单次展示收益原用裸 parse_ecpm_yuan、未钳上限;发奖侧 calculate_ad_reward_coin
  已钳 AD_ECPM_MAX_FEN(¥500 CPM)。异常/伪造天价 eCPM 会让报表预估收益虚高任意大。改为
  min(parse_ecpm_yuan, AD_ECPM_MAX_FEN/100)/1000,与发奖同口径。
- app_env 过滤:报表聚合原无 app_env 过滤,测试应用假 eCPM(如 ¥678 CPM)会进正式收益合计/平均。
  新增 app_env 参数(repository + router Query),显式传 prod/test 才过滤;默认仍全部(不擅自改成
  默认排除 test:本地 dev 库多为 test 会空、且属产品口径)。穿山甲后台收益列暂未联动此过滤。

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

---------

Co-authored-by: zzhyyyyy <2685922758@qq.com>
Reviewed-on: #93
Co-authored-by: zhuzihao <zhuzihao@wonderable.ai>
Co-committed-by: zhuzihao <zhuzihao@wonderable.ai>

.env.example

@@ -117,3 +117,16 @@ PANGLE_REWARD_SECRET=
 # ⚠️ 仅本地联调:true 时开放 POST /api/v1/ad/test-grant,让 debug 客户端看完广告直接发奖,
 # 验证"看广告→金币到账"全链路(未部署公网、穿山甲 S2S 打不到本地时用)。生产必须 false(绕过反作弊)。
 AD_REWARD_TEST_GRANT_ENABLED=false
+
+# ===== 穿山甲 GroMore 数据 API(按天拉收益报表,供后台广告收益报表的「穿山甲后台收益」)=====
+# ⚠️ 与上面发奖回调的 m-key 是【两套不同凭证】:这三样在穿山甲后台「接入中心 → GroMore-API →
+# 聚合数据报告 API」文档页领取。只读拉取 GroMore 天级 revenue(预估)/ api_revenue(收益Api),
+# 不参与发奖。三样齐全才生效;留空 = scripts/sync_pangle_revenue 直接 no-op。
+# 子账号(role_id≠user_id)需主账号在「角色管理」授予「查看全部数据」权限,否则查不到收益(接口 118);
+# role_id 填成 = user_id 即查主账号数据。同步:线上每天 ~10:30 由 timer 跑 python -m scripts.sync_pangle_revenue。
+PANGLE_REPORT_USER_ID=0
+PANGLE_REPORT_ROLE_ID=0
+PANGLE_REPORT_SECURITY_KEY=
+# GroMore AppId(报表 site_id 维度)→ 应用环境;默认取现网两个应用,按需覆盖。
+PANGLE_REPORT_SITE_ID_PROD=5830519
+PANGLE_REPORT_SITE_ID_TEST=5832303

alembic/versions/1699fc2c069f_add_analytics_event_table.py

@@ -0,0 +1,65 @@
+"""add analytics_event table
+
+Revision ID: 1699fc2c069f
+Revises: bcfcaf07152b
+Create Date: 2026-06-26 16:35:16.133975
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = '1699fc2c069f'
+down_revision: str | Sequence[str] | None = 'bcfcaf07152b'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('analytics_event',
+    sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+    sa.Column('event', sa.String(length=64), nullable=False),
+    sa.Column('props', sa.JSON(), nullable=True),
+    sa.Column('device_id', sa.String(length=64), nullable=False),
+    sa.Column('user_id', sa.Integer(), nullable=True),
+    sa.Column('session_id', sa.String(length=64), nullable=True),
+    sa.Column('client_ts', sa.BigInteger(), nullable=False),
+    sa.Column('sent_at', sa.BigInteger(), nullable=True),
+    sa.Column('page', sa.String(length=64), nullable=True),
+    sa.Column('client_ip', sa.String(length=64), nullable=True),
+    sa.Column('oem', sa.String(length=32), nullable=True),
+    sa.Column('os', sa.String(length=32), nullable=True),
+    sa.Column('model', sa.String(length=64), nullable=True),
+    sa.Column('app_ver', sa.String(length=32), nullable=True),
+    sa.Column('network', sa.String(length=16), nullable=True),
+    sa.Column('channel', sa.String(length=32), nullable=True),
+    sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.text('(CURRENT_TIMESTAMP)'), nullable=False),
+    sa.PrimaryKeyConstraint('id')
+    )
+    with op.batch_alter_table('analytics_event', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_analytics_event_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_event_device_id'), ['device_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_event_event'), ['event'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_event_session_id'), ['session_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_event_user_id'), ['user_id'], unique=False)
+
+    # 注:autogenerate 顺带检出 ad_ecpm/cps_*/invite_fingerprint 的历史索引漂移,
+    # 与本次「新增埋点表」无关,已手动移除,避免本迁移误改他人表。
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    with op.batch_alter_table('analytics_event', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_analytics_event_user_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_event_session_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_event_event'))
+        batch_op.drop_index(batch_op.f('ix_analytics_event_device_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_event_created_at'))
+
+    op.drop_table('analytics_event')
+    # ### end Alembic commands ###

alembic/versions/7db22acee504_merge_invite_cash_analytics_device_heads.py

@@ -0,0 +1,26 @@
+"""merge invite_cash + analytics + device heads
+
+Revision ID: 7db22acee504
+Revises: c2874d2bf705, device_first_protected_at, invite_cash_compare_reward
+Create Date: 2026-06-27 03:06:52.594401
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '7db22acee504'
+down_revision: Union[str, Sequence[str], None] = ('c2874d2bf705', 'device_first_protected_at', 'invite_cash_compare_reward')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/ad_pangle_daily_revenue.py

@@ -0,0 +1,63 @@
+"""ad_pangle_daily_revenue: 穿山甲 GroMore 天级收益报表(后台结算口径)
+
+新建表存放从 GroMore 数据 API 按天拉取的收益(revenue 预估 + api_revenue 收益Api),
+粒度 = 日期 × 应用(app_env) × 代码位(our_code_id) × 广告源(adn)。供广告收益报表的
+汇总/趋势级展示「穿山甲后台收益」,与客户端自报 eCPM 折算的预估互为对照。
+
+Revision ID: ad_pangle_daily_revenue
+Revises: 7db22acee504
+Create Date: 2026-06-28
+"""
+
+from __future__ import annotations
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision = "ad_pangle_daily_revenue"
+down_revision = "7db22acee504"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "ad_pangle_daily_revenue",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("report_date", sa.String(length=10), nullable=False),
+        sa.Column("app_env", sa.String(length=16), nullable=False),
+        sa.Column("site_id", sa.String(length=32), nullable=True),
+        sa.Column("our_code_id", sa.String(length=64), nullable=False),
+        sa.Column("adn", sa.String(length=16), nullable=False, server_default=""),
+        sa.Column("revenue_yuan", sa.Float(), nullable=False, server_default="0"),
+        sa.Column("api_revenue_yuan", sa.Float(), nullable=True),
+        sa.Column("ecpm", sa.String(length=32), nullable=True),
+        sa.Column("impressions", sa.Integer(), nullable=False, server_default="0"),
+        sa.Column("currency", sa.String(length=8), nullable=False, server_default="cny"),
+        sa.Column(
+            "synced_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.UniqueConstraint(
+            "report_date", "app_env", "our_code_id", "adn", name="uq_ad_pangle_daily"
+        ),
+    )
+    op.create_index(
+        "ix_ad_pangle_daily_revenue_report_date",
+        "ad_pangle_daily_revenue",
+        ["report_date"],
+    )
+    op.create_index(
+        "ix_ad_pangle_daily_revenue_our_code_id",
+        "ad_pangle_daily_revenue",
+        ["our_code_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_ad_pangle_daily_revenue_our_code_id", table_name="ad_pangle_daily_revenue")
+    op.drop_index("ix_ad_pangle_daily_revenue_report_date", table_name="ad_pangle_daily_revenue")
+    op.drop_table("ad_pangle_daily_revenue")

alembic/versions/c2874d2bf705_add_ad_type_to_ad_feed_reward_and_feed_.py

@@ -0,0 +1,46 @@
+"""add ad_type to ad_feed_reward and feed_scene to ad_ecpm
+
+把信息流广告全面改造成 Draw 信息流(draw):
+- ad_feed_reward_record.ad_type:广告形态 feed(信息流) / draw(Draw 信息流)。可空,旧数据 NULL
+  一律视为 feed(向后兼容);每日上限与因子2(LT)仍按本表全表 unit 累计,不按 ad_type 拆。
+- ad_ecpm_record.feed_scene:点位场景 comparison(比价) / coupon(领券) / welfare(福利),供广告
+  收益报表区分比价/领券 Draw 收益;仅信息流/Draw 上报,激励视频为 NULL。
+
+注:autogenerate 会顺带探测到 analytics_event / cps_* / invite_fingerprint 等无关索引差异(本地库与
+metadata 漂移、analytics 模型尚未并入 __init__),与本次改动无关,已手工剔除——本迁移只 add 两列。
+SQLite 经 env.py 的 render_as_batch 自动走 batch_alter_table 重建表。
+
+Revision ID: c2874d2bf705
+Revises: 1699fc2c069f
+Create Date: 2026-06-26 16:48:52.158609
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "c2874d2bf705"
+down_revision: str | Sequence[str] | None = "1699fc2c069f"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # 信息流发奖记录:新增广告形态 feed/draw(可空,旧数据 NULL=feed)
+    op.add_column(
+        "ad_feed_reward_record",
+        sa.Column("ad_type", sa.String(length=16), nullable=True),
+    )
+    # eCPM 展示上报:新增点位场景 comparison/coupon/welfare(可空,激励视频/旧数据 NULL)
+    op.add_column(
+        "ad_ecpm_record",
+        sa.Column("feed_scene", sa.String(length=16), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("ad_ecpm_record", "feed_scene")
+    op.drop_column("ad_feed_reward_record", "ad_type")

alembic/versions/device_first_protected_at.py

@@ -0,0 +1,31 @@
+"""device_liveness 加 first_protected_at(首次开无障碍时刻)
+
+Revision ID: device_first_protected_at
+Revises: bcfcaf07152b
+Create Date: 2026-06-25 00:00:00.000000
+
+admin 设备存活页要展示「首次无障碍开启时间」。touch_heartbeat 在 ever_protected 首次翻 true
+时记一次(后续心跳不覆盖)。仅新增可空列,SQLite 原生支持 add_column、不用 batch;downgrade
+的 drop_column 在 SQLite 走 batch_alter_table 兜底。老设备无此时刻 → 留 NULL(无法准确回填)。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "device_first_protected_at"
+down_revision: Union[str, Sequence[str], None] = "bcfcaf07152b"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "device_liveness",
+        sa.Column("first_protected_at", sa.DateTime(timezone=True), nullable=True),
+    )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("device_liveness") as batch_op:
+        batch_op.drop_column("first_protected_at")

alembic/versions/feedback_submit_env.py

@@ -0,0 +1,34 @@
+"""feedback 加提交端环境快照(app_version / device_model / rom_name / android_version)
+
+Revision ID: feedback_submit_env
+Revises: ad_pangle_daily_revenue
+Create Date: 2026-06-29 00:00:00.000000
+
+admin 用户反馈页要展示「提交版本号」「机型OS版本」,需在提交时落库端环境。仅新增可空列,
+SQLite 原生支持 add_column、不用 batch;downgrade 的 drop_column 在 SQLite 走 batch 兜底。
+历史反馈无此快照 → 留 NULL(无法回填);客户端改版带上后的新反馈才有值。
+"""
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+revision: str = "feedback_submit_env"
+down_revision: Union[str, Sequence[str], None] = "ad_pangle_daily_revenue"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.add_column("feedback", sa.Column("app_version", sa.String(length=32), nullable=True))
+    op.add_column("feedback", sa.Column("device_model", sa.String(length=64), nullable=True))
+    op.add_column("feedback", sa.Column("rom_name", sa.String(length=32), nullable=True))
+    op.add_column("feedback", sa.Column("android_version", sa.String(length=16), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("feedback") as batch_op:
+        batch_op.drop_column("android_version")
+        batch_op.drop_column("rom_name")
+        batch_op.drop_column("device_model")
+        batch_op.drop_column("app_version")

alembic/versions/invite_cash_compare_reward.py

@@ -0,0 +1,88 @@
+"""invite cash account isolation + compare reward tracking (🅱-1)
+
+Revision ID: invite_cash_compare_reward
+Revises: feedback_review_fields
+Create Date: 2026-06-23 00:00:00.000000
+
+邀请功能 v2 账户隔离 + 比价发奖追踪:
+  - coin_account 加 invite_cash_balance_cents(邀请奖励金独立余额,与金币兑换的 cash 物理隔离)
+  - withdraw_order 加 source(标记提现扣哪个账户,退款退回对应账户;旧单默认 coin_cash)
+  - invite_relation 加比价发奖追踪三列(好友比价多次只发一次)
+  - 新增 invite_cash_transaction 表(邀请奖励金独立流水账本)
+
+加列均 NOT NULL + server_default,存量行自动填默认值,安全。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'invite_cash_compare_reward'
+down_revision: Union[str, Sequence[str], None] = 'feedback_review_fields'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # 1. 邀请奖励金独立余额(与金币兑换的 cash_balance_cents 物理隔离;红线:两本账不可累加)
+    op.add_column(
+        'coin_account',
+        sa.Column('invite_cash_balance_cents', sa.Integer(), nullable=False, server_default='0'),
+    )
+    # 2. 提现单标记账户来源:coin_cash / invite_cash,退款退回对应账户(旧单默认 coin_cash)
+    op.add_column(
+        'withdraw_order',
+        sa.Column('source', sa.String(length=16), nullable=False, server_default='coin_cash'),
+    )
+    # 3. 邀请关系加比价发奖追踪(好友"下载+登录+比价一次"→ 给邀请人发奖,只发一次)
+    op.add_column(
+        'invite_relation',
+        sa.Column('compare_reward_granted', sa.Boolean(), nullable=False, server_default=sa.false()),
+    )
+    op.add_column(
+        'invite_relation',
+        sa.Column('compare_reward_cents', sa.Integer(), nullable=False, server_default='0'),
+    )
+    op.add_column(
+        'invite_relation',
+        sa.Column('compare_rewarded_at', sa.DateTime(timezone=True), nullable=True),
+    )
+    # 4. 邀请奖励金独立流水表(结构同 cash_transaction;balance_after 记 invite_cash_balance_cents)
+    op.create_table(
+        'invite_cash_transaction',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('user_id', sa.Integer(), nullable=False),
+        sa.Column('amount_cents', sa.Integer(), nullable=False),
+        sa.Column('balance_after_cents', sa.Integer(), nullable=False),
+        sa.Column('biz_type', sa.String(length=32), nullable=False),
+        sa.Column('ref_id', sa.String(length=64), nullable=True),
+        sa.Column('remark', sa.String(length=128), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        sa.ForeignKeyConstraint(['user_id'], ['user.id']),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    op.create_index('ix_invite_cash_transaction_user_id', 'invite_cash_transaction', ['user_id'])
+    op.create_index('ix_invite_cash_transaction_created_at', 'invite_cash_transaction', ['created_at'])
+    # 提现退款幂等:一个提现单只退一次(partial unique，对齐 cash_transaction 的 withdraw_refund 去重)
+    op.create_index(
+        'ux_invite_cash_txn_refund_ref',
+        'invite_cash_transaction',
+        ['ref_id'],
+        unique=True,
+        sqlite_where=sa.text("biz_type = 'invite_withdraw_refund' AND ref_id IS NOT NULL"),
+        postgresql_where=sa.text("biz_type = 'invite_withdraw_refund' AND ref_id IS NOT NULL"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_index('ux_invite_cash_txn_refund_ref', table_name='invite_cash_transaction')
+    op.drop_index('ix_invite_cash_transaction_created_at', table_name='invite_cash_transaction')
+    op.drop_index('ix_invite_cash_transaction_user_id', table_name='invite_cash_transaction')
+    op.drop_table('invite_cash_transaction')
+    op.drop_column('invite_relation', 'compare_rewarded_at')
+    op.drop_column('invite_relation', 'compare_reward_cents')
+    op.drop_column('invite_relation', 'compare_reward_granted')
+    op.drop_column('withdraw_order', 'source')
+    op.drop_column('coin_account', 'invite_cash_balance_cents')

app/admin/main.py

@@ -23,7 +23,9 @@ from app.admin.routers.comparison import router as comparison_router
 from app.admin.routers.config import router as config_router
 from app.admin.routers.cps import router as cps_router
 from app.admin.routers.dashboard import router as dashboard_router
+from app.admin.routers.device_liveness import router as device_liveness_router
 from app.admin.routers.ops_stat_config import router as ops_stat_config_router
+from app.admin.routers.event_logs import router as event_logs_router
 from app.admin.routers.feedback import router as feedback_router
 from app.admin.routers.feedback_qr import router as feedback_qr_router
 from app.admin.routers.onboarding import router as onboarding_router
@@ -83,6 +85,7 @@ def health() -> dict[str, str]:
 
 admin_app.include_router(auth_router)
 admin_app.include_router(dashboard_router)
+admin_app.include_router(device_liveness_router)
 admin_app.include_router(ops_stat_config_router)
 admin_app.include_router(ops_marquee_seed_router)
 admin_app.include_router(users_router)
@@ -91,6 +94,7 @@ admin_app.include_router(wallet_router)
 admin_app.include_router(withdraw_router)
 admin_app.include_router(price_report_router)
 admin_app.include_router(feedback_router)
+admin_app.include_router(event_logs_router)
 admin_app.include_router(feedback_qr_router)
 admin_app.include_router(admins_router)
 admin_app.include_router(audit_router)

app/admin/repositories/ad_audit.py

@@ -4,9 +4,9 @@
 - 看视频:每条 granted = 1 份,第 N 份 = 该用户 granted 的 reward_video **账号累计**顺序号
   (与 ad_reward.grant_ad_reward 里 `_granted_cumulative + 1` 一致;LT 因子不按天重置,
   故复算时要把当日序号叠加上该用户在本日**之前**的累计已发份数)。
-- 信息流:每条按 unit_count 份逐份累加,LT 序号 = 该用户 granted 份数**账号累计**
-  (与 ad_feed_reward._unit_reward_total 的 existing_units 一致;同样不按天重置,
-  复算需叠加本日之前的累计份数)。
+- 信息流:**每条 granted = 1 份**(与 ad_feed_reward.grant_feed_reward 同口径:看满一份即发该条
+  满额,**不按 unit_count 逐份累加**),LT 序号 = 该用户 granted **条数**账号累计
+  (与 ad_feed_reward.granted_unit_total 的 COUNT 一致;不按天重置,复算需叠加本日之前的累计条数)。
 
 非 granted(capped/ecpm_missing)不占用份序号、应发恒 0,据此校验闸口是否确实没发。
 """
@@ -108,14 +108,18 @@ def _reward_video_rows(
     return rows
 
 
-def _feed_prior_granted_units(
+def _feed_prior_granted_count(
     db: Session, *, date: str, user_id: int | None
 ) -> dict[int, int]:
-    """各用户在 date **之前** granted 的信息流份数累计,作为当日复算的 LT 序号起点。"""
+    """各用户在 date **之前** granted 的信息流**条数**累计,作为当日复算的 LT 序号起点。
+
+    与发奖侧 ad_feed_reward.granted_unit_total(COUNT status=granted)对齐:一条广告 = 1 份,
+    LT 按账号累计**条数**递进。**不再用 SUM(unit_count)**——那是「一条按时长折多份」的过时口径,
+    与现行发奖(每条 1 份)漂移,会让 unit_count>1 的记录复算虚高、对账恒「不符」。"""
     stmt = (
         select(
             AdFeedRewardRecord.user_id,
-            func.coalesce(func.sum(AdFeedRewardRecord.unit_count), 0),
+            func.count(),
         )
         .where(
             AdFeedRewardRecord.reward_date < date,
@@ -128,8 +132,29 @@ def _feed_prior_granted_units(
     return {uid: int(n) for uid, n in db.execute(stmt).all()}
 
 
-def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
-    """信息流记录复算。granted 记录逐份累加,LT 序号沿用账号累计份数(含本日之前)。"""
+def _feed_scene_matches(rec: AdFeedRewardRecord, scene: str | None) -> bool:
+    """该信息流记录是否落入请求的展示筛选 scene。
+    - scene=="feed":ad_type in ("feed", NULL)(旧数据 NULL 视为 feed,向后兼容)
+    - scene=="draw":ad_type=="draw"
+    - scene 为 None:不筛(两类都要)。
+    """
+    if scene == "feed":
+        return rec.ad_type in (None, "feed")
+    if scene == "draw":
+        return rec.ad_type == "draw"
+    return True
+
+
+def _feed_rows(
+    db: Session, *, date: str, user_id: int | None, scene: str | None = None
+) -> list[dict]:
+    """信息流记录复算。**每条 granted = 1 份**(与发奖同口径,不按 unit_count 累加),
+    LT 序号沿用账号累计**条数**(含本日之前)。
+
+    **关键:LT 因子账号累计按全表 granted 条数累计(feed+draw 共享同一发奖池/上限),不按 ad_type 拆分**——
+    故无论 scene 怎么筛展示,这里都遍历当日**全部**信息流记录维持 granted_count 累加;scene 只决定
+    哪些行被**留下展示**(由 _feed_scene_matches 判断),不影响累计基线,保证复算序号与正式发奖一致。
+    """
     stmt = (
         select(AdFeedRewardRecord)
         .where(AdFeedRewardRecord.reward_date == date)
@@ -138,22 +163,24 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
     if user_id is not None:
         stmt = stmt.where(AdFeedRewardRecord.user_id == user_id)
 
-    # 本日之前的累计份数做起点,与 _unit_reward_total 的 existing_units(累计)对齐
-    granted_units: dict[int, int] = _feed_prior_granted_units(db, date=date, user_id=user_id)
+    # 本日之前的累计**条数**做起点,与发奖侧 granted_unit_total(COUNT granted)对齐
+    granted_count: dict[int, int] = _feed_prior_granted_count(db, date=date, user_id=user_id)
     rows: list[dict] = []
     for rec in db.execute(stmt).scalars():
+        keep = _feed_scene_matches(rec, scene)  # 累计照常推进,这里只决定是否展示本行
         if rec.status == "granted":
-            existing = granted_units.get(rec.user_id, 0)
-            units = rec.unit_count
-            expected = sum(
-                rewards.calculate_ad_reward_coin(rec.ecpm_raw, existing + offset)
-                for offset in range(1, units + 1)
-            )
-            granted_units[rec.user_id] = existing + units
-            start = existing + 1 if units > 0 else None
-            end = existing + units if units > 0 else None
+            # 一条广告 = 1 份(与 grant_feed_reward 同口径:看满一份即发该条满额,不按 unit_count 累加)。
+            # nth = 账号累计第几**条**(含本日之前),与发奖侧 granted_unit_total+1 对齐;累计照常推进
+            # (即便 scene 不匹配不展示也要 +1,保证序号与正式发奖一致)。
+            nth = granted_count.get(rec.user_id, 0) + 1
+            granted_count[rec.user_id] = nth
+            if not keep:
+                continue
+            expected = rewards.calculate_ad_reward_coin(rec.ecpm_raw, nth)
             rows.append({
                 "scene": "feed",
+                "ad_type": rec.ad_type or "feed",
+                "feed_scene": rec.feed_scene,
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
@@ -163,18 +190,22 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
                 "status": rec.status,
                 "ecpm": rec.ecpm_raw,
                 "ecpm_factor": rewards.ad_ecpm_factor(rewards.parse_ecpm_yuan(rec.ecpm_raw)),
-                "units": units,
-                "lt_index_start": start,
-                "lt_index_end": end,
-                "lt_factor_start": rewards.ad_lt_factor(start) if start else None,
-                "lt_factor_end": rewards.ad_lt_factor(end) if end else None,
+                "units": 1,
+                "lt_index_start": nth,
+                "lt_index_end": nth,
+                "lt_factor_start": rewards.ad_lt_factor(nth),
+                "lt_factor_end": rewards.ad_lt_factor(nth),
                 "expected_coin": expected,
                 "actual_coin": rec.coin,
                 "matched": expected == rec.coin,
             })
         else:
+            if not keep:
+                continue
             rows.append({
                 "scene": "feed",
+                "ad_type": rec.ad_type or "feed",
+                "feed_scene": rec.feed_scene,
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
@@ -199,16 +230,19 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
 def audit_rows(
     db: Session, *, date: str, user_id: int | None, scene: str | None = None
 ) -> list[dict]:
-    """当日逐条发奖复算行(未排序)。scene: None=两类 / "reward_video" / "feed"。
+    """当日逐条发奖复算行(未排序)。scene: None=两类 / "reward_video" / "feed" / "draw"。
 
+    "feed" 与 "draw" 都查 ad_feed_reward_record(同一发奖表),按 ad_type 区分:feed 含历史 NULL,
+    draw 仅 ad_type=="draw"。信息流行额外带 `ad_type`/`feed_scene`,供收益报表区分比价/领券 Draw 收益。
     每行含 `app_env`/`our_code_id`/`expected_coin`/`actual_coin` 等,供金币审计逐条对账,
     也供广告收益报表把「应发/实发」按 用户×类型×应用×代码位 聚合(见 ad_revenue,复用同一复算口径)。
+    **LT 因子账号累计仍按全表 unit 累计(feed+draw 共享),scene 只筛展示,不拆累计。**
     """
     rows: list[dict] = []
     if scene in (None, "reward_video"):
         rows.extend(_reward_video_rows(db, date=date, user_id=user_id))
-    if scene in (None, "feed"):
-        rows.extend(_feed_rows(db, date=date, user_id=user_id))
+    if scene in (None, "feed", "draw"):
+        rows.extend(_feed_rows(db, date=date, user_id=user_id, scene=scene))
     return rows
 
 

app/admin/repositories/ad_revenue.py

@@ -11,26 +11,33 @@
 (ad_audit.audit_rows,与正式发奖同一公式口径,不另写公式)。合计与对账在全量上统计,
 不受 limit(只截断 items)影响。
 
-⚠️ 局限:① 历史 Draw 发奖混在 ad_feed_reward_record 无类型标记,金币侧统一记 feed。
-② 跨天 S2S 回调:同一次广告的展示与发奖偶尔落相邻日,各自按 report_date / reward_date 归日。
+每行带 ad_type(reward_video/feed/draw)与 feed_scene(comparison/coupon/welfare),供前端区分
+「比价 Draw 收益」与「领券 Draw 收益」(比价/领券共用同一代码位,只能靠 feed_scene 分)。
+
+⚠️ 局限:① 历史信息流/Draw 发奖 ad_type 为 NULL 的旧记录统一视为 feed(向后兼容);Draw 仅
+ad_type=="draw" 的新记录单独成类。② 跨天 S2S 回调:同一次广告的展示与发奖偶尔落相邻日,各自按
+report_date / reward_date 归日。
 """
 from __future__ import annotations
 
-from datetime import date as _date, datetime, timedelta, timezone
+from datetime import UTC, datetime, timedelta
+from datetime import date as _date
 
 from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.admin.repositories import ad_audit
+from app.admin.repositories import stats as admin_stats
 from app.core import rewards
 from app.models.ad_ecpm import AdEcpmRecord
 from app.models.user import User
+from app.repositories import ad_pangle_revenue
 
 
 def _cn_hour(dt: datetime) -> int:
     """created_at(UTC 口径)→ 北京时间小时(0–23)。naive 当 UTC 处理(sqlite),tz-aware 直接换算(pg)。"""
     if dt.tzinfo is None:
-        dt = dt.replace(tzinfo=timezone.utc)
+        dt = dt.replace(tzinfo=UTC)
     return dt.astimezone(rewards.CN_TZ).hour
 
 
@@ -46,8 +53,18 @@ def _date_range(date_from: str, date_to: str) -> list[str]:
     return out
 
 
-# 审计行的 scene 与报表 ad_type 一一对应
-_SCENE_TO_AD_TYPE = {"reward_video": "reward_video", "feed": "feed"}
+# 报表 ad_type 与审计 scene 取值一致(reward_video / feed / draw):feed 与 draw 同查发奖表
+# ad_feed_reward_record,由 audit 内部按 ad_type 区分(feed 含历史 NULL,draw 仅 ad_type=="draw")。
+_AUDIT_SCENES = {"reward_video", "feed", "draw"}
+
+
+def _event_ad_type(row: dict) -> str:
+    """纯发奖事件行的 ad_type:信息流行用 audit 带回的真实 ad_type(feed/draw),回退 feed;
+    激励视频行恒 reward_video。不再用 scene 硬映射,避免把 draw 丢成 feed。"""
+    if row["scene"] == "reward_video":
+        return "reward_video"
+    return row.get("ad_type") or "feed"
+
 
 # 发奖复算明细字段(展开下钻看「金币怎么算出来的」)——从 audit 行原样取这些 key。
 _REWARD_DETAIL_KEYS = (
@@ -69,14 +86,21 @@ def ad_revenue_report(
     date_to: str,
     user_id: int | None = None,
     ad_type: str | None = None,
+    feed_scene: str | None = None,
+    app_env: str | None = None,
     granularity: str = "day",
     limit: int = 500,
+    offset: int = 0,
+    sort: str = "time",
 ) -> dict:
     """日期区间(北京时间,闭区间)**逐条广告事件**列表 + 发奖对账。单日时 date_from==date_to。
 
     每个 item = 一次广告事件(展示与发奖按 ad_session_id 合并;信息流展示 / 发奖各自成行)。
-    ad_type: None=全部 / reward_video / feed / draw。granularity=hour 时每行带北京小时(由各自时间算)。
-    limit 只截断 items(事件明细),total 与 total_* / daily 在全量上统计,数字始终可信。
+    ad_type: None=全部 / reward_video / feed / draw。feed_scene: None=全部 /
+    comparison / coupon / welfare,作为全局筛选(同时作用于明细、合计与 daily/hourly 趋势)。
+    granularity=hour 时每行带北京小时(由各自时间算),并额外返回全量 hourly 序列。
+    事件按时间倒序(新→旧)排列;limit/offset 对排序后的全量做分页切片(items 为当前页),
+    total 与 total_* / daily / hourly 在全量上统计,不受分页影响。
     """
     by_hour = granularity == "hour"
 
@@ -84,7 +108,9 @@ def ad_revenue_report(
     #    同时保留全量列表,未被展示合并的成「纯发奖」事件。
     reward_by_session: dict[tuple[int, str], list[dict]] = {}
     all_reward_rows: list[dict] = []
-    audit_scene = _SCENE_TO_AD_TYPE.get(ad_type) if ad_type is not None else None
+    # 报表 ad_type 直接当 audit scene 用(取值一致);未知/无效 ad_type 不取发奖行。draw 在此被
+    # 正确传成 scene="draw",audit 会按 ad_type 筛出 Draw 发奖,不再丢成 feed。
+    audit_scene = ad_type if ad_type in _AUDIT_SCENES else None
     if ad_type is None or audit_scene is not None:
         for d in _date_range(date_from, date_to):
             for row in ad_audit.audit_rows(db, date=d, user_id=user_id, scene=audit_scene):
@@ -123,6 +149,7 @@ def ad_revenue_report(
             "report_date": rec.report_date,
             "user_id": rec.user_id,
             "ad_type": rec.ad_type,
+            "feed_scene": rec.feed_scene,
             "app_env": rec.app_env,
             "our_code_id": rec.our_code_id,
             "created_at": rec.created_at,
@@ -130,8 +157,12 @@ def ad_revenue_report(
             "has_impression": True,
             "impressions": 1,
             "ecpm": rec.ecpm_raw,
-            # 单次展示收益(元)= eCPM元 ÷ 1000(每千次→单次);与发奖同源解析,口径一致。
-            "revenue_yuan": round(rewards.parse_ecpm_yuan(rec.ecpm_raw) / 1000.0, 6),
+            # 单次展示收益(元)= eCPM元 ÷ 1000(每千次→单次)。eCPM 先钳到 AD_ECPM_MAX_FEN(¥500 CPM)
+            # 再折收益,与发奖口径 [rewards.calculate_ad_reward_coin] 一致(2026-06-29 修:原裸 parse_ecpm_yuan
+            # 不钳,伪造/异常天价 eCPM 会把报表预估收益冲到任意大;金币侧已钳、收益侧漏钳)。
+            "revenue_yuan": round(
+                min(rewards.parse_ecpm_yuan(rec.ecpm_raw), rewards.AD_ECPM_MAX_FEN / 100.0) / 1000.0, 6,
+            ),
             "adn": rec.adn,
             "slot_id": rec.slot_id,
         }
@@ -162,7 +193,8 @@ def ad_revenue_report(
             "event_key": f"rwd-{row['record_id']}",
             "report_date": row["_report_date"],
             "user_id": row["user_id"],
-            "ad_type": _SCENE_TO_AD_TYPE.get(row["scene"], row["scene"]),
+            "ad_type": _event_ad_type(row),
+            "feed_scene": row.get("feed_scene"),
             "app_env": row.get("app_env"),
             "our_code_id": row.get("our_code_id"),
             "created_at": row["created_at"],
@@ -181,7 +213,25 @@ def ad_revenue_report(
             "reward_detail": _reward_detail(row),
         })
 
-    events.sort(key=lambda e: (e["report_date"], e["user_id"], e["created_at"]))
+    # 「场景」作为全局筛选(与 user_id/ad_type 一致):同时作用于明细、合计与 daily/hourly 趋势。
+    # feed_scene 仅信息流 / Draw 有值,激励视频与旧数据为 None;选中后只保留该场景事件。
+    if feed_scene is not None:
+        events = [e for e in events if e.get("feed_scene") == feed_scene]
+
+    # app_env 过滤(2026-06-29 新增能力,修隐患:测试应用上报的假 eCPM 如 ¥678 CPM 会污染正式收益合计/平均):
+    # 显式传 "prod"/"test" 只看该环境;不传=全部(维持现状)。**不擅自把默认改成排除 test**——本地 dev 库多为
+    # test 数据、默认排除会使本地报表空,且「正式报表是否含 test」属产品口径。建议前端报表页加 app_env 筛选器
+    # (默认选 prod),或产品确认后再把默认改成排除 test。注:穿山甲后台收益列(total_pangle_*)暂未联动此过滤
+    # (它是独立对照列,且 pangle 的 test 是真实小额、非客户端那种假值)。
+    if app_env is not None:
+        events = [e for e in events if e.get("app_env") == app_env]
+
+    # 排序:time=按时间倒序(新→旧);ecpm=按 eCPM 数值倒序(eCPM 原值是字符串「分」,转数值排;
+    # 纯发奖行用其发奖采用的 eCPM,缺失/非法计 0 排末尾)。
+    if sort == "ecpm":
+        events.sort(key=lambda e: rewards.parse_ecpm_fen(e["ecpm"]), reverse=True)
+    else:
+        events.sort(key=lambda e: (e["report_date"], e["created_at"]), reverse=True)
 
     # 补手机号(admin 展示用,完整不脱敏,与用户 / 钱包 / 比价记录页一致):批量一次查,避免 N+1。
     uids = {e["user_id"] for e in events}
@@ -219,14 +269,83 @@ def ad_revenue_report(
         for d in sorted(daily_map.values(), key=lambda x: x["date"])
     ]
 
+    # 穿山甲后台收益(GroMore 数据 API,T+1 入库 ad_pangle_daily_revenue):汇总 + 按天趋势级展示,
+    # 与上面客户端自报 eCPM 折算的预估并列对照(看 gap)。穿山甲数据**无用户/场景/类型维度**,故仅在
+    # 「全量视图」(未按 user_id / ad_type / feed_scene 过滤)给值;一旦带这些过滤,穿山甲数无法对应口径
+    # → 置 None,前端显示「-」并提示。逐条事件行不动(仍是客户端预估)。
+    pangle_filterable = user_id is None and ad_type is None and feed_scene is None
+    total_pangle_revenue_yuan: float | None = None
+    total_pangle_api_revenue_yuan: float | None = None
+    if pangle_filterable:
+        pangle_aggs = ad_pangle_revenue.aggregate_by_date(db, date_from=date_from, date_to=date_to)
+        if pangle_aggs:
+            by_date = {a["date"]: a for a in pangle_aggs}
+            for d in daily:
+                pa = by_date.get(d["date"])
+                d["pangle_revenue_yuan"] = pa["revenue_yuan"] if pa else None
+                d["pangle_api_revenue_yuan"] = pa["api_revenue_yuan"] if pa else None
+            total_pangle_revenue_yuan = round(sum(a["revenue_yuan"] for a in pangle_aggs), 6)
+            api_vals = [a["api_revenue_yuan"] for a in pangle_aggs if a["api_revenue_yuan"] is not None]
+            total_pangle_api_revenue_yuan = round(sum(api_vals), 6) if api_vals else None
+
+    # 按小时汇总(全量,不受分页 limit/offset 影响):供前端按小时趋势图(单日 granularity=hour 时用)。
+    # 只在 by_hour 下聚合(此时每个 event 带 hour);否则空。前端按天趋势仍用 daily。
+    hourly: list[dict] = []
+    if by_hour:
+        hour_map: dict[int, dict] = {}
+        for e in events:
+            h = e["hour"]
+            if h is None:
+                continue
+            hd = hour_map.get(h)
+            if hd is None:
+                hd = {"hour": h, "impressions": 0, "revenue_yuan": 0.0,
+                      "expected_coin": 0, "actual_coin": 0}
+                hour_map[h] = hd
+            hd["impressions"] += e["impressions"]
+            hd["revenue_yuan"] += e["revenue_yuan"]
+            hd["expected_coin"] += e["expected_coin"]
+            hd["actual_coin"] += e["actual_coin"]
+        hourly = [
+            {**hd, "revenue_yuan": round(hd["revenue_yuan"], 6)}
+            for hd in sorted(hour_map.values(), key=lambda x: x["hour"])
+        ]
+
+    # 分广告类型小计(按 ad_type:展示条数 + 预估收益;eCPM 由前端用 收益÷展示×1000 算)。
+    # 基于全量(已按 feed_scene 过滤)events;前端只取 draw / reward_video 两类展示。
+    type_map: dict[str, dict] = {}
+    for e in events:
+        t = type_map.get(e["ad_type"])
+        if t is None:
+            t = {"impressions": 0, "revenue_yuan": 0.0}
+            type_map[e["ad_type"]] = t
+        t["impressions"] += e["impressions"]
+        t["revenue_yuan"] += e["revenue_yuan"]
+    type_stats = {
+        k: {"impressions": v["impressions"], "revenue_yuan": round(v["revenue_yuan"], 6)}
+        for k, v in type_map.items()
+    }
+
+    # DAU:复用大盘「今日活跃」口径(stats.today_dau,last_login_at)。该口径只能算今日,
+    # 故仅当查询=今日单天时给值;历史 / 多天区间返回 None,前端显示「-」。
+    is_today = date_from == date_to == rewards.cn_today().isoformat()
+    dau = admin_stats.today_dau(db) if is_today else None
+
     return {
         "total": len(events),
-        "truncated": len(events) > limit,
+        "truncated": len(events) > offset + limit,
         "total_impressions": total_impressions,
         "total_revenue_yuan": total_revenue_yuan,
+        # 穿山甲后台收益合计(元):预估 revenue + 收益Api;非全量视图(带 user/类型/场景过滤)或无数据为 None。
+        "total_pangle_revenue_yuan": total_pangle_revenue_yuan,
+        "total_pangle_api_revenue_yuan": total_pangle_api_revenue_yuan,
+        "pangle_revenue_available": total_pangle_revenue_yuan is not None,
         "total_expected_coin": total_expected_coin,
         "total_actual_coin": total_actual_coin,
         "mismatch_count": mismatch_count,
         "daily": daily,
-        "items": events[:limit],
+        "hourly": hourly,
+        "type_stats": type_stats,
+        "dau": dau,
+        "items": events[offset:offset + limit],
     }

app/admin/repositories/cps.py

@@ -17,7 +17,7 @@ from app.integrations import meituan
 from app.repositories import cps_link as cps_link_repo
 from app.models.cps_activity import CpsActivity
 from app.models.cps_group import CpsGroup
-from app.models.cps_link import CpsClick
+from app.models.cps_link import CpsClick, CpsLink
 from app.models.cps_order import CpsOrder
 from app.models.cps_wx_user import CpsWxUser
 
@@ -524,3 +524,90 @@ def group_wx_users(db: Session, *, group_id: int, limit: int = 200) -> list[dict
     ]
     result.sort(key=lambda x: x["first_seen"], reverse=True)
     return result[:limit]
+
+
+def group_day_users(
+    db: Session, *, group_id: int, start: datetime, end: datetime, limit: int = 200,
+) -> list[dict]:
+    """该群某天(北京)以用户为单位的领券/点击 + 每人 visit 过的券。
+
+    时间窗为半开区间 [start, end)(end=次日 00:00),避免午夜双计。只统计 openid 非空
+    (可归属到人)的点击 —— 匿名点击(美团/京东 302 多为匿名)不计入。券名 = 该点击 link
+    对应活动名;活动被硬删则兜底 活动#{id}。copy=领券次数、visit=点击次数;coupons 仅
+    取 visit 事件按活动分组、按次数倒序(合计 = visit_count)。排序:领券 desc、再点击 desc。
+    与 group_wx_users 同风格(Python 侧聚合,跨 PG/SQLite 无方言坑)。
+
+    注:每日明细行的 click_pv/copy_pv 计全部点击(含匿名、UV 按 ip,ua);本函数只计 openid
+    用户,故各用户求和 <= 当天行总数,二者口径不同、不必相等。
+    """
+    rows = db.execute(
+        select(CpsClick.openid, CpsClick.event_type, CpsClick.link_id)
+        .where(CpsClick.group_id == group_id)
+        .where(CpsClick.clicked_at >= _as_utc(start))
+        .where(CpsClick.clicked_at < _as_utc(end))
+        .where(CpsClick.openid.is_not(None))
+    ).all()
+    if not rows:
+        return []
+
+    # link_id -> activity_id -> 券名(活动名)
+    link_ids = {r.link_id for r in rows}
+    link_to_act = dict(
+        db.execute(
+            select(CpsLink.id, CpsLink.activity_id).where(CpsLink.id.in_(link_ids))
+        ).all()
+    )
+    act_ids = {aid for aid in link_to_act.values() if aid is not None}
+    act_name = (
+        dict(
+            db.execute(
+                select(CpsActivity.id, CpsActivity.name).where(CpsActivity.id.in_(act_ids))
+            ).all()
+        )
+        if act_ids
+        else {}
+    )
+
+    def _coupon_name(link_id: int) -> str:
+        aid = link_to_act.get(link_id)
+        if aid is None:
+            return f"链接#{link_id}"
+        return act_name.get(aid) or f"活动#{aid}"
+
+    stat: dict[str, dict] = {}
+    for openid, event_type, link_id in rows:
+        s = stat.setdefault(openid, {"copy": 0, "visit": 0, "coupons": {}})
+        if event_type == "copy":
+            s["copy"] += 1
+        else:
+            s["visit"] += 1
+            name = _coupon_name(link_id)
+            s["coupons"][name] = s["coupons"].get(name, 0) + 1
+
+    openids = list(stat.keys())
+    users = {
+        u.openid: u
+        for u in db.execute(
+            select(CpsWxUser).where(CpsWxUser.openid.in_(openids))
+        ).scalars().all()
+    }
+
+    result = [
+        {
+            "openid": openid,
+            "nickname": users[openid].nickname if openid in users else None,
+            "headimgurl": users[openid].headimgurl if openid in users else None,
+            "copy_count": s["copy"],
+            "visit_count": s["visit"],
+            "coupons": [
+                {"name": name, "count": cnt}
+                # 次数倒序;同次数按券名升序兜底,保证 PG 无 ORDER BY 行序下输出稳定
+                for name, cnt in sorted(
+                    s["coupons"].items(), key=lambda kv: (-kv[1], kv[0])
+                )
+            ],
+        }
+        for openid, s in stat.items()
+    ]
+    result.sort(key=lambda x: (x["copy_count"], x["visit_count"]), reverse=True)
+    return result[:limit]

app/admin/repositories/queries.py

@@ -8,14 +8,17 @@ from __future__ import annotations
 from datetime import datetime, timedelta, timezone
 from zoneinfo import ZoneInfo
 
-from sqlalchemy import Select, asc, desc, func, or_, select
+from sqlalchemy import Select, asc, case, desc, func, or_, select
 from sqlalchemy.orm import Session
 
 from app.core import rewards
+from app.core.config import settings
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.ad_reward import AdRewardRecord
 from app.models.admin import AdminAuditLog
+from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
+from app.models.device import DeviceLiveness
 from app.models.feedback import Feedback
 from app.models.onboarding import OnboardingCompletion
 from app.models.price_report import PriceReport
@@ -122,8 +125,9 @@ def list_users(
     return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
 
 
-def _attach_user_info(db: Session, records: list[ComparisonRecord]) -> None:
-    """给每条比价记录瞬态挂 phone/nickname(非 DB 列,供 admin schema from_attributes 读)。"""
+def _attach_user_info(db: Session, records: list[ComparisonRecord | Feedback | PriceReport]) -> None:
+    """给每条记录瞬态挂 phone/nickname(非 DB 列,供 admin schema from_attributes 读)。
+    按 user_id 鸭子类型,比价记录/反馈/上报通用。"""
     uids = {r.user_id for r in records}
     if not uids:
         return
@@ -199,6 +203,156 @@ def list_onboarding_devices(db: Session, *, limit: int = 500) -> list[dict]:
     ]
 
 
+def _heartbeat_seconds_ago(last: datetime | None) -> int | None:
+    """距上次心跳的秒数(兼容 SQLite 取回的 naive datetime,按 UTC 处理)。None = 从没心跳。"""
+    if last is None:
+        return None
+    if last.tzinfo is None:
+        last = last.replace(tzinfo=timezone.utc)
+    return int((datetime.now(timezone.utc) - last).total_seconds())
+
+
+def _device_model_from_id(device_id: str) -> str:
+    """从 device_id(格式 device_<机型>_<hash>)解析机型;不规范则回退原 id。"""
+    parts = device_id.split("_")
+    if len(parts) >= 3 and parts[0] == "device":
+        return "_".join(parts[1:-1]).replace("_", " ")
+    return device_id
+
+
+def _attach_device_derived(devices: list[DeviceLiveness]) -> None:
+    """给每台设备瞬态挂 device_model / online / display_state / offline_seconds(供 schema 读)。
+
+    在线判定:开过无障碍(ever_protected)且距上次心跳 ≤ HEARTBEAT_TIMEOUT_MINUTES。
+    从没开过无障碍(ever_protected=False)= never(不算掉线,避免把装了没用的设备误报掉线)。
+    offline_seconds 仅 offline 时给值(=掉线时长),在线/从未启用为 None。"""
+    timeout_sec = max(1, int(settings.HEARTBEAT_TIMEOUT_MINUTES)) * 60
+    for d in devices:
+        d.device_model = _device_model_from_id(d.device_id)
+        secs = _heartbeat_seconds_ago(d.last_heartbeat_at)
+        if not d.ever_protected:
+            d.online = False
+            d.display_state = "never"
+            d.offline_seconds = None
+        elif secs is not None and secs <= timeout_sec:
+            d.online = True
+            d.display_state = "online"
+            d.offline_seconds = None
+        else:
+            d.online = False
+            d.display_state = "offline"
+            d.offline_seconds = secs
+
+
+def _attach_device_user_info(db: Session, devices: list[DeviceLiveness]) -> None:
+    """给每台设备瞬态挂归属用户 phone/nickname(同 _attach_user_info,供 admin schema 读)。"""
+    uids = {d.user_id for d in devices}
+    if not uids:
+        return
+    rows = db.execute(
+        select(User.id, User.phone, User.nickname).where(User.id.in_(uids))
+    ).all()
+    umap = {uid: (phone, nick) for uid, phone, nick in rows}
+    for d in devices:
+        phone, nick = umap.get(d.user_id, (None, None))
+        d.phone = phone
+        d.nickname = nick
+
+
+def _liveness_cutoff() -> datetime:
+    """掉线判定分界:此刻 - HEARTBEAT_TIMEOUT_MINUTES。心跳早于它 = 掉线(同 list_overdue 口径)。"""
+    timeout_min = max(1, int(settings.HEARTBEAT_TIMEOUT_MINUTES))
+    return datetime.now(timezone.utc) - timedelta(minutes=timeout_min)
+
+
+def list_device_liveness(
+    db: Session,
+    *,
+    status: str | None = None,
+    device_id: str | None = None,
+    phone: str | None = None,
+    user_id: int | None = None,
+    sort_by: str = "status",
+    sort_order: str = "desc",
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[DeviceLiveness], int | None, int]:
+    """设备存活列表(admin 全量)。按 在线情况(online/offline/never)/ 设备id(包含)/
+    归属用户(手机号前缀 或 user_id)筛,offset 分页。join user 取 phone/nickname,派生
+    device_model/online/display_state/offline_seconds 挂行上。
+    默认排序 status=掉线置顶(offline → online → never;掉线组内掉得最久在前)。"""
+    cutoff = _liveness_cutoff()
+    stmt = select(DeviceLiveness)
+    # 在线情况派生筛选(口径同 _attach_device_derived:ever_protected + 心跳是否过阈值)
+    if status == "online":
+        stmt = stmt.where(
+            DeviceLiveness.ever_protected.is_(True),
+            DeviceLiveness.last_heartbeat_at.is_not(None),
+            DeviceLiveness.last_heartbeat_at >= cutoff,
+        )
+    elif status == "offline":
+        stmt = stmt.where(
+            DeviceLiveness.ever_protected.is_(True),
+            DeviceLiveness.last_heartbeat_at.is_not(None),
+            DeviceLiveness.last_heartbeat_at < cutoff,
+        )
+    elif status == "never":
+        stmt = stmt.where(DeviceLiveness.ever_protected.is_(False))
+    if device_id and device_id.strip():
+        stmt = stmt.where(DeviceLiveness.device_id.like(f"%{device_id.strip()}%"))
+    if user_id is not None:
+        stmt = stmt.where(DeviceLiveness.user_id == user_id)
+    if phone:
+        stmt = stmt.where(
+            DeviceLiveness.user_id.in_(select(User.id).where(User.phone.like(f"{phone}%")))
+        )
+
+    if sort_by in ("last_heartbeat_at", "created_at"):
+        col = (
+            DeviceLiveness.last_heartbeat_at
+            if sort_by == "last_heartbeat_at"
+            else DeviceLiveness.created_at
+        )
+        order_fn = asc if sort_order == "asc" else desc
+        id_order = asc(DeviceLiveness.id) if sort_order == "asc" else desc(DeviceLiveness.id)
+        sort_clause: tuple = (order_fn(col), id_order)
+    else:
+        # 默认「掉线置顶」:offline(0) → online(1) → never(2);掉线组内按心跳最旧(掉得最久)在前
+        rank = case(
+            (DeviceLiveness.ever_protected.is_(False), 2),
+            (DeviceLiveness.last_heartbeat_at < cutoff, 0),
+            else_=1,
+        )
+        sort_clause = (asc(rank), asc(DeviceLiveness.last_heartbeat_at), desc(DeviceLiveness.id))
+
+    items, next_cursor, total = offset_paginate(db, stmt, sort_clause, limit=limit, cursor=cursor)
+    _attach_device_user_info(db, items)
+    _attach_device_derived(items)
+    return items, next_cursor, total
+
+
+def device_liveness_stats(db: Session) -> dict:
+    """顶部卡片:总设备数 + 在线 / 已掉线 / 未启用(按心跳阈值派生,口径同列表)。"""
+    cutoff = _liveness_cutoff()
+
+    def _count(*conds) -> int:
+        return int(db.execute(select(func.count(DeviceLiveness.id)).where(*conds)).scalar_one())
+
+    total = int(db.execute(select(func.count(DeviceLiveness.id))).scalar_one())
+    never = _count(DeviceLiveness.ever_protected.is_(False))
+    online = _count(
+        DeviceLiveness.ever_protected.is_(True),
+        DeviceLiveness.last_heartbeat_at.is_not(None),
+        DeviceLiveness.last_heartbeat_at >= cutoff,
+    )
+    offline = _count(
+        DeviceLiveness.ever_protected.is_(True),
+        DeviceLiveness.last_heartbeat_at.is_not(None),
+        DeviceLiveness.last_heartbeat_at < cutoff,
+    )
+    return {"total": total, "online": online, "offline": offline, "never": never}
+
+
 def list_all_coin_transactions(
     db: Session,
     *,
@@ -409,6 +563,62 @@ def list_feedbacks(
     sort_col = sort_cols.get(sort_by, Feedback.id)
     order_fn = asc if sort_order == "asc" else desc
     id_order = asc(Feedback.id) if sort_order == "asc" else desc(Feedback.id)
+    items, next_cursor, total = offset_paginate(
+        db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
+    )
+    _attach_user_info(db, items)  # 列表展示完整手机号(点手机号查该用户全部反馈)
+    return items, next_cursor, total
+
+
+def feedback_summary(db: Session) -> dict:
+    """反馈审核台各状态计数(待审核/已采纳/未采纳/合计)。待审核含历史 new 态(与前端 isPending 一致)。"""
+    rows = db.execute(
+        select(Feedback.status, func.count(Feedback.id)).group_by(Feedback.status)
+    ).all()
+    by_status = {status: int(count) for status, count in rows}
+    return {
+        "pending": by_status.get("pending", 0) + by_status.get("new", 0),
+        "adopted": by_status.get("adopted", 0),
+        "rejected": by_status.get("rejected", 0),
+        "total": sum(by_status.values()),
+    }
+
+
+def list_analytics_events(
+    db: Session,
+    *,
+    event: str | None = None,
+    device_id: str | None = None,
+    user_id: int | None = None,
+    session_id: str | None = None,
+    created_from: datetime | None = None,
+    created_to: datetime | None = None,
+    sort_by: str = "id",
+    sort_order: str = "desc",
+    limit: int = 20,
+    cursor: int | None = None,
+) -> tuple[list[AnalyticsEvent], int | None, int]:
+    """埋点日志列表(admin 全量)。按 事件名 / 设备ID前缀 / 用户ID / 会话ID / 接收时间范围 筛选,
+    按 id·接收时间排序。offset 分页(同 [list_feedbacks])。created_at 为 timestamptz,
+    日期入参统一转 tz-aware UTC 比较。"""
+    stmt = select(AnalyticsEvent)
+    if event:
+        stmt = stmt.where(AnalyticsEvent.event == event)
+    if device_id and device_id.strip():
+        stmt = stmt.where(AnalyticsEvent.device_id.like(f"{device_id.strip()}%"))
+    if user_id is not None:
+        stmt = stmt.where(AnalyticsEvent.user_id == user_id)
+    if session_id and session_id.strip():
+        stmt = stmt.where(AnalyticsEvent.session_id == session_id.strip())
+    if created_from is not None:
+        stmt = stmt.where(AnalyticsEvent.created_at >= _as_utc(created_from))
+    if created_to is not None:
+        stmt = stmt.where(AnalyticsEvent.created_at <= _as_utc(created_to))
+
+    sort_cols = {"id": AnalyticsEvent.id, "created_at": AnalyticsEvent.created_at}
+    sort_col = sort_cols.get(sort_by, AnalyticsEvent.id)
+    order_fn = asc if sort_order == "asc" else desc
+    id_order = asc(AnalyticsEvent.id) if sort_order == "asc" else desc(AnalyticsEvent.id)
     return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
 
 
@@ -787,21 +997,66 @@ def user_coin_records(
     return rows[offset:offset + limit], (offset + limit if has_more else None), total
 
 
+def _attach_price_report_comparison(db: Session, records: list[PriceReport]) -> None:
+    """给每条上报瞬态挂关联比价记录的 trace + 设备/版本快照:
+    trace_id/trace_url(点 Trace 看完整比价过程)、device_model/rom_name/android_version(机型OS版本列)、
+    app_version(提交版本号列,= 提交时我们 app 的 versionName)。
+    comparison_record_id 为空 / 关联记录查不到 → 全 None。"""
+    cids = {r.comparison_record_id for r in records if r.comparison_record_id is not None}
+    rows = (
+        db.execute(
+            select(
+                ComparisonRecord.id,
+                ComparisonRecord.trace_id,
+                ComparisonRecord.trace_url,
+                ComparisonRecord.device_model,
+                ComparisonRecord.rom_name,
+                ComparisonRecord.android_version,
+                ComparisonRecord.app_version,
+            ).where(ComparisonRecord.id.in_(cids))
+        ).all()
+        if cids
+        else []
+    )
+    cmap = {row.id: row for row in rows}
+    for r in records:
+        row = cmap.get(r.comparison_record_id)
+        r.trace_id = row.trace_id if row else None
+        r.trace_url = row.trace_url if row else None
+        r.device_model = row.device_model if row else None
+        r.rom_name = row.rom_name if row else None
+        r.android_version = row.android_version if row else None
+        r.app_version = row.app_version if row else None
+
+
 def list_price_reports(
     db: Session,
     *,
     status: str | None = None,
     user_id: int | None = None,
+    sort_by: str = "id",
+    sort_order: str = "desc",
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[PriceReport], int | None, int]:
-    """上报更低价列表(admin 全量,可按状态/用户筛)。offset 分页 + total,id 倒序。"""
+    """上报更低价列表(admin 全量,可按状态/用户筛)。offset 分页 + total,按 id·提交时间排序。
+    join User 取 phone 瞬态挂(列表展示完整手机号);按 comparison_record_id 挂 trace_id/trace_url。"""
     stmt = select(PriceReport)
     if status:
         stmt = stmt.where(PriceReport.status == status)
     if user_id is not None:
         stmt = stmt.where(PriceReport.user_id == user_id)
-    return offset_paginate(db, stmt, (PriceReport.id.desc(),), limit=limit, cursor=cursor)
+
+    sort_cols = {"id": PriceReport.id, "created_at": PriceReport.created_at}
+    sort_col = sort_cols.get(sort_by, PriceReport.id)
+    order_fn = asc if sort_order == "asc" else desc
+    id_order = asc(PriceReport.id) if sort_order == "asc" else desc(PriceReport.id)
+    items, next_cursor, total = offset_paginate(
+        db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
+    )
+    _attach_user_info(db, items)
+    _attach_price_report_comparison(db, items)
+    return items, next_cursor, total
 
 
 def price_report_summary(db: Session) -> dict:

app/admin/repositories/stats.py

@@ -5,7 +5,8 @@ user.last_login_at / comparison_record.status / withdraw_order.status)要加索
 """
 from __future__ import annotations
 
-from datetime import datetime, timedelta, timezone
+from datetime import date, datetime, time, timedelta, timezone
+from decimal import Decimal, InvalidOperation
 
 from sqlalchemy import func, select
 from sqlalchemy.orm import Session
@@ -13,12 +14,27 @@ from sqlalchemy.orm import Session
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.ad_reward import AdRewardRecord
 from app.models.comparison import ComparisonRecord
+from app.models.coupon_state import CouponPromptEngagement
+from app.models.cps_order import CpsOrder
 from app.models.feedback import Feedback
+from app.models.savings import SavingsRecord
 from app.models.signin import SigninBoostRecord, SigninRecord
 from app.models.user import User
 from app.models.wallet import CoinTransaction, WithdrawOrder
 
 _BEIJING = timezone(timedelta(hours=8))
+COUPON_REWARD_BIZ_TYPES = ("reward_video", "ad_reward", "coupon", "coupon_reward")
+COMPARISON_REWARD_BIZ_TYPES = ("comparison", "compare_reward", "comparison_reward")
+EXCLUDED_REWARD_BIZ_TYPES = ("invite_inviter", "invite_invitee", "admin_grant")
+UNCLASSIFIED_FEED_BIZ_TYPES = ("feed_ad_reward",)
+REGULAR_TASK_EXCLUDED_BIZ_TYPES = (
+    *COUPON_REWARD_BIZ_TYPES,
+    *COMPARISON_REWARD_BIZ_TYPES,
+    *EXCLUDED_REWARD_BIZ_TYPES,
+    *UNCLASSIFIED_FEED_BIZ_TYPES,
+)
+MEITUAN_CPS_INVALID_STATUSES = ("4", "5")
+MEITUAN_CPS_SETTLED_STATUS = "6"
 
 
 def _beijing_today_start_utc() -> datetime:
@@ -28,20 +44,90 @@ def _beijing_today_start_utc() -> datetime:
     return start_bj.astimezone(timezone.utc)
 
 
-def dashboard_overview(db: Session) -> dict:
+def today_dau(db: Session) -> int:
+    """今日活跃用户数(DAU):北京时区今天 0 点后登录过(last_login_at)。
+
+    广告收益报表复用这个函数;历史窗口 DAU 由 dashboard_overview 的 period 口径另算。
+    """
     today_start = _beijing_today_start_utc()
+    return int(
+        db.execute(select(func.count(User.id)).where(User.last_login_at >= today_start)).scalar_one()
+    )
+
+
+def _default_period_end() -> date:
+    """新版大盘不含今日,默认窗口结束日=北京时间昨天。"""
+    return datetime.now(_BEIJING).date() - timedelta(days=1)
+
+
+def _normalize_period(date_from: date | None, date_to: date | None) -> tuple[date, date]:
+    end = date_to or _default_period_end()
+    start = date_from or end
+    if start > end:
+        start, end = end, start
+    return start, end
+
+
+def _period_bounds(date_from: date, date_to: date) -> tuple[datetime, datetime, datetime, datetime]:
+    """返回同一北京自然日窗口的 UTC aware 边界和北京 naive 边界。
+
+    user.created_at / last_login_at 是 UTC aware 口径;比较/金币等历史上有北京 naive
+    写入,所以两套边界同时保留。
+    """
+    start_bj = datetime.combine(date_from, time.min, tzinfo=_BEIJING)
+    end_bj = datetime.combine(date_to + timedelta(days=1), time.min, tzinfo=_BEIJING)
+    start_utc = start_bj.astimezone(timezone.utc)
+    end_utc = end_bj.astimezone(timezone.utc)
+    return (
+        start_utc,
+        end_utc,
+        start_bj.replace(tzinfo=None),
+        end_bj.replace(tzinfo=None),
+    )
+
+
+def _date_range(date_from: date, date_to: date) -> list[date]:
+    days = (date_to - date_from).days
+    return [date_from + timedelta(days=i) for i in range(days + 1)]
+
+
+def _commission_rate_percent(raw: str | None) -> Decimal | None:
+    """美团 commissionRate 原值: "300"=3%, "10"=0.1%;也兼容 "3%"。"""
+    if raw is None:
+        return None
+    s = str(raw).strip()
+    if not s:
+        return None
+    try:
+        if s.endswith("%"):
+            return Decimal(s[:-1])
+        val = Decimal(s)
+    except (InvalidOperation, ValueError):
+        return None
+    return val / Decimal("100")
+
+
+def dashboard_overview(
+    db: Session, *, date_from: date | None = None, date_to: date | None = None
+) -> dict:
+    today_start = _beijing_today_start_utc()
+    period_from, period_to = _normalize_period(date_from, date_to)
+    start_utc, end_utc, start_local, end_local = _period_bounds(period_from, period_to)
 
     def _count(model, *conds) -> int:
         stmt = select(func.count(model.id))
         if conds:
             stmt = stmt.where(*conds)
-        return db.execute(stmt).scalar_one()
+        return int(db.execute(stmt).scalar_one())
 
     def _sum(col, *conds) -> int:
         stmt = select(func.coalesce(func.sum(col), 0))
         if conds:
             stmt = stmt.where(*conds)
-        return db.execute(stmt).scalar_one()
+        return int(db.execute(stmt).scalar_one())
+
+    def _user_id_set(stmt) -> set[int]:
+        return {int(v) for v in db.execute(stmt).scalars().all() if v is not None}
 
     # ===== 用户 =====
     by_status = dict(
@@ -61,6 +147,204 @@ def dashboard_overview(db: Session) -> dict:
     comparison_total = _count(ComparisonRecord)
     comparison_success = _count(ComparisonRecord, ComparisonRecord.status == "success")
     success_rate = round(comparison_success / comparison_total, 4) if comparison_total else 0.0
+    period_comparison_conds = (
+        ComparisonRecord.created_at >= start_local,
+        ComparisonRecord.created_at < end_local,
+    )
+    period_comparison_total = _count(ComparisonRecord, *period_comparison_conds)
+    period_comparison_success = _count(
+        ComparisonRecord,
+        *period_comparison_conds,
+        ComparisonRecord.status == "success",
+    )
+    period_comparison_success_rate = (
+        round(period_comparison_success / period_comparison_total, 4)
+        if period_comparison_total
+        else 0.0
+    )
+    period_saved_positive_count = _count(
+        ComparisonRecord,
+        *period_comparison_conds,
+        ComparisonRecord.status == "success",
+        ComparisonRecord.saved_amount_cents > 0,
+    )
+    period_saved_positive_sum = _sum(
+        ComparisonRecord.saved_amount_cents,
+        *period_comparison_conds,
+        ComparisonRecord.status == "success",
+        ComparisonRecord.saved_amount_cents > 0,
+    )
+    period_avg_saved_cents = (
+        round(period_saved_positive_sum / period_saved_positive_count)
+        if period_saved_positive_count
+        else None
+    )
+    period_avg_duration_ms = db.execute(
+        select(func.avg(ComparisonRecord.total_ms)).where(
+            *period_comparison_conds,
+            ComparisonRecord.total_ms.is_not(None),
+            ComparisonRecord.total_ms > 0,
+        )
+    ).scalar_one()
+    period_avg_duration_ms = (
+        round(float(period_avg_duration_ms))
+        if period_avg_duration_ms is not None
+        else None
+    )
+
+    ordered_exists = (
+        select(SavingsRecord.id)
+        .where(
+            SavingsRecord.user_id == ComparisonRecord.user_id,
+            SavingsRecord.source == "compare",
+            SavingsRecord.shop_name.is_not(None),
+            SavingsRecord.shop_name == ComparisonRecord.store_name,
+        )
+        .exists()
+    )
+    period_ordered_count = _count(
+        ComparisonRecord,
+        *period_comparison_conds,
+        ComparisonRecord.store_name.is_not(None),
+        ordered_exists,
+    )
+
+    # ===== 日期窗口用户 =====
+    period_new_user_ids = _user_id_set(
+        select(User.id).where(User.created_at >= start_utc, User.created_at < end_utc)
+    )
+    login_user_ids = _user_id_set(
+        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc)
+    )
+    compare_user_ids = _user_id_set(
+        select(ComparisonRecord.user_id).where(*period_comparison_conds)
+    )
+    coupon_user_ids = _user_id_set(
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date >= period_from,
+            CouponPromptEngagement.engage_date <= period_to,
+            CouponPromptEngagement.engage_type == "claim_started",
+        )
+    )
+    period_active_user_ids = login_user_ids | compare_user_ids | coupon_user_ids
+    period_retained_new_user_ids = period_new_user_ids & period_active_user_ids
+    period_retention_rate = (
+        round(len(period_retained_new_user_ids) / len(period_new_user_ids), 4)
+        if period_new_user_ids
+        else None
+    )
+    trend_points: list[dict] = []
+    for cur_date in _date_range(period_from, period_to):
+        day_start_utc, day_end_utc, day_start_local, day_end_local = _period_bounds(
+            cur_date, cur_date
+        )
+        daily_comparison_conds = (
+            ComparisonRecord.created_at >= day_start_local,
+            ComparisonRecord.created_at < day_end_local,
+        )
+        daily_login_user_ids = _user_id_set(
+            select(User.id).where(
+                User.last_login_at >= day_start_utc,
+                User.last_login_at < day_end_utc,
+            )
+        )
+        daily_compare_user_ids = _user_id_set(
+            select(ComparisonRecord.user_id).where(*daily_comparison_conds)
+        )
+        daily_coupon_user_ids = _user_id_set(
+            select(CouponPromptEngagement.user_id).where(
+                CouponPromptEngagement.engage_date == cur_date,
+                CouponPromptEngagement.engage_type == "claim_started",
+            )
+        )
+        trend_points.append(
+            {
+                "date": cur_date,
+                "active_users": len(
+                    daily_login_user_ids | daily_compare_user_ids | daily_coupon_user_ids
+                ),
+                "new_users": _count(
+                    User,
+                    User.created_at >= day_start_utc,
+                    User.created_at < day_end_utc,
+                ),
+                "comparisons": _count(ComparisonRecord, *daily_comparison_conds),
+            }
+        )
+
+    period_coin_conds = (
+        CoinTransaction.created_at >= start_local,
+        CoinTransaction.created_at < end_local,
+        CoinTransaction.amount > 0,
+    )
+    period_reward_video_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
+    )
+    period_feed_ad_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type == "feed_ad_reward",
+    )
+    period_signin_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type == "signin",
+    )
+    period_signin_boost_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type == "signin_boost",
+    )
+    period_task_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type.like("task_%"),
+    )
+    period_coupon_reward_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type.in_(COUPON_REWARD_BIZ_TYPES),
+    )
+    period_comparison_reward_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type.in_(COMPARISON_REWARD_BIZ_TYPES),
+    )
+    period_regular_task_coin_total = _sum(
+        CoinTransaction.amount,
+        *period_coin_conds,
+        CoinTransaction.biz_type.notin_(REGULAR_TASK_EXCLUDED_BIZ_TYPES),
+    )
+    period_meituan_orders = list(
+        db.execute(
+            select(CpsOrder).where(
+                CpsOrder.pay_time >= start_utc,
+                CpsOrder.pay_time < end_utc,
+            )
+        ).scalars()
+    )
+    period_meituan_valid_orders = [
+        o for o in period_meituan_orders if o.mt_status not in MEITUAN_CPS_INVALID_STATUSES
+    ]
+    period_meituan_hit_count = 0
+    period_meituan_miss_count = 0
+    period_meituan_unknown_rate_count = 0
+    for order in period_meituan_valid_orders:
+        rate = _commission_rate_percent(order.commission_rate)
+        if rate is None:
+            period_meituan_unknown_rate_count += 1
+        elif rate < Decimal("1"):
+            period_meituan_miss_count += 1
+        else:
+            period_meituan_hit_count += 1
+    period_meituan_hit_denominator = period_meituan_hit_count + period_meituan_miss_count
+    period_meituan_hit_rate = (
+        round(period_meituan_hit_count / period_meituan_hit_denominator, 4)
+        if period_meituan_hit_denominator
+        else None
+    )
 
     return {
         "users": {
@@ -69,7 +353,7 @@ def dashboard_overview(db: Session) -> dict:
             "disabled": by_status.get("disabled", 0),
             "deleted": by_status.get("deleted", 0),
             "new_today": _count(User, User.created_at >= today_start),
-            "dau": _count(User, User.last_login_at >= today_start),
+            "dau": today_dau(db),
         },
         "coins": {
             # 累计发放金币(coin_transaction 里所有 amount>0 之和;负数是兑换/扣减不计)
@@ -119,7 +403,61 @@ def dashboard_overview(db: Session) -> dict:
             "success": comparison_success,
             "success_rate": success_rate,
         },
-        "feedback": {"new": _count(Feedback, Feedback.status.in_(("pending", "new")))},
-        # CPS 收入数据源未接(referral-link 只换链接,转化/佣金未回收)→ 前端显示"待接入"。
-        "cps": {"available": False, "note": "CPS 转化数据未接入(P2)"},
+        "period": {
+            "date_from": period_from,
+            "date_to": period_to,
+            "users": {
+                "new": len(period_new_user_ids),
+                "active": len(period_active_user_ids),
+                "retained_new_users": len(period_retained_new_user_ids),
+                "retention_rate": period_retention_rate,
+                "retention_note": (
+                    "近似口径:登录(last_login_at)+已上报比价记录+领券claim_started;"
+                    "尚不包含未完成上报的比价开始事件"
+                ),
+            },
+            "comparison": {
+                "total": period_comparison_total,
+                "success": period_comparison_success,
+                "success_rate": period_comparison_success_rate,
+                "ordered": period_ordered_count,
+                "average_duration_ms": period_avg_duration_ms,
+                "average_saved_cents": period_avg_saved_cents,
+            },
+            "coins": {
+                "granted_total": _sum(CoinTransaction.amount, *period_coin_conds),
+                "reward_video_coin_total": period_reward_video_coin_total,
+                "feed_ad_coin_total": period_feed_ad_coin_total,
+                "signin_coin_total": period_signin_coin_total,
+                "signin_boost_coin_total": period_signin_boost_coin_total,
+                "task_coin_total": period_task_coin_total,
+                "coupon_reward_coin_total": period_coupon_reward_coin_total,
+                "comparison_reward_coin_total": period_comparison_reward_coin_total,
+                "regular_task_coin_total": period_regular_task_coin_total,
+            },
+            "cash": {
+                "withdraw_success_cents": _sum(
+                    WithdrawOrder.amount_cents,
+                    WithdrawOrder.status == "success",
+                    WithdrawOrder.created_at >= start_local,
+                    WithdrawOrder.created_at < end_local,
+                ),
+            },
+            "trend": trend_points,
+        },
+        "feedback": {
+            "new": _count(Feedback, Feedback.status.in_(("pending", "new"))),
+        },
+        "cps": {
+            "available": True,
+            "note": "美团 CPS 读 cps_order 对账订单;淘宝/京东佣金暂空",
+            "meituan_order_count": len(period_meituan_valid_orders),
+            "meituan_commission_cents": sum(
+                o.commission_cents or 0 for o in period_meituan_valid_orders
+            ),
+            "meituan_hit_count": period_meituan_hit_count,
+            "meituan_miss_count": period_meituan_miss_count,
+            "meituan_unknown_rate_count": period_meituan_unknown_rate_count,
+            "meituan_hit_rate": period_meituan_hit_rate,
+        },
     }

app/admin/routers/ad_audit.py

@@ -26,7 +26,7 @@ def get_ad_coin_audit(
     date: Annotated[str | None, Query(description="北京时间 YYYY-MM-DD,默认今天")] = None,
     user_id: Annotated[int | None, Query(description="只看某用户;不传=全部用户")] = None,
     scene: Annotated[
-        str | None, Query(description="reward_video / feed;不传=两类都要")
+        str | None, Query(description="reward_video / feed / draw;不传=全部")
     ] = None,
     limit: Annotated[int, Query(ge=1, le=500)] = 100,
     only_mismatch: Annotated[

app/admin/routers/ad_revenue.py

@@ -11,7 +11,13 @@ from fastapi import APIRouter, Depends, HTTPException, Query
 
 from app.admin.deps import AdminDb, get_current_admin
 from app.admin.repositories import ad_revenue
-from app.admin.schemas.ad_revenue import AdRevenueDaily, AdRevenueReportOut, AdRevenueRow
+from app.admin.schemas.ad_revenue import (
+    AdRevenueDaily,
+    AdRevenueHourly,
+    AdRevenueReportOut,
+    AdRevenueRow,
+    AdRevenueTypeStat,
+)
 from app.core.rewards import cn_today
 
 router = APIRouter(
@@ -43,10 +49,28 @@ def get_ad_revenue_report(
         str | None,
         Query(description="reward_video / feed / draw;不传=全部类型"),
     ] = None,
+    feed_scene: Annotated[
+        str | None,
+        Query(
+            description="comparison(比价) / coupon(领券) / welfare(福利);不传=全部场景。"
+            "全局筛选,同时影响明细 / 合计 / 趋势"
+        ),
+    ] = None,
+    app_env: Annotated[
+        str | None,
+        Query(
+            description="prod(正式应用) / test(测试应用);不传=全部。"
+            "建议正式收益报表选 prod,避免测试应用的假 eCPM 污染收益合计/平均"
+        ),
+    ] = None,
     granularity: Annotated[
         str, Query(description="day=按天 / hour=按小时(北京时间);区间>1 天建议用 day")
     ] = "day",
-    limit: Annotated[int, Query(ge=1, le=1000)] = 500,
+    limit: Annotated[int, Query(ge=1, le=1000, description="每页条数(分页大小)")] = 500,
+    offset: Annotated[int, Query(ge=0, description="分页偏移(已跳过的条数)=(页码-1)×每页条数")] = 0,
+    sort: Annotated[
+        str, Query(description="排序:time=时间倒序(默认) / ecpm=按 eCPM 数值倒序")
+    ] = "time",
 ) -> AdRevenueReportOut:
     today = cn_today()
     d_from = _parse_day(date_from, field="date_from", default=today)
@@ -58,16 +82,23 @@ def get_ad_revenue_report(
 
     result = ad_revenue.ad_revenue_report(
         db, date_from=d_from.isoformat(), date_to=d_to.isoformat(),
-        user_id=user_id, ad_type=ad_type, granularity=granularity, limit=limit,
+        user_id=user_id, ad_type=ad_type, feed_scene=feed_scene, app_env=app_env,
+        granularity=granularity, limit=limit, offset=offset, sort=sort,
     )
     return AdRevenueReportOut(
         date_from=d_from.isoformat(),
         date_to=d_to.isoformat(),
         daily=[AdRevenueDaily(**d) for d in result["daily"]],
+        hourly=[AdRevenueHourly(**h) for h in result["hourly"]],
+        type_stats={k: AdRevenueTypeStat(**v) for k, v in result["type_stats"].items()},
+        dau=result["dau"],
         total=result["total"],
         truncated=result["truncated"],
         total_impressions=result["total_impressions"],
         total_revenue_yuan=result["total_revenue_yuan"],
+        total_pangle_revenue_yuan=result["total_pangle_revenue_yuan"],
+        total_pangle_api_revenue_yuan=result["total_pangle_api_revenue_yuan"],
+        pangle_revenue_available=result["pangle_revenue_available"],
         total_expected_coin=result["total_expected_coin"],
         total_actual_coin=result["total_actual_coin"],
         mismatch_count=result["mismatch_count"],

app/admin/routers/cps.py

@@ -7,7 +7,7 @@
 from __future__ import annotations
 
 import time
-from datetime import datetime, timedelta, timezone
+from datetime import date as _date, datetime, time as _dt_time, timedelta, timezone
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, File, HTTPException, Query, Request, UploadFile
@@ -340,24 +340,77 @@ def generate_referral_links(
 
 
 # ───────────── 订单对账 ─────────────
+_BEIJING = timezone(timedelta(hours=8))
+
+
+def _parse_day(value: str | None, *, field: str) -> _date | None:
+    if value is None:
+        return None
+    try:
+        return _date.fromisoformat(value)
+    except ValueError as e:
+        raise HTTPException(status_code=422, detail=f"{field} 需为 YYYY-MM-DD") from e
+
+
+def _reconcile_range_to_ts(
+    date_from: _date | None, date_to: _date | None, days: int
+) -> tuple[int, int]:
+    if date_from is None and date_to is None:
+        now = int(time.time())
+        return now - days * 86400, now
+
+    start_day = date_from or date_to
+    end_day = date_to or date_from
+    if start_day is None or end_day is None:
+        raise HTTPException(status_code=422, detail="日期参数不完整")
+    if start_day > end_day:
+        start_day, end_day = end_day, start_day
+    if (end_day - start_day).days + 1 > 90:
+        raise HTTPException(status_code=422, detail="美团订单查询最长 90 天")
+
+    start_dt = datetime.combine(start_day, _dt_time.min, tzinfo=_BEIJING)
+    end_dt = datetime.combine(end_day + timedelta(days=1), _dt_time.min, tzinfo=_BEIJING)
+    return int(start_dt.timestamp()), int(end_dt.timestamp())
+
+
 @router.post("/orders/reconcile", response_model=CpsReconcileResult, summary="拉取美团订单对账")
 def reconcile_orders(
     request: Request,
     admin: Annotated[AdminUser, Depends(require_role("finance"))],
     db: AdminDb,
-    days: Annotated[int, Query(ge=1, le=90)] = 7,
+    date_from: Annotated[str | None, Query(description="起始日 YYYY-MM-DD")] = None,
+    date_to: Annotated[str | None, Query(description="结束日 YYYY-MM-DD")] = None,
+    days: Annotated[int, Query(ge=1, le=90, description="未传日期时默认拉近 N 天")] = 7,
     sid: Annotated[str | None, Query(max_length=64)] = None,
+    query_time_type: Annotated[int, Query(ge=1, le=2)] = 1,
 ) -> CpsReconcileResult:
-    now = int(time.time())
+    start_ts, end_ts = _reconcile_range_to_ts(
+        _parse_day(date_from, field="date_from"),
+        _parse_day(date_to, field="date_to"),
+        days,
+    )
     try:
         result = cps_repo.reconcile_orders(
-            db, start_time=now - days * 86400, end_time=now, sid=sid,
+            db,
+            start_time=start_ts,
+            end_time=end_ts,
+            query_time_type=query_time_type,
+            sid=sid,
         )
     except MeituanCpsError as e:
         raise HTTPException(status_code=502, detail=f"美团拉单失败: {e}") from e
     write_audit(
         db, admin, action="cps.order.reconcile", target_type="cps_order", target_id=None,
-        detail={"days": days, "sid": sid, **result}, ip=get_client_ip(request), commit=True,
+        detail={
+            "date_from": date_from,
+            "date_to": date_to,
+            "days": days,
+            "sid": sid,
+            "query_time_type": query_time_type,
+            **result,
+        },
+        ip=get_client_ip(request),
+        commit=True,
     )
     return CpsReconcileResult(**result)
 
@@ -468,7 +521,7 @@ def group_daily(
     while cur <= last:
         cp = click_points[idx] if idx < len(click_points) else None
         row = {
-            "date": cur.strftime("%m-%d"),
+            "date": cur.strftime("%Y-%m-%d"),
             "click_pv": cp["click_pv"] if cp else 0,
             "click_uv": cp["click_uv"] if cp else 0,
             "copy_pv": cp["copy_pv"] if cp else 0,
@@ -496,3 +549,28 @@ def group_wx_users(group_id: int, db: AdminDb) -> dict:
     if group is None:
         raise HTTPException(status_code=404, detail="群不存在")
     return {"users": cps_repo.group_wx_users(db, group_id=group_id)}
+
+
+@router.get("/groups/{group_id}/day-users", summary="某天该群按用户的领券/点击 + 每人点过的券")
+def group_day_users(
+    group_id: int,
+    db: AdminDb,
+    date: Annotated[str, Query(description="北京日期 YYYY-MM-DD")],
+) -> dict:
+    group = cps_repo.get_group(db, group_id)
+    if group is None:
+        raise HTTPException(status_code=404, detail="群不存在")
+    bj = timezone(timedelta(hours=8))
+    try:
+        day0 = datetime.strptime(date, "%Y-%m-%d").replace(tzinfo=bj)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail="date 格式应为 YYYY-MM-DD") from e
+    start = day0.replace(hour=0, minute=0, second=0, microsecond=0)
+    end = start + timedelta(days=1)
+    users = cps_repo.group_day_users(db, group_id=group_id, start=start, end=end)
+    return {
+        "group_id": group.id,
+        "group_name": group.name,
+        "date": date,
+        "users": users,
+    }

app/admin/routers/dashboard.py

@@ -1,7 +1,9 @@
 """admin 数据大盘(只读聚合)。"""
 from __future__ import annotations
 
-from fastapi import APIRouter, Depends
+from datetime import date
+
+from fastapi import APIRouter, Depends, Query
 
 from app.admin.deps import AdminDb, get_current_admin
 from app.admin.repositories import stats
@@ -15,5 +17,11 @@ router = APIRouter(
 
 
 @router.get("/overview", response_model=DashboardOverview, summary="大盘核心指标")
-def overview(db: AdminDb) -> DashboardOverview:
-    return DashboardOverview.model_validate(stats.dashboard_overview(db))
+def overview(
+    db: AdminDb,
+    date_from: date | None = Query(None, description="北京时间自然日起始日 YYYY-MM-DD"),
+    date_to: date | None = Query(None, description="北京时间自然日结束日 YYYY-MM-DD"),
+) -> DashboardOverview:
+    return DashboardOverview.model_validate(
+        stats.dashboard_overview(db, date_from=date_from, date_to=date_to)
+    )

app/admin/routers/device_liveness.py

@@ -0,0 +1,63 @@
+"""admin 设备存活监控(只读):列设备心跳/在线掉线 + 顶部统计卡片。
+
+数据源 device_liveness 表(心跳 last_heartbeat_at + liveness_state + kill_alert_pending,
+见 app/models/device.py)。在线/掉线、掉线时长由 repo 按 HEARTBEAT_TIMEOUT_MINUTES 阈值派生。
+纯读:无写、无审计。任意登录管理员可看(同大盘/设备管理,无角色门)。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import queries
+from app.admin.schemas.common import CursorPage
+from app.admin.schemas.device import DeviceLivenessItem, DeviceLivenessStats
+
+router = APIRouter(
+    prefix="/admin/api/device-liveness",
+    tags=["admin-device-liveness"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("/stats", response_model=DeviceLivenessStats, summary="设备存活统计(顶部卡片)")
+def device_stats(db: AdminDb) -> DeviceLivenessStats:
+    return DeviceLivenessStats(**queries.device_liveness_stats(db))
+
+
+@router.get(
+    "",
+    response_model=CursorPage[DeviceLivenessItem],
+    summary="设备存活列表(在线情况/设备id/归属用户 筛选 + 排序 + 分页,默认掉线置顶)",
+)
+def list_devices(
+    db: AdminDb,
+    status: Annotated[str | None, Query(pattern="^(online|offline|never)$")] = None,
+    device_id: Annotated[str | None, Query(max_length=128)] = None,
+    phone: Annotated[str | None, Query(max_length=20)] = None,
+    user_id: Annotated[int | None, Query()] = None,
+    sort_by: Annotated[
+        str, Query(pattern="^(status|last_heartbeat_at|created_at)$")
+    ] = "status",
+    sort_order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[DeviceLivenessItem]:
+    items, next_cursor, total = queries.list_device_liveness(
+        db,
+        status=status,
+        device_id=device_id,
+        phone=phone,
+        user_id=user_id,
+        sort_by=sort_by,
+        sort_order=sort_order,
+        limit=limit,
+        cursor=cursor,
+    )
+    return CursorPage(
+        items=[DeviceLivenessItem.model_validate(d) for d in items],
+        next_cursor=next_cursor,
+        total=total,
+    )

app/admin/routers/event_logs.py

@@ -0,0 +1,52 @@
+"""admin 埋点日志:列表 + 按事件 / 设备 / 用户 / 会话 / 时间筛选(只读,同库直接查 analytics_event)。"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, Query
+
+from app.admin.deps import AdminDb, get_current_admin
+from app.admin.repositories import queries
+from app.admin.schemas.analytics import AnalyticsEventOut
+from app.admin.schemas.common import CursorPage
+
+router = APIRouter(
+    prefix="/admin/api/event-logs",
+    tags=["admin-event-logs"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("", response_model=CursorPage[AnalyticsEventOut], summary="埋点日志列表")
+def list_event_logs(
+    db: AdminDb,
+    event: Annotated[str | None, Query(max_length=64)] = None,
+    device_id: Annotated[str | None, Query(max_length=64)] = None,
+    user_id: Annotated[int | None, Query()] = None,
+    session_id: Annotated[str | None, Query(max_length=64)] = None,
+    created_from: Annotated[datetime | None, Query()] = None,
+    created_to: Annotated[datetime | None, Query()] = None,
+    sort_by: Annotated[str, Query(pattern="^(id|created_at)$")] = "id",
+    sort_order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
+    limit: Annotated[int, Query(ge=1, le=100)] = 20,
+    cursor: Annotated[int | None, Query()] = None,
+) -> CursorPage[AnalyticsEventOut]:
+    items, next_cursor, total = queries.list_analytics_events(
+        db,
+        event=event,
+        device_id=device_id,
+        user_id=user_id,
+        session_id=session_id,
+        created_from=created_from,
+        created_to=created_to,
+        sort_by=sort_by,
+        sort_order=sort_order,
+        limit=limit,
+        cursor=cursor,
+    )
+    return CursorPage(
+        items=[AnalyticsEventOut.model_validate(e) for e in items],
+        next_cursor=next_cursor,
+        total=total,
+    )

app/admin/routers/feedback.py

@@ -10,7 +10,12 @@ from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
 from app.admin.repositories import mutations, queries
 from app.admin.schemas.common import CursorPage, OkResponse
-from app.admin.schemas.feedback import FeedbackApproveRequest, FeedbackOut, FeedbackRejectRequest
+from app.admin.schemas.feedback import (
+    FeedbackApproveRequest,
+    FeedbackOut,
+    FeedbackRejectRequest,
+    FeedbackSummary,
+)
 from app.models.admin import AdminUser
 from app.models.feedback import Feedback
 from app.repositories import wallet as wallet_repo
@@ -59,6 +64,11 @@ def list_feedbacks(
     )
 
 
+@router.get("/summary", response_model=FeedbackSummary, summary="反馈审核统计(各状态计数)")
+def feedback_summary(db: AdminDb) -> FeedbackSummary:
+    return FeedbackSummary.model_validate(queries.feedback_summary(db))
+
+
 @router.post("/{feedback_id}/handle", response_model=OkResponse, summary="标记反馈已处理")
 def handle_feedback(
     feedback_id: int,

app/admin/routers/price_report.py

@@ -37,11 +37,14 @@ def list_price_reports(
     db: AdminDb,
     status: Annotated[str | None, Query()] = None,
     user_id: Annotated[int | None, Query()] = None,
+    sort_by: Annotated[str, Query(pattern="^(id|created_at)$")] = "id",
+    sort_order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
     limit: Annotated[int, Query(ge=1, le=100)] = 20,
     cursor: Annotated[int | None, Query()] = None,
 ) -> CursorPage[PriceReportOut]:
     items, next_cursor, total = queries.list_price_reports(
-        db, status=status, user_id=user_id, limit=limit, cursor=cursor,
+        db, status=status, user_id=user_id,
+        sort_by=sort_by, sort_order=sort_order, limit=limit, cursor=cursor,
     )
     return CursorPage(
         items=[PriceReportOut.model_validate(r) for r in items],

app/admin/schemas/ad_config.py

@@ -9,8 +9,8 @@ class AdConfigOut(BaseModel):
 
     app_id: str
     reward_code_id: str
-    compare_feed_code_id: str
-    coupon_feed_code_id: str
+    compare_draw_code_id: str
+    coupon_draw_code_id: str
     reward_mkey: str
     reward_enabled: bool
     compare_ad_enabled: bool
@@ -23,8 +23,8 @@ class AdConfigUpdate(BaseModel):
 
     app_id: str | None = None
     reward_code_id: str | None = None
-    compare_feed_code_id: str | None = None
-    coupon_feed_code_id: str | None = None
+    compare_draw_code_id: str | None = None
+    coupon_draw_code_id: str | None = None
     reward_mkey: str | None = None
     reward_enabled: bool | None = None
     compare_ad_enabled: bool | None = None

app/admin/schemas/ad_revenue.py

@@ -40,15 +40,38 @@ class AdRevenueRecord(BaseModel):
 
 
 class AdRevenueDaily(BaseModel):
-    """按日期汇总的一天(供前端按天趋势图;全量,不受 limit 影响)。"""
+    """按日期汇总的一天(供前端按天趋势图;全量,不受分页影响)。"""
 
     date: str = Field(..., description="北京时间 YYYY-MM-DD")
     impressions: int = Field(..., description="当天展示条数合计")
-    revenue_yuan: float = Field(..., description="当天预估收益合计(元)")
+    revenue_yuan: float = Field(..., description="当天客户端预估收益合计(元;eCPM 折算)")
+    pangle_revenue_yuan: float | None = Field(
+        None, description="当天穿山甲后台预估收益(元;GroMore revenue);非全量视图/无数据为空"
+    )
+    pangle_api_revenue_yuan: float | None = Field(
+        None, description="当天穿山甲收益Api(元;GroMore api_revenue,更接近结算);未配/当天/无数据为空"
+    )
     expected_coin: int = Field(..., description="当天应发金币合计")
     actual_coin: int = Field(..., description="当天实发金币合计")
 
 
+class AdRevenueHourly(BaseModel):
+    """按北京小时(0–23)汇总的一小时(供前端按小时趋势图;全量,不受分页影响,单日 granularity=hour 时非空)。"""
+
+    hour: int = Field(..., description="北京时间小时 0–23")
+    impressions: int = Field(..., description="该小时展示条数合计")
+    revenue_yuan: float = Field(..., description="该小时预估收益合计(元)")
+    expected_coin: int = Field(..., description="该小时应发金币合计")
+    actual_coin: int = Field(..., description="该小时实发金币合计")
+
+
+class AdRevenueTypeStat(BaseModel):
+    """按广告类型(ad_type)的小计:展示条数 + 预估收益(eCPM 由前端用 收益÷展示×1000 算)。"""
+
+    impressions: int = Field(..., description="该类型展示条数合计")
+    revenue_yuan: float = Field(..., description="该类型预估收益合计(元)")
+
+
 class AdRevenueRow(BaseModel):
     """一次广告事件(逐条一行):激励视频展示与发奖按 ad_session_id 合并;信息流展示 / 发奖各自成行。"""
 
@@ -56,7 +79,12 @@ class AdRevenueRow(BaseModel):
     report_date: str = Field(..., description="该事件所属日期(北京时间 YYYY-MM-DD)")
     user_id: int
     user_phone: str | None = Field(None, description="用户手机号(admin 展示用,完整;用户已删 / 查不到为空)")
-    ad_type: str = Field(..., description="reward_video(激励视频) / feed(信息流) / draw(历史 Draw 信息流)")
+    ad_type: str = Field(..., description="reward_video(激励视频) / feed(信息流) / draw(Draw 信息流);历史 NULL 视为 feed")
+    feed_scene: str | None = Field(
+        None,
+        description="点位场景:comparison(比价) / coupon(领券) / welfare(福利);供区分比价/领券 Draw 收益;"
+        "激励视频与旧数据为空",
+    )
     app_env: str | None = Field(None, description="我们的应用:prod(傻瓜比价正式) / test(测试应用);旧数据为空")
     our_code_id: str | None = Field(None, description="我们后台配置的代码位 ID(104xxx);旧数据为空")
     hour: int | None = Field(None, description="北京时间小时 0–23(granularity=hour 时有值;按天为 null)")
@@ -86,10 +114,36 @@ class AdRevenueReportOut(BaseModel):
     date_from: str = Field(..., description="报表起始日期(北京时间 YYYY-MM-DD)")
     date_to: str = Field(..., description="报表结束日期(北京时间 YYYY-MM-DD,闭区间;单日时与 date_from 相同)")
     daily: list[AdRevenueDaily] = Field(..., description="按日期汇总序列(全量,供按天趋势图)")
-    total: int = Field(..., description="广告事件总数(全量,不受 limit 影响)")
-    truncated: bool = Field(..., description="明细是否被 limit 截断")
+    hourly: list[AdRevenueHourly] = Field(
+        default_factory=list,
+        description="按小时汇总序列(全量,供按小时趋势图;按天查询时为空)",
+    )
+    type_stats: dict[str, AdRevenueTypeStat] = Field(
+        default_factory=dict,
+        description="按广告类型(ad_type)小计 {ad_type: {impressions, revenue_yuan}};前端取 draw / reward_video 做分类大盘",
+    )
+    dau: int | None = Field(
+        None,
+        description="今日活跃用户数(复用大盘口径,last_login_at);**仅查询=今日单天时有值**,历史/多天为 null",
+    )
+    total: int = Field(..., description="广告事件总数(全量,不受分页影响;= 当前筛选下的分页总条数)")
+    truncated: bool = Field(..., description="当前页之后是否还有更多事件(len(events) > offset + limit)")
     total_impressions: int = Field(..., description="全量展示条数合计")
-    total_revenue_yuan: float = Field(..., description="全量收益合计(元)")
+    total_revenue_yuan: float = Field(..., description="全量客户端预估收益合计(元;eCPM 折算)")
+    total_pangle_revenue_yuan: float | None = Field(
+        None,
+        description="全量穿山甲后台预估收益合计(元;GroMore revenue)。穿山甲无用户/类型/场景维度,"
+        "仅「全量视图」(未按 user_id/ad_type/feed_scene 过滤)时有值,否则为 null",
+    )
+    total_pangle_api_revenue_yuan: float | None = Field(
+        None,
+        description="全量穿山甲收益Api合计(元;GroMore api_revenue,各 ADN 回传、更接近结算);"
+        "未配 Reporting / 查当天 / 非全量视图 时为 null",
+    )
+    pangle_revenue_available: bool = Field(
+        False,
+        description="本次结果是否带穿山甲后台收益(=全量视图且已同步到数据)。false 时前端「穿山甲收益」显示「-」",
+    )
     total_expected_coin: int = Field(..., description="全量应发金币合计")
     total_actual_coin: int = Field(..., description="全量实发金币合计")
     mismatch_count: int = Field(..., description="应发≠实发的发奖条数(=0 说明全部按公式发放)")

app/admin/schemas/analytics.py

@@ -0,0 +1,33 @@
+"""admin 埋点日志列表响应。"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AnalyticsEventOut(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    event: str
+    # Who
+    device_id: str
+    user_id: int | None
+    # When
+    session_id: str | None
+    client_ts: int
+    sent_at: int | None
+    created_at: datetime  # 服务端接收时间(server_at)
+    # Where
+    page: str | None
+    client_ip: str | None
+    # How
+    oem: str | None
+    os: str | None
+    model: str | None
+    app_ver: str | None
+    network: str | None
+    channel: str | None
+    # What 专属
+    props: dict | None

app/admin/schemas/dashboard.py

@@ -1,6 +1,8 @@
 """admin 大盘 schemas(对应 stats.dashboard_overview 的嵌套结构)。"""
 from __future__ import annotations
 
+from datetime import date
+
 from pydantic import BaseModel
 
 
@@ -38,6 +40,56 @@ class DashboardComparison(BaseModel):
     success_rate: float
 
 
+class DashboardPeriodUsers(BaseModel):
+    new: int
+    active: int
+    retained_new_users: int
+    retention_rate: float | None = None
+    retention_note: str
+
+
+class DashboardPeriodComparison(BaseModel):
+    total: int
+    success: int
+    success_rate: float
+    ordered: int
+    average_duration_ms: int | None = None
+    average_saved_cents: int | None = None
+
+
+class DashboardPeriodCoins(BaseModel):
+    granted_total: int
+    reward_video_coin_total: int = 0
+    feed_ad_coin_total: int = 0
+    signin_coin_total: int = 0
+    signin_boost_coin_total: int = 0
+    task_coin_total: int = 0
+    coupon_reward_coin_total: int = 0
+    comparison_reward_coin_total: int = 0
+    regular_task_coin_total: int = 0
+
+
+class DashboardPeriodCash(BaseModel):
+    withdraw_success_cents: int
+
+
+class DashboardTrendPoint(BaseModel):
+    date: date
+    active_users: int
+    new_users: int
+    comparisons: int
+
+
+class DashboardPeriod(BaseModel):
+    date_from: date
+    date_to: date
+    users: DashboardPeriodUsers
+    comparison: DashboardPeriodComparison
+    coins: DashboardPeriodCoins
+    cash: DashboardPeriodCash
+    trend: list[DashboardTrendPoint] = []
+
+
 class DashboardFeedback(BaseModel):
     new: int
 
@@ -45,6 +97,12 @@ class DashboardFeedback(BaseModel):
 class DashboardCps(BaseModel):
     available: bool
     note: str
+    meituan_order_count: int = 0
+    meituan_commission_cents: int = 0
+    meituan_hit_count: int = 0
+    meituan_miss_count: int = 0
+    meituan_unknown_rate_count: int = 0
+    meituan_hit_rate: float | None = None
 
 
 class DashboardOverview(BaseModel):
@@ -52,5 +110,6 @@ class DashboardOverview(BaseModel):
     coins: DashboardCoins
     cash: DashboardCash
     comparison: DashboardComparison
+    period: DashboardPeriod
     feedback: DashboardFeedback
     cps: DashboardCps

app/admin/schemas/device.py

@@ -0,0 +1,54 @@
+"""admin 设备存活监控 schemas(只读)。
+
+数据源 device_liveness 表(见 app/models/device.py)。online / display_state /
+offline_seconds 为后端按 HEARTBEAT_TIMEOUT_MINUTES 阈值派生的瞬态字段(非 DB 列),
+在 repo 里算好挂到行上,供 from_attributes 读出。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class DeviceLivenessItem(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    user_id: int
+    # join user 取(瞬态;理论上 user 恒存在,留空仅防脏数据)
+    phone: str | None = None
+    nickname: str | None = None
+
+    device_id: str
+    device_model: str | None = None      # 由 device_id 解析(device_<机型>_<hash>);非 DB 列
+    platform: str
+    app_version: str | None = None
+    registration_id: str | None = None  # 非空 = 拿到极光 token、可推送
+
+    ever_protected: bool                 # 是否开过无障碍(=该设备对功能有意义)
+    first_protected_at: datetime | None = None   # 首次开无障碍时刻(老设备为 null)
+    last_heartbeat_at: datetime | None = None
+    last_report_protection_on: bool      # 心跳里上报的无障碍开关(恒 true,仅观测)
+    liveness_state: str                  # unknown / alive / silent(当前未用) / notified
+    notified_at: datetime | None = None
+    kill_alert_pending: bool             # 掉线召回待客户端 ack(与 state 解耦)
+    created_at: datetime
+    updated_at: datetime
+
+    # ===== 后端派生(非 DB 列)=====
+    online: bool = False                 # ever_protected 且距上次心跳 ≤ 阈值
+    # 显示态:online=在线 / offline=已掉线 / never=从未启用(没开过无障碍)
+    display_state: str = "never"
+    # 掉线时长(秒):仅 offline 时有值;在线 / 从未启用为 None
+    offline_seconds: int | None = None
+
+
+class DeviceLivenessStats(BaseModel):
+    """顶部卡片:总设备数 + 在线 / 已掉线 / 未启用(按心跳阈值派生的 operator 口径,
+    不暴露内部状态机 unknown/alive/silent/notified)。"""
+
+    total: int
+    online: int
+    offline: int
+    never: int

app/admin/schemas/feedback.py

@@ -23,6 +23,14 @@ class FeedbackOut(BaseModel):
     reviewed_by_admin_id: int | None = None
     reviewed_at: datetime | None = None
     created_at: datetime
+    # 提交端环境快照(feedback 表列):提交版本号 / 机型OS版本;改版前的历史反馈为 None
+    app_version: str | None = None
+    device_model: str | None = None
+    rom_name: str | None = None
+    android_version: str | None = None
+    # 联表瞬态字段(queries._attach_user_info 挂):列表展示完整手机号,点手机号查该用户全部反馈
+    phone: str | None = None
+    nickname: str | None = None
 
 
 class FeedbackApproveRequest(BaseModel):
@@ -37,3 +45,12 @@ class FeedbackApproveRequest(BaseModel):
 class FeedbackRejectRequest(BaseModel):
     reason: str = Field(min_length=1, max_length=256, description="未采纳原因,用户端可见")
     note: str | None = Field(default=None, max_length=256, description="运营内部审核备注")
+
+
+class FeedbackSummary(BaseModel):
+    """审核台顶部各状态计数(pending 含历史 new 态)。"""
+
+    pending: int
+    adopted: int
+    rejected: int
+    total: int

app/admin/schemas/price_report.py

@@ -31,6 +31,17 @@ class PriceReportOut(BaseModel):
     reward_coins: int | None = None
     reviewed_at: datetime | None = None
     created_at: datetime
+    # 联表瞬态字段:phone/nickname 由 _attach_user_info 挂(展示完整手机号、点击查该用户全部上报);
+    # 其余由 _attach_price_report_comparison 从关联比价记录挂:trace_*(Trace 列点跳调试链接)、
+    # device_model/rom_name/android_version(机型OS版本列)、app_version(提交版本号列)
+    phone: str | None = None
+    nickname: str | None = None
+    trace_id: str | None = None
+    trace_url: str | None = None
+    device_model: str | None = None
+    rom_name: str | None = None
+    android_version: str | None = None
+    app_version: str | None = None
 
 
 class PriceReportRejectRequest(BaseModel):

app/api/internal/launch_confirm.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import hmac
 import logging
+from datetime import datetime, timedelta, timezone
 from typing import Annotated
 
 from fastapi import APIRouter, Header, HTTPException, status
@@ -21,6 +22,7 @@ from app.repositories import launch_confirm_sample as repo
 from app.schemas.launch_confirm_sample import (
     LaunchConfirmSampleIn,
     LaunchConfirmSampleOut,
+    LaunchConfirmSampleRow,
 )
 
 logger = logging.getLogger("shagua.internal.launch_confirm")
@@ -61,3 +63,34 @@ def report_launch_confirm_sample(
         payload.exec_success, payload.trace_id,
     )
     return LaunchConfirmSampleOut(id=sid)
+
+
+@router.get(
+    "/launch-confirm-samples",
+    response_model=list[LaunchConfirmSampleRow],
+    summary="启动确认窗兜底样本列表(沉淀脚本 distill 读; server→server, 不走 JWT)",
+)
+def list_launch_confirm_samples(
+    db: DbSession,
+    x_internal_secret: Annotated[str | None, Header()] = None,
+    exec_success: bool | None = None,
+    host_package: str | None = None,
+    since_days: int | None = None,
+    limit: int = 1000,
+) -> list[LaunchConfirmSampleRow]:
+    """读样本供 pricebot 的 distill_launch_confirm.py 聚合沉淀回 PROFILES。
+
+    与上报端点同一把共享密钥;exec_success/host_package/since_days 均可选,limit 默认 1000。
+    """
+    _check_secret(x_internal_secret)
+    since = None
+    if since_days and since_days > 0:
+        since = datetime.now(timezone.utc) - timedelta(days=since_days)
+    rows = repo.list_samples(
+        db,
+        exec_success=exec_success,
+        host_package=host_package,
+        since=since,
+        limit=limit,
+    )
+    return [LaunchConfirmSampleRow.model_validate(r) for r in rows]

app/api/v1/ad.py

@@ -9,8 +9,8 @@
 """
 from __future__ import annotations
 
-import logging
 import json
+import logging
 import uuid
 
 from fastapi import APIRouter, Depends, HTTPException, Request, status
@@ -18,8 +18,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request, status
 from app.api.deps import CurrentUser, DbSession
 from app.core import rewards
 from app.core.config import settings
-from app.integrations import pangle
 from app.core.ratelimit import rate_limit
+from app.integrations import pangle
 from app.repositories import ad_ecpm as crud_ecpm
 from app.repositories import ad_feed_reward as crud_feed
 from app.repositories import ad_reward as crud_ad
@@ -120,6 +120,21 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
     ad_session_id = extra.get("ad_session_id")
     ecpm = params.get("ecpm")
 
+    # 环境隔离:激励视频 mediaExtra 里带「这次观看属于哪个后端环境」(srv_env=dev/prod,客户端按
+    # BuildConfig.DEBUG 决定),穿山甲 S2S 回调原样带回。回调 URL 在穿山甲后台只配一个(指向生产),
+    # 所以测试包(dev)看广告的 S2S 也会打到生产——若不拦,生产会把奖发给「本库里同 user_id 的另一个
+    # 真人」(user_id 是跨库不隔离的裸数字 → 跨库串号)。这里只处理「属于本服环境」的回调:环境不符
+    # 直接受理但不发币、不写任何记录,保证各环境后台广告收益页只含本环境用户。is_verify=true 让穿山甲
+    # 不再重试(测试用户的币由 localhost 的 test-grant 单独发,不依赖这条 S2S)。
+    # 兼容:旧客户端不带 srv_env(取不到)→ 视为本环境,照常处理,不误伤存量正式用户。
+    callback_env = extra.get("srv_env")
+    if callback_env and callback_env != settings.APP_ENV:
+        logger.info(
+            "pangle callback foreign env skip: callback_env=%s self_env=%s user_id=%d trans_id=%s",
+            callback_env, settings.APP_ENV, user_id, trans_id,
+        )
+        return PangleCallbackOut(is_verify=True, reason=REASON_OK)
+
     existing = crud_ad.find_by_trans(db, trans_id)
     if existing is not None:
         logger.info(
@@ -270,12 +285,13 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
         ad_type=payload.ad_type, ecpm_raw=payload.ecpm,
         ad_session_id=payload.ad_session_id,
         adn=payload.adn, slot_id=payload.slot_id,
+        feed_scene=payload.feed_scene,
         app_env=payload.app_env, our_code_id=payload.our_code_id,
     )
     logger.info(
-        "ad ecpm report user_id=%d type=%s session=%s ecpm=%s adn=%s slot=%s app=%s code=%s",
-        user.id, payload.ad_type, payload.ad_session_id, payload.ecpm, payload.adn, payload.slot_id,
-        payload.app_env, payload.our_code_id,
+        "ad ecpm report user_id=%d type=%s scene=%s session=%s ecpm=%s adn=%s slot=%s app=%s code=%s",
+        user.id, payload.ad_type, payload.feed_scene, payload.ad_session_id, payload.ecpm,
+        payload.adn, payload.slot_id, payload.app_env, payload.our_code_id,
     )
     return EcpmReportOut(ok=True)
 
@@ -386,6 +402,7 @@ def feed_reward(payload: FeedRewardIn, user: CurrentUser, db: DbSession) -> Feed
         client_event_id=payload.client_event_id,
         ecpm=payload.ecpm,
         duration_seconds=payload.duration_seconds,
+        ad_type=payload.ad_type,
         ad_session_id=payload.ad_session_id,
         adn=payload.adn,
         slot_id=payload.slot_id,
@@ -394,6 +411,7 @@ def feed_reward(payload: FeedRewardIn, user: CurrentUser, db: DbSession) -> Feed
         app_env=payload.app_env,
         our_code_id=payload.our_code_id,
         aborted=payload.aborted,
+        display_coin=payload.display_coin,
     )
     logger.info(
         "feed ad reward user_id=%d event=%s status=%s units=%d coin=%d",

app/api/v1/analytics.py

@@ -0,0 +1,31 @@
+"""客户端埋点上报接口。
+
+POST /api/v1/analytics/events — 批量接收新手引导(及后续)埋点,append 落 analytics_event 表。
+**不强制登录**(未登录态也要采集行为):user_id 由客户端在 body 里可选带上,不靠 Bearer。
+服务端补 client_ip(X-Forwarded-For)与 created_at(接收时间 = server_at)。
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Request
+
+from app.api.deps import DbSession
+from app.repositories import analytics as analytics_repo
+from app.schemas.analytics import AnalyticsBatchIn, AnalyticsIngestOut
+
+router = APIRouter(prefix="/api/v1/analytics", tags=["analytics"])
+
+
+def _client_ip(request: Request) -> str:
+    """取客户端 IP:生产经 nginx 反代优先 X-Forwarded-For 第一段,否则直连 IP(同 admin get_client_ip)。"""
+    xff = request.headers.get("x-forwarded-for")
+    if xff:
+        return xff.split(",")[0].strip()
+    return request.client.host if request.client else ""
+
+
+@router.post("/events", response_model=AnalyticsIngestOut, summary="批量上报埋点事件")
+def ingest_events(
+    batch: AnalyticsBatchIn, request: Request, db: DbSession
+) -> AnalyticsIngestOut:
+    n = analytics_repo.record_batch(db, batch, client_ip=_client_ip(request))
+    return AnalyticsIngestOut(received=n)

app/api/v1/auth.py

@@ -12,11 +12,11 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, Request, status
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import test_account
-from app.core.ratelimit import rate_limit
+from app.core.ratelimit import enforce_rate_limit, rate_limit
 from app.core.security import TokenError, decode_token, issue_token_pair
 from app.integrations.jiguang import JiguangError, mask_phone, verify_and_get_phone
 from app.integrations.sms import SmsError, send_code, verify_code
@@ -38,6 +38,12 @@ logger = logging.getLogger("shagua.auth")
 
 router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 
+# 手机号登录防刷:同一设备(device_id) + 同一 IP 每小时最多的登录尝试次数(成功/失败都计)。
+SMS_LOGIN_MAX_PER_HOUR = 5
+# 发码防刷:同一设备(device_id) + 同一 IP 每小时最多的发码次数。
+# 堵「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞 —— 那两道是单号维度,一机换号能绕开。
+SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5
+
 
 def _login_response(
     user, *, onboarding_completed: bool, force_onboarding: bool = False
@@ -84,15 +90,27 @@ def jverify_login(req: JverifyLoginRequest, db: DbSession) -> TokenWithUser:
     "/sms/send",
     response_model=SmsSendResponse,
     summary="发送短信验证码",
-    dependencies=[Depends(rate_limit(10, 60, "sms-send"))],  # 同 IP 每分钟≤10 次(防一 IP 刷不同号)
 )
-def sms_send(req: SmsSendRequest) -> SmsSendResponse:
+def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
     # 测试账号:不真发短信(号码非真实手机号,真发会失败/浪费),直接放行让客户端进入填码界面。
     # 真正的"免验证码"在 /sms/login 跳过校验;每日上限也在 login 处算(send 不耗额度)。
+    # (也不受下面设备发码限流约束:QA 联调要反复发码。)
     if test_account.is_test_account(req.phone):
         logger.info("test_account sms_send short-circuit (不真发)")
         return SmsSendResponse(sent=True, mock=True, cooldown_sec=0)
 
+    # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_SEND_MAX_PER_HOUR_PER_DEVICE 次发码。
+    # 补「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞(那两道是单号维度,一机换号能绕);设备维度按机器封顶,
+    # 挡短信轰炸/烧钱。放在真发(send_code)之前 → 超限直接拦下、不真发短信。与路由上 IP 维度(10次/分钟)互补。
+    enforce_rate_limit(
+        request,
+        scope="sms-send-device",
+        subject=req.device_id,
+        limit=SMS_SEND_MAX_PER_HOUR_PER_DEVICE,
+        window_sec=3600,
+        detail="操作过于频繁,请稍后再试",
+    )
+
     try:
         cooldown = send_code(req.phone)
     except SmsError as e:
@@ -109,9 +127,10 @@ def sms_send(req: SmsSendRequest) -> SmsSendResponse:
     summary="手机号+验证码登录",
     dependencies=[Depends(rate_limit(20, 60, "sms-login"))],  # 防撞库爆破(另有单码失败次数上限)
 )
-def sms_login(req: SmsLoginRequest, db: DbSession) -> TokenWithUser:
+def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWithUser:
     # 测试账号:免验证码登录 + 每日上限 + 每次都走新手引导(详见 app/core/test_account.py)。
     # 放在最前面:命中即不校验验证码;先扣当日额度,超限直接拒,挡住有人猜到号后脚本刷。
+    # 测试账号走自己的每日额度、不受下面 (设备+IP) 每小时限流约束(QA 需在一小时内反复登录联调)。
     if test_account.is_test_account(req.phone):
         if not test_account.try_consume_quota():
             raise HTTPException(status_code=429, detail="测试账号今日使用次数已达上限,请明天再试")
@@ -123,6 +142,19 @@ def sms_login(req: SmsLoginRequest, db: DbSession) -> TokenWithUser:
         # 不读/不写 onboarding_completion 表。
         return _login_response(user, onboarding_completed=False, force_onboarding=True)
 
+    # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_LOGIN_MAX_PER_HOUR 次登录尝试。放在验证码校验
+    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破。与路由上 IP 维度的 sms-login 限流(同 IP)互补。
+    # ⚠️ 按设备而非手机号 → 一台机器换不同手机号刷登录也受限(防一机狂登多号);device_id 空(老客户端)时
+    #    退化为该 IP 下所有空设备聚一桶,仍受限。
+    enforce_rate_limit(
+        request,
+        scope="sms-login-device",
+        subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR,
+        window_sec=3600,
+        detail="登录尝试过于频繁,请稍后再试",
+    )
+
     if not verify_code(req.phone, req.code):
         raise HTTPException(status_code=400, detail="invalid sms code")
 

app/api/v1/compare.py

@@ -26,6 +26,7 @@ import httpx
 from fastapi import APIRouter, HTTPException, Request, status
 
 from app.core.config import settings
+from app.core.pricebot_client import get_pricebot_client
 from app.core.pricebot_router import pick_pricebot
 
 logger = logging.getLogger("shagua.compare")
@@ -65,10 +66,10 @@ async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
     )
 
     try:
-        async with httpx.AsyncClient(timeout=timeout) as client:
-            resp = await client.post(
-                url, content=raw, headers={"Content-Type": "application/json"}
-            )
+        client = get_pricebot_client()
+        resp = await client.post(
+            url, content=raw, headers={"Content-Type": "application/json"}, timeout=timeout
+        )
     except httpx.RequestError as e:
         logger.error("[pricebot] request failed: %s", e)
         raise HTTPException(

app/api/v1/compare_record.py

@@ -21,6 +21,7 @@ from app.api.deps import CurrentUser, DbSession
 from app.db.session import SessionLocal
 from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud_compare
+from app.repositories import invite as crud_invite
 from app.services.pricebot_llm_calls import fetch_llm_calls
 from app.schemas.compare_record import (
     CompareStatsOut,
@@ -52,6 +53,18 @@ def report_record(
     # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
     # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
     background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
+    # 邀请 v2 发奖:被邀请人完成一次【成功】比价 → 给邀请人发邀请奖励金(幂等,只发一次)。
+    # best-effort:发奖异常不影响比价上报本身(rec 已 commit),只 log;邀请人补偿靠后续对账。
+    if rec.status == "success":
+        try:
+            reward = crud_invite.try_reward_on_compare(db, user.id)
+            if reward.status == "granted":
+                logger.info(
+                    "invite compare reward granted inviter=%s invitee=%s cents=%s",
+                    reward.inviter_user_id, user.id, reward.reward_cents,
+                )
+        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞上报
+            logger.warning("invite compare reward failed invitee=%s: %s", user.id, e)
     logger.info(
         "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
         user.id,

app/api/v1/coupon.py

@@ -20,6 +20,7 @@ from fastapi.concurrency import run_in_threadpool
 
 from app.api.deps import CurrentUser, DbSession
 from app.core.config import settings
+from app.core.pricebot_client import get_pricebot_client
 from app.core.pricebot_router import pick_pricebot
 from app.db.session import SessionLocal
 from app.repositories import coupon_state as coupon_repo
@@ -141,10 +142,10 @@ async def coupon_step(
     )
 
     try:
-        async with httpx.AsyncClient(timeout=timeout) as client:
-            resp = await client.post(
-                url, content=raw, headers={"Content-Type": "application/json"}
-            )
+        client = get_pricebot_client()
+        resp = await client.post(
+            url, content=raw, headers={"Content-Type": "application/json"}, timeout=timeout
+        )
     except httpx.RequestError as e:
         logger.error("[pricebot] request failed: %s", e)
         raise HTTPException(

app/api/v1/feedback.py

@@ -61,6 +61,11 @@ async def submit_feedback(
     content: str = Form(...),
     # 原型改版后客户端不再采集联系方式;保留字段以兼容旧端 + 后续可能复用,默认空串。
     contact: str = Form(default=""),
+    # 提交端环境快照(admin 反馈页展示「提交版本号」「机型OS版本」);旧端不带 → 空串 → 存 NULL。
+    app_version: str = Form(default=""),
+    device_model: str = Form(default=""),
+    rom_name: str = Form(default=""),
+    android_version: str = Form(default=""),
     images: list[UploadFile] = File(default=[]),
 ) -> FeedbackOut:
     content = content.strip()
@@ -86,6 +91,8 @@ async def submit_feedback(
 
     fb = feedback_repo.create_feedback(
         db, user_id=user.id, content=content, contact=contact, images=urls,
+        app_version=app_version.strip(), device_model=device_model.strip(),
+        rom_name=rom_name.strip(), android_version=android_version.strip(),
     )
     logger.info("feedback id=%d user_id=%d images=%d", fb.id, user.id, len(urls))
     return FeedbackOut.model_validate(fb)

app/api/v1/invite.py

@@ -38,7 +38,7 @@ logger = logging.getLogger("shagua.invite")
 router = APIRouter(prefix="/api/v1/invite", tags=["invite"])
 
 _BIND_MESSAGES = {
-    "success": "邀请绑定成功,金币已到账",
+    "success": "邀请绑定成功",
     "already_bound": "你已绑定过邀请人",
     "invalid_code": "邀请码无效",
     "self_invite": "不能填写自己的邀请码",
@@ -84,6 +84,8 @@ def _parse_device_model(ua: str) -> str:
 def my_invite(user: CurrentUser, db: DbSession) -> InviteInfoOut:
     code = invite_repo.ensure_code(db, user)
     invited, coins = invite_repo.get_stats(db, user.id)
+    reward_balance, reward_withdrawn = invite_repo.get_reward_stats(db, user.id)
+    days_left, is_fresh_round, countdown_text = invite_repo.compute_invite_countdown(user.created_at)
     sep = "&" if "?" in settings.INVITE_LANDING_URL else "?"
     share_url = f"{settings.INVITE_LANDING_URL}{sep}ref={code}"
     return InviteInfoOut(
@@ -91,6 +93,11 @@ def my_invite(user: CurrentUser, db: DbSession) -> InviteInfoOut:
         share_url=share_url,
         invited_count=invited,
         coins_earned=coins,
+        reward_balance_cents=reward_balance,
+        reward_withdrawn_cents=reward_withdrawn,
+        countdown_days_left=days_left,
+        countdown_is_fresh_round=is_fresh_round,
+        countdown_text=countdown_text,
     )
 
 
@@ -154,7 +161,7 @@ def landing_track(
     return LandingTrackOut(status="ok")
 
 
-@router.post("/bind", response_model=BindInviteOut, summary="绑定邀请人(注册即生效,双方发金币)")
+@router.post("/bind", response_model=BindInviteOut, summary="绑定邀请人(注册即生效,绑定不发奖)")
 def bind_invite(
     req: BindInviteIn, user: CurrentUser, db: DbSession, request: Request
 ) -> BindInviteOut:

app/api/v1/platform.py

@@ -63,8 +63,8 @@ def ad_config(db: DbSession) -> AdConfigPublicOut:
     return AdConfigPublicOut(
         app_id=c["app_id"],
         reward_code_id=c["reward_code_id"],
-        compare_feed_code_id=c["compare_feed_code_id"],
-        coupon_feed_code_id=c["coupon_feed_code_id"],
+        compare_draw_code_id=c["compare_draw_code_id"],
+        coupon_draw_code_id=c["coupon_draw_code_id"],
         reward_enabled=c["reward_enabled"],
         compare_ad_enabled=c["compare_ad_enabled"],
         coupon_ad_enabled=c["coupon_ad_enabled"],

app/api/v1/wallet.py

@@ -200,7 +200,8 @@ def withdraw(req: WithdrawRequest, user: CurrentUser, db: DbSession) -> Withdraw
         raise HTTPException(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail="wechat pay not configured")
     try:
         order = crud_wallet.create_withdraw(
-            db, user.id, req.amount_cents, user_name=req.user_name, out_bill_no=req.out_bill_no
+            db, user.id, req.amount_cents, source=req.source,
+            user_name=req.user_name, out_bill_no=req.out_bill_no,
         )
     except crud_wallet.InvalidWithdrawAmountError as e:
         raise HTTPException(
@@ -274,10 +275,11 @@ def withdraw_status(
 def withdraw_orders(
     user: CurrentUser,
     db: DbSession,
+    source: str | None = Query(None, description="按账户来源过滤:coin_cash / invite_cash;不传=全部"),
     limit: int = Query(20, ge=1, le=100),
     cursor: int | None = Query(None, description="上一页末条 id"),
 ) -> WithdrawOrderPage:
-    items, next_cursor = crud_wallet.list_withdraw_orders(db, user.id, limit=limit, cursor=cursor)
+    items, next_cursor = crud_wallet.list_withdraw_orders(db, user.id, source=source, limit=limit, cursor=cursor)
     return WithdrawOrderPage(
         items=[WithdrawOrderOut.model_validate(it) for it in items],
         next_cursor=next_cursor,

app/core/config.py

@@ -211,6 +211,41 @@ class Settings(BaseSettings):
         """回调开关打开且至少配了一个验签密钥,才接受发奖回调。"""
         return bool(self.PANGLE_CALLBACK_ENABLED and self.pangle_reward_secrets)
 
+    # ===== 穿山甲 GroMore 数据 API(报表收益拉取,T+1)=====
+    # ⚠️ 与上面发奖回调的 m-key 是【两套完全不同的凭证】:这三样在穿山甲后台
+    # 「接入中心 → GroMore-API → 聚合数据报告 API」文档页领取(user_id / role_id / Security Key),
+    # 仅用于按天拉 GroMore 收益报表(revenue 预估收益 + api_revenue 收益Api),不参与发奖。
+    # 该 API 只能查【GroMore 聚合代码位】的数据(=我们 useMediation 的口径),非穿山甲 SDK 数据;
+    # 且不提供用户/设备维度(官方明确),故收益只能落到 日期×代码位 汇总,不能挂到逐条事件。
+    # 子账号(role_id≠user_id)需主账号在「角色管理」授予「查看全部数据」权限,否则查不到
+    # ecpm/revenue(接口返回 118);role_id 填成与 user_id 一致 = 查主账号数据。
+    PANGLE_REPORT_USER_ID: int = 0        # 媒体账号 user_id
+    PANGLE_REPORT_ROLE_ID: int = 0        # 子账号 role_id(=user_id 时查主账号)
+    PANGLE_REPORT_SECURITY_KEY: str = ""  # 该账号的 Security Key(secure_key,≠ 发奖 m-key)
+    # GroMore 聚合 AppId(报表 site_id 维度)→ 我们的应用环境。报表按 site_id 区分两个穿山甲应用,
+    # 用它把每行归到 prod(傻瓜比价正式)/ test(测试应用)。默认值取自现网两个应用,部署时按需覆盖。
+    PANGLE_REPORT_SITE_ID_PROD: str = "5830519"   # 傻瓜比价正式应用 AppId
+    PANGLE_REPORT_SITE_ID_TEST: str = "5832303"   # 测试应用 AppId
+
+    @property
+    def pangle_report_configured(self) -> bool:
+        """三样齐全(user_id / role_id / security_key)才能拉 GroMore 报表;缺任一 → 同步脚本 no-op。"""
+        return bool(
+            self.PANGLE_REPORT_USER_ID
+            and self.PANGLE_REPORT_ROLE_ID
+            and self.PANGLE_REPORT_SECURITY_KEY
+        )
+
+    @property
+    def pangle_report_site_id_to_env(self) -> dict[str, str]:
+        """site_id(穿山甲 AppId)→ app_env(prod/test);供同步脚本把报表行归到我们的应用。留空项忽略。"""
+        out: dict[str, str] = {}
+        if self.PANGLE_REPORT_SITE_ID_PROD.strip():
+            out[self.PANGLE_REPORT_SITE_ID_PROD.strip()] = "prod"
+        if self.PANGLE_REPORT_SITE_ID_TEST.strip():
+            out[self.PANGLE_REPORT_SITE_ID_TEST.strip()] = "test"
+        return out
+
     # ===== Pricebot 上游 (领券/比价业务透传目标) =====
     # pricebot-backend 默认跑在 8000。/api/v1/coupon/step 会透传到这里的 /api/coupon/step
     PRICEBOT_BASE_URL: str = "http://localhost:8000"

app/core/pricebot_client.py

@@ -0,0 +1,35 @@
+"""透传到 pricebot 的共享 httpx.AsyncClient 单例。
+
+为什么不能每请求新建(coupon.py / compare.py 老写法 async with httpx.AsyncClient(...)):
+  ① 每次构造都重建一套 SSL 上下文(httpx.create_ssl_context 加载 certifi CA),实测
+     ~1s+/次;而 pricebot 是纯 http 透传,根本用不到 TLS → 纯浪费,且每帧重交一次。
+  ② trust_env 默认 True 会读进程 HTTP_PROXY,把 http://localhost:8000 这条本地透传整个
+     塞进本机代理(如 Clash 7897),恒定再多几秒。
+单例:启动只建一次(SSL/连接池一次性),keep-alive 复用 TCP,每帧降到个位数 ms。
+trust_env=False:对齐 integrations/meituan.py 的既有约定,不被进程代理误导,直连 pricebot。
+"""
+from __future__ import annotations
+
+import httpx
+
+_client: httpx.AsyncClient | None = None
+
+
+def get_pricebot_client() -> httpx.AsyncClient:
+    """取透传单例。lifespan 启动会预热;未预热(如测试态)懒建兜底。
+
+    超时不在此固化(coupon 30s / compare 60s 不同),由调用点 client.post(timeout=...) 传。
+    懒建无 await,asyncio 单线程下不会有并发竞态。
+    """
+    global _client
+    if _client is None:
+        _client = httpx.AsyncClient(trust_env=False)
+    return _client
+
+
+async def aclose_pricebot_client() -> None:
+    """lifespan 关停时调,优雅关连接池。"""
+    global _client
+    if _client is not None:
+        await _client.aclose()
+        _client = None

app/core/ratelimit.py

@@ -57,3 +57,29 @@ def rate_limit(limit: int, window_sec: float, scope: str):
             )
 
     return _dep
+
+
+def enforce_rate_limit(
+    request: Request,
+    scope: str,
+    subject: str,
+    limit: int,
+    window_sec: float,
+    *,
+    detail: str = "操作过于频繁,请稍后再试",
+) -> None:
+    """在路由内部手动限流,按 (subject, 客户端 IP) 计数。
+
+    用于限流 key 需要请求体字段(如手机号)、Depends 阶段还拿不到 body 时
+    —— 此时无法用 [rate_limit] 依赖,改在 handler 解析完 body 后调用本函数。
+    key = `scope:subject:client_ip`;同一 (subject, IP) 在 window_sec 内超过 limit 次 → 抛 429。
+    受 [settings.RATE_LIMIT_ENABLED] 总开关控制(与 [rate_limit] 一致)。
+    """
+    if not settings.RATE_LIMIT_ENABLED:
+        return
+    key = f"{scope}:{subject}:{_client_ip(request)}"
+    if not _hit(key, limit, window_sec):
+        raise HTTPException(
+            status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+            detail=detail,
+        )

app/core/rewards.py

@@ -113,10 +113,9 @@ PRICE_REPORT_REWARD_COINS: int = 1000
 FEEDBACK_REWARD_MAX_COINS: int = 10000
 
 
-# ===== 邀请好友(注册即生效,邀请人 + 被邀请人各发金币)=====
-# 10000 金币 = 1 元,双方各得 1 元。MVP 先用固定常量(不走 app_config)。
-INVITE_INVITER_COINS: int = 10000
-INVITE_INVITEE_COINS: int = 10000
+# ===== 邀请好友(绑定即生效,绑定只建归因关系、双方都不发钱)=====
+# v3(冰 2026-06-26):废除 v1 的"绑定双方各发金币"——被邀请人无奖励、邀请人改比价后发现金
+# (见下方 INVITE_COMPARE_REWARD_CENTS)。原 INVITE_INVITER_COINS / INVITE_INVITEE_COINS 已删。
 # "新用户闸":被邀请人必须在注册后此窗口内绑定才发奖(挡存量老用户互相填码薅羊毛)。
 # 自动绑(剪贴板)在首次注册登录后几秒内发生;留 72h 给手动填码兜底。
 INVITE_NEW_USER_WINDOW_HOURS: int = 72
@@ -127,6 +126,13 @@ INVITE_NEW_USER_WINDOW_HOURS: int = 72
 INVITE_FP_WINDOW_DAYS: int = 7
 
 
+# ===== 邀请好友 v2(好友"下载+登录+比价一次"→ 给邀请人发邀请奖励金·现金)=====
+# v2 新规则:不再注册即发金币,改"好友完成首次成功比价"才给【邀请人】发奖,发的是【现金·分】
+# 进独立的邀请奖励金账户(coin_account.invite_cash_balance_cents),与金币体系物理隔离。
+# 200 分 = 2 元。⚠️ 金额待产品定准:邀请主页=2元 / 福利入口=3.5元 不一致,定后改此处。
+INVITE_COMPARE_REWARD_CENTS: int = 200
+
+
 # ===== 看激励视频 / 信息流广告发金币 =====
 # eCPM 取自穿山甲 SDK getShowEcpm().getEcpm(),官方口径单位是【分/千次展示】(不是元!
 # csjplatform 文档原文"通过 getEcpm 获取的单位是分")。计算时先 ÷100 转成元;

app/integrations/pangle_report.py

@@ -0,0 +1,148 @@
+"""穿山甲 GroMore「聚合数据报告 API」客户端 —— 按天拉取收益报表(只读、T+1)。
+
+⚠️ 这是 **GroMore 数据拉取 API**,与发奖回调验签(integrations/pangle.py 的 m-key)是
+两套完全不同的凭证与用途。凭证在后台「接入中心 → GroMore-API → 聚合数据报告 API」领取:
+媒体账号 user_id、子账号 role_id、Security Key(secure_key)。
+
+鉴权(文档 v2.x「方法一」):
+  1. 去掉请求参数里的 `sign` 字段与值为空的字段;
+  2. 其余参数按 key 字典序升序,拼成 `k1=v1&k2=v2&...&kn=vn`;
+  3. 末尾直接拼接 security_key(无分隔符),对整串做 MD5,取 32 位小写十六进制 = sign。
+  签名有 3 分钟过期(天级用 `timestamp` 秒级时间戳;小时级才用 `current_time` 字符串)。
+
+数据口径要点(来自官方文档):
+  - 只返回【GroMore 聚合代码位】在 GroMore 内的数据(=我们 useMediation 的口径),
+    查不到穿山甲 SDK 自身的数据;
+  - **不提供分用户/设备维度**(官方 FAQ 明确拒绝),最细到 日期×应用×代码位×广告源;
+  - `revenue` = 预估收益(元,所有 ADN 都有);`api_revenue` = 收益Api(各 ADN 经 Reporting
+    回传、按实时汇率折算账号币种,更接近结算),需后台为该 ADN 配置 Reporting 才有、且不支持当天;
+  - 「今天」与「今天以前」必须分开查;天级跨度 ≤ 1 个月、不早于 12 个月。
+"""
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from app.core.config import settings
+
+logger = logging.getLogger("shagua.pangle_report")
+
+HOST = "https://www.csjplatform.com"
+# 天级收益报表(路径与文档代码示例一致;另有小时级 get_hour_report_data,本服务只用天级)。
+DAILY_PATH = "/union_media/open/api/mediation/get_daily_income_report_data"
+VERSION = "2.0"
+SIGN_TYPE = "MD5"
+PAGE_LIMIT = 5000          # 文档上限;一次尽量多取,减少翻页
+DEFAULT_TIMEOUT = 30.0
+_MAX_PAGES = 200           # 翻页安全阀(5000×200=100w 行,远超我们规模),防异常 has_next 死循环
+
+
+class PangleReportError(Exception):
+    """GroMore 报表接口调用失败(未配置 / 网络 / 业务码非 100)。"""
+
+
+def build_sign(params: Mapping[str, Any], security_key: str) -> str:
+    """按文档「方法一」生成 sign:去 sign/空值 → key 升序 → k=v& 拼接 → 末尾接 secure_key → MD5(32 位小写)。
+
+    与官方 Python/Java 示例逐字节一致(见 tests/test_pangle_report.py 的两个测试向量)。
+    """
+    items = [
+        (str(k), str(v))
+        for k, v in params.items()
+        if k != "sign" and v is not None and str(v) != ""
+    ]
+    items.sort(key=lambda kv: kv[0])
+    raw = "&".join(f"{k}={v}" for k, v in items)
+    return hashlib.md5((raw + security_key).encode("utf-8")).hexdigest()
+
+
+def fetch_daily_report(
+    *,
+    start_date: str,
+    end_date: str,
+    # ⚠️ 用 ad_unit_id(GroMore 广告位ID = 我们的 104xxx),不要用 code_id(底层各 ADN 代码位,对不上)
+    dimensions: str = "date,site_id,ad_unit_id",
+    metrics: str = "revenue,api_revenue,ecpm,imp_cnt",
+    site_ids: str | None = None,
+    code_ids: str | None = None,
+    os: str | None = None,
+    network: str | None = None,
+    time_zone: int = 8,
+    limit: int = PAGE_LIMIT,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> list[dict[str, Any]]:
+    """拉一个日期区间(北京时间,time_zone=8)的天级收益报表,自动翻页,返回 report_list 全量行。
+
+    每行是字符串字典(接口原值),形如
+    {"start_date": "2026-06-27", "site_id": "5830519", "ad_unit_id": "104142227",
+     "revenue": "1.23", "api_revenue": "1.05", "ecpm": "0.80", "imp_cnt": "1537", ...}。
+    业务码非 100 直接抛 PangleReportError(由调用方/脚本兜底,不静默吞)。
+    """
+    if not settings.pangle_report_configured:
+        raise PangleReportError(
+            "PANGLE_REPORT_USER_ID / ROLE_ID / SECURITY_KEY 未配置,无法拉取 GroMore 报表"
+        )
+
+    base_params: dict[str, Any] = {
+        "user_id": settings.PANGLE_REPORT_USER_ID,
+        "role_id": settings.PANGLE_REPORT_ROLE_ID,
+        "version": VERSION,
+        "sign_type": SIGN_TYPE,
+        "start_date": start_date,
+        "end_date": end_date,
+        "dimensions": dimensions,
+        "metrics": metrics,
+        "time_zone": time_zone,
+        "limit": limit,
+    }
+    # 可选过滤(空则不传,避免进签名串)
+    for key, val in (
+        ("site_ids", site_ids), ("code_ids", code_ids),
+        ("os", os), ("network", network),
+    ):
+        if val:
+            base_params[key] = val
+
+    rows: list[dict[str, Any]] = []
+    offset = 0
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            for _ in range(_MAX_PAGES):
+                params = dict(base_params)
+                params["offset"] = offset
+                # timestamp 每页临请求时取最新(3 分钟过期),并参与签名
+                params["timestamp"] = int(time.time())
+                params["sign"] = build_sign(params, settings.PANGLE_REPORT_SECURITY_KEY)
+
+                resp = client.get(HOST + DAILY_PATH, params=params)
+                resp.raise_for_status()
+                body = resp.json()
+
+                code = str(body.get("code"))
+                if code != "100":
+                    raise PangleReportError(
+                        f"GroMore 报表业务失败 code={code} message={body.get('message')!r} "
+                        f"(101=验签失败/102=userid无效/107=无权限/118=无收益查看权限,详见文档状态码)"
+                    )
+
+                data = body.get("data") or {}
+                page = data.get("report_list") or []
+                rows.extend(page)
+
+                # has_next=1 还有下一页;无该字段则按本页是否取满判断
+                has_next = str(data.get("has_next", "")) == "1"
+                if not page or not has_next:
+                    break
+                offset += len(page)
+    except httpx.HTTPError as e:
+        raise PangleReportError(f"GroMore 报表请求异常: {e}") from e
+
+    logger.info(
+        "GroMore 天级报表拉取完成 %s~%s dims=%s 行数=%d", start_date, end_date, dimensions, len(rows)
+    )
+    return rows

app/integrations/sms.py

@@ -14,7 +14,9 @@ worker / 多机时内存不共享 → 冷却、每日上限、校验都会失效
 防刷三层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
   1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
   2. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限(本文件)
-  3. 单 IP 频控(api 层 rate_limit 依赖)+ 极光控制台 IP 白名单/防轰炸(运维侧)
+  3. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
+     ⚠️ 原「单 IP 频控(rate_limit 依赖)」2026-06-26 按产品要求删除、改设备维度;但 device_id 客户端可伪造/轮换,
+        脚本轮换 id 能绕过本层 → 挡脚本狂发主要靠极光控制台侧(+ 可选 nginx 限流)。
 另:单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废(防爆破),验过即作废(一次性)。
 """
 from __future__ import annotations

app/main.py

@@ -15,6 +15,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 
 from app.api.v1.ad import router as ad_router
+from app.api.v1.analytics import router as analytics_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
@@ -48,6 +49,7 @@ from app.core.daily_exchange_worker import (
     stop_daily_exchange_worker,
 )
 from app.core.logging import setup_logging
+from app.core.pricebot_client import aclose_pricebot_client, get_pricebot_client
 from app.core.withdraw_reconcile_worker import (
     start_withdraw_reconcile_worker,
     stop_withdraw_reconcile_worker,
@@ -67,6 +69,7 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
         settings.APP_DEBUG,
         settings.DATABASE_URL.split("://", 1)[0],
     )
+    get_pricebot_client()  # 预热透传 client:把建 SSL 上下文的一次性成本付在启动,首个领券请求即热
     reconcile_task = start_withdraw_reconcile_worker()
     heartbeat_task = start_heartbeat_monitor()
     daily_exchange_task = start_daily_exchange_worker()
@@ -76,6 +79,7 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
         await stop_heartbeat_monitor(heartbeat_task)
         await stop_withdraw_reconcile_worker(reconcile_task)
         await stop_daily_exchange_worker(daily_exchange_task)
+        await aclose_pricebot_client()
         logger.info("shutting down")
 
 
@@ -105,6 +109,7 @@ def health() -> dict[str, str]:
 app.include_router(auth_router)
 app.include_router(user_router)
 app.include_router(feedback_router)
+app.include_router(analytics_router)
 app.include_router(invite_router)
 app.include_router(coupon_router)
 app.include_router(device_router)

app/models/__init__.py

@@ -1,9 +1,11 @@
 """所有 ORM model 必须在这里 import 一次,Alembic / metadata 才能扫到。"""
 from app.models.ad_ecpm import AdEcpmRecord  # noqa: F401
 from app.models.ad_feed_reward import AdFeedRewardRecord  # noqa: F401
+from app.models.ad_pangle_revenue import AdPangleDailyRevenue  # noqa: F401
 from app.models.ad_reward import AdRewardRecord  # noqa: F401
 from app.models.ad_watch_log import AdWatchLog  # noqa: F401
 from app.models.admin import AdminAuditLog, AdminUser  # noqa: F401
+from app.models.analytics_event import AnalyticsEvent  # noqa: F401
 from app.models.app_config import AppConfig  # noqa: F401
 from app.models.comparison import ComparisonRecord  # noqa: F401
 from app.models.cps_activity import CpsActivity  # noqa: F401
@@ -37,5 +39,6 @@ from app.models.wallet import (  # noqa: F401
     CashTransaction,
     CoinAccount,
     CoinTransaction,
+    InviteCashTransaction,
     WithdrawOrder,
 )

app/models/ad_ecpm.py

@@ -29,6 +29,9 @@ class AdEcpmRecord(Base):
     )
     # 广告类型:reward_video(激励视频) / draw(Draw 信息流) 等;不强行统一代码位,各类型各自上报
     ad_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    # 点位场景:comparison(比价) / coupon(领券) / welfare(福利),供收益报表区分比价/领券 Draw 收益;
+    # 仅信息流/Draw 上报(比价与领券共用同一代码位,只能客户端各调用点显式打标),激励视频为 NULL。
+    feed_scene: Mapped[str | None] = mapped_column(String(16), nullable=True)
     # 客户端生成的一次广告会话 id;激励视频 S2S 回调 extra 会透传同值
     ad_session_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
     # 实际投放的 ADN(穿山甲 getShowEcpm().getSdkName(),如 pangle / gdt)

app/models/ad_feed_reward.py

@@ -30,6 +30,9 @@ class AdFeedRewardRecord(Base):
     ecpm_raw: Mapped[str] = mapped_column(String(32), nullable=False)
     adn: Mapped[str | None] = mapped_column(String(32), nullable=True)
     slot_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    # 广告类型:feed(信息流) / draw(Draw 信息流)。比价与领券共用同一 Draw 代码位,靠 feed_scene
+    # 区分收益;ad_type 区分广告形态。旧数据(未升级客户端)为 NULL,一律视为 feed,保持向后兼容。
+    ad_type: Mapped[str | None] = mapped_column(String(16), nullable=True, default="feed")
     # 点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页)。比价与领券共用同一信息流
     # 代码位,slot_id/our_code_id 分不出,只能客户端各调用点显式打标;NULL=历史/未升级客户端=未分类。
     feed_scene: Mapped[str | None] = mapped_column(String(16), nullable=True)

app/models/ad_pangle_revenue.py

@@ -0,0 +1,73 @@
+"""穿山甲 GroMore 天级收益报表(后台结算口径,定时拉取入库)。
+
+每行 = GroMore 数据 API 返回的一条「日期 × 应用 × 代码位」聚合收益(`integrations/pangle_report`
++ `scripts/sync_pangle_revenue` 落库)。**权威/预估收益的来源**,与 `ad_ecpm_record`(客户端自报
+eCPM 折算的预估)互为对照:
+
+- `revenue_yuan` ← 接口 `revenue`(预估收益,元;排序价×展示/1000,所有 ADN 都有);
+- `api_revenue_yuan` ← 接口 `api_revenue`(收益Api,元;各 ADN 经 Reporting 回传、更接近结算;
+  未配置该 ADN 的 Reporting 或查当天时为空)。
+
+⚠️ 穿山甲不提供分用户/设备维度,故本表最细只到 日期×应用×代码位,**无法挂到逐条广告事件**;
+广告收益报表里只用于汇总/趋势级的「穿山甲后台收益」,不改逐条行的客户端预估。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import (
+    DateTime,
+    Float,
+    Integer,
+    String,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AdPangleDailyRevenue(Base):
+    __tablename__ = "ad_pangle_daily_revenue"
+    __table_args__ = (
+        # 一行 = (日期, 应用, 代码位, 广告源);adn 用 "" 表示「未分广告源、该代码位汇总」,
+        # 避免 NULL 在唯一约束里被视为各不相同导致 upsert 重复(SQLite/PG 行为一致)。
+        UniqueConstraint(
+            "report_date", "app_env", "our_code_id", "adn",
+            name="uq_ad_pangle_daily",
+        ),
+    )
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 北京时间日期串 'YYYY-MM-DD'(拉取时 time_zone=8),与 ad_ecpm_record.report_date 同口径,可直接 join。
+    report_date: Mapped[str] = mapped_column(String(10), index=True, nullable=False)
+    # 我们的应用环境:prod(傻瓜比价正式)/ test(测试);由 site_id 经 settings 映射而来。
+    app_env: Mapped[str] = mapped_column(String(16), nullable=False)
+    # 原始 GroMore AppId(site_id),留痕便于排查映射。
+    site_id: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 广告位 ID(= 接口 ad_unit_id = 我们客户端配的 104xxx = ad_ecpm_record.our_code_id),join key。
+    # ⚠️ 不是接口的 code_id —— 那是底层各 ADN 的代码位(如 983674557),对不上我们的口径。
+    our_code_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    # 广告源(接口 network 数字→名,如 pangle/gdt);"" = 未分广告源的代码位汇总行(当前默认口径)。
+    adn: Mapped[str] = mapped_column(String(16), nullable=False, default="")
+    # 预估收益(元)← 接口 revenue。
+    revenue_yuan: Mapped[float] = mapped_column(Float, nullable=False, default=0.0)
+    # 收益Api(元)← 接口 api_revenue;未配 Reporting / 当天 等情况接口不返回 → NULL。
+    api_revenue_yuan: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # 预估 eCPM 原值(接口 ecpm,单位元/千次,**与客户端 getEcpm 的「分」不同**),参考用原样存。
+    ecpm: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 展示次数 ← 接口 imp_cnt。
+    impressions: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # 货币类型(接口 currency,正常为 cny)。
+    currency: Mapped[str] = mapped_column(String(8), nullable=False, default="cny")
+    # 最近一次同步写入时间(同一行可被多次回补覆盖;T+1 数据穿山甲会订正)。
+    synced_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return (
+            f"<AdPangleDailyRevenue {self.report_date} {self.app_env} "
+            f"code={self.our_code_id} revenue={self.revenue_yuan}>"
+        )

app/models/analytics_event.py

@@ -0,0 +1,60 @@
+"""新手引导(及后续)埋点事件表。
+
+每行 = 客户端上报的一条行为埋点,按「Who / When / Where / What / How」五维组织:
+- What :event(事件名,如 video_play)+ props(事件专属属性,JSON)
+- Who  :device_id(硬件级设备标识)+ user_id(登录后才有,可空)
+- When :client_ts(端事件时间 epoch ms)+ session_id(本次引导会话)+ sent_at(端上报时间)
+         + created_at(服务端接收时间 = server_at)
+- Where:page(引导步/页面)+ client_ip(服务端从 X-Forwarded-For 取)
+- How  :oem / os / model / app_ver / network / channel(设备与环境)
+
+append-only,不更新;客户端批量上报(见 app/api/v1/analytics.py),admin 同库直接查(见
+app/admin/routers/event_logs.py)。未登录态也允许上报(user_id 为空),故 user_id 不设外键、只索引。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import JSON, BigInteger, DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AnalyticsEvent(Base):
+    __tablename__ = "analytics_event"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+
+    # ---- What:做了什么 ----
+    event: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    props: Mapped[dict | None] = mapped_column(JSON, nullable=True)
+
+    # ---- Who:谁 ----
+    device_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    user_id: Mapped[int | None] = mapped_column(Integer, index=True, nullable=True)
+
+    # ---- When:何时 ----
+    session_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
+    client_ts: Mapped[int] = mapped_column(BigInteger, nullable=False)  # 端事件时间 epoch ms
+    sent_at: Mapped[int | None] = mapped_column(BigInteger, nullable=True)  # 端上报时间 epoch ms
+
+    # ---- Where:何地 ----
+    page: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    client_ip: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    # ---- How:用什么环境 ----
+    oem: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    os: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    model: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    app_ver: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    network: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    channel: Mapped[str | None] = mapped_column(String(32), nullable=True)
+
+    # 服务端接收时间(= When.server_at);客户端时间不可信,以此为权威落库时刻。
+    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"<AnalyticsEvent id={self.id} event={self.event} device={self.device_id}>"

app/models/device.py

@@ -51,6 +51,11 @@ class DeviceLiveness(Base):
     ever_protected: Mapped[bool] = mapped_column(
         Boolean, nullable=False, default=False
     )
+    # 首次开无障碍(首次收到 accessibility_enabled 心跳)的时刻;ever_protected 第一次翻 true 时记一次,
+    # 后续心跳不覆盖。老设备(迁移前已 protected)无此值 → NULL。
+    first_protected_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
     # 最近一次 service 心跳时间(存活证明);超时即视为保护掉线
     last_heartbeat_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), index=True, nullable=True

app/models/feedback.py

@@ -25,6 +25,11 @@ class Feedback(Base):
     contact: Mapped[str] = mapped_column(String(128), nullable=False)
     # 截图 URL 列表(相对路径,如 ["/media/feedback/u1_ab12.jpg"]);无图为 None
     images: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
+    # 提交时的端环境快照(admin 排查用;客户端改版带上后的新反馈才有,历史数据为 NULL)
+    app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)  # 我们 app versionName
+    device_model: Mapped[str | None] = mapped_column(String(64), nullable=True)  # Build.MODEL
+    rom_name: Mapped[str | None] = mapped_column(String(32), nullable=True)  # OemDetector os:ColorOS/MIUI/...
+    android_version: Mapped[str | None] = mapped_column(String(16), nullable=True)  # Build.VERSION.RELEASE
     # pending(审核中) / adopted(已采纳) / rejected(未采纳)
     status: Mapped[str] = mapped_column(String(16), nullable=False, default="pending", index=True)
     reject_reason: Mapped[str | None] = mapped_column(String(256), nullable=True)

app/models/invite.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import DateTime, ForeignKey, Integer, String, func
+from sqlalchemy import Boolean, DateTime, ForeignKey, Integer, String, false, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -35,6 +35,20 @@ class InviteRelation(Base):
     inviter_coin: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     invitee_coin: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
 
+    # ===== v2 比价发奖追踪(好友"下载+登录+比价一次"→ 给邀请人发邀请奖励金)=====
+    # 是否已因"好友完成比价"发过奖:好友比价多次只发一次(防重复发,与 invitee 唯一约束双保险)
+    compare_reward_granted: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default=false()
+    )
+    # 实发给邀请人的邀请奖励金(分);未发为 0
+    compare_reward_cents: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0"
+    )
+    # 发奖时间(未发为 None)
+    compare_rewarded_at: Mapped[datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
     )

app/models/wallet.py

@@ -25,6 +25,11 @@ class CoinAccount(Base):
     )
     coin_balance: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
     cash_balance_cents: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    # 邀请奖励金余额(分)——与金币兑换来的 cash_balance_cents **物理隔离**(产品红线:
+    # 邀请奖励金 ≠ 看广告/金币现金,两本账不可累加)。好友比价发奖入账、提现出账走它。
+    invite_cash_balance_cents: Mapped[int] = mapped_column(
+        Integer, nullable=False, default=0, server_default="0"
+    )
     # 累计赚取的金币(只增不减),用于"历史总收益"类展示
     total_coin_earned: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
 
@@ -108,6 +113,11 @@ class WithdrawOrder(Base):
     # 商户单号(我们生成,微信查单的 out_bill_no),唯一
     out_bill_no: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
     amount_cents: Mapped[int] = mapped_column(Integer, nullable=False)
+    # 这笔提现扣的是哪个账户:coin_cash(金币兑换的现金) / invite_cash(邀请奖励金)。
+    # 退款时据此退回**对应**账户,两本账不串。旧单默认 coin_cash。
+    source: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="coin_cash", server_default="coin_cash"
+    )
     # 提现实名(微信达额转账要求):审核后异步打款时要用,发起提现时存下,可空
     user_name: Mapped[str | None] = mapped_column(String(64), nullable=True)
     # 归一化状态:reviewing(待审核) / pending(打款在途) / success / failed(打款失败已退) / rejected(审核拒绝已退)
@@ -200,3 +210,41 @@ class CashTransaction(Base):
 
     def __repr__(self) -> str:  # pragma: no cover
         return f"<CashTransaction id={self.id} user_id={self.user_id} cents={self.amount_cents}>"
+
+
+class InviteCashTransaction(Base):
+    """邀请奖励金流水(单位:分)。与 cash_transaction(金币兑换现金)**物理隔离**——
+    产品红线:邀请奖励金 ≠ 看广告/金币现金,两本账不可累加、各自提现。
+    入账=好友比价发奖(invite_reward),出账=提现(invite_withdraw)/退款(invite_withdraw_refund)。
+    结构与 cash_transaction 同构,balance_after_cents 记的是 coin_account.invite_cash_balance_cents。"""
+
+    __tablename__ = "invite_cash_transaction"
+    __table_args__ = (
+        # 提现退款幂等:一个提现单只退一次(同 cash_transaction 的 withdraw_refund 去重)
+        Index(
+            "ux_invite_cash_txn_refund_ref",
+            "ref_id",
+            unique=True,
+            sqlite_where=text("biz_type = 'invite_withdraw_refund' AND ref_id IS NOT NULL"),
+            postgresql_where=text("biz_type = 'invite_withdraw_refund' AND ref_id IS NOT NULL"),
+        ),
+    )
+
+    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
+    )
+    # 正数=入账(发奖),负数=出账(提现)
+    amount_cents: Mapped[int] = mapped_column(Integer, nullable=False)
+    balance_after_cents: Mapped[int] = mapped_column(Integer, nullable=False)
+    # 业务类型:invite_reward / invite_withdraw / invite_withdraw_refund
+    biz_type: Mapped[str] = mapped_column(String(32), nullable=False)
+    ref_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+    remark: Mapped[str | None] = mapped_column(String(128), 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"<InviteCashTransaction id={self.id} user_id={self.user_id} cents={self.amount_cents}>"

app/repositories/ad_ecpm.py

@@ -23,6 +23,7 @@ def create_ecpm_record(
     ad_session_id: str | None = None,
     adn: str | None = None,
     slot_id: str | None = None,
+    feed_scene: str | None = None,
     app_env: str | None = None,
     our_code_id: str | None = None,
 ) -> AdEcpmRecord:
@@ -41,6 +42,7 @@ def create_ecpm_record(
         ad_session_id=ad_session_id,
         adn=adn,
         slot_id=slot_id,
+        feed_scene=feed_scene,
         app_env=app_env,
         our_code_id=our_code_id,
         ecpm_raw=ecpm_raw,
@@ -51,11 +53,16 @@ def create_ecpm_record(
         db.commit()
     except IntegrityError:
         db.rollback()
-        if ad_session_id:
-            existing = find_by_session(db, user_id=user_id, ad_session_id=ad_session_id)
-            if existing is not None:
-                return existing
-        raise
+        # 撞唯一约束 uq_ad_ecpm_record_session(全局按 ad_session_id、不含 user_id):并发同会话重复上报,
+        # 或同一 ad_session_id 已被先到的上报占用。本接口 fire-and-forget、best-effort —— 丢一条不影响业务
+        # (穿山甲后台才是结算权威),绝不向客户端抛 500。兜底查找须与唯一约束**同口径**(只按 ad_session_id、
+        # 不带 user_id):否则不同 user 上报了同一 ad_session_id 时,带 user_id 的查找会漏掉那条别人的记录 →
+        # 旧逻辑在此 raise 成 500(本应静默吞掉)。
+        existing = _find_by_session_global(db, ad_session_id)
+        if existing is not None:
+            return existing
+        # 极少:rollback 后既存记录又查不到(并发删除 / 竞态)。吞掉、返回未入库的内存对象(调用方不读返回值)。
+        return rec
     db.refresh(rec)
     return rec
 
@@ -74,6 +81,20 @@ def find_by_session(
     ).scalar_one_or_none()
 
 
+def _find_by_session_global(db: Session, ad_session_id: str | None) -> AdEcpmRecord | None:
+    """按 ad_session_id **全局**查找(与唯一约束 uq_ad_ecpm_record_session 同口径,不含 user_id)。
+
+    仅 create_ecpm_record 撞约束后兜底用:此时撞的是全局会话约束,既存记录可能属于**另一个 user**,
+    带 user_id 的 find_by_session 会漏掉它、导致误判「查无 → raise 500」。其它业务查「某 user 的某次
+    展示 eCPM」仍用 find_by_session(带 user_id,语义更准),不走这里。
+    """
+    if not ad_session_id:
+        return None
+    return db.execute(
+        select(AdEcpmRecord).where(AdEcpmRecord.ad_session_id == ad_session_id)
+    ).scalar_one_or_none()
+
+
 def count_today(db: Session, user_id: int) -> int:
     """该用户今日(北京时间)上报的 eCPM 条数,排查/对账辅助用。"""
     return db.execute(

app/repositories/ad_feed_reward.py

@@ -14,7 +14,6 @@ from app.core.rewards import cn_today
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.repositories import wallet as crud_wallet
 
-
 FEED_REWARD_UNIT_SECONDS = 10
 # 单个 feed 事件的时长上限(秒):一期 duration_seconds 由客户端上报,伪造超长时长会刷份数
 # (每 10 秒 1 份)。真实单条信息流视频远小于此;取 120s=12 份封顶,挡刷量、不影响正规单。
@@ -65,6 +64,7 @@ def grant_feed_reward(
     client_event_id: str,
     ecpm: str,
     duration_seconds: int,
+    ad_type: str = "feed",
     ad_session_id: str | None = None,
     adn: str | None = None,
     slot_id: str | None = None,
@@ -73,17 +73,22 @@ def grant_feed_reward(
     app_env: str | None = None,
     our_code_id: str | None = None,
     aborted: bool = False,
+    display_coin: int = 0,
 ) -> AdFeedRewardRecord:
     """**每条**信息流广告(客户端每条各上报一次)结算奖励。client_event_id 幂等,同号重试不重复发。
 
-    发奖规则:**一条广告 = 一个单次公式值**(rewards.calculate_ad_reward_coin),因子2(LT)按账号累计
-    **条**数递进;看满一份时长(unit_count>=1, 即 ≥10 秒)才发,**不逐份累加**。
+    发奖规则(所见即所得, 2026-06-27 用户拍板「显示多少给多少」):优先**直接发客户端小球显示的金币
+    display_coin**;防刷钳到本条「1 份满额」(eCPM 已钳 AD_ECPM_MAX_FEN, 因子2 按账号累计已发条数取档),
+    合法显示(实际因子2 × 进度 p ≤ 1 份)不被砍, 只挡伪造天价值。旧客户端不传 display_coin 时退回
+    「看满 10 秒发整份」(兼容不断币)。因子2(LT)由**客户端**按 granted 行 COUNT(拉自 /feed-reward/units)
+    算进 display_coin, 后端只记 granted 行让该计数自增, 不再服务端重算份值。
     - aborted=True(用户中途 ✕ 关闭这条):本条不发,记 status='closed_early'。
-    - 时长不足 10 秒(unit_count==0):记 status='too_short' 不发。
+    - display_coin 为 0 且时长不足一份:记 status='too_short' 不发(不计 LT / 当日上限)。
     - 命中当日条数上限:记 status='capped' 不发。
-    duration_seconds 是**这一条**的观看秒数。服务端两道硬闸防刷:时长钳到 FEED_MAX_DURATION_SECONDS、
-    eCPM 在 calculate_ad_reward_coin 内钳到 AD_ECPM_MAX_FEN;叠加每日 get_ad_daily_limit 条数上限。
+    duration_seconds 落库留痕(unit_count 字段), 旧端兼容路径据它判是否满 1 份。
     feed_scene:点位场景(comparison/coupon/welfare),仅归类落库,不参与计算。
+    ad_type:广告形态(feed 信息流 / draw Draw 信息流),仅归类落库;**每日上限与因子2(LT)仍按本表
+    全表 unit 累计(feed+draw 共享同一发奖池/上限),不按 ad_type 拆分**。
     """
     existing = _find_by_event(db, client_event_id)
     if existing is not None:
@@ -106,6 +111,7 @@ def grant_feed_reward(
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            ad_type=ad_type,
             feed_scene=feed_scene,
             trace_id=trace_id,
             app_env=app_env,
@@ -126,6 +132,7 @@ def grant_feed_reward(
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            ad_type=ad_type,
             feed_scene=feed_scene,
             trace_id=trace_id,
             app_env=app_env,
@@ -135,18 +142,31 @@ def grant_feed_reward(
         )
         return _commit_record(db, rec, client_event_id)
 
-    # 整场总时长不足 10 秒,凑不满一份 → 不发,记 too_short 留痕。
-    if unit_count == 0:
+    # 所见即所得(用户 2026-06-27「显示多少给多少」): 优先发**客户端小球显示**的金币 display_coin,
+    # 钳到本条「1 份满额」防刷(eCPM 已钳 AD_ECPM_MAX_FEN; 合法显示=因子2×p≤1份, 不会被砍)。
+    # 因子2(LT)按账号累计已发条数(granted 行 COUNT), 第 existing_ads+1 条。
+    existing_ads = granted_unit_total(db, user_id)
+    unit_cap = rewards.calculate_ad_reward_coin(ecpm, existing_ads + 1)
+    if display_coin > 0:
+        coin = min(display_coin, unit_cap)              # 新端: 所见即所得(直接发小球显示金币)
+    elif unit_count >= 1:
+        coin = unit_cap                                 # 旧端没传 display_coin: 退回「看满 1 份发整份」(兼容)
+    else:
+        coin = 0
+
+    # 显示金币为 0 且没满一份 → 不发, 记 too_short 留痕(不写 granted 行 → 不计 LT / 当日上限)。
+    if coin <= 0:
         rec = AdFeedRewardRecord(
             client_event_id=client_event_id,
             user_id=user_id,
             reward_date=today,
             duration_seconds=safe_duration,
-            unit_count=0,
+            unit_count=unit_count,
             ad_session_id=ad_session_id,
             ecpm_raw=ecpm,
             adn=adn,
             slot_id=slot_id,
+            ad_type=ad_type,
             feed_scene=feed_scene,
             trace_id=trace_id,
             app_env=app_env,
@@ -156,15 +176,11 @@ def grant_feed_reward(
         )
         return _commit_record(db, rec, client_event_id)
 
-    # 一条广告 = 一个「单次公式值」(因子2 按账号累计**条**数, 即第 existing_ads+1 条);看满一份(unit_count>=1)即发,不逐份累加。
-    existing_ads = granted_unit_total(db, user_id)
-    coin = rewards.calculate_ad_reward_coin(ecpm, existing_ads + 1)
-    if coin > 0:
-        crud_wallet.grant_coins(
-            db, user_id, coin,
-            biz_type="feed_ad_reward", ref_id=client_event_id,
-            remark="信息流广告奖励",
-        )
+    crud_wallet.grant_coins(
+        db, user_id, coin,
+        biz_type="feed_ad_reward", ref_id=client_event_id,
+        remark="信息流广告奖励",
+    )
     rec = AdFeedRewardRecord(
         client_event_id=client_event_id,
         user_id=user_id,

app/repositories/ad_pangle_revenue.py

@@ -0,0 +1,109 @@
+"""穿山甲 GroMore 天级收益 读写(`ad_pangle_daily_revenue` 表)。
+
+`scripts/sync_pangle_revenue` 拉数后调 `upsert_daily_rows` 落库(同一(日期×应用×代码位×广告源)
+幂等覆盖,T+1 订正可重跑);admin 广告收益报表调 `aggregate_by_date` 取「穿山甲后台收益」做
+汇总/趋势级展示。穿山甲无用户维度,故这里不涉及 user_id。
+"""
+from __future__ import annotations
+
+from typing import Any, TypedDict
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.ad_pangle_revenue import AdPangleDailyRevenue
+
+# upsert 时可被覆盖更新的列(唯一键之外的业务列)。
+_UPDATABLE = ("site_id", "revenue_yuan", "api_revenue_yuan", "ecpm", "impressions", "currency")
+
+
+class PangleDateAgg(TypedDict):
+    date: str
+    revenue_yuan: float
+    api_revenue_yuan: float | None
+    impressions: int
+
+
+def upsert_daily_rows(db: Session, rows: list[dict[str, Any]]) -> dict[str, int]:
+    """按唯一键 (report_date, app_env, our_code_id, adn) 逐行 upsert。
+
+    每个 row 须含:report_date, app_env, our_code_id;可选 adn(默认"")、site_id、
+    revenue_yuan、api_revenue_yuan、ecpm、impressions、currency。返回 {inserted, updated}。
+    规模很小(代码位数×天数),逐行 select-then-write 足够,且 SQLite/PG 通用。
+    """
+    inserted = updated = 0
+    for row in rows:
+        adn = row.get("adn") or ""
+        existing = db.execute(
+            select(AdPangleDailyRevenue).where(
+                AdPangleDailyRevenue.report_date == row["report_date"],
+                AdPangleDailyRevenue.app_env == row["app_env"],
+                AdPangleDailyRevenue.our_code_id == row["our_code_id"],
+                AdPangleDailyRevenue.adn == adn,
+            )
+        ).scalar_one_or_none()
+
+        if existing is None:
+            db.add(AdPangleDailyRevenue(
+                report_date=row["report_date"],
+                app_env=row["app_env"],
+                site_id=row.get("site_id"),
+                our_code_id=row["our_code_id"],
+                adn=adn,
+                revenue_yuan=float(row.get("revenue_yuan") or 0.0),
+                api_revenue_yuan=row.get("api_revenue_yuan"),
+                ecpm=row.get("ecpm"),
+                impressions=int(row.get("impressions") or 0),
+                currency=row.get("currency") or "cny",
+            ))
+            inserted += 1
+        else:
+            for col in _UPDATABLE:
+                if col in row:
+                    setattr(existing, col, row[col])
+            updated += 1
+    db.commit()
+    return {"inserted": inserted, "updated": updated}
+
+
+def aggregate_by_date(
+    db: Session,
+    *,
+    date_from: str,
+    date_to: str,
+    app_env: str | None = None,
+    our_code_id: str | None = None,
+) -> list[PangleDateAgg]:
+    """按日期汇总穿山甲收益(闭区间,北京时间),供报表趋势 + 合计。
+
+    revenue_yuan = Σrevenue;api_revenue_yuan = Σapi_revenue(SQL SUM 忽略 NULL,
+    全为空则返回 None,前端显示「-」)。可选按应用 / 代码位过滤。返回按日期升序。
+    """
+    stmt = (
+        select(
+            AdPangleDailyRevenue.report_date,
+            func.sum(AdPangleDailyRevenue.revenue_yuan),
+            func.sum(AdPangleDailyRevenue.api_revenue_yuan),
+            func.sum(AdPangleDailyRevenue.impressions),
+        )
+        .where(
+            AdPangleDailyRevenue.report_date >= date_from,
+            AdPangleDailyRevenue.report_date <= date_to,
+        )
+        .group_by(AdPangleDailyRevenue.report_date)
+        .order_by(AdPangleDailyRevenue.report_date)
+    )
+    if app_env is not None:
+        stmt = stmt.where(AdPangleDailyRevenue.app_env == app_env)
+    if our_code_id is not None:
+        stmt = stmt.where(AdPangleDailyRevenue.our_code_id == our_code_id)
+
+    out: list[PangleDateAgg] = []
+    for report_date, rev, api_rev, imp in db.execute(stmt).all():
+        out.append(PangleDateAgg(
+            date=report_date,
+            revenue_yuan=round(float(rev or 0.0), 6),
+            api_revenue_yuan=(round(float(api_rev), 6) if api_rev is not None else None),
+            impressions=int(imp or 0),
+        ))
+    return out

app/repositories/analytics.py

@@ -0,0 +1,34 @@
+"""埋点事件批量落库。append-only,一次 commit 提交整批。"""
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from app.models.analytics_event import AnalyticsEvent
+from app.schemas.analytics import AnalyticsBatchIn
+
+
+def record_batch(db: Session, batch: AnalyticsBatchIn, *, client_ip: str | None) -> int:
+    """把一批上报事件展开成多行落库(公共维度复制到每行),返回写入条数。"""
+    rows = [
+        AnalyticsEvent(
+            event=e.event,
+            props=e.props or None,
+            device_id=batch.device_id,
+            user_id=batch.user_id,
+            session_id=e.session_id,
+            client_ts=e.client_ts,
+            sent_at=batch.sent_at,
+            page=e.page,
+            client_ip=client_ip or None,
+            oem=batch.oem,
+            os=batch.os,
+            model=batch.model,
+            app_ver=batch.app_ver,
+            network=e.network,
+            channel=batch.channel,
+        )
+        for e in batch.events
+    ]
+    db.add_all(rows)
+    db.commit()
+    return len(rows)

app/repositories/app_config.py

@@ -101,10 +101,10 @@ AD_CONFIG_KEY = "ad_config"
 _AD_CONFIG_DEFAULTS: dict[str, Any] = {
     "app_id": "5830519",                  # 穿山甲应用ID(正式)
     "reward_code_id": "104099389",        # 福利页激励视频位
-    # ⚠️ 2026-06-21 真机核对穿山甲后台:5830519 名下信息流真实位是 104142227「信息流 1」;
-    # 旧值 104090333 不在该应用名下(请求会报 44406/配置 null、出不了广告)。客户端接入下发后以本值为准。
-    "compare_feed_code_id": "104142227",  # 比价信息流位
-    "coupon_feed_code_id": "104142227",   # 领券信息流位(初始同比价,运营可拆)
+    # 比价与领券共用同一穿山甲 Draw 代码位(默认 104098712 = 后台「Draw信息流」位),靠 feed_scene
+    # (comparison/coupon)区分收益;运营可在后台把两者拆成不同代码位。字段从旧 *_feed_code_id 改名为 *_draw_code_id。
+    "compare_draw_code_id": "104098712",  # 比价 Draw 代码位(104098712 = Draw 信息流位)
+    "coupon_draw_code_id": "104098712",   # 领券 Draw 代码位(初始同比价,运营可拆)
     "reward_mkey": "",                    # 激励位 GroMore 验签密钥(空则回退 .env PANGLE_REWARD_SECRET*)
     "reward_enabled": True,               # 福利激励视频开关
     "compare_ad_enabled": True,           # 比价广告开关

app/repositories/device.py

@@ -72,6 +72,8 @@ def touch_heartbeat(
     device.last_report_protection_on = accessibility_enabled
 
     if accessibility_enabled:
+        if not device.ever_protected:
+            device.first_protected_at = now  # 首次开无障碍记一次,后续心跳不覆盖
         device.last_heartbeat_at = now
         device.ever_protected = True
         device.liveness_state = "alive"

app/repositories/feedback.py

@@ -17,12 +17,20 @@ def create_feedback(
     content: str,
     contact: str,
     images: list[str] | None,
+    app_version: str | None = None,
+    device_model: str | None = None,
+    rom_name: str | None = None,
+    android_version: str | None = None,
 ) -> Feedback:
     fb = Feedback(
         user_id=user_id,
         content=content,
         contact=contact,
         images=images or None,
+        app_version=app_version or None,
+        device_model=device_model or None,
+        rom_name=rom_name or None,
+        android_version=android_version or None,
         status="pending",
         created_at=datetime.now(CN_TZ).replace(tzinfo=None),
     )

app/repositories/invite.py

@@ -1,13 +1,14 @@
-"""好友邀请 CRUD(注册即生效,邀请人 + 被邀请人各发金币)。
+"""好友邀请 CRUD(注册即生效,绑定只建归因关系、双方都不发钱)。
+
+发奖规则(v3,冰 2026-06-26 拍板):
+  - 绑定时双方都不发钱(被邀请人无奖励、邀请人不发金币)。
+  - 邀请人的钱由 try_reward_on_compare 在好友"成功比价一次"后发 2 元邀请奖励金(防刷)。
+  - v1 的"绑定双方各发金币"已废;invite_relation 的 inviter_coin/invitee_coin 列保留恒 0(待清)。
 
 防重复发奖三道(仿 ad_reward / 提现的资金安全思路):
   1. invitee_user_id 唯一 → 一个被邀请人只能被绑定一次(幂等键)。
   2. 自邀屏蔽 → inviter == invitee 直接拒。
   3. 现成的手机号唯一(每个被邀请人 = 一个真实手机号账号)= 天然限制刷量规模。
-
-发金币复用 wallet.grant_coins(grant 只 flush 不 commit),与建关系记录在**同一事务**
-commit,保证"建关系 + 双方加金币"原子。奖励额 = rewards.INVITE_INVITER_COINS /
-INVITE_INVITEE_COINS。
 """
 from __future__ import annotations
 
@@ -34,6 +35,30 @@ def _gen_code() -> str:
     return "".join(secrets.choice(_CODE_ALPHABET) for _ in range(_CODE_LEN))
 
 
+# ===== v2 邀请倒计时(7 天 1 轮,锚点=注册日,自然日差,东八区)=====
+# 中国不用夏令时,固定 +8 偏移即可(不依赖 tzdata,Windows 本地联调也稳)。
+_CST = timezone(timedelta(hours=8))
+
+
+def compute_invite_countdown(register_at: datetime) -> tuple[int, bool, str]:
+    """按 7 天 1 轮算邀请页倒计时。
+
+    锚点 = 用户注册日(user.created_at),按东八区自然日差算
+    (跨自然日才减、同日多次登录不减,天然满足)。返回:
+      (本轮剩余天数 1..7, 是否刚进入新一轮[非首轮第1天], 展示文案)。
+    """
+    reg = register_at if register_at.tzinfo else register_at.replace(tzinfo=timezone.utc)
+    days_since = max(0, (datetime.now(_CST).date() - reg.astimezone(_CST).date()).days)
+    day_in_cycle = days_since % 7                            # 0..6(本轮第几天,0-based)
+    days_left = 7 - day_in_cycle                             # 7..1(第1天=7、第7天=1)
+    is_fresh_round = days_since >= 7 and day_in_cycle == 0   # 非首轮的第1天
+    if is_fresh_round:
+        text = "恭喜您进入新一轮邀请！\n距离本轮结束还有7天"
+    else:
+        text = f"距本轮结束还有{days_left}天"
+    return days_left, is_fresh_round, text
+
+
 def ensure_code(db: Session, user: User) -> str:
     """保证 user 有邀请码(懒生成),返回它。唯一约束碰撞则换码重试。
 
@@ -90,15 +115,17 @@ def _is_new_user(user: User) -> bool:
 class BindResult:
     status: str                          # success / already_bound / invalid_code / self_invite / not_eligible
     relation: InviteRelation | None = None
-    invitee_coin: int = 0                # 本次给被邀请人发的金币(success 时 >0)
+    invitee_coin: int = 0                # v3 起恒 0(绑定不再发金币);保留字段兼容响应
 
 
 def bind(
     db: Session, *, invitee: User, invite_code: str, channel: str = "clipboard"
 ) -> BindResult:
-    """把 invitee 绑定到 invite_code 对应的邀请人,注册即生效 + 双方发金币。
+    """把 invitee 绑定到 invite_code 对应的邀请人,注册即生效。
 
-    幂等:invitee 已被绑过 → already_bound(不重复发奖)。
+    v3 发奖(冰 2026-06-26 拍板):绑定双方都不发钱——被邀请人无奖励,邀请人改"好友成功比价一次
+    才发 2 元邀请奖励金"(见 try_reward_on_compare,防刷)。绑定只建归因关系 + 跑防刷闸。
+    幂等:已绑过 → already_bound。
     """
     # 幂等:已绑过直接返回(不重复发奖)
     existing = _relation_of_invitee(db, invitee.id)
@@ -114,27 +141,18 @@ def bind(
     if not _is_new_user(invitee):
         return BindResult("not_eligible")
 
-    inviter_coin = rewards.INVITE_INVITER_COINS
-    invitee_coin = rewards.INVITE_INVITEE_COINS
-
+    # v3(冰 2026-06-26 拍板):绑定双方都不发钱。被邀请人不再发新人金币(去掉拉新即时激励);
+    # 邀请人的钱由 try_reward_on_compare 在好友成功比价后发 2 元邀请奖励金(防刷)。
     rel = InviteRelation(
         inviter_user_id=inviter.id,
         invitee_user_id=invitee.id,
         channel=(channel or "clipboard")[:16],
         status="effective",
-        inviter_coin=inviter_coin,
-        invitee_coin=invitee_coin,
+        inviter_coin=0,                 # v1 金币线已停用,列保留恒 0(待清)
+        invitee_coin=0,                 # v3:被邀请人绑定不再发金币
     )
     db.add(rel)
-    # 双方发金币(同事务,与建关系一起 commit)。ref_id 互指对方便于对账。
-    crud_wallet.grant_coins(
-        db, inviter.id, inviter_coin,
-        biz_type="invite_inviter", ref_id=str(invitee.id), remark="邀请好友奖励",
-    )
-    crud_wallet.grant_coins(
-        db, invitee.id, invitee_coin,
-        biz_type="invite_invitee", ref_id=str(inviter.id), remark="新人受邀奖励",
-    )
+    # 绑定不发任何金币(邀请人改比价发现金、被邀请人无奖励),仅建归因关系。
     try:
         db.commit()
     except IntegrityError:
@@ -145,16 +163,62 @@ def bind(
             return BindResult("already_bound", existing)
         raise
     except Exception:
-        # 其它 commit 失败(DB 故障 / PG 序列化冲突等):显式回滚,保证"建关系 + 双方发币"
-        # 原子(要么全成要么全无),不依赖 get_db 关闭时的隐式回滚,语义更硬。
+        # 其它 commit 失败(DB 故障 / PG 序列化冲突等):显式回滚,保证建关系原子,
+        # 不依赖 get_db 关闭时的隐式回滚,语义更硬。
         db.rollback()
         raise
     db.refresh(rel)
-    return BindResult("success", rel, invitee_coin)
+    return BindResult("success", rel)
+
+
+@dataclass
+class CompareRewardResult:
+    status: str                    # granted / no_relation / already_granted / inviter_inactive
+    inviter_user_id: int | None = None
+    reward_cents: int = 0
+
+
+def try_reward_on_compare(db: Session, invitee_user_id: int) -> CompareRewardResult:
+    """被邀请人完成一次成功比价时调用:若其有邀请关系且尚未发过比价奖,给【邀请人】发邀请奖励金。
+
+    v2 发奖规则核心(替代 v1 的"注册即发金币"):好友"下载+登录+比价一次"→ 邀请人得 2 元现金。
+    幂等:compare_reward_granted 标记保证好友比价多次只发一次。无邀请关系 / 已发过 / 邀请人失效
+    → 空操作。发奖(grant_invite_cash 入账独立账户)+ 置标记同事务 commit,保证原子。
+    """
+    rel = _relation_of_invitee(db, invitee_user_id)
+    if rel is None:
+        return CompareRewardResult("no_relation")
+    if rel.compare_reward_granted:
+        return CompareRewardResult("already_granted", rel.inviter_user_id)
+
+    inviter = db.get(User, rel.inviter_user_id)
+    if inviter is None or inviter.status != "active":
+        # 邀请人注销 / 封禁:本次不发、不置标记,待其恢复后下次比价再试(保守,不吞奖励)
+        return CompareRewardResult("inviter_inactive", rel.inviter_user_id)
+
+    reward = rewards.INVITE_COMPARE_REWARD_CENTS
+    rel.compare_reward_granted = True
+    rel.compare_reward_cents = reward
+    rel.compare_rewarded_at = datetime.now(timezone.utc)
+    # 发邀请奖励金到邀请人的独立账户(与金币隔离),ref_id 指向被邀请人便于对账
+    crud_wallet.grant_invite_cash(
+        db, inviter.id, reward,
+        biz_type="invite_reward", ref_id=str(invitee_user_id), remark="好友比价奖励",
+    )
+    try:
+        db.commit()
+    except Exception:
+        db.rollback()
+        raise
+    return CompareRewardResult("granted", inviter.id, reward)
 
 
 def get_stats(db: Session, inviter_id: int) -> tuple[int, int]:
-    """返回 (已成功邀请人数, 累计从邀请获得的金币)。"""
+    """返回 (已成功邀请人数, 累计从邀请获得的金币)。
+
+    金币口径(inviter_coin 之和)自 v3 起恒 0(邀请人收益改走邀请奖励金,见 get_reward_stats /
+    try_reward_on_compare);保留返回位兼容旧响应字段 coins_earned。
+    """
     count = db.execute(
         select(func.count())
         .select_from(InviteRelation)
@@ -167,6 +231,26 @@ def get_stats(db: Session, inviter_id: int) -> tuple[int, int]:
     return int(count), int(coins)
 
 
+def get_reward_stats(db: Session, inviter_id: int) -> tuple[int, int]:
+    """v2 邀请奖励金战绩:(可提现余额/分, 累计提现成功/分)。
+
+    余额 = coin_account.invite_cash_balance_cents;累计提现 = 该用户 source=invite_cash 且
+    status=success 的提现单金额之和(成功打款才算)。供 /invite/me 提现板块展示。
+    """
+    from app.models.wallet import CoinAccount, WithdrawOrder
+    balance = db.execute(
+        select(CoinAccount.invite_cash_balance_cents).where(CoinAccount.user_id == inviter_id)
+    ).scalar_one_or_none()
+    withdrawn = db.execute(
+        select(func.coalesce(func.sum(WithdrawOrder.amount_cents), 0)).where(
+            WithdrawOrder.user_id == inviter_id,
+            WithdrawOrder.source == "invite_cash",
+            WithdrawOrder.status == "success",
+        )
+    ).scalar_one()
+    return int(balance or 0), int(withdrawn)
+
+
 def _mask_phone(phone: str) -> str:
     """手机号脱敏:138****8888。前端拿不到完整号,展示被邀请人时在此兜底名字。
 
@@ -210,7 +294,7 @@ def get_invitees(
         items.append({
             "display_name": u.nickname or u.wechat_nickname or _mask_phone(u.phone),
             "avatar_url": u.avatar_url or u.wechat_avatar_url or None,
-            "coins": rel.inviter_coin,
+            "coins": rel.inviter_coin,      # v3 起恒 0(邀请人收益改走邀请奖励金)
             "invited_at": rel.created_at,
         })
     has_more = offset + len(rows) < int(total)

app/repositories/launch_confirm_sample.py

@@ -2,8 +2,10 @@
 from __future__ import annotations
 
 import logging
+from datetime import datetime
 from typing import Optional
 
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.models.launch_confirm_sample import LaunchConfirmSample
@@ -33,3 +35,27 @@ def insert_sample(db: Session, payload: LaunchConfirmSampleIn) -> int:
     db.commit()
     db.refresh(row)
     return row.id
+
+
+def list_samples(
+    db: Session,
+    *,
+    exec_success: Optional[bool] = None,
+    host_package: Optional[str] = None,
+    since: Optional[datetime] = None,
+    limit: int = 1000,
+) -> list[LaunchConfirmSample]:
+    """按条件查样本(pricebot 的 distill_launch_confirm.py 沉淀工具读)。created_at 升序。
+
+    过滤项都可空:exec_success(只看放行成功的)/ host_package(只看某宿主包)/
+    since(>= created_at)。limit 兜底防一次拉爆全表。
+    """
+    stmt = select(LaunchConfirmSample)
+    if exec_success is not None:
+        stmt = stmt.where(LaunchConfirmSample.exec_success == exec_success)
+    if host_package:
+        stmt = stmt.where(LaunchConfirmSample.host_package == host_package)
+    if since is not None:
+        stmt = stmt.where(LaunchConfirmSample.created_at >= since)
+    stmt = stmt.order_by(LaunchConfirmSample.created_at.asc()).limit(limit)
+    return list(db.execute(stmt).scalars().all())

app/repositories/wallet.py

@@ -24,6 +24,7 @@ from app.models.wallet import (
     CashTransaction,
     CoinAccount,
     CoinTransaction,
+    InviteCashTransaction,
     WechatTransferAuthorization,
     WithdrawOrder,
 )
@@ -166,6 +167,36 @@ def grant_cash(
     return acc, txn
 
 
+def grant_invite_cash(
+    db: Session,
+    user_id: int,
+    amount_cents: int,
+    *,
+    biz_type: str,
+    ref_id: str | None = None,
+    remark: str | None = None,
+) -> tuple[CoinAccount, InviteCashTransaction]:
+    """邀请奖励金变动入口(正数入账 / 负数出账)。更新 invite_cash_balance_cents + 写
+    invite_cash_transaction,不 commit。与金币兑换的 cash_balance_cents **物理隔离**
+    (产品红线:邀请奖励金 ≠ 金币现金,两本账不可累加)。返回 (account, transaction),
+    调用方负责 commit。不在此校验扣成负——由调用方按业务保护。"""
+    acc = get_or_create_account(db, user_id, commit=False)
+    acc.invite_cash_balance_cents += amount_cents
+
+    txn = InviteCashTransaction(
+        user_id=user_id,
+        amount_cents=amount_cents,
+        balance_after_cents=acc.invite_cash_balance_cents,
+        biz_type=biz_type,
+        ref_id=ref_id,
+        remark=remark,
+        created_at=datetime.now(rewards.CN_TZ).replace(tzinfo=None),
+    )
+    db.add(txn)
+    db.flush()
+    return acc, txn
+
+
 def list_coin_transactions(
     db: Session,
     user_id: int,
@@ -411,33 +442,43 @@ def refund_reviewing_withdraws_on_unbind(db: Session, user_id: int) -> int:
 _OUT_BILL_NO_RE = re.compile(r"^[0-9A-Za-z_-]{8,32}$")
 
 
-def _try_deduct_cash(db: Session, user_id: int, amount_cents: int) -> bool:
-    """原子扣减现金:仅当余额足够时扣,返回是否成功。
+def _balance_col(source: str):
+    """提现账户来源 → CoinAccount 余额列。invite_cash=邀请奖励金;否则金币兑换的现金。
+    两账户物理隔离,提现扣款/退款都按 source 走对应列,互不串。"""
+    return (
+        CoinAccount.invite_cash_balance_cents
+        if source == "invite_cash"
+        else CoinAccount.cash_balance_cents
+    )
 
-    用带条件的 UPDATE(`WHERE cash_balance_cents >= amount`)避免"读-判断-写"竞态——
-    并发/重试时不会两次都通过余额检查导致超额扣款(SQLite 串行写、Postgres 行级,均安全)。
+
+def _try_deduct_cash(db: Session, user_id: int, amount_cents: int, source: str = "coin_cash") -> bool:
+    """原子扣减指定账户余额:仅当余额足够时扣,返回是否成功。
+
+    用带条件的 UPDATE(`WHERE <col> >= amount`)避免"读-判断-写"竞态——并发/重试时不会两次
+    都通过余额检查导致超额扣款(SQLite 串行写、Postgres 行级,均安全)。source 决定扣
+    cash_balance_cents(coin_cash) 还是 invite_cash_balance_cents(invite_cash)。
     """
+    col = _balance_col(source)
     res = db.execute(
         update(CoinAccount)
-        .where(
-            CoinAccount.user_id == user_id,
-            CoinAccount.cash_balance_cents >= amount_cents,
-        )
-        .values(cash_balance_cents=CoinAccount.cash_balance_cents - amount_cents)
+        .where(CoinAccount.user_id == user_id, col >= amount_cents)
+        .values({col: col - amount_cents})
     )
     return res.rowcount == 1
 
 
-def _add_cash(db: Session, user_id: int, amount_cents: int) -> int:
-    """原子增加现金(退款用),返回加后余额。"""
+def _add_cash(db: Session, user_id: int, amount_cents: int, source: str = "coin_cash") -> int:
+    """原子增加指定账户余额(退款用),返回加后余额。source 决定退回哪个账户(两账户隔离)。"""
+    col = _balance_col(source)
     db.execute(
         update(CoinAccount)
         .where(CoinAccount.user_id == user_id)
-        .values(cash_balance_cents=CoinAccount.cash_balance_cents + amount_cents)
+        .values({col: col + amount_cents})
     )
     db.flush()
     bal = db.execute(
-        select(CoinAccount.cash_balance_cents).where(CoinAccount.user_id == user_id)
+        select(col).where(CoinAccount.user_id == user_id)
     ).scalar_one()
     return bal
 
@@ -456,11 +497,15 @@ def _refund_withdraw(
     """
     if order.status in ("failed", "rejected"):
         return  # 防重复退款(并发/对账与查单/重复拒绝同时触发)
+    # 账户隔离:按 order.source 退回对应账户 + 写对应退款流水表
+    is_invite = order.source == "invite_cash"
+    txn_model = InviteCashTransaction if is_invite else CashTransaction
+    refund_biz = "invite_withdraw_refund" if is_invite else "withdraw_refund"
     refunded_txn_id = db.execute(
-        select(CashTransaction.id).where(
-            CashTransaction.user_id == order.user_id,
-            CashTransaction.biz_type == "withdraw_refund",
-            CashTransaction.ref_id == order.out_bill_no,
+        select(txn_model.id).where(
+            txn_model.user_id == order.user_id,
+            txn_model.biz_type == refund_biz,
+            txn_model.ref_id == order.out_bill_no,
         ).limit(1)
     ).scalar_one_or_none()
     if refunded_txn_id is not None:
@@ -468,13 +513,13 @@ def _refund_withdraw(
         order.fail_reason = reason[:256]
         db.commit()
         return
-    bal = _add_cash(db, order.user_id, order.amount_cents)
+    bal = _add_cash(db, order.user_id, order.amount_cents, order.source)
     db.add(
-        CashTransaction(
+        txn_model(
             user_id=order.user_id,
             amount_cents=order.amount_cents,
             balance_after_cents=bal,
-            biz_type="withdraw_refund",
+            biz_type=refund_biz,
             ref_id=order.out_bill_no,
             # 用户可见文案区分"未成功(自动退)"vs"审核未通过";技术原因记在 order.fail_reason
             remark=(
@@ -492,13 +537,13 @@ def _refund_withdraw(
         db.commit()
     except IntegrityError:
         # 并发退款兜底:唯一退款流水已被另一事务写入时,回滚本事务的加钱和流水,
-        # 再把订单状态补到终态。这样无论拒绝/查单/对账怎么并发,现金最多退一次。
+        # 再把订单状态补到终态。这样无论拒绝/查单/对账怎么并发,金额最多退一次。
         db.rollback()
         refunded_txn_id = db.execute(
-            select(CashTransaction.id).where(
-                CashTransaction.user_id == user_id,
-                CashTransaction.biz_type == "withdraw_refund",
-                CashTransaction.ref_id == out_bill_no,
+            select(txn_model.id).where(
+                txn_model.user_id == user_id,
+                txn_model.biz_type == refund_biz,
+                txn_model.ref_id == out_bill_no,
             ).limit(1)
         ).scalar_one_or_none()
         if refunded_txn_id is None:
@@ -562,6 +607,7 @@ def create_withdraw(
     user_id: int,
     amount_cents: int,
     *,
+    source: str = "coin_cash",
     user_name: str | None = None,
     out_bill_no: str | None = None,
 ) -> WithdrawOrder:
@@ -608,20 +654,23 @@ def create_withdraw(
     # 账户须存在(原子扣款的 UPDATE 不会建账户)
     get_or_create_account(db, user_id, commit=True)
 
-    # #1 原子扣款:余额不足时影响行数为 0
-    if not _try_deduct_cash(db, user_id, amount_cents):
+    # #1 原子扣款:余额不足时影响行数为 0(按 source 扣对应账户)
+    if not _try_deduct_cash(db, user_id, amount_cents, source):
         db.rollback()
         raise InsufficientCashError
 
+    is_invite = source == "invite_cash"
+    txn_model = InviteCashTransaction if is_invite else CashTransaction
+    withdraw_biz = "invite_withdraw" if is_invite else "withdraw"
     bal = db.execute(
-        select(CoinAccount.cash_balance_cents).where(CoinAccount.user_id == user_id)
+        select(_balance_col(source)).where(CoinAccount.user_id == user_id)
     ).scalar_one()
     db.add(
-        CashTransaction(
+        txn_model(
             user_id=user_id,
             amount_cents=-amount_cents,
             balance_after_cents=bal,
-            biz_type="withdraw",
+            biz_type=withdraw_biz,
             ref_id=out_bill_no,
             remark="提现到微信零钱(待审核)",
             created_at=datetime.now(rewards.CN_TZ).replace(tzinfo=None),
@@ -631,6 +680,7 @@ def create_withdraw(
         user_id=user_id,
         out_bill_no=out_bill_no,
         amount_cents=amount_cents,
+        source=source,
         user_name=user_name,
         status="reviewing",
     )
@@ -1007,10 +1057,12 @@ def reconcile_pending_withdraws(db: Session, *, older_than_minutes: int = 15) ->
 
 
 def list_withdraw_orders(
-    db: Session, user_id: int, *, limit: int = 20, cursor: int | None = None
+    db: Session, user_id: int, *, source: str | None = None, limit: int = 20, cursor: int | None = None
 ) -> tuple[list[WithdrawOrder], int | None]:
-    """提现单分页(按 id 倒序,游标式)。"""
+    """提现单分页(按 id 倒序,游标式)。source 非空时只返回该账户来源的单(coin_cash / invite_cash)。"""
     stmt = select(WithdrawOrder).where(WithdrawOrder.user_id == user_id)
+    if source is not None:
+        stmt = stmt.where(WithdrawOrder.source == source)
     if cursor is not None:
         stmt = stmt.where(WithdrawOrder.id < cursor)
     stmt = stmt.order_by(WithdrawOrder.id.desc()).limit(limit)

app/schemas/ad.py

@@ -57,6 +57,12 @@ class EcpmReportIn(BaseModel):
     )
     adn: str | None = Field(None, description="实际投放 ADN(getSdkName),如 pangle")
     slot_id: str | None = Field(None, description="实际展示代码位(底层 mediation rit)")
+    feed_scene: str | None = Field(
+        None,
+        max_length=16,
+        description="点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页);"
+        "比价与领券共用同一 Draw 代码位,需客户端在各调用点显式标注,供收益报表区分比价/领券;激励视频为空",
+    )
     app_env: str | None = Field(
         None, max_length=16, description="我们的穿山甲应用环境:prod(傻瓜比价正式) / test(测试应用)"
     )
@@ -128,6 +134,11 @@ class FeedRewardIn(BaseModel):
     """
 
     client_event_id: str = Field(..., min_length=8, max_length=64, description="客户端生成的幂等事件 id")
+    ad_type: str = Field(
+        "feed",
+        max_length=16,
+        description="广告类型:feed(信息流) / draw(Draw 信息流);默认 feed 兼容旧客户端",
+    )
     ad_session_id: str | None = Field(
         None, min_length=8, max_length=64, description="客户端生成的一次信息流广告会话 id"
     )
@@ -156,6 +167,11 @@ class FeedRewardIn(BaseModel):
     aborted: bool = Field(
         False, description="用户中途 ✕ 关闭广告(未走完比价):整场不发,记 closed_early"
     )
+    display_coin: int = Field(
+        0, ge=0,
+        description="客户端金币小球**本条显示**的金币(所见即所得):后端直接发这个数,钳到本条最大 1 份"
+        "满额防刷。缺省 0 = 旧客户端不传,退回服务端「看满 10 秒发整份」",
+    )
 
 
 class FeedRewardOut(BaseModel):

app/schemas/analytics.py

@@ -0,0 +1,42 @@
+"""客户端埋点上报 schema(批量)。
+
+客户端把「设备固定维度」(device_id / user_id / oem / os / model / app_ver / channel / sent_at)
+放批次外层只传一次,events 列表里每条只带「事件维度」(event / client_ts / session_id / page /
+network / props);服务端展开成多行 AnalyticsEvent 落库(见 app/repositories/analytics.py)。
+"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class AnalyticsEventIn(BaseModel):
+    """单条事件维度。"""
+
+    event: str = Field(max_length=64)
+    client_ts: int = Field(description="端事件发生时间 epoch ms")
+    session_id: str | None = Field(default=None, max_length=64)
+    page: str | None = Field(default=None, max_length=64)
+    network: str | None = Field(default=None, max_length=16)
+    props: dict[str, str] = Field(default_factory=dict)
+
+
+class AnalyticsBatchIn(BaseModel):
+    """一批上报:公共维度 + 事件列表。"""
+
+    # Who(整批共享)
+    device_id: str = Field(max_length=64)
+    user_id: int | None = None
+    # When(本批上报时刻 epoch ms)
+    sent_at: int | None = None
+    # How(设备固定维度,整批共享)
+    oem: str | None = Field(default=None, max_length=32)
+    os: str | None = Field(default=None, max_length=32)
+    model: str | None = Field(default=None, max_length=64)
+    app_ver: str | None = Field(default=None, max_length=32)
+    channel: str | None = Field(default=None, max_length=32)
+    events: list[AnalyticsEventIn] = Field(min_length=1, max_length=200)
+
+
+class AnalyticsIngestOut(BaseModel):
+    ok: bool = True
+    received: int

app/schemas/auth.py

@@ -71,6 +71,10 @@ class JverifyLoginRequest(BaseModel):
 
 class SmsSendRequest(BaseModel):
     phone: str = Field(..., min_length=11, max_length=11, pattern=r"^1\d{10}$")
+    device_id: str = Field(
+        "", max_length=64,
+        description="硬件级设备标识(Android ANDROID_ID),用于发码防刷按 设备+IP 限流;空=按 IP 聚一桶",
+    )
 
 
 class SmsSendResponse(BaseModel):

app/schemas/compare_record.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 
 # ===== 上报请求 =====
@@ -21,8 +21,36 @@ class ComparisonItemIn(BaseModel):
 
     name: str
     qty: int = 1
+    # specs 仅供比价记录展示(admin-web 详情 / app 记录页都按字符串数组渲染并 join)。
+    # pricebot(2026-06-27 嵌套规格统一)起 calibration 的 specs 可能是规格对象
+    # [{name, qty, sub_specs}] 而非字符串 → 下面的 before-validator 统一拍平成可读字符串,
+    # 兼容新旧两种输入、保持 list[str] 契约不变(下游零改动)。
+    # ⚠️ 两个坑都踩过, 必须"拍平"而非别的: ① 直接声明 list[str] 不拍平 → 对象 specs 整条
+    # 422 被拒、不入库(同下方 platform_results list→dict 同类事故); ② 仅放宽成裸 list 又会让
+    # 下游 join 出 "[object Object]"/对象 toString 的乱码。
     specs: list[str] | None = None
 
+    @field_validator("specs", mode="before")
+    @classmethod
+    def _flatten_specs(cls, v: object) -> object:
+        """pricebot 规格对象 [{name, qty, sub_specs}] → 可读字符串数组; 字符串元素原样保留;
+        非 list 原样交还(让 pydantic 照常报类型错)。嵌套规格拼成 '主项(子1,子2)'。"""
+        if not isinstance(v, list):
+            return v
+        out: list[str] = []
+        for it in v:
+            if isinstance(it, str):
+                s = it
+            elif isinstance(it, dict):
+                name = str(it.get("name") or "").strip()
+                subs = [str(x).strip() for x in (it.get("sub_specs") or []) if str(x).strip()]
+                s = f"{name}({','.join(subs)})" if name and subs else (name or ",".join(subs))
+            else:
+                continue
+            if s:
+                out.append(s)
+        return out
+
 
 class AppliedCouponIn(BaseModel):
     """单笔已用优惠(来自 comparison_results[].applied_coupons)。amount 单位:元、正数。"""
@@ -95,6 +123,7 @@ class ComparisonRecordIn(BaseModel):
     # pricebot done.params.trace_url 原样上报,落库供记录页「复制调试链接」(dir 名含落盘
     # 时分秒前端拼不出,必须由后端透传)。
     trace_url: str | None = Field(None, description="本次比价公网调试链接")
+    total_ms: int | None = Field(None, description="整场比价墙钟耗时(ms)")
 
     # ===== debug 维度(客户端采集上报;旧客户端不带 → None。仅 admin 比价记录页用)=====
     # 必须显式声明,否则 model_dump() 落 raw_payload 时被 pydantic 静默丢弃(同上面 coupon_saved 的坑)。
@@ -144,6 +173,7 @@ class ComparisonRecordOut(BaseModel):
     items: list = []
     comparison_results: list = []
     skipped_dish_names: list = []
+    total_ms: int | None = None
     # 「已下单」(店级):该店名在该用户真实下单(source='compare')里出现过即 True。
     # 由 list_records 动态算出挂在 ORM 实例上(非 DB 列),from_attributes 读出;缺省 False。
     ordered: bool = False

app/schemas/invite.py

@@ -10,7 +10,12 @@ class InviteInfoOut(BaseModel):
     invite_code: str                # 我的邀请码
     share_url: str                  # 落地页链接(含 ?ref=),前端据此生成二维码 + 复制分享
     invited_count: int              # 已成功邀请人数
-    coins_earned: int               # 累计从邀请获得的金币
+    coins_earned: int               # 累计从邀请获得的金币(v1 口径;v2 邀请人改发奖励金)
+    reward_balance_cents: int = 0   # v2 可提现邀请奖励金(分)
+    reward_withdrawn_cents: int = 0 # v2 累计提现成功的邀请奖励金(分)
+    countdown_days_left: int = 7            # v2 本轮剩余天数(7 天 1 轮)
+    countdown_is_fresh_round: bool = False  # 是否刚进入新一轮(非首轮第1天)
+    countdown_text: str = ""                # 倒计时展示文案(前端直接显示,新轮含换行)
 
 
 class LandingTrackIn(BaseModel):

app/schemas/launch_confirm_sample.py

@@ -1,7 +1,9 @@
 """启动确认窗兜底样本的内部上报模型(pricebot → app-server)。"""
 from __future__ import annotations
 
-from pydantic import BaseModel
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
 
 
 class LaunchConfirmSampleIn(BaseModel):
@@ -24,3 +26,20 @@ class LaunchConfirmSampleOut(BaseModel):
     """落库结果。"""
 
     id: int
+
+
+class LaunchConfirmSampleRow(BaseModel):
+    """单条样本(列表读出;沉淀脚本 distill 用,payload 原样带出)。"""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: int
+    created_at: datetime
+    trace_id: str | None = None
+    device_id: str | None = None
+    host_package: str | None = None
+    target_app: str | None = None
+    system_locale: str | None = None
+    exec_success: bool = False
+    dialog_title: str | None = None
+    payload: dict | None = None

app/schemas/platform.py

@@ -38,8 +38,8 @@ class AdConfigPublicOut(BaseModel):
 
     app_id: str  # 穿山甲应用ID(改了客户端需冷启才生效,SDK init 一次性读)
     reward_code_id: str  # 福利页激励视频位
-    compare_feed_code_id: str  # 比价信息流位
-    coupon_feed_code_id: str  # 领券信息流位
+    compare_draw_code_id: str  # 比价 Draw 代码位
+    coupon_draw_code_id: str  # 领券 Draw 代码位(比价/领券共用同一位,靠 feed_scene 区分收益)
     reward_enabled: bool  # 福利激励视频开关
     compare_ad_enabled: bool  # 比价广告开关
     coupon_ad_enabled: bool  # 领券广告开关

app/schemas/welfare.py

@@ -16,6 +16,7 @@ class CoinAccountOut(BaseModel):
 
     coin_balance: int = Field(..., description="当前金币余额")
     cash_balance_cents: int = Field(..., description="当前现金余额(分)")
+    invite_cash_balance_cents: int = Field(0, description="邀请奖励金余额(分,与现金隔离)")
     total_coin_earned: int = Field(..., description="累计赚取金币")
 
 
@@ -123,6 +124,7 @@ class UnbindWechatResultOut(BaseModel):
 
 class WithdrawRequest(BaseModel):
     amount_cents: int = Field(..., gt=0, description="提现金额(分)")
+    source: str = Field("coin_cash", description="提现账户:coin_cash(金币现金) / invite_cash(邀请奖励金)")
     user_name: str | None = Field(None, description="实名(达额时微信要求,可空)")
     out_bill_no: str | None = Field(
         None, description="客户端幂等键(商户单号):同号重试不重复转账。不传则服务端生成"
@@ -166,6 +168,7 @@ class WithdrawOrderOut(BaseModel):
     id: int
     out_bill_no: str
     amount_cents: int
+    source: str = Field("coin_cash", description="提现账户:coin_cash / invite_cash")
     status: str = Field(..., description="reviewing(待审核) / pending / success / failed / rejected")
     wechat_state: str | None = None
     fail_reason: str | None = None

data/media/dl.html

@@ -8,122 +8,231 @@
 <style>
   * { margin:0; padding:0; box-sizing:border-box; -webkit-tap-highlight-color:transparent; }
   html,body { height:100%; }
+  button { border:0; background:none; color:inherit; font:inherit; cursor:pointer; }
   body {
-    font-family:-apple-system,BlinkMacSystemFont,"PingFang SC","Microsoft YaHei",sans-serif;
-    background:linear-gradient(165deg,#FF7A3D 0%,#FF3B30 52%,#E0245E 100%);
-    color:#fff; min-height:100%; display:flex; flex-direction:column;
-    align-items:center; justify-content:center; padding:40px 26px; text-align:center;
-    overflow-x:hidden;
+    min-height:100vh;
+    display:flex; align-items:center; justify-content:center;
+    background:#000;
+    font-family:-apple-system,BlinkMacSystemFont,"PingFang SC","Helvetica Neue",sans-serif;
   }
-  .logo {
-    width:104px; height:104px; border-radius:26px; background:#fff;
-    display:flex; align-items:center; justify-content:center; font-size:52px;
-    box-shadow:0 14px 34px rgba(0,0,0,.22); margin-bottom:24px;
+  /* 设备框：桌面预览成 375×667 卡片；真机（≤430）铺满全屏 */
+  .device {
+    position:relative; flex:0 0 auto;
+    width:375px; height:667px;
+    overflow:hidden; border-radius:32px;
+    background:#FFF4CD;
+    box-shadow:0 20px 60px rgba(0,0,0,.5);
+    color:#fff;
   }
-  h1 { font-size:30px; font-weight:800; letter-spacing:1px; }
-  .slogan { margin-top:12px; font-size:16px; line-height:1.7; opacity:.95; max-width:300px; }
-  .feats { margin-top:26px; display:flex; flex-direction:column; gap:12px; width:100%; max-width:320px; }
-  .feat { background:rgba(255,255,255,.16); border-radius:14px; padding:13px 16px; font-size:15px; display:flex; align-items:center; gap:10px; }
-  .feat b { font-weight:700; }
-  .btn {
-    margin-top:34px; width:100%; max-width:320px; border:none; cursor:pointer;
-    background:#fff; color:#FF3B30; font-size:19px; font-weight:800;
-    padding:17px 0; border-radius:999px; box-shadow:0 10px 26px rgba(0,0,0,.22);
-    display:flex; align-items:center; justify-content:center; gap:9px;
+  .download-landing {
+    position:absolute; inset:0; z-index:0; overflow:hidden;
+    background:
+      url('coupon-page-bg.png') center center / cover no-repeat,
+      #FFF4CD;
+    color:#1A1A1A; text-align:center;
+  }
+  .download-content {
+    position:relative; z-index:1; height:100%;
+    padding:82px 20px 0;
+    display:flex; flex-direction:column; align-items:center; overflow:hidden;
+  }
+  .brand-lockup {
+    display:flex; align-items:center; justify-content:center; gap:16px;
+  }
+  .ad-logo {
+    width:53px; height:53px; border-radius:13px; display:block;
+    box-shadow:0 10px 24px rgba(255,179,0,.24);
+  }
+  .ad-title {
+    color:#1A1A1A; font-size:32px; font-weight:800; line-height:1.15;
+    letter-spacing:0; white-space:nowrap;
+  }
+  .ad-subtitle {
+    margin-top:22px; max-width:100%;
+    color:#000; font-size:18px; font-weight:400; line-height:1.25;
+    display:flex; align-items:center; justify-content:center; gap:10px; white-space:nowrap;
+  }
+  .ad-subtitle::before, .ad-subtitle::after {
+    content:""; width:5px; height:5px; border-radius:50%; background:#000; flex:0 0 auto;
+  }
+  .bottom-area {
+    position:relative; z-index:2; width:100%; max-width:266px;
+    margin-top:11px;
+    display:grid; grid-template-columns:1fr; justify-items:stretch; align-content:center; gap:10px;
+  }
+  .download-btn {
+    width:100%; height:39px; border-radius:22px; color:#1A1A1A;
+    font-family:inherit; font-size:14px; line-height:1; font-weight:700; letter-spacing:0;
+    display:flex; align-items:center; justify-content:center;
+  }
+  .download-btn.primary {
+    background:linear-gradient(180deg,#FFE066 0%,#FFC400 100%);
+    box-shadow:inset 0 1px 0 rgba(255,255,255,.82), 0 7px 18px rgba(255,179,0,.24);
+  }
+  .download-btn.secondary {
+    background:#fff; border:1px solid #DDD; color:#1A1A1A; font-size:13px;
+    box-shadow:0 2px 8px rgba(122,79,0,.08);
+  }
+  .download-btn:active { transform:translateY(1px); }
+  /* 底部两条卖点文案，压在背景插画两张卡片下方 */
+  /* 卖点卡：CSS 实体卡片（白底+图标），不再靠底图死框，字自适应（对齐 WeChat.html PR siyi 改版）*/
+  .download-feature-card {
+    position:absolute; z-index:2; pointer-events:none;
+    height:62px; padding:0 10px; border-radius:22px;
+    background:#FFFAEE;
+    box-shadow:inset 0 1px 0 rgba(255,255,255,.86), 0 6px 14px rgba(122,79,0,.08);
+    display:flex; align-items:center; gap:8px; color:#1A1A1A;
+  }
+  .download-feature-card.left  { left:24px;  top:576px; width:146px; }
+  .download-feature-card.right { left:199px; top:576px; width:156px; }
+  .download-feature-icon {
+    width:27px; height:27px; flex:0 0 auto; display:block; color:#FFAE00;
+  }
+  .download-feature-icon svg {
+    display:block; width:100%; height:100%; filter:drop-shadow(0 1px 0 rgba(255,255,255,.7));
+  }
+  .download-feature-copy {
+    min-width:0; flex:1 1 auto; text-align:left; white-space:nowrap; letter-spacing:0;
+  }
+  .download-feature-title {
+    display:block; font-size:13px; font-weight:800; line-height:1.12; letter-spacing:0;
+  }
+  .download-feature-desc {
+    display:block; margin-top:5px; color:#5A3A00; font-size:10px; font-weight:400; line-height:1.1;
   }
-  .btn:active { transform:translateY(1px); opacity:.92; }
-  .hint { margin-top:16px; font-size:13px; opacity:.85; }
-  .foot { margin-top:30px; font-size:12px; opacity:.6; line-height:1.6; max-width:320px; }
-
   /* 微信内"去浏览器打开"引导蒙层 */
-  #wxmask {
-    display:none; position:fixed; inset:0; z-index:9999;
-    background:rgba(0,0,0,.86); padding:18px;
+  .download-guide-layer {
+    position:absolute; inset:0; z-index:30; display:none;
+    background:rgba(0,0,0,.85); color:#fff;   /* 半透明黑：透出底层（新版）下载页，隐约可见 */
+  }
+  .download-guide-layer.show { display:block; }
+  .download-guide-arrow {
+    position:absolute; top:17px; right:9px; width:80px; height:60px;
+  }
+  .download-guide-arrow-svg {
+    display:block; width:100%; height:100%; overflow:hidden; shape-rendering:geometricPrecision;
+  }
+  .download-guide-title {
+    position:absolute; top:129px; right:16px; width:218px; margin:0;
+    color:#fff; font-size:17px; font-weight:800; line-height:1.32; letter-spacing:0;
+    text-align:right; text-shadow:0 2px 8px rgba(0,0,0,.36);
+  }
+  .download-guide-title .guide-dots { color:#FFD95A; letter-spacing:4px; }
+  .download-guide-title .guide-highlight { color:#FFD95A; white-space:nowrap; }
+  .download-guide-title .guide-final {
+    display:block; margin-top:10px; color:rgba(255,255,255,.94);
+    font-size:13px; font-weight:700; line-height:1.38;
+  }
+  .download-guide-title .guide-target { color:#FFD95A; white-space:nowrap; }
+  .guide-dismiss {
+    position:absolute; bottom:30px; left:0; right:0; text-align:center;
+    font-size:14px; color:#fff; opacity:.75;
+  }
+  .toast {
+    position:absolute; left:50%; bottom:118px; z-index:20;
+    transform:translateX(-50%) translateY(12px);
+    padding:9px 14px; border-radius:12px; background:rgba(0,0,0,.78);
+    color:#fff; font-size:14px; opacity:0; pointer-events:none;
+    transition:opacity .2s ease, transform .2s ease;
+  }
+  .toast.show { opacity:1; transform:translateX(-50%) translateY(0); }
+  @media (max-width:430px) {
+    /* 真机:宽满屏、高按 375:667 锁比例(不拉伸变形),顶对齐、底部留白用底色填。
+       这样底图(含价格卡)与卖点卡片同处 667 坐标基准,卡片用回 top:576,不再相互错位/遮挡。 */
+    body { align-items:flex-start; background:#FFF4CD; }
+    .device { width:100vw; height:calc(100vw * 667 / 375); border-radius:0; box-shadow:none; }
   }
-  #wxmask.show { display:block; }
-  .arrow { position:absolute; top:8px; right:14px; width:120px; }
-  .wxtip { position:absolute; top:150px; right:18px; left:18px; text-align:right; }
-  .wxtip .big { font-size:21px; font-weight:800; line-height:1.5; }
-  .wxtip .big em { color:#FFD24D; font-style:normal; }
-  .wxtip .sub { margin-top:14px; font-size:15px; line-height:1.8; opacity:.9; }
-  .wxsteps { margin-top:26px; text-align:left; background:rgba(255,255,255,.1); border-radius:14px; padding:18px 18px; font-size:15px; line-height:2; }
-  .wxsteps .n { display:inline-block; width:22px; height:22px; line-height:22px; text-align:center; border-radius:50%; background:#FFD24D; color:#333; font-weight:800; font-size:13px; margin-right:8px; }
-  .closebar { position:absolute; bottom:30px; left:0; right:0; text-align:center; font-size:14px; opacity:.7; }
 </style>
 </head>
 <body>
-  <div class="logo">🛒</div>
-  <h1>傻瓜比价</h1>
-  <div class="slogan">买什么都先比一比<br>自动帮你找全网最低价</div>
-
-  <div class="feats">
-    <div class="feat">🍔 <span>点外卖前一键比价,<b>美团/京东/淘宝</b>到手价一目了然</span></div>
-    <div class="feat">🎟️ <span>自动领遍各平台<b>红包券</b>,能省的一分不漏</span></div>
-    <div class="feat">💰 <span>省下的钱看得见,还能<b>赚金币提现</b></span></div>
-  </div>
-
-  <button class="btn" id="dlbtn">🏪 打开应用商店下载</button>
-  <div class="hint" id="hint">Android 安卓版 · 应用商店安全下载</div>
-
-  <div class="foot">
-    将前往应用商店下载,安全放心。<br>
-    本页为内部测试页。
-  </div>
-
-  <!-- 微信内引导:跳出微信去浏览器 -->
-  <div id="wxmask">
-    <svg class="arrow" viewBox="0 0 120 130" fill="none" xmlns="http://www.w3.org/2000/svg">
-      <path d="M30 120 C 30 70, 55 40, 95 28" stroke="#FFD24D" stroke-width="6" stroke-linecap="round" fill="none" stroke-dasharray="2 13"/>
-      <path d="M95 28 L 78 30 M95 28 L 92 46" stroke="#FFD24D" stroke-width="6" stroke-linecap="round"/>
-    </svg>
-    <div class="wxtip">
-      <div class="big">点击右上角 <em>···</em><br>选择「<em>在浏览器打开</em>」</div>
-      <div class="sub">微信里无法直接下载安装包<br>需在系统浏览器中完成下载</div>
-      <div class="wxsteps">
-        <div><span class="n">1</span>点右上角的 ··· 菜单</div>
-        <div><span class="n">2</span>选择「在浏览器打开」</div>
-        <div><span class="n">3</span>在浏览器里按提示去应用商店下载</div>
+<main class="device" aria-label="傻瓜比价下载页">
+  <section class="download-landing" aria-label="傻瓜比价下载页">
+    <div class="download-content">
+      <div class="brand-lockup">
+        <img class="ad-logo" src="sb-brand.png" alt="傻瓜比价">
+        <h1 class="ad-title">傻瓜比价</h1>
+      </div>
+      <p class="ad-subtitle">跨平台比价，用傻瓜</p>
+      <div class="bottom-area" aria-label="下载入口">
+        <button class="download-btn primary"  id="dlbtn"  type="button">应用商店下载</button>
+        <button class="download-btn secondary" id="dlbtn2" type="button">官网下载</button>
       </div>
     </div>
-    <div class="closebar" id="wxclose">我知道了 ✕</div>
+    <div class="download-feature-card left" aria-label="优惠券轻松领，羊毛全都不错过">
+      <span class="download-feature-icon" aria-hidden="true">
+        <svg viewBox="0 0 40 32" focusable="false">
+          <path d="M5 5h30a3 3 0 0 1 3 3v5.2a4.8 4.8 0 0 0 0 9.6V24a3 3 0 0 1-3 3H5a3 3 0 0 1-3-3v-1.2a4.8 4.8 0 0 0 0-9.6V8a3 3 0 0 1 3-3Z" fill="currentColor"/>
+          <path d="M20 10v12" fill="none" stroke="#FFF7CF" stroke-width="3" stroke-linecap="round"/>
+        </svg>
+      </span>
+      <span class="download-feature-copy">
+        <span class="download-feature-title">优惠券轻松领</span>
+        <span class="download-feature-desc">羊毛全都不错过</span>
+      </span>
+    </div>
+    <div class="download-feature-card right" aria-label="一键全网找底价，再也不用费力切屏">
+      <span class="download-feature-icon" aria-hidden="true">
+        <svg viewBox="0 0 40 32" focusable="false">
+          <rect x="5" y="16" width="8" height="11" rx="2" fill="currentColor"/>
+          <rect x="16" y="9" width="8" height="18" rx="2" fill="currentColor"/>
+          <rect x="27" y="3" width="8" height="24" rx="2" fill="currentColor"/>
+        </svg>
+      </span>
+      <span class="download-feature-copy">
+        <span class="download-feature-title">一键全网找底价</span>
+        <span class="download-feature-desc">再也不用费力切屏</span>
+      </span>
+    </div>
+  </section>
+
+  <!-- 微信内引导：跳出微信去浏览器 -->
+  <div class="download-guide-layer" id="wxGuide" role="dialog" aria-modal="true" aria-labelledby="wxGuideTitle">
+    <div class="download-guide-arrow" aria-hidden="true">
+      <svg class="download-guide-arrow-svg" viewBox="0 0 80 60" focusable="false">
+        <path d="M0 60 C16 32 39 15 66 15" fill="none" stroke="#FFD95A" stroke-width="5.5" stroke-linecap="round"/>
+        <path d="M59 5 L77 14 L63 31" fill="none" stroke="#FFD95A" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+    </div>
+    <h2 class="download-guide-title" id="wxGuideTitle">
+      点击右上角 <span class="guide-dots">···</span><br>
+      选择「<span class="guide-highlight">在浏览器打开</span>」
+      <span class="guide-final">在浏览器里按提示<span class="guide-target">去应用商店下载</span></span>
+    </h2>
+    <div class="guide-dismiss" id="wxGuideDismiss">我知道了 ✕</div>
   </div>
 
+  <div class="toast" id="toast" role="status" aria-live="polite"></div>
+</main>
+
 <script>
-  // 应用商店跳转:用包名(App 唯一标识 = 身份证号)定位到傻瓜比价的商店下载页。
-  // 主:market:// 唤起手机自带应用市场(华为/小米/OV);兜底:应用宝网页(任何浏览器都能开)。
+  // ===== 应用商店跳转：用包名（App 唯一标识）定位到傻瓜比价的商店下载页 =====
+  // 主：market:// 唤起手机自带应用市场（华为/小米/OV）；兜底：应用宝网页（任何浏览器都能开）。
   var PKG = "com.jishisongfu.shaguabijia";
   var MARKET_URL = "market://details?id=" + PKG;
   var YYB_URL = "https://a.app.qq.com/o/simple.jsp?pkgname=" + PKG;
   var ua = navigator.userAgent || "";
   var isWeChat = /MicroMessenger/i.test(ua);
   var isIOS = /iPhone|iPad|iPod/i.test(ua);
-  var isAndroid = /Android/i.test(ua);
-  var ref = new URLSearchParams(location.search).get("ref");  // 邀请码(来自二维码 URL ?ref=)
+  var ref = new URLSearchParams(location.search).get("ref");  // 邀请码（来自二维码 URL ?ref=）
 
-  // 【任务 3】指纹归因兜底:页面加载即上报访问者指纹,后端存 invite_fingerprint 表。
-  // 当 APK 首启读剪贴板失败(被覆盖)时,客户端会用 (IP+屏幕+UA 解析的手机型号) 反查
-  // 本表 7 天内最近一条匹配 → 撞库出原邀请人 → 走原 bind 流程。
-  // 任何失败都 silent(不影响下载主流程);后端 invalid_code/no_ip 也只返 200。
+  // ===== 指纹归因兜底：页面加载即上报访问者指纹，后端存 invite_fingerprint 表 =====
+  // 当 APK 首启读剪贴板失败（被覆盖）时，客户端用 (IP+屏幕+UA 机型) 反查 7 天内最近一条 → 撞出原邀请人。
+  // 任何失败都 silent，不影响下载主流程。
   if (ref) {
-    // screen 报【物理像素】= CSS 像素 × devicePixelRatio,跟 Android dm.widthPixels(物理像素)对齐。
-    // 不同设备 DPR 不同(常见 2/2.5/3/3.5),CSS 像素直接报会跟客户端不对齐 → 撞不上库。
+    // screen 报【物理像素】= CSS 像素 × devicePixelRatio，跟 Android dm.widthPixels 对齐，否则撞不上库。
     var _dpr = window.devicePixelRatio || 1;
     var _sw = Math.round(screen.width * _dpr);
     var _sh = Math.round(screen.height * _dpr);
     fetch("/api/v1/invite/landing-track", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        ref: ref,
-        screen: _sw + "x" + _sh,
-        // IP / UA 服务端从 HTTP 头自动拿,无需 JS 上报
-      }),
-    }).catch(function () {});  // silent,绝不阻断下载
+      body: JSON.stringify({ ref: ref, screen: _sw + "x" + _sh }),
+    }).catch(function () {});  // silent，绝不阻断下载
   }
 
-  // 把邀请码写进剪贴板,APK 首启时读出来完成归因(deferred deeplink 的关键一步)。
-  // 浏览器要求:必须在用户点击手势里调用 + HTTPS 下才允许写。
-  function legacyCopy(payload) {                // 老 webview / 无 clipboard API 兜底
+  // ===== 把邀请码写进剪贴板，APK 首启读出完成归因（deferred deeplink）=====
+  // 浏览器要求：必须在用户点击手势里调用 + HTTPS 下才允许写。
+  function legacyCopy(payload) {                 // 老 webview / 无 clipboard API 兜底
     try {
       var ta = document.createElement("textarea");
       ta.value = payload; ta.style.position = "fixed"; ta.style.top = "-1000px"; ta.style.opacity = "0";
@@ -131,50 +240,48 @@
       document.execCommand("copy"); document.body.removeChild(ta);
     } catch (e) {}
   }
-  function copyInviteCode() {                   // 返回 Promise(完成后才下载,避免异步写入被打断)
+  function copyInviteCode() {                    // 返回 Promise，完成后才下载，避免异步写入被打断
     if (!ref) return Promise.resolve();
     var payload = "SGBJ_INVITE:" + ref;
-    legacyCopy(payload);                         // 同步兜底:在用户手势内立刻 execCommand 写一次(最可靠)
+    legacyCopy(payload);                          // 同步兜底：在用户手势内立刻 execCommand 写一次（最可靠）
     if (navigator.clipboard && navigator.clipboard.writeText) {
-      return navigator.clipboard.writeText(payload).catch(function () {});  // 现代 API 锦上添花,失败无妨
+      return navigator.clipboard.writeText(payload).catch(function () {});
     }
     return Promise.resolve();
   }
-  // 跳应用商店:先尝试 market:// 唤起手机自带商店;若 2.5s 内页面没切到后台
-  //(= 没有商店接管 market://),兜底跳应用宝网页下载页,不让用户卡死。
+  // 跳应用商店：先 market:// 唤起自带商店；2.5s 内页面没切后台 → 兜底跳应用宝网页，不让用户卡死。
   function openStore() {
     var jumped = false;
-    function markJumped() { jumped = true; }           // 页面切到后台 = 商店已唤起
-    document.addEventListener("visibilitychange", function () {
-      if (document.hidden) jumped = true;
-    });
-    window.addEventListener("pagehide", markJumped);
-    window.addEventListener("blur", markJumped);
-    window.location.href = MARKET_URL;                 // 唤起自带应用市场
-    setTimeout(function () {
-      if (!jumped) window.location.href = YYB_URL;     // 没唤起 → 应用宝网页兜底
-    }, 2500);
+    document.addEventListener("visibilitychange", function () { if (document.hidden) jumped = true; });
+    window.addEventListener("pagehide", function () { jumped = true; });
+    window.addEventListener("blur", function () { jumped = true; });
+    window.location.href = MARKET_URL;
+    setTimeout(function () { if (!jumped) window.location.href = YYB_URL; }, 2500);
   }
 
-  var hint = document.getElementById("hint");
-  if (isIOS) hint.textContent = "检测到 iPhone · iOS 版请前往 App Store";
+  // ===== 微信内引导蒙层 =====
+  var wxGuide = document.getElementById("wxGuide");
+  function showWxGuide() { wxGuide.classList.add("show"); }
+  function hideWxGuide() { wxGuide.classList.remove("show"); }
+  document.getElementById("wxGuideDismiss").addEventListener("click", hideWxGuide);
+  if (isWeChat) showWxGuide();   // 微信里一进页面就提示去浏览器（微信内下载必被拦）
 
-  var mask = document.getElementById("wxmask");
-  function showMask(){ mask.classList.add("show"); }
-  function hideMask(){ mask.classList.remove("show"); }
-  document.getElementById("wxclose").addEventListener("click", hideMask);
+  function showToast(text) {
+    var toast = document.getElementById("toast");
+    toast.textContent = text; toast.classList.add("show");
+    clearTimeout(showToast.timer);
+    showToast.timer = setTimeout(function () { toast.classList.remove("show"); }, 1400);
+  }
 
-  // 微信里一进页面就提示去浏览器打开(下载在微信内必被拦)
-  if (isWeChat) showMask();
-
-  document.getElementById("dlbtn").addEventListener("click", function(){
-    if (isWeChat) { showMask(); return; }           // 微信内:引导去浏览器
-    if (isIOS)    { alert("iOS 版即将上线,请前往 App Store 搜索「傻瓜比价」"); return; }
-    // 安卓浏览器:先把邀请码写进剪贴板(legacyCopy 同步写、最可靠),再跳应用商店。
-    // 剪贴板供 App 首启归因;链路长易丢时由指纹兜底(已上报 landing-track)接住。
-    copyInviteCode();
+  // ===== 下载按钮：微信内引导去浏览器；iOS 提示；安卓写邀请码 + 跳应用商店 =====
+  function handleDownload() {
+    if (isWeChat) { showWxGuide(); return; }
+    if (isIOS)    { alert("iOS 版即将上线，请前往 App Store 搜索「傻瓜比价」"); return; }
+    copyInviteCode();   // 先把邀请码写进剪贴板（供 App 首启归因），链路丢了还有 landing-track 指纹兜底
     openStore();
-  });
+  }
+  document.getElementById("dlbtn").addEventListener("click", handleDownload);
+  document.getElementById("dlbtn2").addEventListener("click", handleDownload);
 </script>
 </body>
 </html>

docs/api/admin-ad-revenue-report.md

@@ -27,8 +27,11 @@
   | `date_to` | string | =`date_from` | 结束日 北京时间 `YYYY-MM-DD`,**闭区间**;单日时与 `date_from` 相同 |
   | `user_id` | int | 全部 | 只看某用户;不传=所有用户 |
   | `ad_type` | string | 全部 | `reward_video` / `feed` / `draw`;不传=全部类型 |
+  | `feed_scene` | string | 全部 | `comparison`(比价)/ `coupon`(领券)/ `welfare`(福利);**全局筛选**,同时作用于明细 / 合计 / `daily`·`hourly` 趋势;不传=全部场景 |
   | `granularity` | string | `day` | `day`=按天 / `hour`=按小时(聚合键再加北京时间小时 0–23);**区间>1 天建议用 day** |
-  | `limit` | int(1~1000) | 500 | **展示**明细组数(截断;`total`/`total_*`/`daily` 按全量统计不受影响) |
+  | `limit` | int(1~1000) | 500 | **每页条数**(分页大小);`total`/`total_*`/`daily`/`hourly` 按全量统计不受分页影响 |
+  | `offset` | int(≥0) | 0 | 分页偏移(已跳过条数)=(页码−1)×`limit` |
+  | `sort` | string | `time` | 明细排序:`time`=按时间倒序(新→旧) / `ecpm`=按 eCPM 数值倒序 |
 
   约束:`date_to` 不早于 `date_from`、区间最长 **92 天**、日期须 `YYYY-MM-DD`,否则 `422`。
 
@@ -36,25 +39,48 @@
   | 字段 | 类型 | 说明 |
   |---|---|---|
   | `date_from` / `date_to` | string | 报表起止日期(闭区间) |
-  | `daily` | `AdRevenueDaily[]` | 按日期汇总序列(全量,供按天趋势图;不受 `limit` 影响) |
-  | `total` | int | 聚合组**总数**(全量,不受 `limit` 影响) |
-  | `truncated` | bool | 明细是否被 `limit` 截断 |
+  | `daily` | `AdRevenueDaily[]` | 按日期汇总序列(全量,供按天趋势图;不受分页影响) |
+  | `hourly` | `AdRevenueHourly[]` | 按小时汇总序列(全量,供按小时趋势图;**仅 `granularity=hour` 时非空**;不受分页影响) |
+  | `type_stats` | `{[ad_type]: AdRevenueTypeStat}` | 按广告类型(`ad_type`)小计(全量);前端取 `draw` / `reward_video` 做分类大盘 |
+  | `dau` | int \| null | 今日活跃用户数(复用大盘口径 `last_login_at`,今日登录过);**仅查询=今日单天时有值**,历史/多天为 `null` |
+  | `total` | int | 当前筛选下的**分页总条数**(全量,不受分页影响;= 前端分页器 total) |
+  | `truncated` | bool | 当前页之后是否还有更多事件(`len(events) > offset + limit`) |
   | `total_impressions` | int | 全量展示条数合计 |
-  | `total_revenue_yuan` | float | 全量收益合计(元) |
+  | `total_revenue_yuan` | float | 全量**客户端预估**收益合计(元;eCPM 折算) |
+  | `total_pangle_revenue_yuan` | float \| null | 全量**穿山甲后台预估**收益合计(元;GroMore `revenue`)。穿山甲无用户/类型/场景维度,**仅全量视图**(未按 `user_id`/`ad_type`/`feed_scene` 过滤)有值,否则 `null` |
+  | `total_pangle_api_revenue_yuan` | float \| null | 全量**穿山甲收益Api**合计(元;GroMore `api_revenue`,各 ADN 回传更接近结算);未配 Reporting / 查当天 / 非全量视图为 `null` |
+  | `pangle_revenue_available` | bool | 本次是否带穿山甲后台收益(=全量视图且对应日期已同步到 `ad_pangle_daily_revenue`) |
   | `total_expected_coin` | int | 全量应发金币合计 |
   | `total_actual_coin` | int | 全量实发金币合计 |
   | `mismatch_count` | int | 应发≠实发的组数(=0 说明全部按公式发放) |
-  | `items` | `AdRevenueRow[]` | 聚合明细(按 日期→用户→类型→代码位 排序) |
+  | `items` | `AdRevenueRow[]` | 逐条广告事件(**按时间倒序:新→旧**);`limit`/`offset` 对全量做分页切片,返回当前页 |
 
 ### AdRevenueDaily(`daily[]` — 按天趋势)
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `date` | string | 北京时间 `YYYY-MM-DD` |
 | `impressions` | int | 当天展示条数合计 |
-| `revenue_yuan` | float | 当天预估收益合计(元) |
+| `revenue_yuan` | float | 当天客户端预估收益合计(元;eCPM 折算) |
+| `pangle_revenue_yuan` | float \| null | 当天穿山甲后台预估收益(元;GroMore `revenue`);非全量视图 / 无数据为 `null` |
+| `pangle_api_revenue_yuan` | float \| null | 当天穿山甲收益Api(元;GroMore `api_revenue`);未配 / 当天 / 无数据为 `null` |
 | `expected_coin` | int | 当天应发金币合计 |
 | `actual_coin` | int | 当天实发金币合计 |
 
+### AdRevenueHourly(`hourly[]` — 按小时趋势,仅 `granularity=hour` 时非空)
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `hour` | int | 北京时间小时 0–23 |
+| `impressions` | int | 该小时展示条数合计 |
+| `revenue_yuan` | float | 该小时预估收益合计(元) |
+| `expected_coin` | int | 该小时应发金币合计 |
+| `actual_coin` | int | 该小时实发金币合计 |
+
+### AdRevenueTypeStat(`type_stats[ad_type]` — 分广告类型小计,供大盘第二行)
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `impressions` | int | 该类型展示条数合计 |
+| `revenue_yuan` | float | 该类型预估收益合计(元);eCPM 由前端用 收益÷展示×1000 算 |
+
 ### AdRevenueRow(`items[]`)
 | 字段 | 类型 | 说明 |
 |---|---|---|
@@ -104,5 +130,6 @@
 - **展示 vs 发奖分离**:信息流轮播一会话可展示多条(都计入 `impressions`),但发奖仍按现规则(一会话发一次),`coin` 不因展示条数变化——这是有意设计(用户中途关只记展示不发奖)。
 - **历史 Draw 不可拆**:迁移(Draw→普通信息流)前,Draw 发奖混在 `ad_feed_reward_record` 且无类型标记,金币侧统一记 `feed`;迁移后 Draw 不再产生新数据。展示侧 `ad_type` 由客户端上报区分,故 `draw` 桶基本为空。
 - **来源字段从上线起齐全**:`app_env`/`our_code_id` 是本期新增列,历史记录为 NULL(报表来源列留空)。
-- **收益是预估**:基于客户端上报的 eCPM,非穿山甲后台结算值;以后台报表为结算权威。
+- **逐条/明细的收益是预估**:`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_*`。
 - **对账聚合级 + 逐条下钻**:行级 `matched` 给出该组(用户×类型×应用×代码位)应发是否==实发;**展开 `records` 即可看该组逐条明细**(eCPM/因子1/份数/LT/因子2/应发/实发/一致)定位到具体记录。独立逐条审计接口 [admin-ad-coin-audit](./admin-ad-coin-audit.md) 仍保留(同一复算口径,可全局按场景/只看不符筛选)。

docs/database/ad_pangle_daily_revenue.md

@@ -0,0 +1,45 @@
+# ad_pangle_daily_revenue — 穿山甲 GroMore 天级收益
+
+> 模型:[app/models/ad_pangle_revenue.py](../../app/models/ad_pangle_revenue.py) | 读写:[app/repositories/ad_pangle_revenue.py](../../app/repositories/ad_pangle_revenue.py) | 拉取:[app/integrations/pangle_report.py](../../app/integrations/pangle_report.py) + [scripts/sync_pangle_revenue.py](../../scripts/sync_pangle_revenue.py)
+
+存放从穿山甲 **GroMore 数据 API**(聚合数据报告 API,天级、T+1)按天拉取的收益,供 admin
+[广告收益报表](../api/admin-ad-revenue-report.md) 的「穿山甲后台收益」做汇总/趋势级展示,
+与客户端自报 eCPM 折算的预估互为对照(看 gap)。
+
+**粒度 = 日期 × 应用(app_env) × 代码位(our_code_id) × 广告源(adn)**。穿山甲**不提供分用户/设备维度**
+(官方明确),故本表无 `user_id`,也无法挂到逐条广告事件;报表逐条行仍用客户端预估。
+
+## 数据流
+
+- **写**:`scripts/sync_pangle_revenue`(线上每天 ~10:30 由 systemd timer 跑)调
+  `pangle_report.fetch_daily_report` 拉昨天(可 `--days N` 回补),维度 `date,site_id,ad_unit_id`,
+  映射 `site_id→app_env`、`ad_unit_id→our_code_id` 后 `upsert_daily_rows` 落库。按唯一键幂等,T+1 订正可重跑。
+  ⚠️ 用 `ad_unit_id`(广告位ID=104xxx)而非 `code_id`:实测 `code_id` 返回底层各 ADN 代码位(如 `983674557`),对不上我们的口径。
+- **读**:`ad_pangle_revenue.aggregate_by_date` 按日期汇总 → admin 报表
+  `total_pangle_revenue_yuan` / `total_pangle_api_revenue_yuan` / `daily[].pangle_*`。
+
+## 字段
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| `id` | int PK | |
+| `report_date` | str(10) idx | 北京时间 `YYYY-MM-DD`(拉取 `time_zone=8`),与 `ad_ecpm_record.report_date` 同口径可 join |
+| `app_env` | str(16) | `prod`(傻瓜比价正式)/ `test`(测试);由 `site_id` 经 `settings.pangle_report_site_id_to_env` 映射;未映射记 `site:<id>` |
+| `site_id` | str(32) \| null | 原始 GroMore AppId(留痕) |
+| `our_code_id` | str(64) idx | 广告位 ID(= 接口 `ad_unit_id` = 客户端配的 104xxx = `ad_ecpm_record.our_code_id`),join key。⚠️ **非** `code_id`(那是底层各 ADN 代码位,对不上);`-1` 为 GroMore 未归因桶 |
+| `adn` | str(16) | 广告源(接口 `network`);当前默认口径不分广告源(按 `ad_unit_id` 汇总),统一 `""` |
+| `revenue_yuan` | float | 预估收益(元)← 接口 `revenue`(排序价×展示/1000,所有 ADN) |
+| `api_revenue_yuan` | float \| null | 收益Api(元)← 接口 `api_revenue`(各 ADN 经 Reporting 回传、更接近结算);未配 / 当天为 `null` |
+| `ecpm` | str(32) \| null | 预估 eCPM 原值(接口 `ecpm`,单位**元/千次**,与客户端 getEcpm 的「分」不同) |
+| `impressions` | int | 展示次数 ← 接口 `imp_cnt` |
+| `currency` | str(8) | 货币(接口 `currency`,正常 `cny`) |
+| `synced_at` | datetime | 最近同步写入时间(可被回补覆盖) |
+
+唯一约束 `uq_ad_pangle_daily (report_date, app_env, our_code_id, adn)`;`adn` 用 `""` 而非
+NULL,避免 NULL 在唯一约束里互不相同导致 upsert 重复。
+
+## 局限
+
+- **T+1**:当天数据穿山甲不出 `api_revenue`,`revenue` 也次日才稳;报表「今天」此两列多为空。
+- **`revenue` vs `api_revenue`**:前者所有 ADN 都有(预估口径);后者需后台为该 ADN 配置 Reporting
+  才回传,部分 ADN 可能长期为空。结算仍以各 ADN 结算单 / 穿山甲后台为准。

docs/guides/邀请功能-实现原理与本地测试.md

@@ -37,7 +37,7 @@ B 安装并首启 App
         └─ POST /api/v1/invite/bind { invite_code, channel="clipboard" }
         ↓
 后端 repositories/invite.py bind()
-  └─ 过四道防线 → 建 invite_relation + 给 A、B 各发金币(同事务原子提交)
+  └─ 过四道防线 → 建 invite_relation(邀请金币已下线,不写金币流水)
 ```
 
 手动填码这条:B 在邀请页输码 → `InviteRepository.bindManual()` → `POST /bind { channel="manual" }` → 同一个 `bind()`。
@@ -52,20 +52,20 @@ B 安装并首启 App
 |---|---|
 | 端点 | `app/api/v1/invite.py`:`GET /api/v1/invite/me`(返回 `invite_code` + `share_url` + 战绩)、`POST /api/v1/invite/bind`(绑定,`channel` = `clipboard` / `manual`)。**均需 Bearer 鉴权**。 |
 | share_url 构造 | `invite.py` 的 `my_invite`:`settings.INVITE_LANDING_URL + "?ref=" + code`。`INVITE_LANDING_URL` 在 `app/core/config.py`(默认 `https://app-api.shaguabijia.com/media/dl.html`)。 |
-| 业务逻辑 | `app/repositories/invite.py`:`ensure_code`(懒生成 6 位邀请码,去混淆字符集,唯一约束碰撞则换码)/ `resolve_inviter`(邀请码→邀请人,大小写不敏感)/ `bind`(下面详述)/ `get_stats`(已邀人数 + 累计金币)。 |
+| 业务逻辑 | `app/repositories/invite.py`:`ensure_code`(懒生成 6 位邀请码,去混淆字符集,唯一约束碰撞则换码)/ `resolve_inviter`(邀请码→邀请人,大小写不敏感)/ `bind`(下面详述)/ `get_stats`(已邀人数 + 兼容累计金币字段,当前恒为 0)。 |
 | 数据模型 | `app/models/invite.py` 的 `InviteRelation`(`inviter_user_id` / `invitee_user_id` / `channel` / `status` / `inviter_coin` / `invitee_coin` / `created_at`)+ `app/models/user.py` 的 `User.invite_code` 列。 |
 | 迁移 | `alembic/versions/invite_code_and_relation.py`:给 `user` 加 `invite_code`(唯一索引)+ 建 `invite_relation` 表。`down_revision = 11a1d08c6f55`。 |
 | 收发模型 | `app/schemas/invite.py`:`InviteInfoOut` / `BindInviteIn` / `BindInviteOut`。 |
-| 奖励常量 | `app/core/rewards.py`:`INVITE_INVITER_COINS` / `INVITE_INVITEE_COINS`(各 10000 = 1 元)、`INVITE_NEW_USER_WINDOW_HOURS`(72)。 |
+| 新人窗口 | `app/core/rewards.py`:`INVITE_NEW_USER_WINDOW_HOURS`(72)。邀请金币已下线,不再配置邀请金币常量。 |
 
 **`bind()` 的四道防线(防重复 / 防刷,看 `repositories/invite.py`):**
 
-1. **被邀请人唯一**:`invitee_user_id` 唯一约束 → 一个 B 只能被绑一次(幂等键,重复返回 `already_bound`,不重复发奖)。
+1. **被邀请人唯一**:`invitee_user_id` 唯一约束 → 一个 B 只能被绑一次(幂等键,重复返回 `already_bound`,不重复绑定)。
 2. **自邀屏蔽**:`inviter == invitee` → `self_invite`。
-3. **新人闸**:`_is_new_user`(B 的 `created_at` 在 `INVITE_NEW_USER_WINDOW_HOURS` = 72h 内)才发奖,挡存量老用户互相填码薅羊毛 → 否则 `not_eligible`。
+3. **新人闸**:`_is_new_user`(B 的 `created_at` 在 `INVITE_NEW_USER_WINDOW_HOURS` = 72h 内)才生效,挡存量老用户互相填码刷关系 → 否则 `not_eligible`。
 4. **手机号唯一**(天然限量):每个 B = 一个真实手机号账号。
 
-发金币复用 `repositories/wallet.py` 的 `grant_coins`,与建关系记录在**同一事务**提交,保证"建关系 + 双方加金币"原子。
+邀请金币已下线:`bind()` 只记录绑定关系,不再写 `coin_transaction`;响应里的金币字段保留兼容旧客户端,当前恒为 0。
 
 ### 3.2 前端(shaguabijia-app-android)
 
@@ -120,7 +120,7 @@ B 安装并首启 App
 ### 4.4 测试硬约束 / 坑(都是机制,不是 bug)
 
 - **B 必须用新手机号**:`invitee_user_id` 唯一,一个 B 只能绑一次;反复测要换号(或手删 `invite_relation` 那行 + 回滚金币)。
-- **72h 新人闸**:B 注册后 72 小时内绑才发奖(刚注册肯定满足)。
+- **72h 新人闸**:B 注册后 72 小时内绑定才生效(刚注册肯定满足)。
 - **A ≠ B**:自邀被屏蔽。
 - **B 从点下载到首启 App 之间别复制别的东西**:剪贴板会被覆盖 → 归因丢(剪贴板 deferred deeplink 的固有脆弱性)。
 - **笔记本 IP 别变**:debug 包把 `BASE_URL` 的 IP 烧死在编译期,DHCP 一换就连不上 → 给笔记本固定个 LAN IP。

h5/shared/api.js

@@ -0,0 +1,52 @@
+/**
+ * SGApi —— H5 调 app-server 后端的薄封装。
+ *
+ * 同源：H5 由 app-server 的 /media/h5/ 托管，后端在 /api/v1，同 host:port → 用相对路径、无 CORS。
+ * 鉴权：JWT Bearer。token 经 SGBridge.getToken() 从原生取(原生持登录态)；浏览器调试走 bridge 的 mock token。
+ * 401：交原生拉登录(requestLogin)兜底，本次请求按失败 reject；正式的 refresh 重试策略阶段2 再补。
+ *
+ * 依赖 shared/bridge.js 先加载(取 token)。
+ */
+(function (global) {
+  'use strict';
+
+  var BASE = '/api/v1';
+
+  function authHeaders() {
+    var t = (global.SGBridge && global.SGBridge.getToken()) || '';
+    var h = { 'Content-Type': 'application/json' };
+    if (t) h['Authorization'] = 'Bearer ' + t;
+    return h;
+  }
+
+  function handle(res) {
+    if (res.status === 401) {
+      // 未授权：拉原生登录(异步)，本次请求按失败处理，调用方自行决定是否重试
+      if (global.SGBridge) global.SGBridge.requestLogin();
+      return Promise.reject(new Error('unauthorized'));
+    }
+    if (!res.ok) {
+      return res.text().then(function (t) {
+        return Promise.reject(new Error('http ' + res.status + ' ' + t));
+      });
+    }
+    // 204 / 空体兜底
+    return res.text().then(function (t) { return t ? JSON.parse(t) : null; });
+  }
+
+  /** GET /api/v1<path>。path 以 / 开头，如 '/savings/battle'。 */
+  function apiGet(path) {
+    return fetch(BASE + path, { method: 'GET', headers: authHeaders() }).then(handle);
+  }
+
+  /** POST /api/v1<path>，body 自动 JSON 序列化。 */
+  function apiPost(path, body) {
+    return fetch(BASE + path, {
+      method: 'POST',
+      headers: authHeaders(),
+      body: JSON.stringify(body || {}),
+    }).then(handle);
+  }
+
+  global.SGApi = { base: BASE, get: apiGet, post: apiPost };
+})(window);

h5/shared/bridge.js

@@ -0,0 +1,162 @@
+/**
+ * SGBridge —— 傻瓜比价 H5 ↔ Android 原生 的桥。
+ *
+ * 背景：四个主 tab(首页/福利/记录/我的)由原生 Compose 改造为 WebView 加载本工程 H5。
+ * H5 只负责"画 + 取后端数据"；凡需要原生能力(登录态 / 跳转 / 跳外卖 App / 比价领券 /
+ * 权限 / 定位 / Toast / 激励视频)，一律经本桥调用原生。
+ *
+ * 协议两个方向：
+ *  ① H5 → 原生：Android 端 WebView.addJavascriptInterface(obj, "SGBridgeNative")。
+ *     obj 方法都是【同步】：查询类返回 String(JSON 或纯串)，动作类无返回。
+ *  ② 原生 → H5：原生执行 evaluateJavascript("window.SGBridge._emit('<event>', '<json>')")。
+ *     事件：onAuthChange(登录态变) / onBalanceChange(余额变) / onSigninChange(签到态变) / onResume(回前台刷新)。
+ *
+ * 离线兜底：浏览器里(无 SGBridgeNative)走 MOCK，便于不装 App 直接在本地 server 调样式 / 渲染。
+ * 与原生实现对应：见 shaguabijia-app-android 的 SGBridge.kt(方法名逐个对齐本文件)。
+ */
+(function (global) {
+  'use strict';
+
+  var native = global.SGBridgeNative || null;
+  var hasNative = !!native;
+
+  // ---- 离线 MOCK(仅无原生时生效，便于浏览器调试渲染；真机一律走 native) ----
+  var MOCK = {
+    authState: { loggedIn: true, userId: 1, nickname: '冰', avatarUrl: '', phone: '188****8888' },
+    token: 'mock-token-for-browser-debug',
+    deviceId: 'browser-debug-device',
+    appVersion: '0.0.0-debug',
+  };
+
+  function safeParse(s, fallback) {
+    try { return s ? JSON.parse(s) : fallback; } catch (e) { return fallback; }
+  }
+
+  // ====== 查询类(同步返回) ======
+
+  /** 当前登录态 + 用户基本信息 → {loggedIn, userId, nickname, avatarUrl, phone}。 */
+  function getAuthState() {
+    if (hasNative && native.getAuthState) return safeParse(native.getAuthState(), { loggedIn: false });
+    return MOCK.authState;
+  }
+
+  /** 后端鉴权用的 access token(空串=未登录)。原生持登录态，H5 调后端前取它拼 Bearer。 */
+  function getToken() {
+    if (hasNative && native.getToken) return native.getToken() || '';
+    return MOCK.token;
+  }
+
+  /** 设备唯一标识(心跳 / 领券状态查询等用)。 */
+  function getDeviceId() {
+    if (hasNative && native.getDeviceId) return native.getDeviceId() || '';
+    return MOCK.deviceId;
+  }
+
+  /** App 版本号。 */
+  function getAppVersion() {
+    if (hasNative && native.getAppVersion) return native.getAppVersion() || '';
+    return MOCK.appVersion;
+  }
+
+  /** 已安装的目标电商/外卖 App 包名数组(原生 InstalledApps 探测)。H5 选平台弹窗据此判真实装机态。 */
+  function getInstalledApps() {
+    if (hasNative && native.getInstalledApps) return safeParse(native.getInstalledApps(), []);
+    // MOCK(浏览器无原生):给主流已装,便于本地预览选平台弹窗正常显示"有"。
+    return ['com.sankuai.meituan', 'com.taobao.taobao', 'com.jingdong.app.mall', 'me.ele'];
+  }
+
+  /** 今日是否已领券(置灰「去领取」→「去查看」)。原生读 CompareButtonState(SP 按天);无桥默认 false。 */
+  function getCouponClaimedToday() {
+    if (hasNative && native.getCouponClaimedToday) return !!native.getCouponClaimedToday();
+    return false;
+  }
+
+  // ====== 动作类(无返回；异步结果走事件) ======
+
+  /** 跳原生页。route 取值对齐安卓 Routes(invite / settings / feedback / withdrawal / compareRecords / reportFlow / guideVideo / compareResult / coinHistory / cashHistory / welfareRules ...)。 */
+  function navigate(route) {
+    if (hasNative && native.navigate) native.navigate(route);
+    else console.log('[SGBridge mock] navigate →', route);
+  }
+
+  /** 拉起极光一键登录。结果异步经 onAuthChange 事件回来(不在此函数返回)。 */
+  function requestLogin() {
+    if (hasNative && native.requestLogin) native.requestLogin();
+    else console.log('[SGBridge mock] requestLogin');
+  }
+
+  /** 原生居中 Toast。 */
+  function toast(msg) {
+    if (hasNative && native.toast) native.toast(String(msg));
+    else console.log('[SGBridge mock] toast →', msg);
+  }
+
+  /** 跳美团/外卖 App(deeplink 优先；空则原生按包名启动，未装可跳应用商店)。 */
+  function openMeituan(deeplink) {
+    if (hasNative && native.openMeituan) native.openMeituan(deeplink || '');
+    else console.log('[SGBridge mock] openMeituan →', deeplink);
+  }
+
+  /** 触发 agent 比价流程(原生起无障碍引擎)。 */
+  function startCompare() {
+    if (hasNative && native.startCompare) native.startCompare();
+    else console.log('[SGBridge mock] startCompare');
+  }
+
+  /** 触发一键领券(原生先校验悬浮窗/无障碍权限，再起前台服务)。platforms: string[]。 */
+  function startCouponClaim(platforms) {
+    var json = JSON.stringify(platforms || []);
+    if (hasNative && native.startCouponClaim) native.startCouponClaim(json);
+    else console.log('[SGBridge mock] startCouponClaim →', json);
+  }
+
+  /** 按候选包名拉起对应平台 App。照原生 HomePicker 点击跳转:原生在该平台一组候选包里取首个可
+   *  getLaunchIntentForPackage 的拉起(NEW_TASK|CLEAR_TASK 冷启到平台首页)。packages: string[](一个平台一组候选包,任一可拉即拉)。 */
+  function launchApp(packages) {
+    var json = JSON.stringify(packages || []);
+    if (hasNative && native.launchApp) native.launchApp(json);
+    else console.log('[SGBridge mock] launchApp →', json);
+  }
+
+  // ====== 原生 → H5 事件总线 ======
+
+  var listeners = {}; // event → [fn]
+
+  /** 订阅原生事件。返回取消订阅函数。 */
+  function on(event, fn) {
+    (listeners[event] || (listeners[event] = [])).push(fn);
+    return function off() {
+      listeners[event] = (listeners[event] || []).filter(function (f) { return f !== fn; });
+    };
+  }
+
+  /** 供原生回调：window.SGBridge._emit('onAuthChange', '{...}')。payload 可为 JSON 串或对象。 */
+  function _emit(event, payload) {
+    var data = typeof payload === 'string' ? safeParse(payload, payload) : payload;
+    (listeners[event] || []).forEach(function (fn) {
+      try { fn(data); } catch (e) { console.error('[SGBridge] listener error', event, e); }
+    });
+  }
+
+  global.SGBridge = {
+    hasNative: hasNative,
+    // 查询
+    getAuthState: getAuthState,
+    getToken: getToken,
+    getDeviceId: getDeviceId,
+    getAppVersion: getAppVersion,
+    getInstalledApps: getInstalledApps,
+    getCouponClaimedToday: getCouponClaimedToday,
+    // 动作
+    navigate: navigate,
+    requestLogin: requestLogin,
+    toast: toast,
+    openMeituan: openMeituan,
+    startCompare: startCompare,
+    startCouponClaim: startCouponClaim,
+    launchApp: launchApp,
+    // 事件
+    on: on,
+    _emit: _emit,
+  };
+})(window);

scripts/sim_pangle_callback.py

@@ -12,6 +12,7 @@ FastAPI TestClient 在进程内打**真实** endpoint(`/api/v1/ad/pangle-callbac
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import sys
 import uuid
@@ -56,6 +57,11 @@ def main() -> None:
     p = argparse.ArgumentParser(description="模拟穿山甲发奖回调")
     p.add_argument("user_id", nargs="?", type=int, default=None, help="目标 user_id(默认最近注册)")
     p.add_argument("--trans", default=None, help="交易号(默认随机);同号重跑验幂等")
+    p.add_argument(
+        "--srv-env", default=None,
+        help="模拟客户端 mediaExtra 里的后端环境标记(dev/prod)。与本服 APP_ENV 不符时"
+             "应被环境隔离拦下(Δ0、不串号);留空=不带该字段(旧客户端,照常发)",
+    )
     args = p.parse_args()
 
     if not settings.pangle_callback_configured:
@@ -75,6 +81,9 @@ def main() -> None:
         # 镜像生产:后台代码位"奖励数量"应配成 AD_REWARD_COIN,回调据此发金币
         "reward_amount": str(AD_REWARD_COIN),
     }
+    # 镜像穿山甲透传 mediaExtra:把后端环境标记放进 gromoreExtra(服务端据此做环境隔离)
+    if args.srv_env:
+        params["gromoreExtra"] = json.dumps({"srv_env": args.srv_env})
     params["sign"] = pangle.build_sign(trans_id, settings.PANGLE_REWARD_SECRET)
 
     resp = TestClient(app).get("/api/v1/ad/pangle-callback", params=params)

scripts/sync_pangle_revenue.py

@@ -0,0 +1,151 @@
+"""每日拉取穿山甲 GroMore 天级收益报表入库(供 admin 广告收益报表的「穿山甲后台收益」)。
+
+GroMore 数据 API 为 T+1:次日穿山甲约 10:00 出数。建议线上每天 ~10:30 由 systemd timer 跑一次
+(默认拉【昨天】);穿山甲对历史数据可能订正,故支持回补近 N 天(幂等 upsert,重跑无害)。
+
+用法:
+    python -m scripts.sync_pangle_revenue                 # 拉昨天(北京时间)
+    python -m scripts.sync_pangle_revenue --days 3        # 回补昨天起往前 3 天
+    python -m scripts.sync_pangle_revenue --date 2026-06-27           # 指定单天
+    python -m scripts.sync_pangle_revenue --start 2026-06-01 --end 2026-06-27  # 指定区间
+
+约束(来自官方文档):天级跨度 ≤ 1 个月、不早于 12 个月;「今天」与「今天以前」必须分开查,
+本脚本默认只拉昨天及更早,不混查今天。未配置 PANGLE_REPORT_* 时直接 no-op 退出。
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import date, timedelta
+
+# Windows 控制台按 UTF-8 输出中文/¥
+try:
+    sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+except Exception:  # noqa: BLE001
+    pass
+
+from app.core.config import settings
+from app.core.rewards import cn_today
+from app.db.session import SessionLocal
+from app.integrations import pangle_report
+from app.integrations.pangle_report import PangleReportError
+from app.repositories import ad_pangle_revenue as repo
+
+# 拉取维度固定:date×site_id×ad_unit_id。⚠️ 用 ad_unit_id(GroMore 广告位ID = 我们客户端配的 104xxx
+# = ad_ecpm_record.our_code_id)而**非** code_id —— 实测 code_id 返回的是底层各 ADN 的代码位
+# (如 983674557 / youlianghui_xinxiliu),对不上我们的口径。指标取预估 + Api 两个收益。
+_DIMENSIONS = "date,site_id,ad_unit_id"
+_METRICS = "revenue,api_revenue,ecpm,imp_cnt"
+
+
+def _to_float(v: object) -> float | None:
+    """接口数值字段都是字符串;空/非法 → None(api_revenue 缺失时即为 None,前端显示「-」)。"""
+    if v is None or str(v).strip() == "":
+        return None
+    try:
+        return float(str(v).strip())
+    except (TypeError, ValueError):
+        return None
+
+
+def _row_date(row: dict) -> str | None:
+    """报表行的日期:优先 date 维度,回退 start_date;取前 10 位 'YYYY-MM-DD'。"""
+    raw = row.get("date") or row.get("start_date") or ""
+    raw = str(raw).strip()
+    return raw[:10] if len(raw) >= 10 else None
+
+
+def _normalize(rows: list[dict]) -> tuple[list[dict], int, set[str]]:
+    """接口原始行 → 入库行;返回 (入库行, 跳过数, 未映射 site_id 集合)。
+
+    site_id 经 settings 映射成 app_env(prod/test);未映射的仍入库(app_env=site:<id>)但提示,
+    避免静默丢收益。缺 code_id / 日期的行跳过。
+    """
+    site_map = settings.pangle_report_site_id_to_env
+    out: list[dict] = []
+    skipped = 0
+    unmapped: set[str] = set()
+    for row in rows:
+        rdate = _row_date(row)
+        # 用 ad_unit_id(GroMore 广告位ID = 我们的 104xxx),不是 code_id(底层 ADN 代码位)
+        code_id = str(row.get("ad_unit_id") or "").strip()
+        if not rdate or not code_id:
+            skipped += 1
+            continue
+        site_id = str(row.get("site_id") or "").strip()
+        app_env = site_map.get(site_id)
+        if app_env is None:
+            app_env = f"site:{site_id}" if site_id else "unknown"
+            if site_id:
+                unmapped.add(site_id)
+        out.append({
+            "report_date": rdate,
+            "app_env": app_env,
+            "site_id": site_id or None,
+            "our_code_id": code_id,
+            "adn": "",
+            "revenue_yuan": _to_float(row.get("revenue")) or 0.0,
+            "api_revenue_yuan": _to_float(row.get("api_revenue")),
+            "ecpm": (str(row.get("ecpm")).strip() or None) if row.get("ecpm") is not None else None,
+            "impressions": int(_to_float(row.get("imp_cnt")) or 0),
+            "currency": "cny",
+        })
+    return out, skipped, unmapped
+
+
+def sync_range(start_date: str, end_date: str) -> None:
+    if not settings.pangle_report_configured:
+        print("PANGLE_REPORT_* 未配置,跳过(no-op)。需在后台「接入中心 → GroMore-API」领取 "
+              "user_id/role_id/Security Key 并填入 .env。")
+        return
+
+    print(f"拉取 GroMore 天级收益 {start_date} ~ {end_date} (dims={_DIMENSIONS}) ...")
+    try:
+        raw = pangle_report.fetch_daily_report(
+            start_date=start_date, end_date=end_date,
+            dimensions=_DIMENSIONS, metrics=_METRICS, time_zone=8,
+        )
+    except PangleReportError as e:
+        print(f"❌ 拉取失败:{e}")
+        sys.exit(1)
+
+    rows, skipped, unmapped = _normalize(raw)
+    if unmapped:
+        print(f"⚠️ 有未映射 site_id(收益仍入库,app_env=site:<id>):{sorted(unmapped)};"
+              f"如需归入 prod/test,补 PANGLE_REPORT_SITE_ID_* 配置。")
+    with SessionLocal() as db:
+        stats = repo.upsert_daily_rows(db, rows)
+    total_rev = round(sum(r["revenue_yuan"] for r in rows), 4)
+    print(f"✅ 完成:接口 {len(raw)} 行 → 入库 {len(rows)} 行(跳过 {skipped}),"
+          f"新增 {stats['inserted']} / 更新 {stats['updated']};预估收益合计 ¥{total_rev}")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="拉取穿山甲 GroMore 天级收益报表入库")
+    ap.add_argument("--date", help="指定单天 YYYY-MM-DD")
+    ap.add_argument("--start", help="区间起始 YYYY-MM-DD(与 --end 同用)")
+    ap.add_argument("--end", help="区间结束 YYYY-MM-DD(与 --start 同用)")
+    ap.add_argument("--days", type=int, help="回补:昨天起往前 N 天(含昨天)")
+    args = ap.parse_args()
+
+    yesterday = cn_today() - timedelta(days=1)
+    if args.date:
+        start = end = args.date
+    elif args.start and args.end:
+        start, end = args.start, args.end
+    elif args.days:
+        start = (yesterday - timedelta(days=args.days - 1)).isoformat()
+        end = yesterday.isoformat()
+    else:
+        start = end = yesterday.isoformat()
+
+    # 防呆:跨度 > 31 天直接拒(接口上限 1 个月,超了会返回 114)
+    if (date.fromisoformat(end) - date.fromisoformat(start)).days > 31:
+        print("❌ 区间跨度超过 31 天(接口上限 1 个月),请分批拉。")
+        sys.exit(1)
+
+    sync_range(start, end)
+
+
+if __name__ == "__main__":
+    main()

tests/test_ad_reward.py

@@ -5,6 +5,8 @@
 """
 from __future__ import annotations
 
+import json
+
 from sqlalchemy import select
 
 from app.core.config import settings
@@ -179,6 +181,38 @@ def test_callback_unknown_user(client) -> None:
     assert r.json() == {"is_verify": False, "reason": 2}
 
 
+def test_callback_foreign_env_skipped(client) -> None:
+    """回调 srv_env 与本服 APP_ENV 不符(测试包的 S2S 打到生产)→ 受理但不发币、不串号。
+
+    防的是跨库串号:同一 user_id 在测试库 / 正式库是两个人,回调地址只配生产,测试包(dev)看广告
+    的 S2S 也会打到生产。测试环境 APP_ENV=dev:srv_env=prod 视为「别的环境」→ 跳过,余额不变、
+    不写记录;srv_env=dev(本环境)照常发。srv_env 走 gromoreExtra 透传(穿山甲带回 mediaExtra 的字段)。
+    兼容:不带 srv_env 的旧客户端按本环境处理(其余用例已覆盖)。
+    """
+    phone = "13800003501"
+    token = _login(client, phone)
+    uid = _user_id(phone)
+
+    # 外环境(prod)回调:受理(is_verify=true 防穿山甲重试)但不发币、不留记录
+    foreign = _signed(uid, "trans_foreign_env", ecpm="200",
+                      gromoreExtra=json.dumps({"srv_env": "prod"}))
+    r = _callback(client, foreign)
+    assert r.status_code == 200, r.text
+    assert r.json() == {"is_verify": True, "reason": 0}
+    assert _coin_balance(client, token) == 0
+    st = client.get("/api/v1/ad/reward-status", headers=_auth(token)).json()
+    assert st["used_today"] == 0
+
+    # 本环境(dev)回调:照常发币
+    same = _signed(uid, "trans_same_env", ecpm="200",
+                   gromoreExtra=json.dumps({"srv_env": "dev"}))
+    r = _callback(client, same)
+    assert r.status_code == 200, r.text
+    assert _coin_balance(client, token) == calculate_ad_reward_coin("200", 1)
+    st = client.get("/api/v1/ad/reward-status", headers=_auth(token)).json()
+    assert st["used_today"] == 1
+
+
 def test_reward_status_requires_auth(client) -> None:
     """客户端进度接口需登录。"""
     r = client.get("/api/v1/ad/reward-status")
@@ -271,11 +305,12 @@ def test_feed_reward_grants_by_10_second_units(client) -> None:
         "duration_seconds": 30,
         "adn": "pangle",
         "slot_id": "slot_feed",
+        "display_coin": 4,
     }
     r = client.post("/api/v1/ad/feed-reward", json=payload, headers=_auth(token))
     assert r.status_code == 200, r.text
     body = r.json()
-    expected = sum(calculate_ad_reward_coin("200", i) for i in range(1, 4))
+    expected = 4
     assert body["granted"] is True
     assert body["status"] == "granted"
     assert body["unit_count"] == 3

tests/test_admin_read.py

@@ -64,7 +64,8 @@ def test_dashboard_overview(admin_client: TestClient, admin_token: str) -> None:
     assert data["users"]["total"] >= 1
     assert data["coins"]["granted_total"] >= 5000
     assert "success_rate" in data["comparison"]
-    assert data["cps"]["available"] is False
+    assert data["cps"]["available"] is True
+    assert "meituan_order_count" in data["cps"]
 
 
 def test_user_list_and_detail(admin_client: TestClient, admin_token: str) -> None:

tests/test_auth.py

@@ -74,6 +74,73 @@ def test_sms_send_too_frequent(client) -> None:
     assert client.post("/api/v1/auth/sms/send", json={"phone": phone}).status_code == 429
 
 
+def test_sms_send_device_ip_rate_limit(client, monkeypatch) -> None:
+    """发码防刷:同一设备(device_id) + 同一 IP 每小时最多 N 次发码,超出 429。
+    用不同手机号(绕开单号 60s 冷却)证明限流按设备封顶 —— 堵「换号绕开单号冷却/每日上限」的洞。
+    conftest 默认关限流;本用例临时打开 + 调小阈值便于测 + 清计数隔离。"""
+    from app.api.v1 import auth
+    from app.core import ratelimit
+
+    monkeypatch.setattr(ratelimit.settings, "RATE_LIMIT_ENABLED", True)
+    monkeypatch.setattr(auth, "SMS_SEND_MAX_PER_HOUR_PER_DEVICE", 3)
+    ratelimit._buckets.clear()
+
+    device = "dev-send-A"
+    # 同设备、每次换不同手机号(绕开单号冷却)发码,前 3 次 200
+    for i in range(3):
+        r = client.post(
+            "/api/v1/auth/sms/send",
+            json={"phone": f"137001370{i:02d}", "device_id": device},
+        )
+        assert r.status_code == 200, f"第 {i + 1} 次应放行: {r.text}"
+    # 第 4 次:同设备超限 → 429(即便又换了手机号)
+    r = client.post(
+        "/api/v1/auth/sms/send",
+        json={"phone": "13700137003", "device_id": device},
+    )
+    assert r.status_code == 429, r.text
+
+    # 换个设备 → 独立计数(限流键含 device_id),放行
+    r = client.post(
+        "/api/v1/auth/sms/send",
+        json={"phone": "13700137004", "device_id": "dev-send-B"},
+    )
+    assert r.status_code == 200, r.text
+
+
+def test_sms_login_device_ip_rate_limit(client, monkeypatch) -> None:
+    """防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_LOGIN_MAX_PER_HOUR 次登录尝试,超出 429。
+    conftest 默认 RATE_LIMIT_ENABLED=false(内存计数跨用例累加),本用例临时打开并清空计数隔离。"""
+    from app.api.v1 import auth
+    from app.core import ratelimit
+
+    monkeypatch.setattr(ratelimit.settings, "RATE_LIMIT_ENABLED", True)
+    ratelimit._buckets.clear()  # 隔离:清掉跨用例累加的内存计数
+
+    device = "dev-rl-A"
+    # 前 N 次故意每次换手机号、固定设备:mock 校验放行 → 200。证明限流按设备而非手机号,同设备共用一个桶
+    for i in range(auth.SMS_LOGIN_MAX_PER_HOUR):
+        r = client.post(
+            "/api/v1/auth/sms/login",
+            json={"phone": f"135331533{i:02d}", "code": "123456", "device_id": device},
+        )
+        assert r.status_code == 200, f"第 {i + 1} 次应放行: {r.text}"
+    # 第 N+1 次:同设备同 IP 超限 → 429(即便又换了个手机号)
+    r = client.post(
+        "/api/v1/auth/sms/login",
+        json={"phone": "13533153399", "code": "123456", "device_id": device},
+    )
+    assert r.status_code == 429, r.text
+    assert "频繁" in r.json()["detail"]
+
+    # 同 IP 换个设备 → 独立计数(限流键含 device_id、非纯 IP/手机号),仍放行
+    r = client.post(
+        "/api/v1/auth/sms/login",
+        json={"phone": "13533153300", "code": "123456", "device_id": "dev-rl-B"},
+    )
+    assert r.status_code == 200, r.text
+
+
 def test_sms_login_bad_code(client) -> None:
     """mock 下校验位数:5 位过 schema 但业务要 6 位 → 400。"""
     phone = "13700137000"

tests/test_compare_record.py

@@ -44,6 +44,7 @@ def _food_payload(trace_id: str) -> dict:
         "skipped_dish_names": ["黑牛肉卷"],
         "total_dish_count": 3,
         "information": "在美团找到同店,到手价 ¥123.50",
+        "total_ms": 12345,
     }
 
 
@@ -71,6 +72,8 @@ def test_report_and_derive(client) -> None:
     assert d["information"] == "在美团找到同店,到手价 ¥123.50"
     assert d["store_name"] == "海底捞(朝阳店)"
     assert d["total_dish_count"] == 3
+    assert d["total_ms"] == 12345
+    assert d["raw_payload"]["total_ms"] == 12345
     assert d["skipped_dish_count"] == 1
     assert d["skipped_dish_names"] == ["黑牛肉卷"]
     assert len(d["comparison_results"]) == 3

tests/test_cps_admin.py

@@ -0,0 +1,182 @@
+"""admin CPS 端点测试:每日明细 date 格式 + 按天按用户领券下钻(/day-users)。"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+import pytest
+from fastapi.testclient import TestClient
+
+from app.admin.main import admin_app
+from app.admin.repositories import admin_user as admin_repo
+from app.admin.repositories import cps as cps_repo
+from app.db.session import SessionLocal
+from app.models.cps_link import CpsClick
+from app.models.cps_wx_user import CpsWxUser
+from app.repositories import cps_link as cps_link_repo
+
+_BJ = timezone(timedelta(hours=8))
+
+
+@pytest.fixture()
+def admin_client() -> TestClient:
+    return TestClient(admin_app)
+
+
+@pytest.fixture()
+def admin_token() -> str:
+    db = SessionLocal()
+    try:
+        if admin_repo.get_by_username(db, "cps_test_admin") is None:
+            admin_repo.create_admin(
+                db, username="cps_test_admin", password="cps-pass", role="super_admin"
+            )
+    finally:
+        db.close()
+    c = TestClient(admin_app)
+    r = c.post("/admin/api/auth/login", json={"username": "cps_test_admin", "password": "cps-pass"})
+    return r.json()["access_token"]
+
+
+def _auth(token: str) -> dict:
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _seed_cps_day(day_bj: date) -> tuple[int, str]:
+    """造淘宝群 + 2 个活动(券) + 2 条 link + day_bj 当天点击(含匿名 + 次日各 1) + 授权画像。
+
+    o_user(本群唯一):券A visit×3、券B visit×2、copy×2 → visit_count=5、copy_count=2。
+    另造 1 条匿名 visit(openid=None)与 1 条次日 visit,均不应计入当天该用户聚合。
+    clicked_at 统一存 tz-aware UTC(SQLite DateTime 按字段渲染、忽略 tzinfo;
+    转 UTC 后字段即 UTC 墙钟,与 repo 侧 _as_utc 比较口径一致)。返回 (group_id, openid)。
+    """
+    db = SessionLocal()
+    try:
+        gid = cps_repo.create_group(db, name="下钻测试群", platforms=["taobao"]).id
+        openid = f"od_user_{gid}"  # 按群唯一,规避 CpsWxUser.openid 唯一约束跨用例冲突
+        a1 = cps_repo.create_activity(db, name="618神券", platform="taobao", payload="tkl-1")
+        a2 = cps_repo.create_activity(db, name="买一送一", platform="taobao", payload="tkl-2")
+        link1 = cps_link_repo.create_link(
+            db, group_id=gid, activity_id=a1.id, sid=None, target_url="t1", platform="taobao"
+        )
+        link2 = cps_link_repo.create_link(
+            db, group_id=gid, activity_id=a2.id, sid=None, target_url="t2", platform="taobao"
+        )
+        db.add(CpsWxUser(openid=openid, nickname="张三", headimgurl="https://h/1"))
+        db.commit()
+
+        def at(hour: int) -> datetime:
+            return datetime(day_bj.year, day_bj.month, day_bj.day, hour, tzinfo=_BJ).astimezone(
+                timezone.utc
+            )
+
+        for _ in range(3):
+            db.add(CpsClick(link_id=link1.id, group_id=gid, sid=None,
+                            event_type="visit", openid=openid, clicked_at=at(10)))
+        for _ in range(2):
+            db.add(CpsClick(link_id=link2.id, group_id=gid, sid=None,
+                            event_type="visit", openid=openid, clicked_at=at(11)))
+        for _ in range(2):
+            db.add(CpsClick(link_id=link1.id, group_id=gid, sid=None,
+                            event_type="copy", openid=openid, clicked_at=at(12)))
+        # 匿名点击 — 不计入
+        db.add(CpsClick(link_id=link1.id, group_id=gid, sid=None,
+                        event_type="visit", openid=None, clicked_at=at(13)))
+        # 次日点击 — 验证时间窗,不计入当天
+        nxt = (datetime(day_bj.year, day_bj.month, day_bj.day, 10, tzinfo=_BJ)
+               + timedelta(days=1)).astimezone(timezone.utc)
+        db.add(CpsClick(link_id=link1.id, group_id=gid, sid=None,
+                        event_type="visit", openid=openid, clicked_at=nxt))
+        db.commit()
+        return gid, openid
+    finally:
+        db.close()
+
+
+def test_daily_date_is_full_iso(admin_client: TestClient, admin_token: str) -> None:
+    """/daily 每行 date 改为 YYYY-MM-DD(10 字符、两个连字符),不再是 MM-DD。"""
+    gid, _ = _seed_cps_day(date(2026, 6, 25))
+    r = admin_client.get(
+        f"/admin/api/cps/groups/{gid}/daily", params={"days": 3}, headers=_auth(admin_token)
+    )
+    assert r.status_code == 200, r.text
+    rows = r.json()["rows"]
+    assert rows, "应有按天补零行"
+    for row in rows:
+        assert len(row["date"]) == 10 and row["date"].count("-") == 2, row["date"]
+
+
+def test_day_users_aggregates(admin_client: TestClient, admin_token: str) -> None:
+    """当天该群:仅授权用户;领券=copy、点击=visit;coupons=visit 券×次数倒序、合计=点击次数。"""
+    gid, openid = _seed_cps_day(date(2026, 6, 25))
+    r = admin_client.get(
+        f"/admin/api/cps/groups/{gid}/day-users",
+        params={"date": "2026-06-25"},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    body = r.json()
+    assert body["group_id"] == gid
+    assert body["date"] == "2026-06-25"
+    users = body["users"]
+    assert len(users) == 1  # 匿名不计、次日不计
+    u = users[0]
+    assert u["openid"] == openid
+    assert u["nickname"] == "张三"
+    assert u["headimgurl"] == "https://h/1"
+    assert u["copy_count"] == 2
+    assert u["visit_count"] == 5
+    assert [c["name"] for c in u["coupons"]] == ["618神券", "买一送一"]
+    assert [c["count"] for c in u["coupons"]] == [3, 2]
+    assert sum(c["count"] for c in u["coupons"]) == u["visit_count"]
+
+
+def test_day_users_group_not_found(admin_client: TestClient, admin_token: str) -> None:
+    r = admin_client.get(
+        "/admin/api/cps/groups/999999/day-users",
+        params={"date": "2026-06-25"},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 404
+
+
+def test_day_users_bad_date(admin_client: TestClient, admin_token: str) -> None:
+    gid, _ = _seed_cps_day(date(2026, 6, 25))
+    r = admin_client.get(
+        f"/admin/api/cps/groups/{gid}/day-users",
+        params={"date": "2026/06/25"},  # 非 YYYY-MM-DD
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 400
+
+
+def test_day_users_requires_auth(admin_client: TestClient) -> None:
+    r = admin_client.get(
+        "/admin/api/cps/groups/1/day-users", params={"date": "2026-06-25"}
+    )
+    assert r.status_code == 401
+
+
+def test_day_users_empty_when_no_clicks(admin_client: TestClient, admin_token: str) -> None:
+    gid, _ = _seed_cps_day(date(2026, 6, 25))
+    r = admin_client.get(
+        f"/admin/api/cps/groups/{gid}/day-users",
+        params={"date": "2026-06-20"},  # 该群当天无任何点击
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200
+    assert r.json()["users"] == []
+
+
+def test_day_users_cross_year(admin_client: TestClient, admin_token: str) -> None:
+    """跨年:YYYY-MM-DD 才能精确定位 12-31(MM-DD 会丢年份);次日(次年 01-01)不计入。"""
+    gid, openid = _seed_cps_day(date(2025, 12, 31))
+    r = admin_client.get(
+        f"/admin/api/cps/groups/{gid}/day-users",
+        params={"date": "2025-12-31"},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    users = r.json()["users"]
+    assert len(users) == 1
+    assert users[0]["openid"] == openid
+    assert users[0]["visit_count"] == 5  # 次年 01-01 那条被时间窗排除

tests/test_invite.py

@@ -1,4 +1,4 @@
-"""好友邀请测试:邀请码、绑定、双方发金币、幂等、自邀/无效码屏蔽、指纹兜底归因。
+"""好友邀请测试:邀请码、绑定(双方不发钱)、幂等、自邀/无效码屏蔽、指纹兜底归因。
 
 用 sms mock 登录拿 token(同 test_welfare),再跑邀请闭环。
 """
@@ -10,8 +10,6 @@ from sqlalchemy import select
 
 from app.core.rewards import (
     INVITE_FP_WINDOW_DAYS,
-    INVITE_INVITEE_COINS,
-    INVITE_INVITER_COINS,
     INVITE_NEW_USER_WINDOW_HOURS,
 )
 from app.db.session import SessionLocal
@@ -56,8 +54,8 @@ def test_invite_me_returns_stable_code(client) -> None:
     assert _my_code(client, token) == body["invite_code"]
 
 
-def test_bind_flow_both_get_coins(client) -> None:
-    """B 用 A 的码绑定 → 双方各得 1 万金币;A 战绩 +1。"""
+def test_bind_flow_no_coins_either_side(client) -> None:
+    """v3:B 用 A 的码绑定 → 双方都不发钱(被邀请人无奖励、邀请人改比价后发现金)。"""
     a = _login(client, "13800002002")
     b = _login(client, "13800002003")
     a_code = _my_code(client, a)
@@ -69,16 +67,16 @@ def test_bind_flow_both_get_coins(client) -> None:
     assert r.status_code == 200, r.text
     res = r.json()
     assert res["status"] == "success"
-    assert res["coins_awarded"] == INVITE_INVITEE_COINS
+    assert res["coins_awarded"] == 0
 
-    # 双方金币到账
-    assert _coin_balance(client, b) == INVITE_INVITEE_COINS
-    assert _coin_balance(client, a) == INVITE_INVITER_COINS
+    # 绑定后双方金币都不增(邀请人收益改走"好友比价发 2 元邀请奖励金")
+    assert _coin_balance(client, b) == 0
+    assert _coin_balance(client, a) == 0
 
-    # A 的战绩:已邀 1 人,累计获得 = 邀请人那份
+    # A 的战绩:已邀 1 人;金币口径收益恒 0(邀请人收益走邀请奖励金,见 try_reward_on_compare)
     r = client.get("/api/v1/invite/me", headers=_auth(a))
     assert r.json()["invited_count"] == 1
-    assert r.json()["coins_earned"] == INVITE_INVITER_COINS
+    assert r.json()["coins_earned"] == 0
 
 
 def test_bind_idempotent_no_double_reward(client) -> None:
@@ -217,9 +215,9 @@ def test_bind_by_fingerprint_success(client) -> None:
     )
     assert r2.status_code == 200, r2.text
     assert r2.json()["status"] == "success"
-    # 双方各发金币
-    assert _coin_balance(client, a) == INVITE_INVITER_COINS
-    assert _coin_balance(client, b) == INVITE_INVITEE_COINS
+    # v3:绑定双方都不发钱(被邀请人无奖励、邀请人改比价发现金)
+    assert _coin_balance(client, a) == 0
+    assert _coin_balance(client, b) == 0
 
 
 def test_bind_by_fingerprint_not_found(client) -> None:
@@ -322,7 +320,8 @@ def test_invitees_basic(client) -> None:
     names = {it["display_name"] for it in body["items"]}
     assert names == expected_names
     assert all(it["avatar_url"] is None for it in body["items"])
-    assert all(it["coins"] == INVITE_INVITER_COINS for it in body["items"])
+    # v2:绑定时邀请人那份为 0(收益改"好友比价才发奖"),故每条 coins 字段=0
+    assert all(it["coins"] == 0 for it in body["items"])
 
 
 def test_invitees_order_desc(client) -> None:

tests/test_invite_cash_withdraw.py

@@ -0,0 +1,193 @@
+"""邀请奖励金提现账户隔离测试:提现扣 invite_cash 账户、退款退回 invite_cash、与金币现金不串、
+/invite/me 返回奖励金战绩、提现单 source 过滤。复用 test_withdraw 的 wxpay monkeypatch 模式。
+"""
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from app.db.session import SessionLocal
+from app.models.user import User
+from app.models.wallet import CoinAccount, InviteCashTransaction
+from app.repositories import wallet as crud_wallet
+
+
+def _login(client, phone: str) -> str:
+    client.post("/api/v1/auth/sms/send", json={"phone": phone})
+    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    assert r.status_code == 200, r.text
+    return r.json()["access_token"]
+
+
+def _auth(token: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _patch_userinfo(monkeypatch, openid: str) -> None:
+    monkeypatch.setattr(
+        "app.integrations.wxpay.code_to_userinfo",
+        lambda code: {"openid": openid, "nickname": None, "avatar_url": None, "raw": {}},
+    )
+
+
+def _seed_balances(client, token: str, phone: str, *, cash: int = 0, invite_cash: int = 0) -> None:
+    """访问 /account 触发建账户,再 DB 直接灌两个账户余额(没有"加钱"接口,正常靠兑换/发奖)。"""
+    client.get("/api/v1/wallet/account", headers=_auth(token))
+    db = SessionLocal()
+    try:
+        user = db.execute(select(User).where(User.phone == phone)).scalar_one()
+        acc = db.get(CoinAccount, user.id)
+        acc.cash_balance_cents = cash
+        acc.invite_cash_balance_cents = invite_cash
+        db.commit()
+    finally:
+        db.close()
+
+
+def _balances(client, token: str) -> tuple[int, int]:
+    j = client.get("/api/v1/wallet/account", headers=_auth(token)).json()
+    return j["cash_balance_cents"], j["invite_cash_balance_cents"]
+
+
+def _reject(bill: str, reason: str = "测试拒绝") -> None:
+    db = SessionLocal()
+    try:
+        crud_wallet.reject_withdraw(db, bill, reason)
+    finally:
+        db.close()
+
+
+def test_invite_cash_withdraw_deducts_invite_account(client, monkeypatch) -> None:
+    """source=invite_cash 提现 → 扣 invite_cash_balance_cents,不动 cash;流水落 invite_cash_transaction。"""
+    _patch_userinfo(monkeypatch, "openid_ic_1")
+    token = _login(client, "13800004001")
+    _seed_balances(client, token, "13800004001", cash=300, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+
+    r = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["status"] == "reviewing"
+
+    cash, invite_cash = _balances(client, token)
+    assert invite_cash == 300       # 扣了邀请奖励金
+    assert cash == 300              # 金币现金没动
+
+    db = SessionLocal()
+    try:
+        user = db.execute(select(User).where(User.phone == "13800004001")).scalar_one()
+        txns = db.execute(
+            select(InviteCashTransaction).where(
+                InviteCashTransaction.user_id == user.id,
+                InviteCashTransaction.biz_type == "invite_withdraw",
+            )
+        ).scalars().all()
+        assert len(txns) == 1 and txns[0].amount_cents == -200
+    finally:
+        db.close()
+    orders = client.get("/api/v1/wallet/withdraw-orders", headers=_auth(token)).json()["items"]
+    assert orders[0]["source"] == "invite_cash"
+
+
+def test_invite_cash_reject_refunds_invite_account(client, monkeypatch) -> None:
+    """拒绝 invite_cash 提现 → 退回 invite_cash,不串金币现金;退款流水落 invite_cash_transaction。"""
+    _patch_userinfo(monkeypatch, "openid_ic_2")
+    token = _login(client, "13800004002")
+    _seed_balances(client, token, "13800004002", cash=0, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+
+    r = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    bill = r.json()["out_bill_no"]
+    cash, invite_cash = _balances(client, token)
+    assert invite_cash == 300 and cash == 0    # 扣后
+
+    _reject(bill)
+
+    cash, invite_cash = _balances(client, token)
+    assert invite_cash == 500    # 退回邀请奖励金
+    assert cash == 0             # 没串进现金
+
+    db = SessionLocal()
+    try:
+        user = db.execute(select(User).where(User.phone == "13800004002")).scalar_one()
+        refunds = db.execute(
+            select(InviteCashTransaction).where(
+                InviteCashTransaction.user_id == user.id,
+                InviteCashTransaction.biz_type == "invite_withdraw_refund",
+            )
+        ).scalars().all()
+        assert len(refunds) == 1 and refunds[0].amount_cents == 200
+    finally:
+        db.close()
+
+
+def test_two_accounts_withdraw_independent(client, monkeypatch) -> None:
+    """两账户各提各的不串:先提 invite_cash(拒绝结清),再提 cash,各扣各账户。
+    注:一个用户同一时间只能一个活跃提现单(跨账户),故第二笔需先结清第一笔。"""
+    _patch_userinfo(monkeypatch, "openid_ic_3")
+    token = _login(client, "13800004003")
+    _seed_balances(client, token, "13800004003", cash=400, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+
+    r1 = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    _reject(r1.json()["out_bill_no"])    # 退回 invite_cash + 结清活跃单
+    r2 = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 100, "source": "coin_cash"},
+        headers=_auth(token),
+    )
+    assert r2.json()["status"] == "reviewing"
+
+    cash, invite_cash = _balances(client, token)
+    assert invite_cash == 500    # 已退回
+    assert cash == 300           # 扣了 cash 100
+
+
+def test_invite_me_returns_reward_stats(client) -> None:
+    """/invite/me 返回 reward_balance_cents(可提现奖励金)。"""
+    token = _login(client, "13800004004")
+    _seed_balances(client, token, "13800004004", invite_cash=350)
+    j = client.get("/api/v1/invite/me", headers=_auth(token)).json()
+    assert j["reward_balance_cents"] == 350
+    assert j["reward_withdrawn_cents"] == 0
+
+
+def test_withdraw_orders_source_filter(client, monkeypatch) -> None:
+    """/wallet/withdraw-orders?source=invite_cash 只返回邀请奖励金提现单。"""
+    _patch_userinfo(monkeypatch, "openid_ic_5")
+    token = _login(client, "13800004005")
+    _seed_balances(client, token, "13800004005", cash=400, invite_cash=500)
+    client.post("/api/v1/wallet/bind-wechat", json={"code": "c"}, headers=_auth(token))
+
+    r1 = client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 200, "source": "invite_cash"},
+        headers=_auth(token),
+    )
+    _reject(r1.json()["out_bill_no"])    # 结清,才能提第二笔
+    client.post(
+        "/api/v1/wallet/withdraw",
+        json={"amount_cents": 100, "source": "coin_cash"},
+        headers=_auth(token),
+    )
+
+    all_orders = client.get("/api/v1/wallet/withdraw-orders", headers=_auth(token)).json()["items"]
+    invite_orders = client.get(
+        "/api/v1/wallet/withdraw-orders", params={"source": "invite_cash"}, headers=_auth(token)
+    ).json()["items"]
+    coin_orders = client.get(
+        "/api/v1/wallet/withdraw-orders", params={"source": "coin_cash"}, headers=_auth(token)
+    ).json()["items"]
+    assert len(all_orders) == 2
+    assert len(invite_orders) == 1 and invite_orders[0]["source"] == "invite_cash"
+    assert len(coin_orders) == 1 and coin_orders[0]["source"] == "coin_cash"

tests/test_invite_compare_reward.py

@@ -0,0 +1,114 @@
+"""邀请 v3 比价发奖测试:好友完成成功比价 → 邀请人得邀请奖励金(独立账户),幂等只发一次,
+账户隔离不串金币/现金。被邀请人绑定不得任何奖励由 test_invite.py 覆盖。
+"""
+from __future__ import annotations
+
+from sqlalchemy import select
+
+from app.core.rewards import INVITE_COMPARE_REWARD_CENTS
+from app.db.session import SessionLocal
+from app.models.wallet import CoinAccount, InviteCashTransaction
+from app.repositories.user import get_user_by_phone
+
+
+def _login(client, phone: str) -> str:
+    client.post("/api/v1/auth/sms/send", json={"phone": phone})
+    r = client.post("/api/v1/auth/sms/login", json={"phone": phone, "code": "123456"})
+    assert r.status_code == 200, r.text
+    return r.json()["access_token"]
+
+
+def _auth(token: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {token}"}
+
+
+def _my_code(client, token: str) -> str:
+    return client.get("/api/v1/invite/me", headers=_auth(token)).json()["invite_code"]
+
+
+def _bind(client, token: str, code: str):
+    return client.post("/api/v1/invite/bind", json={"invite_code": code}, headers=_auth(token))
+
+
+def _report_compare(client, token: str, trace_id: str, status: str = "success"):
+    return client.post(
+        "/api/v1/compare/record",
+        json={"trace_id": trace_id, "status": status},
+        headers=_auth(token),
+    )
+
+
+def _invite_cash(phone: str) -> int:
+    """被试用户的邀请奖励金余额(分)。专用查询端点见小步3,这里直接查 DB。"""
+    with SessionLocal() as db:
+        u = get_user_by_phone(db, phone)
+        acc = db.get(CoinAccount, u.id) if u else None
+        return acc.invite_cash_balance_cents if acc else 0
+
+
+def test_compare_reward_granted_to_inviter(client) -> None:
+    """B 被 A 邀请后完成一次成功比价 → A 得邀请奖励金 2 元(独立账户),B 不得该奖。"""
+    a = _login(client, "13800003001")
+    b = _login(client, "13800003002")
+    _bind(client, b, _my_code(client, a))
+
+    assert _invite_cash("13800003001") == 0                            # 发奖前
+
+    r = _report_compare(client, b, "trace-reward-1")
+    assert r.status_code == 200, r.text
+
+    assert _invite_cash("13800003001") == INVITE_COMPARE_REWARD_CENTS  # 邀请人到账
+    assert _invite_cash("13800003002") == 0                            # 被邀请人不得此奖
+
+
+def test_compare_reward_idempotent(client) -> None:
+    """好友比价多次 → 只发一次(compare_reward_granted 幂等)。"""
+    a = _login(client, "13800003003")
+    b = _login(client, "13800003004")
+    _bind(client, b, _my_code(client, a))
+
+    _report_compare(client, b, "trace-idem-1")
+    _report_compare(client, b, "trace-idem-2")    # 第二次比价(不同 trace)
+    _report_compare(client, b, "trace-idem-1")    # 重复上报同 trace
+
+    assert _invite_cash("13800003003") == INVITE_COMPARE_REWARD_CENTS  # 仍只发一次
+
+
+def test_compare_no_relation_no_reward(client) -> None:
+    """没有邀请关系的人比价 → 不发奖(没人是他的邀请人)。"""
+    x = _login(client, "13800003005")
+    r = _report_compare(client, x, "trace-norel-1")
+    assert r.status_code == 200, r.text
+    assert _invite_cash("13800003005") == 0
+
+
+def test_compare_failed_no_reward(client) -> None:
+    """失败的比价(status=failed)不触发发奖。"""
+    a = _login(client, "13800003006")
+    b = _login(client, "13800003007")
+    _bind(client, b, _my_code(client, a))
+
+    _report_compare(client, b, "trace-fail-1", status="failed")
+    assert _invite_cash("13800003006") == 0
+
+
+def test_compare_reward_isolated_from_coin_cash(client) -> None:
+    """账户隔离:邀请奖励金进 invite_cash,不串 cash_balance_cents;流水落 invite_cash_transaction。"""
+    a = _login(client, "13800003008")
+    b = _login(client, "13800003009")
+    _bind(client, b, _my_code(client, a))
+    _report_compare(client, b, "trace-iso-1")
+
+    with SessionLocal() as db:
+        ua = get_user_by_phone(db, "13800003008")
+        acc = db.get(CoinAccount, ua.id)
+        assert acc.invite_cash_balance_cents == INVITE_COMPARE_REWARD_CENTS  # 奖励金到账
+        assert acc.cash_balance_cents == 0                                   # 没串进金币现金
+        txns = db.execute(
+            select(InviteCashTransaction).where(
+                InviteCashTransaction.user_id == ua.id,
+                InviteCashTransaction.biz_type == "invite_reward",
+            )
+        ).scalars().all()
+        assert len(txns) == 1
+        assert txns[0].amount_cents == INVITE_COMPARE_REWARD_CENTS

tests/test_pangle_report.py

@@ -0,0 +1,134 @@
+"""穿山甲 GroMore 数据 API 客户端测试。
+
+重点锚定**签名算法**:用官方文档 Python / Java 示例里给出的「参数 + secure_key → sign」两个
+测试向量做断言,保证我们的 build_sign 与穿山甲服务端逐字节一致(签错=接口直接 101 验签失败)。
+另测拉取的翻页、业务码非 100 抛错、响应解析。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.core.config import settings
+from app.integrations import pangle_report
+from app.integrations.pangle_report import PangleReportError, build_sign
+
+# ---- 签名:官方文档测试向量(完整 key 与期望 sign 来自文档代码注释)----
+
+def test_build_sign_matches_doc_python_vector():
+    params = {
+        "current_time": "2022-01-06 16:10:54",
+        "sign_type": "MD5",
+        "version": "2.0",
+        "user_id": 459,
+        "role_id": 459,
+    }
+    sign = build_sign(params, "7f2ddb34d999ea61c00246ea3971529c")
+    assert sign == "57b9fed9b6c09cefdced7fa770fe341d"
+
+
+def test_build_sign_matches_doc_java_vector():
+    params = {
+        "user_id": 459,
+        "role_id": 459,
+        "version": "2.0",
+        "sign_type": "MD5",
+        "current_time": "2022-01-06 16:05:49",
+    }
+    sign = build_sign(params, "1c589c70f7bb2746027ce90c33d2544c")
+    assert sign == "4d47b3a7679448c3da5c1d05e5291533"
+
+
+def test_build_sign_drops_sign_and_empty_fields():
+    """sign 字段与空值字段不参与签名:带上它们应得到与不带时相同的 sign。"""
+    base = {"version": "2.0", "user_id": 459, "role_id": 459, "sign_type": "MD5"}
+    with_noise = {**base, "sign": "deadbeef", "code_ids": "", "os": None}
+    assert build_sign(with_noise, "key123") == build_sign(base, "key123")
+
+
+# ---- 拉取:伪造 httpx 客户端,验证翻页 / 解析 / 业务码 ----
+
+class _FakeResp:
+    def __init__(self, payload: dict):
+        self._payload = payload
+
+    def raise_for_status(self) -> None:
+        pass
+
+    def json(self) -> dict:
+        return self._payload
+
+
+class _FakeClient:
+    """按 offset 返回分页响应;记录每次请求的 params 供断言。"""
+
+    def __init__(self, pages: list[dict]):
+        self._pages = pages
+        self.calls: list[dict] = []
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        return False
+
+    def get(self, url: str, params: dict):
+        self.calls.append(params)
+        # 第 N 次调用取第 N 页(has_next 驱动翻页);超出用最后一页兜底
+        page = self._pages[min(len(self.calls) - 1, len(self._pages) - 1)]
+        return _FakeResp(page)
+
+
+@pytest.fixture
+def _configured(monkeypatch):
+    monkeypatch.setattr(settings, "PANGLE_REPORT_USER_ID", 459)
+    monkeypatch.setattr(settings, "PANGLE_REPORT_ROLE_ID", 459)
+    monkeypatch.setattr(settings, "PANGLE_REPORT_SECURITY_KEY", "key123")
+
+
+def test_fetch_daily_report_paginates_and_parses(monkeypatch, _configured):
+    page1 = {
+        "code": "100", "message": "",
+        "data": {
+            "has_next": "1", "currency": "cny", "total": 3,
+            "report_list": [
+                {"start_date": "2026-06-27", "site_id": "5830519", "ad_unit_id": "104142227",
+                 "revenue": "1.23", "api_revenue": "1.05", "ecpm": "0.80", "imp_cnt": "1537"},
+            ],
+        },
+    }
+    page2 = {
+        "code": "100", "message": "",
+        "data": {
+            "has_next": "0", "currency": "cny", "total": 3,
+            "report_list": [
+                {"start_date": "2026-06-27", "site_id": "5832303", "ad_unit_id": "104137445",
+                 "revenue": "0.00", "api_revenue": "", "ecpm": "0", "imp_cnt": "12"},
+            ],
+        },
+    }
+    fake = _FakeClient([page1, page2])
+    monkeypatch.setattr(pangle_report.httpx, "Client", lambda *a, **k: fake)
+
+    rows = pangle_report.fetch_daily_report(start_date="2026-06-27", end_date="2026-06-27")
+
+    assert len(rows) == 2          # 两页都被取到(has_next 驱动翻页)
+    assert rows[0]["ad_unit_id"] == "104142227"
+    assert rows[1]["api_revenue"] == ""
+    # 每次请求都带上签名与必填鉴权参数
+    assert "sign" in fake.calls[0]
+    assert fake.calls[0]["user_id"] == 459 and fake.calls[0]["version"] == "2.0"
+
+
+def test_fetch_daily_report_raises_on_business_error(monkeypatch, _configured):
+    fail = {"code": "118", "message": "no revenue permission", "data": {}}
+    monkeypatch.setattr(
+        pangle_report.httpx, "Client", lambda *a, **k: _FakeClient([fail])
+    )
+    with pytest.raises(PangleReportError):
+        pangle_report.fetch_daily_report(start_date="2026-06-27", end_date="2026-06-27")
+
+
+def test_fetch_daily_report_no_config_raises(monkeypatch):
+    monkeypatch.setattr(settings, "PANGLE_REPORT_USER_ID", 0)
+    with pytest.raises(PangleReportError):
+        pangle_report.fetch_daily_report(start_date="2026-06-27", end_date="2026-06-27")

tests/test_test_account.py

@@ -142,6 +142,54 @@ def test_send_does_not_consume_quota(client, enabled, monkeypatch) -> None:
     assert client.post("/api/v1/auth/sms/login", json={"phone": TEST_PHONE, "code": "1234"}).status_code == 429
 
 
+# ============================ 登录限流豁免 ============================
+
+def test_exempt_from_device_ip_login_rate_limit(client, enabled, monkeypatch) -> None:
+    """测试号豁免 (设备+IP) 每小时登录限流。
+
+    普通设备同设备同 IP 到 SMS_LOGIN_MAX_PER_HOUR 次即被拦(见 test_auth.test_sms_login_device_ip_rate_limit);
+    测试号走自己的每日额度、不受这道限流——这里临时打开 RATE_LIMIT_ENABLED,同一设备连登远超该上限仍全 200。
+    回归用:防有人把 enforce_rate_limit 挪到测试账号 early-return 之前而破坏豁免。"""
+    from app.api.v1 import auth
+    from app.core import ratelimit
+
+    monkeypatch.setattr(ratelimit.settings, "RATE_LIMIT_ENABLED", True)
+    ratelimit._buckets.clear()  # 隔离:清掉跨用例累加的内存计数
+
+    # 同一设备连登 (每小时上限 + 3) 次,远超普通设备会被拦的阈值;测试号豁免 → 全部放行
+    for i in range(auth.SMS_LOGIN_MAX_PER_HOUR + 3):
+        r = client.post(
+            "/api/v1/auth/sms/login",
+            json={"phone": TEST_PHONE, "code": "000000", "device_id": "dev-test-exempt"},
+        )
+        assert r.status_code == 200, (
+            f"测试号第 {i + 1} 次登录应放行(豁免每小时限流),实际 {r.status_code}: {r.text}"
+        )
+
+
+def test_exempt_from_device_ip_send_rate_limit(client, enabled, monkeypatch) -> None:
+    """测试号豁免 (设备+IP) 每小时**发码**限流(与登录那道同样靠早返回豁免)。
+
+    普通设备同设备到 SMS_SEND_MAX_PER_HOUR_PER_DEVICE 次发码即被拦(见 test_auth.test_sms_send_device_ip_rate_limit);
+    测试号发码本就短路(不真发)、且在限流之前早返回 → 同一设备连发远超上限仍全 200。
+    回归用:防有人把发码限流挪到测试账号 early-return 之前而把 QA 联调也风控了。"""
+    from app.api.v1 import auth
+    from app.core import ratelimit
+
+    monkeypatch.setattr(ratelimit.settings, "RATE_LIMIT_ENABLED", True)
+    monkeypatch.setattr(auth, "SMS_SEND_MAX_PER_HOUR_PER_DEVICE", 2)  # 调小:不豁免的话第 3 次就该被拦
+    ratelimit._buckets.clear()
+
+    for i in range(auth.SMS_SEND_MAX_PER_HOUR_PER_DEVICE + 2):
+        r = client.post(
+            "/api/v1/auth/sms/send",
+            json={"phone": TEST_PHONE, "device_id": "dev-test-send"},
+        )
+        assert r.status_code == 200, (
+            f"测试号第 {i + 1} 次发码应放行(豁免每小时限流),实际 {r.status_code}: {r.text}"
+        )
+
+
 # ============================ 计数单元逻辑 ============================
 
 def test_quota_resets_across_day(enabled, monkeypatch) -> None:

tests/test_welfare.py

@@ -46,7 +46,12 @@ def test_account_auto_created_empty(client) -> None:
     r = client.get("/api/v1/wallet/account", headers=_auth(token))
     assert r.status_code == 200, r.text
     body = r.json()
-    assert body == {"coin_balance": 0, "cash_balance_cents": 0, "total_coin_earned": 0}
+    assert body == {
+        "coin_balance": 0,
+        "cash_balance_cents": 0,
+        "invite_cash_balance_cents": 0,    # v2 账户隔离新增(邀请奖励金,与现金隔离)
+        "total_coin_earned": 0,
+    }
 
 
 def test_signin_flow(client) -> None:

tools/meituan_playground.py

@@ -52,7 +52,8 @@ def call_raw(path: str, body_obj: dict) -> dict:
     }
     url = f"{settings.MT_CPS_HOST}{path}"
     t0 = time.time()
-    resp = httpx.post(url, content=body, headers=headers, timeout=settings.MT_CPS_TIMEOUT_SEC)
+    # trust_env=False: 美团是国内域名,强制直连绕开本机代理(代理会掐断 TLS 握手,报 SSL EOF)
+    resp = httpx.post(url, content=body, headers=headers, timeout=settings.MT_CPS_TIMEOUT_SEC, trust_env=False)
     ms = int((time.time() - t0) * 1000)
     try:
         j = resp.json()