fix(migration): 缩短 revision id 至 26 字符(修 alembic_version varchar(32) 截断致 0.2.1 部署失败)

invite_cash_account_and_compare_reward(38字符) > alembic_version.version_num varchar(32),
INSERT 时 psycopg StringDataRightTruncation → 部署 alembic 迁移失败。改为 invite_cash_compare_reward(26)。
该迁移是链末端(无后续 down_revision 依赖)、首次部署(任何环境都没应用过、PG DDL 事务失败已回滚无残留), 改 id 安全。

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

CLAUDE.md

@@ -0,0 +1,116 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+Shaguabijia (傻瓜比价) App backend — FastAPI + SQLAlchemy 2.0 + JWT. Covers user auth (Jiguang one-click / SMS), welfare wallet (coins/cash/signin/tasks/savings), WeChat Pay withdrawals, ad-reward callbacks (Pangle/GroMore S2S), Meituan CPS (coupon forwarding / price comparison), and an admin backend.
+
+## Commands
+
+```bash
+# Install
+pip install -e ".[dev]"
+
+# Run app server (port 8770, auto-migrates, auto-reload)
+./run.sh                    # or: uvicorn app.main:app --reload --port 8770
+
+# Run admin server (port 8771, separate process)
+uvicorn app.admin.main:admin_app --reload --port 8771
+
+# Database
+alembic upgrade head        # apply all migrations (idempotent)
+alembic revision --autogenerate -m "description"  # generate new migration
+
+# Tests
+pytest -q                   # all tests
+pytest tests/test_auth.py -q        # single file
+pytest -k "test_sms_login" -q       # single test by name
+
+# Lint
+ruff check .
+ruff check --fix .
+```
+
+## Architecture: two FastAPI apps
+
+This repo runs **two separate FastAPI processes** sharing the same `app/` codebase (models, repositories, integrations, config):
+
+| | App server | Admin server |
+|---|---|---|
+| Entry | `app/main.py` → `app:app` | `app/admin/main.py` → `admin_app` |
+| Port | 8770 | 8771 |
+| Auth | User JWT (`JWT_SECRET_KEY`) | Admin JWT (`ADMIN_JWT_SECRET`, independent) |
+| Audience | Mobile app clients | Internal admin dashboard |
+| Docs | `/docs` (non-prod only) | `/admin/docs` (non-prod only) |
+
+The two apps are intentionally decoupled — `app.main` never imports `app.admin`. Admin has its own auth chain (`app/admin/deps.py`, `app/admin/security.py`), role-based guards (`require_role`), and routers under `app/admin/routers/`.
+
+## Layered request flow
+
+```
+api/v1/  (thin: parse → delegate → respond + HTTP errors)
+  ├── integrations/   (external SDKs: signature, encryption, HTTP calls)
+  └── repositories/   (data access + transactions)
+        └── models/   (SQLAlchemy ORM, DeclarativeBase)
+```
+
+- **`api/v1/`**: Route handlers. Keep these thin — parse request, call repository or integration, return response. Never put business logic or external HTTP here.
+- **`api/deps.py`**: Shared FastAPI dependencies — `get_current_user` (Bearer JWT → User ORM object), `get_db` (request-scoped session).
+- **`integrations/`**: All external service logic — Jiguang REST + RSA decryption, WeChat Pay V3 signing/encryption, Meituan CPS gateway signing, Pangle callback signature verification, SMS sending. This is the layer you change when swapping vendors.
+- **`repositories/`**: Data access. Each file wraps SQLAlchemy queries + transactions for one domain (user, wallet, signin, savings, ad_reward, etc.). Some repositories also call integrations (e.g., `wallet.py` calls `integrations/wxpay.py` for withdrawals).
+- **`models/`**: ORM table definitions (SQLAlchemy 2.0 `Mapped` style, `DeclarativeBase`). Every new model must be imported in `app/models/__init__.py` so Alembic can discover it.
+- **`schemas/`**: Pydantic request/response contracts.
+- **`core/`**: Infrastructure — config (`pydantic-settings`), JWT (`security.py`), in-memory rate limiter (`ratelimit.py`), reward constants (`rewards.py`), logging setup, pricebot router (consistent-hash load balancing), withdraw reconcile worker.
+
+## Internal (server-to-server) endpoints
+
+Endpoints under `app/api/internal/` are for server-to-server communication (pricebot → app-server), NOT for clients. They use a shared secret header `X-Internal-Secret` (compared via `hmac.compare_digest`) instead of user JWT. If `INTERNAL_API_SECRET` is empty, these endpoints return 503.
+
+## Auth system
+
+- **User login**: Jiguang one-click (`integrations/jiguang.py` — REST token verification + RSA decryption with multi-padding retry) or SMS code (mock by default; `SMS_MOCK=true`).
+- **Tokens**: JWT access (2h) + refresh (30d). Both are JWT with `typ` claim (`"access"` vs `"refresh"`) to prevent refresh-as-access. See `core/security.py`.
+- **Admin auth**: Separate JWT secret (`ADMIN_JWT_SECRET`), 12h expiry, no refresh. Username + bcrypt password login. Role-based access via `require_role()` guard in `app/admin/deps.py` (`super_admin` bypasses all role checks).
+- **Rate limiting**: In-memory fixed-window by client IP (`core/ratelimit.py`). Single-worker only; disabled in tests via `RATE_LIMIT_ENABLED=false`.
+
+## Database
+
+- **Dev**: SQLite (`sqlite:///./data/app.db`), `check_same_thread=False`, no connection pool.
+- **Prod**: PostgreSQL — just change `DATABASE_URL` in `.env`. Pool size 10 + max overflow 20, pool_recycle 3600.
+- **Migrations**: Alembic with `render_as_batch` for SQLite compatibility. ~60+ migration files in `alembic/versions/` (filenames are descriptive, not hex prefixes). Migration chain uses `down_revision` within each file.
+- **New models**: Define in `app/models/`, import in `app/models/__init__.py`, then run `alembic revision --autogenerate`.
+
+## Config
+
+All config via `pydantic-settings` in `app/core/config.py`. Single `Settings` class with env vars / `.env` file. Access anywhere via `from app.core.config import settings`. Key patterns:
+- `*_configured` properties gate features gracefully (e.g., `mt_cps_configured`, `wxpay_configured`, `pangle_callback_configured`) — missing credentials → endpoints return empty/503 rather than crashing at startup.
+- Prod validation: `_enforce_prod_secrets` model validator blocks startup if `APP_ENV=prod` with weak JWT secrets.
+
+## Testing
+
+- `tests/conftest.py`: Sets env vars BEFORE imports, creates temp SQLite file, builds all tables with `Base.metadata.create_all()`, tears down with `drop_all()` + unlink.
+- External integrations are monkeypatched in tests (e.g., WeChat Pay, Jiguang, Pangle callbacks) — tests never make real HTTP calls.
+- `TestClient` from FastAPI is used for all tests. Rate limiting is disabled globally in tests.
+
+## Key integration details
+
+- **Jiguang one-click login**: REST call to verify `loginToken`, then RSA decrypt the returned phone number. Multiple padding schemes tried in order (PKCS1v15, OAEP with SHA1/SHA256) because Jiguang's encryption padding varies.
+- **WeChat Pay withdrawals**: V3 API merchant transfer to user WeChat balance. Lazy-loads merchant certificates from `secrets/`. Withdrawal flow: bind WeChat → create withdraw order → auto-reconcile worker polls pending orders.
+- **Pangle ad rewards**: S2S callback verification via SHA256 signature. Multiple `m-key` secrets supported (one per ad placement). Callback is idempotent by `trans_id`. Test grant endpoint (`AD_REWARD_TEST_GRANT_ENABLED`) for local debugging — must be false in prod.
+- **Meituan CPS**: Gateway signature-based API calls. Proxy support (`MT_CPS_PROXY`) for local dev (direct connection causes SSL EOF). Coupon endpoints gracefully return empty when credentials are missing.
+- **Pricebot forwarding**: `/api/v1/coupon/step` and `/api/v1/compare/*` proxy to pricebot-backend. Multi-instance support with consistent-hash routing by `trace_id` (see `core/pricebot_router.py`).
+- **CPS redirect**: `/c/{code}` is a public (no auth) short-link redirect — records a click then 302s to Meituan. Click recording failure never blocks the redirect.
+
+## Money and units
+
+All monetary amounts are in **cents** (`*_cents` fields). Coins/gold have their own unit. Conversion constants are in `core/rewards.py`.
+
+## Scripts
+
+Key operational scripts in `scripts/`:
+- `migrate.sh` — run migrations standalone
+- `create_admin.py` — create admin user
+- `daily_auto_exchange.py` — auto-convert coins to cash (triggered by systemd timer)
+- `reconcile_withdraws.py` — reconcile withdrawal orders with WeChat Pay
+- `sim_pangle_callback.py` — simulate Pangle S2S callback for testing

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/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/cps_v2_platforms.py

@@ -23,39 +23,64 @@ branch_labels: Union[str, Sequence[str], None] = None
 depends_on: Union[str, Sequence[str], None] = None
 
 
-def upgrade() -> None:
-    # 活动:淘宝淘口令 / 京东链接
-    op.add_column("cps_activity", sa.Column("payload", sa.Text(), nullable=True))
+def _has_column(insp: sa.Inspector, table: str, column: str) -> bool:
+    return any(c["name"] == column for c in insp.get_columns(table))
 
-    # 群:多平台(现有群都是美团,server_default 回填)+ sid 可空
-    op.add_column(
-        "cps_group",
-        sa.Column(
-            "platforms",
-            sa.JSON().with_variant(postgresql.JSONB(), "postgresql"),
-            nullable=False,
-            server_default=sa.text("'[\"meituan\"]'::jsonb"),
-        ),
+
+def upgrade() -> None:
+    bind = op.get_bind()
+    insp = sa.inspect(bind)
+    # SQLite 不认 ::jsonb cast(会报 "unrecognized token: :"),只有 PG 用显式 cast。
+    # 两边列类型都靠上面的 with_variant 区分,这里只管 server_default 文本。
+    platforms_default = (
+        sa.text("'[\"meituan\"]'::jsonb")
+        if bind.dialect.name == "postgresql"
+        else sa.text("'[\"meituan\"]'")
     )
-    op.alter_column("cps_group", "sid", existing_type=sa.String(64), nullable=True)
+
+    # 活动:淘宝淘口令 / 京东链接
+    # 加 add_column 存在性守卫:本迁移历史上在 SQLite 第一次跑时加完 payload 即在
+    # platforms 那步炸掉(::jsonb),DDL 非事务不回滚 → 半应用状态。守卫让其可自愈重跑。
+    if not _has_column(insp, "cps_activity", "payload"):
+        op.add_column("cps_activity", sa.Column("payload", sa.Text(), nullable=True))
+
+    # 群:多平台(现有群都是美团,server_default 回填)+ sid 可空。
+    # SQLite 不支持 ALTER COLUMN,必须用 batch(重建表)才能改 nullable;PG 走原生 ALTER。
+    with op.batch_alter_table("cps_group") as batch_op:
+        if not _has_column(insp, "cps_group", "platforms"):
+            batch_op.add_column(
+                sa.Column(
+                    "platforms",
+                    sa.JSON().with_variant(postgresql.JSONB(), "postgresql"),
+                    nullable=False,
+                    server_default=platforms_default,
+                )
+            )
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=True)
 
     # link:sid 可空 + target 加长
