fix(alembic): 合并 88f2380 引入的双 head,恢复 upgrade head 可用

88f2380 把 origin/main 合进本分支后,两条迁移线在 git 上汇合了、在 alembic 图上
却没有:本分支的 ad_reward_boost_round_id → drop_signin_boost_record 与 main 的
merge_active_phone 同从 comparison_llm_cost 分叉,此后再无迁移 revise
drop_signin_boost_record,它成了悬空的第二个 head。

后果:`alembic upgrade head`(单数)报 "Multiple head revisions are present"。
按 CLAUDE.md,run.sh 启动即自动迁移 —— app server 直接起不来,CI/线上同样报错。

用标准 merge revision 收敛(而非改 down_revision 指向),保留两侧作者文件不动。
纯 merge,无表结构/数据改动。

验证:alembic heads 恰好一个 merge_signin_boost_main;空库 alembic upgrade head
全链路跑通,current 停在 (head) (mergepoint);ruff 通过;pytest 435 passed
(6 个既有失败,与本次改动前一致)。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.env.example

@@ -137,3 +137,19 @@ PANGLE_REPORT_SECURITY_KEY=
 # GroMore AppId(报表 site_id 维度)→ 应用环境;默认取现网两个应用,按需覆盖。
 PANGLE_REPORT_SITE_ID_PROD=5830519
 PANGLE_REPORT_SITE_ID_TEST=5832303
+
+# ===== 可观测(OpenObserve 接口指标)=====
+# 采集每个接口 QPS + 耗时 + 错误率,批量直采到 OpenObserve(本地 Docker,见 deploy/openobserve/)。
+# 默认关;开启需 ENABLED=true 且填 USER/PASSWORD(与 docker-compose 里 root 账号一致)。
+# 未开/缺凭证 → 中间件透传、worker 不启动,整套 no-op,不影响业务。
+OBSERVE_ENABLED=false
+OBSERVE_ENDPOINT=http://localhost:5080
+OBSERVE_ORG=default
+OBSERVE_STREAM=app_requests
+OBSERVE_USER=admin@shaguabijia.local
+OBSERVE_PASSWORD=Complexpass#123
+# 进阶(一般不用改):攒批间隔秒 / 单批最大条数 / 有界队列上限(满则丢) / 上报超时秒
+OBSERVE_FLUSH_INTERVAL_SEC=5
+OBSERVE_BATCH_MAX=200
+OBSERVE_QUEUE_MAX=10000
+OBSERVE_TIMEOUT_SEC=5

.gitignore

@@ -48,3 +48,12 @@ secrets/*
 # 运行日志(run.sh 输出, 不入库)
 *.log
 logs/
+
+# Claude Code 自动持久化的权限 allowlist / 个人本地设置(会话专属,不入库)。
+# 需要团队共享的 Claude 配置(commands/ 等)可单独 git add -f,不受此忽略影响。
+.claude/settings.json
+.claude/settings.local.json
+tests/meituan_coupon_bj.tsv
+tests/meituan_coupon_data.tsv
+tests/meituan_coupon_fz.tsv
+tests/meituan_coupon_xm.tsv

alembic/versions/11c44afbea58_analytics_selfstat_tables.py

@@ -0,0 +1,72 @@
+"""analytics_selfstat tables
+
+Revision ID: 11c44afbea58
+Revises: admin_user_plain_password
+Create Date: 2026-07-08 16:32:49.351817
+
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = '11c44afbea58'
+down_revision: str | Sequence[str] | None = 'admin_user_plain_password'
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'analytics_selfstat',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('device_id', sa.String(length=64), nullable=False),
+        sa.Column('epoch_id', sa.String(length=64), nullable=False),
+        sa.Column('app_ver', sa.String(length=32), nullable=True),
+        sa.Column('oem', sa.String(length=32), nullable=True),
+        sa.Column('os', sa.String(length=32), nullable=True),
+        sa.Column('batches_attempted', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('batches_ok', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('batches_fail', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('retries', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('queue_depth', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('sent_at', sa.BigInteger(), 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_selfstat', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_created_at'), ['created_at'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_device_id'), ['device_id'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_epoch_id'), ['epoch_id'], unique=False)
+
+    op.create_table(
+        'analytics_selfstat_event',
+        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column('snapshot_id', sa.Integer(), nullable=False),
+        sa.Column('event', sa.String(length=64), nullable=False),
+        sa.Column('attempted', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('drop_capture', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('delivered', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('drop_undelivered', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.ForeignKeyConstraint(['snapshot_id'], ['analytics_selfstat.id'], ),
+        sa.PrimaryKeyConstraint('id'),
+    )
+    with op.batch_alter_table('analytics_selfstat_event', schema=None) as batch_op:
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_event_event'), ['event'], unique=False)
+        batch_op.create_index(batch_op.f('ix_analytics_selfstat_event_snapshot_id'), ['snapshot_id'], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table('analytics_selfstat_event', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_event_snapshot_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_event_event'))
+    op.drop_table('analytics_selfstat_event')
+    with op.batch_alter_table('analytics_selfstat', schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_epoch_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_device_id'))
+        batch_op.drop_index(batch_op.f('ix_analytics_selfstat_created_at'))
+    op.drop_table('analytics_selfstat')

alembic/versions/135e79414fd0_add_inactivity_tables.py

@@ -0,0 +1,68 @@
+"""add inactivity tables
+
+Revision ID: 135e79414fd0
+Revises: comparison_llm_cost
+Create Date: 2026-07-16 18:31:02.105929
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '135e79414fd0'
+down_revision: Union[str, Sequence[str], None] = 'comparison_llm_cost'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "inactivity_reset_log",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("coin_balance_before", sa.Integer(), nullable=False),
+        sa.Column("cash_balance_cents_before", sa.Integer(), nullable=False),
+        sa.Column("invite_cash_balance_cents_before", sa.Integer(), nullable=False),
+        sa.Column("last_active_at", sa.DateTime(timezone=True), nullable=True),
+        sa.Column("inactive_days", sa.Integer(), nullable=False),
+        sa.Column("reason", sa.String(length=32), nullable=False),
+        sa.Column("reset_at", sa.DateTime(timezone=True),
+                  server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    with op.batch_alter_table("inactivity_reset_log", schema=None) as batch_op:
+        batch_op.create_index(batch_op.f("ix_inactivity_reset_log_user_id"), ["user_id"], unique=False)
+        batch_op.create_index(batch_op.f("ix_inactivity_reset_log_reset_at"), ["reset_at"], unique=False)
+
+    op.create_table(
+        "inactivity_notification_log",
+        sa.Column("id", sa.Integer(), autoincrement=True, nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("stage", sa.Integer(), nullable=False),
+        sa.Column("inactive_days", sa.Integer(), nullable=False),
+        sa.Column("coin_balance", sa.Integer(), nullable=False),
+        sa.Column("cash_balance_cents", sa.Integer(), nullable=False),
+        sa.Column("invite_cash_balance_cents", sa.Integer(), nullable=False),
+        sa.Column("channel", sa.String(length=16), nullable=False),
+        sa.Column("status", sa.String(length=16), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True),
+                  server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+    with op.batch_alter_table("inactivity_notification_log", schema=None) as batch_op:
+        batch_op.create_index(batch_op.f("ix_inactivity_notification_log_user_id"), ["user_id"], unique=False)
+        batch_op.create_index(batch_op.f("ix_inactivity_notification_log_created_at"), ["created_at"], unique=False)
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("inactivity_notification_log", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_inactivity_notification_log_created_at"))
+        batch_op.drop_index(batch_op.f("ix_inactivity_notification_log_user_id"))
+    op.drop_table("inactivity_notification_log")
+    with op.batch_alter_table("inactivity_reset_log", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_inactivity_reset_log_reset_at"))
+        batch_op.drop_index(batch_op.f("ix_inactivity_reset_log_user_id"))
+    op.drop_table("inactivity_reset_log")

alembic/versions/ad_ecpm_trace_id.py

@@ -0,0 +1,44 @@
+"""ad_ecpm_record.trace_id(展示收益归属到比价/领券 trace)
+
+信息流(Draw)展示 eCPM 上报时带上本场比价/领券 trace_id,落此列;领券数据 / 比价记录看板
+按 trace_id 聚合"本次广告收益"。激励视频/福利/旧客户端为 NULL。
+
+本迁移原以 (11c44afbea58, merge_pages_override_coupon_slot) 为双亲、顺带收敛双 head,
+但与它并行落 main 的 merge_selfstat_coupon_slot 已用同一对双亲做了纯收敛 → 同一对
+父节点出现两个收敛点、main 上又成双 head。故重挂到该 merge 之后成单链(仅改链接、
+schema 改动不变;两文件都保留,已 stamp 在 merge 上的库可直接线性升级)。
+
+Revision ID: ad_ecpm_trace_id
+Revises: merge_selfstat_coupon_slot
+Create Date: 2026-07-10
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+revision: str = "ad_ecpm_trace_id"
+down_revision: Union[str, Sequence[str], None] = "merge_selfstat_coupon_slot"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # SQLite 下 ADD COLUMN(可空)与 CREATE INDEX 均原生支持,无需 batch_alter_table
+    # (同 ad_feed_reward_trace_id 迁移)。
+    op.add_column(
+        "ad_ecpm_record",
+        sa.Column("trace_id", sa.String(length=64), nullable=True),
+    )
+    op.create_index(
+        op.f("ix_ad_ecpm_record_trace_id"),
+        "ad_ecpm_record",
+        ["trace_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index(op.f("ix_ad_ecpm_record_trace_id"), table_name="ad_ecpm_record")
+    op.drop_column("ad_ecpm_record", "trace_id")

alembic/versions/ad_reward_boost_round_id.py

@@ -0,0 +1,47 @@
+"""ad_reward_record.boost_round_id(金币膨胀「本轮累计」标签)
+
+看完一条激励视频后客户端要弹「本轮累计获得 N 金币」,N 必须等于这一轮实际到账之和(否则用户
+会认为少发了钱)。单条到账额 reward-result 已经能给,但「一轮」的边界只有客户端知道(点「放弃
+赚钱」才算结束),客户端自己累加又会在进程被杀后丢失。
+
+解法:客户端把轮次 id 随 mediaExtra 透传,穿山甲 S2S 原样带回,发奖时打在记录上;
+reward-result 按 (user_id, boost_round_id) 对 granted 记录求和返回 round_coin。
+
+本列是**纯标签**:不参与发奖判定,发多少/发不发完全不受影响。客户端就算一直复用同一个 id,
+也只是把展示数字滚大,不产生任何新入账(求和的是已发生的发奖记录),无资损风险。
+
+Revision ID: ad_reward_boost_round_id
+Revises: comparison_llm_cost
+Create Date: 2026-07-20
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "ad_reward_boost_round_id"
+down_revision: str | Sequence[str] | None = "comparison_llm_cost"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # 可空、无默认:SQLite 原生支持 ADD COLUMN,不需要 batch_alter_table(同 comparison_llm_cost)。
+    # 存量行留 NULL = 「不属于任何一轮」,求和时天然不参与,老客户端行为不变。
+    op.add_column(
+        "ad_reward_record",
+        sa.Column("boost_round_id", sa.String(length=64), nullable=True),
+    )
+    # 求和恒带 user_id(轮 id 是客户端生成的,不能跨用户信任),故建复合索引而非单列
+    op.create_index(
+        "ix_ad_reward_user_boost_round",
+        "ad_reward_record",
+        ["user_id", "boost_round_id"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_ad_reward_user_boost_round", table_name="ad_reward_record")
+    op.drop_column("ad_reward_record", "boost_round_id")

alembic/versions/admin_role_table.py

@@ -0,0 +1,69 @@
+"""admin_role 表(RBAC 角色 → 可见页面)+ 种子内建角色
+
+新增后台 RBAC:角色持有一组页面 key,登录后左侧只展示这些页。super_admin 内建全权(pages 存空、
+effective_pages 特判为全部)、不可编辑删除;operator/finance 播默认页集,可由 super_admin 增删改。
+admin_user.role 弱引用本表 name。全新环境顺序应用即得三条内建角色。
+
+Revision ID: admin_role_table
+Revises: comparison_product_names
+Create Date: 2026-07-04 00:00:00.000000
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "admin_role_table"
+down_revision: str | Sequence[str] | None = "comparison_product_names"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_JSON = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+# 与 app/admin/permissions.py 的 BUILTIN_ROLES 同口径(迁移内联一份,不耦合 app 常量)。
+# 页集对齐 Prototypes/dashboard/permissions.md 的 ROLES。key 承重(require_role),label 为展示名。
+_BUILTIN = [
+    {"name": "super_admin", "label": "管理员", "pages": [], "is_builtin": True},
+    {"name": "operator", "label": "运营", "pages": [
+        "dashboard", "coupon-data", "ad-revenue-report", "comparison-records",
+        "cps", "device-liveness", "price-reports", "feedbacks",
+    ], "is_builtin": False},
+    {"name": "finance", "label": "财务", "pages": [
+        "dashboard", "ad-revenue-report", "cps", "withdraws",
+    ], "is_builtin": False},
+    {"name": "tech", "label": "技术", "pages": [
+        "dashboard", "device-liveness", "config", "ad-revenue", "event-logs", "audit-logs",
+    ], "is_builtin": False},
+]
+
+
+def upgrade() -> None:
+    op.create_table(
+        "admin_role",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("name", sa.String(length=32), nullable=False),
+        sa.Column("label", sa.String(length=32), nullable=False, server_default=""),
+        sa.Column("pages", _JSON, nullable=False),
+        sa.Column("is_builtin", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True),
+            server_default=sa.func.now(), nullable=False,
+        ),
+    )
+    op.create_index("ix_admin_role_name", "admin_role", ["name"], unique=True)
+
+    tbl = sa.table(
+        "admin_role",
+        sa.column("name", sa.String),
+        sa.column("label", sa.String),
+        sa.column("pages", _JSON),
+        sa.column("is_builtin", sa.Boolean),
+    )
+    op.bulk_insert(tbl, _BUILTIN)
+
+
+def downgrade() -> None:
+    op.drop_index("ix_admin_role_name", table_name="admin_role")
+    op.drop_table("admin_role")

alembic/versions/admin_user_pages_override.py

@@ -0,0 +1,35 @@
+"""admin_user 加 pages_override 列(「自定义」权限:按人存专属可见页 key 列表)
+
+权限管理页新增「自定义」角色:选它时该成员的可见页不跟随任何共享角色,而由逐页勾选决定,
+存这个人专属的一份页 key 列表。仅 role == "custom" 时有效;普通角色为 None(可见页跟随角色)。
+PG 用 JSONB,SQLite 退化为通用 JSON(同 admin_audit_log.detail / comparison_record.raw_payload)。
+
+Revision ID: admin_user_pages_override
+Revises: admin_user_plain_password
+Create Date: 2026-07-08 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = "admin_user_pages_override"
+down_revision: str | Sequence[str] | None = "admin_user_plain_password"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# 与 app/models/admin.py 的 _JSON 一致:PG JSONB / 其它 JSON
+_JSON = sa.JSON().with_variant(JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("pages_override", _JSON, nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.drop_column("pages_override")

alembic/versions/admin_user_plain_password.py

@@ -0,0 +1,29 @@
+"""admin_user 加 plain_password 列(明文登录密码,仅后台 UI 建/重置的账号留存)
+
+权限管理页需能复看某成员已确定的登录密码转交本人。系统只存哈希无法反推,故对「后台 UI 创建/重置」
+的管理员额外留存一份明文;脚本/起后台建的超管为 None(前端不显示密码)。旧账号无此列值 → 同样不显示。
+
+Revision ID: admin_user_plain_password
+Revises: admin_role_table
+Create Date: 2026-07-04 00:00:00.000000
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "admin_user_plain_password"
+down_revision: str | Sequence[str] | None = "admin_role_table"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("plain_password", sa.String(length=128), nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.drop_column("plain_password")

alembic/versions/analytics_active_idx_active_composite_index.py

@@ -0,0 +1,38 @@
+"""analytics_event 活跃口径复合索引
+
+Revision ID: analytics_active_idx
+Revises: 135e79414fd0
+Create Date: 2026-07-18 17:35:00.000000
+
+给 analytics_event 加活跃口径热点复合索引 (event, page, user_id, created_at):
+activity.active_event_condition 按 event IN (home_visible ∪ 比价 ∪ 领券) 过滤后
+group by user_id、max(created_at)。覆盖索引让该聚合走 index-only,避免高频活跃事件全表扫。
+(历史:早期首页可见用 event=show+page=home 组合,故索引含 page 列;现改单一 home_visible、
+不再按 page 过滤 → page 列成冗余,索引仍靠 event 前缀生效;如需更优可后续新迁移瘦成 (event,user_id,created_at)。)
+
+⚠️ 本分支迁移树有**既有多头**:135e79414fd0(不活跃两表)与 phone_rebind_log 同从
+comparison_llm_cost 分叉,`alembic upgrade head` 会多头报错。本迁移挂在 135e79414fd0
+一侧;集成到 main 时需 `alembic merge` 合并 phone_rebind_log 那个头(与本迁移无关的既有问题)。
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "analytics_active_idx"
+down_revision: Union[str, Sequence[str], None] = "135e79414fd0"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_index(
+        "ix_analytics_event_active",
+        "analytics_event",
+        ["event", "page", "user_id", "created_at"],
+        unique=False,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_analytics_event_active", table_name="analytics_event")

alembic/versions/comparison_llm_cost.py

@@ -0,0 +1,33 @@
+"""comparison_record: llm_cost_yuan + llm_price_snapshot(比价 LLM 调用成本 + 当时单价快照)
+
+回填 llm_calls 时按「当时的价」逐模型算出本次比价 LLM 总成本(元),连同所用单价快照一起冻结到
+记录上;admin 比价记录详情展示实际成本(旧记录 NULL → 前端回退估算)。见 services/llm_cost.py。
+
+Revision ID: comparison_llm_cost
+Revises: ad_ecpm_trace_id
+Create Date: 2026-07-13
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision: str = "comparison_llm_cost"
+down_revision: str | Sequence[str] | None = "ad_ecpm_trace_id"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+_JSONB = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    # 均可空、无索引;SQLite 原生支持 ADD COLUMN,无需 batch_alter_table(同 comparison_debug_fields)。
+    op.add_column("comparison_record", sa.Column("llm_cost_yuan", sa.Float(), nullable=True))
+    op.add_column("comparison_record", sa.Column("llm_price_snapshot", _JSONB, nullable=True))
+
+
+def downgrade() -> None:
+    op.drop_column("comparison_record", "llm_price_snapshot")
+    op.drop_column("comparison_record", "llm_cost_yuan")

alembic/versions/comparison_product_names.py

@@ -0,0 +1,70 @@
+"""comparison_record 加 product_names 列(下单商品名派生串)+ 回填历史行
+
+admin 比价记录页要把原「店/商品」一列拆成「店」+「商品」两列、并支持按商品名搜索。
+items 是 JSON(SQLite 下 json.dumps ensure_ascii 会把中文转义存成 \\uXXXX,无法直接 CAST+LIKE
+命中中文),故把商品名派生成普通文本列,跨库 LIKE 一致、可索引。
+
+写路径(upsert_record / harvest_done)已同步派生;本迁移建列并从已存 items 回填历史行。
+全新环境顺序应用即得空列 + 回填(表本为空,回填 no-op)。
+
+Revision ID: comparison_product_names
+Revises: comparison_record_trace_unique
+Create Date: 2026-07-04 00:00:00.000000
+"""
+
+import json
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "comparison_product_names"
+down_revision: str | Sequence[str] | None = "comparison_record_trace_unique"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _product_names(items) -> str | None:
+    """items([{name,...}]) → 顿号分隔的商品名串(去重保序)。与 repositories.comparison
+    ._product_names_from_items 同口径,迁移内联一份避免耦合 app 代码。"""
+    if isinstance(items, str):  # SQLite: items 以 JSON 文本存,取回是 str
+        try:
+            items = json.loads(items)
+        except (ValueError, TypeError):
+            return None
+    if not isinstance(items, list) or not items:
+        return None
+    names: list[str] = []
+    for it in items:
+        name = it.get("name") if isinstance(it, dict) else None
+        if not name:
+            continue
+        s = str(name).strip()
+        if s and s not in names:
+            names.append(s)
+    joined = "、".join(names)
+    return joined[:500] or None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("product_names", sa.String(length=512), nullable=True))
+
+    # 回填:从已存 items 派生商品名。items 小(菜名列表),一次取回即可;只更新有商品名的行。
+    bind = op.get_bind()
+    rows = bind.execute(
+        sa.text("SELECT id, items FROM comparison_record")
+    ).fetchall()
+    for rid, items in rows:
+        pn = _product_names(items)
+        if pn:
+            bind.execute(
+                sa.text("UPDATE comparison_record SET product_names = :pn WHERE id = :id"),
+                {"pn": pn, "id": rid},
+            )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
+        batch_op.drop_column("product_names")

alembic/versions/coupon_claim_app_env.py

@@ -0,0 +1,32 @@
+"""coupon_claim_record 加 app_env 列(领券所属 session 环境;每券成功率表按它过滤 prod/dev)
+
+Revision ID: coupon_claim_app_env
+Revises: coupon_session_platform_success
+Create Date: 2026-07-08 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "coupon_claim_app_env"
+down_revision: str | Sequence[str] | None = "coupon_session_platform_success"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("coupon_claim_record", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("app_env", sa.String(length=16), nullable=True))
+        batch_op.create_index(
+            "ix_coupon_claim_record_app_env", ["app_env"], unique=False
+        )
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("coupon_claim_record", schema=None) as batch_op:
+        batch_op.drop_index("ix_coupon_claim_record_app_env")
+        batch_op.drop_column("app_env")

alembic/versions/coupon_session_platform_success.py

@@ -0,0 +1,37 @@
+"""coupon_session 加 platform_success 列(本次至少领到一张的平台 id 列表)
+
+供 admin「领券数据」算 ②整单成功率 / ③点位成功率(平台粒度)。数据落点:服务端 /step 逐帧
+按 trace_id 并集写入(见 app/repositories/coupon_state.merge_session_platform_success)。旧行 NULL
+视作空集,已建表环境靠它补列、全新环境顺序应用不重复加列。设计:docs/guides/领券成功率指标-设计与埋点.md。
+
+Revision ID: coupon_session_platform_success
+Revises: admin_user_plain_password
+Create Date: 2026-07-07 00:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "coupon_session_platform_success"
+down_revision: str | Sequence[str] | None = "admin_user_plain_password"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# PG 用 JSONB,SQLite(本地/测试)退化为通用 JSON(同 model 的 _JSON variant / 建表迁移)。
+_JSON = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("platform_success", _JSON, nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("coupon_session", schema=None) as batch_op:
+        batch_op.drop_column("platform_success")

alembic/versions/drop_signin_boost_record.py

@@ -0,0 +1,56 @@
+"""下线签到膨胀:drop signin_boost_record
+
+产品 2026-07 确认「固定 3000 金币的签到膨胀」从来不是设计内的口径 —— 奖励只有「签到」和
+「看视频」两种。签到弹窗里的「看广告膨胀」改与福利页看视频走同一条 reward_video 路径
+(按 eCPM 公式发,记在 ad_reward_record),signin_boost 场景整体摘除。
+
+⚠️ **只 drop 这张表,不动 coin_transaction**:`biz_type='signin_boost'` 的金币流水是真发过的
+钱,账必须留得住(admin 大盘的 signin_boost_coin_total / signin_boost_watch_count 改为从
+coin_transaction 统计,继续能查回历史)。本表只是「哪天膨胀过」的业务留痕,金额与去向都能
+从流水还原,drop 掉不影响对账。
+
+downgrade 只重建空表结构,**不恢复数据** —— 真要回滚得先从备份捞行。
+
+Revision ID: drop_signin_boost_record
+Revises: ad_reward_boost_round_id
+Create Date: 2026-07-20
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "drop_signin_boost_record"
+down_revision: str | Sequence[str] | None = "ad_reward_boost_round_id"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("signin_boost_record", schema=None) as batch_op:
+        batch_op.drop_index(batch_op.f("ix_signin_boost_record_user_id"))
+    op.drop_table("signin_boost_record")
+
+
+def downgrade() -> None:
+    # 只还结构不还数据(见模块 docstring)
+    op.create_table(
+        "signin_boost_record",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("user_id", sa.Integer(), nullable=False),
+        sa.Column("signin_date", sa.Date(), nullable=False),
+        sa.Column("coin_awarded", sa.Integer(), nullable=False),
+        sa.Column("ad_ref_id", sa.String(length=64), nullable=True),
+        sa.Column(
+            "created_at", sa.DateTime(timezone=True),
+            server_default=sa.text("(CURRENT_TIMESTAMP)"), nullable=False,
+        ),
+        sa.ForeignKeyConstraint(["user_id"], ["user.id"]),
+        sa.PrimaryKeyConstraint("id"),
+        sa.UniqueConstraint("user_id", "signin_date", name="uq_signin_boost_user_date"),
+    )
+    with op.batch_alter_table("signin_boost_record", schema=None) as batch_op:
+        batch_op.create_index(
+            batch_op.f("ix_signin_boost_record_user_id"), ["user_id"], unique=False
+        )

alembic/versions/merge_active_phone_merge_inactivity_analytics_active_idx_.py

@@ -0,0 +1,25 @@
+"""merge inactivity(analytics_active_idx) + phone_rebind_log heads
+
+Revision ID: merge_active_phone
+Revises: analytics_active_idx, phone_rebind_log
+Create Date: 2026-07-18 18:52:34.001148
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+
+
+# revision identifiers, used by Alembic.
+revision: str = 'merge_active_phone'
+down_revision: Union[str, Sequence[str], None] = ('analytics_active_idx', 'phone_rebind_log')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/merge_pages_override_coupon_slot.py

@@ -0,0 +1,28 @@
+"""合并两个 alembic head:admin_user_pages_override(#126 权限)+ coupon_claim_app_env(领券成功率)。
+
+两条迁移都从 admin_user_plain_password 分叉——#126 经 pull main 进入本分支,领券成功率为本分支新增——
+于是出现两个 head。本迁移仅把二者收敛成单 head,让 `alembic upgrade head`(单数,部署/run.sh 用)
+恢复正常;**不含任何表结构 / 数据改动**(纯 merge)。
+
+Revision ID: merge_pages_override_coupon_slot
+Revises: admin_user_pages_override, coupon_claim_app_env
+Create Date: 2026-07-09 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+revision: str = "merge_pages_override_coupon_slot"
+down_revision: str | Sequence[str] | None = (
+    "admin_user_pages_override",
+    "coupon_claim_app_env",
+)
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """纯合并 head,无 schema 改动。"""
+
+
+def downgrade() -> None:
+    """拆回两个 head,无 schema 改动。"""

alembic/versions/merge_selfstat_coupon_slot.py

@@ -0,0 +1,29 @@
+"""合并两个 alembic head:11c44afbea58(#127 埋点健康度 selfstat)+ merge_pages_override_coupon_slot(#130 自带的合并迁移)。
+
+三条分支都从 admin_user_plain_password 分叉(#126 权限 / #127 selfstat / #130 领券成功率)。
+#130 自带的 merge 创建时本地 main 尚无 #127 的 11c44afbea58,只收敛了 #126 + 自身两条,
+#130 合入后 main 上仍留两个 head → `alembic upgrade head`(单数,部署/run.sh 用)直接报错、服务起不来。
+本迁移仅把二者收敛成单 head;**不含任何表结构 / 数据改动**(纯 merge)。
+
+Revision ID: merge_selfstat_coupon_slot
+Revises: 11c44afbea58, merge_pages_override_coupon_slot
+Create Date: 2026-07-10 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+revision: str = "merge_selfstat_coupon_slot"
+down_revision: str | Sequence[str] | None = (
+    "11c44afbea58",
+    "merge_pages_override_coupon_slot",
+)
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """纯合并 head,无 schema 改动。"""
+
+
+def downgrade() -> None:
+    """拆回两个 head,无 schema 改动。"""

alembic/versions/merge_signin_boost_main.py

@@ -0,0 +1,32 @@
+"""合并两个 alembic head:drop_signin_boost_record(本分支)+ merge_active_phone(main)。
+
+两条线同从 comparison_llm_cost 分叉——本分支的 ad_reward_boost_round_id → drop_signin_boost_record
+走「金币膨胀本轮累计 + 下线签到膨胀」;main 侧的 phone_rebind_log / analytics_active_idx 两支已由
+merge_active_phone 收敛。88f2380 把 main 合进本分支后,两条迁移线在 git 上汇合了、在 alembic 图上
+却没有,于是 `alembic upgrade head`(单数)报 "Multiple head revisions are present"——按 CLAUDE.md
+run.sh 启动即自动迁移,app server 会直接起不来。
+
+本迁移仅把二者收敛成单 head;**不含任何表结构 / 数据改动**(纯 merge)。
+
+Revision ID: merge_signin_boost_main
+Revises: drop_signin_boost_record, merge_active_phone
+Create Date: 2026-07-21 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+revision: str = "merge_signin_boost_main"
+down_revision: str | Sequence[str] | None = (
+    "drop_signin_boost_record",
+    "merge_active_phone",
+)
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """纯合并 head,无 schema 改动。"""
+
+
+def downgrade() -> None:
+    """拆回两个 head,无 schema 改动。"""

alembic/versions/phone_rebind_log.py

@@ -0,0 +1,32 @@
+"""phone_rebind_log 表(M2 换绑 30 天限制台账)
+
+Revision ID: phone_rebind_log
+Revises: comparison_llm_cost
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "phone_rebind_log"
+down_revision = "comparison_llm_cost"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "phone_rebind_log",
+        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
+        sa.Column("phone", sa.String(length=20), nullable=False),
+        sa.Column("old_user_id", sa.Integer(), nullable=True),
+        sa.Column("new_user_id", sa.Integer(), nullable=False),
+        sa.Column("source", sa.String(length=32), nullable=False, server_default="wechat_conflict"),
+        sa.Column("rebound_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+    )
+    op.create_index("ix_phone_rebind_log_phone", "phone_rebind_log", ["phone"])
+    op.create_index("ix_phone_rebind_log_rebound_at", "phone_rebind_log", ["rebound_at"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_phone_rebind_log_rebound_at", table_name="phone_rebind_log")
+    op.drop_index("ix_phone_rebind_log_phone", table_name="phone_rebind_log")
+    op.drop_table("phone_rebind_log")

app/admin/main.py

@@ -4,7 +4,6 @@
 复用 App 的 DB/models/repositories/integrations;鉴权独立(admin JWT,见 app/admin/security.py)。
 现有 app.main:app 不 import 本模块,两进程互不影响。
 """
-
 from __future__ import annotations
 
 import logging
@@ -13,7 +12,6 @@ from contextlib import asynccontextmanager
 
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import PlainTextResponse, RedirectResponse
 
 from app.admin.routers.ad_audit import router as ad_audit_router
 from app.admin.routers.ad_config import router as ad_config_router
@@ -27,13 +25,16 @@ from app.admin.routers.coupon_data import router as coupon_data_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.analytics_health import router as analytics_health_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.huawei_review import router as huawei_review_router
 from app.admin.routers.onboarding import router as onboarding_router
 from app.admin.routers.ops_marquee_seed import router as ops_marquee_seed_router
-from app.admin.routers.ops_stat_config import router as ops_stat_config_router
 from app.admin.routers.price_report import router as price_report_router
+from app.admin.routers.roles import router as roles_router
 from app.admin.routers.users import router as users_router
 from app.admin.routers.wallet import router as wallet_router
 from app.admin.routers.withdraw import router as withdraw_router
@@ -86,15 +87,6 @@ def health() -> dict[str, str]:
     return {"status": "ok", "service": "admin"}
 
 
-@admin_app.get("/", include_in_schema=False)
-def root():
-    """根路径落脚点:直接访问 :8771 时,非 prod 跳 API 文档,prod 下给一句纯文本说明
-    (prod 关了 docs_url,不能跳一个不存在的页面,也不暴露文档)。避免浏览器打开根路径吃 404。"""
-    if not settings.is_prod:
-        return RedirectResponse(url="/admin/docs")
-    return PlainTextResponse("shaguabijia admin API. See /admin/api/*.")
-
-
 admin_app.include_router(auth_router)
 admin_app.include_router(dashboard_router)
 admin_app.include_router(device_liveness_router)
@@ -107,8 +99,10 @@ 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(analytics_health_router)
 admin_app.include_router(feedback_qr_router)
 admin_app.include_router(admins_router)
+admin_app.include_router(roles_router)
 admin_app.include_router(audit_router)
 admin_app.include_router(config_router)
 admin_app.include_router(comparison_router)
@@ -116,4 +110,5 @@ admin_app.include_router(cps_router)
 admin_app.include_router(coupon_data_router)
 admin_app.include_router(ad_audit_router)
 admin_app.include_router(ad_config_router)
+admin_app.include_router(huawei_review_router)
 admin_app.include_router(ad_revenue_router)

app/admin/permissions.py

@@ -0,0 +1,85 @@
+"""admin 后台「页面权限目录」—— RBAC 的权限侧单一真源。
+
+一个权限 = 一个页面(= 左侧导航项)。角色持有一组 page key,登录后左侧只展示这些页(见前端
+layout.tsx 按 pages 过滤导航)。key 必须与前端路由一级对齐(/dashboard → "dashboard")。
+
+super_admin 为内建全权角色,恒可见全部页(effective_pages 特判)。新增页面 = 这里加一条 +
+前端导航加对应项(key 一致即可被各角色勾选可见)。
+"""
+from __future__ import annotations
+
+SUPER_ADMIN_ROLE = "super_admin"
+# 「自定义」哨兵角色:不是 admin_role 表里的行,而是标记「这个人的可见页由 pages_override 决定」。
+# admin_user.role == CUSTOM_ROLE 时,有效可见页取 admin_user.pages_override(见 auth._admin_out_with_pages)。
+CUSTOM_ROLE = "custom"
+
+# 分组镜像前端导航(app/(main)/layout.tsx 的 NAV_GROUPS);key = 路由一级
+PERMISSION_CATALOG: list[dict] = [
+    {"group": "看板", "pages": [
+        {"key": "dashboard", "label": "数据大盘"},
+        {"key": "coupon-data", "label": "领券数据"},
+        {"key": "ad-revenue-report", "label": "广告收益"},
+        {"key": "comparison-records", "label": "比价记录"},
+        {"key": "cps", "label": "CPS收益"},
+        {"key": "device-liveness", "label": "设备存活"},
+    ]},
+    {"group": "奖励审核", "pages": [
+        {"key": "withdraws", "label": "提现审核"},
+        {"key": "price-reports", "label": "低价审核"},
+        {"key": "feedbacks", "label": "用户反馈"},
+    ]},
+    {"group": "数据配置", "pages": [
+        {"key": "config", "label": "系统配置"},
+        {"key": "ad-revenue", "label": "广告配置"},
+        {"key": "huawei-review", "label": "华为审核开关"},
+        {"key": "users", "label": "用户管理"},
+    ]},
+    {"group": "其他", "pages": [
+        {"key": "admins", "label": "权限管理"},
+        {"key": "event-logs", "label": "埋点日志"},
+        {"key": "audit-logs", "label": "审计日志"},
+    ]},
+]
+
+# 全部页面 key(super_admin 有效可见 = 此全集;也用于校验角色 pages 合法性)
+ALL_PAGE_KEYS: list[str] = [p["key"] for g in PERMISSION_CATALOG for p in g["pages"]]
+_ALL_SET = set(ALL_PAGE_KEYS)
+
+# 内建角色定义(种子 / ensure 兜底的单一真源):(key, 中文展示名, 默认可见页)。
+# 页集对齐 Prototypes/dashboard/permissions.md 的 ROLES;super_admin 恒全权(pages 空、bypass)。
+# key 承重(require_role / admin_user.role),勿改;label 为 UI 展示名。
+BUILTIN_ROLES: list[dict] = [
+    {"name": SUPER_ADMIN_ROLE, "label": "管理员", "pages": []},
+    {"name": "operator", "label": "运营", "pages": [
+        "dashboard", "coupon-data", "ad-revenue-report", "comparison-records",
+        "cps", "device-liveness", "price-reports", "feedbacks", "huawei-review",
+    ]},
+    {"name": "finance", "label": "财务", "pages": [
+        "dashboard", "ad-revenue-report", "cps", "withdraws",
+    ]},
+    {"name": "tech", "label": "技术", "pages": [
+        "dashboard", "device-liveness", "config", "ad-revenue", "huawei-review",
+        "event-logs", "audit-logs",
+    ]},
+]
+
+# 内建 key → 中文展示名(展示 / 自愈用)
+BUILTIN_LABELS: dict[str, str] = {r["name"]: r["label"] for r in BUILTIN_ROLES}
+
+
+def sanitize_pages(pages: list[str] | None) -> list[str]:
+    """过滤掉不在目录里的 key(去重、保序),防脏数据/目录收缩后的悬空 key。"""
+    seen: set[str] = set()
+    out: list[str] = []
+    for k in pages or []:
+        if k in _ALL_SET and k not in seen:
+            seen.add(k)
+            out.append(k)
+    return out
+
+
+def effective_pages(role_name: str, role_pages: list[str] | None) -> list[str]:
+    """某角色的有效可见页:super_admin → 全部;其余 → 其 pages 与目录取交(自愈悬空 key)。"""
+    if role_name == SUPER_ADMIN_ROLE:
+        return list(ALL_PAGE_KEYS)
+    return sanitize_pages(role_pages)

app/admin/repositories/ad_revenue.py

@@ -385,10 +385,33 @@ def ad_revenue_report(
         for k, v in type_map.items()
     }
 
-    # DAU:复用大盘「今日活跃」口径(stats.today_dau,last_login_at)。该口径只能算今日,
-    # 故仅当查询=今日单天时给值;历史 / 多天区间返回 None,前端显示「-」。
-    is_today = date_from == date_to == rewards.cn_today().isoformat()
-    dau = admin_stats.today_dau(db) if is_today else None
+    # 分场景小计(按 feed_scene:展示条数 + 预估收益),同 type_stats 基于全量 events——
+    # 供数据大盘「领券广告 / 比价广告」卡用。此前大盘是在分页 items 里按 feed_scene 现算,
+    # 2026-07-02 起信息流逐条展示行(唯一带收益 + 场景的行)不再进主表 items,现算恒为 0;
+    # 改为服务端在全量上聚合下发(也顺带不受 limit 分页截断影响)。feed_scene 为空(激励视频 /
+    # 旧数据)不计入任何场景桶。
+    scene_map: dict[str, dict] = {}
+    for e in events:
+        sc = e.get("feed_scene")
+        if not sc:
+            continue
+        s = scene_map.get(sc)
+        if s is None:
+            s = {"impressions": 0, "revenue_yuan": 0.0}
+            scene_map[sc] = s
+        s["impressions"] += e["impressions"]
+        s["revenue_yuan"] += e["revenue_yuan"]
+    scene_stats = {
+        k: {"impressions": v["impressions"], "revenue_yuan": round(v["revenue_yuan"], 6)}
+        for k, v in scene_map.items()
+    }
+
+    # DAU:复用数据大盘活跃用户口径(登录 + 开始比价 + 开始领券,按用户去重),按所选日期区间
+    # 统计(含今日),历史 / 多天区间同样有值。ARPU = 区间预估收益 ÷ 区间活跃用户。全局口径,
+    # 不随 user / ad_type / feed_scene / app_env 筛选变化(活跃用户口径无这些维度)。
+    dau = admin_stats.period_active_dau(
+        db, _date.fromisoformat(date_from), _date.fromisoformat(date_to)
+    )
 
     # 主表「逐行」= 单次广告行为(2026-07 按「一次比价/领券放一块」聚合):激励视频 = 一次观看一行(展示+发奖
     # 按 ad_session_id 合并);一次比价 / 一次领券 = 该次整场多条广告按 ad_session_id 聚成一行(展开看逐条)。
@@ -416,6 +439,7 @@ def ad_revenue_report(
         "daily": daily,
         "hourly": hourly,
         "type_stats": type_stats,
+        "scene_stats": scene_stats,
         "dau": dau,
         "items": main_rows[offset:offset + limit],
     }

app/admin/repositories/admin_role.py

@@ -0,0 +1,81 @@
+"""admin_role 表 CRUD + 「角色 → 有效可见页」解析。"""
+from __future__ import annotations
+
+from sqlalchemy import select
+from sqlalchemy.orm import Session
+
+from app.admin.permissions import (
+    ALL_PAGE_KEYS,
+    BUILTIN_ROLES,
+    SUPER_ADMIN_ROLE,
+    sanitize_pages,
+)
+from app.models.admin_role import AdminRole
+
+
+def ensure_builtin_roles(db: Session) -> None:
+    """空表时播种内建角色(管理员/运营/财务/技术)。幂等:表非空即 no-op。
+    给 create_all 环境(测试 / 未跑迁移的全新库)兜底,迁移已播种则不重复。
+    仅 super_admin 为 is_builtin(锁定不可改删);运营/财务/技术可编辑页/删除。"""
+    if db.execute(select(AdminRole.id).limit(1)).first() is not None:
+        return
+    db.add_all([
+        AdminRole(
+            name=r["name"], label=r["label"], pages=list(r["pages"]),
+            is_builtin=(r["name"] == SUPER_ADMIN_ROLE),
+        )
+        for r in BUILTIN_ROLES
+    ])
+    db.commit()
+
+
+def list_roles(db: Session) -> list[AdminRole]:
+    ensure_builtin_roles(db)
+    # super_admin(内建)恒排最前,其余按创建序
+    return list(
+        db.execute(
+            select(AdminRole).order_by(AdminRole.is_builtin.desc(), AdminRole.id)
+        ).scalars().all()
+    )
+
+
+def get_role(db: Session, name: str) -> AdminRole | None:
+    return db.execute(
+        select(AdminRole).where(AdminRole.name == name)
+    ).scalar_one_or_none()
+
+
+def create_role(db: Session, *, name: str, label: str, pages: list[str]) -> AdminRole:
+    # 自定义角色:name(key)= label = 用户输入的名称
+    role = AdminRole(name=name, label=label, pages=sanitize_pages(pages), is_builtin=False)
+    db.add(role)
+    db.commit()
+    db.refresh(role)
+    return role
+
+
+def update_role(
+    db: Session, role: AdminRole, *, label: str | None = None, pages: list[str] | None = None
+) -> AdminRole:
+    # 只改展示名 label + 可见页;name(key)不可变(admin_user.role / require_role 承重)
+    if label is not None:
+        role.label = label
+    if pages is not None:
+        role.pages = sanitize_pages(pages)
+    db.commit()
+    db.refresh(role)
+    return role
+
+
+def delete_role(db: Session, role: AdminRole) -> None:
+    db.delete(role)
+    db.commit()
+
+
+def effective_pages_of(db: Session, role_name: str) -> list[str]:
+    """某角色名的有效可见页:super_admin → 全部;其余 → 查表 pages 与目录取交。"""
+    if role_name == SUPER_ADMIN_ROLE:
+        return list(ALL_PAGE_KEYS)
+    ensure_builtin_roles(db)
+    role = get_role(db, role_name)
+    return sanitize_pages(role.pages if role else None)

app/admin/repositories/admin_user.py

@@ -20,12 +20,23 @@ def get_by_username(db: Session, username: str) -> AdminUser | None:
 
 
 def create_admin(
-    db: Session, *, username: str, password: str, role: str = "operator"
+    db: Session,
+    *,
+    username: str,
+    password: str,
+    role: str = "operator",
+    plain_password: str | None = None,
+    pages_override: list[str] | None = None,
 ) -> AdminUser:
+    """建管理员。plain_password 非空则额外留存明文(后台 UI 建的账号传,供权限管理页复看);
+    脚本/起后台建账号不传(留 None → 前端不显示密码)。
+    pages_override:role=="custom" 时传专属可见页 key 列表;普通角色为 None。"""
     admin = AdminUser(
         username=username,
         password_hash=hash_password(password),
         role=role,
+        plain_password=plain_password,
+        pages_override=pages_override,
     )
     db.add(admin)
     db.commit()

app/admin/repositories/analytics_health.py

@@ -0,0 +1,146 @@
+"""埋点健康度聚合(埋点成功率 / 上报成功率)。
+
+只存原始累计快照,查询时在 Python 侧差分聚合(admin 低频、量级小,跨 PG/SQLite 无方言坑;
+与 cps.py / coupon_data.py 同款约定)。差分按 (device_id, epoch_id, event) 分区、created_at
+升序,相邻做差、负值夹 0;每增量按其快照 created_at 归入北京天桶。
+"""
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import UTC, datetime
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.core import rewards
+from app.models.analytics_selfstat import AnalyticsSelfStat as H
+from app.models.analytics_selfstat import AnalyticsSelfStatEvent as E
+
+_COUNTS = ("attempted", "drop_capture", "delivered", "drop_undelivered")
+
+
+def diff_snapshots(rows: list[dict]) -> list[dict]:
+    """累计快照行 → 每快照增量行(纯逻辑)。
+
+    rows 每行含 device_id/epoch_id/event/created_at/app_ver/oem/os + 四个累计计数。
+    返回每行含 dims + created_at + 四个增量 d_*(分区首行增量=累计值;负值夹 0)。
+    """
+    parts: dict[tuple, list[dict]] = defaultdict(list)
+    for r in rows:
+        parts[(r["device_id"], r["epoch_id"], r["event"])].append(r)
+
+    out: list[dict] = []
+    for group in parts.values():
+        group.sort(key=lambda r: (r["created_at"], r.get("id", 0)))
+        prev = {k: 0 for k in _COUNTS}
+        for r in group:
+            deltas = {f"d_{k}": max(0, int(r[k]) - prev[k]) for k in _COUNTS}
+            out.append({
+                "device_id": r["device_id"], "epoch_id": r["epoch_id"], "event": r["event"],
+                "created_at": r["created_at"], "app_ver": r["app_ver"],
+                "oem": r["oem"], "os": r["os"], **deltas,
+            })
+            prev = {k: int(r[k]) for k in _COUNTS}
+    return out
+
+
+def _cn_day(dt: datetime) -> str:
+    """created_at(UTC 口径)→ 北京日期字符串 YYYY-MM-DD。naive 当 UTC,tz-aware 直接换算。"""
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=UTC)
+    return dt.astimezone(rewards.CN_TZ).date().isoformat()
+
+
+def _rates(sums: dict) -> dict:
+    """由四个增量和派生两段率(分母 0 → None)。"""
+    persisted_denom = sums["attempted"]
+    report_denom = sums["delivered"] + sums["drop_undelivered"]
+    return {
+        **sums,
+        "track_success_rate": (
+            (sums["attempted"] - sums["drop_capture"]) / persisted_denom
+            if persisted_denom else None
+        ),
+        "report_success_rate": (
+            sums["delivered"] / report_denom if report_denom else None
+        ),
+    }
+
+
+def _sum_deltas(deltas: list[dict]) -> dict:
+    return {k: sum(d[f"d_{k}"] for d in deltas) for k in _COUNTS}
+
+
+def _fetch_rows(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    """取 [from, to) 区间行 + 每分区在 from 左侧的最后一条基线行(供第一条区间增量做差)。"""
+    cols = (
+        H.id, H.device_id, H.epoch_id, E.event, H.created_at,
+        H.app_ver, H.oem, H.os,
+        E.attempted, E.drop_capture, E.delivered, E.drop_undelivered,
+    )
+    in_range = db.execute(
+        select(*cols).join(E, E.snapshot_id == H.id)
+        .where(H.created_at >= date_from, H.created_at < date_to)
+    ).mappings().all()
+
+    # 注:基线子查询无下界扫 from 左侧全量(spec §7 已接受的取舍;量级变大再上物化 rollup)。
+    # 用 max(id) 而非 max(created_at) 选"最新一条":id 严格单调,避免 SQLite 秒级时间戳撞车时选歧义。
+    sub = (
+        select(H.device_id, H.epoch_id, E.event, func.max(H.id).label("max_id"))
+        .join(E, E.snapshot_id == H.id)
+        .where(H.created_at < date_from)
+        .group_by(H.device_id, H.epoch_id, E.event)
+        .subquery()
+    )
+    baseline = db.execute(
+        select(*cols).join(E, E.snapshot_id == H.id).join(
+            sub, sub.c.max_id == H.id
+        )
+    ).mappings().all()
+
+    return [dict(r) for r in list(baseline) + list(in_range)]
+
+
+def _in_range_deltas(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    """差分后只保留 created_at ∈ [from, to) 的增量(基线行被差分用后丢弃)。
+
+    Python 侧过滤需对齐 tz 口径:SQLite 返回 naive UTC,PG 返回 aware UTC。
+    统一转成 naive UTC 再比较,兼容两种后端。
+    """
+    def _to_naive_utc(dt: datetime) -> datetime:
+        if dt.tzinfo is not None:
+            return dt.astimezone(UTC).replace(tzinfo=None)
+        return dt
+
+    from_naive = _to_naive_utc(date_from)
+    to_naive = _to_naive_utc(date_to)
+    deltas = diff_snapshots(_fetch_rows(db, date_from, date_to))
+    return [d for d in deltas if from_naive <= _to_naive_utc(d["created_at"]) < to_naive]
+
+
+def overview(db: Session, date_from: datetime, date_to: datetime) -> dict:
+    deltas = _in_range_deltas(db, date_from, date_to)
+    return _rates(_sum_deltas(deltas))
+
+
+def trend(db: Session, date_from: datetime, date_to: datetime) -> list[dict]:
+    deltas = _in_range_deltas(db, date_from, date_to)
+    by_day: dict[str, list[dict]] = defaultdict(list)
+    for d in deltas:
+        by_day[_cn_day(d["created_at"])].append(d)
+    return [
+        {"day": day, **_rates(_sum_deltas(items))}
+        for day, items in sorted(by_day.items())
+    ]
+
+
+def breakdown(db: Session, date_from: datetime, date_to: datetime, dim: str) -> list[dict]:
+    if dim not in ("event", "app_ver", "oem"):
+        raise ValueError(f"invalid dim: {dim!r}")
+    deltas = _in_range_deltas(db, date_from, date_to)
+    by_key: dict[str, list[dict]] = defaultdict(list)
+    for d in deltas:
+        by_key[d.get(dim) or "(unknown)"].append(d)
+    rows = [{"key": key, **_rates(_sum_deltas(items))} for key, items in by_key.items()]
+    rows.sort(key=lambda r: (r["report_success_rate"] is None, r["report_success_rate"] or 0.0))
+    return rows

app/admin/repositories/coupon_data.py

@@ -5,17 +5,21 @@
 - 发起数 = 区间内全部 session(含 started/completed/failed/abandoned),= 流失统计的基数。
 - 完成数 / 耗时均值 / 分位 = 仅 status==completed 子集(成功跑完才有可比的"领券耗时")。
 - summary/daily/hourly/total 在全量上算,不受分页;items 为排序后当前页。
+- 另含 coupon_slot_report(数据源 coupon_claim_record):按 coupon_id「按券成功率」表,见设计 §13。
 """
 from __future__ import annotations
 
-from datetime import UTC, date as _date, datetime
+from datetime import UTC, datetime
+from datetime import date as _date
 
-from sqlalchemy import func, or_, select
+from sqlalchemy import case, func, or_, select
 from sqlalchemy.orm import Session
 
 from app.core import rewards
-from app.models.coupon_state import CouponSession
+from app.models.coupon_state import CouponClaimRecord, CouponSession
 from app.models.user import User
+from app.repositories import ad_ecpm as crud_ecpm
+from app.repositories.coupon_state import DEFAULT_PLATFORMS, coupon_id_to_platform
 
 
 def _cn_hour(dt: datetime) -> int:
@@ -42,7 +46,47 @@ def _avg(vals: list[int]) -> int | None:
     return round(sum(vals) / len(vals)) if vals else None
 
 
-def _session_to_row(r, phone: str | None = None, nickname: str | None = None) -> dict:
+def _success_rates(rows: list) -> dict:
+    """平台粒度成功率(见 docs/guides/领券成功率指标-设计与埋点.md §3/§12):
+
+    - sel(s) = 勾选平台(`platforms` 空 → 全领三档 DEFAULT_PLATFORMS);
+    - succ(s) = `platform_success` ∩ sel(至少领到一张的平台);
+    - ② 整单成功率 = #{sel⊆succ 且 sel≠∅} / 发起数;
+    - ③ 点位成功率 = Σ|succ| / Σ|sel|;per_platform[p] = 勾了 p 且成功 / 勾了 p。
+    基数含全部 session(started/completed/failed/abandoned),与「发起数」同基数。
+    """
+    started = len(rows)
+    full_success = 0
+    point_success = 0
+    point_total = 0
+    per_succ = {p: 0 for p in DEFAULT_PLATFORMS}
+    per_total = {p: 0 for p in DEFAULT_PLATFORMS}
+    for r in rows:
+        sel = set(r.platforms) if r.platforms else set(DEFAULT_PLATFORMS)
+        succ = set(r.platform_success or []) & sel
+        point_success += len(succ)
+        point_total += len(sel)
+        if sel and succ == sel:
+            full_success += 1
+        for p in sel:
+            if p in per_total:  # 只统计三档已知平台;未知/非法平台 id 不进 per_platform
+                per_total[p] += 1
+                if p in succ:
+                    per_succ[p] += 1
+    return {
+        "full_success_count": full_success,
+        "full_success_rate": round(full_success / started, 4) if started else None,
+        "point_success_count": point_success,
+        "point_total_count": point_total,
+        "point_success_rate": round(point_success / point_total, 4) if point_total else None,
+        "per_platform": {
+            p: (round(per_succ[p] / per_total[p], 4) if per_total[p] else None)
+            for p in DEFAULT_PLATFORMS
+        },
+    }
+
+
+def _session_to_row(r, phone: str | None = None, nickname: str | None = None, ad_revenue_yuan: float = 0.0) -> dict:
     """CouponSession ORM → 明细行 dict(主表「领券数据」与「用户全部领券」抽屉共用)。"""
     return {
         "id": r.id,
@@ -61,6 +105,7 @@ def _session_to_row(r, phone: str | None = None, nickname: str | None = None) ->
         "started_at": r.started_at,
         "claimed_count": r.claimed_count,
         "trace_url": r.trace_url,
+        "ad_revenue_yuan": ad_revenue_yuan,
     }
 
 
@@ -84,6 +129,7 @@ def coupon_data_report(
     date_to: str,
     user: str | None = None,
     app_env: str | None = None,
+    statuses: list[str] | None = None,
     granularity: str = "day",
     limit: int = 500,
     offset: int = 0,
@@ -93,6 +139,8 @@ def coupon_data_report(
 
     - user:手机号/昵称模糊搜(匹配不到任何用户 → 空结果)。
     - app_env:prod/dev 精确;None=全部。
+    - statuses:领券状态多选(started/completed/failed/abandoned);None/空=全部。整个视图
+      (汇总/成功率/趋势/明细)按选中状态算,与 app_env 同级过滤(方案 A)。
     - sort:time=发起时刻倒序(默认) / elapsed=全程耗时倒序(None 末尾)。
     """
     by_hour = granularity == "hour"
@@ -115,6 +163,8 @@ def coupon_data_report(
     )
     if app_env is not None:
         stmt = stmt.where(CouponSession.app_env == app_env)
+    if statuses:
+        stmt = stmt.where(CouponSession.status.in_(statuses))
     if user_ids is not None:
         stmt = stmt.where(CouponSession.user_id.in_(user_ids))
     rows = list(db.execute(stmt).scalars())
@@ -131,6 +181,7 @@ def coupon_data_report(
         "p50_ms": _percentile(completed_elapsed, 50),
         "p95_ms": _percentile(completed_elapsed, 95),
         "p99_ms": _percentile(completed_elapsed, 99),
+        **_success_rates(rows),
     }
 
     # ── 按天趋势(柱=发起/完成数,线=平均耗时)──
@@ -197,10 +248,11 @@ def coupon_data_report(
                 select(User.id, User.phone, User.nickname).where(User.id.in_(uids))
             ).all()
         }
+    rev_map = crud_ecpm.revenue_yuan_by_trace(db, [r.trace_id for r in page])
     items = []
     for r in page:
         phone, nickname = user_map.get(r.user_id, (None, None)) if r.user_id is not None else (None, None)
-        items.append(_session_to_row(r, phone, nickname))
+        items.append(_session_to_row(r, phone, nickname, ad_revenue_yuan=rev_map.get(r.trace_id, 0.0)))
 
     return {
         "summary": summary,
@@ -222,4 +274,57 @@ def coupon_user_records(db: Session, *, user_id: int, limit: int = 100) -> dict:
     total = db.execute(
         select(func.count()).select_from(CouponSession).where(CouponSession.user_id == user_id)
     ).scalar_one()
-    return {"items": [_session_to_row(r) for r in rows], "total": int(total)}
+    rev_map = crud_ecpm.revenue_yuan_by_trace(db, [r.trace_id for r in rows])
+    return {
+        "items": [_session_to_row(r, ad_revenue_yuan=rev_map.get(r.trace_id, 0.0)) for r in rows],
+        "total": int(total),
+    }
+
+
+_SLOT_OK = ("success", "already_claimed")
+_SLOT_TRIED = ("success", "already_claimed", "failed")
+
+
+def coupon_slot_report(
+    db: Session, *, date_from: str, date_to: str, app_env: str | None = None
+) -> dict:
+    """按 coupon_id(具体券)聚合成功率(见 docs/guides/领券成功率指标-设计与埋点.md §13)。
+
+    数据源 coupon_claim_record(粒度=设备-天,唯一键 device+coupon+day)。
+    - 尝试 = status ∈ {success, already_claimed, failed}(skipped 排除);
+    - 成功 = status ∈ {success, already_claimed};成功率 = 成功/尝试;
+    - claim_date 区间 + app_env(None=全部)过滤;按 tried 倒序返回。
+    """
+    d_from = _date.fromisoformat(date_from)
+    d_to = _date.fromisoformat(date_to)
+    ok = case((CouponClaimRecord.status.in_(_SLOT_OK), 1), else_=0)
+    stmt = (
+        select(
+            CouponClaimRecord.coupon_id,
+            func.max(CouponClaimRecord.coupon_name).label("coupon_name"),
+            func.count().label("tried"),
+            func.sum(ok).label("succeeded"),
+        )
+        .where(
+            CouponClaimRecord.claim_date >= d_from,
+            CouponClaimRecord.claim_date <= d_to,
+            CouponClaimRecord.status.in_(_SLOT_TRIED),
+        )
+        .group_by(CouponClaimRecord.coupon_id)
+    )
+    if app_env is not None:
+        stmt = stmt.where(CouponClaimRecord.app_env == app_env)
+    items = []
+    for coupon_id, coupon_name, tried, succeeded in db.execute(stmt).all():
+        tried = int(tried or 0)
+        succeeded = int(succeeded or 0)
+        items.append({
+            "coupon_id": coupon_id,
+            "coupon_name": coupon_name,
+            "platform": coupon_id_to_platform(coupon_id),
+            "tried": tried,
+            "succeeded": succeeded,
+            "success_rate": round(succeeded / tried, 4) if tried else None,
+        })
+    items.sort(key=lambda x: (-x["tried"], x["coupon_id"]))
+    return {"items": items}

app/admin/repositories/cps.py

@@ -51,7 +51,27 @@ def _yuan_to_cents(v: object) -> int | None:
 
 def _ts_to_dt(ts: object) -> datetime | None:
     """秒级时间戳 → tz-aware UTC datetime(绝对时刻,前端按北京展示)。"""
-    if not ts:
+    if ts is None:
+        return None
+    if isinstance(ts, datetime):
+        return ts if ts.tzinfo else ts.replace(tzinfo=_BJ_TZ).astimezone(timezone.utc)
+    s = str(ts).strip()
+    if not s or s.lower() == "null":
+        return None
+    try:
+        seconds = float(Decimal(s))
+    except (InvalidOperation, ValueError):
+        return None
+    if seconds == 0:
+        return None
+    # 美团文档是秒级时间戳，这里顺手兼容毫秒/微秒，避免上游格式变化导致时间再次落空。
+    if abs(seconds) > 10_000_000_000_000:
+        seconds /= 1_000_000
+    elif abs(seconds) > 10_000_000_000:
+        seconds /= 1_000
+    try:
+        return datetime.fromtimestamp(seconds, tz=timezone.utc)
+    except (OverflowError, OSError, ValueError):
         return None
 
 
@@ -83,10 +103,6 @@ def _pick(row: dict[str, Any], *keys: str) -> Any:
         if key in row and row[key] is not None:
             return row[key]
     return None
-    try:
-        return datetime.fromtimestamp(int(ts), tz=timezone.utc)
-    except (ValueError, OSError, TypeError):
-        return None
 
 
 # ───────────── 群 ─────────────

app/admin/repositories/queries.py

@@ -18,12 +18,20 @@ 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.coupon_state import CouponPromptEngagement
 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
 from app.models.user import User
-from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder
+from app.models.wallet import (
+    CashTransaction,
+    CoinAccount,
+    CoinTransaction,
+    InviteCashTransaction,
+    WithdrawOrder,
+)
+from app.repositories import activity, ad_ecpm
 
 # 折算成可提现现金时,非广告金币来源的排除集(广告单独统计、人工调整不算"赚取")
 _NON_TASK_BIZ_TYPES = ("reward_video", "feed_ad_reward", "admin_grant", "admin_deduct")
@@ -76,6 +84,43 @@ def offset_paginate(
     return items, next_cursor, total
 
 
+def _attach_last_active(db: Session, users: list[User]) -> None:
+    """给本页用户瞬态挂 last_active_at(非 DB 列,供 AdminUserListItem from_attributes 读)。
+
+    口径同 [_last_active_expr];按本页 user_id 批量两次 GROUP BY,防 N+1。
+    """
+    uids = [u.id for u in users]
+    if not uids:
+        return
+    ev_map = dict(
+        db.execute(
+            select(AnalyticsEvent.user_id, func.max(AnalyticsEvent.created_at))
+            .where(
+                AnalyticsEvent.user_id.in_(uids),
+                activity.active_event_condition(),
+            )
+            .group_by(AnalyticsEvent.user_id)
+        ).all()
+    )
+    eng_map = dict(
+        db.execute(
+            select(CouponPromptEngagement.user_id, func.max(CouponPromptEngagement.created_at))
+            .where(
+                CouponPromptEngagement.user_id.in_(uids),
+                CouponPromptEngagement.engage_type == "claim_started",
+            )
+            .group_by(CouponPromptEngagement.user_id)
+        ).all()
+    )
+    for u in users:
+        candidates = [
+            activity.norm_utc(u.created_at),      # baseline 由 last_login_at 改为 created_at(登录不算活跃)
+            activity.norm_utc(ev_map.get(u.id)),
+            activity.norm_utc(eng_map.get(u.id)),
+        ]
+        u.last_active_at = max((c for c in candidates if c is not None), default=None)
+
+
 def list_users(
     db: Session,
     *,
@@ -87,16 +132,30 @@ def list_users(
     created_to: datetime | None = None,
     last_login_from: datetime | None = None,
     last_login_to: datetime | None = None,
+    last_active_from: datetime | None = None,
+    last_active_to: datetime | None = None,
     sort_by: str = "id",
     sort_order: str = "desc",
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[User], int | None, int]:
-    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录时间范围筛选,
-    按 id·注册时间·最近登录排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
+    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录·最近活跃
+    时间范围筛选,按 id·注册时间·最近登录·最近活跃排序;每页附带计算列 last_active_at
+    (口径见 [_last_active_expr])。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
     代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
     日期入参统一转 tz-aware UTC 比较(列为 timestamptz,见 _as_utc)。"""
-    stmt = select(User)
+    # 最近活跃 = max(注册时间, 最近行为事件, 最近领券发起)。baseline 由 last_login_at 改为 created_at
+    #(登录不代表在用 App;口径统一到 activity.py,含 home_visible + 比价 + 领券,见 activity.ACTIVE_EVENTS)。
+    # 未命中侧 coalesce 到 created_at(恒非空基线)。派生表 1:1,outerjoin 不放大行数。
+    ev_agg, eng_agg = activity.last_active_subqueries(db)
+    last_active = activity.last_active_expr(
+        User.created_at, ev_agg, eng_agg, db.get_bind().dialect.name
+    )
+    stmt = (
+        select(User)
+        .outerjoin(ev_agg, ev_agg.c.user_id == User.id)
+        .outerjoin(eng_agg, eng_agg.c.user_id == User.id)
+    )
     if phone:
         stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
     if register_channel:
@@ -113,16 +172,25 @@ def list_users(
         stmt = stmt.where(User.last_login_at >= _as_utc(last_login_from))
     if last_login_to is not None:
         stmt = stmt.where(User.last_login_at <= _as_utc(last_login_to))
+    if last_active_from is not None:
+        stmt = stmt.where(last_active >= _as_utc(last_active_from))
+    if last_active_to is not None:
+        stmt = stmt.where(last_active <= _as_utc(last_active_to))
 
     sort_cols = {
         "id": User.id,
         "created_at": User.created_at,
         "last_login_at": User.last_login_at,
+        "last_active_at": last_active,
     }
     sort_col = sort_cols.get(sort_by, User.id)
     order_fn = asc if sort_order == "asc" else desc
     id_order = asc(User.id) if sort_order == "asc" else desc(User.id)
-    return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)
+    items, next_cursor, total = offset_paginate(
+        db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
+    )
+    _attach_last_active(db, items)
+    return items, next_cursor, total
 
 
 def _attach_user_info(db: Session, records: list[ComparisonRecord | Feedback | PriceReport]) -> None:
@@ -148,11 +216,14 @@ def list_comparison_records(
     phone: str | None = None,
     status: str | None = None,
     business_type: str | None = None,
+    store: str | None = None,
+    product: str | None = None,
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[ComparisonRecord], int | None, int]:
     """admin 比价记录列表(debug)。按 user_id 精确 或 phone 前缀定位用户 + status/业务类型筛,
-    offset 分页(创建时间倒序、id 兜底)。join User 取 phone/nickname 瞬态挂记录上。"""
+    store(店名)/product(商品名)子串模糊匹配,offset 分页(创建时间倒序、id 兜底)。
+    join User 取 phone/nickname 瞬态挂记录上。"""
     stmt = select(ComparisonRecord)
     if user_id is not None:
         stmt = stmt.where(ComparisonRecord.user_id == user_id)
@@ -166,12 +237,22 @@ def list_comparison_records(
         stmt = stmt.where(ComparisonRecord.status == status)
     if business_type:
         stmt = stmt.where(ComparisonRecord.business_type == business_type)
+    if store:
+        stmt = stmt.where(ComparisonRecord.store_name.like(f"%{store}%"))
+    if product:
+        # 商品名搜 product_names 派生文本列(非 items JSON:SQLite 下 JSON 中文被转义无法直接 LIKE)。
+        stmt = stmt.where(ComparisonRecord.product_names.like(f"%{product}%"))
     items, next_cursor, total = offset_paginate(
         db, stmt,
         (desc(ComparisonRecord.created_at), desc(ComparisonRecord.id)),
         limit=limit, cursor=cursor,
     )
     _attach_user_info(db, items)
+    # 「本次比价看广告的预估收益」:按本页 trace_id 一次性聚合(同 _attach_user_info 逐页范式)。
+    # ad_revenue_yuan 非 ORM 列,仅瞬态挂实例上供 AdminComparisonListItem(from_attributes)读出。
+    rev = ad_ecpm.revenue_yuan_by_trace(db, [it.trace_id for it in items])
+    for it in items:
+        it.ad_revenue_yuan = rev.get(it.trace_id, 0.0)
     return items, next_cursor, total
 
 
@@ -726,26 +807,19 @@ def withdraw_risk_flags(
     return flags, score
 
 
-def withdraw_ledger_check(db: Session) -> dict:
-    cash_balance_total = int(
-        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
-    )
-    cash_txn_total = int(
-        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
-    )
+def _check_withdraw_ledger_side(
+    orders: list[WithdrawOrder], txns: list, *, withdraw_biz: str, refund_biz: str
+) -> dict:
+    """对某一本账(普通现金 / 邀请奖励金)做提现单 ↔ 流水的交叉校验。
 
-    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
-    cash_txns = list(
-        db.execute(
-            select(CashTransaction).where(
-                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
-            )
-        ).scalars().all()
-    )
-    withdraw_refs = {txn.ref_id for txn in cash_txns if txn.biz_type == "withdraw"}
+    orders 已按 source 过滤到本账;txns 是本账流水表里 withdraw_biz/refund_biz 两类流水。
+    规则:每单发起应有一条扣款流水(ref_id=out_bill_no);失败/拒绝单应有且仅一条退款流水;
+    非退款终态不应出现退款流水。四个计数全为 0 即本账自洽。
+    """
+    withdraw_refs = {txn.ref_id for txn in txns if txn.biz_type == withdraw_biz}
     refund_counts: dict[str, int] = {}
-    for txn in cash_txns:
-        if txn.biz_type == "withdraw_refund" and txn.ref_id:
+    for txn in txns:
+        if txn.biz_type == refund_biz and txn.ref_id:
             refund_counts[txn.ref_id] = refund_counts.get(txn.ref_id, 0) + 1
 
     missing_withdraw = 0
@@ -760,24 +834,95 @@ def withdraw_ledger_check(db: Session) -> dict:
         if has_refund and order.status not in {"failed", "rejected"}:
             refund_on_non_terminal += 1
 
-    duplicate_refund = sum(1 for count in refund_counts.values() if count > 1)
-    diff = cash_balance_total - cash_txn_total
+    return {
+        "missing_withdraw": missing_withdraw,
+        "missing_refund": missing_refund,
+        "duplicate_refund": sum(1 for count in refund_counts.values() if count > 1),
+        "refund_on_non_terminal": refund_on_non_terminal,
+    }
+
+
+def withdraw_ledger_check(db: Session) -> dict:
+    """现金账本校验:两本物理隔离的账各自对账(产品红线:coin_cash / invite_cash 不串)。
+
+    普通现金:CoinAccount.cash_balance_cents ↔ cash_transaction(withdraw/withdraw_refund);
+    邀请奖励金:CoinAccount.invite_cash_balance_cents ↔ invite_cash_transaction
+              (invite_withdraw/invite_withdraw_refund)。
+    提现单按 source 分流到对应账核对——邀请提现的流水写在 invite_cash_transaction 表,
+    绝不能拿去和普通现金流水比(否则每笔邀请提现单都会被误报「缺扣款/缺退款流水」)。
+    分流口径与 create_withdraw 一致:仅 source==invite_cash 走邀请账,其余(含历史空值)归普通现金。
+    """
+    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
+    coin_orders = [o for o in orders if o.source != "invite_cash"]
+    invite_orders = [o for o in orders if o.source == "invite_cash"]
+
+    # —— 普通现金账(coin_cash) ——
+    cash_balance_total = int(
+        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
+    )
+    cash_txn_total = int(
+        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
+    )
+    cash_txns = list(
+        db.execute(
+            select(CashTransaction).where(
+                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
+            )
+        ).scalars().all()
+    )
+    coin = _check_withdraw_ledger_side(
+        coin_orders, cash_txns, withdraw_biz="withdraw", refund_biz="withdraw_refund"
+    )
+    cash_diff = cash_balance_total - cash_txn_total
+
+    # —— 邀请奖励金账(invite_cash,独立账户 + 独立流水表) ——
+    invite_balance_total = int(
+        db.execute(
+            select(func.coalesce(func.sum(CoinAccount.invite_cash_balance_cents), 0))
+        ).scalar_one()
+    )
+    invite_txn_total = int(
+        db.execute(
+            select(func.coalesce(func.sum(InviteCashTransaction.amount_cents), 0))
+        ).scalar_one()
+    )
+    invite_txns = list(
+        db.execute(
+            select(InviteCashTransaction).where(
+                InviteCashTransaction.biz_type.in_(("invite_withdraw", "invite_withdraw_refund"))
+            )
+        ).scalars().all()
+    )
+    invite = _check_withdraw_ledger_side(
+        invite_orders, invite_txns,
+        withdraw_biz="invite_withdraw", refund_biz="invite_withdraw_refund",
+    )
+    invite_diff = invite_balance_total - invite_txn_total
+
     ok = (
-        diff == 0
-        and missing_withdraw == 0
-        and missing_refund == 0
-        and duplicate_refund == 0
-        and refund_on_non_terminal == 0
+        cash_diff == 0
+        and invite_diff == 0
+        and all(v == 0 for v in coin.values())
+        and all(v == 0 for v in invite.values())
     )
     return {
         "ok": ok,
+        # 普通现金账(coin_cash:金币兑换的现金)
         "cash_balance_total_cents": cash_balance_total,
         "cash_transaction_total_cents": cash_txn_total,
-        "balance_diff_cents": diff,
-        "missing_withdraw_txn_count": missing_withdraw,
-        "missing_refund_txn_count": missing_refund,
-        "duplicate_refund_txn_count": duplicate_refund,
-        "refund_txn_on_non_terminal_count": refund_on_non_terminal,
+        "balance_diff_cents": cash_diff,
+        "missing_withdraw_txn_count": coin["missing_withdraw"],
+        "missing_refund_txn_count": coin["missing_refund"],
+        "duplicate_refund_txn_count": coin["duplicate_refund"],
+        "refund_txn_on_non_terminal_count": coin["refund_on_non_terminal"],
+        # 邀请奖励金账(invite_cash:与普通现金物理隔离,各自对账)
+        "invite_cash_balance_total_cents": invite_balance_total,
+        "invite_cash_transaction_total_cents": invite_txn_total,
+        "invite_balance_diff_cents": invite_diff,
+        "invite_missing_withdraw_txn_count": invite["missing_withdraw"],
+        "invite_missing_refund_txn_count": invite["missing_refund"],
+        "invite_duplicate_refund_txn_count": invite["duplicate_refund"],
+        "invite_refund_txn_on_non_terminal_count": invite["refund_on_non_terminal"],
     }
 
 

app/admin/repositories/stats.py

@@ -5,30 +5,42 @@ user.last_login_at / comparison_record.status / withdraw_order.status)要加索
 """
 from __future__ import annotations
 
+from collections import Counter
 from datetime import date, datetime, time, timedelta, timezone
-from decimal import Decimal, InvalidOperation
+from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
 
-from sqlalchemy import func, select
+from sqlalchemy import case, func, select
 from sqlalchemy.orm import Session
 
+from app.admin.repositories.coupon_data import _percentile
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.ad_reward import AdRewardRecord
 from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
-from app.models.coupon_state import CouponPromptEngagement
+from app.models.coupon_state import (
+    CouponClaimRecord,
+    CouponPromptEngagement,
+    CouponSession,
+)
 from app.models.cps_order import CpsOrder
 from app.models.feedback import Feedback
 from app.models.savings import SavingsRecord
-from app.models.signin import SigninBoostRecord, SigninRecord
+from app.models.signin import SigninRecord
 from app.models.user import User
 from app.models.wallet import CoinTransaction, WithdrawOrder
 
 _BEIJING = timezone(timedelta(hours=8))
-COUPON_REWARD_BIZ_TYPES = ("reward_video", "ad_reward", "coupon", "coupon_reward")
+REWARD_VIDEO_BIZ_TYPES = ("reward_video", "ad_reward")
+# 领券/比价奖励金币的真实来源是信息流广告发奖(ad_feed_reward_record,按 feed_scene 分场景);
+# coin_transaction 里只有扁平的 feed_ad_reward、biz_type 不分 coupon/comparison,故这俩桶历史从未
+# 被写入,仅留作未来兜底,实际金额在下方按 feed_scene 汇总 ad_feed_reward_record 得出。reward_video/
+# ad_reward 是激励视频,单独成桶、不再混进领券奖励(历史误并会把激励视频金币双计进领券)。
+COUPON_REWARD_BIZ_TYPES = ("coupon", "coupon_reward")
 COMPARISON_REWARD_BIZ_TYPES = ("comparison", "compare_reward", "comparison_reward")
 EXCLUDED_REWARD_BIZ_TYPES = ("invite_inviter", "invite_invitee", "admin_grant")
 UNCLASSIFIED_FEED_BIZ_TYPES = ("feed_ad_reward",)
 REGULAR_TASK_EXCLUDED_BIZ_TYPES = (
+    *REWARD_VIDEO_BIZ_TYPES,
     *COUPON_REWARD_BIZ_TYPES,
     *COMPARISON_REWARD_BIZ_TYPES,
     *EXCLUDED_REWARD_BIZ_TYPES,
@@ -55,29 +67,10 @@ def _beijing_today_start_utc() -> datetime:
 def today_dau(db: Session) -> int:
     """今日活跃用户数(DAU):登录 + 开始比价 + 开始领券,按用户去重。
 
-    广告收益报表复用这个函数;历史窗口 DAU 由 dashboard_overview 的 period 口径另算。
+    = period_active_dau(今天, 今天);历史 / 多天窗口用 period_active_dau 传区间(广告收益报表复用)。
     """
     today_bj = datetime.now(_BEIJING).date()
-    today_start = _beijing_today_start_utc()
-    tomorrow_start = today_start + timedelta(days=1)
-    login_user_ids = _id_set(
-        db,
-        select(User.id).where(User.last_login_at >= today_start, User.last_login_at < tomorrow_start),
-    )
-    compare_start_user_ids = _event_user_ids(
-        db, (COMPARE_START_EVENT,), today_start, tomorrow_start
-    )
-    coupon_event_user_ids = _event_user_ids(
-        db, (COUPON_START_EVENT,), today_start, tomorrow_start
-    )
-    coupon_claim_user_ids = _id_set(
-        db,
-        select(CouponPromptEngagement.user_id).where(
-            CouponPromptEngagement.engage_date == today_bj,
-            CouponPromptEngagement.engage_type == "claim_started",
-        ),
-    )
-    return len(login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids)
+    return period_active_dau(db, today_bj, today_bj)
 
 
 def _default_period_end() -> date:
@@ -116,6 +109,23 @@ def _date_range(date_from: date, date_to: date) -> list[date]:
     return [date_from + timedelta(days=i) for i in range(days + 1)]
 
 
+def _duration_percentile(sorted_values: list[int], q: float) -> int | None:
+    """Linear-interpolated percentile with the same half-up rounding as Math.round."""
+    if not sorted_values:
+        return None
+    if len(sorted_values) == 1:
+        return sorted_values[0]
+    index = (len(sorted_values) - 1) * q
+    lower = int(index)
+    upper = min(lower + 1, len(sorted_values) - 1)
+    fraction = Decimal(str(index - lower))
+    value = (
+        Decimal(sorted_values[lower]) * (Decimal(1) - fraction)
+        + Decimal(sorted_values[upper]) * fraction
+    )
+    return int(value.quantize(Decimal("1"), rounding=ROUND_HALF_UP))
+
+
 def _id_set(db: Session, stmt) -> set[int]:
     return {int(v) for v in db.execute(stmt).scalars().all() if v is not None}
 
@@ -134,6 +144,56 @@ def _event_user_ids(
     )
 
 
+def _period_active_user_ids(
+    db: Session,
+    *,
+    start_utc: datetime,
+    end_utc: datetime,
+    period_from: date,
+    period_to: date,
+) -> set[int]:
+    """区间去重活跃用户 id 集合:登录(last_login_at)+ 开始比价(real_compare_start)+
+    开始领券(real_coupon_start / claim_started)。
+
+    user / analytics_event 用 UTC aware 边界 [start_utc, end_utc);coupon_prompt_engagement
+    的 engage_date 是北京自然日 date 列,用 [period_from, period_to] 闭区间。今日 / 历史 / 多天通用。
+    """
+    login_user_ids = _id_set(
+        db,
+        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc),
+    )
+    compare_start_user_ids = _event_user_ids(db, (COMPARE_START_EVENT,), start_utc, end_utc)
+    coupon_event_user_ids = _event_user_ids(db, (COUPON_START_EVENT,), start_utc, end_utc)
+    coupon_claim_user_ids = _id_set(
+        db,
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date >= period_from,
+            CouponPromptEngagement.engage_date <= period_to,
+            CouponPromptEngagement.engage_type == "claim_started",
+        ),
+    )
+    return login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
+
+
+def period_active_dau(db: Session, date_from: date, date_to: date) -> int:
+    """任意北京自然日区间 [date_from, date_to] 的去重活跃用户数。
+
+    与数据大盘 period.users.active 同口径(登录 + 开始比价 + 开始领券);广告收益报表按所选
+    日期区间(含今日)复用,ARPU = 区间预估收益 ÷ 本数。全局口径,不随用户 / 类型 / 场景筛选变化。
+    """
+    period_from, period_to = _normalize_period(date_from, date_to)
+    start_utc, end_utc, _start_local, _end_local = _period_bounds(period_from, period_to)
+    return len(
+        _period_active_user_ids(
+            db,
+            start_utc=start_utc,
+            end_utc=end_utc,
+            period_from=period_from,
+            period_to=period_to,
+        )
+    )
+
+
 def _commission_rate_percent(raw: str | None) -> Decimal | None:
     """美团 commissionRate 原值: "300"=3%, "10"=0.1%;也兼容 "3%"。"""
     if raw is None:
@@ -199,16 +259,46 @@ def dashboard_overview(
         ComparisonRecord.created_at >= start_local,
         ComparisonRecord.created_at < end_local,
     )
-    period_comparison_total = _count(ComparisonRecord, *period_comparison_conds)
-    period_comparison_success = _count(
-        ComparisonRecord,
-        *period_comparison_conds,
-        ComparisonRecord.status == "success",
+    period_comparison_stats = db.execute(
+        select(
+            func.count(ComparisonRecord.id),
+            func.coalesce(
+                func.sum(
+                    case(
+                        (ComparisonRecord.status.in_(("success", "failed")), 1),
+                        else_=0,
+                    )
+                ),
+                0,
+            ),
+            func.coalesce(
+                func.sum(
+                    case((ComparisonRecord.status == "cancelled", 1), else_=0)
+                ),
+                0,
+            ),
+            func.coalesce(
+                func.sum(case((ComparisonRecord.status == "success", 1), else_=0)),
+                0,
+            ),
+            func.coalesce(func.sum(ComparisonRecord.llm_cost_yuan), 0.0),
+        ).where(*period_comparison_conds)
+    ).one()
+    period_comparison_total = int(period_comparison_stats[0])
+    period_comparison_completed = int(period_comparison_stats[1])
+    period_comparison_cancelled = int(period_comparison_stats[2])
+    period_comparison_success = int(period_comparison_stats[3])
+    period_comparison_token_cost_yuan = float(period_comparison_stats[4])
+    period_comparison_success_denominator = (
+        period_comparison_total - period_comparison_cancelled
     )
     period_comparison_success_rate = (
-        round(period_comparison_success / period_comparison_total, 4)
-        if period_comparison_total
-        else 0.0
+        round(
+            period_comparison_success / period_comparison_success_denominator,
+            4,
+        )
+        if period_comparison_success_denominator > 0
+        else None
     )
     period_saved_positive_count = _count(
         ComparisonRecord,
@@ -239,6 +329,47 @@ def dashboard_overview(
         if period_avg_duration_ms is not None
         else None
     )
+    completed_duration_conds = (
+        *period_comparison_conds,
+        ComparisonRecord.status.in_(("success", "failed")),
+        ComparisonRecord.total_ms.is_not(None),
+    )
+    if db.bind is not None and db.bind.dialect.name == "postgresql":
+        period_median_duration_ms, period_p95_duration_ms = db.execute(
+            select(
+                func.percentile_cont(0.5).within_group(ComparisonRecord.total_ms),
+                func.percentile_cont(0.95).within_group(ComparisonRecord.total_ms),
+            ).where(*completed_duration_conds)
+        ).one()
+        period_median_duration_ms = (
+            int(
+                Decimal(str(period_median_duration_ms)).quantize(
+                    Decimal("1"), rounding=ROUND_HALF_UP
+                )
+            )
+            if period_median_duration_ms is not None
+            else None
+        )
+        period_p95_duration_ms = (
+            int(
+                Decimal(str(period_p95_duration_ms)).quantize(
+                    Decimal("1"), rounding=ROUND_HALF_UP
+                )
+            )
+            if period_p95_duration_ms is not None
+            else None
+        )
+    else:
+        # SQLite 测试环境没有 percentile_cont；仅回退读取耗时单列，不加载完整记录。
+        completed_durations = list(
+            db.execute(
+                select(ComparisonRecord.total_ms)
+                .where(*completed_duration_conds)
+                .order_by(ComparisonRecord.total_ms)
+            ).scalars()
+        )
+        period_median_duration_ms = _duration_percentile(completed_durations, 0.5)
+        period_p95_duration_ms = _duration_percentile(completed_durations, 0.95)
 
     ordered_exists = (
         select(SavingsRecord.id)
@@ -261,31 +392,19 @@ def dashboard_overview(
     period_new_user_ids = _user_id_set(
         select(User.id).where(User.created_at >= start_utc, User.created_at < end_utc)
     )
-    login_user_ids = _user_id_set(
-        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc)
-    )
-    compare_start_user_ids = _event_user_ids(
-        db, (COMPARE_START_EVENT,), start_utc, end_utc
-    )
-    coupon_event_user_ids = _event_user_ids(
-        db, (COUPON_START_EVENT,), start_utc, end_utc
-    )
-    coupon_claim_user_ids = _user_id_set(
-        select(CouponPromptEngagement.user_id).where(
-            CouponPromptEngagement.engage_date >= period_from,
-            CouponPromptEngagement.engage_date <= period_to,
-            CouponPromptEngagement.engage_type == "claim_started",
-        )
-    )
-    period_active_user_ids = (
-        login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
-    )
-    period_retained_new_user_ids = period_new_user_ids & period_active_user_ids
-    period_retention_rate = (
-        round(len(period_retained_new_user_ids) / len(period_new_user_ids), 4)
-        if period_new_user_ids
-        else None
+    period_active_user_ids = _period_active_user_ids(
+        db,
+        start_utc=start_utc,
+        end_utc=end_utc,
+        period_from=period_from,
+        period_to=period_to,
     )
+    # 留存口径(2026-07-05 产品改):次日留存——窗口内每天 D,取 **D-1 日(前日)新增**用户,
+    # 统计其 D 日活跃(登录/开始比价/开始领券)比例,逐日累加。默认窗口=昨日单天,即
+    # 「前日新增用户的昨日留存」。原口径(窗口内新增∩窗口内活跃)在单日窗口下≈100% 无意义
+    # (注册即登录,当天新增必然当天活跃)。逐日 cohort 在下方 trend 循环内顺带累计。
+    retention_cohort_total = 0
+    retention_retained_total = 0
     trend_points: list[dict] = []
     for cur_date in _date_range(period_from, period_to):
         day_start_utc, day_end_utc, day_start_local, day_end_local = _period_bounds(
@@ -295,33 +414,26 @@ def dashboard_overview(
             ComparisonRecord.created_at >= day_start_local,
             ComparisonRecord.created_at < day_end_local,
         )
-        daily_login_user_ids = _user_id_set(
+        daily_active_user_ids = _period_active_user_ids(
+            db,
+            start_utc=day_start_utc,
+            end_utc=day_end_utc,
+            period_from=cur_date,
+            period_to=cur_date,
+        )
+        # 次日留存:cohort = 前一日(D-1)新增用户,留存 = 其中当日(D)活跃者(口径见上)。
+        cohort_ids = _user_id_set(
             select(User.id).where(
-                User.last_login_at >= day_start_utc,
-                User.last_login_at < day_end_utc,
-            )
-        )
-        daily_compare_start_user_ids = _event_user_ids(
-            db, (COMPARE_START_EVENT,), day_start_utc, day_end_utc
-        )
-        daily_coupon_event_user_ids = _event_user_ids(
-            db, (COUPON_START_EVENT,), day_start_utc, day_end_utc
-        )
-        daily_coupon_claim_user_ids = _user_id_set(
-            select(CouponPromptEngagement.user_id).where(
-                CouponPromptEngagement.engage_date == cur_date,
-                CouponPromptEngagement.engage_type == "claim_started",
+                User.created_at >= day_start_utc - timedelta(days=1),
+                User.created_at < day_end_utc - timedelta(days=1),
             )
         )
+        retention_cohort_total += len(cohort_ids)
+        retention_retained_total += len(cohort_ids & daily_active_user_ids)
         trend_points.append(
             {
                 "date": cur_date,
-                "active_users": len(
-                    daily_login_user_ids
-                    | daily_compare_start_user_ids
-                    | daily_coupon_event_user_ids
-                    | daily_coupon_claim_user_ids
-                ),
+                "active_users": len(daily_active_user_ids),
                 "new_users": _count(
                     User,
                     User.created_at >= day_start_utc,
@@ -330,6 +442,11 @@ def dashboard_overview(
                 "comparisons": _count(ComparisonRecord, *daily_comparison_conds),
             }
         )
+    period_retention_rate = (
+        round(retention_retained_total / retention_cohort_total, 4)
+        if retention_cohort_total
+        else None
+    )
 
     period_coin_conds = (
         CoinTransaction.created_at >= start_local,
@@ -339,7 +456,7 @@ def dashboard_overview(
     period_reward_video_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
-        CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
+        CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
     )
     period_feed_ad_coin_total = _sum(
         CoinTransaction.amount,
@@ -361,15 +478,29 @@ def dashboard_overview(
         *period_coin_conds,
         CoinTransaction.biz_type.like("task_%"),
     )
+    # 领券/比价奖励金币 = biz_type 桶(历史空,兜底)+ 该场景信息流广告实发金币
+    # (ad_feed_reward_record.feed_scene,granted;reward_date 是北京日期串,与 period 同自然日窗口)。
     period_coupon_reward_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
         CoinTransaction.biz_type.in_(COUPON_REWARD_BIZ_TYPES),
+    ) + _sum(
+        AdFeedRewardRecord.coin,
+        AdFeedRewardRecord.status == "granted",
+        AdFeedRewardRecord.feed_scene == "coupon",
+        AdFeedRewardRecord.reward_date >= period_from.isoformat(),
+        AdFeedRewardRecord.reward_date <= period_to.isoformat(),
     )
     period_comparison_reward_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
         CoinTransaction.biz_type.in_(COMPARISON_REWARD_BIZ_TYPES),
+    ) + _sum(
+        AdFeedRewardRecord.coin,
+        AdFeedRewardRecord.status == "granted",
+        AdFeedRewardRecord.feed_scene == "comparison",
+        AdFeedRewardRecord.reward_date >= period_from.isoformat(),
+        AdFeedRewardRecord.reward_date <= period_to.isoformat(),
     )
     period_regular_task_coin_total = _sum(
         CoinTransaction.amount,
@@ -413,6 +544,98 @@ def dashboard_overview(
         else None
     )
 
+    # ===== 领券核心数据(2026-07-05 产品新增)=====
+    # 数据源:coupon_session(一次领券一行,started_date 北京自然日)+ coupon_claim_record
+    # (一券/点位一天一条终态,claim_date 北京自然日)。点位与 session 不按 trace_id 关联——
+    # record_claims 更新路径不覆盖 trace_id(同设备同券同日重跑归第一次的 trace),按
+    # (device_id, 自然日) 桶关联才可靠;同桶多次发起共享同一份点位终态。
+    period_coupon_sessions = db.execute(
+        select(
+            CouponSession.device_id,
+            CouponSession.started_date,
+            CouponSession.status,
+            CouponSession.elapsed_ms,
+        ).where(
+            CouponSession.started_date >= period_from,
+            CouponSession.started_date <= period_to,
+            # 只统计正式环境,同「领券数据」页默认口径(防 debug 包调试数据串台;
+            # 命中 ix_coupon_session_date_env)。点位表无 app_env 列,但点位指标只经
+            # 下方 prod session 触达的 (device, 日) 桶进入统计,随之收敛到 prod。
+            CouponSession.app_env == "prod",
+        )
+    ).all()
+    coupon_started = len(period_coupon_sessions)
+    coupon_completed_elapsed = sorted(
+        s.elapsed_ms
+        for s in period_coupon_sessions
+        if s.status == "completed" and s.elapsed_ms is not None
+    )
+    # 点位桶:(device, 日) → (点位总数, 成功点位数)。成功口径与「我的」页累计领券一致
+    # (sum_claimed_count,2026-06-15 产品定):success + already_claimed(已领过=持有券)都算成功。
+    point_buckets: dict[tuple[str, date], tuple[int, int]] = {
+        (dev, d): (int(total), int(succ or 0))
+        for dev, d, total, succ in db.execute(
+            select(
+                CouponClaimRecord.device_id,
+                CouponClaimRecord.claim_date,
+                func.count(),
+                func.sum(
+                    case(
+                        (CouponClaimRecord.status.in_(("success", "already_claimed")), 1),
+                        else_=0,
+                    )
+                ),
+            )
+            .where(
+                CouponClaimRecord.claim_date >= period_from,
+                # 上界放宽一天:跨零点场次(23:5x 发起)的点位 claim_date 落在发起日+1,
+                # 桶只经下方 session 触达的键参与计数,放宽不会引入无关数据。
+                CouponClaimRecord.claim_date <= period_to + timedelta(days=1),
+            )
+            .group_by(CouponClaimRecord.device_id, CouponClaimRecord.claim_date)
+        ).all()
+    }
+    # 全部领成功的次数:completed 且其 (device, 日) 桶内点位全部成功(桶为空不算)。
+    coupon_all_success = 0
+    completed_bucket_totals: list[int] = []
+    session_bucket_keys: set[tuple[str, date]] = set()
+    for s in period_coupon_sessions:
+        key = (s.device_id, s.started_date)
+        if key not in point_buckets:
+            # 跨零点回退:发起日桶不存在(点位终态全部落在次日)时取 (device, 发起日+1)。
+            # 仅在发起日桶完全缺失时回退,避免抢占该设备次日 session 自己的桶。
+            next_key = (s.device_id, s.started_date + timedelta(days=1))
+            if next_key in point_buckets:
+                key = next_key
+        bucket = point_buckets.get(key)
+        if bucket is not None:
+            session_bucket_keys.add(key)
+        if s.status != "completed" or bucket is None:
+            continue
+        total, succ = bucket
+        completed_bucket_totals.append(total)
+        if total > 0 and succ == total:
+            coupon_all_success += 1
+    # 每次发起的应领点位数:取「完成过的领券」实际点位数的众数(done 帧会给所有点位终态,
+    # 完成场的点位数=当前配置的全量点位数;数据自校准,配置改点位数无需改代码)。本期无完成场
+    # 时给不出,点位成功率置空。
+    coupon_points_per_session = (
+        Counter(completed_bucket_totals).most_common(1)[0][0]
+        if completed_bucket_totals
+        else None
+    )
+    # 成功点位数:本期 session 触达过的 (device, 日) 桶内成功点位之和(桶级去重,同桶重试不重复计)。
+    coupon_point_success = sum(point_buckets[k][1] for k in session_bucket_keys)
+    # 点位成功率 = 成功点位数 / (发起数 × 应领点位数):中途退出未跑到的点位不产生记录,
+    # 但发起数×点位数把它们计入分母 → 视为失败,符合产品口径;重试会拉低该率(分母按次数计)。
+    coupon_point_success_rate = (
+        round(
+            min(1.0, coupon_point_success / (coupon_started * coupon_points_per_session)), 4
+        )
+        if coupon_started and coupon_points_per_session
+        else None
+    )
+
     return {
         "users": {
             "total": _count(User),
@@ -428,7 +651,7 @@ def dashboard_overview(
             "reward_video_coin_total": _sum(
                 CoinTransaction.amount,
                 CoinTransaction.amount > 0,
-                CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
+                CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
             ),
             "reward_video_watch_count": _count(
                 AdRewardRecord,
@@ -455,7 +678,14 @@ def dashboard_overview(
                 CoinTransaction.amount > 0,
                 CoinTransaction.biz_type == "signin_boost",
             ),
-            "signin_boost_watch_count": _count(SigninBoostRecord),
+            # 签到膨胀 2026-07 已下线,signin_boost_record 表随之 drop。这两项保留为**历史口径**
+            # (钱是真发过的,账要能查回)。次数改数金币流水:一次膨胀 = 一笔 signin_boost 流水,
+            # 与原来数 signin_boost_record 行数等价。
+            "signin_boost_watch_count": _count(
+                CoinTransaction,
+                CoinTransaction.biz_type == "signin_boost",
+                CoinTransaction.amount > 0,
+            ),
         },
         "cash": {
             "withdraw_success_cents": _sum(
@@ -476,20 +706,38 @@ def dashboard_overview(
             "users": {
                 "new": len(period_new_user_ids),
                 "active": len(period_active_user_ids),
-                "retained_new_users": len(period_retained_new_user_ids),
+                "retained_new_users": retention_retained_total,
+                "retention_cohort": retention_cohort_total,
                 "retention_rate": period_retention_rate,
                 "retention_note": (
-                    "口径:登录(last_login_at)+开始比价(real_compare_start)+"
-                    "开始领券(real_coupon_start/claim_started),按用户去重"
+                    "次日留存:窗口内每天取前一日新增用户,统计其当日活跃"
+                    "(登录/开始比价/开始领券,按用户去重)比例,逐日累加;"
+                    "默认窗口=昨日,即前日新增用户的昨日留存"
                 ),
             },
             "comparison": {
                 "total": period_comparison_total,
+                "completed": period_comparison_completed,
+                "cancelled": period_comparison_cancelled,
                 "success": period_comparison_success,
                 "success_rate": period_comparison_success_rate,
                 "ordered": period_ordered_count,
                 "average_duration_ms": period_avg_duration_ms,
+                "median_duration_ms": period_median_duration_ms,
+                "p95_duration_ms": period_p95_duration_ms,
                 "average_saved_cents": period_avg_saved_cents,
+                "token_cost_total_yuan": period_comparison_token_cost_yuan,
+            },
+            "coupon": {
+                "started": coupon_started,
+                "all_success": coupon_all_success,
+                "success_rate": (
+                    round(coupon_all_success / coupon_started, 4) if coupon_started else None
+                ),
+                "point_success": coupon_point_success,
+                "points_per_session": coupon_points_per_session,
+                "point_success_rate": coupon_point_success_rate,
+                "median_elapsed_ms": _percentile(coupon_completed_elapsed, 50),
             },
             "coins": {
                 "granted_total": _sum(CoinTransaction.amount, *period_coin_conds),

app/admin/routers/ad_revenue.py

@@ -91,6 +91,7 @@ def get_ad_revenue_report(
         daily=[AdRevenueDaily(**d) for d in result["daily"]],
         hourly=[AdRevenueHourly(**h) for h in result["hourly"]],
         type_stats={k: AdRevenueTypeStat(**v) for k, v in result["type_stats"].items()},
+        scene_stats={k: AdRevenueTypeStat(**v) for k, v in result["scene_stats"].items()},
         dau=result["dau"],
         total=result["total"],
         truncated=result["truncated"],

app/admin/routers/admins.py

@@ -5,6 +5,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request
 
 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
+from app.admin.permissions import CUSTOM_ROLE, SUPER_ADMIN_ROLE, sanitize_pages
+from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.admin import AdminCreateRequest, AdminUpdateRequest
 from app.admin.schemas.auth import AdminOut
@@ -23,9 +25,31 @@ def _active_super_count(db: AdminDb) -> int:
     )
 
 
-@router.get("", response_model=list[AdminOut], summary="管理员列表")
+def _validate_role(db: AdminDb, role: str) -> None:
+    """角色必须是 super_admin / custom(自定义) / admin_role 表里已存在的角色,否则 400。"""
+    if role in (SUPER_ADMIN_ROLE, CUSTOM_ROLE):
+        return
+    role_repo.ensure_builtin_roles(db)  # 空表(测试/全新库)兜底播种,再校验
+    if role_repo.get_role(db, role) is None:
+        raise HTTPException(status_code=400, detail=f"角色不存在: {role}")
+
+
+def _clean_override(role: str, pages_override: list[str] | None) -> list[str] | None:
+    """按最终角色算出该存的 pages_override:custom → 勾选集(过滤非法 key,可空列表);
+    非 custom → None(切回普通角色即清空自定义页)。"""
+    if role == CUSTOM_ROLE:
+        return sanitize_pages(pages_override)
+    return None
+
+
+@router.get("", response_model=list[AdminOut], summary="管理员列表(含明文密码,super_admin 专属)")
 def list_admins(db: AdminDb) -> list[AdminOut]:
-    return [AdminOut.model_validate(a) for a in admin_repo.list_admins(db)]
+    out: list[AdminOut] = []
+    for a in admin_repo.list_admins(db):
+        item = AdminOut.model_validate(a)
+        item.password = a.plain_password  # 明文:仅本 super_admin 专属路由下发,供权限管理页复看
+        out.append(item)
+    return out
 
 
 @router.post("", response_model=AdminOut, summary="创建管理员")
@@ -34,12 +58,17 @@ def create_admin(
 ) -> AdminOut:
     if admin_repo.get_by_username(db, body.username) is not None:
         raise HTTPException(status_code=409, detail="用户名已存在")
+    _validate_role(db, body.role)
+    override = _clean_override(body.role, body.pages_override)
     new = admin_repo.create_admin(
-        db, username=body.username, password=body.password, role=body.role
+        db, username=body.username, password=body.password, role=body.role,
+        plain_password=body.password,  # UI 建的账号留存明文,供权限管理页复看
+        pages_override=override,
     )
     write_audit(
         db, admin, action="admin.create", target_type="admin", target_id=new.id,
-        detail={"username": new.username, "role": new.role}, ip=get_client_ip(request), commit=True,
+        detail={"username": new.username, "role": new.role, "pages_override": override},
+        ip=get_client_ip(request), commit=True,
     )
     return AdminOut.model_validate(new)
 
@@ -67,8 +96,12 @@ def update_admin(
     if demotes_super and _active_super_count(db) <= 1:
         raise HTTPException(status_code=400, detail="不能降级/禁用最后一个超级管理员")
 
+    if body.role is not None:
+        _validate_role(db, body.role)
+
     changes: dict = {}
-    if body.role is not None and body.role != target.role:
+    role_changed = body.role is not None and body.role != target.role
+    if role_changed:
         changes["role"] = {"before": target.role, "after": body.role}
         target.role = body.role
     if body.status is not None and body.status != target.status:
@@ -77,6 +110,18 @@ def update_admin(
     if body.password is not None:
         changes["password"] = "reset"
         target.password_hash = hash_password(body.password)
+        target.plain_password = body.password  # 同步留存明文,权限管理页复看保持一致
+
+    # 自定义可见页:按「最终角色」(target.role,已应用完角色变更)决定该存什么。
+    # - 切到/维持 custom 且传了 pages_override → 用勾选集;切到 custom 没传 → 清成空列表。
+    # - 切回普通角色 → 清空 override(_clean_override 返回 None)。
+    # - 角色没变、只传 pages_override(编辑现有 custom 用户的勾选)→ 也更新。
+    if role_changed or body.pages_override is not None:
+        new_override = _clean_override(target.role, body.pages_override)
+        if new_override != target.pages_override:
+            changes["pages_override"] = {"before": target.pages_override, "after": new_override}
+            target.pages_override = new_override
+
     if not changes:
         raise HTTPException(status_code=400, detail="无任何变更字段")
     db.commit()
@@ -86,3 +131,27 @@ def update_admin(
         detail=changes, ip=get_client_ip(request), commit=True,
     )
     return AdminOut.model_validate(target)
+
+
+@router.delete("/{admin_id}", summary="删除管理员(带审计)")
+def delete_admin(admin_id: int, request: Request, admin: CurrentAdmin, db: AdminDb) -> dict:
+    target = admin_repo.get_by_id(db, admin_id)
+    if target is None:
+        raise HTTPException(status_code=404, detail="管理员不存在")
+    if admin_id == admin.id:
+        raise HTTPException(status_code=400, detail="不能删除自己")
+    # 防自锁:删掉某个 active super_admin 前,确认后仍至少剩 1 个,否则进「零可用超管」死局。
+    if (
+        target.role == "super_admin"
+        and target.status == "active"
+        and _active_super_count(db) <= 1
+    ):
+        raise HTTPException(status_code=400, detail="不能删除最后一个超级管理员")
+    username = target.username
+    db.delete(target)
+    db.commit()
+    write_audit(
+        db, admin, action="admin.delete", target_type="admin", target_id=admin_id,
+        detail={"username": username, "role": target.role}, ip=get_client_ip(request), commit=True,
+    )
+    return {"deleted": True}

app/admin/routers/analytics_health.py

@@ -0,0 +1,49 @@
+"""admin 埋点健康度:埋点成功率 / 上报成功率 总览 + 趋势 + 下钻(只读)。"""
+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 analytics_health as repo
+from app.admin.schemas.analytics_health import (
+    HealthBreakdownRow,
+    HealthMetrics,
+    HealthTrendPoint,
+)
+
+router = APIRouter(
+    prefix="/admin/api/analytics-health",
+    tags=["admin-analytics-health"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+@router.get("/overview", response_model=HealthMetrics, summary="两段成功率总览")
+def overview(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+) -> HealthMetrics:
+    return HealthMetrics(**repo.overview(db, date_from, date_to))
+
+
+@router.get("/trend", response_model=list[HealthTrendPoint], summary="按北京天趋势")
+def trend(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+) -> list[HealthTrendPoint]:
+    return [HealthTrendPoint(**p) for p in repo.trend(db, date_from, date_to)]
+
+
+@router.get("/breakdown", response_model=list[HealthBreakdownRow], summary="按维度下钻")
+def breakdown(
+    db: AdminDb,
+    date_from: Annotated[datetime, Query()],
+    date_to: Annotated[datetime, Query()],
+    dim: Annotated[str, Query(pattern="^(event|app_ver|oem)$")] = "event",
+) -> list[HealthBreakdownRow]:
+    return [HealthBreakdownRow(**r) for r in repo.breakdown(db, date_from, date_to, dim)]

app/admin/routers/auth.py

@@ -6,6 +6,8 @@ import logging
 from fastapi import APIRouter, Depends, HTTPException
 
 from app.admin.deps import AdminDb, CurrentAdmin
+from app.admin.permissions import CUSTOM_ROLE, sanitize_pages
+from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.auth import AdminLoginRequest, AdminLoginResponse, AdminOut
 from app.admin.security import create_admin_token
@@ -17,6 +19,17 @@ logger = logging.getLogger("shagua.admin.auth")
 router = APIRouter(prefix="/admin/api/auth", tags=["admin-auth"])
 
 
+def _admin_out_with_pages(admin, db: AdminDb) -> AdminOut:  # noqa: ANN001
+    """AdminOut + 有效可见页(前端左侧导航按此过滤)。
+    role=="custom" → 用这个人的 pages_override(按人自定义,过滤悬空 key);其余走角色解析。"""
+    out = AdminOut.model_validate(admin)
+    if admin.role == CUSTOM_ROLE:
+        out.pages = sanitize_pages(admin.pages_override)
+    else:
+        out.pages = role_repo.effective_pages_of(db, admin.role)
+    return out
+
+
 @router.post(
     "/login",
     response_model=AdminLoginResponse,
@@ -39,10 +52,10 @@ def login(req: AdminLoginRequest, db: AdminDb) -> AdminLoginResponse:
     return AdminLoginResponse(
         access_token=token,
         expires_in=expires_in,
-        admin=AdminOut.model_validate(admin),
+        admin=_admin_out_with_pages(admin, db),
     )
 
 
-@router.get("/me", response_model=AdminOut, summary="当前管理员")
-def me(admin: CurrentAdmin) -> AdminOut:
-    return AdminOut.model_validate(admin)
+@router.get("/me", response_model=AdminOut, summary="当前管理员(含有效可见页)")
+def me(admin: CurrentAdmin, db: AdminDb) -> AdminOut:
+    return _admin_out_with_pages(admin, db)

app/admin/routers/comparison.py

@@ -32,12 +32,15 @@ def list_comparison_records(
     phone: Annotated[str | None, Query(description="手机号前缀")] = None,
     status: Annotated[str | None, Query(pattern="^(success|failed|cancelled)$")] = None,
     business_type: Annotated[str | None, Query()] = None,
+    store: Annotated[str | None, Query(description="店名子串模糊匹配")] = None,
+    product: Annotated[str | None, Query(description="商品名子串模糊匹配")] = None,
     limit: Annotated[int, Query(ge=1, le=100)] = 20,
     cursor: Annotated[int | None, Query()] = None,
 ) -> CursorPage[AdminComparisonListItem]:
     items, next_cursor, total = queries.list_comparison_records(
         db, user_id=user_id, phone=phone, status=status,
-        business_type=business_type, limit=limit, cursor=cursor,
+        business_type=business_type, store=store, product=product,
+        limit=limit, cursor=cursor,
     )
     return CursorPage(
         items=[AdminComparisonListItem.model_validate(r) for r in items],

app/admin/routers/config.py

@@ -55,9 +55,14 @@ def _item(db, key: str) -> ConfigItemOut:
     raise HTTPException(status_code=404, detail="未知配置项")
 
 
-@router.get("", response_model=list[ConfigItemOut], summary="所有可配项 + 当前值")
+@router.get("", response_model=list[ConfigItemOut], summary="所有可配项 + 当前值(不含 hidden)")
 def list_config(db: AdminDb) -> list[ConfigItemOut]:
-    return [ConfigItemOut(**item) for item in app_config.list_all(db)]
+    # hidden 项(已下线/由专用页管理,如福利页任务·里程碑·看广告调参、首页轮播数据源)不在本页渲染。
+    return [
+        ConfigItemOut(**item)
+        for item in app_config.list_all(db)
+        if not CONFIG_DEFS[item["key"]].get("hidden")
+    ]
 
 
 @router.patch("/{key}", response_model=ConfigItemOut, summary="改某项配置(带审计)")

app/admin/routers/coupon_data.py

@@ -18,6 +18,8 @@ from app.admin.schemas.coupon_data import (
     CouponDataOut,
     CouponDataRow,
     CouponDataSummary,
+    CouponSlotRow,
+    CouponSlotsOut,
     CouponUserRecordsOut,
 )
 from app.core.rewards import cn_today
@@ -52,6 +54,10 @@ def get_coupon_data(
     date_to: Annotated[str | None, Query(description="结束日 北京 YYYY-MM-DD,闭区间,默认=date_from")] = None,
     user: Annotated[str | None, Query(description="用户手机号/昵称模糊搜;不传=全部")] = None,
     app_env: Annotated[str, Query(description="prod(默认) / dev / all(全部环境)")] = "prod",
+    status: Annotated[
+        list[str] | None,
+        Query(description="领券状态多选 started/completed/failed/abandoned;不传=全部"),
+    ] = None,
     granularity: Annotated[
         str, Query(description="day=按天 / hour=按小时(北京);区间>1 天建议 day")
     ] = "day",
@@ -73,7 +79,7 @@ def get_coupon_data(
     env = None if app_env == "all" else app_env
     result = coupon_data.coupon_data_report(
         db, date_from=d_from.isoformat(), date_to=d_to.isoformat(),
-        user=user, app_env=env, granularity=granularity,
+        user=user, app_env=env, statuses=status, granularity=granularity,
         limit=limit, offset=offset, sort=sort,
     )
     return CouponDataOut(
@@ -87,6 +93,35 @@ def get_coupon_data(
     )
 
 
+@router.get(
+    "/coupons",
+    response_model=CouponSlotsOut,
+    summary="按券成功率(coupon_id 粒度;成功/(成功+失败),skipped 排除,设备-天口径)",
+)
+def get_coupon_slots(
+    db: AdminDb,
+    date_from: Annotated[str | None, Query(description="起始日 北京 YYYY-MM-DD,默认今天")] = None,
+    date_to: Annotated[str | None, Query(description="结束日 北京 YYYY-MM-DD,闭区间,默认=date_from")] = None,
+    app_env: Annotated[str, Query(description="prod(默认) / dev / all(全部环境)")] = "prod",
+) -> CouponSlotsOut:
+    today = cn_today()
+    d_from = _parse_day(date_from, field="date_from", default=today)
+    d_to = _parse_day(date_to, field="date_to", default=d_from)
+    if d_to < d_from:
+        raise HTTPException(status_code=422, detail="date_to 不能早于 date_from")
+    if (d_to - d_from).days + 1 > _MAX_RANGE_DAYS:
+        raise HTTPException(status_code=422, detail=f"区间最长 {_MAX_RANGE_DAYS} 天")
+    env = None if app_env == "all" else app_env
+    result = coupon_data.coupon_slot_report(
+        db, date_from=d_from.isoformat(), date_to=d_to.isoformat(), app_env=env
+    )
+    return CouponSlotsOut(
+        date_from=d_from.isoformat(),
+        date_to=d_to.isoformat(),
+        items=[CouponSlotRow(**r) for r in result["items"]],
+    )
+
+
 @router.get(
     "/user-records",
     response_model=CouponUserRecordsOut,

app/admin/routers/huawei_review.py

@@ -0,0 +1,58 @@
+"""admin 华为审核开关:控制新手引导页(快速设置)在华为 ROM 客户端能否被用户关闭。
+
+存在 app_config 表的 huawei_review dict(见 repositories/app_config.get_huawei_review/set_huawei_review)。
+客户端经 /api/v1/platform/huawei-review 拉取(且只有华为 ROM 机型会去拉)。权限 operator/tech + 审计。
+"""
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy.orm import Session
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
+from app.admin.schemas.huawei_review import HuaweiReviewOut, HuaweiReviewUpdate
+from app.models.admin import AdminUser
+from app.models.app_config import AppConfig
+from app.repositories import app_config
+
+router = APIRouter(
+    prefix="/admin/api/huawei-review",
+    tags=["admin-huawei-review"],
+    dependencies=[Depends(get_current_admin)],
+)
+
+
+def _out(db: Session) -> HuaweiReviewOut:
+    row = db.get(AppConfig, app_config.HUAWEI_REVIEW_KEY)
+    return HuaweiReviewOut(
+        mode=app_config.get_huawei_review(db)["mode"],
+        updated_at=row.updated_at.isoformat() if row is not None else None,
+    )
+
+
+@router.get("", response_model=HuaweiReviewOut, summary="华为审核开关当前状态")
+def get_huawei_review(db: AdminDb) -> HuaweiReviewOut:
+    return _out(db)
+
+
+@router.patch("", response_model=HuaweiReviewOut, summary="切换华为审核开关(带审计)")
+def update_huawei_review(
+    body: HuaweiReviewUpdate,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator", "tech"))],
+    db: AdminDb,
+) -> HuaweiReviewOut:
+    before = app_config.get_huawei_review(db)["mode"]
+    try:
+        app_config.set_huawei_review(db, body.mode, admin_id=admin.id, commit=False)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+    write_audit(
+        db, admin, action="huawei_review.set", target_type="huawei_review",
+        target_id=app_config.HUAWEI_REVIEW_KEY,
+        detail={"before": before, "after": body.mode}, ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return _out(db)

app/admin/routers/ops_marquee_seed.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel
 
 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
@@ -18,11 +19,17 @@ from app.admin.schemas.ops_marquee_seed import (
     OpsMarqueeSeedCreate,
     OpsMarqueeSeedOut,
     OpsMarqueeSeedUpdate,
+    OpsRealRecordItem,
+    OpsRealRecordsOut,
     OpsSavingsFeedPreviewOut,
 )
 from app.models.admin import AdminUser
 from app.models.ops_marquee_seed import OpsMarqueeSeed
-from app.repositories import ops_marquee
+from app.repositories import app_config, ops_marquee
+
+
+class MarqueeModeUpdate(BaseModel):
+    mode: str  # mixed / real / seed
 
 router = APIRouter(
     prefix="/admin/api/marquee-seeds",
@@ -52,9 +59,58 @@ def list_seeds(db: AdminDb) -> list[OpsMarqueeSeedOut]:
 def preview_feed(
     db: AdminDb,
     limit: Annotated[int, Query(ge=1, le=30)] = 8,
+    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
 ) -> OpsSavingsFeedPreviewOut:
-    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。"""
-    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit))
+    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。
+
+    mode 显式指定则预览该模式(**不改持久化配置**,供前端切换开关时实时预览);不传则用当前持久化模式。
+    """
+    if mode is not None and mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit, mode=mode))
+
+
+@router.get("/real-records", response_model=OpsRealRecordsOut, summary="分页浏览当前模式下可展示的记录(审核用)")
+def list_real_records(
+    db: AdminDb,
+    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=50)] = 8,
+) -> OpsRealRecordsOut:
+    """分页列出**当前模式**下可在 app 轮播展示的全部记录(**不去重**):只真实=真实记录;只种子=各启用
+    种子按生成逻辑各出一行;混播=真实+种子。与 app 同口径洗牌+去连簇,固定种子→翻页稳定、能翻遍全部。
+    item.user_id=0 表示种子行。"""
+    if mode is not None and mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    items, total = ops_marquee.list_real_records(db, mode=mode, offset=offset, limit=limit)
+    return OpsRealRecordsOut(items=[OpsRealRecordItem(**it) for it in items], total=total)
+
+
+# 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。
+@router.get("/mode", summary="首页轮播数据源模式(mixed/real/seed)")
+def get_feed_mode(db: AdminDb) -> dict:
+    """当前轮播取数模式:mixed=真实优先+种子补位(默认)/ real=只真实 / seed=只种子·合成。"""
+    return {"mode": ops_marquee.get_feed_mode(db)}
+
+
+@router.patch("/mode", summary="改首页轮播数据源模式(带审计)")
+def set_feed_mode(
+    body: MarqueeModeUpdate,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> dict:
+    if body.mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    before = ops_marquee.get_feed_mode(db)
+    app_config.set_value(db, "marquee_feed_mode", body.mode, admin_id=admin.id, commit=False)
+    write_audit(
+        db, admin, action="ops_marquee_seed.set_mode", target_type="config",
+        target_id="marquee_feed_mode", detail={"before": before, "after": body.mode},
+        ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return {"mode": body.mode}
 
 
 @router.post("", response_model=OpsMarqueeSeedOut, summary="新增轮播种子(带审计)")

app/admin/routers/roles.py

@@ -0,0 +1,129 @@
+"""admin RBAC 角色管理(仅 super_admin):列角色 / 权限目录 / 增删改角色。均写审计。
+
+角色 = 一组「可见页面」(见 app/admin/permissions.py)。角色登录后台后左侧只展示其 pages 对应导航项。
+只有 super_admin(内建全权角色)能进本组端点(dependencies=require_role() 无参 = 仅 super_admin)。
+"""
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from sqlalchemy import func, select
+
+from app.admin.audit import write_audit
+from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
+from app.admin.permissions import (
+    PERMISSION_CATALOG,
+    SUPER_ADMIN_ROLE,
+    effective_pages,
+    sanitize_pages,
+)
+from app.admin.repositories import admin_role as role_repo
+from app.admin.schemas.role import (
+    PermissionGroup,
+    RoleCreateRequest,
+    RoleOut,
+    RoleUpdateRequest,
+)
+from app.models.admin import AdminUser
+from app.models.admin_role import AdminRole
+
+router = APIRouter(
+    prefix="/admin/api/roles",
+    tags=["admin-roles"],
+    dependencies=[Depends(require_role())],  # 无参 = 仅 super_admin
+)
+
+
+def _usage_counts(db: AdminDb) -> dict[str, int]:
+    rows = db.execute(
+        select(AdminUser.role, func.count(AdminUser.id)).group_by(AdminUser.role)
+    ).all()
+    return {r: c for r, c in rows}
+
+
+def _to_out(role: AdminRole, usage: dict[str, int]) -> RoleOut:
+    return RoleOut(
+        id=role.id,
+        name=role.name,
+        label=role.label or role.name,
+        pages=effective_pages(role.name, role.pages),
+        is_builtin=role.is_builtin,
+        in_use=usage.get(role.name, 0),
+    )
+
+
+@router.get("", response_model=list[RoleOut], summary="角色列表(含可见页 + 使用数)")
+def list_roles(db: AdminDb) -> list[RoleOut]:
+    usage = _usage_counts(db)
+    return [_to_out(r, usage) for r in role_repo.list_roles(db)]
+
+
+@router.get("/catalog", response_model=list[PermissionGroup], summary="页面权限目录(分组)")
+def get_catalog() -> list[PermissionGroup]:
+    return [PermissionGroup(**g) for g in PERMISSION_CATALOG]
+
+
+@router.post("", response_model=RoleOut, summary="新增角色(带审计)")
+def create_role(
+    body: RoleCreateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
+) -> RoleOut:
+    name = body.name.strip()
+    if not name:
+        raise HTTPException(status_code=400, detail="角色名称不能为空")
+    if name == SUPER_ADMIN_ROLE:
+        raise HTTPException(status_code=400, detail="super_admin 为内建角色,不能新建")
+    if role_repo.get_role(db, name) is not None:
+        raise HTTPException(status_code=409, detail="角色名称已存在")
+    # 自定义角色:name(key)= label = 输入名称
+    role = role_repo.create_role(db, name=name, label=name, pages=body.pages)
+    write_audit(
+        db, admin, action="role.create", target_type="role", target_id=str(role.id),
+        detail={"name": name, "pages": role.pages}, ip=get_client_ip(request), commit=True,
+    )
+    return _to_out(role, _usage_counts(db))
+
+
+@router.patch("/{role_id}", response_model=RoleOut, summary="改角色(展示名/可见页,带审计)")
+def update_role(
+    role_id: int, body: RoleUpdateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
+) -> RoleOut:
+    role = db.get(AdminRole, role_id)
+    if role is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if role.is_builtin:
+        raise HTTPException(status_code=400, detail="内建角色「管理员」不可编辑")
+
+    new_label = body.label.strip() if body.label is not None else None
+    changes: dict = {}
+    if new_label and new_label != role.label:
+        changes["label"] = {"before": role.label, "after": new_label}
+    if body.pages is not None:
+        changes["pages"] = {"before": role.pages, "after": sanitize_pages(body.pages)}
+    if not changes:
+        raise HTTPException(status_code=400, detail="无任何变更字段")
+
+    # 只改展示名 + 可见页;key(name)不可变,故无需级联 admin_user.role
+    role_repo.update_role(db, role, label=new_label, pages=body.pages)
+    write_audit(
+        db, admin, action="role.update", target_type="role", target_id=str(role_id),
+        detail=changes, ip=get_client_ip(request), commit=True,
+    )
+    return _to_out(role, _usage_counts(db))
+
+
+@router.delete("/{role_id}", summary="删角色(带审计;内建/在用不可删)")
+def delete_role(role_id: int, request: Request, admin: CurrentAdmin, db: AdminDb) -> dict:
+    role = db.get(AdminRole, role_id)
+    if role is None:
+        raise HTTPException(status_code=404, detail="角色不存在")
+    if role.is_builtin:
+        raise HTTPException(status_code=400, detail="内建角色不可删除")
+    used = _usage_counts(db).get(role.name, 0)
+    if used > 0:
+        raise HTTPException(status_code=400, detail=f"该角色仍有 {used} 名管理员在用,请先改派再删")
+    name = role.name
+    role_repo.delete_role(db, role)
+    write_audit(
+        db, admin, action="role.delete", target_type="role", target_id=str(role_id),
+        detail={"name": name}, ip=get_client_ip(request), commit=True,
+    )
+    return {"deleted": True}

app/admin/routers/users.py

@@ -13,7 +13,6 @@ from app.admin.schemas.common import CursorPage, OkResponse
 from app.admin.schemas.user import (
     AdminUserListItem,
     AdminUserOverview,
-    DeleteUserRequest,
     GrantCashRequest,
     GrantCoinsRequest,
     SetDebugTraceRequest,
@@ -43,7 +42,12 @@ def list_users(
     created_to: Annotated[datetime | None, Query()] = None,
     last_login_from: Annotated[datetime | None, Query()] = None,
     last_login_to: Annotated[datetime | None, Query()] = None,
-    sort_by: Annotated[str, Query(pattern="^(id|created_at|last_login_at)$")] = "id",
+    # 最近活跃(登录/发起比价/发起领券取最大,见 queries._last_active_expr)筛选与排序
+    last_active_from: Annotated[datetime | None, Query()] = None,
+    last_active_to: Annotated[datetime | None, Query()] = None,
+    sort_by: Annotated[
+        str, Query(pattern="^(id|created_at|last_login_at|last_active_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,
@@ -52,6 +56,7 @@ def list_users(
         db, phone=phone, register_channel=register_channel, status=status,
         nickname=nickname, created_from=created_from, created_to=created_to,
         last_login_from=last_login_from, last_login_to=last_login_to,
+        last_active_from=last_active_from, last_active_to=last_active_to,
         sort_by=sort_by, sort_order=sort_order, limit=limit, cursor=cursor,
     )
     return CursorPage(
@@ -133,40 +138,6 @@ def set_user_status(
     return OkResponse()
 
 
-@router.delete("/{user_id}", response_model=OkResponse, summary="注销/删除账号(清理个人数据 + 匿名化,带审计)")
-def delete_user(
-    user_id: int,
-    body: DeleteUserRequest,
-    request: Request,
-    admin: Annotated[AdminUser, Depends(require_role("super_admin"))],
-    db: AdminDb,
-) -> OkResponse:
-    """后台删除账号:复用 C 端自助注销同一套清理逻辑(soft_delete_account)——物理删除个人内容/
-    行为/PII 表 + 清零余额 + 匿名化 user 行释放唯一约束,保留资金流水/邀请关系/广告幂等+对账表。
-    仅 super_admin 可操作(最高危、不可逆)。资金安全同 C 端:有未提现现金/邀请金 / 在审提现单 → 409 拒绝。
-    """
-    user = user_repo.get_user_by_id(db, user_id)
-    if user is None:
-        raise HTTPException(status_code=404, detail="用户不存在")
-    if user.status == "deleted":
-        raise HTTPException(status_code=400, detail="账号已注销,请勿重复操作")
-    # 资金前置校验(与 C 端 delete_account 端点一致):余额一旦清零拿不回,有活钱先拦下。
-    if wallet_repo.get_cash_balance_cents(db, user_id) > 0:
-        raise HTTPException(status_code=409, detail="该账户还有未提现的现金余额,请先处理后再删除")
-    if wallet_repo.get_invite_cash_balance_cents(db, user_id) > 0:
-        raise HTTPException(status_code=409, detail="该账户还有未提现的邀请奖励金,请先处理后再删除")
-    if wallet_repo.has_reviewing_withdraw(db, user_id):
-        raise HTTPException(status_code=409, detail="该账户有提现正在审核中,请等审核完成后再删除")
-    # 先写审计(commit=False,挂进 session),再由 soft_delete_account 做清理 + 最终 commit —— 一次 commit
-    # 同时落审计行与清理结果,保持"改了就有痕、有痕就改了"原子(soft_delete_account 内部 commit 会一并 flush)。
-    write_audit(
-        db, admin, action="user.delete", target_type="user", target_id=user_id,
-        detail={"reason": body.reason, "phone": user.phone}, ip=get_client_ip(request), commit=False,
-    )
-    user_repo.soft_delete_account(db, user)
-    return OkResponse()
-
-
 @router.post("/{user_id}/debug-trace", response_model=OkResponse, summary="开关调试链接权限")
 def set_user_debug_trace(
     user_id: int,

app/admin/schemas/ad_revenue.py

@@ -136,9 +136,16 @@ class AdRevenueReportOut(BaseModel):
         default_factory=dict,
         description="按广告类型(ad_type)小计 {ad_type: {impressions, revenue_yuan}};前端取 draw / reward_video 做分类大盘",
     )
+    scene_stats: dict[str, AdRevenueTypeStat] = Field(
+        default_factory=dict,
+        description="按信息流场景(feed_scene)小计 {comparison/coupon/welfare: {impressions, revenue_yuan}};"
+        "全量统计(不受分页截断),供数据大盘「领券广告 / 比价广告」卡;feed_scene 为空的事件不计入",
+    )
     dau: int | None = Field(
         None,
-        description="今日活跃用户数(复用大盘口径,last_login_at);**仅查询=今日单天时有值**,历史/多天为 null",
+        description="所选日期区间的去重活跃用户数(口径同数据大盘 period.users.active:登录 + 开始比价 + "
+        "开始领券)。按 date_from~date_to 区间统计,含今日、近 7 天、近 30 天等任意区间;全局口径,"
+        "不随 user_id / ad_type / feed_scene / app_env 筛选变化",
     )
     total: int = Field(..., description="广告事件总数(全量,不受分页影响;= 当前筛选下的分页总条数)")
     truncated: bool = Field(..., description="当前页之后是否还有更多事件(len(events) > offset + limit)")

app/admin/schemas/admin.py

@@ -6,21 +6,25 @@ from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-_Role = Literal["super_admin", "finance", "operator"]
+# 角色不再硬编码枚举:改为任意角色名(自定义角色由 admin_role 表管理),存在性在路由层校验。
 
 
 class AdminCreateRequest(BaseModel):
     username: str = Field(..., min_length=3, max_length=64)
     password: str = Field(..., min_length=8, max_length=72)  # bcrypt ≤72 字节
-    role: _Role = "operator"
+    role: str = Field("operator", min_length=1, max_length=32)
+    # 仅当 role == "custom":这个人专属可见页 key 列表(逐页勾选结果)。其余角色不传/忽略。
+    pages_override: list[str] | None = None
 
 
 class AdminUpdateRequest(BaseModel):
-    """改角色 / 启用禁用 / 重置密码,字段都可选(只改传了的)。"""
+    """改角色 / 启用禁用 / 重置密码 / 自定义可见页,字段都可选(只改传了的)。"""
 
-    role: _Role | None = None
+    role: str | None = Field(None, min_length=1, max_length=32)
     status: Literal["active", "disabled"] | None = None
     password: str | None = Field(None, min_length=8, max_length=72)
+    # 改成/更新「自定义」可见页;role 切回普通角色时后端会清空 override(见路由)。
+    pages_override: list[str] | None = None
 
 
 class AdminAuditLogOut(BaseModel):

app/admin/schemas/analytics_health.py

@@ -0,0 +1,21 @@
+"""埋点健康度 admin 响应 schema。"""
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class HealthMetrics(BaseModel):
+    attempted: int
+    drop_capture: int
+    delivered: int
+    drop_undelivered: int
+    track_success_rate: float | None
+    report_success_rate: float | None
+
+
+class HealthTrendPoint(HealthMetrics):
+    day: str
+
+
+class HealthBreakdownRow(HealthMetrics):
+    key: str

app/admin/schemas/auth.py

@@ -20,6 +20,15 @@ class AdminOut(BaseModel):
     status: str
     created_at: datetime
     last_login_at: datetime | None = None
+    # 该管理员当前角色的有效可见页(= 左侧导航项 key);仅登录 / /me 填充,列表接口默认空。
+    # 前端据此过滤左侧导航(super_admin = 全部页;role=="custom" = pages_override)。见 permissions.py。
+    pages: list[str] = []
+    # 「自定义」可见页原始勾选集(role=="custom" 时非空);列表接口下发,供权限管理页编辑回填勾选。
+    # 普通角色为 None。from_attributes 自动从 ORM 列取。
+    pages_override: list[str] | None = None
+    # 明文登录密码:仅「管理员账号列表」(super_admin 专属路由)填充,供权限管理页编辑时复看;
+    # 无留存(脚本建的超管 / 旧账号)为 None → 前端不显示。登录 / /me 不下发(保持 None)。
+    password: str | None = None
 
 
 class AdminLoginResponse(BaseModel):

app/admin/schemas/comparison.py

@@ -23,6 +23,7 @@ class AdminComparisonListItem(BaseModel):
     status: str
     information: str | None = None
     store_name: str | None = None
+    product_names: str | None = None   # 下单商品名派生串(顿号分隔;「商品」列展示 + 商品搜索)
     source_platform_name: str | None = None
     best_platform_name: str | None = None
     source_price_cents: int | None = None
@@ -35,11 +36,14 @@ class AdminComparisonListItem(BaseModel):
     retry_count: int | None = None
     input_tokens: int | None = None      # Σ usage.prompt_tokens(server 派生)
     output_tokens: int | None = None     # Σ usage.completion_tokens(server 派生)
+    # 本次比价 LLM 总成本(元,按当时价冻结);旧记录/未回填为 None → 前端「成本」列回退估算。见 services/llm_cost.py。
+    llm_cost_yuan: float | None = None
     device_model: str | None = None
     rom_vendor: str | None = None
     rom_name: str | None = None
     android_version: str | None = None
     app_version: str | None = None
+    ad_revenue_yuan: float = 0.0   # 本次比价看的信息流广告预估收益(元),queries 瞬态挂 ORM 实例上
     created_at: datetime
 
 
@@ -70,3 +74,5 @@ class AdminComparisonDetail(AdminComparisonListItem):
     # 原始上报全量;「卡在哪一步」从 raw_payload.platform_results[*].status 读
     # (store_not_found/items_not_found/below_minimum/unsupported = 卡在 找店/加菜/起送/读价)。
     raw_payload: dict | None = None
+    # 算成本所用单价快照 {mode, prices:{model:{...}}}(llm_cost_yuan 继承自列表项)。见 services/llm_cost.py。
+    llm_price_snapshot: dict | None = None

app/admin/schemas/coupon_data.py

@@ -19,6 +19,16 @@ class CouponDataSummary(BaseModel):
     p50_ms: int | None = Field(None, description="耗时 50 分位(ms,中位数)")
     p95_ms: int | None = Field(None, description="耗时 95 分位(ms)")
     p99_ms: int | None = Field(None, description="耗时 99 分位(ms)")
+    # 平台粒度成功率(见 docs/guides/领券成功率指标-设计与埋点.md):基数含全部 session。
+    full_success_count: int = Field(0, description="整单成功数(勾选平台全部领到的 session 数)")
+    full_success_rate: float | None = Field(None, description="整单成功率②=整单成功数/发起数;无数据为空")
+    point_success_count: int = Field(0, description="成功平台点位数(Σ 每次成功的平台数)")
+    point_total_count: int = Field(0, description="总平台点位数(Σ 每次勾选平台数;空勾选=全领三档)")
+    point_success_rate: float | None = Field(None, description="点位成功率③=成功点位/总点位;无数据为空")
+    per_platform: dict[str, float | None] = Field(
+        default_factory=dict,
+        description="分平台点位成功率 {平台id: rate|None};恒含美团/淘宝/京东三档,区间内无人勾选的平台为 None",
+    )
 
 
 class CouponDataDaily(BaseModel):
@@ -60,6 +70,9 @@ class CouponDataRow(BaseModel):
     started_at: datetime = Field(..., description="发起时刻(明细「时间」列)")
     claimed_count: int | None = None
     trace_url: str | None = Field(None, description="pricebot 公网 trace 链接(仅 completed 有);admin 渲染可点链接,无则显示可复制 trace_id")
+    ad_revenue_yuan: float = Field(
+        0.0, description="本次领券看的信息流广告预估收益(元);按 trace_id 聚合 ad_ecpm_record"
+    )
 
 
 class CouponDataOut(BaseModel):
@@ -81,3 +94,22 @@ class CouponUserRecordsOut(BaseModel):
 
     items: list[CouponDataRow]
     total: int
+
+
+class CouponSlotRow(BaseModel):
+    """按券成功率一行(§13):粒度=设备-天;成功率=成功/(成功+失败),skipped 排除。"""
+
+    coupon_id: str
+    coupon_name: str | None = None
+    platform: str | None = Field(None, description="美团/淘宝/京东 平台 id;无法识别为空")
+    tried: int = Field(..., description="尝试数(success+already_claimed+failed 的设备-天数)")
+    succeeded: int = Field(..., description="成功数(success+already_claimed)")
+    success_rate: float | None = Field(None, description="成功率=成功/尝试")
+
+
+class CouponSlotsOut(BaseModel):
+    """按券成功率表响应(§13)。"""
+
+    date_from: str
+    date_to: str
+    items: list[CouponSlotRow]

app/admin/schemas/dashboard.py

@@ -43,18 +43,44 @@ class DashboardComparison(BaseModel):
 class DashboardPeriodUsers(BaseModel):
     new: int
     active: int
+    # 次日留存(2026-07-05 起):retained_new_users = 窗口内逐日「前一日新增且当日活跃」用户数之和,
+    # retention_cohort = 对应的前一日新增基数之和,retention_rate = 两者之比。
     retained_new_users: int
+    retention_cohort: int = 0
     retention_rate: float | None = None
     retention_note: str
 
 
 class DashboardPeriodComparison(BaseModel):
     total: int
+    completed: int
+    cancelled: int
     success: int
-    success_rate: float
+    success_rate: float | None = None
     ordered: int
     average_duration_ms: int | None = None
+    median_duration_ms: int | None = None
+    p95_duration_ms: int | None = None
     average_saved_cents: int | None = None
+    token_cost_total_yuan: float = 0.0
+
+
+class DashboardPeriodCoupon(BaseModel):
+    """领券核心数据(2026-07-05 产品新增)。点位=一张券(coupon_claim_record 一天一条终态);
+    成功口径 success+already_claimed(与「我的」页累计领券一致)。"""
+
+    started: int = 0
+    # 全部领成功的次数:completed 且当日该设备全部点位成功
+    all_success: int = 0
+    success_rate: float | None = None
+    # 本期 session 触达的点位中成功的条数(同设备同日去重)
+    point_success: int = 0
+    # 每次发起的应领点位数(本期完成场实际点位数的众数;无完成场为空)
+    points_per_session: int | None = None
+    # 点位成功率 = point_success / (started × points_per_session);未跑到的点位计入分母视为失败
+    point_success_rate: float | None = None
+    # 耗时中位数(仅 completed 的 elapsed_ms,同「领券数据」页口径)
+    median_elapsed_ms: int | None = None
 
 
 class DashboardPeriodCoins(BaseModel):
@@ -85,6 +111,7 @@ class DashboardPeriod(BaseModel):
     date_to: date
     users: DashboardPeriodUsers
     comparison: DashboardPeriodComparison
+    coupon: DashboardPeriodCoupon = DashboardPeriodCoupon()
     coins: DashboardPeriodCoins
     cash: DashboardPeriodCash
     trend: list[DashboardTrendPoint] = []

app/admin/schemas/huawei_review.py

@@ -0,0 +1,19 @@
+"""admin 华为审核开关 schemas(两态:default / review)。"""
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class HuaweiReviewOut(BaseModel):
+    """当前开关状态。updated_at 给后台展示「谁什么时候切的」提供时间锚点。"""
+
+    mode: Literal["default", "review"]
+    updated_at: str | None = None  # ISO 字符串;从未切过为 None
+
+
+class HuaweiReviewUpdate(BaseModel):
+    """切换开关。整值覆盖,不做部分更新(就一个字段)。"""
+
+    mode: Literal["default", "review"]

app/admin/schemas/ops_marquee_seed.py

@@ -62,3 +62,16 @@ class OpsSavingsFeedPreviewItem(BaseModel):
 class OpsSavingsFeedPreviewOut(BaseModel):
     """运营预览:实际混播出来的 feed(真实记录会插队,与客户端一致)。"""
     items: list[OpsSavingsFeedPreviewItem]
+
+
+class OpsRealRecordItem(BaseModel):
+    masked_user: str          # 脱敏后展示名(与 app 一致)
+    saved_amount_cents: int   # 节省金额(分)
+    created_at: str           # 比价记录时间(YYYY-MM-DD HH:MM)
+    user_id: int              # 真实 user_id(供运营核对,不下发客户端)
+
+
+class OpsRealRecordsOut(BaseModel):
+    """分页浏览「全部可展示的真实记录」(success+省>0,不去重、稳定顺序)。"""
+    items: list[OpsRealRecordItem]
+    total: int                # 满足条件的真实记录总数(算页数用)

app/admin/schemas/role.py

@@ -0,0 +1,35 @@
+"""admin RBAC 角色 + 权限目录 schemas。"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class PermissionPage(BaseModel):
+    key: str
+    label: str
+
+
+class PermissionGroup(BaseModel):
+    group: str
+    pages: list[PermissionPage]
+
+
+class RoleOut(BaseModel):
+    id: int
+    name: str             # 角色 key(承重,不可变)
+    label: str            # 展示名(UI 显示)
+    pages: list[str]      # 有效可见页 key(super_admin = 全部页)
+    is_builtin: bool      # 内建角色(super_admin):不可编辑/删除
+    in_use: int           # 使用该角色的管理员数(删除前端提示 / 拦截用)
+
+
+class RoleCreateRequest(BaseModel):
+    # 新增自定义角色:name 即用户输入的名称(同时作 key 与展示名)
+    name: str = Field(..., min_length=1, max_length=32)
+    pages: list[str] = Field(default_factory=list)
+
+
+class RoleUpdateRequest(BaseModel):
+    # 只改展示名 + 可见页;key 不可变
+    label: str | None = Field(None, min_length=1, max_length=32)
+    pages: list[str] | None = None

app/admin/schemas/user.py

@@ -20,6 +20,9 @@ class AdminUserListItem(BaseModel):
     wechat_nickname: str | None = None
     created_at: datetime
     last_login_at: datetime
+    # 最近活跃 = max(最近登录, 最近发起比价, 最近发起领券);列表页由 queries._attach_last_active
+    # 瞬态挂上。其他复用本 schema 的入口(用户 360 等)没挂该属性 → None(前端显示 '-')。
+    last_active_at: datetime | None = None
 
 
 class AdminUserOverview(BaseModel):
@@ -115,9 +118,3 @@ class SetUserStatusRequest(BaseModel):
 
 class SetDebugTraceRequest(BaseModel):
     enabled: bool = Field(..., description="是否给该用户开「复制调试链接」权限")
-
-
-class DeleteUserRequest(BaseModel):
-    reason: str = Field(..., min_length=1, max_length=128, description="删除原因(必填,入审计)")
-
-    _v_reason = field_validator("reason")(_strip_reason)

app/admin/schemas/wallet.py

@@ -130,6 +130,7 @@ class WithdrawBulkResult(BaseModel):
 
 class WithdrawLedgerCheckOut(BaseModel):
     ok: bool
+    # 普通现金账(coin_cash:金币兑换的现金)
     cash_balance_total_cents: int
     cash_transaction_total_cents: int
     balance_diff_cents: int
@@ -137,6 +138,14 @@ class WithdrawLedgerCheckOut(BaseModel):
     missing_refund_txn_count: int
     duplicate_refund_txn_count: int
     refund_txn_on_non_terminal_count: int
+    # 邀请奖励金账(invite_cash:与普通现金物理隔离,各自对账)。默认 0 向后兼容。
+    invite_cash_balance_total_cents: int = 0
+    invite_cash_transaction_total_cents: int = 0
+    invite_balance_diff_cents: int = 0
+    invite_missing_withdraw_txn_count: int = 0
+    invite_missing_refund_txn_count: int = 0
+    invite_duplicate_refund_txn_count: int = 0
+    invite_refund_txn_on_non_terminal_count: int = 0
 
 
 class WxpayHealthCheckOut(BaseModel):

app/api/v1/ad.py

@@ -3,6 +3,8 @@
 路由前缀 `/api/v1/ad`:
   GET  /pangle-callback   穿山甲 S2S 发奖回调(**无 JWT,靠验签**),穿山甲服务器调
   GET  /reward-status     客户端查今日看广告发奖进度(Bearer)
+  GET  /reward-result/{ad_session_id}
+                          客户端按会话查本次广告实发金币(Bearer,只读,弹窗金额用)
 
 发奖走服务端:激励视频播完穿山甲回调本接口,验签通过后幂等发金币。客户端只负责
 看完后刷新余额,不参与发奖,被破解也刷不到钱。
@@ -13,7 +15,7 @@ import json
 import logging
 import uuid
 
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Path, Request, status
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import rewards
@@ -25,8 +27,8 @@ from app.repositories import ad_feed_reward as crud_feed
 from app.repositories import ad_reward as crud_ad
 from app.repositories import ad_watch as crud_watch
 from app.repositories import app_config
-from app.repositories import signin as crud_signin
 from app.schemas.ad import (
+    AdRewardResultOut,
     AdRewardStatusOut,
     EcpmReportIn,
     EcpmReportOut,
@@ -52,11 +54,14 @@ REASON_BAD_PARAMS = 1  # 验签过但缺 trans_id / user_id 非数字
 REASON_UNKNOWN_USER = 2  # user_id 不存在(可能伪造)
 
 REWARD_SCENE_REWARD_VIDEO = "reward_video"
-REWARD_SCENE_SIGNIN_BOOST = "signin_boost"
 # 提现看视频:看完才能提现的「硬门槛」广告,**不发金币**,只记一条幂等记录(收益由 eCPM 上报口径
 # ad_type="withdrawal_video" 单独统计)。故意不放进 SUPPORTED_REWARD_SCENES——它不走发币分支。
 REWARD_SCENE_WITHDRAWAL_AD = "withdrawal_ad"
-SUPPORTED_REWARD_SCENES = {REWARD_SCENE_REWARD_VIDEO, REWARD_SCENE_SIGNIN_BOOST}
+# 2026-07 下线 signin_boost(签到膨胀):它按固定 3000 金币发,与广告实际收益脱钩,产品确认
+# 从来不是设计内的口径。签到弹窗里的「看广告膨胀」现在与福利页看视频走同一条 reward_video
+# 路径(按 eCPM 公式发),奖励只剩「签到」+「看视频」两种。历史发币流水(coin_transaction
+# .biz_type='signin_boost')保留不动——钱是真发过的,账必须留。
+SUPPORTED_REWARD_SCENES = {REWARD_SCENE_REWARD_VIDEO}
 
 
 def _parse_extra(raw_extra: str | None) -> dict[str, str]:
@@ -118,6 +123,11 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
         extra.update(_parse_extra(params.get(extra_key)))
     reward_scene = extra.get("reward_scene") or REWARD_SCENE_REWARD_VIDEO
     ad_session_id = extra.get("ad_session_id")
+    # 「这条广告属于哪一轮膨胀」。纯标签:不参与发奖判定,只让 reward-result 能把同一轮求和成
+    # 弹窗要显示的累计值(见 crud_ad.round_coin_total)。老客户端不带 → NULL → 累计值返 null。
+    boost_round_id = (extra.get("boost_round_id") or None)
+    if boost_round_id is not None:
+        boost_round_id = boost_round_id[:64]
     ecpm = params.get("ecpm")
 
     # 环境隔离:激励视频 mediaExtra 里带「这次观看属于哪个后端环境」(srv_env=dev/prod,客户端按
@@ -169,50 +179,11 @@ def pangle_callback(request: Request, db: DbSession) -> PangleCallbackOut:
                 user_id, trans_id, reward_scene,
             )
             return PangleCallbackOut(is_verify=False, reason=REASON_BAD_PARAMS)
-        if reward_scene == REWARD_SCENE_SIGNIN_BOOST:
-            try:
-                boost, _balance = crud_signin.boost_today_signin(
-                    db, user_id, ad_ref_id=trans_id, commit=False
-                )
-            except crud_signin.NotSignedTodayError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="not_signed",
-                )
-            except crud_signin.AlreadyBoostedError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="already_boosted",
-                )
-            except crud_signin.LastCycleDayBoostBlockedError:
-                db.rollback()
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=0, reward_scene=reward_scene,
-                    ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    status="last_day",
-                )
-            else:
-                rec = crud_ad.record_external_reward(
-                    db, user_id, trans_id, coin=boost.coin_awarded,
-                    reward_scene=reward_scene, ad_session_id=ad_session_id, ecpm=ecpm,
-                    reward_name=params.get("reward_name"), raw=raw[:1024],
-                    commit=False,
-                )
-                db.commit()
-                db.refresh(rec)
-        else:
-            rec = crud_ad.grant_ad_reward(
-                db, user_id, trans_id, ecpm=ecpm, ad_session_id=ad_session_id,
-                reward_scene=REWARD_SCENE_REWARD_VIDEO,
-                reward_name=params.get("reward_name"), raw=raw[:1024],
-            )
+        rec = crud_ad.grant_ad_reward(
+            db, user_id, trans_id, ecpm=ecpm, ad_session_id=ad_session_id,
+            reward_scene=REWARD_SCENE_REWARD_VIDEO, boost_round_id=boost_round_id,
+            reward_name=params.get("reward_name"), raw=raw[:1024],
+        )
     except crud_ad.UnknownUserError:
         logger.warning("pangle callback unknown user_id=%d trans_id=%s", user_id, trans_id)
         return PangleCallbackOut(is_verify=False, reason=REASON_UNKNOWN_USER)
@@ -242,6 +213,46 @@ def reward_status(user: CurrentUser, db: DbSession) -> AdRewardStatusOut:
     )
 
 
+@router.get(
+    "/reward-result/{ad_session_id}",
+    response_model=AdRewardResultOut,
+    summary="按 ad_session_id 查本次广告的权威发奖结果",
+    dependencies=[Depends(rate_limit(120, 60, "ad-reward-result"))],
+)
+def reward_result(
+    user: CurrentUser,
+    db: DbSession,
+    ad_session_id: str = Path(..., min_length=8, max_length=64, description="本次广告会话 id"),
+) -> AdRewardResultOut:
+    """客户端看完激励视频后轮询本接口拿**本次实发金币 + 本轮累计**用于弹窗,不再用余额差 /
+    coin_per_ad 估算(修「弹窗数值与真实金币对不上」)。
+
+    round_coin 是「恭喜累计获得奖励」弹窗真正显示的数:本轮(= 客户端的 boost_round_id)所有
+    granted 记录之和。由服务端求和而不是客户端自己累加——客户端进程被杀/重建后本地累计会丢,
+    发奖记录不会。取不到轮 id(pending / 老客户端 / extra 丢失)时为 null,客户端退回显示单条。
+
+    S2S 回调异步:查不到记录 = 回调还没到 → 返 200 + status='pending' 让客户端继续重试,
+    **不返 404**(404 只表示路由不存在)。纯只读:发奖仍只由验签过的 S2S 回调完成,
+    这里不写库、不产生任何奖励,被刷也只是查自己的记录。
+    """
+    rec = crud_ad.find_by_session(db, user.id, ad_session_id)
+    if rec is None:
+        # 连记录都没有 → 不知道属于哪一轮,round_coin 一并为 null(不是 0,0 会被当成"本轮没赚到")
+        return AdRewardResultOut(
+            ad_session_id=ad_session_id, status="pending", coin=None, round_coin=None,
+        )
+    # 本条不是 granted 时**仍返本轮累计**(这条按 0 计):第 3 条撞每日上限那下,客户端的限额
+    # toast 要显示的是前两条已到账的总额,不是空。
+    round_coin = (
+        crud_ad.round_coin_total(db, user.id, rec.boost_round_id)
+        if rec.boost_round_id
+        else None
+    )
+    return AdRewardResultOut(
+        ad_session_id=ad_session_id, status=rec.status, coin=rec.coin, round_coin=round_coin,
+    )
+
+
 @router.post(
     "/watch-report",
     response_model=WatchReportOut,
@@ -280,18 +291,31 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
     Bearer 鉴权,user_id 取自 JWT(不信 body)。best-effort:落库即 ok,客户端 fire-and-forget,
     丢一两条不影响业务(穿山甲后台报表是结算权威)。eCPM 与发奖(S2S)是两条独立流,不逐条关联。
     """
+    attributed_trace_id = crud_ecpm.attributable_trace_id(
+        db,
+        feed_scene=payload.feed_scene,
+        trace_id=payload.trace_id,
+        exposure_ms=payload.exposure_ms,
+    )
+    if payload.trace_id and attributed_trace_id is None:
+        logger.info(
+            "detach late coupon ad impression from failed trace user_id=%d trace=%s session=%s",
+            user.id, payload.trace_id, payload.ad_session_id,
+        )
     crud_ecpm.create_ecpm_record(
         db, user.id,
         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,
+        trace_id=attributed_trace_id,
         app_env=payload.app_env, our_code_id=payload.our_code_id,
+        exposure_ms=payload.exposure_ms,
     )
     logger.info(
-        "ad ecpm report user_id=%d type=%s scene=%s session=%s ecpm=%s adn=%s slot=%s app=%s code=%s",
+        "ad ecpm report user_id=%d type=%s scene=%s session=%s ecpm=%s exposure_ms=%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,
+        payload.exposure_ms, payload.adn, payload.slot_id, payload.app_env, payload.our_code_id,
     )
     return EcpmReportOut(ok=True)
 
@@ -316,55 +340,27 @@ def test_grant(user: CurrentUser, db: DbSession, payload: TestGrantIn | None = N
     if reward_scene not in SUPPORTED_REWARD_SCENES:
         raise HTTPException(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, detail="bad reward_scene")
 
-    # 每次新 trans_id,模拟一次独立的穿山甲发奖回调(幂等键各不相同 → 每次都发,直到当日上限/今日膨胀一次)
+    # 每次新 trans_id,模拟一次独立的穿山甲发奖回调(幂等键各不相同 → 每次都发,直到当日上限)
     trans_id = f"test-{user.id}-{uuid.uuid4().hex}"
-    if reward_scene == REWARD_SCENE_SIGNIN_BOOST:
-        try:
-            boost, _balance = crud_signin.boost_today_signin(
-                db, user.id, ad_ref_id=trans_id, commit=False
-            )
-        except crud_signin.NotSignedTodayError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="not_signed",
-            )
-        except crud_signin.AlreadyBoostedError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="already_boosted",
-            )
-        except crud_signin.LastCycleDayBoostBlockedError:
-            db.rollback()
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=0, reward_scene=reward_scene,
-                raw="client debug test-grant signin_boost", status="last_day",
-            )
-        else:
-            rec = crud_ad.record_external_reward(
-                db, user.id, trans_id, coin=boost.coin_awarded,
-                reward_scene=reward_scene, reward_name="测试签到膨胀",
-                raw="client debug test-grant signin_boost", commit=False,
-            )
-            db.commit()
-            db.refresh(rec)
-    else:
-        # 优先用客户端按 ad_session_id 上报的真实 eCPM(走与正式发奖相同的公式);
-        # 取不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍能验出非零金币。
-        ad_session_id = payload.ad_session_id if payload is not None else None
-        ecpm_val = "200"
-        if ad_session_id:
-            ecpm_rec = crud_ecpm.find_by_session(db, user_id=user.id, ad_session_id=ad_session_id)
-            if ecpm_rec is not None and rewards.parse_ecpm_fen(ecpm_rec.ecpm_raw) > 0:
-                ecpm_val = ecpm_rec.ecpm_raw
-        try:
-            rec = crud_ad.grant_ad_reward(
-                db, user.id, trans_id, ecpm=ecpm_val, ad_session_id=ad_session_id,
-                reward_name="测试发奖", raw=f"client debug test-grant ecpm={ecpm_val}",
-            )
-        except crud_ad.UnknownUserError as e:
-            raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user not found") from e
+    # 正式链路的轮次 id 走 S2S 的 mediaExtra;本接口不经 S2S,只能由 body 补,否则 debug 包
+    # 的 reward-result 恒返 round_coin=null,「弹窗 40 → 60」那套累计验收在本地跑不起来。
+    boost_round_id = (payload.boost_round_id if payload is not None else None) or None
+    # 优先用客户端按 ad_session_id 上报的真实 eCPM(走与正式发奖相同的公式);
+    # 取不到或 eCPM≤0(测试应用常返 0/假值)时兜底 200,保证本地联调仍能验出非零金币。
+    ad_session_id = payload.ad_session_id if payload is not None else None
+    ecpm_val = "200"
+    if ad_session_id:
+        ecpm_rec = crud_ecpm.find_by_session(db, user_id=user.id, ad_session_id=ad_session_id)
+        if ecpm_rec is not None and rewards.parse_ecpm_fen(ecpm_rec.ecpm_raw) > 0:
+            ecpm_val = ecpm_rec.ecpm_raw
+    try:
+        rec = crud_ad.grant_ad_reward(
+            db, user.id, trans_id, ecpm=ecpm_val, ad_session_id=ad_session_id,
+            boost_round_id=boost_round_id,
+            reward_name="测试发奖", raw=f"client debug test-grant ecpm={ecpm_val}",
+        )
+    except crud_ad.UnknownUserError as e:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="user not found") from e
 
     (used, limit, coin_per, round_count, cooldown_until,
      _watched, _watch_limit) = crud_ad.today_status(db, user.id)

app/api/v1/analytics.py

@@ -6,13 +6,18 @@ POST /api/v1/analytics/events — 批量接收新手引导(及后续)埋点,appe
 """
 from __future__ import annotations
 
-from fastapi import APIRouter, Request
+import logging
+
+from fastapi import APIRouter, HTTPException, Request
 
 from app.api.deps import DbSession
 from app.repositories import analytics as analytics_repo
+from app.repositories import analytics_selfstat as selfstat_repo
 from app.schemas.analytics import AnalyticsBatchIn, AnalyticsIngestOut
+from app.schemas.analytics_selfstat import SelfStatBatchIn, SelfStatIngestOut
 
 router = APIRouter(prefix="/api/v1/analytics", tags=["analytics"])
+logger = logging.getLogger("shagua.analytics")
 
 
 def _client_ip(request: Request) -> str:
@@ -29,3 +34,13 @@ def ingest_events(
 ) -> AnalyticsIngestOut:
     n = analytics_repo.record_batch(db, batch, client_ip=_client_ip(request))
     return AnalyticsIngestOut(received=n)
+
+
+@router.post("/selfstat", response_model=SelfStatIngestOut, summary="上报自报计数快照")
+def ingest_selfstat(batch: SelfStatBatchIn, db: DbSession) -> SelfStatIngestOut:
+    try:
+        snap_id = selfstat_repo.record_selfstat(db, batch)
+    except Exception:  # noqa: BLE001 — 计数链路要稳,落库失败不裸奔 500,记日志回明确错误
+        logger.exception("selfstat ingest failed device=%s epoch=%s", batch.device_id, batch.epoch_id)
+        raise HTTPException(status_code=503, detail="selfstat ingest failed") from None
+    return SelfStatIngestOut(snapshot_id=snap_id)

app/api/v1/auth.py

@@ -12,19 +12,36 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, HTTPException, Request, status
+from fastapi import APIRouter, HTTPException, Request
+from sqlalchemy.exc import IntegrityError
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import test_account
-from app.core.ratelimit import enforce_rate_limit
-from app.core.security import TokenError, decode_token, issue_token_pair
+from app.core.ratelimit import (
+    RateLimitRule,
+    check_rate_limits,
+    enforce_rate_limit,
+    record_rate_limits,
+)
+from app.core.security import (
+    TokenError,
+    create_bind_ticket,
+    create_conflict_ticket,
+    decode_bind_ticket,
+    decode_conflict_ticket,
+    decode_token,
+    issue_token_pair,
+)
+from app.integrations import wxpay
 from app.integrations.jiguang import JiguangError, mask_phone, verify_and_get_phone
 from app.integrations.sms import SmsError, send_code, verify_code
 from app.repositories import onboarding as onboarding_repo
+from app.repositories import phone_rebind as rebind_repo
 from app.repositories import user as user_repo
 from app.schemas.auth import (
     JverifyLoginRequest,
     LogoutResponse,
+    OccupiedAccountInfo,
     RefreshRequest,
     SmsLoginRequest,
     SmsSendRequest,
@@ -32,6 +49,13 @@ from app.schemas.auth import (
     TokenPair,
     TokenWithUser,
     UserOut,
+    WechatBindPhoneJverifyRequest,
+    WechatBindPhoneSmsRequest,
+    WechatBindResultResponse,
+    WechatConflictContinueRequest,
+    WechatConflictRebindRequest,
+    WechatLoginRequest,
+    WechatLoginResponse,
 )
 
 logger = logging.getLogger("shagua.auth")
@@ -40,9 +64,10 @@ router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 
 # 手机号登录防刷:同一设备(device_id) + 同一 IP 每小时最多的登录尝试次数(成功/失败都计)。
 SMS_LOGIN_MAX_PER_HOUR = 5
-# 发码防刷:同一设备(device_id) + 同一 IP 每小时最多的发码次数。
+# 发码防刷(同一设备 device_id + 同一 IP,**只按成功发码计数**;被单号 60s 冷却挡下的重发不占额度):
 # 堵「换手机号绕开单号 60s 冷却」的洞 —— 冷却是单号维度,一机换号能绕开。
-SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5
+SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5     # 每小时上限
+SMS_SEND_MAX_PER_DAY_PER_DEVICE = 20     # 每天上限(再叠一层日封顶,挡低频长时间轰炸)
 
 
 def _login_response(
@@ -99,23 +124,26 @@ def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
         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)之前 → 超限直接拦下、不真发短信。
-    enforce_rate_limit(
-        request,
-        scope="sms-send-device",
-        subject=req.device_id,
-        limit=SMS_SEND_MAX_PER_HOUR_PER_DEVICE,
-        window_sec=3600,
-        detail="操作过于频繁,请稍后再试",
-    )
+    # 发码防刷:同一设备(device_id) + 同一 IP,每小时 / 每天两道闸,**均只按成功发码计数**。
+    # 补「换手机号绕开单号 60s 冷却」的洞(冷却是单号维度,一机换号能绕);设备维度按机器封顶,挡短信轰炸/烧钱。
+    # 关键:被单号 60s 冷却挡下的重发是「没真发、没烧钱」→ 不该占额度。故 check(先判)放在真发之前
+    # (超限直接 429、不真发),record(计数)只在 send_code 成功后调 —— 冷却/供应商失败抛 429 时直接返回、不计数。
+    send_rules = [
+        RateLimitRule("sms-send-device", SMS_SEND_MAX_PER_HOUR_PER_DEVICE, 3600,
+                      "操作过于频繁,请稍后再试"),
+        RateLimitRule("sms-send-device-daily", SMS_SEND_MAX_PER_DAY_PER_DEVICE, 86400,
+                      "今日验证码发送次数过多,请明天再试"),
+    ]
+    check_rate_limits(request, subject=req.device_id, rules=send_rules)
 
     try:
         cooldown = send_code(req.phone)
     except SmsError as e:
         raise HTTPException(status_code=e.status_code, detail=str(e)) from e
 
+    # 发码成功 → 两道闸各 +1(被单号冷却挡下的重发走不到这里,故不占额度)
+    record_rate_limits(request, subject=req.device_id, rules=send_rules)
+
     from app.core.config import settings  # 局部 import 避免循环
 
     return SmsSendResponse(sent=True, mock=settings.SMS_MOCK, cooldown_sec=cooldown)
@@ -166,6 +194,261 @@ def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWit
     return _login_response(user, onboarding_completed=completed)
 
 
+# ===================== 微信登录 =====================
+
+@router.post(
+    "/wechat-login",
+    response_model=WechatLoginResponse,
+    summary="微信登录(openid 命中即登入,否则发绑号令牌)",
+)
+def wechat_login(req: WechatLoginRequest, db: DbSession) -> WechatLoginResponse:
+    from app.core.config import settings  # 局部 import,避免循环
+
+    # 微信登录只需 code→openid(sns/oauth2),不需要商户转账证书;故只校验 APP_ID/SECRET。
+    if not (settings.WECHAT_APP_ID and settings.WECHAT_APP_SECRET):
+        raise HTTPException(status_code=503, detail="wechat login not configured")
+
+    try:
+        info = wxpay.code_to_userinfo(req.code)  # {openid, nickname, avatar_url, raw};失败抛 ValueError
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e)) from e
+
+    openid = info["openid"]
+    user = user_repo.get_user_by_wechat_openid(db, openid)
+    if user is not None:
+        # openid 命中 → 直接登入(绝不套用提现 bind-wechat 的"撞号即 409"逻辑)
+        if user.status != "active":
+            raise HTTPException(status_code=403, detail="account disabled")
+        user_repo.touch_last_login(db, user)
+        completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+        logger.info("wechat_login hit user_id=%d openid=%s*** onboarded=%s", user.id, openid[:6], completed)
+        return WechatLoginResponse(
+            status="logged_in",
+            token=_login_response(user, onboarding_completed=completed),
+        )
+
+    # 未命中 → 签发短时 bind_ticket,进手机号绑定流程(账号此刻还不建)
+    ticket = create_bind_ticket(
+        openid=openid,
+        wechat_nickname=info["nickname"],
+        wechat_avatar_url=info["avatar_url"],
+    )
+    logger.info("wechat_login new openid=%s*** issue bind_ticket", openid[:6])
+    return WechatLoginResponse(
+        status="need_bind_phone",
+        bind_ticket=ticket,
+        wechat_nickname=info["nickname"],
+        wechat_avatar_url=info["avatar_url"],
+    )
+
+
+def _finish_wechat_bind(
+    db,
+    *,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+    phone: str,
+    device_id: str,
+) -> WechatBindResultResponse:
+    """绑手机建号的公共尾段:手机号被占用 → 返回 phone_occupied(M2 处理 3 选 1);
+    未占用 → 新建微信账号(channel=wechat,昵称头像取微信)→ 签 token 登入。"""
+    existing = user_repo.get_user_by_phone(db, phone)
+    if existing is not None:
+        from app.core.config import settings  # 局部 import,避免循环
+
+        ticket = create_conflict_ticket(
+            openid=openid,
+            wechat_nickname=wechat_nickname,
+            wechat_avatar_url=wechat_avatar_url,
+            phone=phone,
+        )
+        blocked = rebind_repo.rebound_within_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+        logger.info(
+            "wechat bind phone occupied phone=%s by user_id=%d has_wechat=%s",
+            mask_phone(phone), existing.id, bool(existing.wechat_openid),
+        )
+        return WechatBindResultResponse(
+            status="phone_occupied",
+            occupied_account=OccupiedAccountInfo(
+                nickname=existing.nickname,
+                avatar_url=existing.avatar_url,
+                created_at=existing.created_at,
+                has_wechat=bool(existing.wechat_openid),
+            ),
+            conflict_ticket=ticket,
+            rebind_available=not blocked,
+            rebind_blocked_days=(
+                rebind_repo.remaining_block_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+                if blocked else 0
+            ),
+        )
+    user = user_repo.create_wechat_user(
+        db,
+        phone=phone,
+        openid=openid,
+        wechat_nickname=wechat_nickname,
+        wechat_avatar_url=wechat_avatar_url,
+    )
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=device_id)
+    logger.info("wechat bind ok user_id=%d phone=%s openid=%s*** onboarded=%s",
+                user.id, mask_phone(phone), openid[:6], completed)
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
+@router.post(
+    "/wechat/bind-phone/sms",
+    response_model=WechatBindResultResponse,
+    summary="微信登录·其他手机号(短信)绑定",
+)
+def wechat_bind_phone_sms(
+    req: WechatBindPhoneSmsRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_bind_ticket(req.bind_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="授权已过期,请重新用微信登录") from e
+
+    # 防刷:同 sms/login,按 设备+IP 每小时限流(放在验证码校验之前,失败也计数)
+    enforce_rate_limit(
+        request,
+        scope="wechat-bind-sms-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")
+
+    return _finish_wechat_bind(
+        db,
+        openid=claims["openid"],
+        wechat_nickname=claims["wnk"],
+        wechat_avatar_url=claims["wav"],
+        phone=req.phone,
+        device_id=req.device_id,
+    )
+
+
+@router.post(
+    "/wechat/bind-phone/jverify",
+    response_model=WechatBindResultResponse,
+    summary="微信登录·本机号(极光)绑定",
+)
+def wechat_bind_phone_jverify(
+    req: WechatBindPhoneJverifyRequest, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_bind_ticket(req.bind_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="授权已过期,请重新用微信登录") from e
+
+    try:
+        phone = verify_and_get_phone(req.login_token)
+    except JiguangError as e:
+        logger.error("[JG] verify+decrypt failed: %s", e, exc_info=True)
+        raise HTTPException(status_code=502, detail=f"jiguang verify failed: {e}") from e
+
+    return _finish_wechat_bind(
+        db,
+        openid=claims["openid"],
+        wechat_nickname=claims["wnk"],
+        wechat_avatar_url=claims["wav"],
+        phone=phone,
+        device_id=req.device_id,
+    )
+
+
+# ===================== 微信占用冲突(M2) =====================
+
+@router.post(
+    "/wechat/conflict/continue",
+    response_model=WechatBindResultResponse,
+    summary="微信占用冲突·继续绑定(登录老账号,能绑就绑)",
+)
+def wechat_conflict_continue(
+    req: WechatConflictContinueRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    try:
+        claims = decode_conflict_ticket(req.conflict_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="操作超时,请重新用微信登录") from e
+
+    enforce_rate_limit(
+        request, scope="wechat-conflict-device", subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR, window_sec=3600, detail="操作过于频繁,请稍后再试",
+    )
+
+    user = user_repo.get_user_by_phone(db, claims["phone"])
+    if user is None:
+        # P 期间被腾空(老账号改号/注销)→ 前提已变,让前端重走
+        raise HTTPException(status_code=409, detail="账号状态已变化,请重新登录")
+    if user.status != "active":
+        raise HTTPException(status_code=403, detail="account disabled")
+
+    if user.wechat_openid is None:
+        try:
+            user_repo.attach_wechat_to_user(
+                db, user, openid=claims["openid"],
+                wechat_nickname=claims["wnk"], wechat_avatar_url=claims["wav"],
+            )
+        except IntegrityError:
+            db.rollback()  # openid 被别处绑走 → 只登入不绑
+            user_repo.touch_last_login(db, user)
+    else:
+        user_repo.touch_last_login(db, user)  # X 已绑别的微信 → 只登入,丢弃本次 openid
+
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("wechat conflict continue user_id=%d openid=%s***", user.id, claims["openid"][:6])
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
+@router.post(
+    "/wechat/conflict/rebind",
+    response_model=WechatBindResultResponse,
+    summary="微信占用冲突·换绑(注销老账号+用该号重建全新账号)",
+)
+def wechat_conflict_rebind(
+    req: WechatConflictRebindRequest, request: Request, db: DbSession
+) -> WechatBindResultResponse:
+    from app.core.config import settings  # 局部 import,避免循环
+
+    try:
+        claims = decode_conflict_ticket(req.conflict_ticket)
+    except TokenError as e:
+        raise HTTPException(status_code=401, detail="操作超时,请重新用微信登录") from e
+
+    enforce_rate_limit(
+        request, scope="wechat-conflict-device", subject=req.device_id,
+        limit=SMS_LOGIN_MAX_PER_HOUR, window_sec=3600, detail="操作过于频繁,请稍后再试",
+    )
+
+    phone = claims["phone"]
+    if rebind_repo.rebound_within_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS):
+        days = rebind_repo.remaining_block_days(db, phone, settings.PHONE_REBIND_LIMIT_DAYS)
+        raise HTTPException(status_code=409, detail=f"该手机号 {days} 天内已换绑过,暂不能再次换绑")
+
+    user = user_repo.rebind_account(
+        db, phone=phone, openid=claims["openid"],
+        wechat_nickname=claims["wnk"], wechat_avatar_url=claims["wav"],
+    )
+    completed = onboarding_repo.is_completed(db, user_id=user.id, device_id=req.device_id)
+    logger.info("wechat conflict rebind new_user_id=%d phone=%s openid=%s***",
+                user.id, mask_phone(phone), claims["openid"][:6])
+    return WechatBindResultResponse(
+        status="logged_in",
+        token=_login_response(user, onboarding_completed=completed),
+    )
+
+
 # ===================== Refresh =====================
 
 @router.post("/refresh", response_model=TokenPair, summary="用 refresh_token 换新 token 对")

app/api/v1/compare_record.py

@@ -27,6 +27,7 @@ from app.schemas.compare_record import (
     ComparisonRecordOut,
     ComparisonRecordPage,
 )
+from app.services.llm_cost import compute_llm_cost, get_llm_prices
 from app.services.pricebot_llm_calls import fetch_llm_calls
 
 logger = logging.getLogger("shagua.compare_record")
@@ -81,6 +82,8 @@ def _backfill_llm_calls(record_id: int, trace_id: str) -> None:
         # error 的调用 usage 可能为 None,or {} 兜底)
         rec.input_tokens = sum((c.get("usage") or {}).get("prompt_tokens") or 0 for c in calls)
         rec.output_tokens = sum((c.get("usage") or {}).get("completion_tokens") or 0 for c in calls)
+        # 本次比价 LLM 成本(元)+ 当时单价快照:按 app_config 现价逐模型算好冻结(services/llm_cost.py)。
+        rec.llm_cost_yuan, rec.llm_price_snapshot = compute_llm_cost(calls, get_llm_prices(db))
         db.commit()
         logger.info(
             "backfill llm_calls trace=%s n=%d in_tok=%d out_tok=%d",

app/api/v1/coupon.py

@@ -81,7 +81,16 @@ def _record_claims_blocking(
     device_id: str, user_id: int | None, trace_id: str | None, results: list[dict]
 ) -> None:
     with SessionLocal() as db:
-        coupon_repo.record_claims(db, device_id, user_id, trace_id, results)
+        # 取本次 session 环境,给 coupon_claim_record 打 app_env 标(每券成功率表按它过滤;设计 §13)。
+        app_env = coupon_repo.session_app_env(db, trace_id)
+        coupon_repo.record_claims(db, device_id, user_id, trace_id, results, app_env=app_env)
+        # 顺带把本帧「成功平台」并入 coupon_session.platform_success(admin 领券数据 ②整单/③点位成功率;
+        # 设计 route B,见 docs/guides/领券成功率指标-设计与埋点.md)。复用同一 SessionLocal、紧接 record_claims,
+        # 不新增连接;并集幂等(无新平台不写),trace_id 缺失或 session 行未落库则跳过。
+        if trace_id:
+            coupon_repo.merge_session_platform_success(
+                db, trace_id, coupon_repo.succeeded_platforms(results)
+            )
 
 
 def _mark_completed_blocking(

app/api/v1/meituan.py

@@ -25,9 +25,19 @@ from app.schemas.meituan import (
     ReferralLinkResponse,
     TopSalesRequest,
 )
+from app.utils.meituan_city import get_meituan_city
 
 logger = logging.getLogger("shagua.meituan")
 
+
+def _resolve_city_id(latitude: float, longitude: float) -> str:
+    """经纬度 → 美团城市 ID;解析失败返 ""（调用方应降级返空）。"""
+    try:
+        return get_meituan_city(latitude, longitude).get("city_id", "")
+    except Exception:
+        logger.exception("get_meituan_city 失败")
+        return ""
+
 router = APIRouter(prefix="/api/v1/meituan", tags=["meituan-cps"])
 
 
@@ -175,13 +185,19 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
         status = "degraded" if (not cards and wm_fail and dd_fail) else ("ok" if cards else "empty")
         return FeedResponse(items=cards, has_next=wm_hn or dd_hn, page=req.page, status=status)
 
-    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
+    # 智能推荐(rec):走【离线库】筛佣金率 ≥ 3%,按城市过滤,分页返回(SQL 侧去重+排序+分页,秒级、不打美团)。
     # 实测库里佣金≥3% 去重后仅 ~578 条(几乎全是外卖;到店团购佣金普遍 <3%):实时按"同城热销榜单"
     # 拉既撞限流、又填不满(该榜单中位佣金 ~0.8%,筛完每页剩 0-1 条),故从库出。佣金阈值逻辑不变。
     if tab == "rec":
+        city_id = _resolve_city_id(lat, lon)
+        if not city_id:
+            return FeedResponse(items=[], has_next=False, page=req.page, status="degraded")
         PAGE = 20
         try:
-            base = select(MeituanCoupon).where(MeituanCoupon.commission_percent >= 3.0)
+            base = select(MeituanCoupon).where(
+                MeituanCoupon.commission_percent >= 3.0,
+                MeituanCoupon.city_id == city_id,
+            )
             deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
                 MeituanCoupon.dedup_key,
                 MeituanCoupon.commission_percent.desc(),
@@ -211,6 +227,9 @@ def feed(req: FeedRequest, db: Session = Depends(get_db)) -> FeedResponse:
                 card.distance_text = None
                 card.distance_meters = None
                 cards.append(card)
+        if not cards and req.page == 1:
+            # 命中城市却 0 券:该城确无 ≥3% 券,或 ETL 灌的 city_id 与 city_dict 口径不一致。
+            logger.info("[feed] rec city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
         return FeedResponse(items=cards, has_next=has_next, page=req.page,
                             status="ok" if cards else "empty")
 
@@ -254,14 +273,24 @@ def referral_link(req: ReferralLinkRequest) -> ReferralLinkResponse:
 
 
 @router.post("/top-sales", response_model=CouponListResponse,
-             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,不实时打美团)")
+             summary="销量最高(从离线库 meituan_coupon 按销量降序 + 跨源去重,按城市过滤,不实时打美团)")
 def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponListResponse:
+    # 按设备经纬度定位城市,只查同城券;老客户端不带坐标 → 降级返空(不 422、不误返全城)。
+    if req.latitude is None or req.longitude is None:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+    city_id = _resolve_city_id(req.latitude, req.longitude)
+    if not city_id:
+        return CouponListResponse(items=[], has_next=False, search_id=None, status="degraded")
+
     # 去重 + 排序 + 分页全在 SQL 做,每页只取并解析当前页 ~20 条。
     # (之前实现每翻一页都全表拉取 + 全量 from_raw 解析,翻页慢 → 客户端滑动卡顿/翻不动。)
     # 库为空(prod 刚部署 / ETL 未跑完)时返空 + status=empty,不崩;库查询异常降级 degraded。
     try:
         # 1) DISTINCT ON (dedup_key):每个去重键(品牌|名|价)只留销量最高那条(同销量再按佣金)
-        base = select(MeituanCoupon).where(MeituanCoupon.sale_volume_num.isnot(None))
+        base = select(MeituanCoupon).where(
+            MeituanCoupon.sale_volume_num.isnot(None),
+            MeituanCoupon.city_id == city_id,
+        )
         if req.platform is not None:
             base = base.where(MeituanCoupon.platform == req.platform)
         deduped = base.distinct(MeituanCoupon.dedup_key).order_by(
@@ -292,6 +321,14 @@ def top_sales(req: TopSalesRequest, db: Session = Depends(get_db)) -> CouponList
         except Exception:  # noqa: BLE001
             continue
         if card.product_view_sign:
+            # 不显示距离:库里的距离是相对城市默认点的(对用户无意义、且误导)。
+            # 置空后前端"距离 店名"那行只剩店名、自动顶到最左(店名移到原距离的位置)。
+            # 逻辑与推荐流保持一致
+            card.distance_text = None
+            card.distance_meters = None
             cards.append(card)
+    if not cards and req.page == 1:
+        # 命中城市却 0 券:可能该城确无券,也可能 ETL 灌的 city_id 与 city_dict 口径不一致(静默降级的隐患)。
+        logger.info("[top-sales] city_id=%s 命中 0 券(该城确无券?或 ETL/city_dict 的 city_id 口径不一致)", city_id)
     return CouponListResponse(items=cards, has_next=has_next, search_id=None,
                               status="ok" if cards else "empty")

app/api/v1/platform.py

@@ -20,6 +20,7 @@ from app.schemas.platform import (
     AdConfigPublicOut,
     AppFlagsOut,
     AppVersionOut,
+    HuaweiReviewOut,
     PlatformStatsOut,
     SavingsFeedItem,
     SavingsFeedOut,
@@ -72,6 +73,15 @@ def ad_config(db: DbSession) -> AdConfigPublicOut:
     )
 
 
+@router.get("/huawei-review", response_model=HuaweiReviewOut, summary="华为审核开关(不鉴权)")
+def huawei_review(db: DbSession) -> HuaweiReviewOut:
+    """客户端进新手引导前拉一次,决定「快速设置」权限步左上角要不要给退出按钮。
+    不鉴权:引导页在登录之前就展示,此时必然没有 token。空库回退 default(=不给退出按钮,维持现状)。
+    只有华为 ROM 客户端会来拉(荣耀 MagicOS 不拉),故这里不做机型判断,由客户端自己 gate。"""
+    mode = app_config.get_huawei_review(db)["mode"]
+    return HuaweiReviewOut(mode=mode, onboarding_closable=(mode == "review"))
+
+
 @router.get("/app-version", response_model=AppVersionOut, summary="最新 App 版本(OTA 检查更新,不鉴权)")
 def app_version(db: DbSession) -> AppVersionOut:
     """客户端启动 / 手动检查更新时拉取。不鉴权:版本信息非敏感,且检查更新可能在登录前。

app/api/v1/signin.py

@@ -1,9 +1,12 @@
 """签到 endpoint。
 
 路由前缀 `/api/v1/signin`:
-  GET  /status    今日签到状态 + 14 天档位
+  GET  /status    今日签到状态 + 7 天档位
   POST /          执行今日签到
-  POST /boost     签到后看广告膨胀金币
+
+2026-07 下线 `POST /boost`(签到膨胀):它按固定 3000 金币补发、与广告实际收益脱钩。
+签到弹窗里的「看广告膨胀」改与福利页看视频走同一条 reward_video 路径(按 eCPM 发,
+`/ad/pangle-callback` → `/ad/reward-result` 取金额),奖励只剩「签到」+「看视频」两种。
 """
 from __future__ import annotations
 
@@ -12,15 +15,8 @@ import logging
 from fastapi import APIRouter, HTTPException, status
 
 from app.api.deps import CurrentUser, DbSession
-from app.repositories import ad_reward as crud_ad
 from app.repositories import signin as crud_signin
-from app.repositories import wallet as crud_wallet
-from app.schemas.welfare import (
-    SigninBoostRequest,
-    SigninBoostResultOut,
-    SigninResultOut,
-    SigninStatusOut,
-)
+from app.schemas.welfare import SigninResultOut, SigninStatusOut
 
 logger = logging.getLogger("shagua.signin")
 
@@ -50,34 +46,3 @@ def do_signin(user: CurrentUser, db: DbSession) -> SigninResultOut:
         streak=record.streak,
         coin_balance=balance,
     )
-
-
-@router.post("/boost", response_model=SigninBoostResultOut, summary="签到后看广告膨胀金币")
-def boost_signin(
-    payload: SigninBoostRequest, user: CurrentUser, db: DbSession
-) -> SigninBoostResultOut:
-    if not payload.ad_ref_id:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="ad reward required")
-    ad_rec = crud_ad.find_by_trans(db, payload.ad_ref_id)
-    if (
-        ad_rec is None
-        or ad_rec.user_id != user.id
-        or ad_rec.reward_scene != "signin_boost"
-        or ad_rec.status != "granted"
-    ):
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="ad reward not verified")
-    record = crud_signin.boost_by_ad_ref(db, user.id, payload.ad_ref_id)
-    if record is None:
-        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="signin boost not granted")
-    acc = crud_wallet.get_or_create_account(db, user.id)
-    balance = acc.coin_balance
-
-    logger.info(
-        "signin boost ok user_id=%d date=%s coin=%d",
-        user.id, record.signin_date, record.coin_awarded,
-    )
-    return SigninBoostResultOut(
-        coin_awarded=record.coin_awarded,
-        coin_balance=balance,
-        signin_date=record.signin_date.isoformat(),
-    )

app/api/v1/user.py

@@ -98,19 +98,15 @@ def onboarding_status(
     return OnboardingStatusResponse(completed=completed)
 
 
-@router.delete("", response_model=OkResponse, summary="注销账号(清理个人数据 + 匿名化)")
+@router.delete("", response_model=OkResponse, summary="注销账号(软删除)")
 def delete_account(user: CurrentUser, db: DbSession) -> OkResponse:
-    # 资金前置校验:注销会物理清理个人数据 + 清零余额 + 匿名化,余额一旦清零就再也拿不回。
-    # 有可提现现金 / 邀请奖励金 / 在审提现单 → 拒绝注销,引导用户先把钱处理掉。
+    # 资金前置校验:注销是软删 + 匿名化,余额一旦留在 deleted 行就锁死(既退不出、新号也
+    # 拿不回)。有可提现现金 / 在审提现单 → 拒绝注销,引导用户先把钱处理掉。
     # (pending 提现转账已在途、对账 worker 不依赖 user.status 照常到账,故不拦 pending。)
     if wallet_repo.get_cash_balance_cents(db, user.id) > 0:
         raise HTTPException(
             status_code=409, detail="账户还有未提现的现金余额,请先提现后再注销"
         )
-    if wallet_repo.get_invite_cash_balance_cents(db, user.id) > 0:
-        raise HTTPException(
-            status_code=409, detail="账户还有未提现的邀请奖励金,请先提现后再注销"
-        )
     if wallet_repo.has_reviewing_withdraw(db, user.id):
         raise HTTPException(
             status_code=409, detail="有提现正在审核中,请等审核完成后再注销"

app/api/v1/wallet.py

@@ -43,6 +43,7 @@ from app.schemas.welfare import (
     WithdrawRequest,
     WithdrawResultOut,
     WithdrawStatusOut,
+    WithdrawTierOut,
 )
 
 logger = logging.getLogger("shagua.wallet")
@@ -173,8 +174,15 @@ def unbind_wechat(
     return UnbindWechatResultOut(bound=False)
 
 
-@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态/免确认开关")
-def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
+@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态/免确认开关/档位")
+def withdraw_info(
+    user: CurrentUser,
+    db: DbSession,
+    source: str = Query(
+        "coin_cash",
+        description="提现账户:coin_cash(福利页,下发 tiers 档位) / invite_cash(邀请页,tiers 为空走旧逻辑)",
+    ),
+) -> WithdrawInfoOut:
     u = db.get(User, user.id)
     # 顺带同步免确认授权状态(捕获首单确认后已生效的授权 pending→active),让开关展示实时
     auth = crud_wallet.sync_transfer_auth(db, user.id)
@@ -185,6 +193,7 @@ def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
         wechat_nickname=u.wechat_nickname if u else None,
         wechat_avatar_url=u.wechat_avatar_url if u else None,
         transfer_auth_enabled=bool(auth and auth.state == "active"),
+        tiers=[WithdrawTierOut(**t) for t in crud_wallet.withdraw_tier_states(db, user.id, source)],
     )
 
 
@@ -218,6 +227,9 @@ def withdraw(req: WithdrawRequest, user: CurrentUser, db: DbSession) -> Withdraw
             status_code=status.HTTP_409_CONFLICT,
             detail="已有提现申请正在审核或打款中,请处理完成后再申请",
         ) from e
+    except crud_wallet.WithdrawTierUnavailableError as e:
+        # 福利页档位闸(7-9):次数满/已选其他额度。正常客户端已按 tiers 预拦,此处兜底防绕过。
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="今日额度已达上限") from e
     except crud_wallet.InsufficientCashError as e:
         raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="现金余额不足") from e
 

app/core/config.py

@@ -44,6 +44,11 @@ class Settings(BaseSettings):
     JWT_ALGORITHM: str = "HS256"
     JWT_ACCESS_TOKEN_EXPIRE_MINUTES: int = 120
     JWT_REFRESH_TOKEN_EXPIRE_DAYS: int = 30
+    # 微信登录未命中 openid 时签发的"待绑手机"令牌有效期(JWT_SECRET_KEY 签名,typ=wechat_bind;
+    # 见 security.create_bind_ticket)。需覆盖"授权→输手机号→收短信→输验证码"整个绑定流程。
+    WECHAT_BIND_TICKET_EXPIRE_MINUTES: int = 10
+    # 一个手机号 30 天内最多换绑一次(微信占用冲突页的"换绑"动作)。见 phone_rebind_log。
+    PHONE_REBIND_LIMIT_DAYS: int = 30
 
     # ===== Admin 后台 =====
     # admin 用独立 JWT secret(≠ JWT_SECRET_KEY),App 用户 token 无法越权访问后台。
@@ -81,6 +86,7 @@ class Settings(BaseSettings):
     SMS_SIGN_ID: int = 31729       # 极光短信签名 ID(非机密,可被 .env 覆盖)
     SMS_TEMPLATE_ID: int = 1       # 极光短信模板 ID(变量名 code,有效期 5 分钟)
     SMS_CODE_LENGTH: int = 6       # 验证码位数(本服务生成;前端 code 字段 4-8 位兼容)
+    SMS_DAILY_LIMIT_PER_PHONE: int = 10   # 单手机号每日发送上限(防刷 + 控费)
     SMS_MAX_VERIFY_ATTEMPTS: int = 5      # 单个验证码最多校验失败次数,超过即作废(防爆破)
 
     # ===== 测试账号(release 包全流程联调用)=====
@@ -106,6 +112,9 @@ class Settings(BaseSettings):
     # 美团调用走的代理。本机开发直连美团会 SSL EOF,需填 http://127.0.0.1:7897;
     # 线上国内服务器留空(=直连)。见 .env.example 与 integrations/meituan.py。
     MT_CPS_PROXY: str = ""
+    # 本地开发:开启后 /feed 接口直接返回 mock 数据,不调美团 API、不查离线库,
+    # 方便前端联调 feed 卡片样式、分页、距离排序等 UI。生产必须 false。
+    MT_CPS_MOCK_FEED: bool = True
 
     @property
     def mt_cps_configured(self) -> bool:
@@ -169,6 +178,15 @@ class Settings(BaseSettings):
     # 进程内自动兑换 worker 的检查间隔(秒):每隔这么久醒一次,跨过北京 0 点就跑一轮。
     # 默认 600s=10min,即 0 点后最多 10 分钟内兑完(客户端文案已注明「可能存在延迟」)。
     AUTO_EXCHANGE_CHECK_INTERVAL_SEC: int = 600
+    # === 15 天不活跃清零(app.core.inactivity_reset_worker,worker 常驻)===
+    # ENABLED 只决定是否**真清**:false(默认)= 只记审计名单、不动钱(dry-run,灰度看名单);
+    # true = 真清金币 + 折算现金(邀请金不清)。看准名单后再置 true。
+    INACTIVITY_RESET_ENABLED: bool = False
+    INACTIVITY_RESET_DAYS: int = 15                  # 不活跃阈值(天),第 (N+1) 日 0 点清
+    INACTIVITY_WARN_DAYS_BEFORE: str = "7,2"         # 清零前几天各推一次;""=不推。逗号分隔
+    INACTIVITY_RESET_RUN_HOUR: int = 3               # 北京时间每日执行点(0-23)
+    INACTIVITY_NOTIFY_CHANNEL: str = "log"           # log(占位) / jpush / sms
+    INACTIVITY_RESET_CHECK_INTERVAL_SEC: int = 1800  # worker 唤醒间隔(秒)
     # 免确认收款授权(用户授权免确认模式)的授权结果回调地址,必须公网可访问 HTTPS、不带参数。
     # 发起授权 / 首单顺带授权时作为 authorization_notify_url 传给微信。一期不处理回调内容
     # (授权状态靠 query 查询兜底),但微信要求该字段非空,故启用免确认前必须配置;留空时免确认相关接口返回未配置。
@@ -189,6 +207,19 @@ class Settings(BaseSettings):
         """免确认收款授权可用 = 微信支付凭证齐全 + 授权回调地址已配。"""
         return bool(self.wxpay_configured and self.WXPAY_AUTH_NOTIFY_URL)
 
+    @property
+    def inactivity_warn_stages(self) -> list[int]:
+        """解析 INACTIVITY_WARN_DAYS_BEFORE → 降序去重的提前天数列表。
+        丢弃非数字 / <=0 / >=RESET_DAYS 的项(空串 → 空列表 = 不推)。"""
+        out: list[int] = []
+        for part in (self.INACTIVITY_WARN_DAYS_BEFORE or "").split(","):
+            part = part.strip()
+            if part.isdigit():
+                v = int(part)
+                if 0 < v < self.INACTIVITY_RESET_DAYS and v not in out:
+                    out.append(v)
+        return sorted(out, reverse=True)
+
     # ===== 穿山甲激励视频(服务端发奖回调)=====
     # 看完激励视频后穿山甲服务器回调本服务发金币(S2S,客户端被破解也刷不到)。
     # 穿山甲后台配置的"奖励校验密钥"(m-key),验签用。每个 GroMore 广告位 m-key 不同(后台各自
@@ -316,6 +347,31 @@ class Settings(BaseSettings):
             return []
         return [o.strip() for o in self.CORS_ALLOW_ORIGINS.split(",") if o.strip()]
 
+    # ===== 可观测(OpenObserve 接口指标)=====
+    # 采集每个接口的 QPS + 耗时 + 错误率,批量直采到 OpenObserve(本地 Docker)。
+    # 默认关(prod 安全):未开启 → 中间件透传、worker 不启动,整套 no-op。
+    # 开启需 ENABLED=true 且 ENDPOINT/USER/PASSWORD 齐全(见 observe_configured)。
+    OBSERVE_ENABLED: bool = False
+    OBSERVE_ENDPOINT: str = "http://localhost:5080"   # OpenObserve base URL
+    OBSERVE_ORG: str = "default"                        # 组织名
+    OBSERVE_STREAM: str = "app_requests"               # stream 名(首次上报自动建)
+    OBSERVE_USER: str = ""                             # Basic auth 邮箱
+    OBSERVE_PASSWORD: str = ""                         # Basic auth 密码/token
+    OBSERVE_FLUSH_INTERVAL_SEC: float = 5.0            # worker 最长攒批间隔
+    OBSERVE_BATCH_MAX: int = 200                       # 单批最大事件数
+    OBSERVE_QUEUE_MAX: int = 10000                     # 有界队列上限,满则丢
+    OBSERVE_TIMEOUT_SEC: float = 5.0                   # 上报 HTTP 超时
+
+    @property
+    def observe_configured(self) -> bool:
+        """观测上报可用 = 总开关开 且 endpoint/账号/密码齐全(缺则整套 no-op)。"""
+        return bool(
+            self.OBSERVE_ENABLED
+            and self.OBSERVE_ENDPOINT
+            and self.OBSERVE_USER
+            and self.OBSERVE_PASSWORD
+        )
+
     @property
     def is_prod(self) -> bool:
         return self.APP_ENV == "prod"

app/core/config_schema.py

@@ -11,7 +11,10 @@ from typing import Any
 
 from app.core import rewards as r
 
-# type 约定(给前端渲染编辑控件用):int / int_list / dict_str_int / bool
+# type 约定(给前端渲染编辑控件用):int / int_list / dict_str_int / bool / enum
+# hidden=True:仍是合法可配项(业务照常 get_value / admin 可经专用端点读写),但**不在通用
+#   「系统配置」页渲染**(admin/routers/config.py:list_config 按此过滤)。用于把已下线/已改由
+#   专用页管理的项从福利页 Tab 收起,同时保留后端默认值与写入能力。
 CONFIG_DEFS: dict[str, dict[str, Any]] = {
     "signin_rewards": {
         "default": list(r.SIGNIN_REWARDS), "label": "签到 7 天金币档位",
@@ -30,18 +33,21 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
         "default": r.WITHDRAW_MAX_CENTS, "label": "提现最高额(分)",
         "group": "钱包", "type": "int",
     },
+    # 从福利页 Tab 收起(hidden)的项:任务 / 里程碑 整组 + 看广告组里的「单次金币(遗留展示值)/
+    # 每轮次数 / 比价领券信息流广告开关 comparing_ad_enabled」。key 与默认值保留、后端业务照常读取,
+    # 仅不在配置页渲染。看广告组保留可见的:每日上限 / 单次金币上限 / 关闭后冷却。
     "task_rewards": {
         "default": dict(r.TASK_REWARDS), "label": "一次性任务奖励",
-        "group": "任务", "type": "dict_str_int", "help": "task_key → 金币。",
+        "group": "任务", "type": "dict_str_int", "help": "task_key → 金币。", "hidden": True,
     },
     "record_milestones": {
         "default": list(r.RECORD_MILESTONES), "label": "比价里程碑金币档位",
-        "group": "里程碑", "type": "int_list",
+        "group": "里程碑", "type": "int_list", "hidden": True,
         "help": "累计成功比价第 1~N 档解锁发的金币。",
     },
     "ad_reward_coin": {
         "default": r.AD_REWARD_COIN, "label": "看广告单次金币",
-        "group": "看广告", "type": "int",
+        "group": "看广告", "type": "int", "hidden": True,
         "help": "历史兼容/测试展示值;正式发放按 eCPM 公式计算。",
     },
     "ad_daily_limit": {
@@ -54,20 +60,15 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
     },
     "ad_round_count": {
         "default": r.VIDEO_ROUND_REQUIRED_COUNT, "label": "每轮看广告次数",
-        "group": "看广告", "type": "int", "help": "当前为 1,表示每次广告关闭后触发短冷却。",
+        "group": "看广告", "type": "int", "hidden": True, "help": "当前为 1,表示每次广告关闭后触发短冷却。",
     },
     "ad_cooldown_sec": {
         "default": r.VIDEO_ROUND_COOLDOWN_SECONDS, "label": "广告关闭后冷却(秒)",
         "group": "看广告", "type": "int", "help": "点击退出广告后,下次点击观看前的冷却时间,默认 3 秒。",
     },
-    "signin_boost_coin": {
-        "default": r.SIGNIN_BOOST_COIN, "label": "签到膨胀固定金币",
-        "group": "签到", "type": "int",
-        "help": "Day1-Day6 签到后看完激励视频额外发放的固定金币;Day7 不展示也不允许膨胀。",
-    },
     "comparing_ad_enabled": {
         "default": True, "label": "比价/领券期信息流广告",
-        "group": "看广告", "type": "bool",
+        "group": "看广告", "type": "bool", "hidden": True,
         "help": (
             "开启后,比价进行中 + 领券等候期会在悬浮窗展示穿山甲信息流广告(变现行为);"
             "关闭则全程不出广告。客户端按 app 启动 / 每场比价开始时拉取并缓存,故为「最终一致」的"
@@ -84,4 +85,25 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
             "提现页「批量对账」手动按钮不受影响。"
         ),
     },
+    # 首页轮播数据源(hidden:不进通用配置 Tab,由「首页轮播种子」页的专用端点 /marquee-seeds/mode 读写)。
+    "marquee_feed_mode": {
+        "default": "mixed", "label": "首页轮播数据源",
+        "group": "首页轮播", "type": "enum", "hidden": True,
+        "help": "mixed=真实优先+种子补位(默认);real=只用真实比价记录;seed=只用种子/合成(演示)。",
+    },
+    # 比价 LLM 调用成本计价。值是嵌套 JSON(非 str→int),借 dict_str_int 类型在配置页走原始 JSON
+    # 编辑框;set_value 不校验类型,嵌套 JSON 照存。
+    "llm_token_price": {
+        "default": {
+            "per_model": {"qwen3.5-flash": {"input_per_1m": 0.8, "output_per_1m": 2.0}},
+            "default": {"input_per_1m": 3.0, "output_per_1m": 15.0},
+            "currency": "CNY", "unit": "per_1m_tokens",
+        },
+        "label": "LLM 模型单价(元/百万 token)",
+        "group": "LLM 成本", "type": "dict_str_int",
+        "help": (
+            "比价 LLM 调用成本计价。JSON:per_model 按模型配 input/output 单价(元/1M token),"
+            "default 兜底未登记的模型。改价只影响之后回填的新记录,历史记录用当时价格快照。"
+        ),
+    },
 }

app/core/inactivity_reset_worker.py

@@ -0,0 +1,145 @@
+"""15 天不活跃清零的进程内每日任务。
+
+仿 daily_exchange_worker:App 启动自带,每 `INACTIVITY_RESET_CHECK_INTERVAL_SEC` 醒一次,
+跨进北京新的一天且到达 `INACTIVITY_RESET_RUN_HOUR`(默认 3 点)后跑一轮 `run_once`(预警 + 清零)。
+
+健壮性:
+- **逐用户幂等**:清完余额=0 次日不再匹配;预警按 streak 去重。启动补跑 / 多次唤醒 / 重启都安全。
+- **同机多进程互斥**:文件锁保证多 worker 只有一个实际跑。
+- **常驻 + dry-run 默认**:worker 一直跑;INACTIVITY_RESET_ENABLED=false(默认)只记审计名单、
+  不动钱(dry-run 灰度看名单),=true 才真清。
+
+⚠️ 这是不可逆批量资金操作(清空金币 + 折算现金,**邀请现金不清**)。口径见
+app.repositories.inactivity / app.repositories.activity。
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import os
+import time
+from collections.abc import Iterator
+from datetime import date, datetime
+from pathlib import Path
+
+from sqlalchemy.exc import SQLAlchemyError
+
+from app.core.config import settings
+from app.core.rewards import CN_TZ, cn_today
+from app.db.session import SessionLocal
+from app.integrations.notifier import get_notifier
+from app.repositories import inactivity as inactivity_repo
+
+logger = logging.getLogger("shagua.inactivity")
+_LOCK_PATH = Path(__file__).resolve().parents[2] / "data" / "inactivity_reset.lock"
+
+
+def _cn_today() -> date:
+    return cn_today()
+
+
+def _touch_lock() -> None:
+    with contextlib.suppress(FileNotFoundError):
+        os.utime(_LOCK_PATH, None)
+
+
+@contextlib.contextmanager
+def _single_instance_lock(stale_after_sec: int) -> Iterator[bool]:
+    """同机多进程保护:同一时间只允许一个清零 worker 运行。"""
+    _LOCK_PATH.parent.mkdir(parents=True, exist_ok=True)
+    fd: int | None = None
+    try:
+        try:
+            fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            try:
+                age = time.time() - _LOCK_PATH.stat().st_mtime
+            except FileNotFoundError:
+                age = stale_after_sec + 1
+            if age > stale_after_sec:
+                with contextlib.suppress(FileNotFoundError):
+                    _LOCK_PATH.unlink()
+                try:
+                    fd = os.open(str(_LOCK_PATH), os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+                except FileExistsError:
+                    fd = None
+
+        if fd is None:
+            yield False
+            return
+
+        os.write(fd, f"pid={os.getpid()} started_at={int(time.time())}\n".encode("ascii"))
+        yield True
+    finally:
+        if fd is not None:
+            os.close(fd)
+            with contextlib.suppress(FileNotFoundError):
+                _LOCK_PATH.unlink()
+
+
+def _run_once_entry() -> dict:
+    """跑一轮(预警 + 清零)。独立开 Session。"""
+    notifier = get_notifier(settings.INACTIVITY_NOTIFY_CHANNEL)
+    with SessionLocal() as db:
+        return inactivity_repo.run_once(
+            db,
+            notifier=notifier,
+            reset_days=settings.INACTIVITY_RESET_DAYS,
+            warn_stages=settings.inactivity_warn_stages,
+            today=_cn_today(),
+            dry_run=not settings.INACTIVITY_RESET_ENABLED,  # ENABLED=false → 只记审计名单、不清
+        )
+
+
+async def _run_loop() -> None:
+    interval = max(60, int(settings.INACTIVITY_RESET_CHECK_INTERVAL_SEC))
+    lock_stale_after = max(interval * 3, 1800)
+    with _single_instance_lock(lock_stale_after) as lock_acquired:
+        if not lock_acquired:
+            logger.warning("inactivity reset skipped: another worker owns lock")
+            return
+        await _run_locked_loop(interval)
+
+
+async def _run_locked_loop(interval: int) -> None:
+    logger.info(
+        "inactivity reset worker started interval=%ss run_hour=%s mode=%s",
+        interval,
+        settings.INACTIVITY_RESET_RUN_HOUR,
+        "clear" if settings.INACTIVITY_RESET_ENABLED else "dry-run(audit-only)",
+    )
+    # 本进程上次跑过的北京日;None=尚未跑过本进程(当天到点即补)。
+    last_run: date | None = None
+    try:
+        while True:
+            try:
+                _touch_lock()
+                today = _cn_today()
+                hour = datetime.now(CN_TZ).hour
+                if last_run != today and hour >= int(settings.INACTIVITY_RESET_RUN_HOUR):
+                    result = await asyncio.to_thread(_run_once_entry)
+                    last_run = today
+                    logger.info("inactivity reset done date=%s result=%s", today, result)
+            except SQLAlchemyError:
+                logger.exception("inactivity reset db error")
+            except Exception:  # noqa: BLE001 - 后台任务不能因单次异常退出
+                logger.exception("inactivity reset unexpected error")
+            await asyncio.sleep(interval)
+    except asyncio.CancelledError:
+        logger.info("inactivity reset worker stopped")
+        raise
+
+
+def start_inactivity_reset_worker() -> asyncio.Task | None:
+    # worker 常驻(不再有"完全关"档);INACTIVITY_RESET_ENABLED 只决定是否**真清**:
+    # false(默认)= 只记审计名单(dry-run,不动钱),true = 真清金币+现金。
+    return asyncio.create_task(_run_loop(), name="inactivity-reset")
+
+
+async def stop_inactivity_reset_worker(task: asyncio.Task | None) -> None:
+    if task is None:
+        return
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task

app/core/observe.py

@@ -0,0 +1,110 @@
+"""接口指标埋点:有界事件队列 + 纯 ASGI 中间件。
+
+每个 HTTP 请求测总耗时、抓路由模板 + 状态码,非阻塞塞进有界队列;由 observe_worker
+后台批量上报到 OpenObserve。请求路径上无任何 I/O。未配置观测时中间件直接透传。
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+
+from starlette.routing import Match
+
+from app.core.config import settings
+
+# 不采集的路径(纯噪音):健康检查。
+_SKIP_PATHS = frozenset({"/health"})
+# 未匹配路由(404/扫描器)归一到此,防维度爆炸。
+_UNMATCHED = "__unmatched__"
+# service 字段:与 logging.py 同源(LOG_SERVICE_NAME),默认 app-server。
+_SERVICE = os.getenv("LOG_SERVICE_NAME", "app-server")
+
+# 有界事件队列(懒创建,见 get_queue):首次取用时在运行中的 loop 里建,避免 import 期
+# 无 loop 的边角问题;put_nowait/get_nowait 不需运行中的 loop → 可在无 loop 下测试。
+_queue: asyncio.Queue[dict] | None = None
+# 队列满时的丢弃计数,worker 定期取出打日志。
+_dropped = 0
+
+
+def get_queue() -> asyncio.Queue[dict]:
+    """返回全局有界事件队列(懒创建)。测试可 monkeypatch 模块级 _queue 换成小队列。"""
+    global _queue
+    if _queue is None:
+        _queue = asyncio.Queue(maxsize=settings.OBSERVE_QUEUE_MAX)
+    return _queue
+
+
+def take_dropped() -> int:
+    """取出并清零累计丢弃数(供 worker 打点)。"""
+    global _dropped
+    n, _dropped = _dropped, 0
+    return n
+
+
+def record_event(event: dict) -> None:
+    """非阻塞入队;队列满则丢弃当前事件并计数。永不抛异常、永不阻塞请求。"""
+    global _dropped
+    try:
+        get_queue().put_nowait(event)
+    except asyncio.QueueFull:
+        _dropped += 1
+
+
+def _resolve_route(scope) -> str:
+    """从 scope 取路由模板(如 /things/{tid})。优先 scope['route'](现代 Starlette
+    路由后写入);取不到则手动匹配一次(老版本兜底);仍无 → __unmatched__(404/扫描器)。"""
+    route = scope.get("route")
+    path = getattr(route, "path", None)
+    if path:
+        return path
+    app_ = scope.get("app")
+    router = getattr(app_, "router", None)
+    for candidate in getattr(router, "routes", []):
+        try:
+            match, _ = candidate.matches(scope)
+        except Exception:  # noqa: BLE001 - 匹配兜底,任一路由异常不影响整体
+            continue
+        if match == Match.FULL and getattr(candidate, "path", None):
+            return candidate.path
+    return _UNMATCHED
+
+
+class RequestMetricsMiddleware:
+    """纯 ASGI 中间件:测每个 http 请求耗时,记 method/route/status/duration。
+
+    放在最外层(main.py 里 CORS 之后 add),测到含 CORS 的完整耗时。未配置观测 → 透传。
+    """
+
+    def __init__(self, app) -> None:
+        self.app = app
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http" or not settings.observe_configured:
+            await self.app(scope, receive, send)
+            return
+        if scope.get("path") in _SKIP_PATHS:
+            await self.app(scope, receive, send)
+            return
+
+        start = time.perf_counter()
+        status_holder = {"status": 500}  # 下游异常未产出 response 时兜底 500
+
+        async def send_wrapper(message) -> None:
+            if message["type"] == "http.response.start":
+                status_holder["status"] = message["status"]
+            await send(message)
+
+        try:
+            await self.app(scope, receive, send_wrapper)
+        finally:
+            duration_ms = (time.perf_counter() - start) * 1000.0
+            record_event({
+                "_timestamp": int(time.time() * 1_000_000),  # µs,OpenObserve 时间列
+                "service": _SERVICE,
+                "env": settings.APP_ENV,
+                "method": scope.get("method", ""),
+                "route": _resolve_route(scope),
+                "status": status_holder["status"],
+                "duration_ms": round(duration_ms, 3),
+            })

app/core/observe_worker.py

@@ -0,0 +1,128 @@
+"""接口指标后台上报 worker:批量 drain 事件队列 → POST 到 OpenObserve。
+
+对齐 heartbeat_monitor_worker 等的 start_*/stop_* 形态。best-effort 遥测:catch 全部
+异常,上报失败直接丢批不重试。未配置观测 → start 返回 None(不启动),整套 no-op。
+"""
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+
+import httpx
+
+from app.core.config import settings
+from app.core.observe import get_queue, take_dropped
+
+logger = logging.getLogger("shagua.observe")
+
+# 上报用的 httpx client,start 时建、stop 时关。
+_client: httpx.AsyncClient | None = None
+
+
+async def _collect_batch() -> list[dict]:
+    """等到 ≥1 条(或到 flush 间隔)后,连抽到 BATCH_MAX 条或抽空。超时且空 → 返回 []。"""
+    queue = get_queue()
+    batch: list[dict] = []
+    try:
+        first = await asyncio.wait_for(
+            queue.get(), timeout=settings.OBSERVE_FLUSH_INTERVAL_SEC
+        )
+    except asyncio.TimeoutError:  # noqa: UP041 - 3.10 兼容:该版 wait_for 抛的 asyncio.TimeoutError ≠ 内置 TimeoutError
+        return batch
+    batch.append(first)
+    while len(batch) < settings.OBSERVE_BATCH_MAX:
+        try:
+            batch.append(queue.get_nowait())
+        except asyncio.QueueEmpty:
+            break
+    return batch
+
+
+async def _post_batch(client: httpx.AsyncClient, batch: list[dict]) -> None:
+    """POST 一批事件到 OpenObserve 的 _json ingest 端点。非 2xx 仅告警。"""
+    url = f"/api/{settings.OBSERVE_ORG}/{settings.OBSERVE_STREAM}/_json"
+    resp = await client.post(url, json=batch)
+    if resp.status_code >= 300:
+        logger.warning(
+            "observe ingest failed status=%s body=%s",
+            resp.status_code,
+            resp.text[:200],
+        )
+
+
+async def _run_loop(client: httpx.AsyncClient) -> None:
+    try:
+        while True:
+            batch = await _collect_batch()
+            dropped = take_dropped()
+            if dropped:
+                logger.warning("observe dropped %d events (queue full)", dropped)
+            if not batch:
+                continue
+            try:
+                await _post_batch(client, batch)
+            except Exception:  # noqa: BLE001 - best-effort 遥测,失败丢批不重试、不退出
+                logger.warning(
+                    "observe post batch failed, dropped %d events",
+                    len(batch),
+                    exc_info=True,
+                )
+    except asyncio.CancelledError:
+        logger.info("observe worker stopped")
+        raise
+
+
+def start_observe_worker() -> asyncio.Task | None:
+    """启动上报 worker。未配置观测 → 返回 None(no-op)。约定每进程只调一次(lifespan)。"""
+    global _client
+    if not settings.observe_configured:
+        return None
+    if _client is not None:
+        # 约定 start 每进程只调一次;已启动则不重复建 client(避免泄漏旧连接池)。
+        logger.warning("observe worker already started; ignoring duplicate start")
+        return None
+    _client = httpx.AsyncClient(
+        base_url=settings.OBSERVE_ENDPOINT,
+        auth=(settings.OBSERVE_USER, settings.OBSERVE_PASSWORD),
+        timeout=settings.OBSERVE_TIMEOUT_SEC,
+    )
+    logger.info(
+        "observe worker started endpoint=%s org=%s stream=%s",
+        settings.OBSERVE_ENDPOINT,
+        settings.OBSERVE_ORG,
+        settings.OBSERVE_STREAM,
+    )
+    return asyncio.create_task(_run_loop(_client), name="observe-worker")
+
+
+async def stop_observe_worker(task: asyncio.Task | None) -> None:
+    """收尾:cancel worker → best-effort 发最后一批 → 关 client。"""
+    global _client
+    if task is None:
+        return
+    task.cancel()
+    with contextlib.suppress(asyncio.CancelledError):
+        await task
+    dropped = take_dropped()  # 收口:补记最后一个 flush 窗口累计的丢弃数,不让账丢在关停期
+    if dropped:
+        logger.warning("observe dropped %d events (queue full) before shutdown", dropped)
+    if _client is not None:
+        # worker 已停,安全 drain 剩余并 best-effort 发最后一批(短超时,不卡关停);
+        # 超过一批(BATCH_MAX)的剩余直接丢,不做多轮 flush(best-effort,关停从速)。
+        try:
+            queue = get_queue()
+            final: list[dict] = []
+            while len(final) < settings.OBSERVE_BATCH_MAX:
+                try:
+                    final.append(queue.get_nowait())
+                except asyncio.QueueEmpty:
+                    break
+            if final:
+                await asyncio.wait_for(
+                    _post_batch(_client, final), timeout=settings.OBSERVE_TIMEOUT_SEC
+                )
+        except Exception:  # noqa: BLE001 - 关停期尽力而为,失败忽略
+            pass
+        await _client.aclose()
+        _client = None

app/core/ratelimit.py

@@ -9,29 +9,41 @@ from __future__ import annotations
 
 import threading
 import time
+from typing import NamedTuple
 
 from fastapi import HTTPException, Request, status
 
 from app.core.config import settings
 
-# key -> (window_start_ts, count)
-_buckets: dict[str, tuple[float, int]] = {}
+# key -> (window_start_ts, count, window_sec)
+# 存每个 key 自己的 window_sec:_buckets 混着不同窗口(60s 广告 / 3600s 登录 / 86400s 日闸)的 key,
+# GC 必须按各 key 自己的窗口判过期(见 [_purge_expired]),否则短窗口调用触发的 GC 会误删长窗口 key。
+_buckets: dict[str, tuple[float, int, float]] = {}
 _lock = threading.Lock()
+_GC_THRESHOLD = 10000  # _buckets 超此阈值才顺手清过期 key(仿 sms.py;测试可 monkeypatch 调小强制每次扫)
+
+
+def _purge_expired(now: float) -> None:
+    """清过期 key(**仅在持有 _lock 时调用**)。按每个 key 自己存的 window_sec 判过期,而非调用方的窗口
+    —— _buckets 是全局共享、混着 60s(广告)/3600s(登录)/86400s(日闸)不同窗口的 key;若用调用方窗口,
+    高频的 60s 广告端点触发 GC 时会把本该活 3600s/86400s 的登录/日闸计数一并删掉,使其在规模上(超阈值才
+    触发本清理)被反复清零而失效。仅在超阈值时扫,低频、开销可忽略。"""
+    if len(_buckets) <= _GC_THRESHOLD:
+        return
+    for k in [k for k, (s, _, w) in _buckets.items() if now - s >= w]:
+        _buckets.pop(k, None)
 
 
 def _hit(key: str, limit: int, window_sec: float) -> bool:
     """记一次访问。返回 True=放行,False=超限。"""
     now = time.monotonic()
     with _lock:
-        start, count = _buckets.get(key, (now, 0))
+        start, count, _ = _buckets.get(key, (now, 0, window_sec))
         if now - start >= window_sec:  # 窗口过期,重置
             start, count = now, 0
         count += 1
-        _buckets[key] = (start, count)
-        # 顺手清理过期 key,防内存无限涨(低频访问足够)
-        if len(_buckets) > 10000:
-            for k in [k for k, (s, _) in _buckets.items() if now - s >= window_sec]:
-                _buckets.pop(k, None)
+        _buckets[key] = (start, count, window_sec)
+        _purge_expired(now)  # 顺手清过期 key(按各自窗口),防内存无限涨
     return count <= limit
 
 
@@ -83,3 +95,76 @@ def enforce_rate_limit(
             status_code=status.HTTP_429_TOO_MANY_REQUESTS,
             detail=detail,
         )
+
+
+# ===================== 先判 / 后记(只按「成功」计数)=====================
+# _hit 是原子「判+记」:一调用就 +1,适合登录爆破(失败尝试也要计)。但对「短信发码」这类
+# **只想给成功动作计数**的场景不合适 —— 被单号冷却挡下的重发没真发、没烧钱,不该占额度。
+# 故拆成 _peek(只判不记)+ _commit(只记):check_rate_limits 先判 → 动作 → 成功后 record。
+
+
+class RateLimitRule(NamedTuple):
+    """一条限流规则。scope 区分不同闸(不同 key 前缀);同一 (subject, IP) 在 window_sec
+    内最多 limit 次,超限抛 429 用 detail 文案。
+
+    (scope, window_sec) 成对绑在一条规则里 —— check(先判)与 record(计数)复用同一条,
+    避免两处把窗口/scope 写歪导致 key 对不上。
+    """
+
+    scope: str
+    limit: int
+    window_sec: float
+    detail: str = "操作过于频繁,请稍后再试"
+
+
+def _peek(key: str, limit: int, window_sec: float) -> bool:
+    """只读:当前窗口内是否还没到上限(count < limit)。**不改计数**。
+    与 [_commit] 配对实现「先判后记」——只在动作成功后才 _commit。"""
+    now = time.monotonic()
+    with _lock:
+        start, count, _ = _buckets.get(key, (now, 0, window_sec))
+        if now - start >= window_sec:  # 窗口已过期 → 视作已重置(count 归零)
+            count = 0
+    return count < limit
+
+
+def _commit(key: str, window_sec: float) -> None:
+    """记一次访问(+1)。窗口过期则以本次为起点重置。仅在动作成功后调用。"""
+    now = time.monotonic()
+    with _lock:
+        start, count, _ = _buckets.get(key, (now, 0, window_sec))
+        if now - start >= window_sec:  # 窗口过期,重置
+            start, count = now, 0
+        _buckets[key] = (start, count + 1, window_sec)
+        _purge_expired(now)  # 顺手清过期 key(按各自窗口,同 [_hit])
+
+
+def check_rate_limits(request: Request, subject: str, rules: list[RateLimitRule]) -> None:
+    """【先判】一组限流:任一规则已达上限即抛 429,且**不改计数**。
+
+    配合 [record_rate_limits] 实现「只按成功计数」:先 check 所有闸(全未超才继续)→ 执行动作
+    → 动作**成功后**再 record。动作被下游挡下(如短信单号冷却)、没真正发生时不 record → 不占额度。
+    key = `scope:subject:client_ip`(与 [enforce_rate_limit] 同款)。
+    """
+    if not settings.RATE_LIMIT_ENABLED:
+        return
+    ip = _client_ip(request)
+    for rule in rules:
+        if not _peek(f"{rule.scope}:{subject}:{ip}", rule.limit, rule.window_sec):
+            raise HTTPException(
+                status_code=status.HTTP_429_TOO_MANY_REQUESTS,
+                detail=rule.detail,
+            )
+
+
+def record_rate_limits(request: Request, subject: str, rules: list[RateLimitRule]) -> None:
+    """【记一次】一组限流(每条规则 +1)。仅在动作成功后调用,与 [check_rate_limits] 配对。
+
+    ⚠️ check→动作→record 非原子:并发突发下计数可能略超 limit(每个在途请求各 +1)。对
+    「防脚本/防轰炸」的安全网定位可接受;要精确配额需迁 Redis(见模块 docstring)。
+    """
+    if not settings.RATE_LIMIT_ENABLED:
+        return
+    ip = _client_ip(request)
+    for rule in rules:
+        _commit(f"{rule.scope}:{subject}:{ip}", rule.window_sec)

app/core/rewards.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 from datetime import date, datetime, timedelta, timezone
+from typing import NamedTuple
 
 # 业务时区:签到的"今天"按北京时间算,不能用 UTC。
 # 否则 UTC+8 的凌晨 0~8 点会被算成 UTC 的前一天,导致签到日期错位。
@@ -52,6 +53,30 @@ WITHDRAW_MIN_CENTS: int = 10
 WITHDRAW_MAX_CENTS: int = 5_000_000  # 5 万元
 
 
+# ===== 提现档位(福利页 coin_cash;7-9 对齐原型 withdrawal.html)=====
+# 后端是档位唯一真相源:withdraw-info 按此下发,create_withdraw 按此校验(防绕过客户端刷)。
+# 规则(2026-07-09 拍板):
+#   - 新人档(is_newbie):账号历史一次性,"发起就算用过"(任意状态含被拒),用过即不再下发;
+#     0.1 与 0.3 各自独立同天可各提一次,且不参与常规档"每日选一个额度"互斥。
+#   - 常规档:按北京日计次(0.5×3 / 10×1 / 20×1),三档每天只能选一个。
+# invite_cash(邀请页)本轮无档位概念,不在此表。改档位=改这里发版。
+class WithdrawTier(NamedTuple):
+    amount_cents: int
+    label: str          # 客户端档位方块展示文案
+    badge: str | None   # 角标文案;None=无角标
+    daily_limit: int    # 每日次数上限(新人档的"历史一次性"另由 is_newbie 判定)
+    is_newbie: bool
+
+
+WITHDRAW_TIERS_COIN_CASH: tuple[WithdrawTier, ...] = (
+    WithdrawTier(10, "0.1", "新人福利", 1, True),
+    WithdrawTier(30, "0.3", "新人福利", 1, True),
+    WithdrawTier(50, "0.5", None, 3, False),
+    WithdrawTier(1000, "10", None, 1, False),
+    WithdrawTier(2000, "20", None, 1, False),
+)
+
+
 # ===== 一次性任务(领一次,user_task 去重)=====
 TASK_ENABLE_NOTIFICATION = "enable_notification"
 
@@ -214,8 +239,8 @@ def calculate_ad_reward_coin(ecpm: str | int | float | None, count_after_this: i
     return max(0, round(yuan * COIN_PER_YUAN))
 
 
-# 签到看广告膨胀:S2S 固定补发(原型 2026-06 由 2000 提到 3000,对应 CTA「看广告最高膨胀至3000金币」)。
-SIGNIN_BOOST_COIN: int = 3000
+# 签到膨胀(SIGNIN_BOOST_COIN,固定 3000)已于 2026-07 下线:它与广告实际收益脱钩,产品确认
+# 非设计内口径。签到弹窗的「看广告膨胀」现与福利页看视频同走 calculate_ad_reward_coin。
 
 
 # ===== 看激励视频发金币(穿山甲 S2S 服务端回调发奖)=====
@@ -309,5 +334,3 @@ def get_ad_cooldown_sec(db) -> int:  # noqa: ANN001
     return int(_cfg(db, "ad_cooldown_sec"))
 
 
-def get_signin_boost_coin(db) -> int:  # noqa: ANN001
-    return int(_cfg(db, "signin_boost_coin"))

app/core/security.py

@@ -87,6 +87,91 @@ def issue_token_pair(user_id: int) -> dict[str, Any]:
     }
 
 
+def create_bind_ticket(
+    *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None
+) -> str:
+    """微信登录未命中 openid 时,签发短时"待绑手机"令牌,承载 openid + 微信昵称头像。
+
+    typ='wechat_bind'、sub=openid;有效期 settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES 分钟。
+    与 access/refresh 用同一 JWT_SECRET_KEY 签名,靠 typ 区分,decode_bind_ticket 校验 typ。
+    """
+    now = _now()
+    expire = now + timedelta(minutes=settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES)
+    payload: dict[str, Any] = {
+        "sub": openid,
+        "typ": "wechat_bind",
+        "wnk": wechat_nickname,
+        "wav": wechat_avatar_url,
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+    }
+    return jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_bind_ticket(token: str) -> dict[str, Any]:
+    """解析"待绑手机"令牌,校验签名/过期/类型。失败抛 TokenError。
+
+    返回 {'openid': str, 'wnk': str|None, 'wav': str|None}。
+    """
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+    except jwt.ExpiredSignatureError as e:
+        raise TokenError("bind ticket expired") from e
+    except jwt.InvalidTokenError as e:
+        raise TokenError(f"invalid bind ticket: {e}") from e
+    if payload.get("typ") != "wechat_bind":
+        raise TokenError(f"wrong token type: want=wechat_bind got={payload.get('typ')}")
+    if "sub" not in payload:
+        raise TokenError("bind ticket missing sub")
+    return {"openid": payload["sub"], "wnk": payload.get("wnk"), "wav": payload.get("wav")}
+
+
+def create_conflict_ticket(
+    *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None, phone: str
+) -> str:
+    """手机号占用时签发的短时"冲突处理"令牌。
+
+    比 bind_ticket 多编码 **已验证的手机号 phone** —— 换绑/继续绑定只认它,证明"这对
+    openid/手机号刚在绑号时验证通过",免用户重输验证码,又堵住"拿自己 openid + 任意手机号
+    去夺号"的接管漏洞。typ='wechat_conflict';有效期复用 WECHAT_BIND_TICKET_EXPIRE_MINUTES。
+    """
+    now = _now()
+    expire = now + timedelta(minutes=settings.WECHAT_BIND_TICKET_EXPIRE_MINUTES)
+    payload: dict[str, Any] = {
+        "sub": openid,
+        "typ": "wechat_conflict",
+        "wnk": wechat_nickname,
+        "wav": wechat_avatar_url,
+        "phn": phone,
+        "iat": int(now.timestamp()),
+        "exp": int(expire.timestamp()),
+    }
+    return jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm=settings.JWT_ALGORITHM)
+
+
+def decode_conflict_ticket(token: str) -> dict[str, Any]:
+    """解析"冲突处理"令牌,校验签名/过期/类型。失败抛 TokenError。
+
+    返回 {'openid': str, 'wnk': str|None, 'wav': str|None, 'phone': str}。
+    """
+    try:
+        payload = jwt.decode(token, settings.JWT_SECRET_KEY, algorithms=[settings.JWT_ALGORITHM])
+    except jwt.ExpiredSignatureError as e:
+        raise TokenError("conflict ticket expired") from e
+    except jwt.InvalidTokenError as e:
+        raise TokenError(f"invalid conflict ticket: {e}") from e
+    if payload.get("typ") != "wechat_conflict":
+        raise TokenError(f"wrong token type: want=wechat_conflict got={payload.get('typ')}")
+    if "sub" not in payload or "phn" not in payload:
+        raise TokenError("conflict ticket missing sub/phn")
+    return {
+        "openid": payload["sub"],
+        "wnk": payload.get("wnk"),
+        "wav": payload.get("wav"),
+        "phone": payload["phn"],
+    }
+
+
 # ===================== 密码 hash(admin 后台账号用)=====================
 # 用户侧是手机号+验证码登录,不存密码;仅 admin 账号用 username+password 登录。
 

app/integrations/notifier.py

@@ -0,0 +1,43 @@
+"""不活跃预警通知器(可插拔)。
+
+v1 仅日志占位(LogNotifier):现状无真实推送能力(极光只用于一键登录解密 + 设备心跳告警,
+心跳 worker 也只打印),先把清零主流程 + 审计做扎实。后续实现同协议的 JPushNotifier /
+SmsNotifier 即可替换,worker/repo 不改。
+"""
+from __future__ import annotations
+
+import logging
+from typing import Protocol
+
+logger = logging.getLogger("shagua.inactivity")
+
+
+class InactivityNotifier(Protocol):
+    channel: str
+
+    def warn(self, *, user_id: int, coin: int, cash_cents: int,
+             stage: int, days_until_reset: int) -> str:
+        """发预警(只涉及会被清的金币 + 折算现金;邀请现金不清、不预警)。
+        返回状态:'sent' / 'failed' / 'placeholder'。"""
+        ...
+
+
+class LogNotifier:
+    """占位实现:只打印,不真推。参照 heartbeat_monitor_worker「本期先不接推送」先例。"""
+
+    channel = "log"
+
+    def warn(self, *, user_id: int, coin: int, cash_cents: int,
+             stage: int, days_until_reset: int) -> str:
+        logger.warning(
+            "[inactivity-warn] user=%s coin=%s cash_cents=%s stage=T-%s days_until_reset=%s",
+            user_id, coin, cash_cents, stage, days_until_reset,
+        )
+        return "placeholder"
+
+
+def get_notifier(channel: str) -> InactivityNotifier:
+    """按配置返回通知器。未实现的通道(jpush/sms)暂回退 LogNotifier 占位。"""
+    # 后续:if channel == "jpush": return JPushNotifier()
+    #       if channel == "sms":   return SmsNotifier()
+    return LogNotifier()

app/integrations/sms.py

@@ -13,7 +13,8 @@ worker / 多机时内存不共享 → 冷却、校验都会失效,届时迁移
 
 防刷两层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
   1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
-  2. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
+  2. 单设备(device_id)+ IP 每小时 / 每天频控(api 层 auth.sms_send 的 check/record_rate_limits,
+     **只按成功发码计数** —— 被本文件单号冷却挡下的重发不占额度)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
      ⚠️ 原「单 IP 频控(rate_limit 依赖)」2026-06-26 按产品要求删除、改设备维度;但 device_id 客户端可伪造/轮换,
         脚本轮换 id 能绕过本层 → 挡脚本狂发主要靠极光控制台侧(+ 可选 nginx 限流)。
      ⚠️ 原「单号每日上限」2026-07-03 按精简要求删除(mentor 定:登录风控只留单号冷却 + 单设备频控);

app/main.py

@@ -49,7 +49,16 @@ from app.core.heartbeat_monitor_worker import (
     start_heartbeat_monitor,
     stop_heartbeat_monitor,
 )
+from app.core.inactivity_reset_worker import (
+    start_inactivity_reset_worker,
+    stop_inactivity_reset_worker,
+)
 from app.core.logging import setup_logging
+from app.core.observe import RequestMetricsMiddleware
+from app.core.observe_worker import (
+    start_observe_worker,
+    stop_observe_worker,
+)
 from app.core.pricebot_client import aclose_pricebot_client, get_pricebot_client
 from app.core.withdraw_reconcile_worker import (
     start_withdraw_reconcile_worker,
@@ -71,15 +80,25 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
         settings.DATABASE_URL.split("://", 1)[0],
     )
     get_pricebot_client()  # 预热透传 client:把建 SSL 上下文的一次性成本付在启动,首个领券请求即热
+    try:
+        # 预热离线地理库:首次加载 ~2.5M 行 CSV + 建 KDTree,摊到启动、不砸首个按城市过滤的请求
+        from app.utils import geo
+        geo.ensure_loaded()
+    except Exception:  # noqa: BLE001
+        logger.exception("reverse_geocoder 预热失败(城市反查将在首个请求时懒加载)")
     reconcile_task = start_withdraw_reconcile_worker()
     heartbeat_task = start_heartbeat_monitor()
     daily_exchange_task = start_daily_exchange_worker()
+    observe_task = start_observe_worker()
+    inactivity_task = start_inactivity_reset_worker()
     try:
         yield
     finally:
         await stop_heartbeat_monitor(heartbeat_task)
         await stop_withdraw_reconcile_worker(reconcile_task)
         await stop_daily_exchange_worker(daily_exchange_task)
+        await stop_observe_worker(observe_task)
+        await stop_inactivity_reset_worker(inactivity_task)
         await aclose_pricebot_client()
         logger.info("shutting down")
 
@@ -101,6 +120,9 @@ if settings.cors_origins_list:
         allow_headers=["*"],
     )
 
+# 接口指标埋点(放在 CORS 之后 = 最外层:测到含 CORS 的完整耗时)。未配置观测时中间件自 no-op。
+app.add_middleware(RequestMetricsMiddleware)
+
 
 @app.get("/health", tags=["meta"])
 def health() -> dict[str, str]:

app/models/__init__.py

@@ -5,7 +5,12 @@ from app.models.ad_pangle_revenue import AdPangleDailyRevenue  # noqa: F401
 from app.models.ad_reward import AdRewardRecord  # noqa: F401
 from app.models.ad_watch_log import AdWatchLog  # noqa: F401
 from app.models.admin import AdminAuditLog, AdminUser  # noqa: F401
+from app.models.admin_role import AdminRole  # noqa: F401
 from app.models.analytics_event import AnalyticsEvent  # noqa: F401
+from app.models.analytics_selfstat import (  # noqa: F401
+    AnalyticsSelfStat,
+    AnalyticsSelfStatEvent,
+)
 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
@@ -22,17 +27,22 @@ from app.models.coupon_state import (  # noqa: F401
     CouponSession,
 )
 from app.models.feedback import Feedback  # noqa: F401
+from app.models.inactivity import (  # noqa: F401
+    InactivityNotificationLog,
+    InactivityResetLog,
+)
 from app.models.invite import InviteRelation  # noqa: F401
 from app.models.invite_fingerprint import InviteFingerprint  # noqa: F401
 from app.models.launch_confirm_sample import LaunchConfirmSample  # noqa: F401
 from app.models.meituan_coupon import MeituanCoupon  # noqa: F401
 from app.models.onboarding import OnboardingCompletion  # noqa: F401
+from app.models.phone_rebind_log import PhoneRebindLog  # noqa: F401
 from app.models.ops_marquee_seed import OpsMarqueeSeed  # noqa: F401
 from app.models.ops_stat_config import OpsStatConfig  # noqa: F401
 from app.models.price_observation import PriceObservation  # noqa: F401
 from app.models.price_report import PriceReport  # noqa: F401
 from app.models.savings import SavingsRecord  # noqa: F401
-from app.models.signin import SigninBoostRecord, SigninRecord  # noqa: F401
+from app.models.signin import SigninRecord  # noqa: F401
 from app.models.store_mapping import StoreMapping  # noqa: F401
 from app.models.task import UserTask  # noqa: F401
 from app.models.user import User  # noqa: F401

app/models/ad_ecpm.py

@@ -32,6 +32,9 @@ class AdEcpmRecord(Base):
     # 点位场景:comparison(比价) / coupon(领券) / welfare(福利),供收益报表区分比价/领券 Draw 收益;
     # 仅信息流/Draw 上报(比价与领券共用同一代码位,只能客户端各调用点显式打标),激励视频为 NULL。
     feed_scene: Mapped[str | None] = mapped_column(String(16), nullable=True)
+    # 本次比价/领券 trace_id(信息流场景客户端带上):把这条展示收益归属到对应比价/领券记录。
+    # 领券数据 / 比价记录看板按 trace_id 聚合"本次广告收益"。激励视频/福利/旧客户端 = NULL。
+    trace_id: Mapped[str | None] = mapped_column(String(64), index=True, 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_reward.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import DateTime, ForeignKey, Integer, String, func
+from sqlalchemy import DateTime, ForeignKey, Index, Integer, String, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -16,6 +16,10 @@ from app.db.base import Base
 
 class AdRewardRecord(Base):
     __tablename__ = "ad_reward_record"
+    __table_args__ = (
+        # 「本轮膨胀累计发了多少」= SUM(coin) WHERE user_id=? AND boost_round_id=? AND status='granted'
+        Index("ix_ad_reward_user_boost_round", "user_id", "boost_round_id"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
     # 穿山甲交易号,幂等键(同号回调不重复发奖)
@@ -31,6 +35,10 @@ class AdRewardRecord(Base):
     reward_scene: Mapped[str] = mapped_column(String(32), nullable=False, default="reward_video")
     # 客户端生成并通过 extra 透传的广告会话 id
     ad_session_id: Mapped[str | None] = mapped_column(String(64), index=True, nullable=True)
+    # 客户端生成并通过 extra 透传的「膨胀轮」id:一轮 = 用户点「去膨胀」到点「放弃赚钱」之间连看的
+    # 若干条广告。纯标签,不影响发多少/发不发,只用于把同一轮的发奖记录求和成弹窗要显示的累计值。
+    # 轮次边界完全由客户端定(它才知道用户点了放弃);老客户端/extra 丢失时为 NULL → 累计值返 null。
+    boost_round_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
     # 本次发奖采用的 eCPM 原始值(回调自带或按 ad_session_id 匹配的客户端上报)
     ecpm_raw: Mapped[str | None] = mapped_column(String(32), nullable=True)
     # 来源(广告收益报表用):我们的应用环境 prod/test + 我们配置的代码位 104xxx。

app/models/admin.py

@@ -25,8 +25,14 @@ class AdminUser(Base):
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
     username: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
     password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
-    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)
+    # 明文登录密码:仅「后台 UI 创建/重置」的管理员留存,供超管在权限管理页复看转交。
+    # 脚本/起后台时建的超管账号不写(为 None → 前端「不显示密码」)。⚠️ 内部工具便利取舍,见 create/list。
+    plain_password: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)/ custom(按人自定义)
     role: Mapped[str] = mapped_column(String(20), nullable=False, default="operator")
+    # 「自定义」权限:仅当 role == "custom" 时有效,存这个人专属的可见页 key 列表(不共享给他人)。
+    # 非 custom 用户为 None → 可见页跟随角色。登录/`/me` 下发有效页时,非空即优先用它(见 auth._admin_out_with_pages)。
+    pages_override: Mapped[list | None] = mapped_column(_JSON, nullable=True)
     # active / disabled
     status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")
 

app/models/admin_role.py

@@ -0,0 +1,42 @@
+"""admin 角色 → 可见页面(权限)映射表。
+
+RBAC 的「角色」侧:每个角色持有一组「页面 key」(= 左侧导航项),决定该角色登录后台后左边能看到
+哪些页。super_admin 是内建全权角色(is_builtin=True),恒可见全部页(effective_pages 里特判,
+不依赖本表存的 pages)、不可编辑/删除。其余角色(含 operator/finance)可由 super_admin 增删改。
+
+admin_user.role 存的是本表的 name(字符串弱引用,不建外键——与既有 require_role 字符串口径一致;
+删除在用角色由业务层拦截,见 routers/roles.py)。页面 key 清单见 app/admin/permissions.py。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import JSON, Boolean, DateTime, Integer, String, func
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+_JSON = JSON().with_variant(JSONB(), "postgresql")
+
+
+class AdminRole(Base):
+    __tablename__ = "admin_role"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 角色标识 key(不可变,承重):admin_user.role 引用它、require_role 按它鉴权。
+    # 内建 = super_admin/operator/finance/tech(英文,勿改);自定义 = 创建时的名称。
+    name: Mapped[str] = mapped_column(String(32), unique=True, index=True, nullable=False)
+    # 展示名(可改):内建 = 管理员/运营/财务/技术;自定义默认 = name。UI 一律展示 label。
+    label: Mapped[str] = mapped_column(String(32), nullable=False, default="")
+    # 该角色可见页面 key 列表(= 左侧导航项),见 app/admin/permissions.py 的 PERMISSION_CATALOG
+    pages: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
+    # 内建角色(当前仅 super_admin):不可编辑/删除,恒全权
+    is_builtin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
+
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), nullable=False
+    )
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AdminRole name={self.name} pages={len(self.pages)} builtin={self.is_builtin}>"

app/models/analytics_event.py

@@ -15,7 +15,7 @@ from __future__ import annotations
 
 from datetime import datetime
 
-from sqlalchemy import JSON, BigInteger, DateTime, Integer, String, func
+from sqlalchemy import JSON, BigInteger, DateTime, Index, Integer, String, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -23,6 +23,13 @@ from app.db.base import Base
 
 class AnalyticsEvent(Base):
     __tablename__ = "analytics_event"
+    __table_args__ = (
+        # 活跃口径聚合热点(activity.active_event_condition + last_active_subqueries):
+        # 按 event IN (home_visible∪比价∪领券) 过滤,再 group by user_id 取 max(created_at)。
+        # 覆盖索引 → 该聚合走 index-only。注:page 列是早期 show+home 组合的遗留,现不再按 page
+        # 过滤(索引靠 event 前缀仍生效);后续可新迁移瘦成 (event,user_id,created_at)。
+        Index("ix_analytics_event_active", "event", "page", "user_id", "created_at"),
+    )
 
     id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
 

app/models/analytics_selfstat.py

@@ -0,0 +1,59 @@
+"""埋点/上报成功率自报计数快照表(append-only)。
+
+客户端周期上报「自 epoch 起算的累计计数」;服务端只存原始快照,查询时在 Python 侧差分聚合
+(见 app/admin/repositories/analytics_health.py)。与既有 analytics_event 表完全独立。
+
+- analytics_selfstat        :一快照一行(快照头 + 设备维度 + 设备级诊断量)
+- analytics_selfstat_event  :一 event 一行(四类累计计数),外键指向快照头
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import BigInteger, DateTime, ForeignKey, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class AnalyticsSelfStat(Base):
+    __tablename__ = "analytics_selfstat"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    device_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    epoch_id: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    # 设备维度(每设备固定,下钻用)
+    app_ver: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    oem: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    os: Mapped[str | None] = mapped_column(String(32), nullable=True)
+    # 设备级诊断量(累计;queue_depth 是瞬时 gauge)
+    batches_attempted: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    batches_ok: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    batches_fail: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    retries: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    queue_depth: Mapped[int] = mapped_column(Integer, nullable=False, default=0)
+    sent_at: Mapped[int | None] = mapped_column(BigInteger, nullable=True)  # 端上报时刻 epoch ms
+    # 服务端接收时间(权威,用于时间分桶与分区排序)
+    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"<AnalyticsSelfStat id={self.id} device={self.device_id} epoch={self.epoch_id}>"
+
+
+class AnalyticsSelfStatEvent(Base):
+    __tablename__ = "analytics_selfstat_event"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    snapshot_id: Mapped[int] = mapped_column(
+        ForeignKey("analytics_selfstat.id"), index=True, nullable=False
+    )
+    event: Mapped[str] = mapped_column(String(64), index=True, nullable=False)
+    attempted: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    drop_capture: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    delivered: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+    drop_undelivered: Mapped[int] = mapped_column(BigInteger, nullable=False, default=0)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<AnalyticsSelfStatEvent snap={self.snapshot_id} event={self.event}>"

app/models/comparison.py

@@ -86,6 +86,10 @@ class ComparisonRecord(Base):
 
     # ===== 订单概要 =====
     store_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 下单商品名拼接串(顿号分隔,从 items[].name 去重派生),供 admin 列表「商品」列展示 + 商品名搜索。
+    # items 是 JSON(SQLite 下 json.dumps ensure_ascii 把中文转义,无法直接 CAST+LIKE),故另派生成普通
+    # 文本列——跨库 LIKE 一致、可加索引。写路径(upsert_record / harvest_done)落库时同步派生。
+    product_names: Mapped[str | None] = mapped_column(String(512), nullable=True)
     total_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
     skipped_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
 
@@ -133,6 +137,12 @@ class ComparisonRecord(Base):
     # 每次 LLM 调用明细 [{scene,model,input_messages,output,usage,latency_ms,error}];
     # server 收上报后按 trace_id 同机拉 pricebot 落库(见 compare_record 端点)。旧记录/未采集为 None。
     llm_calls: Mapped[list | None] = mapped_column(_JSON, nullable=True)
+    # 本次比价 LLM 总成本(元):回填时按「当时的价」逐模型算好冻结(见 services/llm_cost.py)。
+    # 单次亚分级 → float「元」(不用 *_cents)。旧记录/未回填为 None,前端回退「估算成本」。
+    llm_cost_yuan: Mapped[float | None] = mapped_column(Float, nullable=True)
+    # 算成本所用单价快照 {mode, prices:{model:{input_per_1m,output_per_1m,_source}}}:app_config 只存
+    # 当前价、不留历史,故把当时价冻结进来供审计/复算。
+    llm_price_snapshot: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
 
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), server_default=func.now(), index=True, nullable=False

app/models/coupon_state.py

@@ -66,6 +66,9 @@ class CouponClaimRecord(Base):
 
     # success / already_claimed / failed / skipped(原样取 pricebot coupon 结果)
     status: Mapped[str] = mapped_column(String(24), nullable=False)
+    # 领券所属 session 的环境 prod/dev(/step 按 trace_id 查 coupon_session.app_env 打标)。
+    # 旧行 NULL(不回填)。admin「按券成功率」表据此过滤环境。见设计 §13。
+    app_env: Mapped[str | None] = mapped_column(String(16), index=True, nullable=True)
     vendor: Mapped[str | None] = mapped_column(String(48), nullable=True)
     coupon_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
     # 这张领到几张(pricebot display_count;给不出时为 None)
@@ -240,6 +243,10 @@ class CouponSession(Base):
     platform_elapsed: Mapped[dict | None] = mapped_column(_JSON, nullable=True)
     # 领到总张数(收尾帧带)。
     claimed_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 本次 session 至少领到一张(status∈{success,already_claimed})的平台 id 列表,如 ["meituan-waimai","jd-waimai"]。
+    # admin「领券数据」据此算整单成功率(②)/点位成功率(③);服务端 /step 逐帧按 trace_id 并集写入
+    # (见 coupon_state.merge_session_platform_success)。旧行=NULL → 视作空集。
+    platform_success: Mapped[list | None] = mapped_column(_JSON, nullable=True)
     # pricebot done 帧回传的公网调试链接(price.shaguabijia.com/traces/{dir});含落盘时分秒、拼不出,只能存
     # (同 ComparisonRecord.trace_url)。admin「领券数据」明细据此渲染可点 trace 链接;未到 done(failed/abandoned)为空。
     trace_url: Mapped[str | None] = mapped_column(String(512), nullable=True)

app/models/inactivity.py

@@ -0,0 +1,58 @@
+"""15 天不活跃清零相关表。
+
+- inactivity_reset_log:每次清零一行,记清零前三桶余额快照 + 原因 + 判定时活跃时间/不活跃天数,
+  供纠纷排查(需求①)。清零同时另写 2 条钱包流水(金币 + 折算现金,biz_type=inactivity_reset),
+  资金流可逐笔回溯。**邀请现金是产品红线、不清零**,invite_cash_balance_cents_before 仅为清零时
+  仍保留的邀请现金快照(便于排查、非被清金额;见 wallet.CoinAccount 注释)。
+- inactivity_notification_log:每次预警一行,记推送时余额快照 + 档位 + 通道 + 状态,
+  兼作"预警去重"依据(created_at > last_active)与"待推送"占位 outbox(v1 通道=log)。
+
+append-only,不更新。user_id 只索引、不设外键(同 analytics_event,避免删用户级联/历史留痕)。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class InactivityResetLog(Base):
+    __tablename__ = "inactivity_reset_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
+    coin_balance_before: Mapped[int] = mapped_column(Integer, nullable=False)
+    cash_balance_cents_before: Mapped[int] = mapped_column(Integer, nullable=False)
+    invite_cash_balance_cents_before: Mapped[int] = mapped_column(Integer, nullable=False)
+    last_active_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    inactive_days: Mapped[int] = mapped_column(Integer, nullable=False)
+    reason: Mapped[str] = mapped_column(String(32), nullable=False)
+    reset_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"<InactivityResetLog id={self.id} user_id={self.user_id} coin={self.coin_balance_before}>"
+
+
+class InactivityNotificationLog(Base):
+    __tablename__ = "inactivity_notification_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    user_id: Mapped[int] = mapped_column(Integer, index=True, nullable=False)
+    stage: Mapped[int] = mapped_column(Integer, nullable=False)      # 提前天数档(如 7 / 2)
+    inactive_days: Mapped[int] = mapped_column(Integer, nullable=False)
+    coin_balance: Mapped[int] = mapped_column(Integer, nullable=False)
+    cash_balance_cents: Mapped[int] = mapped_column(Integer, nullable=False)
+    invite_cash_balance_cents: Mapped[int] = mapped_column(Integer, nullable=False)
+    channel: Mapped[str] = mapped_column(String(16), nullable=False)   # log / jpush / sms
+    status: Mapped[str] = mapped_column(String(16), nullable=False)    # placeholder / sent / failed
+    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"<InactivityNotificationLog id={self.id} user_id={self.user_id} stage={self.stage}>"

app/models/phone_rebind_log.py

@@ -0,0 +1,31 @@
+"""手机号换绑台账。
+
+记录"手机号从老账号被夺走、重建为新账号(X 注销 → Y)"这一破坏性事件,支撑"一个手机号
+30 天内最多换绑一次"的限制。手机号级、渠道无关(source 标来源);普通微信绑定不写此表。
+见 M2 spec §4.1。
+"""
+from __future__ import annotations
+
+from datetime import datetime
+
+from sqlalchemy import DateTime, Integer, String, func
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class PhoneRebindLog(Base):
+    __tablename__ = "phone_rebind_log"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    # 被换绑的真实手机号(注意:存真实号,不是老账号被腾号后的 deleted_<id>)
+    phone: Mapped[str] = mapped_column(String(20), index=True, nullable=False)
+    # 被注销的老账号 X;P 换绑时已被腾空(极边界)则为空
+    old_user_id: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    # 换绑后新建的账号 Y
+    new_user_id: Mapped[int] = mapped_column(Integer, nullable=False)
+    # 换绑来源。手机号级配额、渠道无关,留字段给未来其他换绑路径共用同一份 30 天限制。
+    source: Mapped[str] = mapped_column(String(32), nullable=False, default="wechat_conflict")
+    rebound_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), index=True, nullable=False
+    )

app/models/signin.py

@@ -1,6 +1,10 @@
 """签到记录表。
 
 每次签到一行,(user_id, signin_date) 唯一,天然防一天签两次。
+
+2026-07 下线 `signin_boost_record`(签到膨胀):膨胀按固定 3000 金币补发、与广告实际收益
+脱钩,产品确认非设计内口径。签到弹窗的「看广告膨胀」改走 reward_video(按 eCPM 发,记在
+`ad_reward_record`)。历史发币流水 `coin_transaction.biz_type='signin_boost'` 保留不动。
   - cycle_day: 1..7,7 天循环里今天落在第几档,决定发多少金币;断签后重置回 1
               (周期长度 = rewards.SIGNIN_CYCLE_LEN,2026-06 由 14 天改 7 天一轮)。
   - streak:   连续签到天数(不封顶),用于"已连续签到 N 天"展示;断签后重置回 1。
@@ -9,7 +13,7 @@ from __future__ import annotations
 
 from datetime import date, datetime
 
-from sqlalchemy import Date, DateTime, ForeignKey, Integer, String, UniqueConstraint, func
+from sqlalchemy import Date, DateTime, ForeignKey, Integer, UniqueConstraint, func
 from sqlalchemy.orm import Mapped, mapped_column
 
 from app.db.base import Base
@@ -42,29 +46,3 @@ class SigninRecord(Base):
         )
 
 
-class SigninBoostRecord(Base):
-    """签到后看广告膨胀记录。
-
-    一天最多膨胀一次,补发金额等于当天签到原始奖励。独立表用于防并发重复补发,
-    后续接入真实 S2S 广告 session 时可把 ad_ref_id 回填为广告会话/交易号。
-    """
-
-    __tablename__ = "signin_boost_record"
-    __table_args__ = (
-        UniqueConstraint("user_id", "signin_date", name="uq_signin_boost_user_date"),
-    )
-
-    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
-    )
-    signin_date: Mapped[date] = mapped_column(Date, nullable=False)
-    coin_awarded: Mapped[int] = mapped_column(Integer, nullable=False)
-    ad_ref_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
-
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=func.now(), nullable=False
-    )
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return f"<SigninBoostRecord user_id={self.user_id} date={self.signin_date} coin={self.coin_awarded}>"

app/repositories/activity.py

@@ -0,0 +1,95 @@
+"""活跃口径唯一真源:worker(不活跃清零)与 admin(最近活跃/DAU)共用,防两处漂移。
+
+口径 = max(User.created_at, AnalyticsEvent[首页可见 home_visible + 比价 + 领券], CouponPromptEngagement[claim_started])。
+**不含 last_login_at**(登录/re-login 不代表在用 App);created_at 为恒非空基线。
+清零/预警按北京自然日 0 点对齐(见 reset_cutoff)。
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.core.rewards import CN_TZ, cn_today
+from app.models.analytics_event import AnalyticsEvent
+from app.models.coupon_state import CouponPromptEngagement
+
+# —— 活跃口径事件(与"用户管理"口径一致)——
+# 首页可见:前端埋点确认 event=home_visible(首页进入可视区时触发,单一 event 名即可判定)。
+HOME_VISIBLE_EVENT = "home_visible"
+COMPARE_START_EVENT = "real_compare_start"   # 发起比价(含浮窗触发)
+COUPON_START_EVENT = "real_coupon_start"     # 发起领券
+ACTIVE_EVENTS = (HOME_VISIBLE_EVENT, COMPARE_START_EVENT, COUPON_START_EVENT)
+ACTIVE_ENGAGE_TYPE = "claim_started"         # coupon_prompt_engagement 一键领取
+
+
+def active_event_condition():
+    """analytics_event 中算"活跃"的行为过滤:首页可见(event=home_visible)
+    ∪ 发起比价 ∪ 发起领券。worker 子查询与 admin 展示共用,单一真源。"""
+    return AnalyticsEvent.event.in_(ACTIVE_EVENTS)
+
+
+def as_utc(value: datetime) -> datetime:
+    """任意 datetime → tz-aware UTC(无时区按 UTC 解释)。用于与 DateTime(timezone=True) 列比较,
+    比较绝对时刻、与会话时区无关(口径同 admin queries._as_utc)。"""
+    if value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value.astimezone(timezone.utc)
+
+
+def norm_utc(dt: datetime | None) -> datetime | None:
+    """naive 视为 UTC 补 tzinfo(SQLite 读回 naive、PG 读回 aware,混着 max() 会 TypeError)。"""
+    if dt is None:
+        return None
+    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
+
+
+def cn_midnight_utc(d: date) -> datetime:
+    """北京 d 日 00:00 → tz-aware UTC datetime。"""
+    return as_utc(datetime(d.year, d.month, d.day, tzinfo=CN_TZ))
+
+
+def reset_cutoff(reset_days: int, today: date | None = None) -> datetime:
+    """应清零边界(tz-aware UTC):last_active < 此值 ⟺ 距末次活跃已满 reset_days 天(北京 0 点对齐)。
+    = 北京 00:00 of (today − (reset_days − 1))。例:reset_days=15、today=1/20 → 北京 1/6 00:00。"""
+    today = today or cn_today()
+    return cn_midnight_utc(today - timedelta(days=reset_days - 1))
+
+
+def last_active_subqueries(db: Session):
+    """两个按 user_id 预聚合的派生表:最近活跃事件(见 active_event_condition)、
+    最近领券发起(claim_started)。返回 (ev_sub, eng_sub)。口径同 admin,LEFT JOIN 用。"""
+    ev_sub = (
+        select(
+            AnalyticsEvent.user_id.label("user_id"),
+            func.max(AnalyticsEvent.created_at).label("last_at"),
+        )
+        .where(AnalyticsEvent.user_id.is_not(None), active_event_condition())
+        .group_by(AnalyticsEvent.user_id)
+        .subquery()
+    )
+    eng_sub = (
+        select(
+            CouponPromptEngagement.user_id.label("user_id"),
+            func.max(CouponPromptEngagement.created_at).label("last_at"),
+        )
+        .where(
+            CouponPromptEngagement.user_id.is_not(None),
+            CouponPromptEngagement.engage_type == ACTIVE_ENGAGE_TYPE,
+        )
+        .group_by(CouponPromptEngagement.user_id)
+        .subquery()
+    )
+    return ev_sub, eng_sub
+
+
+def last_active_expr(base_col, ev_sub, eng_sub, dialect: str):
+    """max(base_col, 最近活跃事件, 最近领券) 的 SQL 表达式。PG 用 greatest、SQLite 用 max。
+    子聚合缺失(未命中)时 coalesce 到 base_col(= User.created_at,恒非空基线)。"""
+    greatest = func.greatest if dialect == "postgresql" else func.max
+    return greatest(
+        base_col,
+        func.coalesce(ev_sub.c.last_at, base_col),
+        func.coalesce(eng_sub.c.last_at, base_col),
+    )

app/repositories/ad_ecpm.py

@@ -10,8 +10,46 @@ from sqlalchemy import func, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
+from app.core import rewards
 from app.core.rewards import cn_today
 from app.models.ad_ecpm import AdEcpmRecord
+from app.models.coupon_state import CouponSession
+
+MIN_REVENUE_EXPOSURE_MS = 1000
+
+
+def effective_ecpm_raw(ecpm_raw: str, exposure_ms: int | None) -> str:
+    """曝光不足一秒时保留展示记录，但把该条有效 eCPM 归零。"""
+    if exposure_ms is not None and exposure_ms < MIN_REVENUE_EXPOSURE_MS:
+        return "0"
+    return ecpm_raw
+
+
+def attributable_trace_id(
+    db: Session,
+    *,
+    feed_scene: str | None,
+    trace_id: str | None,
+    exposure_ms: int | None = None,
+) -> str | None:
+    """返回广告展示允许归属的业务 trace。
+
+    领券任务可能在 Draw 广告异步加载完成前已经失败或被用户放弃。非完成终态先落库、
+    广告回调后到时，收益仍需保留在总广告报表中，但不能再挂到该死亡领券明细，
+    因此清空关联 trace。其它场景、找不到 session、进行中或已完成状态保持原值，
+    由客户端生命周期修复负责主防线。
+    """
+    if feed_scene != "coupon" or not trace_id:
+        return trace_id
+    session_status = db.execute(
+        select(CouponSession.status).where(CouponSession.trace_id == trace_id)
+    ).scalar_one_or_none()
+    if session_status not in {"failed", "abandoned"}:
+        return trace_id
+    # 已真实上墙但不足一秒的曝光要在终态明细中明确显示 0，而不是被误判成“未填充”。
+    if exposure_ms is not None and exposure_ms < MIN_REVENUE_EXPOSURE_MS:
+        return trace_id
+    return None
 
 
 def create_ecpm_record(
@@ -24,8 +62,10 @@ def create_ecpm_record(
     adn: str | None = None,
     slot_id: str | None = None,
     feed_scene: str | None = None,
+    trace_id: str | None = None,
     app_env: str | None = None,
     our_code_id: str | None = None,
+    exposure_ms: int | None = None,
 ) -> AdEcpmRecord:
     """落一条 eCPM 上报记录。report_date 用北京时间当天,供按天聚合。
 
@@ -43,9 +83,10 @@ def create_ecpm_record(
         adn=adn,
         slot_id=slot_id,
         feed_scene=feed_scene,
+        trace_id=trace_id,
         app_env=app_env,
         our_code_id=our_code_id,
-        ecpm_raw=ecpm_raw,
+        ecpm_raw=effective_ecpm_raw(ecpm_raw, exposure_ms),
         report_date=cn_today().isoformat(),
     )
     db.add(rec)
@@ -105,3 +146,27 @@ def count_today(db: Session, user_id: int) -> int:
             AdEcpmRecord.report_date == cn_today().isoformat(),
         )
     ).scalar_one()
+
+
+def revenue_yuan_by_trace(db: Session, trace_ids: list[str]) -> dict[str, float]:
+    """各 trace_id 的广告预估收益(元):按 trace_id 聚合 ad_ecpm_record 的展示收益。
+
+    单条展示收益 = min(eCPM元, AD_ECPM_MAX_FEN/100) / 1000(与 admin 广告收益报表同口径)。
+    ecpm_raw 是字符串且需逐条钳顶,故取回后 Python 求和(行数=本页各 trace 的展示条数,很小)。
+    trace_id 仅信息流(比价/领券)场景客户端带,激励视频/旧数据为 NULL,按 trace_id 过滤天然只算对应场景。
+    只喂**当前页**的 trace_id(≤ 一页条数);空集合直接返回(避免 IN () 非法)。
+    """
+    if not trace_ids:
+        return {}
+    rows = db.execute(
+        select(AdEcpmRecord.trace_id, AdEcpmRecord.ecpm_raw).where(
+            AdEcpmRecord.trace_id.in_(trace_ids),
+        )
+    ).all()
+    cap_yuan = rewards.AD_ECPM_MAX_FEN / 100.0
+    out: dict[str, float] = {}
+    for tid, ecpm_raw in rows:
+        if not tid:
+            continue
+        out[tid] = out.get(tid, 0.0) + min(rewards.parse_ecpm_yuan(ecpm_raw), cap_yuan) / 1000.0
+    return {tid: round(v, 6) for tid, v in out.items()}

app/repositories/ad_feed_reward.py

@@ -176,10 +176,19 @@ def grant_feed_reward(
         )
         return _commit_record(db, rec, client_event_id)
 
+    # 按点位场景拆流水文案(2026-07):比价等候期看的广告 vs 领券时看的广告,在收益明细里分开显示。
+    # feed_scene=comparison→比价奖励 / coupon→领券奖励;其它(welfare/空/旧端不带)维持通用「信息流广告奖励」。
+    # 客户端按此 biz_type 直显固定文案(见 CoinHistoryViewModel.coinTitle),故 remark 只作后台留痕/兜底。
+    if feed_scene == "comparison":
+        reward_biz, reward_remark = "feed_ad_reward_comparison", "比价奖励"
+    elif feed_scene == "coupon":
+        reward_biz, reward_remark = "feed_ad_reward_coupon", "领券奖励"
+    else:
+        reward_biz, reward_remark = "feed_ad_reward", "信息流广告奖励"
     crud_wallet.grant_coins(
         db, user_id, coin,
-        biz_type="feed_ad_reward", ref_id=client_event_id,
-        remark="信息流广告奖励",
+        biz_type=reward_biz, ref_id=client_event_id,
+        remark=reward_remark,
     )
     rec = AdFeedRewardRecord(
         client_event_id=client_event_id,

app/repositories/ad_reward.py

@@ -41,6 +41,61 @@ def find_by_trans(db: Session, trans_id: str) -> AdRewardRecord | None:
     return _find_by_trans(db, trans_id)
 
 
+def find_by_session(db: Session, user_id: int, ad_session_id: str) -> AdRewardRecord | None:
+    """按广告会话 id 查该用户本次广告的发奖记录,供客户端轮询弹窗金额(reward-result)。
+
+    同一 ad_session_id 可能命中多条,**必须显式优先 granted**,不能只取最近一条:
+      - 客户端先上报 closed_early、S2S 随后才姗姗来迟 → 两条,granted 反而是后写的;
+      - record_reward_noshow 只在写入前查 granted,挡不住这种后到的竞态;
+      - 本地联调重复调 test-grant → 同 session 多条 granted(trans_id 各不相同)。
+    granted 是唯一「真发了钱」的状态,取它才是权威金额;都没有再取最近一条,让客户端
+    知道没发的原因(capped/closed_early…)。按 user_id 收窄,防止拿别人的 session 探测结果。
+    """
+    granted = db.execute(
+        select(AdRewardRecord)
+        .where(
+            AdRewardRecord.user_id == user_id,
+            AdRewardRecord.ad_session_id == ad_session_id,
+            AdRewardRecord.status == "granted",
+        )
+        .order_by(AdRewardRecord.created_at.desc())
+        .limit(1)
+    ).scalars().first()
+    if granted is not None:
+        return granted
+    return db.execute(
+        select(AdRewardRecord)
+        .where(
+            AdRewardRecord.user_id == user_id,
+            AdRewardRecord.ad_session_id == ad_session_id,
+        )
+        .order_by(AdRewardRecord.created_at.desc())
+        .limit(1)
+    ).scalars().first()
+
+
+def round_coin_total(db: Session, user_id: int, boost_round_id: str) -> int:
+    """本轮膨胀累计已发金币 = 该轮所有 granted 记录的 coin 之和(含刚发的这条)。
+
+    客户端弹窗要显示的就是它:第 1 条弹 40、第 2 条弹 60(=40+20),点「放弃赚钱」后余额涨 60,
+    三个数必须相等。之所以由服务端求和而不是客户端自己累加——客户端进程被杀/低内存重建后
+    本地累计就丢了,而发奖记录不会丢。
+
+    **必须带 user_id**:boost_round_id 是客户端生成的,不带 user_id 就等于让任何人拿别人的
+    轮 id 查别人发了多少。未发奖的状态(capped/closed_early/ecpm_missing)coin 本就是 0,
+    这里按 status 过滤只是让意图显式。
+    """
+    return int(
+        db.execute(
+            select(func.coalesce(func.sum(AdRewardRecord.coin), 0)).where(
+                AdRewardRecord.user_id == user_id,
+                AdRewardRecord.boost_round_id == boost_round_id,
+                AdRewardRecord.status == "granted",
+            )
+        ).scalar_one()
+    )
+
+
 def _granted_today(db: Session, user_id: int, reward_date: str) -> int:
     return db.execute(
         select(func.count())
@@ -78,8 +133,12 @@ def grant_ad_reward(
     reward_scene: str = "reward_video",
     reward_name: str | None = None,
     raw: str | None = None,
+    boost_round_id: str | None = None,
 ) -> AdRewardRecord:
-    """福利页激励视频发奖(幂等 + 每日限额 + eCPM 公式)。"""
+    """福利页激励视频发奖(幂等 + 每日限额 + eCPM 公式)。
+
+    boost_round_id 只是随记录存下的标签(见 round_coin_total),**不参与任何发奖判定**。
+    """
     # #2 幂等:同 trans_id 已处理过 → 原样返回,不重复发
     existing = _find_by_trans(db, trans_id)
     if existing is not None:
@@ -112,7 +171,7 @@ def grant_ad_reward(
             trans_id=trans_id, user_id=user_id, coin=0, status="capped",
             reward_date=today, reward_name=reward_name, raw=raw,
             reward_scene=reward_scene, ad_session_id=ad_session_id, ecpm_raw=ecpm,
-            app_env=src_app_env, our_code_id=src_code_id,
+            app_env=src_app_env, our_code_id=src_code_id, boost_round_id=boost_round_id,
         )
         return _commit_record(db, rec, trans_id)
 
@@ -123,7 +182,7 @@ def grant_ad_reward(
             trans_id=trans_id, user_id=user_id, coin=0, status="ecpm_missing",
             reward_date=today, reward_name=reward_name, raw=raw,
             reward_scene=reward_scene, ad_session_id=ad_session_id, ecpm_raw=None,
-            app_env=src_app_env, our_code_id=src_code_id,
+            app_env=src_app_env, our_code_id=src_code_id, boost_round_id=boost_round_id,
         )
         return _commit_record(db, rec, trans_id)
 
@@ -140,7 +199,7 @@ def grant_ad_reward(
         trans_id=trans_id, user_id=user_id, coin=coin, status="granted",
         reward_date=today, reward_name=reward_name, raw=raw,
         reward_scene=reward_scene, ad_session_id=ad_session_id, ecpm_raw=ecpm_raw,
-        app_env=src_app_env, our_code_id=src_code_id,
+        app_env=src_app_env, our_code_id=src_code_id, boost_round_id=boost_round_id,
     )
     return _commit_record(db, rec, trans_id)
 
@@ -206,8 +265,13 @@ def record_external_reward(
     raw: str | None = None,
     status: str = "granted",
     commit: bool = True,
+    boost_round_id: str | None = None,
 ) -> AdRewardRecord:
-    """记录非普通看视频场景的 S2S 回调幂等,发币由调用方业务仓储完成。"""
+    """记录非普通看视频场景的 S2S 回调幂等,发币由调用方业务仓储完成。
+
+    boost_round_id 同 grant_ad_reward:纯标签。签到膨胀场景的 coin 也会计入本轮累计
+    (它的 coin 就是实发额),所以这里也要存,否则一轮里混了膨胀就会漏算。
+    """
     existing = _find_by_trans(db, trans_id)
     if existing is not None:
         return existing
@@ -224,6 +288,7 @@ def record_external_reward(
         reward_scene=reward_scene,
         ad_session_id=ad_session_id,
         ecpm_raw=ecpm,
+        boost_round_id=boost_round_id,
     )
     db.add(rec)
     if commit:

app/repositories/analytics_selfstat.py

@@ -0,0 +1,38 @@
+"""自报计数快照落库。一次事务:插 1 条快照头 + N 条 event 行,返回快照 id。"""
+from __future__ import annotations
+
+from sqlalchemy.orm import Session
+
+from app.models.analytics_selfstat import AnalyticsSelfStat, AnalyticsSelfStatEvent
+from app.schemas.analytics_selfstat import SelfStatBatchIn
+
+
+def record_selfstat(db: Session, batch: SelfStatBatchIn) -> int:
+    snap = AnalyticsSelfStat(
+        device_id=batch.device_id,
+        epoch_id=batch.epoch_id,
+        app_ver=batch.app_ver,
+        oem=batch.oem,
+        os=batch.os,
+        batches_attempted=batch.batches_attempted,
+        batches_ok=batch.batches_ok,
+        batches_fail=batch.batches_fail,
+        retries=batch.retries,
+        queue_depth=batch.queue_depth,
+        sent_at=batch.sent_at,
+    )
+    db.add(snap)
+    db.flush()  # 拿到 snap.id
+    db.add_all([
+        AnalyticsSelfStatEvent(
+            snapshot_id=snap.id,
+            event=e.event,
+            attempted=e.attempted,
+            drop_capture=e.drop_capture,
+            delivered=e.delivered,
+            drop_undelivered=e.drop_undelivered,
+        )
+        for e in batch.events
+    ])
+    db.commit()
+    return snap.id

app/repositories/app_config.py

@@ -142,3 +142,47 @@ def set_ad_config(db: Session, data: dict, *, admin_id: int, commit: bool = True
     else:
         db.flush()
     return row
+
+
+# ── 华为审核开关(admin 可切,仅华为 ROM 客户端拉)────────────────────────────────
+# 同 ad_config:复用 AppConfig 表但不进 CONFIG_DEFS——它由「华为审核开关」专用页管理,
+# 有自己的两态语义,混进通用系统配置页只会显示成一个没头没尾的 on/off。
+#   default → 新手引导页(快速设置)强制展示,用户无法关闭(= 上线至今的现状)
+#   review  → 快速设置的权限步左上角出现退出按钮,可直接进首页(过华为应用市场审核用)
+# 空库 = default = 行为完全不变。客户端经 /api/v1/platform/huawei-review 拉取。
+HUAWEI_REVIEW_KEY = "huawei_review"
+HUAWEI_REVIEW_MODES = ("default", "review")
+_HUAWEI_REVIEW_DEFAULTS: dict[str, Any] = {
+    "mode": "default",
+}
+
+
+def get_huawei_review(db: Session) -> dict:
+    """读华为审核开关。DB 无 / 脏值一律回退 default(宁可不给退出按钮,也不误放开)。"""
+    row = db.get(AppConfig, HUAWEI_REVIEW_KEY)
+    merged = dict(_HUAWEI_REVIEW_DEFAULTS)
+    if row is not None and isinstance(row.value, dict):
+        merged.update(row.value)
+    if merged.get("mode") not in HUAWEI_REVIEW_MODES:
+        merged["mode"] = _HUAWEI_REVIEW_DEFAULTS["mode"]
+    return merged
+
+
+def set_huawei_review(db: Session, mode: str, *, admin_id: int, commit: bool = True) -> AppConfig:
+    """admin 切换华为审核开关。非法 mode 抛 ValueError(路由转 400)。"""
+    if mode not in HUAWEI_REVIEW_MODES:
+        raise ValueError(f"invalid mode: {mode} (expected one of {list(HUAWEI_REVIEW_MODES)})")
+    row = db.get(AppConfig, HUAWEI_REVIEW_KEY)
+    value = {"mode": mode}
+    if row is None:
+        row = AppConfig(key=HUAWEI_REVIEW_KEY, value=value, updated_by_admin_id=admin_id)
+        db.add(row)
+    else:
+        row.value = value
+        row.updated_by_admin_id = admin_id
+    if commit:
+        db.commit()
+        db.refresh(row)
+    else:
+        db.flush()
+    return row

app/repositories/comparison.py

@@ -24,6 +24,23 @@ def _yuan_to_cents(yuan: float | None) -> int | None:
     return round(yuan * 100)
 
 
+def _product_names_from_items(items: list | None) -> str | None:
+    """下单商品 items([{name, qty, specs?}])→ 顿号分隔的商品名串(去重保序),
+    供 admin「商品」列展示 + 商品名 LIKE 搜索。空 / 无名 → None;超列宽(512)截断留余量。"""
+    if not items:
+        return None
+    names: list[str] = []
+    for it in items:
+        name = it.get("name") if isinstance(it, dict) else None
+        if not name:
+            continue
+        s = str(name).strip()
+        if s and s not in names:
+            names.append(s)
+    joined = "、".join(names)
+    return joined[:500] or None
+
+
 def _derive(payload: ComparisonRecordIn) -> dict:
     """从上报 payload 派生结构化列(best/saved/is_source_best/status)。"""
     results = payload.comparison_results
@@ -81,10 +98,12 @@ def upsert_record(
     新客户端不再 POST(改由 compare.py 透传壳 harvest 落库)。
     """
     derived = _derive(payload)
+    items = [it.model_dump(exclude_none=True) for it in payload.items]
     fields = dict(
         device_id=payload.device_id,
         business_type=payload.business_type,
         store_name=payload.store_name,
+        product_names=_product_names_from_items(items),
         source_platform_id=payload.source_platform_id,
         source_platform_name=payload.source_platform_name,
         source_package=payload.source_package,
@@ -93,7 +112,7 @@ def upsert_record(
         trace_url=payload.trace_url,
         total_dish_count=payload.total_dish_count,
         skipped_dish_count=payload.skipped_dish_count,
-        items=[it.model_dump(exclude_none=True) for it in payload.items],
+        items=items,
         comparison_results=[r.model_dump() for r in payload.comparison_results],
         skipped_dish_names=list(payload.skipped_dish_names),
         # 客户端环境 / 性能(debug,客户端上报;旧客户端为 None)
@@ -288,6 +307,8 @@ def harvest_done(
     行不存在(理论上帧0已建;防御)则新建。"""
     results = done_params.get("comparison_results") or []
     derived = _derive_from_results(results)
+    # 菜品:pricebot 已把源单菜品塞进 comparison_results[源行].items
+    items = next((r.get("items") or [] for r in results if r.get("is_source")), [])
     fields = dict(
         business_type=business_type or "food",
         information=done_params.get("information") or None,
@@ -298,8 +319,8 @@ def harvest_done(
         skipped_dish_count=done_params.get("skipped_dish_count"),
         skipped_dish_names=list(done_params.get("skipped_dish_names") or []),
         comparison_results=results,
-        # 菜品:pricebot 已把源单菜品塞进 comparison_results[源行].items
-        items=next((r.get("items") or [] for r in results if r.get("is_source")), []),
+        items=items,
+        product_names=_product_names_from_items(items),
         raw_payload=done_params,
         **derived,
         **_device_cols_from_info(device_info),

app/repositories/coupon_state.py

@@ -147,12 +147,22 @@ def reset_today_completion(db: Session, device_id: str) -> int:
 
 # ===== 领券记录(coupon_claim_record)=====
 
+def session_app_env(db: Session, trace_id: str | None) -> str | None:
+    """按 trace_id 取 coupon_session.app_env(每券成功率表打环境标用);无 trace_id / 查不到 → None。"""
+    if not trace_id:
+        return None
+    return db.execute(
+        select(CouponSession.app_env).where(CouponSession.trace_id == trace_id)
+    ).scalar_one_or_none()
+
+
 def record_claims(
     db: Session,
     device_id: str,
     user_id: int | None,
     trace_id: str | None,
     results: list[dict],
+    app_env: str | None = None,
 ) -> int:
     """一批券领取结果幂等写入,返回写入(新增 + 更新)条数。
 
@@ -186,12 +196,15 @@ def record_claims(
                 row.user_id = user_id
             if count is not None:
                 row.claimed_count = count
+            if app_env is not None:
+                row.app_env = app_env
             row.extra = r
         else:
             db.add(CouponClaimRecord(
                 device_id=device_id, user_id=user_id,
                 coupon_id=coupon_id, claim_date=today,
-                status=status, vendor=r.get("vendor"), coupon_name=r.get("name"),
+                status=status, app_env=app_env,
+                vendor=r.get("vendor"), coupon_name=r.get("name"),
                 claimed_count=count, trace_id=trace_id, reason=r.get("reason"),
                 extra=r,
             ))
@@ -235,6 +248,47 @@ def sum_claimed_count(db: Session, user_id: int) -> int:
     return int(total or 0)
 
 
+# ===== 领券平台推导(coupon_id → 平台;成功平台集)=====
+
+# 成功语义:success + already_claimed 算成功(pricebot 代码 emit already_claimed,协议 enum 漏了);
+# failed / skipped 不算。与 sum_claimed_count 同口径。
+_SUCCESS_STATUSES = frozenset({"success", "already_claimed"})
+
+# 三档平台 id 及固定序(美团→淘宝→京东),与客户端 DEFAULT_PLATFORM_ORDER 对齐。
+DEFAULT_PLATFORMS: tuple[str, ...] = ("meituan-waimai", "taobao-shanguang", "jd-waimai")
+
+
+def coupon_id_to_platform(coupon_id: str | None) -> str | None:
+    """coupon_id 前缀 → 平台 id;无法识别 / 空 → None。
+
+    与客户端 `CouponForegroundService.couponIdToPlatform` 同词表:
+    mt_→美团外卖 / tb_·ele_·elm_→淘宝闪购 / jd_→京东外卖。
+    """
+    if not coupon_id:
+        return None
+    if coupon_id.startswith("mt_"):
+        return "meituan-waimai"
+    if coupon_id.startswith(("tb_", "ele_", "elm_")):
+        return "taobao-shanguang"
+    if coupon_id.startswith("jd_"):
+        return "jd-waimai"
+    return None
+
+
+def succeeded_platforms(results: list[dict]) -> list[str]:
+    """一批券结果 → 至少领到一张的平台集(按 DEFAULT_PLATFORMS 去重保序)。
+
+    只取 status∈{success, already_claimed} 的券;失败/跳过、无法识别平台的券跳过。
+    """
+    ok: set[str] = set()
+    for r in results:
+        if r.get("status") in _SUCCESS_STATUSES:
+            platform = coupon_id_to_platform(r.get("coupon_id"))
+            if platform is not None:
+                ok.add(platform)
+    return [p for p in DEFAULT_PLATFORMS if p in ok]
+
+
 # ===== 领券任务流水(coupon_session,admin「领券数据」看板数据源)=====
 
 def upsert_coupon_session(
@@ -321,3 +375,31 @@ def upsert_coupon_session(
     except IntegrityError:
         # 并发下另一请求刚插了同 trace_id → 唯一约束撞,回滚忽略(本就幂等)。
         db.rollback()
+
+
+def merge_session_platform_success(
+    db: Session, trace_id: str, platforms: list[str]
+) -> None:
+    """把本帧「成功平台」并入 coupon_session.platform_success(按 trace_id,并集幂等,按 DEFAULT_PLATFORMS 保序)。
+
+    - 领券 /step 每逢带券结果的帧调一次(平台成败布尔,跨帧取并集天然幂等,不重复计)。
+    - 读不到该 trace_id 的行 → **静默跳过**(不建兜底行;设计 §5:started 帧几乎必先落库)。
+    - 并集无变化(该平台已记过)→ 不写库,省一次 UPDATE。
+    - fire-and-forget:调用方已吞异常;并发唯一冲突回滚忽略。
+    """
+    if not platforms:
+        return
+    row = db.execute(
+        select(CouponSession).where(CouponSession.trace_id == trace_id)
+    ).scalar_one_or_none()
+    if row is None:
+        return
+    merged = set(row.platform_success or []) | set(platforms)
+    new_list = [p for p in DEFAULT_PLATFORMS if p in merged]
+    if new_list == (row.platform_success or []):
+        return  # 幂等:无新平台,不写
+    row.platform_success = new_list
+    try:
+        db.commit()
+    except IntegrityError:
+        db.rollback()

app/repositories/inactivity.py

@@ -0,0 +1,198 @@
+"""15 天不活跃清零业务逻辑(纯同步,可单测)。worker 只是它的 asyncio 外壳。
+
+活跃口径复用 app.repositories.activity;清零走 wallet.grant_*(负数出账、写流水、不 commit)。
+逐用户独立事务,一个失败不影响其余。
+"""
+from __future__ import annotations
+
+import logging
+from datetime import date, datetime
+
+from sqlalchemy import or_, select
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.orm import Session
+
+from app.core.rewards import CN_TZ
+from app.integrations.notifier import InactivityNotifier
+from app.models.inactivity import InactivityNotificationLog, InactivityResetLog
+from app.models.user import User
+from app.models.wallet import CoinAccount
+from app.repositories import activity
+from app.repositories import wallet as wallet_repo
+
+logger = logging.getLogger("shagua.inactivity")
+
+RESET_BIZ_TYPE = "inactivity_reset"
+RESET_REMARK = "15天不活跃清零"
+
+# 清零候选口径:金币或折算现金有余额即入选。**邀请现金不算**——它是产品红线、不清零
+# (见 wallet.CoinAccount 注释),只有邀请现金余额的用户没有可清项,故不入选。
+_ANY_BALANCE = or_(
+    CoinAccount.coin_balance > 0,
+    CoinAccount.cash_balance_cents > 0,
+)
+
+
+def _base_query(db: Session):
+    """select(user_id, last_active, 三桶余额),join CoinAccount + 两活跃子查询。"""
+    ev_sub, eng_sub = activity.last_active_subqueries(db)
+    dialect = db.get_bind().dialect.name
+    last_active = activity.last_active_expr(User.created_at, ev_sub, eng_sub, dialect)
+    stmt = (
+        select(
+            User.id.label("user_id"),
+            last_active.label("last_active"),
+            CoinAccount.coin_balance,
+            CoinAccount.cash_balance_cents,
+            CoinAccount.invite_cash_balance_cents,
+        )
+        .join(CoinAccount, CoinAccount.user_id == User.id)
+        .outerjoin(ev_sub, ev_sub.c.user_id == User.id)
+        .outerjoin(eng_sub, eng_sub.c.user_id == User.id)
+    )
+    return stmt, last_active
+
+
+def _cn_date(dt: datetime) -> date:
+    """datetime → 北京自然日(naive 视为 UTC)。"""
+    return activity.norm_utc(dt).astimezone(CN_TZ).date()
+
+
+def _inactive_days(last_active: datetime, today: date) -> int:
+    return (today - _cn_date(last_active)).days
+
+
+def select_inactive_users(db: Session, *, cutoff: datetime):
+    """应清零用户:last_active < cutoff 且金币/折算现金有余额(邀请现金不清、不计)。
+    返回 Row 列表(值已快照,可跨 commit)。"""
+    stmt, last_active = _base_query(db)
+    stmt = stmt.where(_ANY_BALANCE, last_active < activity.as_utc(cutoff))
+    return db.execute(stmt).all()
+
+
+def clear_user(db: Session, *, user_id: int, last_active: datetime, inactive_days: int,
+               reason: str, dry_run: bool = False) -> bool:
+    """单用户清零(独立事务、行锁)。金币 + 折算现金归零 + 写审计 + 2 条流水;**邀请现金不清**
+    (产品红线,见 wallet.CoinAccount 注释),仅作快照记入审计。返回是否真处理了(有可清余额)。
+
+    dry_run=True:**只写审计名单、不动钱不写流水**(灰度看名单)。按 streak 去重——本 streak
+    已记过(reset_at > last_active)就跳,避免 worker 每日重复记。"""
+    acc = wallet_repo.get_or_create_account(db, user_id, commit=False, lock=True)
+    coin, cash, invite = acc.coin_balance, acc.cash_balance_cents, acc.invite_cash_balance_cents
+    if coin == 0 and cash == 0:  # 邀请现金不清,故不算"有可清余额"
+        return False
+    if dry_run and db.execute(
+        select(InactivityResetLog.id).where(
+            InactivityResetLog.user_id == user_id,
+            InactivityResetLog.reset_at > activity.as_utc(last_active),
+        ).limit(1)
+    ).first():
+        return False  # dry-run:本 streak 已记过审计,不重复记
+    log = InactivityResetLog(
+        user_id=user_id, coin_balance_before=coin, cash_balance_cents_before=cash,
+        invite_cash_balance_cents_before=invite, last_active_at=activity.norm_utc(last_active),
+        inactive_days=inactive_days, reason=reason,
+    )
+    db.add(log)
+    db.flush()  # 拿 log.id 作 ref_id 交叉链接审计↔流水
+    if not dry_run:  # dry-run 只记审计名单,不真出账
+        ref = str(log.id)
+        if coin:
+            wallet_repo.grant_coins(db, user_id, -coin, biz_type=RESET_BIZ_TYPE, ref_id=ref, remark=RESET_REMARK)
+        if cash:
+            wallet_repo.grant_cash(db, user_id, -cash, biz_type=RESET_BIZ_TYPE, ref_id=ref, remark=RESET_REMARK)
+        # 邀请现金(invite_cash_balance_cents)刻意不动:两本账物理隔离、邀请金是产品红线。
+    db.commit()
+    return True
+
+
+def run_reset_once(db: Session, *, reset_days: int, today: date, dry_run: bool = False) -> dict:
+    """扫一轮清零。逐用户独立 commit,失败隔离。dry_run=True 只记审计名单、不动钱(见 clear_user)。"""
+    stats = {"scanned": 0, "cleared": 0, "failed": 0}
+    cutoff = activity.reset_cutoff(reset_days, today)
+    reason = f"inactive_{reset_days}d" + ("_dryrun" if dry_run else "")
+    rows = select_inactive_users(db, cutoff=cutoff)  # 先物化,避免边遍历边 commit
+    for row in rows:
+        stats["scanned"] += 1
+        idays = _inactive_days(row.last_active, today)
+        try:
+            if clear_user(db, user_id=row.user_id, last_active=row.last_active,
+                          inactive_days=idays, reason=reason, dry_run=dry_run):
+                stats["cleared"] += 1
+        except SQLAlchemyError:
+            db.rollback()
+            stats["failed"] += 1
+    return stats
+
+
+def select_warn_candidates(db: Session, *, clear_cutoff: datetime, warn_hi: datetime):
+    """预警候选:clear_cutoff <= last_active < warn_hi 且有可清余额(即已进预警窗、尚未到清零)。"""
+    stmt, last_active = _base_query(db)
+    stmt = stmt.where(
+        _ANY_BALANCE,
+        last_active >= activity.as_utc(clear_cutoff),
+        last_active < activity.as_utc(warn_hi),
+    )
+    return db.execute(stmt).all()
+
+
+def run_warn_once(db: Session, notifier: InactivityNotifier, *,
+                  reset_days: int, warn_stages: list[int], today: date) -> dict:
+    """扫一轮预警。每人取"最紧急的已到达档",按 streak 去重(notification_log.created_at > last_active)。
+    预警只涉及会被清的金币 + 折算现金;邀请现金不清、不预警(仅在 notification_log 记快照)。
+    逐用户 try/except 隔离:单用户通知器抛错 / DB 错不阻断其余,也绝不能拖累后续清零。"""
+    stats = {"warned": 0, "warn_skipped": 0, "warn_failed": 0}
+    if not warn_stages:
+        return stats
+    clear_cutoff = activity.reset_cutoff(reset_days, today)                # 到此即清零,不再预警
+    warn_hi = activity.reset_cutoff(reset_days - max(warn_stages), today)  # 最早预警档边界
+    ascending = sorted(warn_stages)                                       # 最紧急(最小 k)在前
+    for row in select_warn_candidates(db, clear_cutoff=clear_cutoff, warn_hi=warn_hi):
+        idays = _inactive_days(row.last_active, today)
+        stage = next((k for k in ascending if idays >= reset_days - k), None)
+        if stage is None:  # 防御:候选已在预警窗内、stage 必命中,此分支实际不可达
+            continue
+        try:
+            already = db.execute(
+                select(InactivityNotificationLog.id).where(
+                    InactivityNotificationLog.user_id == row.user_id,
+                    InactivityNotificationLog.stage == stage,
+                    InactivityNotificationLog.created_at > activity.as_utc(row.last_active),
+                ).limit(1)
+            ).first()
+            if already:
+                stats["warn_skipped"] += 1
+                continue
+            status = notifier.warn(
+                user_id=row.user_id, coin=row.coin_balance, cash_cents=row.cash_balance_cents,
+                stage=stage, days_until_reset=reset_days - idays,
+            )
+            db.add(InactivityNotificationLog(
+                user_id=row.user_id, stage=stage, inactive_days=idays,
+                coin_balance=row.coin_balance, cash_balance_cents=row.cash_balance_cents,
+                invite_cash_balance_cents=row.invite_cash_balance_cents,  # 快照,不参与"将清"额度
+                channel=notifier.channel, status=status,
+            ))
+            db.commit()
+            stats["warned"] += 1
+        except Exception:  # noqa: BLE001 - 单用户预警失败(通知器抛错/DB 错)隔离,不阻断其余、不拖累清零
+            db.rollback()
+            stats["warn_failed"] += 1
+    return stats
+
+
+def run_once(db: Session, *, notifier: InactivityNotifier, reset_days: int,
+             warn_stages: list[int], today: date, dry_run: bool = False) -> dict:
+    """一轮完整任务:先预警(阶段 A)再清零(阶段 B)。返回合并统计。
+    预警整段异常也**绝不阻塞清零**——清零是核心、不可逆资金操作,不能被通知故障拖住。
+    dry_run=True(灰度默认):只记审计名单、不清、**也不预警**(不通知一个不会发生的清零)。"""
+    warn = {"warned": 0, "warn_skipped": 0, "warn_failed": 0}
+    if not dry_run:
+        try:
+            warn = run_warn_once(db, notifier, reset_days=reset_days, warn_stages=warn_stages, today=today)
+        except Exception:  # noqa: BLE001 - 预警阶段整体失败(如候选查询失败)也要继续清零
+            logger.exception("inactivity warn phase failed; proceeding to reset")
+            db.rollback()
+            warn = {"warned": 0, "warn_skipped": 0, "warn_failed": 0, "warn_phase_error": 1}
+    reset = run_reset_once(db, reset_days=reset_days, today=today, dry_run=dry_run)
+    return {**warn, **reset}

app/repositories/ops_marquee.py

@@ -29,6 +29,18 @@ from app.core.rewards import CN_TZ
 from app.models.comparison import ComparisonRecord
 from app.models.ops_marquee_seed import OpsMarqueeSeed
 from app.models.user import User
+from app.repositories import app_config
+from app.repositories.user import is_default_nickname
+
+# 首页轮播数据源模式(存 app_config.marquee_feed_mode):
+#   mixed=真实优先+种子补位+合成兜底(默认,原行为);real=只真实(不足则少/空);seed=只种子+合成兜底。
+FEED_MODES = ("mixed", "real", "seed")
+
+
+def get_feed_mode(db: Session) -> str:
+    """读首页轮播数据源模式;非法/未配置回退 mixed(= 原行为)。"""
+    mode = app_config.get_value(db, "marquee_feed_mode")
+    return mode if mode in FEED_MODES else "mixed"
 
 # feed 运行时随机源(每次请求结果不同 = 轮播想要的「鲜活感」)
 _rng = random.Random()
@@ -129,9 +141,12 @@ def _synth_masked_name(rng: random.Random) -> str:
 
 def _mask_real(nickname: str | None, user_id: int) -> str:
     """真实用户脱敏(对齐 PRD「用户标识打码规则」):设过昵称→昵称脱敏(中英文皆可);
-    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。"""
+    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。
+
+    创建时自动分配的默认昵称(「用户」+9 位随机,见 user.is_default_nickname)不算用户主动设的昵称,
+    按「无昵称」处理走 id 规则(产品决策 2026-07:默认昵称归入「没昵称」档)。"""
     nick = (nickname or "").strip()
-    if nick:
+    if nick and not is_default_nickname(nick):
         return _mask_nickname(nick)
     return _mask_anon(user_id)
 
@@ -202,60 +217,79 @@ def _recent_real_rows(db: Session) -> list[tuple[int, int, str | None]]:
     return out
 
 
-def get_feed(db: Session, limit: int = 8) -> list[dict]:
+def _shuffle_declustered(rows: list, rng: random.Random | None = None) -> list:
+    """洗牌 + 「去连簇」:先洗牌,再贪心重排让相邻两条尽量不是同一 user_id(元素 [0] 即 user_id)。
+    rng=None → 用全局 _rng(feed 每次新随机);传入 rng(如固定种子 Random)→ 排列确定(admin 稳定分页)。
+    减少同一用户连续出现;只有少数几个用户时 best-effort。"""
+    rng = rng or _rng
+    pool = list(rows)
+    rng.shuffle(pool)
+    result: list = []
+    while pool:
+        prev_uid = result[-1][0] if result else None
+        # 优先挑与上一条不同 user 的;挑不到(只剩同 user)才取第一个
+        idx = next((i for i, r in enumerate(pool) if r[0] != prev_uid), 0)
+        result.append(pool.pop(idx))
+    return result
+
+
+def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]:
     """返回最多 limit 条 {masked_user, saved_amount_cents, time(HH:MM:SS 北京)}。
 
-    真实条:success 且 0 < saved ≤ 上限,按 user 去重(同一用户只取最新一条,避免单人刷屏)。
+    mode:显式传入(admin 预览指定模式)则用它、**不改持久化配置**;不传(客户端 /savings-feed)读
+    持久化的 marquee_feed_mode;非法值一律回退到持久化模式。
+    真实条:success 且 0 < saved ≤ 上限,**不按 user 去重**(打乱 + 去连簇:相邻尽量不同用户、减少单人连刷)后取前 limit。
     不足用启用的种子补齐——**公平随机抽取** need 个(而非固定取前 N),让所有种子都有机会露出;
     种子用户名留空则随机合成(避开撞名),金额取**长尾随机**(小额居多、偶尔大额,更像真实分布)。
     真实 + 种子仍不满 limit → 内置合成条**补满**,保证轮播既不空也不稀疏。
     展示时间统一「刷新」成相对现在的最近时刻(从 now 往前**随机抖动**递减),保证轮播永远像刚发生、
     节奏自然不机械(真实用户/金额不变,只换展示时间——避免旧测试数据 / 低谷期记录显示成过时时间)。
     """
-    # 真实条:取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
-    rows = _recent_real_rows(db)
+    # 预览可显式指定模式(所见=选中模式,不依赖 PATCH 落库时序);None/非法 → 读持久化配置。
+    mode = mode if mode in FEED_MODES else get_feed_mode(db)  # mixed / real / seed
 
     items: list[dict] = []
     used_names: set[str] = set()
-    seen_users: set[int] = set()
-    for uid, sc, nick in rows:
-        if uid in seen_users:
-            continue
-        seen_users.add(uid)
-        name = _mask_real(nick, uid)
-        used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
-        items.append({"masked_user": name, "saved_amount_cents": int(sc)})
-        if len(items) >= limit:
-            break
 
-    need = limit - len(items)
-    if need > 0:
-        seeds = db.execute(
-            select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
-        ).scalars().all()
-        # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
-        chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
-        _rng.shuffle(chosen)
-        for s in chosen:
-            # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
-            # 仅运营手动设的非模板真名才原样用。
-            fixed = (s.masked_user or "").strip()
-            name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
+    # 真实条(mixed / real):**不按 user 去重**——打乱 + 去连簇(相邻尽量不同用户、减少单人连刷)后取前
+    # limit;金额超上限的异常值已在查询剔除。同一用户可多条露出,但被打散、尽量不连续。
+    if mode != "seed":
+        for uid, sc, nick in _shuffle_declustered(_recent_real_rows(db))[:limit]:
+            name = _mask_real(nick, uid)
+            used_names.add(name)  # 同一用户可多条,名字重复无害(used_names 仅供种子避重)
+            items.append({"masked_user": name, "saved_amount_cents": int(sc)})
+
+    # 种子补位 + 合成兜底(mixed / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
+    # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
+    if mode != "real":
+        need = limit - len(items)
+        if need > 0:
+            seeds = db.execute(
+                select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
+            ).scalars().all()
+            # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
+            chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
+            _rng.shuffle(chosen)
+            for s in chosen:
+                # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
+                # 仅运营手动设的非模板真名才原样用。
+                fixed = (s.masked_user or "").strip()
+                name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
+                used_names.add(name)
+                # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
+                lo = max(0, int(s.min_cents))
+                hi = max(lo, int(s.max_cents))
+                items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
+
+        # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
+        # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
+        while len(items) < limit:
+            name = _unique_name(used_names)
             used_names.add(name)
-            # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
-            lo = max(0, int(s.min_cents))
-            hi = max(lo, int(s.max_cents))
-            items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
-
-    # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
-    # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
-    while len(items) < limit:
-        name = _unique_name(used_names)
-        used_names.add(name)
-        items.append({
-            "masked_user": name,
-            "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
-        })
+            items.append({
+                "masked_user": name,
+                "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
+            })
 
     # 统一赋「最近」时间:从 now 往前**随机抖动**递减,避免固定节奏被看出规律。
     # 首条几十秒前;其余多数 1~5 分钟,偶尔扎堆(20~55s)或较长(5~9 分钟),降序、像真实流水。
@@ -276,6 +310,78 @@ def get_feed(db: Session, limit: int = 8) -> list[dict]:
     return items
 
 
+# ===== admin 侧:分页浏览「当前模式下可展示的记录」(审核用,不去重) =====
+_REAL_BROWSE_CAP = 1000   # 真实记录一次最多纳入这么多去洗牌+分页(足够审核;防超大库全量洗牌)
+_BROWSE_SEED = 20260707   # 固定洗牌种子:同一批数据下排列恒定 → 翻页稳定、能翻遍全部
+
+
+def _seed_browse_row(seed: OpsMarqueeSeed) -> dict:
+    """把一条种子按其「生成逻辑」**确定性**生成一行浏览项(名字/金额按 seed.id 派生固定种子 → 翻页稳定)。
+    名字:运营手填的非模板名原样用,否则本地合成;金额:区间内确定性长尾取值。user_id=0(种子无真实用户)。"""
+    r = random.Random(_BROWSE_SEED * 1_000_003 + int(seed.id))
+    fixed = (seed.masked_user or "").strip()
+    name = fixed if (fixed and not fixed.startswith("用户****")) else _synth_name(r)
+    lo = max(0, int(seed.min_cents))
+    hi = max(lo, int(seed.max_cents))
+    amt = lo if hi <= lo else lo + int(round((hi - lo) * (r.random() ** 2.2)))
+    return {"masked_user": name, "saved_amount_cents": amt, "created_at": "", "user_id": 0}
+
+
+def list_real_records(
+    db: Session, mode: str | None = None, offset: int = 0, limit: int = 8
+) -> tuple[list[dict], int]:
+    """分页浏览「**当前模式**下可在 app 轮播展示的全部记录」,供 admin 逐页审核(**不去重**):
+      - 只真实:全部 success+省>0 的真实记录;
+      - 只种子:每条启用种子按生成逻辑各出一行;
+      - 混播:真实 + 种子 全部合在一起。
+    与 app 轮播同口径:先洗牌 + 去连簇(相邻尽量不同 user;种子各自独立、不算同 user);**固定种子** →
+    同批数据下排列恒定,翻页不跳、能翻遍全部。返回 (items, total);item.user_id=0 表示种子。"""
+    mode = mode if mode in FEED_MODES else get_feed_mode(db)
+    # pool: [(cluster_key, item)];cluster_key 供去连簇——真实=user_id、种子=各自唯一负数(互不聚簇)
+    pool: list[tuple[int, dict]] = []
+    if mode != "seed":
+        rows = db.execute(
+            select(
+                ComparisonRecord.user_id,
+                ComparisonRecord.saved_amount_cents,
+                User.nickname,
+                ComparisonRecord.created_at,
+            )
+            .join(User, User.id == ComparisonRecord.user_id)
+            .where(
+                ComparisonRecord.status == "success",
+                ComparisonRecord.saved_amount_cents > 0,
+                ComparisonRecord.saved_amount_cents <= _REAL_MAX_CENTS,
+            )
+            .order_by(ComparisonRecord.created_at.desc())
+            .limit(_REAL_BROWSE_CAP)
+        ).all()
+        for uid, sc, nick, ca in rows:
+            pool.append((
+                int(uid),
+                {
+                    "masked_user": _mask_real(nick, int(uid)),
+                    "saved_amount_cents": int(sc),
+                    "created_at": str(ca)[:16] if ca is not None else "",
+                    "user_id": int(uid),
+                },
+            ))
+    if mode != "real":
+        seeds = (
+            db.execute(select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True)))
+            .scalars()
+            .all()
+        )
+        for i, s in enumerate(seeds):
+            pool.append((-(i + 1), _seed_browse_row(s)))  # 每个种子唯一 key → 互不聚簇
+    total = len(pool)
+    # 每次用同一固定种子新建 Random → 同批数据排列恒定(翻页稳定);同时相邻尽量不同 user。
+    ordered = _shuffle_declustered(pool, random.Random(_BROWSE_SEED))
+    off = max(0, offset)
+    items = [item for _key, item in ordered[off : off + limit]]
+    return items, total
+
+
 # ===== 运营侧:种子 CRUD =====
 def list_seeds(db: Session) -> list[OpsMarqueeSeed]:
     return list(

app/repositories/ops_stat.py

@@ -318,11 +318,14 @@ def update_config(
         row.random_current = _monotonic(row, random_initial)
         row.random_last_tick_at = now
     elif apply_now:
-        # 立即更新:不等钟点,马上刷新一次
+        # 立即更新:不等钟点,马上刷新一次。
+        # random:走一档增长;real/manual:直接落到「配置目标值」(manual_value / max(真实,保底)),
+        # **显式保存即所见即所得,绕过「只增不减」护栏**——运营手动改值就是要按配置显示(含调小)。
+        # (护栏仍作用于自动 tick 的 _refresh:防门面在两次保存之间被真实刷新/自增长悄悄缩水。)
         if row.mode == "random" and row.random_current is not None:
             row.random_current = _grow(row, row.random_current, 1)
         else:
-            row.random_current = _monotonic(row, _current_target(db, row))
+            row.random_current = _current_target(db, row)
         row.random_last_tick_at = now
     elif row.random_current is None:
         # 首次无值:按当前模式播种,使配置后立即有合理展示值

app/repositories/phone_rebind.py

@@ -0,0 +1,39 @@
+"""手机号换绑台账(phone_rebind_log)的查询与写入。见 M2 spec §4.1。"""
+from __future__ import annotations
+
+import math
+from datetime import datetime, timedelta, timezone
+
+from sqlalchemy import func, select
+from sqlalchemy.orm import Session
+
+from app.models.phone_rebind_log import PhoneRebindLog
+
+
+def rebound_within_days(db: Session, phone: str, days: int) -> bool:
+    """该手机号在最近 days 天内是否换绑过(命中 → 禁止再次换绑)。"""
+    since = datetime.now(timezone.utc) - timedelta(days=days)
+    stmt = (
+        select(PhoneRebindLog.id)
+        .where(PhoneRebindLog.phone == phone, PhoneRebindLog.rebound_at >= since)
+        .limit(1)
+    )
+    return db.execute(stmt).first() is not None
+
+
+def remaining_block_days(db: Session, phone: str, days: int) -> int:
+    """距离该手机号可再次换绑还剩几天(向上取整;无记录返回 0)。"""
+    last = db.execute(
+        select(func.max(PhoneRebindLog.rebound_at)).where(PhoneRebindLog.phone == phone)
+    ).scalar_one_or_none()
+    if last is None:
+        return 0
+    if last.tzinfo is None:  # SQLite 取回 naive datetime,按 UTC 归一
+        last = last.replace(tzinfo=timezone.utc)
+    remaining = (last + timedelta(days=days) - datetime.now(timezone.utc)).total_seconds()
+    return max(0, math.ceil(remaining / 86400))
+
+
+def add_rebind_log(db: Session, *, phone: str, old_user_id: int | None, new_user_id: int, source: str) -> None:
+    """写一条换绑台账(**不 commit**,交给调用方 rebind_account 的单事务)。"""
+    db.add(PhoneRebindLog(phone=phone, old_user_id=old_user_id, new_user_id=new_user_id, source=source))

app/repositories/signin.py

@@ -11,12 +11,11 @@ from dataclasses import dataclass
 from datetime import timedelta
 
 from sqlalchemy import select
-from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
 from app.core import rewards
 from app.core.rewards import SIGNIN_CYCLE_LEN, cn_today
-from app.models.signin import SigninBoostRecord, SigninRecord
+from app.models.signin import SigninRecord
 from app.repositories import wallet as crud_wallet
 
 
@@ -24,18 +23,6 @@ class AlreadySignedError(Exception):
     """今天已经签过了。"""
 
 
-class NotSignedTodayError(Exception):
-    """今天尚未签到,不能膨胀。"""
-
-
-class AlreadyBoostedError(Exception):
-    """今天签到奖励已经膨胀过。"""
-
-
-class LastCycleDayBoostBlockedError(Exception):
-    """循环最后一天(第 SIGNIN_CYCLE_LEN 天)不允许签到膨胀。"""
-
-
 @dataclass
 class SigninStep:
     day: int  # 1..14
@@ -141,69 +128,3 @@ def do_signin(db: Session, user_id: int) -> tuple[SigninRecord, int]:
     db.commit()
     db.refresh(record)
     return record, acc.coin_balance
-
-
-def _today_record(db: Session, user_id: int) -> SigninRecord | None:
-    today = cn_today()
-    return db.execute(
-        select(SigninRecord).where(
-            SigninRecord.user_id == user_id,
-            SigninRecord.signin_date == today,
-        )
-    ).scalar_one_or_none()
-
-
-def boost_by_ad_ref(
-    db: Session, user_id: int, ad_ref_id: str
-) -> SigninBoostRecord | None:
-    """按广告交易号查签到膨胀记录。S2S 发奖后客户端确认用。"""
-    return db.execute(
-        select(SigninBoostRecord).where(
-            SigninBoostRecord.user_id == user_id,
-            SigninBoostRecord.ad_ref_id == ad_ref_id,
-        )
-    ).scalar_one_or_none()
-
-
-def boost_today_signin(
-    db: Session, user_id: int, *, ad_ref_id: str | None = None, commit: bool = True
-) -> tuple[SigninBoostRecord, int]:
-    """签到后看广告膨胀:固定补发配置金币。返回 (膨胀记录, 补发后余额)。"""
-    record = _today_record(db, user_id)
-    if record is None:
-        raise NotSignedTodayError
-    if record.cycle_day == SIGNIN_CYCLE_LEN:
-        raise LastCycleDayBoostBlockedError
-
-    today = record.signin_date
-    existing = db.execute(
-        select(SigninBoostRecord).where(
-            SigninBoostRecord.user_id == user_id,
-            SigninBoostRecord.signin_date == today,
-        )
-    ).scalar_one_or_none()
-    if existing is not None:
-        raise AlreadyBoostedError
-
-    boost = SigninBoostRecord(
-        user_id=user_id,
-        signin_date=today,
-        coin_awarded=rewards.get_signin_boost_coin(db),
-        ad_ref_id=ad_ref_id,
-    )
-    db.add(boost)
-    try:
-        acc, _ = crud_wallet.grant_coins(
-            db, user_id, boost.coin_awarded,
-            biz_type="signin_boost", ref_id=ad_ref_id or today.isoformat(),
-            remark=f"签到膨胀 第{record.cycle_day}天",
-        )
-        if commit:
-            db.commit()
-        else:
-            db.flush()
-    except IntegrityError as e:
-        db.rollback()
-        raise AlreadyBoostedError from e
-    db.refresh(boost)
-    return boost, acc.coin_balance

app/repositories/user.py

@@ -8,29 +8,11 @@ import secrets
 import string
 from datetime import datetime, timezone
 
-from sqlalchemy import delete, select
+from sqlalchemy import select
 from sqlalchemy.orm import Session
 
-from app.models.ad_watch_log import AdWatchLog
-from app.models.analytics_event import AnalyticsEvent
-from app.models.comparison import ComparisonRecord
-from app.models.comparison_milestone import ComparisonMilestoneClaim
-from app.models.coupon_state import (
-    CouponClaimRecord,
-    CouponDailyCompletion,
-    CouponPromptEngagement,
-    CouponSession,
-)
-from app.models.device import DeviceLiveness
-from app.models.feedback import Feedback
-from app.models.invite_fingerprint import InviteFingerprint
-from app.models.onboarding import OnboardingCompletion
-from app.models.price_report import PriceReport
-from app.models.savings import SavingsRecord
-from app.models.signin import SigninBoostRecord, SigninRecord
-from app.models.task import UserTask
 from app.models.user import User
-from app.models.wallet import CoinAccount
+from app.repositories import phone_rebind
 
 
 # ===== 创建时分配的标识:用户名(对外展示账号 ID)+ 默认昵称 =====
@@ -61,6 +43,33 @@ def _gen_nickname() -> str:
     )
 
 
+def is_default_nickname(nickname: str | None) -> bool:
+    """是否为创建时自动分配的默认昵称(= "用户" + 9 位字母数字,见 [_gen_nickname])。
+
+    这类不是用户主动设置的昵称,展示脱敏时按「无昵称」处理(走 id 规则,见 ops_marquee._mask_real)。
+    精确匹配生成格式(前缀 + 定长字母数字集),不误伤真人以「用户」开头的昵称(如「用户体验师」含汉字、
+    长度也不符)。用户改过昵称即不再匹配。"""
+    if not nickname:
+        return False
+    s = nickname.strip()
+    return (
+        len(s) == len(_NICKNAME_PREFIX) + _NICKNAME_LEN
+        and s.startswith(_NICKNAME_PREFIX)
+        and all(c in _NICKNAME_ALPHABET for c in s[len(_NICKNAME_PREFIX):])
+    )
+
+
+def apply_wechat_display_identity(
+    user: User, *, wechat_nickname: str | None, wechat_avatar_url: str | None
+) -> None:
+    """§10:用已有账号绑微信时,仅当展示字段仍为默认才用微信昵称/头像替换(两规则独立);
+    自定义(改过昵称/传过头像)则保留。只改内存对象,由调用方 commit。"""
+    if is_default_nickname(user.nickname) and wechat_nickname:
+        user.nickname = wechat_nickname
+    if user.avatar_url is None and wechat_avatar_url:
+        user.avatar_url = wechat_avatar_url
+
+
 def get_user_by_username(db: Session, username: str) -> User | None:
     return db.execute(
         select(User).where(User.username == username)
@@ -89,6 +98,85 @@ def get_user_by_phone(db: Session, phone: str) -> User | None:
     return db.execute(stmt).scalar_one_or_none()
 
 
+def get_user_by_wechat_openid(db: Session, openid: str) -> User | None:
+    stmt = select(User).where(User.wechat_openid == openid)
+    return db.execute(stmt).scalar_one_or_none()
+
+
+def touch_last_login(db: Session, user: User) -> User:
+    """openid 命中登录时更新 last_login_at(手机号登录在 upsert_user_for_login 里已更新)。"""
+    user.last_login_at = datetime.now(timezone.utc)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def attach_wechat_to_user(
+    db: Session, user: User, *, openid: str, wechat_nickname: str | None, wechat_avatar_url: str | None
+) -> User:
+    """继续绑定:把微信 openid + 微信源字段并入已存在账号(调用方保证 user.wechat_openid 为空)。
+
+    写 wechat_openid / wechat_nickname / wechat_avatar_url,并按 §10 规则回填展示字段:
+    仅当昵称仍为默认值(is_default_nickname)时用微信昵称替换,仅当头像为 null 时用微信头像替换;
+    用户已自定义的展示昵称/头像始终保留,两规则相互独立。
+    撞 openid 唯一约束(O 期间被别处绑走,极罕见)时由调用方捕获 IntegrityError 兜底降级为"只登入不绑"。
+    """
+    user.wechat_openid = openid
+    user.wechat_nickname = wechat_nickname
+    user.wechat_avatar_url = wechat_avatar_url
+    user.last_login_at = datetime.now(timezone.utc)
+    apply_wechat_display_identity(user, wechat_nickname=wechat_nickname, wechat_avatar_url=wechat_avatar_url)
+    db.commit()
+    db.refresh(user)
+    return user
+
+
+def _build_wechat_user(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+) -> User:
+    """构造并 db.add 一个微信账号行(register_channel='wechat',展示昵称头像取微信,缺则默认),
+    **不 commit**。create_wechat_user 与 rebind_account 共用,保证建号逻辑单一来源。"""
+    user = User(
+        phone=phone,
+        username=_gen_unique_username(db),
+        nickname=wechat_nickname or _gen_nickname(),
+        avatar_url=wechat_avatar_url,
+        register_channel="wechat",
+        wechat_openid=openid,
+        wechat_nickname=wechat_nickname,
+        wechat_avatar_url=wechat_avatar_url,
+        last_login_at=datetime.now(timezone.utc),
+    )
+    db.add(user)
+    return user
+
+
+def create_wechat_user(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+) -> User:
+    """微信登录新建账号(未占用分支)。见 _build_wechat_user。
+
+    openid 唯一约束是并发/重复绑定的最终防线(极罕见,openid 在 wechat-login 刚查过为空)。
+    """
+    user = _build_wechat_user(
+        db, phone=phone, openid=openid,
+        wechat_nickname=wechat_nickname, wechat_avatar_url=wechat_avatar_url,
+    )
+    db.commit()
+    db.refresh(user)
+    return user
+
+
 def upsert_user_for_login(
     db: Session,
     *,
@@ -133,63 +221,19 @@ def set_avatar_url(db: Session, user: User, *, avatar_url: str) -> User:
 
 
 def soft_delete_account(db: Session, user: User) -> None:
-    """注销账号:物理删除个人数据 + 清零余额 + 匿名化保留财务/关系 + 释放唯一约束。
+    """注销账号:软删除 + 匿名化 + 释放唯一约束/外部绑定。
 
-    删除策略(按"删了是否破坏对账 / 影响别人 / 是否 PII"分类):
-      物理删除(个人内容/成绩/行为/PII,只涉本人、删了不碰账目也不影响别人):比价/
-        省钱/签到/领券/任务/里程碑领取/埋点/引导标记/设备活跃/价格上报/反馈/看广告时长日志
-        (ad_watch_log:前端上报时长、不可信、非发奖依据,纯行为埋点),以及
-        邀请指纹(含 IP/机型/UA 的 PII,按 inviter_user_id 存 = 本人作为邀请人留的)。
-      清零保留:coin_account 的金币/现金/邀请金/累计收益归零(现金/邀请金已由端点
-        前置校验=0),行保留 —— 避免碰资金流水外键,也留作审计。
-      保留 + 随本行匿名化与身份解绑(动了会破坏对账/在途到账/发奖幂等/误伤邀请人):
-        三本资金流水(coin/cash/invite_cash_transaction)、提现单(pending 在途照常到账)、
-        微信转账授权(worker 对账 pending 要用)、广告发奖幂等记录(ad_reward 有 trans_id、
-        ad_feed_reward_record 有 client_event_id 唯一键,删了幂等键会致回调/重放重复发奖)、
-        广告 eCPM 收益记录(ad_ecpm_record 是内部收益统计/对账口径,同资金流水按对账保留)、
-        邀请关系(inviter/invitee 双向、不含 PII,删了会破坏邀请人侧归属)。这些表的 user_id
-        指向已匿名化的本行,身份已解绑。
+    把 phone 改成 `deleted_<id>` 释放手机号唯一约束,允许同号码重新注册成全新账号;
+    清空 PII(昵称/头像),保留行用于审计。status=deleted 后将无法再登录该行
+    (登录接口校验 status==active)。
 
-    ⚠️ 匿名化必须连同释放 user 其余唯一约束/外部身份,否则 deleted 行永久占着槽位:
+    ⚠️ 注销必须连同释放 user 上其余唯一约束/外部身份,否则 deleted 行永久占着槽位,
+    对应资源再也无法被复用:
       - wechat_openid: 不清 → 这个微信再也无法被任何账号绑定(提现通道彻底锁死);
       - invite_code:   不清 → 邀请码槽位被占 + 裸查仍命中死号(发奖已被 bind 的
         status==active 校验兜住,清掉更干净)。
-    资金安全(未提现现金/邀请金 / 在审提现单)由调用方 delete_account 端点前置校验。
+    资金安全(未提现现金 / 在审提现单)由调用方 delete_account 端点前置校验,这里只匿名化。
     """
-    uid = user.id
-
-    # 1) 物理删除个人内容/行为/成绩/PII 数据(不碰资金流水/账户/邀请关系/广告幂等)
-    personal_deletions = [
-        delete(ComparisonRecord).where(ComparisonRecord.user_id == uid),
-        delete(SavingsRecord).where(SavingsRecord.user_id == uid),
-        delete(SigninRecord).where(SigninRecord.user_id == uid),
-        delete(SigninBoostRecord).where(SigninBoostRecord.user_id == uid),
-        delete(CouponClaimRecord).where(CouponClaimRecord.user_id == uid),
-        delete(CouponDailyCompletion).where(CouponDailyCompletion.user_id == uid),
-        delete(CouponPromptEngagement).where(CouponPromptEngagement.user_id == uid),
-        delete(CouponSession).where(CouponSession.user_id == uid),
-        delete(UserTask).where(UserTask.user_id == uid),
-        delete(ComparisonMilestoneClaim).where(ComparisonMilestoneClaim.user_id == uid),
-        delete(DeviceLiveness).where(DeviceLiveness.user_id == uid),
-        delete(PriceReport).where(PriceReport.user_id == uid),
-        delete(Feedback).where(Feedback.user_id == uid),
-        delete(OnboardingCompletion).where(OnboardingCompletion.user_id == uid),
-        delete(AnalyticsEvent).where(AnalyticsEvent.user_id == uid),
-        delete(AdWatchLog).where(AdWatchLog.user_id == uid),
-        delete(InviteFingerprint).where(InviteFingerprint.inviter_user_id == uid),
-    ]
-    for stmt in personal_deletions:
-        db.execute(stmt)
-
-    # 2) 清零余额账户(现金/邀请金已前置=0;金币/累计收益一并归零,行保留不碰流水外键)
-    acc = db.get(CoinAccount, uid)
-    if acc is not None:
-        acc.coin_balance = 0
-        acc.cash_balance_cents = 0
-        acc.invite_cash_balance_cents = 0
-        acc.total_coin_earned = 0
-
-    # 3) 匿名化本行 + 释放唯一约束/外部身份(保留行:审计锚 + 资金流水/邀请关系外键不断)
     user.status = "deleted"
     user.phone = f"deleted_{user.id}"
     user.nickname = None
@@ -201,3 +245,44 @@ def soft_delete_account(db: Session, user: User) -> None:
     # 释放邀请码唯一槽
     user.invite_code = None
     db.commit()
+
+
+def rebind_account(
+    db: Session,
+    *,
+    phone: str,
+    openid: str,
+    wechat_nickname: str | None,
+    wechat_avatar_url: str | None,
+    source: str = "wechat_conflict",
+) -> User:
+    """换绑:**单事务内**注销老账号 X(腾出手机号)+ 用该号建全新微信账号 Y + 写换绑台账。
+
+    - 老账号可能已不存在(P 被腾空)→ old_user_id=None,直接建 Y(幂等更稳)。
+    - 手机号唯一约束靠时序:先把 X.phone 改名并 flush 腾号,再插 Y。
+    - 全程不中途 commit,任一步失败整体回滚,绝不出现"X 删了 Y 没建"。
+    X 的字段变更等价 soft_delete_account(软删 + 匿名化 + 释放 openid/邀请码唯一槽),但不在此 commit。
+    """
+    old = get_user_by_phone(db, phone)
+    old_id = old.id if old is not None else None
+    if old is not None:
+        old.status = "deleted"
+        old.phone = f"deleted_{old.id}"
+        old.nickname = None
+        old.avatar_url = None
+        old.wechat_openid = None
+        old.wechat_nickname = None
+        old.wechat_avatar_url = None
+        old.invite_code = None
+        db.flush()  # 先落 phone 改名,腾出手机号唯一约束,才能给 Y 用
+    new_user = _build_wechat_user(
+        db, phone=phone, openid=openid,
+        wechat_nickname=wechat_nickname, wechat_avatar_url=wechat_avatar_url,
+    )
+    db.flush()  # 拿 new_user.id
+    phone_rebind.add_rebind_log(
+        db, phone=phone, old_user_id=old_id, new_user_id=new_user.id, source=source
+    )
+    db.commit()
+    db.refresh(new_user)
+    return new_user