-    op.alter_column("cps_link", "sid", existing_type=sa.String(64), nullable=True)
-    op.alter_column("cps_link", "target_url", existing_type=sa.String(1024), type_=sa.String(2048))
+    with op.batch_alter_table("cps_link") as batch_op:
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=True)
+        batch_op.alter_column("target_url", existing_type=sa.String(1024), type_=sa.String(2048))
 
     # click:sid 可空 + 事件类型
-    op.alter_column("cps_click", "sid", existing_type=sa.String(64), nullable=True)
-    op.add_column(
-        "cps_click",
-        sa.Column("event_type", sa.String(16), nullable=False, server_default="visit"),
-    )
+    with op.batch_alter_table("cps_click") as batch_op:
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=True)
+        if not _has_column(insp, "cps_click", "event_type"):
+            batch_op.add_column(
+                sa.Column("event_type", sa.String(16), nullable=False, server_default="visit")
+            )
 
 
 def downgrade() -> None:
-    op.drop_column("cps_click", "event_type")
-    op.alter_column("cps_click", "sid", existing_type=sa.String(64), nullable=False)
-    op.alter_column("cps_link", "target_url", existing_type=sa.String(2048), type_=sa.String(1024))
-    op.alter_column("cps_link", "sid", existing_type=sa.String(64), nullable=False)
-    op.drop_column("cps_group", "platforms")
-    op.alter_column("cps_group", "sid", existing_type=sa.String(64), nullable=False)
-    op.drop_column("cps_activity", "payload")
+    with op.batch_alter_table("cps_click") as batch_op:
+        batch_op.drop_column("event_type")
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=False)
+    with op.batch_alter_table("cps_link") as batch_op:
+        batch_op.alter_column("target_url", existing_type=sa.String(2048), type_=sa.String(1024))
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=False)
+    with op.batch_alter_table("cps_group") as batch_op:
+        batch_op.drop_column("platforms")
+        batch_op.alter_column("sid", existing_type=sa.String(64), nullable=False)
+    with op.batch_alter_table("cps_activity") as batch_op:
+        batch_op.drop_column("payload")

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/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

@@ -128,8 +128,28 @@ 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 记录逐份累加,LT 序号沿用账号累计份数(含本日之前)。
+
+    **关键:LT 因子账号累计按全表 unit 累计(feed+draw 共享同一发奖池/上限),不按 ad_type 拆分**——
+    故无论 scene 怎么筛展示,这里都遍历当日**全部**信息流记录维持 granted_units 累加;scene 只决定
+    哪些行被**留下展示**(由 _feed_scene_matches 判断),不影响累计基线,保证复算序号与正式发奖一致。
+    """
     stmt = (
         select(AdFeedRewardRecord)
         .where(AdFeedRewardRecord.reward_date == date)
@@ -142,18 +162,23 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
     granted_units: dict[int, int] = _feed_prior_granted_units(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
+            granted_units[rec.user_id] = existing + units
+            if not keep:
+                continue
             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
             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,
@@ -173,8 +198,12 @@ def _feed_rows(db: Session, *, date: str, user_id: int | None) -> list[dict]:
                 "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 +228,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,12 +11,17 @@
 (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
@@ -30,7 +35,7 @@ from app.models.user import User
 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 +51,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 = (
@@ -84,7 +99,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 +140,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,
@@ -162,7 +180,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"],

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
@@ -199,6 +202,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,
     *,
@@ -412,6 +565,44 @@ def list_feedbacks(
     return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
 
 
+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)
+
+
 def get_withdraw_by_out_bill_no(db: Session, out_bill_no: str) -> WithdrawOrder | None:
     """按商户单号查提现单(admin 重试打款先拿 user_id 用,M3)。"""
     return db.execute(

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/cps.py

@@ -468,7 +468,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 +496,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/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/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

@@ -56,7 +56,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)")

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/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/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,

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_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/cps_redirect.py

@@ -94,16 +94,35 @@ def cps_landing(code: str, request: Request, db: Session = Depends(get_db)):
         return HTMLResponse(
             _taobao_landing_html(link.target_url, image_url, code, openid, has_uinfo)
         )
-    # 美团短链 / 京东链接:直接 302 跳
+    # 美团短链 / 京东链接:微信内 + 已拿 openid + 还没授权过头像 → 先出「领券前授权」插页,
+    # 点按钮(交互手势,避免微信快照页)走 snsapi_userinfo 拿昵称头像,授权回来经
+    # /c/{code}?authed=1 自动 302 跳券。其余(非微信 / 未配授权 / 无 openid / 已授权)直接 302。
+    # 产品决定:每次未授权都提示(不做冷却、不种"已提示"cookie)。取消授权由插页前端自动
+    # 转跳目标券页(无单独"暂不授权"出口),拒绝也能拿到券(对齐「绝不阻断领券」)。
+    if (
+        settings.wx_oauth_active
+        and _is_wechat(request)
+        and openid is not None
+        and request.cookies.get(_WX_UINFO_COOKIE) != "1"
+    ):
+        return HTMLResponse(_coupon_auth_landing_html(link.target_url, code))
     return RedirectResponse(link.target_url, status_code=302)
 
 
 @router.get("/wx/oauth/cb", include_in_schema=False)
-def wx_oauth_cb(code: str, state: str, db: Session = Depends(get_db)):
+def wx_oauth_cb(
+    code: str | None = None, state: str | None = None, db: Session = Depends(get_db)
+):
     """微信网页授权回调。state='base:{原code}'(静默拿 openid) 或 'uinfo:{原code}'(补昵称头像)。
     换 openid(+userinfo)→ upsert 用户 → 种 cookie → 302 回落地页。任何失败兜底回落地页,
     绝不阻断用户领券。"""
-    kind, _, orig_code = state.partition(":")
+    kind, _, orig_code = (state or "").partition(":")
+    # 授权弹窗点「取消」时,部分微信版本会带空 code 回调本端点(而非退回落地页)。无 code 换
+    # 不到 openid,直接兜底跳回落地页(美团/京东落地页前端会再转跳目标券页),不报 422。
+    if not code:
+        return RedirectResponse(
+            f"/c/{orig_code}" if orig_code else _FALLBACK_URL, status_code=302
+        )
     try:
         token = wx_oauth.exchange_code(code)  # {openid, access_token, scope, ...}
         openid = token["openid"]
@@ -139,6 +158,12 @@ def cps_copy(code: str, request: Request, db: Session = Depends(get_db)) -> dict
     return {"ok": True}
 
 
+def _js_str(s: str) -> str:
+    """把字符串安全嵌进 <script> 的 JS 字面量:json.dumps 不转义 '<',值里含 '</script>'
+    会逃逸标签 → 把 '<' 转成 \\u003c(JS 仍解析为 '<')。auth/target/淘口令等都走它。"""
+    return json.dumps(s).replace("<", "\\u003c")
+
+
 def _taobao_landing_html(
     token: str, image_url: str, code: str, openid: str | None, has_uinfo: bool
 ) -> str:
@@ -156,8 +181,8 @@ def _taobao_landing_html(
     return (
         _TAOBAO_HTML
         .replace("__IMAGE_URL__", safe_img)
-        .replace("__UINFO_URL__", json.dumps(uinfo_url))
-        .replace("__TOKEN_JS__", json.dumps(token))
+        .replace("__UINFO_URL__", _js_str(uinfo_url))
+        .replace("__TOKEN_JS__", _js_str(token))
     )
 
 
@@ -210,3 +235,66 @@ if(location.search.indexOf('authed=1')>=0){doCopy();history.replaceState(null,''
 </script>
 </body>
 </html>"""
+
+
+def _coupon_auth_landing_html(target_url: str, code: str) -> str:
+    """美团/京东「领券前先授权头像」插页(单按钮)。
+
+    唯一按钮「立即领取优惠券」→ snsapi_userinfo 授权(用户点击=交互手势,避免微信快照页)。
+    - 点「允许」→ 回调拿昵称头像 + 种 wx_uinfo cookie → 经 /c/{code}?authed=1 自动 302 跳券。
+    - 点「取消」→ 微信退回本插页,前端 pageshow/visibilitychange 检测到"刚点过领取"即直接
+      转跳 target(不再设单独的"暂不授权"出口),保证拒绝也能拿到券(对齐「绝不阻断领券」)。
+    AUTH/TARGET 经 json.dumps 安全嵌入 JS 字符串(URL 里的 & 不会被 HTML 转义,直跳更稳)。
+    """
+    redirect_uri = f"{settings.CPS_REDIRECT_BASE.rstrip('/')}/wx/oauth/cb"
+    auth_url = wx_oauth.build_authorize_url(redirect_uri, "snsapi_userinfo", f"uinfo:{code}")
+    return (
+        _COUPON_AUTH_HTML
+        .replace("__AUTH_URL__", _js_str(auth_url))
+        .replace("__TARGET_URL__", _js_str(target_url))
+    )
+
+
+_COUPON_AUTH_HTML = """<!DOCTYPE html>
+<html lang="zh">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no">
+<title>领取优惠券</title>
+<style>
+*{margin:0;padding:0;box-sizing:border-box;-webkit-tap-highlight-color:transparent}
+body{font-family:-apple-system,"PingFang SC",sans-serif;background:#fff0ef;color:#333;min-height:100vh;display:flex;align-items:center;justify-content:center;padding:24px}
+.card{width:100%;max-width:340px;background:#fff;border-radius:18px;padding:34px 24px;text-align:center;box-shadow:0 8px 24px rgba(255,59,59,.12)}
+.title{font-size:22px;font-weight:800;color:#ff3b3b;margin-bottom:10px}
+.sub{font-size:14px;color:#999;line-height:1.6;margin-bottom:28px}
+.btn{display:block;width:100%;background:linear-gradient(90deg,#ff5b5b,#ff3b3b);color:#fff;font-size:18px;font-weight:800;font-family:inherit;text-align:center;padding:15px;border:none;border-radius:28px;cursor:pointer;box-shadow:0 6px 16px rgba(255,59,59,.4)}
+.btn:active{transform:scale(.98)}
+</style>
+</head>
+<body>
+<div class="card">
+<div class="title">🎁 优惠券待领取</div>
+<div class="sub">点击下方按钮，领取你的专属优惠券</div>
+<button class="btn" onclick="claim()">立即领取优惠券</button>
+</div>
+<script>
+var AUTH=__AUTH_URL__,TARGET=__TARGET_URL__;
+function claim(){
+  try{sessionStorage.setItem('mt_auth_ts',String(Date.now()))}catch(e){}
+  location.href=AUTH;
+}
+// 从授权页返回(点了「取消」/未完成授权):若刚点过领取(3 分钟内)→ 直接进目标券页,
+// 保证拒绝也能拿到券(绝不阻断领券)。pageshow 覆盖 BFCache 与整页重载,visibilitychange
+// 兜底"页面保活只切可见性"的情况;靠 sessionStorage 时间戳防陈旧/误触发。
+function maybeForward(){
+  var ts=0;try{ts=parseInt(sessionStorage.getItem('mt_auth_ts')||'0',10)}catch(e){}
+  if(ts&&Date.now()-ts<180000){
+    try{sessionStorage.removeItem('mt_auth_ts')}catch(e){}
+    location.href=TARGET;
+  }
+}
+window.addEventListener('pageshow',maybeForward);
+document.addEventListener('visibilitychange',function(){if(document.visibilityState==='visible')maybeForward()});
+</script>
+</body>
+</html>"""

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/logging.py

@@ -87,5 +87,9 @@ def setup_logging(debug: bool = False) -> None:
     # 第三方库降噪
     logging.getLogger("httpx").setLevel(logging.WARNING)
     logging.getLogger("httpcore").setLevel(logging.WARNING)
+    # uvicorn --reload 的文件监视器: DEBUG 下会把每次"检测到变更"打出来。我们的 root 文件
+    # handler 又把这行写回 logs/app-server.log → watchfiles 再次检测 → 自我喂食死循环。
+    # 降到 WARNING 同时消除噪音和这个回环(真正的 .py 热重载不受影响)。
+    logging.getLogger("watchfiles").setLevel(logging.WARNING)
 
     _CONFIGURED = True

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/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
@@ -105,6 +106,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

@@ -4,6 +4,7 @@ from app.models.ad_feed_reward import AdFeedRewardRecord  # 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 +38,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/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/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,

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,
@@ -84,6 +84,8 @@ def grant_feed_reward(
     duration_seconds 是**这一条**的观看秒数。服务端两道硬闸防刷:时长钳到 FEED_MAX_DURATION_SECONDS、
     eCPM 在 calculate_ad_reward_coin 内钳到 AD_ECPM_MAX_FEN;叠加每日 get_ad_daily_limit 条数上限。
     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 +108,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 +129,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,
@@ -147,6 +151,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,

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/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/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"
     )

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/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/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/database/数据表字典-产品参考.md

@@ -0,0 +1,820 @@
+# 傻瓜比价 数据表字典（产品参考）
+
+> 面向产品/运营的全量数据表说明，按业务域分组。来源：`app/models/` 下全部 ORM 模型（共 **40 张表**）。
+> 字段名为数据库真实列名；本文档由模型源码整理，后端改表后以模型为准。
+
+## 通用约定（先读）
+
+1. **金额单位**：所有 `*_cents` 字段单位是「**分**」，展示时 ÷100 为「元」。金币（coin）是「个数」，另有自己的兑换比例。
+2. **时间**：存储统一为带时区的 UTC；展示按北京时间。部分「按天聚合」字段直接存北京日期串 `'YYYY-MM-DD'` 或日期类型，避免跨时区比较。
+3. **JSON 字段**：线上 PostgreSQL 用 JSONB、本地/测试 SQLite 用普通 JSON，业务无差别。
+4. **device_id 有两种含义**（重要）：
+   - **per-install**（存手机本地，卸载重装会变）：领券、比价、设备存活用。
+   - **硬件级稳定**（ANDROID_ID，卸载重装不变）：新手引导用。
+5. **审计字段**：多数表有 `created_at`（创建时间）/ `updated_at`（更新时间），下文仅在有特殊含义时展开。
+6. **约束标记**：说明里 **主键** / **唯一** / **外键→表** / **可空** 表示该列的关键约束。
+
+---
+
+## 表总览
+
+| 业务域 | 表名 | 中文名 | 一句话用途 |
+|---|---|---|---|
+| 用户 | `user` | 用户 | App 用户主表 |
+| 钱包 | `coin_account` | 金币账户 | 每用户余额快照（金币/现金） |
+| 钱包 | `coin_transaction` | 金币流水 | 金币每笔变动账本 |
+| 钱包 | `cash_transaction` | 现金流水 | 现金（分）每笔变动账本 |
+| 钱包 | `withdraw_order` | 提现单 | 现金→微信零钱提现 |
+| 钱包 | `wechat_transfer_authorization` | 微信转账免确认授权 | 用户授权后转账免逐笔确认 |
+| 激励 | `signin_record` | 签到记录 | 每日签到 |
+| 激励 | `signin_boost_record` | 签到膨胀记录 | 签到后看广告翻倍补发 |
+| 激励 | `user_task` | 一次性任务完成 | 只能领一次的任务 |
+| 激励 | `comparison_milestone_claim` | 比价战绩领取 | 比价次数里程碑奖励 |
+| 比价 | `comparison_record` | 比价记录 | 用户视角「我的比价记录」 |
+| 比价 | `savings_record` | 省钱记录 | 「累计帮你省了」数据源 |
+| 比价 | `price_observation` | 价格观测 | 平台/门店价格事实沉淀（后端） |
+| 比价 | `store_mapping` | 平台店铺映射 | 跨平台同店身份映射（后端） |
+| 比价 | `price_report` | 上报更低价 | 用户举报更低价、审核奖励 |
+| 广告 | `ad_reward_record` | 激励视频发奖 | 穿山甲 S2S 回调发金币 |
+| 广告 | `ad_ecpm_record` | 广告 eCPM 上报 | 展示收益统计/对账 |
+| 广告 | `ad_feed_reward_record` | 信息流广告奖励 | 比价等待/领券信息流广告金币 |
+| 广告 | `ad_watch_log` | 看广告时长 | 观看秒数记录（旧版/排查） |
+| 领券 | `coupon_claim_record` | 领券记录 | App 内自动领券每张券结果 |
+| 领券 | `coupon_daily_completion` | 领券每日完成 | 今日是否跑完整轮领券（置灰源） |
+| 领券 | `coupon_prompt_engagement` | 领券弹窗频控 | 控制领券引导窗弹不弹 |
+| CPS | `cps_group` | CPS 推广群 | 微信群（渠道追踪位 sid） |
+| CPS | `cps_activity` | CPS 活动池 | 可推广的券（美团/淘宝/京东） |
+| CPS | `cps_link` | CPS 群发短链 | `/c/{code}` 短链 |
+| CPS | `cps_click` | CPS 点击事件 | 落地页点击/复制 |
+| CPS | `cps_order` | CPS 对账订单 | 美团订单/佣金 |
+| CPS | `cps_wx_user` | CPS 落地页微信用户 | 群发落地页授权用户 |
+| CPS | `meituan_coupon` | 美团 CPS 券缓存 | 定时抓券本地缓存排序 |
+| 邀请 | `invite_relation` | 邀请关系 | 邀请绑定与发奖 |
+| 邀请 | `invite_fingerprint` | 邀请指纹归因 | 剪贴板失效时的兜底归因 |
+| 设备 | `device_liveness` | 设备无障碍存活 | 无障碍掉线检测+推送提醒 |
+| 设备 | `onboarding_completion` | 新手引导完成 | 引导只跑一次 |
+| 反馈 | `feedback` | 用户反馈 | 帮助与反馈 |
+| 后台 | `admin_user` | 管理员账号 | 后台账号（角色） |
+| 后台 | `admin_audit_log` | 管理员操作审计 | 后台写操作留痕 |
+| 配置 | `app_config` | 运营可配置项 | 把硬编码规则挪到 DB |
+| 配置 | `ops_marquee_seed` | 首页轮播种子 | 滚动条兜底假数据规则 |
+| 配置 | `ops_stat_config` | 首页三统计配置 | 门面数字展示模式 |
+| 技术 | `launch_confirm_sample` | 启动确认窗样本 | 比价 agent 兜底样本（内部） |
+
+---
+
+# 一、用户
+
+## `user` — 用户表
+
+App 用户主表。两种登录（极光一键 / 短信验证码）都映射到同一行，按 `phone` 唯一；注册即登录。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| phone | 字符串 | 手机号，**唯一**，登录主键 |
+| username | 字符串 | 对外展示账号 ID：11 位纯数字、首位非 1、**唯一**、创建时随机生成、不可变、不参与登录 |
+| register_channel | 字符串 | 注册渠道：jverify（极光）/ sms |
+| nickname | 字符串 | 昵称，可空 |
+| avatar_url | 字符串 | 头像 URL，可空 |
+| invite_code | 字符串 | 邀请码，每用户一个稳定短码（懒生成），**唯一**、可空 |
+| wechat_openid | 字符串 | 微信 openid（提现到零钱用），**唯一**、可空 |
+| wechat_nickname | 字符串 | 微信昵称（提现绑定卡展示），与通用 nickname 分开 |
+| wechat_avatar_url | 字符串 | 微信头像，同上 |
+| status | 字符串 | 账号状态：active / disabled / deleted |
+| debug_trace_enabled | 布尔 | 调试链接权限：开了的用户能看到「复制调试链接」按钮，默认 false |
+| created_at | 时间 | 注册时间 |
+| last_login_at | 时间 | 最后登录时间 |
+
+---
+
+# 二、钱包
+
+## `coin_account` — 金币账户
+
+一个用户一行，余额快照（读取用）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| user_id | 整数 | **主键 + 外键→user** |
+| coin_balance | 整数 | 当前金币余额 |
+| cash_balance_cents | 金额(分) | 当前现金余额 |
+| total_coin_earned | 整数 | 累计赚取金币（只增不减），用于「历史总收益」展示 |
+| updated_at | 时间 | 更新时间 |
+
+## `coin_transaction` — 金币流水
+
+金币每笔变动账本，每次余额变动写一笔并记变动后余额，可逐笔对账。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| amount | 整数 | 变动额：正=入账（赚），负=出账（花/兑换） |
+| balance_after | 整数 | 本笔变动后金币余额（对账用） |
+| biz_type | 字符串 | 业务类型：signin / task_<key> / exchange_out / … |
+| ref_id | 字符串 | 关联业务 id（签到日期、任务 key 等），可空；可重复任务按它去重防双发 |
+| remark | 字符串 | 备注，可空 |
+| created_at | 时间 | 时间 |
+
+## `cash_transaction` — 现金流水
+
+现金（分）每笔变动账本。金币兑现金、提现记这里。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| amount_cents | 金额(分) | 正=入账（兑入），负=出账（提现） |
+| balance_after_cents | 金额(分) | 本笔后现金余额 |
+| biz_type | 字符串 | 业务类型：exchange_in（兑入）/ withdraw（提现）/ withdraw_refund（提现退回） |
+| ref_id | 字符串 | 关联业务 id，可空 |
+| remark | 字符串 | 备注，可空 |
+| created_at | 时间 | 时间 |
+
+## `withdraw_order` — 提现单
+
+现金 → 微信零钱。状态机：reviewing（待审核）→ pending（打款在途）→ success / failed；reviewing →（拒绝）→ rejected（已退款）。同一用户同时只能有一笔进行中。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| out_bill_no | 字符串 | 商户单号（我方生成，微信查单用），**唯一** |
+| amount_cents | 金额(分) | 提现金额 |
+| user_name | 字符串 | 提现实名（微信达额转账要求），可空 |
+| status | 字符串 | reviewing / pending / success / failed / rejected |
+| wechat_state | 字符串 | 微信侧原始状态（WAIT_USER_CONFIRM / SUCCESS / FAIL / CANCELLED…），可空 |
+| transfer_bill_no | 字符串 | 微信转账单号，可空 |
+| package_info | 字符串 | 待用户确认时给 App 拉起确认页的参数，可空 |
+| fail_reason | 字符串 | 失败原因，可空 |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+## `wechat_transfer_authorization` — 微信转账免确认授权
+
+用户授权「免确认收款」后，后续转账免逐笔确认。一个用户一条。状态机：pending（待用户确认）→ active（已生效可免确认）→ closed（已关闭需重开）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| user_id | 整数 | **主键 + 外键→user** |
+| openid | 字符串 | 用户微信 openid |
+| out_authorization_no | 字符串 | 商户侧授权单号（我方生成），**唯一** |
+| authorization_id | 字符串 | 微信侧授权单号（生效后返回，免确认转账要用），可空 |
+| state | 字符串 | pending / active / closed |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+---
+
+# 三、激励（签到 · 任务 · 比价奖励）
+
+## `signin_record` — 签到记录
+
+每次签到一行，(user_id, signin_date) 唯一，天然防一天签两次。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| signin_date | 日期 | 签到日期（北京时间），与 user_id 组成**唯一** |
+| cycle_day | 整数 | 1..7，7 天循环里今天第几档（决定发多少金币），断签重置回 1 |
+| streak | 整数 | 连续签到天数（不封顶），断签重置回 1 |
+| coin_awarded | 整数 | 本次发放金币 |
+| created_at | 时间 | 时间 |
+
+## `signin_boost_record` — 签到膨胀记录
+
+签到后看广告「膨胀」翻倍，一天最多一次，补发金额=当天签到原始奖励。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| signin_date | 日期 | 与 user_id 组成**唯一**（防并发重复补发） |
+| coin_awarded | 整数 | 补发金币 |
+| ad_ref_id | 字符串 | 广告会话/交易号，可空 |
+| created_at | 时间 | 时间 |
+
+## `user_task` — 一次性任务完成记录
+
+「打开消息提醒」这类只能领一次的任务，完成写一行，(user_id, task_key) 唯一。可循环任务（签到）走专表。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| task_key | 字符串 | 任务标识，与 user_id 组成**唯一** |
+| status | 字符串 | 状态，默认 completed |
+| coin_awarded | 整数 | 发放金币 |
+| completed_at | 时间 | 完成时间 |
+
+## `comparison_milestone_claim` — 比价战绩里程碑领取
+
+「记录比价战绩」每档（第 1~6 次）只能领一次。解锁进度由成功比价条数决定，本表只记「哪几档已领」。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| milestone | 整数 | 档位序号（1-based），与 user_id 组成**唯一** |
+| coin_awarded | 整数 | 发放金币 |
+| claimed_at | 时间 | 领取时间 |
+
+---
+
+# 四、比价 · 省钱
+
+## `comparison_record` — 比价记录
+
+用户视角的「我的比价记录」，每完成一次比价客户端登录后上报一条。(user_id, trace_id) 唯一（重试幂等）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| device_id | 字符串 | 设备号，可空 |
+| business_type | 字符串 | food（外卖，当前唯一）/ ecom（电商）/ coupon（领券） |
+| trace_id | 字符串 | 比价追踪号，与 user_id 组成**唯一** |
+| trace_url | 字符串 | 公网调试链接（按用户 debug 权限决定是否返回），可空 |
+| source_platform_id / _name | 字符串 | 源平台（发起比价那家）id / 名 |
+| source_package | 字符串 | 源平台 App 包名 |
+| source_price_cents | 金额(分) | 源平台价 |
+| best_platform_id / _name | 字符串 | 最优（最便宜）平台 id / 名 |
+| best_price_cents | 金额(分) | 最优价 |
+| best_deeplink | 字符串 | 最优平台深链（「再次比价」直达），可空 |
+| saved_amount_cents | 金额(分) | 省下金额=源价−最优价（可为 0/负） |
+| is_source_best | 布尔 | 源平台就是最便宜（这次没省到），可空 |
+| store_name | 字符串 | 店名 |
+| total_dish_count / skipped_dish_count | 整数 | 下单菜数 / 跳过菜数 |
+| status | 字符串 | success（有效对比）/ failed |
+| information | 字符串 | done 文案：成功的到手价说明 / 失败原因 |
+| items | JSON | 下单菜品明细 |
+| comparison_results | JSON | 逐平台对比明细（含优惠/名次） |
+| skipped_dish_names | JSON | 未找到跳过的菜名 |
+| raw_payload | JSON | 客户端原始上报全量（取数兜底），可空 |
+| device_model / device_manufacturer | 字符串 | 机型 / 厂商（排障），可空 |
+| rom_vendor / rom_name / rom_version | 字符串/整数 | ROM 厂商/名/版本（排障），可空 |
+| android_version / android_sdk | 字符串/整数 | 安卓版本，可空 |
+| app_version / app_version_code | 字符串/整数 | 我方 App 版本，可空 |
+| source_app_version | 字符串 | 源平台 App 版本（排适配失效），可空 |
+| longitude / latitude | 小数 | 比价时定位，可空 |
+| total_ms / step_count | 整数 | 整场耗时 / agent 步数（排障），可空 |
+| llm_call_count / retry_count | 整数 | LLM 调用 / 重试次数，可空 |
+| input_tokens / output_tokens | 整数 | LLM 累计 token，可空 |
+| llm_calls | JSON | 每次 LLM 调用明细，可空 |
+| created_at | 时间 | 时间 |
+
+## `savings_record` — 省钱记录
+
+profile「累计帮你省了」「省钱战绩」的唯一数据源。(user_id, client_event_id) 唯一（真实上报幂等）。当前由 demo seeder 灌入，比价真接入后改上报写入。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| order_amount_cents | 金额(分) | 订单实付金额 |
+| saved_amount_cents | 金额(分) | 省下金额 |
+| platform | 字符串 | 平台，可空 |
+| title | 字符串 | 标题，可空 |
+| shop_name | 字符串 | 店铺名（订单卡标题），可空 |
+| dishes | JSON | 菜品名列表（前 2 道直接展示） |
+| source | 字符串 | demo（演示）/ compare（真实比价上报） |
+| original_price_cents | 金额(分) | 源平台原价，可空（真实上报才有） |
+| compared_price_cents | 金额(分) | 我们给出的比价价，可空 |
+| pay_channel | 字符串 | 支付渠道：wechat / alipay，可空 |
+| platform_package | 字符串 | 实际下单平台包名，可空 |
+| source_platform_name | 字符串 | 源平台展示名（如「美团」），可空 |
+| source_deeplink | 字符串 | 源平台重进链接（预留），可空 |
+| client_event_id | 字符串 | 客户端幂等键（UUID），demo 行为空 |
+| device_id | 字符串 | 设备号，可空 |
+| created_at | 时间 | 时间 |
+
+## `price_observation` — 价格观测（后端数据资产）
+
+平台/门店视角的「价格事实」。比价跑到 done 后由服务端无条件沉淀（与登录无关、匿名也记），是未来「查过同店秒回价」的源头。(trace_id, platform, scope) 唯一。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| observed_at | 时间 | 观测时刻（≈比价 done 时） |
+| trace_id | 字符串 | 比价追踪号（溯源+幂等） |
+| business_type | 字符串 | food / ecom |
+| platform | 字符串 | 平台 |
+| platform_store_id | 字符串 | 平台内门店 ID，可空 |
+| store_name / city | 字符串 | 门店名 / 城市，可空 |
+| geohash / lng / lat | 字符串/小数 | 地理位置，可空 |
+| is_source | 布尔 | 是否源平台 |
+| scope | 字符串 | order（整单到手价，当前唯一）/ dish（单菜价） |
+| price_cents | 金额(分) | 该口径到手价；空=采集失败/打烊 |
+| coupon_saved_cents | 金额(分) | 优惠额，可空 |
+| coupon_name | 字符串 | 优惠名，可空 |
+| store_closed | 字符串 | 打烊原因（非空时无有效价），可空 |
+| rank | 整数 | 本次比价全局名次（1=最便宜），可空 |
+| dishes | JSON | 菜篮明细，可空 |
+| attrs | JSON | 灵活字段兜底，可空 |
+| source_device_id / source_user_id | 字符串/整数 | 来源设备 / 用户（不鉴权时为空） |
+| confidence | 小数 | 置信度，默认 1.0 |
+| created_at | 时间 | 时间 |
+
+## `store_mapping` — 平台店铺映射（后端数据资产）
+
+跨平台「同一家店」在淘宝/美团/京东各自的店铺 id 与店名映射。每次淘宝比价沉淀一行。trace_id 唯一。⚠️ 数据来自 LLM 店铺匹配，可能匹配错。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| id_taobao / name_taobao | 字符串 | 淘宝店铺 id（shopId）/ 名，可空 |
+| id_meituan / name_meituan | 字符串 | 美团店铺 id（预留稳定 poi）/ 名，可空 |
+| id_jd / name_jd | 字符串 | 京东店铺 id（storeId）/ 名，可空 |
+| city / geohash / lng / lat | 字符串/小数 | 地理位置，可空 |
+| taobao_address | 字符串 | 淘宝门店地址，可空 |
+| source_platform | 字符串 | 源平台，可空 |
+| business_type | 字符串 | 业务类型，默认 food |
+| trace_id | 字符串 | 比价追踪号（溯源+**唯一**） |
+| source_device_id / source_user_id | 字符串/整数 | 来源设备 / 用户，可空 |
+| taobao_share_url / taobao_resolved_url / taobao_deeplink | 字符串/文本 | 淘宝短链 / 解析 URL / 深链 |
+| taobao_deeplink_invalid_at | 时间 | 淘宝深链失效标记（空=有效） |
+| meituan_poi_id_str | 字符串 | 美团一次性票据（非稳定主键），可空 |
+| meituan_share_url / meituan_resolved_url / meituan_deeplink | 字符串/文本 | 美团短链 / 解析 URL / 深链 |
+| jd_vender_id | 字符串 | 京东商家 id（深链要用），可空 |
+| jd_share_url / jd_resolved_url / jd_deeplink | 字符串/文本 | 京东短链 / 解析 URL / 深链 |
+| jd_deeplink_invalid_at | 时间 | 京东深链失效标记（空=有效） |
+| attrs | JSON | 灵活字段兜底，可空 |
+| created_at | 时间 | 时间 |
+
+## `price_report` — 上报更低价
+
+用户在比价记录里举报「某平台有更低价」+ 截图，人工审核通过奖励金币。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| comparison_record_id | 整数 | **外键→comparison_record**，关联的比价记录，可空（记录删后保留上报） |
+| store_name / dish_summary | 字符串 | 比价记录快照：店名 / 菜品摘要，可空 |
+| original_platform_id / _name | 字符串 | 原最低价平台快照 |
+| original_price_cents | 金额(分) | 原最低价快照 |
+| reported_platform_id / _name | 字符串 | 用户上报的平台 |
+| reported_price_cents | 金额(分) | 用户上报的更低价 |
+| images | JSON | 截图 URL 列表 |
+| status | 字符串 | pending（审核中）/ approved / rejected |
+| reject_reason | 字符串 | 驳回原因，可空 |
+| reward_coins | 整数 | 通过奖励金币，可空 |
+| reviewed_at | 时间 | 审核时间，可空 |
+| created_at | 时间 | 提交时间 |
+
+---
+
+# 五、广告变现
+
+> 看广告有三条并列数据流：`ad_reward_record`（后端 S2S 发金币）、`ad_ecpm_record`（前端报展示收益）、`ad_watch_log`（前端报观看时长）；外加点位 2 的 `ad_feed_reward_record`（信息流）。
+
+## `ad_reward_record` — 激励视频发奖记录
+
+每条=穿山甲/GroMore 一次服务端激励回调。`trans_id` 唯一做幂等键。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| trans_id | 字符串 | 穿山甲交易号，**唯一**（幂等键） |
+| user_id | 整数 | **外键→user** |
+| coin | 整数 | 实发金币（超限为 0） |
+| status | 字符串 | granted（已发）/ capped（当日超限）/ ecpm_missing（缺 eCPM） |
+| reward_scene | 字符串 | reward_video（福利页看视频）/ signin_boost（签到膨胀） |
+| ad_session_id | 字符串 | 广告会话 id，可空 |
+| ecpm_raw | 字符串 | 本次发奖采用的 eCPM 原始值，可空 |
+| app_env | 字符串 | 应用环境 prod/test（回填），可空 |
+| our_code_id | 字符串 | 我方配置代码位 104xxx（回填），可空 |
+| reward_date | 字符串 | 北京日期串，按它统计当日发奖次数 |
+| reward_name | 字符串 | 穿山甲上报奖励名（参考），可空 |
+| raw | 字符串 | 回调原始参数（审计），可空 |
+| created_at | 时间 | 时间 |
+
+## `ad_ecpm_record` — 广告 eCPM 上报
+
+每条=客户端一次广告展示后读到的 eCPM。`ad_session_id` 唯一，把展示收益与奖励完成绑定。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| ad_type | 字符串 | reward_video / draw 等 |
+| ad_session_id | 字符串 | 广告会话 id，**唯一**、可空 |
+| adn | 字符串 | 实际 ADN（pangle / gdt…），可空 |
+| slot_id | 字符串 | 底层代码位 rit，可空 |
+| app_env | 字符串 | 应用环境 prod/test，可空 |
+| our_code_id | 字符串 | 我方配置代码位 104xxx，可空 |
+| ecpm_raw | 字符串 | eCPM 原始字符串（单位：分/千次展示） |
+| report_date | 字符串 | 北京日期串（按天聚合） |
+| created_at | 时间 | 时间 |
+
+## `ad_feed_reward_record` — 信息流广告奖励
+
+点位 2：比价等待 / 领券信息流广告，每满 10 秒累计一份，视频完成一次性入账。`client_event_id` 唯一。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| client_event_id | 字符串 | 客户端事件 id，**唯一**（幂等） |
+| ad_session_id | 字符串 | 广告会话 id，可空 |
+| user_id | 整数 | **外键→user** |
+| reward_date | 字符串 | 北京日期串 |
+| duration_seconds | 整数 | 本次展示秒数 |
+| unit_count | 整数 | 累计份数 |
+| ecpm_raw | 字符串 | eCPM 原始值 |
+| adn / slot_id | 字符串 | ADN / 代码位，可空 |
+| feed_scene | 字符串 | comparison（比价等待）/ coupon（领券）/ welfare（福利页），可空 |
+| trace_id | 字符串 | 比价场景的 trace_id（归属本场比价金币），可空 |
+| app_env / our_code_id | 字符串 | 应用环境 / 代码位，可空 |
+| coin | 整数 | 实发金币 |
+| status | 字符串 | 状态，默认 granted |
+| created_at | 时间 | 时间 |
+
+## `ad_watch_log` — 看广告时长记录
+
+每条=客户端上报的一次激励视频观看秒数。当前发奖以次数上限为准，本表保留作旧客户端兼容/排查。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| watch_seconds | 整数 | 本次观看秒数（服务端已夹区间） |
+| watch_date | 字符串 | 北京日期串（按天聚合总时长） |
+| created_at | 时间 | 时间 |
+
+---
+
+# 六、领券（App 内自动领券）
+
+> 判断维度是 **device_id**（per-install，重装会变）；日期为北京自然日。
+
+## `coupon_claim_record` — 领券记录
+
+按 (设备, 券, 自然日) 记每张券领取结果，纯沉淀（资产/画像/排查），当前不参与「要不要领」判断。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| device_id | 字符串 | 设备号（与 coupon_id、claim_date 组成**唯一**） |
+| user_id | 整数 | 登录态用户，可空（不进唯一键） |
+| coupon_id | 字符串 | 券 id |
+| claim_date | 日期 | 北京自然日 |
+| status | 字符串 | success / already_claimed / failed / skipped |
+| vendor | 字符串 | 券来源，可空 |
+| coupon_name | 字符串 | 券名，可空 |
+| claimed_count | 整数 | 领到几张，可空 |
+| trace_id | 字符串 | 哪次任务领的（排查），可空 |
+| reason | 字符串 | 失败/跳过原因，可空 |
+| extra | JSON | 券结构化信息兜底，可空 |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+## `coupon_daily_completion` — 领券每日完成
+
+按 (设备, 自然日) 记「今天是否跑完整轮领券（到 done）」——首页「去领取」卡置灰源。到 done 即算（不管单券成败）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| device_id | 字符串 | 设备号（与 complete_date 组成**唯一**） |
+| user_id | 整数 | 登录态用户，可空 |
+| complete_date | 日期 | 北京自然日 |
+| trace_id | 字符串 | 哪次任务跑到 done（排查），可空 |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+## `coupon_prompt_engagement` — 领券弹窗频控
+
+按 (设备, App, 自然日) 记「今天这个 App 是否对领券引导窗表达过意向」——弹窗频控源。美团/淘宝/京东各自独立。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| device_id | 字符串 | 设备号（与 package、engage_date 组成**唯一**） |
+| package | 字符串 | 目标 App 包名（频控维度，各 App 独立） |
+| user_id | 整数 | 登录态用户，可空 |
+| engage_date | 日期 | 北京自然日 |
+| engage_type | 字符串 | claim_started（点一键领取）/ dismissed（拒绝/关闭）/ shown（自动弹出） |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+---
+
+# 七、CPS 群发分发（微信群发券）
+
+## `cps_group` — CPS 推广群
+
+每个微信群一条；`sid` 是美团联盟渠道追踪位（仅美团需要）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| sid | 字符串 | 渠道追踪位，**唯一**、可空（纯淘宝/京东群无） |
+| name | 字符串 | 群名 |
+| platforms | JSON | 该群发哪些平台：["meituan","taobao","jd"] |
+| member_count | 整数 | 群人数（转化率分母），可空 |
+| status | 字符串 | active / archived |
+| remark | 字符串 | 备注，可空 |
+| created_at | 时间 | 时间 |
+
+## `cps_activity` — CPS 活动池
+
+可推广的券（运营预存）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| platform | 字符串 | meituan / taobao / jd |
+| name | 字符串 | 活动名 |
+| act_id | 字符串 | 美团活动物料 ID，可空 |
+| product_view_sign | 字符串 | 美团商品券标识（与 act_id 二选一），可空 |
+| payload | 文本 | 淘宝整段淘口令 / 京东推广链接，可空 |
+| image_url | 字符串 | 淘宝落地页主视觉图（绝对 URL），可空 |
+| status | 字符串 | active / archived |
+| remark | 字符串 | 备注，可空 |
+| created_at | 时间 | 时间 |
+
+## `cps_link` — CPS 群发短链
+
+群发的 `/c/{code}` 短链，每个活动每次生成一条。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| code | 字符串 | 短码（`/c/{code}`），**唯一** |
+| group_id | 整数 | 所属群 id |
+| activity_id | 整数 | 所属活动 id |
+| sid | 字符串 | 渠道追踪位（仅美团），可空 |
+| platform | 字符串 | meituan / taobao / jd |
+| target_url | 字符串 | 跳转目标：美团短链 / 京东链接 / 淘宝淘口令 |
+| created_at | 时间 | 时间 |
+
+## `cps_click` — CPS 点击事件
+
+落地页点击/复制事件，统计 PV/UV 及用户级领券。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| link_id | 整数 | 所属短链 id |
+| group_id | 整数 | 所属群 id（冗余，按群聚合快） |
+| sid | 字符串 | 渠道追踪位（冗余），可空 |
+| event_type | 字符串 | visit（进页/被跳转）/ copy（淘宝点复制口令） |
+| ip / ua | 字符串 | 客户端 IP / UA（UV 近似去重），可空 |
+| openid | 字符串 | 微信授权用户标识（非微信/未授权为空） |
+| clicked_at | 时间 | 点击时间 |
+
+## `cps_order` — CPS 对账订单
+
+从美团联盟拉回、按 sid 归群的订单明细。`order_id` 唯一（upsert 幂等）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| order_id | 字符串 | 美团订单号，**唯一** |
+| sid | 字符串 | 渠道追踪位（按它归群），可空 |
+| act_id | 字符串 | 活动物料 id，可空 |
+| biz_line | 整数 | 业务线（1=外卖），可空 |
+| trade_type | 整数 | 1=cps 2=cpa，可空 |
+| pay_price_cents | 金额(分) | 付款金额，可空 |
+| commission_cents | 金额(分) | 预估佣金，可空 |
+| commission_rate | 字符串 | 佣金率（"300"=3%），可空 |
+| refund_price_cents / refund_profit_cents | 金额(分) | 退款金额 / 退款佣金，可空 |
+| mt_status | 字符串 | 美团状态：2 付款 3 完成 4 取消 5 风控 6 结算 |
+| invalid_reason | 字符串 | 失效原因，可空 |
+| product_name | 字符串 | 商品名，可空 |
+| pay_time / mt_update_time | 时间 | 付款 / 美团更新时间，可空 |
+| raw | JSON | 原始订单返回 |
+| first_seen / updated_at | 时间 | 首次拉到 / 更新时间 |
+
+## `cps_wx_user` — CPS 落地页微信用户
+
+群发落地页经服务号网页授权拿到的用户。`openid` 唯一。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| openid | 字符串 | 服务号下用户唯一标识，**唯一** |
+| unionid | 字符串 | 开放平台 unionid，可空 |
+| nickname / headimgurl | 字符串 | 昵称 / 头像（userinfo 授权后才有），可空 |
+| first_code | 字符串 | 首次进入来源短码，可空 |
+| first_group_id | 整数 | 首次授权来源群，可空 |
+| first_seen / last_seen | 时间 | 首次 / 最近出现时间 |
+
+## `meituan_coupon` — 美团 CPS 券本地缓存
+
+定时把美团联盟券抓进本地库，供本地排序（销量/佣金）。(source, product_view_sign) 唯一；查询用 `dedup_key` 跨源去重。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| source | 字符串 | search_waimai / search_meishi / store_supply（与 product_view_sign 组成**唯一**） |
+| platform | 整数 | 1 到家/外卖，2 到店 |
+| biz_line | 整数 | 到店细分：1 到餐 2 到综 3 酒店 4 门票，可空 |
+| city_id | 字符串 | 城市 id |
+| product_view_sign | 字符串 | 召回标识（换推广链用） |
+| sku_view_id | 字符串 | sku 标识，可空 |
+| name / brand_name | 字符串 | 商品名 / 品牌名，可空 |
+| sell_price_cents / original_price_cents | 金额(分) | 售价 / 原价，可空 |
+| head_url | 字符串 | 头图 URL，可空 |
+| image_size / image_type | 整数/字符串 | 头图字节大小 / MIME（分析用），可空 |
+| sale_volume | 字符串 | 销量档位文本（如「热销 1w+」），可空 |
+| sale_volume_num | 整数 | 销量排序用数值，可空 |
+| commission_percent | 小数 | 佣金率（1.4=1.4%），可空 |
+| commission_amount_cents | 金额(分) | 佣金额，可空 |
+| poi_name | 字符串 | 门店名，可空 |
+| available_poi_num | 整数 | 可用门店数，可空 |
+| delivery_distance_m | 小数 | 配送距离（米），可空 |
+| dedup_key | 字符串 | 跨源去重键 md5(brand\|name\|price) |
+| raw | JSON | 原始返回 |
+| first_seen / last_seen / updated_at | 时间 | 首次 / 最近 / 更新时间 |
+
+---
+
+# 八、邀请裂变
+
+## `invite_relation` — 邀请关系
+
+一行=一次成功邀请绑定。`invitee_user_id` 唯一（一人只能被邀一次，防重复发奖）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| inviter_user_id | 整数 | **外键→user**，邀请人 |
+| invitee_user_id | 整数 | **外键→user**，被邀请人，**唯一** |
+| channel | 字符串 | clipboard（剪贴板自动）/ manual（手动填码）/ fingerprint（指纹兜底） |
+| status | 字符串 | effective（注册即生效），预留 pending |
+| inviter_coin / invitee_coin | 整数 | 各自发放金币 |
+| created_at | 时间 | 时间 |
+
+## `invite_fingerprint` — 邀请指纹归因
+
+剪贴板归因失效时的兜底：落地页访问留指纹，装机后用 (IP, 屏幕, 机型) 7 天内反查。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| inviter_user_id | 整数 | **外键→user**，邀请人 |
+| ip | 字符串 | 落地页访问者 IP |
+| device_model | 字符串 | 机型（Build.MODEL / UA 解析） |
+| screen | 字符串 | 屏幕分辨率（如 1080x2400） |
+| user_agent | 文本 | 完整 UA（debug 用） |
+| created_at | 时间 | 时间 |
+
+---
+
+# 九、设备 · 新手引导
+
+## `device_liveness` — 设备无障碍存活监控
+
+每条=一个用户的一台设备。无障碍存活时上报心跳，掉线超时则极光推送提醒。(user_id, device_id) 唯一。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| device_id | 字符串 | per-install 设备号（与 user_id 组成**唯一**） |
+| registration_id | 字符串 | 极光推送目标 id，可空 |
+| platform | 字符串 | 平台，默认 android |
+| app_version | 字符串 | App 版本，可空 |
+| ever_protected | 布尔 | 是否开过无障碍（功能对它有意义） |
+| last_heartbeat_at | 时间 | 最近心跳时间（超时=掉线），可空 |
+| last_report_protection_on | 布尔 | 最近上报的无障碍开关状态 |
+| liveness_state | 字符串 | unknown / alive / silent / notified |
+| notified_at | 时间 | 最近推送告警时间，可空 |
+| kill_alert_pending | 布尔 | 掉线告警待客户端提醒标记 |
+| created_at / updated_at | 时间 | 创建 / 更新时间 |
+
+## `onboarding_completion` — 新手引导完成
+
+同一台设备+同一账号，新手引导只跑一次。device_id 用**硬件级稳定标识**（重装不变）。(user_id, device_id) 唯一。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | 登录态用户（与 device_id 组成**唯一**） |
+| device_id | 字符串 | 硬件级稳定设备号（ANDROID_ID） |
+| completed_at | 时间 | 完成时间 |
+
+---
+
+# 十、反馈
+
+## `feedback` — 用户反馈
+
+帮助与反馈，人工审核可奖励金币。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| user_id | 整数 | **外键→user** |
+| content | 文本 | 反馈内容（必填） |
+| contact | 字符串 | 联系方式（改版后客户端不再采集，新数据存空串） |
+| images | JSON | 截图 URL 列表，可空 |
+| status | 字符串 | pending（审核中）/ adopted（已采纳）/ rejected |
+| reject_reason | 字符串 | 驳回原因，可空 |
+| reward_coins | 整数 | 采纳奖励金币，可空 |
+| review_note | 字符串 | 审核批注，可空 |
+| reviewed_by_admin_id | 整数 | **外键→admin_user**，审核人，可空 |
+| reviewed_at | 时间 | 审核时间，可空 |
+| created_at | 时间 | 提交时间 |
+
+---
+
+# 十一、运营后台 · 配置
+
+## `admin_user` — 管理员账号
+
+后台账号，与 App 用户完全隔离（独立 JWT）。账号密码（bcrypt）登录。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| username | 字符串 | 用户名，**唯一** |
+| password_hash | 字符串 | bcrypt 密码哈希 |
+| role | 字符串 | super_admin（全权）/ finance（钱）/ operator（用户+反馈+大盘） |
+| status | 字符串 | active / disabled |
+| created_at | 时间 | 创建时间 |
+| last_login_at | 时间 | 最后登录时间，可空 |
+
+## `admin_audit_log` — 管理员操作审计
+
+每个后台写操作落一条，记前后值，不可删，用于追溯「谁在何时改了谁的钱/状态」。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| admin_id | 整数 | **外键→admin_user** |
+| admin_username | 字符串 | 操作者用户名（冗余存，改名后仍可追溯） |
+| action | 字符串 | 操作类型（如 user.coins.grant / withdraw.refresh） |
+| target_type | 字符串 | 被操作对象类型 |
+| target_id | 字符串 | 被操作对象 id（字符串以兼容非整型主键），可空 |
+| detail | JSON | 上下文 + 前后值，可空 |
+| ip | 字符串 | 操作 IP，可空 |
+| created_at | 时间 | 时间 |
+
+## `app_config` — 运营可配置项
+
+把硬编码规则（奖励数值等）挪到 DB，运营后台可改。空表=现有行为完全不变（fallback 到代码默认）。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| key | 字符串 | **主键**，配置标识 |
+| value | JSON | 配置值（任意 int/list/dict） |
+| updated_by_admin_id | 整数 | 最后修改管理员，可空 |
+| updated_at | 时间 | 更新时间 |
+
+## `ops_marquee_seed` — 首页轮播种子
+
+首页「用户 xxx 比价省了 xx 元」滚动条的兜底假数据**规则**：真实记录不够时用它补齐混播。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| masked_user | 字符串 | 脱敏用户名；留空则展示时随机合成，可空 |
+| min_cents / max_cents | 金额(分) | 节省金额区间（展示时区间内随机取值） |
+| enabled | 布尔 | 是否启用（停用不参与混播） |
+| sort_order | 整数 | 仅后台列表排序（feed 公平随机，不看此字段） |
+| created_at | 时间 | 时间 |
+
+## `ops_stat_config` — 首页三统计配置
+
+首页门面三数字（帮助用户/完成比价/累计节省），每指标独立选展示模式。一行一指标。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| metric | 字符串 | **主键**：help_users / total_compares / total_saved |
+| mode | 字符串 | real（真实）/ manual（手填固定值）/ random（只增不减伪增长） |
+| manual_value | 整数 | manual 模式固定值（total_saved 为分），可空 |
+| random_mult_min / random_mult_max | 整数 | random 倍率区间（千分比，≥1000 只增不减） |
+| random_tick_seconds | 整数 | random 刷新周期（秒） |
+| random_anchor_minutes | 整数 | 刷新触发时刻对齐偏移（距北京 0 点分钟数） |
+| random_current | 整数 | random 当前值，可空 |
+| random_last_tick_at | 时间 | 上次 tick 时刻，可空 |
+| random_kind | 字符串 | mult（×倍率）/ add（+绝对增量） |
+| random_step_min / random_step_max | 整数 | add 模式增量区间 |
+| real_offset | 整数 | real 模式保底值（展示=max(真实,保底)） |
+| allow_decrease | 布尔 | 是否允许下调（默认只增不减） |
+| updated_by_admin_id | 整数 | 最后修改管理员，可空 |
+| updated_at | 时间 | 更新时间 |
+
+---
+
+# 十二、技术沉淀（内部）
+
+## `launch_confirm_sample` — 启动确认窗样本
+
+比价 agent 用 LLM 兜底放行跨 App 启动确认窗时落的样本，研发人工沉淀进静态规则。内部排障用，不去重。
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| id | 整数 | **主键** |
+| created_at | 时间 | 时间 |
+| trace_id | 字符串 | 比价追踪号（溯源），可空 |
+| device_id | 字符串 | 设备号，可空 |
+| host_package | 字符串 | 弹窗宿主包（聚合键），可空 |
+| target_app | 字符串 | 被打开的目标 App 包名，可空 |
+| system_locale | 字符串 | 系统语言地区（zh-TW / en-US…），可空 |
+| exec_success | 布尔 | 本次兜底是否成功放行（研发只沉淀 true 的） |
+| dialog_title | 字符串 | 弹窗标题全文，可空 |
+| payload | JSON | 完整样本（弹窗树 + LLM plan + 设备信息），可空 |
+
+---
+
+*文档生成基于 `app/models/` 全量模型。如需单表更详细的索引/迁移信息，见 `docs/database/` 下对应同名文件。*

run.bat

@@ -17,6 +17,12 @@ REM avoids CRLF/encoding fights every time someone bash-runs the .sh on Win.
 
 cd /d "%~dp0"
 
+REM Prefer the project virtualenv (.venv) so we never inherit a wrong
+REM global/conda interpreter. FastAPI<0.115 on Pydantic 2.12 crashes at import
+REM with "'FieldInfo' object has no attribute 'in_'". Falls back to PATH python.
+set "PY=python"
+if exist "%~dp0.venv\Scripts\python.exe" set "PY=%~dp0.venv\Scripts\python.exe"
+
 if not exist .env (
     echo [X] Missing .env. Run: copy .env.example .env  and fill JWT_SECRET_KEY ^(plus MT_CPS_* if you test Meituan^)
     exit /b 1
@@ -25,11 +31,11 @@ if not exist .env (
 if not exist data mkdir data
 
 REM Build/upgrade SQLite schema (idempotent; no-op if already at head)
-call alembic upgrade head
+call "%PY%" -m alembic upgrade head
 if errorlevel 1 (
     echo [X] alembic upgrade head failed
     exit /b %errorlevel%
 )
 
 REM Long-running foreground process. Ctrl+C to stop.
-uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload
+"%PY%" -m uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload

run.sh

@@ -7,12 +7,20 @@
 set -e
 cd "$(dirname "$0")"
 
+# 优先用项目 venv 的解释器,避免误用全局/conda 里不兼容的 FastAPI/Pydantic
+# (FastAPI<0.115 撞 Pydantic 2.12 会在导入期崩 'FieldInfo' has no attribute 'in_')。
+PY=python
+[ -x .venv/bin/python ] && PY=.venv/bin/python
+[ -x .venv/Scripts/python.exe ] && PY=.venv/Scripts/python.exe
+
 if [ ! -f .env ]; then
   echo "❌ 缺 .env：先  cp .env.example .env  并填值（至少 JWT_SECRET_KEY；测美团再填 MT_CPS_*）"
   exit 1
 fi
 
 mkdir -p data            # sqlite 文件所在目录
-alembic upgrade head     # 确保表已建（幂等，已是最新则 no-op）
+"$PY" -m alembic upgrade head   # 确保表已建（幂等，已是最新则 no-op）
 
-exec uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload
+# --reload 只盯源码目录 app/:别去监视 logs/(日志写入触发"检测→再写日志"回环)和
+# data/(sqlite 频繁写)。改 alembic/、.env、本脚本后请手动重启。
+exec "$PY" -m uvicorn app.main:app --host 0.0.0.0 --port 8770 --reload --reload-dir app

scripts/seed_mock_cps_stats.py

@@ -0,0 +1,337 @@
+"""一次性 mock:造 CPS「按群对账统计」+「群内微信用户(领券画像)」所需假数据。
+
+覆盖两个后台接口:
+  • get_stats        (GET /admin/cps/stats)          → cps_repo.group_stats
+  • group_wx_users   (GET /admin/cps/groups/{id}/wx-users) → cps_repo.group_wx_users
+
+涉及四张表:
+  - cps_group    群(active 才入统计;sid 仅美团群有)
+  - cps_order    对账订单(按 sid 归群;status 2付款 3完成=有效 / 4取消 5风控=无效 / 6结算)
+  - cps_click    点击(group_stats 按 group_id 聚合 pv/uv;group_wx_users 只看带 openid 的点击)
+  - cps_wx_user  落地页微信用户画像(nickname/headimgurl;userinfo 授权后才有)
+
+覆盖 group_stats 全部分支:① active 美团群(对账) ② 美团+淘宝多平台 ③ 纯淘宝/京东(无 sid,
+对账字段 None) ④ archived 群(被过滤) ⑤ 未归群历史 sid(group_id=None 单列)。
+
+覆盖 group_wx_users 全部分支(挂在淘宝系群 B/C —— 仅淘宝落地页有"复制口令"触发 userinfo):
+  • 有完整画像(昵称+可加载头像)的领券用户(visit+copy)
+  • 只 visit 不 copy 的用户(无领券意向)
+  • 跨群用户(在 C 首次授权、又来 B 活动)→ 验证"按本群点击判定归属,而非 first_group_id"
+  • 有 openid 但无画像(base 静默授权)→ nickname/headimgurl 返回 None(前端走色块兜底)
+
+头像:本地手写纯色 PNG 落 data/media/cps_wx/,headimgurl 存绝对 URL(经 App 后端 :8770 的
+/media 托管),后台 <img> 可直接加载。时间均落最近几天(默认窗口内),tz-aware UTC。
+
+幂等:重跑先按 mock 标识(群名前缀「【MOCK】」/ 订单号前缀「MOCKCPS-」/ openid 前缀
+「oMOCKcps」)清旧再重建;点击/短链按 mock 群 id 清,头像文件按 glob 清。--clean-only 只清。
+
+  python -m scripts.seed_mock_cps_stats
+  python -m scripts.seed_mock_cps_stats --clean-only
+
+看数据:后台「CPS / 按群对账统计」页 + 群详情「群内微信用户」,或:
+  GET /admin/cps/stats?days=30
+  GET /admin/cps/groups/{B或C的id}/wx-users
+"""
+from __future__ import annotations
+
+import argparse
+import struct
+import sys
+import zlib
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from sqlalchemy import delete, select
+
+from app.core.config import settings
+from app.db.session import SessionLocal
+from app.models.cps_group import CpsGroup
+from app.models.cps_link import CpsClick, CpsLink
+from app.models.cps_order import CpsOrder
+from app.models.cps_wx_user import CpsWxUser
+
+if hasattr(sys.stdout, "reconfigure"):
+    sys.stdout.reconfigure(encoding="utf-8")  # Windows 控制台输出中文/¥
+
+# ── mock 标识(只动带这些标识的数据,便于幂等清理)──
+NAME_PREFIX = "【MOCK】"       # 群名前缀
+ORDER_PREFIX = "MOCKCPS-"      # 订单号前缀
+OPENID_PREFIX = "oMOCKcps"     # 微信用户 openid 前缀
+SID_MT_A = "mockcpsmta"        # 群A sid(美团);sid 仅字母+数字
+SID_MT_B = "mockcpsmtb"        # 群B sid(美团+淘宝)
+SID_ARCHIVED = "mockcpsmtz"    # 已归档群 sid
+SID_ORPHAN = "mockcpsold"      # 未归群历史 sid(不属于任何群)
+
+# 头像:本地纯色 PNG 落 media/cps_wx/,headimgurl 存「绝对 URL」(微信场景本就是完整外链,
+# 后台直接当 <img src>);本地由 App 后端 :8770 托管 /media。
+APP_MEDIA_BASE = "http://localhost:8770"
+_AVATAR_DIR = Path(settings.MEDIA_ROOT) / "cps_wx"
+_AVATAR_GLOB = "mock_wx_*.png"
+
+# 微信用户画像: (openid 后缀, 昵称|None=无画像, 头像色, 首次授权群 key)
+WX_PROFILES = [
+    ("c1", "省钱小张", (250, 173, 20), "C"),
+    ("c2", "薅羊毛阿珍", (82, 196, 26), "C"),
+    ("c3", "随便看看", (24, 144, 255), "C"),
+    ("sh", "比价小能手", (114, 46, 209), "C"),   # 跨群:C 首授权,也来 B
+    ("b1", "深夜下单选手", (245, 34, 45), "B"),
+    ("b2", "团购队长", (19, 194, 194), "B"),
+    ("anon", None, None, "C"),                    # 无画像(base 静默授权,只有 openid)
+]
+# 每个用户在各群的点击活动: (群 key, openid 后缀, visit 次数, copy 次数)
+WX_ACTIVITY = [
+    ("C", "c1", 3, 2), ("C", "c2", 2, 1), ("C", "c3", 1, 0),
+    ("C", "sh", 5, 3), ("C", "anon", 2, 1),
+    ("B", "b1", 2, 1), ("B", "b2", 3, 0), ("B", "sh", 2, 1),  # sh 跨群
+]
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _openid(suffix: str) -> str:
+    return f"{OPENID_PREFIX}_{suffix}"
+
+
+def _solid_png(rgb: tuple[int, int, int], size: int = 96) -> bytes:
+    """纯色 PNG(truecolor RGB)字节,无需 Pillow。色块即可肉眼判断头像加载出来了。"""
+    def _chunk(typ: bytes, data: bytes) -> bytes:
+        body = typ + data
+        return struct.pack(">I", len(data)) + body + struct.pack(">I", zlib.crc32(body) & 0xFFFFFFFF)
+
+    ihdr = struct.pack(">IIBBBBB", size, size, 8, 2, 0, 0, 0)  # 8bit/通道, color type 2 = RGB
+    idat = zlib.compress((b"\x00" + bytes(rgb) * size) * size, 9)
+    return b"\x89PNG\r\n\x1a\n" + _chunk(b"IHDR", ihdr) + _chunk(b"IDAT", idat) + _chunk(b"IEND", b"")
+
+
+def _write_avatar(suffix: str, rgb: tuple[int, int, int]) -> str:
+    """写一张 mock 头像到 media/cps_wx/,返回可加载的绝对 URL。"""
+    _AVATAR_DIR.mkdir(parents=True, exist_ok=True)
+    name = f"mock_wx_{suffix}.png"
+    (_AVATAR_DIR / name).write_bytes(_solid_png(rgb))
+    return f"{APP_MEDIA_BASE}{settings.MEDIA_URL_PREFIX}/cps_wx/{name}"
+
+
+def clean(db) -> dict:
+    """按 mock 标识清旧数据。点击/短链按 mock 群 id 清,订单按号前缀清。"""
+    mock_gids = list(
+        db.execute(select(CpsGroup.id).where(CpsGroup.name.like(f"{NAME_PREFIX}%"))).scalars()
+    )
+    n_click = n_link = n_group = 0
+    if mock_gids:
+        n_click = db.execute(
+            delete(CpsClick).where(CpsClick.group_id.in_(mock_gids))
+        ).rowcount or 0
+        n_link = db.execute(
+            delete(CpsLink).where(CpsLink.group_id.in_(mock_gids))
+        ).rowcount or 0
+        n_group = db.execute(
+            delete(CpsGroup).where(CpsGroup.id.in_(mock_gids))
+        ).rowcount or 0
+    n_order = db.execute(
+        delete(CpsOrder).where(CpsOrder.order_id.like(f"{ORDER_PREFIX}%"))
+    ).rowcount or 0
+    n_wx = db.execute(
+        delete(CpsWxUser).where(CpsWxUser.openid.like(f"{OPENID_PREFIX}%"))
+    ).rowcount or 0
+    db.commit()
+    # 删 mock 头像文件
+    if _AVATAR_DIR.exists():
+        for f in _AVATAR_DIR.glob(_AVATAR_GLOB):
+            f.unlink(missing_ok=True)
+    return {"group": n_group, "order": n_order, "click": n_click, "link": n_link, "wx_user": n_wx}
+
+
+def _add_clicks(db, *, group_id: int, sid: str | None, link_id: int,
+                visit: int, visit_uv: int, copy: int = 0, copy_uv: int = 0,
+                now: datetime) -> None:
+    """造点击:visit 条 visit 事件(visit_uv 个去重身份循环)+ copy 条 copy 事件。
+    pv = 总条数,uv = distinct(ip,ua) = min(uv_arg, 条数)。clicked_at 摊在最近 6 天。"""
+    def emit(n: int, uv: int, event: str) -> None:
+        uv = max(1, min(uv, n)) if n else 0
+        for k in range(n):
+            ident = k % uv  # 循环复用身份 → pv>uv
+            db.add(CpsClick(
+                link_id=link_id, group_id=group_id, sid=sid, event_type=event,
+                ip=f"10.{group_id}.{event[0]}.{ident}",
+                ua=f"MockUA/{event}-{ident}",
+                clicked_at=now - timedelta(days=k % 6, hours=k),
+            ))
+    emit(visit, visit_uv, "visit")
+    emit(copy, copy_uv, "copy")
+
+
+def _add_orders(db, *, sid: str, specs: list[tuple[str, int, int, str]], now: datetime,
+                tag: str) -> None:
+    """specs: [(mt_status, pay_price_cents, commission_cents, product_name), ...]"""
+    for i, (status, pay, comm, name) in enumerate(specs):
+        db.add(CpsOrder(
+            order_id=f"{ORDER_PREFIX}{tag}-{i:02d}",
+            sid=sid, act_id="100001", biz_line=1, trade_type=1,
+            pay_price_cents=pay, commission_cents=comm, commission_rate="500",
+            refund_price_cents=None, refund_profit_cents=None,
+            mt_status=status, product_name=name,
+            pay_time=now - timedelta(days=i % 6, hours=i),
+            mt_update_time=now - timedelta(days=i % 6),
+            raw={"mock": True, "status": status},
+        ))
+
+
+def seed(db) -> dict:
+    now = _now()
+
+    # ── 1) 建群(覆盖 active 美团 / 美团+淘宝 / 纯淘宝 / 纯京东 / archived)──
+    groups = [
+        CpsGroup(sid=SID_MT_A, name=f"{NAME_PREFIX}美团外卖群A",
+                 platforms=["meituan"], member_count=480, status="active",
+                 remark="mock-纯美团,走对账"),
+        CpsGroup(sid=SID_MT_B, name=f"{NAME_PREFIX}美团+淘宝群B",
+                 platforms=["meituan", "taobao"], member_count=320, status="active",
+                 remark="mock-多平台,对账+复制口令"),
+        CpsGroup(sid=None, name=f"{NAME_PREFIX}淘宝券群C",
+                 platforms=["taobao"], member_count=210, status="active",
+                 remark="mock-无 sid,对账字段 None"),
+        CpsGroup(sid=None, name=f"{NAME_PREFIX}京东券群D",
+                 platforms=["jd"], member_count=150, status="active",
+                 remark="mock-无 sid,对账字段 None"),
+        CpsGroup(sid=SID_ARCHIVED, name=f"{NAME_PREFIX}已归档美团群E",
+                 platforms=["meituan"], member_count=90, status="archived",
+                 remark="mock-archived,应被统计排除"),
+    ]
+    db.add_all(groups)
+    db.flush()  # 拿 group.id
+    g_a, g_b, g_c, g_d, g_e = groups
+
+    # ── 2) 每群一条短链(cps_click.link_id 非空;无 FK,activity_id 占位即可)──
+    links = {}
+    for g in groups:
+        link = CpsLink(
+            code=f"MK{g.id:05d}", group_id=g.id, activity_id=0,
+            sid=g.sid, platform=(g.platforms[0] if g.platforms else "meituan"),
+            target_url=f"https://example.com/mock/{g.id}",
+        )
+        db.add(link)
+        links[g.id] = link
+    db.flush()  # 拿 link.id
+
+    # ── 3) 点击(pv>uv;淘宝群带 copy 复制口令)──
+    _add_clicks(db, group_id=g_a.id, sid=g_a.sid, link_id=links[g_a.id].id,
+                visit=5, visit_uv=3, now=now)
+    _add_clicks(db, group_id=g_b.id, sid=g_b.sid, link_id=links[g_b.id].id,
+                visit=8, visit_uv=5, copy=3, copy_uv=2, now=now)
+    _add_clicks(db, group_id=g_c.id, sid=None, link_id=links[g_c.id].id,
+                visit=6, visit_uv=4, copy=4, copy_uv=3, now=now)
+    _add_clicks(db, group_id=g_d.id, sid=None, link_id=links[g_d.id].id,
+                visit=4, visit_uv=3, now=now)
+    _add_clicks(db, group_id=g_e.id, sid=g_e.sid, link_id=links[g_e.id].id,
+                visit=3, visit_uv=2, now=now)  # archived,统计里看不到
+
+    # ── 3.5) 微信用户画像 + 带 openid 的点击(挂淘宝系群 B/C;这些点击也计入 stats 的 pv/uv)──
+    groups_by_key = {"A": g_a, "B": g_b, "C": g_c, "D": g_d, "E": g_e}
+    # 建画像;无昵称的 anon 不建 CpsWxUser → group_wx_users 里 nickname/headimgurl 为 None
+    for i, (suf, nickname, rgb, fg_key) in enumerate(WX_PROFILES):
+        if nickname is None:
+            continue
+        fg = groups_by_key[fg_key]
+        db.add(CpsWxUser(
+            openid=_openid(suf), nickname=nickname, headimgurl=_write_avatar(suf, rgb),
+            first_code=links[fg.id].code, first_group_id=fg.id,
+            first_seen=now - timedelta(days=3, hours=i), last_seen=now - timedelta(hours=1),
+        ))
+    # 逐条 openid 点击:同一 openid 固定一个 (ip,ua) 身份(跨群复用=同人同设备)
+    idx_of = {_openid(suf): i for i, (suf, *_rest) in enumerate(WX_PROFILES)}
+    counter = [0]
+
+    def _wx_clicks(group: CpsGroup, openid: str, visit: int, copy: int) -> None:
+        ident = idx_of[openid]
+        ip, ua = f"100.64.{ident}.{ident}", f"WeChat/8.0 {openid}"
+        for event, n in (("visit", visit), ("copy", copy)):
+            for _ in range(n):
+                counter[0] += 1
+                db.add(CpsClick(
+                    link_id=links[group.id].id, group_id=group.id, sid=group.sid,
+                    event_type=event, ip=ip, ua=ua, openid=openid,
+                    clicked_at=now - timedelta(hours=counter[0]),
+                ))
+
+    for gk, suf, visit, copy in WX_ACTIVITY:
+        _wx_clicks(groups_by_key[gk], _openid(suf), visit, copy)
+
+    # ── 4) 订单(按 sid 归群;状态覆盖 有效/无效/结算)──
+    # 群A:有效5(2,3,3,6,6) 结算2 取消2(4,5)
+    _add_orders(db, sid=SID_MT_A, tag="A", now=now, specs=[
+        ("2", 3580, 180, "麦当劳 板烧鸡腿堡套餐"),
+        ("3", 4200, 210, "瑞幸 生椰拿铁×2"),
+        ("3", 2890, 140, "肯德基 早餐组合"),
+        ("6", 5100, 255, "海底捞 双人套餐"),
+        ("6", 3300, 165, "蜜雪冰城 多杯装"),
+        ("4", 2600, 130, "(取消)星巴克 美式"),
+        ("5", 1990, 90, "(风控)某外卖单"),
+    ])
+    # 群B:有效3(3,6,2) 结算1 取消1(4)
+    _add_orders(db, sid=SID_MT_B, tag="B", now=now, specs=[
+        ("3", 6800, 340, "必胜客 双人餐"),
+        ("6", 4500, 225, "喜茶 多肉葡萄×3"),
+        ("2", 3120, 150, "华莱士 全鸡套餐"),
+        ("4", 2200, 110, "(取消)某甜品单"),
+    ])
+    # 未归群历史 sid(不属于任何群)→ 结果里 group_id=None 单列
+    _add_orders(db, sid=SID_ORPHAN, tag="OLD", now=now, specs=[
+        ("6", 2800, 140, "历史结算单"),
+        ("3", 3600, 180, "历史完成单"),
+    ])
+
+    db.commit()
+    return {
+        "groups": len(groups), "orders": 7 + 4 + 2,
+        "anon_clicks": 5 + (8 + 3) + (6 + 4) + 4 + 3,
+        "wx_clicks": sum(v + c for *_, v, c in WX_ACTIVITY),
+        "wx_users": len({suf for _, suf, *_ in WX_ACTIVITY}),
+        "wx_profiles": sum(1 for _, nn, *_ in WX_PROFILES if nn is not None),
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="造 CPS 按群对账统计 mock 数据(后台 get_stats 用)")
+    parser.add_argument("--clean-only", action="store_true", help="只清理 mock 数据,不重建")
+    args = parser.parse_args()
+
+    db = SessionLocal()
+    try:
+        removed = clean(db)
+        if any(removed.values()):
+            print(f"🧹 已清理旧 mock:群{removed['group']} 订单{removed['order']} "
+                  f"点击{removed['click']} 短链{removed['link']} 微信用户{removed['wx_user']}")
+        if args.clean_only:
+            print("✅ 仅清理,已完成。")
+            return
+
+        r = seed(db)
+        print(f"\n✅ 已生成:{r['groups']} 群 / {r['orders']} 订单 / "
+              f"{r['anon_clicks'] + r['wx_clicks']} 点击(其中带 openid {r['wx_clicks']}) / "
+              f"{r['wx_users']} 微信用户(含画像 {r['wx_profiles']})\n")
+        print("① 预期 get_stats(days=30)(B/C 的 pv/uv 已含带 openid 的用户点击):")
+        print("  群A(美团,sid=%s)  : 有效5 结算2 取消2 | GMV ¥190.70 预估 ¥9.50 已结算 ¥4.20 | 点击 pv5/uv3"
+              % SID_MT_A)
+        print("  群B(美团+淘宝,sid=%s): 有效3 结算1 取消1 | GMV ¥144.20 预估 ¥7.15 已结算 ¥2.25 | 点击 pv15/uv8 复制 pv5/uv4"
+              % SID_MT_B)
+        print("  群C(淘宝,无 sid)    : 对账字段 '-' | 点击 pv19/uv9 复制 pv11/uv7")
+        print("  群D(京东,无 sid)    : 对账字段 '-' | 点击 pv4/uv3")
+        print("  群E(已归档)         : 不出现在结果(status 过滤)")
+        print("  未归群 sid=%s        : group_id=None 单列 | 有效2 结算1 | GMV ¥64.00 预估 ¥3.20 已结算 ¥1.40"
+              % SID_ORPHAN)
+        print("  合计:订单 10 | 预估佣金 ¥19.85 | 已结算佣金 ¥7.85")
+        print("\n② 预期 group_wx_users(按本群首次点击倒序):")
+        print("  群C(5 人): 省钱小张 v3/c2 | 薅羊毛阿珍 v2/c1 | 随便看看 v1/c0 | "
+              "比价小能手 v5/c3 | (匿名·无画像) v2/c1")
+        print("  群B(3 人): 深夜下单选手 v2/c1 | 团购队长 v3/c0 | 比价小能手 v2/c1(跨群,首授权在 C)")
+        print("  群A/D/E   : 无带 openid 点击 → 返回 []")
+        print("\n👉 验收:GET /admin/cps/stats?days=30")
+        print("         GET /admin/cps/groups/{群B或C的id}/wx-users(头像经 :8770 /media 加载,App 后端需在跑)")
+    finally:
+        db.close()
+
+
+if __name__ == "__main__":
+    main()

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)

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")

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_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_cps_redirect.py

@@ -0,0 +1,87 @@
+"""美团/京东 CPS 落地页「领券前授权头像」插页(/c/{code})。
+
+验证:微信内未授权头像 → 出插页(snsapi_userinfo 按钮 + 「直接领券」出口);
+已授权(wx_uinfo cookie) / 非微信 → 直接 302 跳 target。
+插页只渲染 HTML、不真调微信,故无需 mock 微信网络。
+"""
+from __future__ import annotations
+
+import pytest
+
+from app.core.config import settings
+from app.db.session import SessionLocal
+from app.repositories import cps_link as cps_link_repo
+
+_WECHAT_UA = "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) MicroMessenger/8.0.40"
+_OTHER_UA = "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) Safari/605.1"
+
+
+@pytest.fixture()
+def _wx_oauth_on(monkeypatch):
+    """打开微信网页授权(插页只在 settings.wx_oauth_active 时出)。"""
+    monkeypatch.setattr(settings, "WX_MP_APPID", "wxtestappid")
+    monkeypatch.setattr(settings, "WX_MP_SECRET", "wxtestsecret")
+    monkeypatch.setattr(settings, "WX_MP_OAUTH_ENABLED", True)
+    monkeypatch.setattr(settings, "CPS_REDIRECT_BASE", "https://coupon.example.com")
+
+
+def _make_link(platform: str, target: str) -> tuple[str, str]:
+    with SessionLocal() as db:
+        link = cps_link_repo.create_link(
+            db, group_id=1, activity_id=1,
+            sid="g1" if platform == "meituan" else None,
+            target_url=target, platform=platform,
+        )
+        return link.code, link.target_url
+
+
+@pytest.mark.parametrize("platform,target", [
+    ("meituan", "https://dpurl.cn/mt-abc"),
+    ("jd", "https://u.jd.com/jd-xyz"),
+])
+def test_wechat_unauthorized_shows_interstitial(client, _wx_oauth_on, platform, target):
+    """微信内 + 有 openid + 无 wx_uinfo → 200 插页:userinfo 授权按钮 + 直接领券出口。"""
+    code, tgt = _make_link(platform, target)
+    r = client.get(
+        f"/c/{code}",
+        headers={"user-agent": _WECHAT_UA, "cookie": "wx_openid=o_test"},
+        follow_redirects=False,
+    )
+    assert r.status_code == 200, r.text
+    body = r.text
+    assert "snsapi_userinfo" in body   # 唯一按钮走 userinfo 授权(交互手势触发)
+    assert code in body                # 授权 state=uinfo:{code}
+    assert tgt in body                 # 取消授权时前端转跳的目标券页(绝不阻断领券)
+    assert "暂不授权" not in body       # 已去掉单独的"暂不授权"出口,改为取消即自动转跳
+
+
+def test_authorized_redirects_to_target(client, _wx_oauth_on):
+    """已授权头像(wx_uinfo=1)→ 不再出插页,直接 302 跳 target。"""
+    code, tgt = _make_link("meituan", "https://dpurl.cn/mt-ok")
+    r = client.get(
+        f"/c/{code}",
+        headers={"user-agent": _WECHAT_UA, "cookie": "wx_openid=o_test; wx_uinfo=1"},
+        follow_redirects=False,
+    )
+    assert r.status_code == 302
+    assert r.headers["location"] == tgt
+
+
+def test_non_wechat_redirects_to_target(client, _wx_oauth_on):
+    """非微信浏览器(拿不了授权)→ 直接 302 跳 target,不出插页。"""
+    code, tgt = _make_link("meituan", "https://dpurl.cn/mt-other")
+    r = client.get(
+        f"/c/{code}",
+        headers={"user-agent": _OTHER_UA, "cookie": "wx_openid=o_test"},
+        follow_redirects=False,
+    )
+    assert r.status_code == 302
+    assert r.headers["location"] == tgt
+
+
+def test_oauth_cb_cancel_no_code_redirects_back(client):
+    """授权弹窗点「取消」、微信带空 code 回调 → 兜底 302 回落地页(不报 422)。
+    落地页再由前端转跳目标券页,保证拒绝也能拿到券。"""
+    r = client.get("/wx/oauth/cb?state=uinfo:ABC123", follow_redirects=False)
+    assert r.status_code == 302
+    assert r.headers["location"] == "/c/ABC123"

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_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: