chore(alembic): 合并 analytics_active_idx + phone_rebind_log 两 head(修复多头)

既有多头——135e79414fd0(不活跃两表)与 phone_rebind_log 同从 comparison_llm_cost 分叉——
导致 `alembic upgrade head` 多头报错。加一个空 merge 修订汇合两头,upgrade head 恢复单头正常。

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

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

@@ -0,0 +1,36 @@
+"""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=show & page=home) ∪ 比价 ∪ 领券 过滤后
+group by user_id、max(created_at)。覆盖索引让该聚合走 index-only,避免高频 show 事件全表扫。
+
+⚠️ 本分支迁移树有**既有多头**: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/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/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/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

@@ -26,6 +26,7 @@ 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
@@ -97,6 +98,7 @@ 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)

app/admin/permissions.py

@@ -9,6 +9,9 @@ super_admin 为内建全权角色,恒可见全部页(effective_pages 特判)。
 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] = [

app/admin/repositories/ad_revenue.py

@@ -385,6 +385,27 @@ def ad_revenue_report(
         for k, v in type_map.items()
     }
 
+    # 分场景小计(按 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 筛选变化(活跃用户口径无这些维度)。
@@ -418,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_user.py

@@ -26,14 +26,17 @@ def create_admin(
     password: str,
     role: str = "operator",
     plain_password: str | None = None,
+    pages_override: list[str] | None = None,
 ) -> AdminUser:
     """建管理员。plain_password 非空则额外留存明文(后台 UI 建的账号传,供权限管理页复看);
-    脚本/起后台建账号不传(留 None → 前端不显示密码)。"""
+    脚本/起后台建账号不传(留 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,6 +18,7 @@ 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
@@ -30,6 +31,7 @@ from app.models.wallet import (
     InviteCashTransaction,
     WithdrawOrder,
 )
+from app.repositories import activity, ad_ecpm
 
 # 折算成可提现现金时,非广告金币来源的排除集(广告单独统计、人工调整不算"赚取")
 _NON_TASK_BIZ_TYPES = ("reward_video", "feed_ad_reward", "admin_grant", "admin_deduct")
@@ -82,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,
     *,
@@ -93,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_view + 比价 + 领券,见 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:
@@ -119,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:
@@ -186,6 +248,11 @@ def list_comparison_records(
         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
 
 

app/admin/repositories/stats.py

@@ -5,17 +5,23 @@ 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 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
@@ -24,11 +30,17 @@ 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,
@@ -299,12 +311,12 @@ def dashboard_overview(
         period_from=period_from,
         period_to=period_to,
     )
-    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
-    )
+    # 留存口径(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(
@@ -314,18 +326,26 @@ def dashboard_overview(
             ComparisonRecord.created_at >= day_start_local,
             ComparisonRecord.created_at < day_end_local,
         )
+        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.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(
-                    _period_active_user_ids(
-                        db,
-                        start_utc=day_start_utc,
-                        end_utc=day_end_utc,
-                        period_from=cur_date,
-                        period_to=cur_date,
-                    )
-                ),
+                "active_users": len(daily_active_user_ids),
                 "new_users": _count(
                     User,
                     User.created_at >= day_start_utc,
@@ -334,6 +354,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,
@@ -343,7 +368,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,
@@ -365,15 +390,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,
@@ -417,6 +456,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),
@@ -432,7 +563,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,
@@ -480,11 +611,13 @@ 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": {
@@ -495,6 +628,17 @@ def dashboard_overview(
                 "average_duration_ms": period_avg_duration_ms,
                 "average_saved_cents": period_avg_saved_cents,
             },
+            "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),
                 "reward_video_coin_total": period_reward_video_coin_total,

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,7 +5,7 @@ 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 SUPER_ADMIN_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
@@ -26,14 +26,22 @@ def _active_super_count(db: AdminDb) -> int:
 
 
 def _validate_role(db: AdminDb, role: str) -> None:
-    """角色必须是 super_admin 或 admin_role 表里已存在的角色,否则 400。"""
-    if role == SUPER_ADMIN_ROLE:
+    """角色必须是 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]:
     out: list[AdminOut] = []
@@ -51,13 +59,16 @@ def create_admin(
     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,
         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)
 
@@ -89,7 +100,8 @@ def update_admin(
         _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:
@@ -99,6 +111,17 @@ def update_admin(
         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()

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,7 @@ 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
@@ -19,9 +20,13 @@ router = APIRouter(prefix="/admin/api/auth", tags=["admin-auth"])
 
 
 def _admin_out_with_pages(admin, db: AdminDb) -> AdminOut:  # noqa: ANN001
-    """AdminOut + 当前角色有效可见页(前端左侧导航按此过滤)。"""
+    """AdminOut + 有效可见页(前端左侧导航按此过滤)。
+    role=="custom" → 用这个人的 pages_override(按人自定义,过滤悬空 key);其余走角色解析。"""
     out = AdminOut.model_validate(admin)
-    out.pages = role_repo.effective_pages_of(db, admin.role)
+    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
 
 

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

@@ -19,6 +19,8 @@ from app.admin.schemas.ops_marquee_seed import (
     OpsMarqueeSeedCreate,
     OpsMarqueeSeedOut,
     OpsMarqueeSeedUpdate,
+    OpsRealRecordItem,
+    OpsRealRecordsOut,
     OpsSavingsFeedPreviewOut,
 )
 from app.models.admin import AdminUser
@@ -68,6 +70,22 @@ def preview_feed(
     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:

app/admin/routers/users.py

@@ -42,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,
@@ -51,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(

app/admin/schemas/ad_revenue.py

@@ -136,6 +136,11 @@ 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="所选日期区间的去重活跃用户数(口径同数据大盘 period.users.active:登录 + 开始比价 + "

app/admin/schemas/admin.py

@@ -13,14 +13,18 @@ class AdminCreateRequest(BaseModel):
     username: str = Field(..., min_length=3, max_length=64)
     password: str = Field(..., min_length=8, max_length=72)  # bcrypt ≤72 字节
     role: str = Field("operator", min_length=1, max_length=32)
+    # 仅当 role == "custom":这个人专属可见页 key 列表(逐页勾选结果)。其余角色不传/忽略。
+    pages_override: list[str] | None = None
 
 
 class AdminUpdateRequest(BaseModel):
-    """改角色 / 启用禁用 / 重置密码,字段都可选(只改传了的)。"""
+    """改角色 / 启用禁用 / 重置密码 / 自定义可见页,字段都可选(只改传了的)。"""
 
     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

@@ -21,8 +21,11 @@ class AdminOut(BaseModel):
     created_at: datetime
     last_login_at: datetime | None = None
     # 该管理员当前角色的有效可见页(= 左侧导航项 key);仅登录 / /me 填充,列表接口默认空。
-    # 前端据此过滤左侧导航(super_admin = 全部页)。见 app/admin/permissions.py。
+    # 前端据此过滤左侧导航(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

app/admin/schemas/comparison.py

@@ -36,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
 
 
@@ -71,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,7 +43,10 @@ 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
 
@@ -57,6 +60,24 @@ class DashboardPeriodComparison(BaseModel):
     average_saved_cents: int | None = None
 
 
+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):
     granted_total: int
     reward_video_coin_total: int = 0
@@ -85,6 +106,7 @@ class DashboardPeriod(BaseModel):
     date_to: date
     users: DashboardPeriodUsers
     comparison: DashboardPeriodComparison
+    coupon: DashboardPeriodCoupon = DashboardPeriodCoupon()
     coins: DashboardPeriodCoins
     cash: DashboardPeriodCash
     trend: list[DashboardTrendPoint] = []

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

app/api/v1/ad.py

@@ -286,6 +286,7 @@ def ecpm_report(payload: EcpmReportIn, user: CurrentUser, db: DbSession) -> Ecpm
         ad_session_id=payload.ad_session_id,
         adn=payload.adn, slot_id=payload.slot_id,
         feed_scene=payload.feed_scene,
+        trace_id=payload.trace_id,
         app_env=payload.app_env, our_code_id=payload.our_code_id,
     )
     logger.info(

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/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,13 @@ class Settings(BaseSettings):
     # 进程内自动兑换 worker 的检查间隔(秒):每隔这么久醒一次,跨过北京 0 点就跑一轮。
     # 默认 600s=10min,即 0 点后最多 10 分钟内兑完(客户端文案已注明「可能存在延迟」)。
     AUTO_EXCHANGE_CHECK_INTERVAL_SEC: int = 600
+    # === 15 天不活跃清零(app.core.inactivity_reset_worker)===
+    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 +205,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 不同(后台各自

app/core/config_schema.py

@@ -96,4 +96,19 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
         "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,143 @@
+"""15 天不活跃清零的进程内每日任务。
+
+仿 daily_exchange_worker:App 启动自带,每 `INACTIVITY_RESET_CHECK_INTERVAL_SEC` 醒一次,
+跨进北京新的一天且到达 `INACTIVITY_RESET_RUN_HOUR`(默认 3 点)后跑一轮 `run_once`(预警 + 清零)。
+
+健壮性:
+- **逐用户幂等**:清完余额=0 次日不再匹配;预警按 streak 去重。启动补跑 / 多次唤醒 / 重启都安全。
+- **同机多进程互斥**:文件锁保证多 worker 只有一个实际跑。
+- **开关**:settings.INACTIVITY_RESET_ENABLED=false 时不启动(默认关,灰度验证后再开)。
+
+⚠️ 这是不可逆批量资金操作(清空金币 + 折算现金,**邀请现金不清**)。口径见
+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(),
+        )
+
+
+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",
+        interval,
+        settings.INACTIVITY_RESET_RUN_HOUR,
+    )
+    # 本进程上次跑过的北京日;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:
+    if not settings.INACTIVITY_RESET_ENABLED:
+        logger.info("inactivity reset disabled (INACTIVITY_RESET_ENABLED=false)")
+        return None
+    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/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"
 

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,6 +49,10 @@ 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.pricebot_client import aclose_pricebot_client, get_pricebot_client
 from app.core.withdraw_reconcile_worker import (
@@ -80,12 +84,14 @@ async def lifespan(_: FastAPI) -> AsyncIterator[None]:
     reconcile_task = start_withdraw_reconcile_worker()
     heartbeat_task = start_heartbeat_monitor()
     daily_exchange_task = start_daily_exchange_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_inactivity_reset_worker(inactivity_task)
         await aclose_pricebot_client()
         logger.info("shutting down")
 

app/models/__init__.py

@@ -7,6 +7,10 @@ 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
@@ -23,11 +27,16 @@ 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

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

@@ -28,8 +28,11 @@ class AdminUser(Base):
     # 明文登录密码:仅「后台 UI 创建/重置」的管理员留存,供超管在权限管理页复看转交。
     # 脚本/起后台时建的超管账号不写(为 None → 前端「不显示密码」)。⚠️ 内部工具便利取舍,见 create/list。
     plain_password: Mapped[str | None] = mapped_column(String(128), nullable=True)
-    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)
+    # 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/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,12 @@ from app.db.base import Base
 
 class AnalyticsEvent(Base):
     __tablename__ = "analytics_event"
+    __table_args__ = (
+        # 活跃口径聚合热点(activity.active_event_condition + last_active_subqueries):
+        # 按 (event,page) 过滤 首页可见(show/home)∪比价∪领券,再 group by user_id 取
+        # max(created_at)。覆盖索引 → 该聚合走 index-only,避免高频 show 事件全表扫。
+        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

@@ -137,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/repositories/activity.py

@@ -0,0 +1,101 @@
+"""活跃口径唯一真源:worker(不活跃清零)与 admin(最近活跃/DAU)共用,防两处漂移。
+
+口径 = max(User.created_at, AnalyticsEvent[首页可见 show/home + 比价 + 领券], 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 and_, func, or_, 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=show + page=home(组合判定,单个 event 名不足以区分,见
+# active_event_condition);其余为纯 event 名。
+HOME_VIEW_EVENT = "show"
+HOME_VIEW_PAGE = "home"
+COMPARE_START_EVENT = "real_compare_start"   # 发起比价(含浮窗触发)
+COUPON_START_EVENT = "real_coupon_start"     # 发起领券
+# 纯 event 名即可判定的活跃事件(首页可见是 event+page 组合、不在此列)
+ACTIVE_EVENTS = (COMPARE_START_EVENT, COUPON_START_EVENT)
+ACTIVE_ENGAGE_TYPE = "claim_started"         # coupon_prompt_engagement 一键领取
+
+
+def active_event_condition():
+    """analytics_event 中算"活跃"的行为过滤:首页可见(event=show & page=home)
+    ∪ 发起比价 ∪ 发起领券。worker 子查询与 admin 展示共用,单一真源。"""
+    return or_(
+        and_(AnalyticsEvent.event == HOME_VIEW_EVENT, AnalyticsEvent.page == HOME_VIEW_PAGE),
+        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,6 +10,7 @@ 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
 
@@ -24,6 +25,7 @@ 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,
 ) -> AdEcpmRecord:
@@ -43,6 +45,7 @@ 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,
@@ -105,3 +108,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/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/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,183 @@
+"""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) -> bool:
+    """单用户清零(独立事务、行锁)。金币 + 折算现金归零 + 写审计 + 2 条流水;**邀请现金不清**
+    (产品红线,见 wallet.CoinAccount 注释),仅作快照记入审计。返回是否真清了(有可清余额)。"""
+    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
+    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 交叉链接审计↔流水
+    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) -> dict:
+    """扫一轮清零。逐用户独立 commit,失败隔离。"""
+    stats = {"scanned": 0, "cleared": 0, "failed": 0}
+    cutoff = activity.reset_cutoff(reset_days, today)
+    reason = f"inactive_{reset_days}d"
+    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):
+                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) -> dict:
+    """一轮完整任务:先预警(阶段 A)再清零(阶段 B)。返回合并统计。
+    预警整段异常也**绝不阻塞清零**——清零是核心、不可逆资金操作,不能被通知故障拖住。"""
+    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)
+    return {**warn, **reset}

app/repositories/ops_marquee.py

@@ -217,12 +217,28 @@ def _recent_real_rows(db: Session) -> list[tuple[int, int, str | None]]:
     return out
 
 
+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 北京)}。
 
     mode:显式传入(admin 预览指定模式)则用它、**不改持久化配置**;不传(客户端 /savings-feed)读
     持久化的 marquee_feed_mode;非法值一律回退到持久化模式。
-    真实条:success 且 0 < saved ≤ 上限,按 user 去重(同一用户只取最新一条,避免单人刷屏)。
+    真实条:success 且 0 < saved ≤ 上限,**不按 user 去重**(打乱 + 去连簇:相邻尽量不同用户、减少单人连刷)后取前 limit。
     不足用启用的种子补齐——**公平随机抽取** need 个(而非固定取前 N),让所有种子都有机会露出;
     种子用户名留空则随机合成(避开撞名),金额取**长尾随机**(小额居多、偶尔大额,更像真实分布)。
     真实 + 种子仍不满 limit → 内置合成条**补满**,保证轮播既不空也不稀疏。
@@ -235,19 +251,13 @@ def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]
     items: list[dict] = []
     used_names: set[str] = set()
 
-    # 真实条(mixed / real):取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
+    # 真实条(mixed / real):**不按 user 去重**——打乱 + 去连簇(相邻尽量不同用户、减少单人连刷)后取前
+    # limit;金额超上限的异常值已在查询剔除。同一用户可多条露出,但被打散、尽量不连续。
     if mode != "seed":
-        rows = _recent_real_rows(db)
-        seen_users: set[int] = set()
-        for uid, sc, nick in rows:
-            if uid in seen_users:
-                continue
-            seen_users.add(uid)
+        for uid, sc, nick in _shuffle_declustered(_recent_real_rows(db))[:limit]:
             name = _mask_real(nick, uid)
-            used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
+            used_names.add(name)  # 同一用户可多条,名字重复无害(used_names 仅供种子避重)
             items.append({"masked_user": name, "saved_amount_cents": int(sc)})
-            if len(items) >= limit:
-                break
 
     # 种子补位 + 合成兜底(mixed / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
     # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
@@ -300,6 +310,78 @@ def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> 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/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/user.py

@@ -12,6 +12,7 @@ from sqlalchemy import select
 from sqlalchemy.orm import Session
 
 from app.models.user import User
+from app.repositories import phone_rebind
 
 
 # ===== 创建时分配的标识:用户名(对外展示账号 ID)+ 默认昵称 =====
@@ -58,6 +59,17 @@ def is_default_nickname(nickname: str | None) -> bool:
     )
 
 
+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)
@@ -86,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,
     *,
@@ -154,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

app/repositories/wallet.py

@@ -11,7 +11,7 @@ import unicodedata
 import uuid
 from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import select, update
+from sqlalchemy import func, select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -20,6 +20,7 @@ from app.core.config import settings
 from app.core.rewards import COIN_PER_CENT, coins_to_cents
 from app.integrations import wxpay
 from app.models.user import User
+from app.repositories.user import apply_wechat_display_identity
 from app.models.wallet import (
     CashTransaction,
     CoinAccount,
@@ -34,6 +35,10 @@ _WX_STATE_SUCCESS = "SUCCESS"
 _WX_STATE_FAILED = {"FAIL", "CANCELLED", "CLOSED"}
 _WX_STATE_WAIT_CONFIRM = "WAIT_USER_CONFIRM"  # 用户还没在微信确认页确认
 _WITHDRAW_ACTIVE_STATUSES = {"reviewing", "pending"}
+# 占用新人档「一次性」资格的提现状态:进行中(reviewing/pending)或成功打款(success)。
+# 被拒/转账失败/解绑退回(rejected/failed,均已退款、钱没到手)不在此列 → 新人档恢复可提
+# (2026-07-16 修正:此前判定不看状态,解绑微信退回后 0.1 被误判已用、资格永久锁死)。
+_NEWBIE_TIER_HELD_STATUSES = {"reviewing", "pending", "success"}
 # 免确认收款授权状态
 _WX_AUTH_ACTIVE = "TAKING_EFFECT"   # 已生效,可免确认转账
 _WX_AUTH_CLOSED = "CLOSED"          # 已关闭(用户/商户/风控),需重新开启
@@ -67,6 +72,10 @@ class WithdrawTooFrequentError(Exception):
     """提现申请过于频繁,或已有未完成提现单。"""
 
 
+class WithdrawTierUnavailableError(Exception):
+    """该档位今日不可提:次数已满,或今天已选了其他额度(7-9 福利页档位规则)。"""
+
+
 class WithdrawTransferError(Exception):
     """调用微信转账失败(已退回余额)。"""
 
@@ -370,6 +379,7 @@ def bind_wechat_openid(db: Session, user_id: int, code: str) -> dict:
     user.wechat_openid = info["openid"]
     user.wechat_nickname = info["nickname"]
     user.wechat_avatar_url = info["avatar_url"]
+    apply_wechat_display_identity(user, wechat_nickname=info["nickname"], wechat_avatar_url=info["avatar_url"])
     db.commit()
     return info
 
@@ -605,6 +615,91 @@ def _settle_after_ambiguous(db: Session, order: WithdrawOrder, reason: str) -> N
         db.commit()
 
 
+def _beijing_today_start_utc() -> datetime:
+    """北京时今日 0 点(转 UTC)。WithdrawOrder.created_at 是 func.now()(UTC)存储,
+    比较时统一转 UTC,与 admin 看板 today_start 同口径(admin/repositories/queries.py)。"""
+    return (
+        datetime.now(rewards.CN_TZ)
+        .replace(hour=0, minute=0, second=0, microsecond=0)
+        .astimezone(timezone.utc)
+    )
+
+
+def withdraw_tier_states(db: Session, user_id: int, source: str = "coin_cash") -> list[dict]:
+    """福利页(coin_cash)提现档位的可提现状态。withdraw-info 下发与 create_withdraw 校验共用此口径。
+
+    规则(2026-07-09 拍板,7-9提现ui对齐;新人档判定 2026-07-16 修正):
+      - 新人档(0.1/0.3):账号历史一次性——进行中(reviewing/pending)或成功打款(success)即视为
+        已用,直接**从返回列表消失**;被拒/转账失败/解绑退回(均已退款、钱没到手)则恢复可提,不永久
+        占用资格。两档各自独立互不影响,不参与"每日选一个额度"互斥。
+      - 常规档(0.5×3 / 10×1 / 20×1):按北京日计次,"发起就算占用"(当天创建的单不论最终状态
+        都计入,被拒/失败不退当天名额);三档每天只能选一个,选定后其余两档当天 other_tier_selected。
+      - invite_cash 本轮无档位概念 → 返回空列表(邀请页客户端仍用本地写死档位,行为不变)。
+    余额是否足够由客户端本地判断(余额随兑换实时变化,不在此快照)。
+    """
+    if source != "coin_cash":
+        return []
+    tiers = rewards.WITHDRAW_TIERS_COIN_CASH
+    amounts = [t.amount_cents for t in tiers]
+    newbie_amounts = [t.amount_cents for t in tiers if t.is_newbie]
+    # 新人档历史是否用过:进行中或已成功打款的单占用资格;被拒/失败/解绑退回(已退款)不算(恢复可提)
+    used_newbie: set[int] = set(
+        db.execute(
+            select(WithdrawOrder.amount_cents)
+            .distinct()
+            .where(
+                WithdrawOrder.user_id == user_id,
+                WithdrawOrder.source == "coin_cash",
+                WithdrawOrder.amount_cents.in_(newbie_amounts),
+                WithdrawOrder.status.in_(_NEWBIE_TIER_HELD_STATUSES),
+            )
+        ).scalars()
+    ) if newbie_amounts else set()
+    # 今日(北京日)每档已发起次数(任意状态)
+    today_counts: dict[int, int] = {
+        int(amount): int(cnt)
+        for amount, cnt in db.execute(
+            select(WithdrawOrder.amount_cents, func.count(WithdrawOrder.id))
+            .where(
+                WithdrawOrder.user_id == user_id,
+                WithdrawOrder.source == "coin_cash",
+                WithdrawOrder.amount_cents.in_(amounts),
+                WithdrawOrder.created_at >= _beijing_today_start_utc(),
+            )
+            .group_by(WithdrawOrder.amount_cents)
+        )
+    }
+    # "每日选一个额度":今天发起过的常规档(新人档不算)
+    selected_regular = next(
+        (t.amount_cents for t in tiers if not t.is_newbie and today_counts.get(t.amount_cents, 0) > 0),
+        None,
+    )
+    out: list[dict] = []
+    for t in tiers:
+        if t.is_newbie:
+            if t.amount_cents in used_newbie:
+                continue  # 用过即消失,不再下发
+            out.append({
+                "amount_cents": t.amount_cents, "label": t.label, "badge": t.badge,
+                "is_newbie": True, "available": True, "disabled_reason": None,
+                "remaining_today": 1,
+            })
+            continue
+        used = today_counts.get(t.amount_cents, 0)
+        if selected_regular is not None and selected_regular != t.amount_cents:
+            available, reason, remaining = False, "other_tier_selected", 0
+        elif used >= t.daily_limit:
+            available, reason, remaining = False, "quota_exhausted", 0
+        else:
+            available, reason, remaining = True, None, t.daily_limit - used
+        out.append({
+            "amount_cents": t.amount_cents, "label": t.label, "badge": t.badge,
+            "is_newbie": False, "available": available, "disabled_reason": reason,
+            "remaining_today": remaining,
+        })
+    return out
+
+
 def create_withdraw(
     db: Session,
     user_id: int,
@@ -660,6 +755,19 @@ def create_withdraw(
     if active_order_id is not None:
         raise WithdrawTooFrequentError
 
+    # 福利页档位闸(7-9):coin_cash 只能提预设档位,且该档今日可提(服务端权威口径,防绕过
+    # 客户端刷)。放在幂等返回/在途互斥之后:同号重试仍原样返回旧单,不被档位闸误杀。
+    # allow_sub_min(0.01 调试直发)保持原样放行,不受档位约束;invite_cash 本轮无档位概念不校验。
+    if source == "coin_cash" and not allow_sub_min:
+        tier_state = next(
+            (t for t in withdraw_tier_states(db, user_id, source) if t["amount_cents"] == amount_cents),
+            None,
+        )
+        if tier_state is None:  # 非预设档位金额,或新人档已用过(已从列表消失)
+            raise InvalidWithdrawAmountError
+        if not tier_state["available"]:
+            raise WithdrawTierUnavailableError
+
     # 账户须存在(原子扣款的 UPDATE 不会建账户)
     get_or_create_account(db, user_id, commit=True)
 

app/schemas/ad.py

@@ -63,6 +63,12 @@ class EcpmReportIn(BaseModel):
         description="点位场景:comparison(比价等待) / coupon(领券) / welfare(福利页);"
         "比价与领券共用同一 Draw 代码位,需客户端在各调用点显式标注,供收益报表区分比价/领券;激励视频为空",
     )
+    trace_id: str | None = Field(
+        None,
+        max_length=64,
+        description="本次比价/领券 trace_id(信息流场景带上):把这条展示收益归属到对应比价/领券,"
+        "供领券数据/比价记录看板聚合本场广告收益;激励视频/福利为空",
+    )
     app_env: str | None = Field(
         None, max_length=16, description="我们的穿山甲应用环境:prod(傻瓜比价正式) / test(测试应用)"
     )

app/schemas/analytics_selfstat.py

@@ -0,0 +1,34 @@
+"""自报计数上报 schema。字段名对齐客户端 payload(snake_case),累计值语义。"""
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SelfStatEventIn(BaseModel):
+    event: str = Field(max_length=64)
+    attempted: int = 0
+    drop_capture: int = 0
+    delivered: int = 0
+    drop_undelivered: int = 0
+
+
+class SelfStatBatchIn(BaseModel):
+    device_id: str = Field(max_length=64)
+    epoch_id: str = Field(max_length=64)
+    sent_at: int | None = None
+    app_ver: str | None = Field(default=None, max_length=32)
+    oem: str | None = Field(default=None, max_length=32)
+    os: str | None = Field(default=None, max_length=32)
+    batches_attempted: int = 0
+    batches_ok: int = 0
+    batches_fail: int = 0
+    retries: int = 0
+    queue_depth: int = 0
+    # 允许空列表:某次快照只上报设备级计数(batches_*/retries/queue_depth)、无 event 细分时也合法
+    # (与 AnalyticsBatchIn 的 min_length=1 有意不同——那是行为事件、必须至少一条)。
+    events: list[SelfStatEventIn] = Field(default_factory=list, max_length=200)
+
+
+class SelfStatIngestOut(BaseModel):
+    ok: bool = True
+    snapshot_id: int

app/schemas/auth.py

@@ -102,3 +102,64 @@ class RefreshRequest(BaseModel):
 
 class LogoutResponse(BaseModel):
     ok: bool = True
+
+
+# ===== 微信登录 =====
+
+class WechatLoginRequest(BaseModel):
+    code: str = Field(..., min_length=1, description="微信 App 授权拿到的 code(单次有效)")
+    device_id: str = Field(
+        "", max_length=64,
+        description="硬件级设备标识(Android ANDROID_ID),用于新手引导按 设备+账号 去重;空=按未完成处理",
+    )
+
+
+class WechatLoginResponse(BaseModel):
+    # status="logged_in" → openid 命中,token 有值;"need_bind_phone" → 未命中,bind_ticket 有值
+    status: str
+    token: TokenWithUser | None = None
+    bind_ticket: str | None = None
+    wechat_nickname: str | None = None
+    wechat_avatar_url: str | None = None
+
+
+class OccupiedAccountInfo(BaseModel):
+    """手机号被占用时返回的原账号脱敏展示信息(供冲突页)。"""
+    nickname: str | None = None
+    avatar_url: str | None = None
+    created_at: datetime
+    has_wechat: bool = False
+
+
+class WechatBindResultResponse(BaseModel):
+    # status="logged_in" → 未占用,已建号登入,token 有值;
+    # "phone_occupied" → 手机号被占用,occupied_account + conflict_ticket 有值,token 为 None
+    status: str
+    token: TokenWithUser | None = None
+    occupied_account: OccupiedAccountInfo | None = None
+    conflict_ticket: str | None = None            # 占用时签发,换绑/继续绑定只认它
+    rebind_available: bool | None = None          # 该手机号 30 天内是否还能换绑(给换绑按钮预置禁用态)
+    rebind_blocked_days: int | None = None        # 被限时剩余天数(rebind_available=False 时>0)
+
+
+class WechatBindPhoneSmsRequest(BaseModel):
+    bind_ticket: str = Field(..., min_length=1)
+    phone: str = Field(..., min_length=11, max_length=11, pattern=r"^1\d{10}$")
+    code: str = Field(..., min_length=4, max_length=8)
+    device_id: str = Field("", max_length=64)
+
+
+class WechatBindPhoneJverifyRequest(BaseModel):
+    bind_ticket: str = Field(..., min_length=1)
+    login_token: str = Field(..., min_length=1, description="客户端 loginAuth 拿到的 loginToken")
+    device_id: str = Field("", max_length=64)
+
+
+class WechatConflictContinueRequest(BaseModel):
+    conflict_ticket: str = Field(..., min_length=1)
+    device_id: str = Field("", max_length=64)
+
+
+class WechatConflictRebindRequest(BaseModel):
+    conflict_ticket: str = Field(..., min_length=1)
+    device_id: str = Field("", max_length=64)

app/schemas/welfare.py

@@ -75,6 +75,21 @@ class ExchangeResultOut(BaseModel):
 
 # ===== 提现(现金 → 微信零钱) =====
 
+class WithdrawTierOut(BaseModel):
+    """提现档位(福利页 coin_cash;7-9 对齐原型)。served by rewards.WITHDRAW_TIERS_COIN_CASH。"""
+
+    amount_cents: int = Field(..., description="档位金额(分)")
+    label: str = Field(..., description="档位方块展示文案,如 0.1 / 10")
+    badge: str | None = Field(None, description="角标文案(如 新人福利);无则空")
+    is_newbie: bool = Field(False, description="新人档:历史一次性,用过后不再下发;免广告直提")
+    available: bool = Field(True, description="当前是否可提(次数/选一额度口径;余额由客户端自判)")
+    disabled_reason: str | None = Field(
+        None,
+        description="不可提原因:quota_exhausted(今日次数满) / other_tier_selected(今日已选其他额度)",
+    )
+    remaining_today: int = Field(0, description="今日剩余可提次数")
+
+
 class WithdrawInfoOut(BaseModel):
     min_cents: int = Field(..., description="单次最低提现(分)")
     max_cents: int = Field(..., description="单次最高提现(分)")
@@ -84,6 +99,10 @@ class WithdrawInfoOut(BaseModel):
     transfer_auth_enabled: bool = Field(
         False, description="是否已开启免确认到账(开启后提现免跳微信确认,直接到账)"
     )
+    tiers: list[WithdrawTierOut] = Field(
+        default_factory=list,
+        description="提现档位(source=coin_cash 下发;invite_cash 为空,客户端走旧逻辑)",
+    )
 
 
 # ===== 免确认收款授权(用户授权免确认模式)=====

app/services/llm_cost.py

@@ -0,0 +1,53 @@
+"""LLM 调用成本计算(纯逻辑,无 DB):按 model 分桶累加 token × 单价,返回总成本(元)+ 价格快照。
+
+用量取自 comparison_record.llm_calls[].usage(pricebot 已归一为 prompt/completion_tokens);
+error / 无 usage 的调用跳过。price_cfg = {per_model:{model:{input_per_1m,output_per_1m}}, default:{...}}。
+成本单位「元」——单次亚分级,用 float(不用 *_cents);snapshot 只含本次用到的模型的价(审计用,
+不存整张价表)。用到但没配价(既无 per_model 又无 default)的模型 → 快照标 unpriced,成本按 0 计。
+"""
+from __future__ import annotations
+
+_PRICE_KEY = "llm_token_price"
+
+
+def get_llm_prices(db) -> dict:
+    """读 LLM 单价配置(app_config;表内无则回退 CONFIG_DEFS 默认)。返回 compute_llm_cost 的 price_cfg。"""
+    from app.repositories import app_config  # 延迟 import:compute_llm_cost 纯逻辑不牵连 DB 层
+    return app_config.get_value(db, _PRICE_KEY)
+
+
+def compute_llm_cost(calls: list[dict], price_cfg: dict) -> tuple[float | None, dict | None]:
+    """遍历 calls 按 model 分桶,cost = Σ(入/1e6*入价 + 出/1e6*出价);无有效调用 → (None, None)。"""
+    if not calls:
+        return None, None
+    per_model = price_cfg.get("per_model") or {}
+    default = price_cfg.get("default")
+    buckets: dict[str, list[int]] = {}  # model -> [Σprompt_tokens, Σcompletion_tokens]
+    for c in calls:
+        if c.get("error"):
+            continue
+        usage = c.get("usage") or {}
+        model = c.get("model") or "unknown"
+        b = buckets.setdefault(model, [0, 0])
+        b[0] += usage.get("prompt_tokens") or 0
+        b[1] += usage.get("completion_tokens") or 0
+    if not buckets:  # 全是 error / 无 usage
+        return None, None
+    total = 0.0
+    prices: dict[str, dict] = {}
+    for model, (tin, tout) in buckets.items():
+        price = per_model.get(model, default)
+        in_p = price.get("input_per_1m") if isinstance(price, dict) else None
+        out_p = price.get("output_per_1m") if isinstance(price, dict) else None
+        # 没配价 / 无 default / 单价残缺或非法(配置页手改 JSON 可能存出脏数据)→ 标记待补价、
+        # 不计入成本;绝不抛异常,以免连累同一回填里的 token/llm_calls 落库。
+        if not isinstance(in_p, (int, float)) or not isinstance(out_p, (int, float)):
+            prices[model] = {"input_per_1m": in_p, "output_per_1m": out_p, "unpriced": True}
+            continue
+        total += tin / 1e6 * in_p + tout / 1e6 * out_p
+        prices[model] = {
+            "input_per_1m": in_p,
+            "output_per_1m": out_p,
+            "_source": "per_model" if model in per_model else "default",
+        }
+    return round(total, 6), {"mode": "per_model", "prices": prices}

docs/api/README.md

@@ -3,7 +3,7 @@
 > Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
 > 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
-> 最后更新:2026-07-03（补全缺失文档:ad/watch-report, wallet/transfer-auth 族, coupon/session+stats+completed-today+prompt 族, invite 族, user/onboarding, platform/flags+ad-config+app-version, intent/step+precoupon/step, analytics/events, order/report, report 族, feedback/config+records, trace/finalize。文档移至分类子目录,新增 mock 入参/出参示例）
+> 最后更新:2026-07-09（① 比价透传改「软鉴权 + trace_id 签发 + harvest 落库」(#112 尾声帧 `trace/epilogue` 一并补录);② 新端点:`user/onboarding/reset`(#114)、`GET /internal/launch-confirm-samples`(#91);③ 参数更新:提现族 `source` 分账(#82/#121)、`wallet/account` 邀请奖励金余额、美团 feed/top-sales 按城市过滤(#116)、admin 调现金 `account` 目标账户(#95);④ **Admin 索引补全到当前全量**:新家族 roles(#117/#126)/coupon-data(#99)/device-liveness(#80)/event-logs(#83)/price-reports(#94)/CPS 运营台/提现审核族,及 feedbacks 采纳拒绝(#94/#105)、marquee 模式与真实条浏览(#122/#123)等。上一次 2026-07-03）
 > 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
 
 ---
@@ -27,17 +27,18 @@
 | 8e | `GET /api/v1/coupon/completed-today` | 无 | [详情](./coupon/coupon-completed-today.md)（这台设备今天是否已跑完整轮领券） |
 | 8f | `POST /api/v1/coupon/completed-today/reset` | 无 | [详情](./coupon/coupon-completed-today.md)（重置今日已完成,开发用） |
 | 8g | `GET /api/v1/coupon/stats` | Bearer | [详情](./coupon/coupon-stats.md)（累计领券数,「我的」页战绩卡） |
-| 8h | `POST /api/v1/coupon/session` | 无 | [详情](./coupon/coupon/coupon-session.md)（领券流水上报,admin 看板数据源） |
+| 8h | `POST /api/v1/coupon/session` | 无 | [详情](./coupon/coupon-session.md)（领券流水上报,admin 看板数据源） |
 | 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan/meituan-coupons.md) |
-| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan/meituan-feed.md) |
+| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan/meituan-feed.md)（`rec` tab 离线库 + **按城市过滤** #116） |
 | 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan/meituan-referral-link.md) |
-| 11a | `POST /api/v1/meituan/top-sales` | 无 | [详情](./meituan/meituan-top-sales.md)（销量榜:离线库 `meituan_coupon` 按销量降序 + 跨源去重,不实时打美团） |
-| **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend；下按 Phase 流程列,均不鉴权） |||
-| 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./intent/compare-intent-recognize.md)（Phase 1 意图识别,单次,多数源） |
-| 12a | `POST /api/v1/intent/precoupon/step` | 无 | [详情](./intent/intent-step.md)（Phase 0 意图识别前先用券,仅美团源） |
-| 12b | `POST /api/v1/intent/step` | 无 | [详情](./intent/intent-step.md)（Phase 1 多帧意图识别,仅淘宝源,循环到 done） |
-| 13 | `POST /api/v1/price/step` | 无 | [详情](./intent/compare-price-step.md)（Phase 2 步进） |
-| 13a | `POST /api/v1/trace/finalize` | 无 | [详情](./other/trace-finalize.md)（比价 trace 收尾上云,终止/未识别拿 trace_url） |
+| 11a | `POST /api/v1/meituan/top-sales` | 无 | [详情](./meituan/meituan-top-sales.md)（同城销量榜:离线库按销量降序 + 跨源去重 + 城市过滤 #116,不实时打美团） |
+| **比价透传**（前缀 `/api/v1`,透传 pricebot-backend;**软鉴权 OptionalUser** + 首帧签发 trace_id + harvest 落 `comparison_record`,2026-07 起不再是纯透传） |||
+| 12 | `POST /api/v1/intent/recognize` | 软 | [详情](./intent/compare-intent-recognize.md)（Phase 1 意图识别,单次,多数源;mint 帧建 running 行） |
+| 12a | `POST /api/v1/intent/precoupon/step` | 软 | [详情](./intent/intent-step.md)（Phase 0 意图识别前先用券,仅美团源） |
+| 12b | `POST /api/v1/intent/step` | 软 | [详情](./intent/intent-step.md)（Phase 1 多帧意图识别,仅淘宝源,循环到 done） |
+| 13 | `POST /api/v1/price/step` | 软 | [详情](./intent/compare-price-step.md)（Phase 2 步进;done 帧 harvest 写终态） |
+| 13a | `POST /api/v1/trace/finalize` | 软 | [详情](./other/trace-finalize.md)（比价 trace 收尾上云 + 夭折落库,终止/未识别拿 trace_url） |
+| 13b | `POST /api/v1/trace/epilogue` | 软 | [详情](./other/trace-finalize.md)（结果页尾声帧:App 结果页截图入 trace,纯透传不落库,#112） |
 | **比价记录**（前缀 `/api/v1/compare`；按用户落库，**鉴权**，区别于上面不鉴权的透传） |||
 | 12a | `POST /api/v1/compare/record` | Bearer | [详情](./compare/compare-record-report.md) |
 | 12b | `GET /api/v1/compare/records` | Bearer | [详情](./compare/compare-records.md) |
@@ -54,7 +55,7 @@
 | **上报更低价**（前缀 `/api/v1/report`；众包纠偏,人工审核发奖） |||
 | R1 | `POST /api/v1/report` | Bearer | [详情](./other/report-submit.md)（提交上报更低价,multipart:比价记录ID+平台+价格+截图1-4张） |
 | R2 | `GET /api/v1/report/records` | Bearer | [详情](./other/report-records.md)（上报记录列表,?status=pending/approved/rejected 可选筛选） |
-| **好友邀请**（前缀 `/api/v1/invite`；注册即生效,双方各发 1 万金币） |||
+| **好友邀请**（前缀 `/api/v1/invite`；绑定注册即生效但**不发奖**,#113 起好友「比价并下单」才给邀请人发**邀请奖励金**,经 `POST /order/report` 触发） |||
 | I1 | `GET /api/v1/invite/me` | Bearer | [详情](./invite/invite-me.md)（我的邀请码+分享链接+已邀人数/已得金币） |
 | I2 | `GET /api/v1/invite/invitees` | Bearer | [详情](./invite/invite-invitees.md)（我邀请的人列表,limit/offset 分页） |
 | I3 | `POST /api/v1/invite/landing-track` | 无 | [详情](./invite/invite-bind.md)（落地页 dl.html 访问上报指纹,剪贴板归因兜底;浏览器无 token） |
@@ -68,9 +69,9 @@
 | 19 | `POST /api/v1/wallet/bind-wechat` | Bearer | [详情](./wallet/wallet-bind-wechat.md) |
 | 20 | `POST /api/v1/wallet/unbind-wechat` | Bearer | [详情](./wallet/wallet-unbind-wechat.md) |
 | 21 | `GET /api/v1/wallet/withdraw-info` | Bearer | [详情](./wallet/wallet-withdraw-info.md) |
-| 22 | `POST /api/v1/wallet/withdraw` | Bearer | [详情](./wallet/wallet-withdraw.md) |
+| 22 | `POST /api/v1/wallet/withdraw` | Bearer | [详情](./wallet/wallet-withdraw.md)（`source` 分账:coin_cash / invite_cash,#121） |
 | 23 | `GET /api/v1/wallet/withdraw/status` | Bearer | [详情](./wallet/wallet-withdraw-status.md) |
-| 24 | `GET /api/v1/wallet/withdraw-orders` | Bearer | [详情](./wallet/wallet-withdraw-orders.md) |
+| 24 | `GET /api/v1/wallet/withdraw-orders` | Bearer | [详情](./wallet/wallet-withdraw-orders.md)（可按 `source` 过滤） |
 | 24a | `POST /api/v1/wallet/transfer-auth` | Bearer | [详情](./wallet/wallet-transfer-auth.md)（开启免确认到账,申请授权,返回拉起微信授权页的 package） |
 | 24b | `GET /api/v1/wallet/transfer-auth/status` | Bearer | [详情](./wallet/wallet-transfer-auth.md)（查免确认授权状态,从微信授权页返回后轮询） |
 | 24c | `POST /api/v1/wallet/transfer-auth/close` | Bearer | [详情](./wallet/wallet-transfer-auth.md)（关闭免确认到账,解除授权） |
@@ -99,6 +100,7 @@
 | 36 | `POST /api/v1/user/avatar` | Bearer | [详情](./user/user-avatar.md) |
 | 36a | `POST /api/v1/user/onboarding/complete` | Bearer | [详情](./user/user-onboarding.md)（标记新手引导完成,按 账号+device_id 幂等,跨卸载重装持久） |
 | 36b | `GET /api/v1/user/onboarding/status` | Bearer | [详情](./user/user-onboarding.md)（查该 账号+设备 是否走过引导,运营在 admin 删记录即触发重走） |
+| 36c | `POST /api/v1/user/onboarding/reset` | Bearer | [详情](./user/user-onboarding.md)（重置本设备引导标记,下次登录重走,#114） |
 | 37 | `DELETE /api/v1/user` | Bearer | [详情](./user/user-delete.md) |
 | **帮助与反馈**（前缀 `/api/v1/feedback`） |||
 | 38 | `POST /api/v1/feedback` | Bearer | [详情](./other/feedback.md) |
@@ -127,43 +129,37 @@
 | N4 | `POST /internal/store-mapping/invalidate` | 内部密钥 | [详情](./internal/internal.md)（标记某平台 shopId 缓存 deeplink 失效） |
 | N5 | `POST /internal/launch-confirm-sample` | 内部密钥 | [详情](./internal/internal.md)（启动确认窗兜底样本落 `launch_confirm_sample`） |
 | N6 | `POST /internal/app-version` | 内部密钥 | [详情](./internal/internal.md)（发布流程写最新 App 版本,落 `app_config`） |
+| N7 | `GET /internal/launch-confirm-samples` | 内部密钥 | [详情](./internal/internal.md)（样本列表,供 pricebot distill 脚本聚合沉淀回静态规则,#91） |
 | **静态资源**（StaticFiles 挂载,见下方 `/media` 静态服务） |||
 | - | `GET /media/avatars/<file>` | 无 | 用户头像;返回二进制图片 |
 | - | `GET /media/feedback/<file>` | 无 | 反馈截图;返回二进制图片 |
-| **运营后台 Admin**（独立子应用 `app/admin/`,前缀 `/admin/api`,独立进程 + 独立 admin JWT。鉴权列:`admin`=任意已登录管理员,`operator`/`finance`/`super_admin`=需对应角色（`super_admin` 恒通过）） |||
-| A1 | `POST /admin/api/auth/login` | 无 | [详情](./admin/auth/admin-auth-login.md) |
-| A2 | `GET /admin/api/auth/me` | admin | [详情](./admin/auth/admin-auth-me.md) |
-| A3 | `GET /admin/api/stats/overview` | admin | [详情](./admin/admin-stats-overview.md) |
-| A4 | `GET /admin/api/users` | admin | [详情](./admin/users/admin-users-list.md) |
-| A5 | `GET /admin/api/users/{user_id}` | admin | [详情](./admin/users/admin-user-detail.md) |
-| A6 | `POST /admin/api/users/{user_id}/status` | operator | [详情](./admin/users/admin-user-status.md) |
-| A7 | `POST /admin/api/users/{user_id}/coins` | finance | [详情](./admin/users/admin-user-coins.md) |
-| A8 | `POST /admin/api/users/{user_id}/cash` | finance | [详情](./admin/users/admin-user-cash.md) |
-| A9 | `GET /admin/api/wallet/coin-transactions` | admin | [详情](./admin/wallet/admin-wallet-coin-transactions.md) |
-| A10 | `GET /admin/api/wallet/cash-transactions` | admin | [详情](./admin/wallet/admin-wallet-cash-transactions.md) |
-| A11 | `GET /admin/api/withdraws` | admin | [详情](./admin/withdraws/admin-withdraws-list.md) |
-| A12 | `POST /admin/api/withdraws/reconcile` | finance | [详情](./admin/withdraws/admin-withdraw-reconcile.md) |
-| A13 | `POST /admin/api/withdraws/{out_bill_no}/refresh` | finance | [详情](./admin/withdraws/admin-withdraw-refresh.md) |
-| A14 | `GET /admin/api/feedbacks` | admin | [详情](./admin/feedbacks/admin-feedbacks-list.md) |
-| A15 | `POST /admin/api/feedbacks/{feedback_id}/handle` | operator | [详情](./admin/feedbacks/admin-feedback-handle.md) |
-| A16 | `GET /admin/api/admins` | super_admin | [详情](./admin/admins/admin-admins-list.md) |
-| A17 | `POST /admin/api/admins` | super_admin | [详情](./admin/admins/admin-admin-create.md) |
-| A18 | `PATCH /admin/api/admins/{admin_id}` | super_admin | [详情](./admin/admins/admin-admin-update.md) |
-| A19 | `GET /admin/api/audit-logs` | admin | [详情](./admin/admin-audit-logs.md) |
-| A20 | `GET /admin/api/dashboard-display` | admin | [详情](./admin/admin-dashboard-display.md) |
-| A21 | `PATCH /admin/api/dashboard-display/{metric}` | operator | [详情](./admin/admin-dashboard-display.md) |
-| A22 | `GET /admin/api/marquee-seeds` | admin | [详情](./admin/admin-marquee-seeds.md) |
-| A23 | `POST /admin/api/marquee-seeds` | operator | [详情](./admin/admin-marquee-seeds.md) |
-| A24 | `PATCH /admin/api/marquee-seeds/{seed_id}` | operator | [详情](./admin/admin-marquee-seeds.md) |
-| A25 | `DELETE /admin/api/marquee-seeds/{seed_id}` | operator | [详情](./admin/admin-marquee-seeds.md) |
-| A26 | `POST /admin/api/marquee-seeds/bulk` | operator | [详情](./admin/admin-marquee-seeds.md) |
-| A27 | `GET /admin/api/marquee-seeds/preview` | admin | [详情](./admin/admin-marquee-seeds.md) |
-| A28 | `GET /admin/api/ad-coin-audit` | admin | [详情](./admin/ad/admin-ad-coin-audit.md)(看广告金币公式复算对账,只读) |
-| A29 | `GET /admin/api/ad-revenue-report` | admin | [详情](./admin/ad/admin-ad-revenue-report.md)(广告收益报表:按用户/日期/类型/应用/代码位 聚合 条数/收益/金币,只读) |
+| **运营后台 Admin**（独立子应用 `app/admin/`,前缀 `/admin/api`,独立进程 + 独立 admin JWT。鉴权列:`admin`=任意已登录管理员,`operator`/`finance`/`super_admin`=需对应角色;#117 起可见页由 [admin_role](../database/admin_role.md) 数据驱动,`super_admin` 恒通过） |||
+| A1 | `POST /admin/api/auth/login` · `GET /auth/me` | 无 / admin | [详情](./admin/auth/admin-auth-login.md) / [me](./admin/auth/admin-auth-me.md)（me 返回有效可见页 `pages`） |
+| A2 | `GET /admin/api/stats/overview` | admin | [详情](./admin/admin-stats-overview.md)（大盘核心指标;#103 按 trace 聚合 + 京东收益 #90 + feed_scene 口径 #125） |
+| A3 | `GET /admin/api/event-logs` | admin | [详情](./admin/admin-event-logs.md)（埋点日志检索,#83） |
+| **A·用户**:`GET /users`(筛选排序分页)、`GET /users/{id}`(360 详情)、`GET /{id}/reward-stats` + `GET /{id}/coin-records`(提现详情联查)、`POST /{id}/status`(封禁)、`POST /{id}/debug-trace`(调试链接权限)、`POST /{id}/coins`、`POST /{id}/cash`(#95 `account` 目标账户) ||| [列表](./admin/users/admin-users-list.md) / [详情](./admin/users/admin-user-detail.md) / [状态+debug-trace](./admin/users/admin-user-status.md) / [金币](./admin/users/admin-user-coins.md) / [现金](./admin/users/admin-user-cash.md) |
+| A4 | `GET /admin/api/wallet/coin-transactions` / `cash-transactions` | admin | [金币](./admin/wallet/admin-wallet-coin-transactions.md) / [现金](./admin/wallet/admin-wallet-cash-transactions.md) |
+| **A·提现审核台**:`GET /withdraws`(列表)、`/summary`、`/health-check`(finance)、`/ledger-check`(#121 分账对账)、`/{out_bill_no}`(详情)、`POST /reconcile`、单笔 `refresh`/`approve`/`reject`、批量 `bulk/refresh`/`bulk/approve`/`bulk/reject` ||| [列表](./admin/withdraws/admin-withdraws-list.md) / [审核族](./admin/withdraws/admin-withdraw-review.md) / [对账](./admin/withdraws/admin-withdraw-reconcile.md) / [查单](./admin/withdraws/admin-withdraw-refresh.md) |
+| **A·反馈**:`GET /feedbacks`、`/summary`、`POST /{id}/approve`(采纳发币 #94)、`/{id}/reject`、`/{id}/handle` ||| [列表](./admin/feedbacks/admin-feedbacks-list.md) / [审核族](./admin/feedbacks/admin-feedback-handle.md) |
+| A5 | `GET`/`PATCH` `/admin/api/feedback-config`,`POST`/`DELETE` `…/image` | operator | 反馈页「加群二维码」卡配置(admin 侧;C 端读见 38a)(无单独文档,见 `app/admin/routers/feedback_qr.py`) |
+| **A·上报更低价**:`GET /price-reports`、`/summary`、`POST /{id}/approve|reject`(#94) ||| [审核族](./admin/admin-price-reports.md) |
+| A6 | `GET /admin/api/comparison-records`(+`/{id}` 详情) | admin | 比价记录检索(按 user/phone/**店与商品名模糊搜** #117 筛;详情含 LLM 调用明细)(无单独文档,见 `app/admin/routers/comparison.py`) |
+| A7 | `GET /admin/api/coupon-data`(+`/user-records`) | admin | [详情](./admin/admin-coupon-data.md)(领券数据看板,#99) |
+| A8 | `GET /admin/api/device-liveness`(+`/stats`) | admin | [详情](./admin/admin-device-liveness.md)(设备存活监控,#80) |
+| A9 | `GET /onboarding/devices`、`POST /devices/{id}/reset`、`POST /reset-all` | operator | 新手引导记录管理(按设备聚合/重置)(无单独文档,见 `app/admin/routers/onboarding.py`) |
+| **A·轮播**:`GET /marquee-seeds`、`/preview`、`/real-records`(#123)、`GET`/`PATCH` `/mode`(#122,模式落 `app_config`)、`POST`(+`/bulk`、`/batch-delete`、`/batch-enable`)、`PATCH`/`DELETE` `/{seed_id}` ||| [详情](./admin/admin-marquee-seeds.md) |
+| A10 | `GET / PATCH /admin/api/dashboard-display` | admin / operator | [详情](./admin/admin-dashboard-display.md)(首页三统计配置) |
+| A11 | `GET /admin/api/ad-coin-audit` | admin | [详情](./admin/ad/admin-ad-coin-audit.md)(看广告金币公式复算对账,只读) |
+| A12 | `GET /admin/api/ad-revenue-report` | admin | [详情](./admin/ad/admin-ad-revenue-report.md)(广告收益报表:分页/场景/`app_env` 筛 + **DAU/ARPU** #120;真实收益侧接穿山甲日表 #92) |
+| A13 | `GET / PATCH /admin/api/ad-config` | operator/finance | 广告配置(穿山甲 ID/验签密钥/各场景开关;C 端只读版见 40b)(无单独文档,见 `app/admin/routers/ad_config.py`) |
+| A14 | `GET /admin/api/config`、`PATCH /config/{key}` | operator/finance | 运营可配置项([app_config](../database/app_config.md):奖励常量/提现地板价等;#117 修系统配置下发)(无单独文档,见 `app/admin/routers/config.py`) |
+| **A·管理员与角色**(super_admin):`GET`/`POST` `/admins`、`PATCH`/`DELETE` `/admins/{id}`(#126 删除+`pages_override`)、`GET`/`POST` `/roles`、`GET /roles/catalog`、`PATCH`/`DELETE` `/roles/{id}`(#117/#126 自定义角色) ||| [列表](./admin/admins/admin-admins-list.md) / [建](./admin/admins/admin-admin-create.md) / [改+删](./admin/admins/admin-admin-update.md) / [角色](./admin/admin-roles.md) |
+| A15 | `GET /admin/api/audit-logs` | admin | [详情](./admin/admin-audit-logs.md) |
+| **A·CPS 运营台**:群/活动 CRUD、`POST /referral-links`、`POST /orders/reconcile`(美团+京东 #90)、`GET /orders`、`/stats`、群 `timeseries`/`daily`/`wx-users`/`day-users`(#79) ||| [详情](./admin/admin-cps.md) |
 | - | `GET /admin/api/health` | 无 | admin 健康检查(无单独文档) |
 
 > ⚠️ 美团三个接口当前**无鉴权**,且 `referral-link` 的 `sid` 允许客户端传值覆盖默认渠道——见各接口"备注"。
-> `coupon/step` 及外卖比价的 `intent/recognize`、`intent/precoupon/step`、`intent/step`、`price/step`、`trace/finalize` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见 `app/api/v1/compare.py`)。
+> `coupon/step` 透传到 pricebot-backend,**仍不鉴权**(device_id 区分设备,待补 JWT)。外卖比价透传族(`intent/*`、`price/step`、`trace/finalize|epilogue`)2026-07 起改**软鉴权 OptionalUser**:带 Bearer 则比价记录绑 `user_id`,不带也放行;并由 app-server 首帧签发 `trace_id` + harvest 落 `comparison_record`(见 `app/api/v1/compare.py` 模块注释)。
 > 福利相关业务接口（wallet/signin/tasks/savings、`ad/reward-status`、`ad/feed-reward`）均需 **Bearer**;`wallet/exchange-info` 是静态规则无鉴权;`ad/pangle-callback` 不走 JWT、靠穿山甲**验签**;`ad/test-grant` **仅本地联调**(开关控制,生产 404)。
 > 金额字段一律以**分**为单位（`*_cents`）。
 

docs/api/admin/admin-coupon-data.md

@@ -0,0 +1,17 @@
+# /admin/api/coupon-data — 领券数据看板(#99)
+
+> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin(任意已登录管理员) | 表 [coupon_session](../../database/coupon_session.md) | [← 返回 API 索引](../README.md)
+
+数据源是客户端两段上报的 `coupon_session`(一次领券任务一行:发起建行/收尾更新)。看板量化:发起数、完成率、**中途流失**(started 无终态)、平均/分位耗时、各平台耗时、机型/ROM 维度。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/coupon-data` | 看板聚合:发起/完成数 + 耗时分位 + 按天趋势 + 逐条明细(按 `started_date` 区间 + `app_env` 筛,默认只看 prod 防测试数据串台) |
+| `GET /admin/api/coupon-data/user-records` | 某用户全部领券记录(用户列表点手机号抽屉:领券次数 + 记录列表) |
+
+## 说明
+- 明细行 LEFT JOIN `user` 出手机号/昵称(匿名领券行 user 列为空)。
+- 「发起平台」列按 `origin_package` 区分:空=App 内首页发起,包名=从对应外卖 App 弹券引导发起。
+- 耗时口径:`elapsed_ms` 客户端全程计时(只统计 completed)。

docs/api/admin/admin-cps.md

@@ -0,0 +1,28 @@
+# /admin/api/cps — CPS 群发联盟运营台(群/活动/短链/对账)
+
+> 所属:Admin 子应用(前缀 `/admin/api/cps`) | 鉴权:读=admin,写=operator/finance(对账) | 表 [cps_group](../../database/cps_group.md) / [cps_activity](../../database/cps_activity.md) / [cps_link](../../database/cps_link.md) / [cps_click](../../database/cps_click.md) / [cps_order](../../database/cps_order.md) / [cps_wx_user](../../database/cps_wx_user.md) | [← 返回 API 索引](../README.md)
+>
+> 业务与授权流程详见 [guides/CPS发券分发与微信授权](../../guides/CPS发券分发与微信授权.md);C 端落地短链见 [cps-redirect](../other/cps-redirect.md)。
+
+私域社群 CPS 的完整运营链:建群(拿 `sid`)→ 建活动(券/物料)→ 生成群发短链 `/c/{code}` → 用户点击/复制口令 → 联盟订单按 `sid` 归群对账,汇成「点击→下单→佣金」漏斗。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET / POST /admin/api/cps/groups`,`PATCH / DELETE /groups/{id}` | 推广群 CRUD;含美团平台的群自动分配 `sid` |
+| `GET / POST /admin/api/cps/activities`,`PATCH / DELETE /activities/{id}` | 可推广活动 CRUD(美团 actId / 淘宝淘口令 / 京东链接) |
+| `POST /admin/api/cps/upload-image`、`GET /activity-images` | 活动落地页图上传 / 已有图列表(新建复用) |
+| `POST /admin/api/cps/referral-links` | 批量生成群×活动短链(美团经 sid 转链) |
+| `POST /admin/api/cps/orders/reconcile` | 拉联盟订单对账(美团 `query_order` + 京东联盟 #90,`order_id` 幂等 upsert;finance) |
+| `GET /admin/api/cps/orders` | 订单明细(游标分页,可按 sid / 状态筛) |
+| `GET /admin/api/cps/stats` | 按群对账统计(点击/订单/GMV/预估与结算佣金) |
+| `GET /admin/api/cps/groups/{id}/timeseries` | 群点击时序(天/小时级 PV/UV/复制,折线图) |
+| `GET /admin/api/cps/groups/{id}/daily` | 群每天明细大表格(点击+订单按天合并;#79 起支持按天下钻) |
+| `GET /admin/api/cps/groups/{id}/wx-users` | 群内微信用户(领券画像:头像/昵称/领券次数) |
+| `GET /admin/api/cps/groups/{id}/day-users` | 某天该群按用户的领券/点击 + 每人点过的券(#79) |
+
+## 说明
+- 订单与点击**只能在群(sid)维度汇合**,无法对到单笔(联盟只回传 sid)。
+- 京东单有效性按 `jd_valid_code`,美团按 `mt_status`(4 取消/5 风控不计佣,6 结算才到账);淘宝无对账 API,对账列显示 `-`。
+- #119 修美团 `pay_time` 入库为空导致大盘时间窗漏算。

docs/api/admin/admin-device-liveness.md

@@ -0,0 +1,15 @@
+# /admin/api/device-liveness — 设备存活监控(#80)
+
+> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin | 表 [device_liveness](../../database/device_liveness.md) | [← 返回 API 索引](../README.md)
+
+无障碍保护存活的后台视角:哪些设备开过保护(`ever_protected`)、现在在线还是掉线(心跳超时,#107 起阈值 1 小时)、首次开启时间(`first_protected_at`)。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/device-liveness/stats` | 顶部卡片统计:设备总数 / 开过保护 / 当前在线 / 掉线数 |
+| `GET /admin/api/device-liveness` | 设备存活列表(游标分页):在线情况/设备 id/归属用户 筛选 + 排序,**默认掉线置顶**;行含最近心跳、首次开启、App 版本、push token 有无 |
+
+## 说明
+- 「在线」= `last_heartbeat_at` 距今 < 超时阈值;掉线召回链路(worker 置 `kill_alert_pending` → 客户端 pull)见表文档。

docs/api/admin/admin-event-logs.md

@@ -0,0 +1,15 @@
+# /admin/api/event-logs — 埋点日志(#83)
+
+> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin | 表 [analytics_event](../../database/analytics_event.md) | [← 返回 API 索引](../README.md)
+
+客户端埋点(`POST /api/v1/analytics/events` 批量上报)的后台检索页。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/event-logs` | 埋点事件列表(游标分页):可按 `event` / `device_id` / `user_id` 筛;行含事件名、props、页面、机型/系统/网络、client_ts |
+
+## 说明
+- 纯只读;无聚合报表(要分析导出后自己算)。
+- 时间轴用 `client_ts`(事件真实发生时刻),入库时间受客户端攒批影响。

docs/api/admin/admin-marquee-seeds.md

@@ -2,7 +2,7 @@
 
 > 所属:Admin 组（前缀 `/admin/api/marquee-seeds`） | 鉴权:Admin Bearer（改需 operator/super) | [← 返回 API 索引](../README.md)
 
-管理首页轮播「真实+种子混播」的兜底种子。种子是「生成规则」:`masked_user` 可空(空→feed 随机合成名)、金额是 `[min_cents, max_cents]` 区间(feed 每次随机取值)。用户侧 feed 见 [platform-savings-feed](./platform-savings-feed.md);表见 [ops_marquee_seed](../database/ops_marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
+管理首页轮播「真实+种子混播」的兜底种子。种子是「生成规则」:`masked_user` 可空(空→feed 随机合成名)、金额是 `[min_cents, max_cents]` 区间(feed 每次随机取值)。用户侧 feed 见 [platform-savings-feed](../savings/platform-savings-feed.md);表见 [ops_marquee_seed](../../database/ops_marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
 
 ## 复用结构 OpsMarqueeSeedOut
 | 字段 | 类型 | 说明 |
@@ -19,9 +19,20 @@
 出参 `200`:`list[OpsMarqueeSeedOut]`(按 `sort_order,id`)。
 
 ## GET /admin/api/marquee-seeds/preview — 预览实际混播 feed
-预览客户端实际会看到的轮播(真实记录会插队、种子随机抽取 / 金额随机 / 名字合成),供运营对效果。**含随机,每次结果不同**。
+预览客户端实际会看到的轮播(真实记录会插队、种子随机抽取 / 金额随机 / 名字合成),供运营对效果。**含随机,每次结果不同**;#122 起按**当前数据源模式**实时预览(mixed/real/seed 各自的真实产出)。
 - 入参:`limit`(query,1~30,默认 8)
-- 出参 `200`:`{"items": [{masked_user, saved_amount_cents, time}]}`(条目同 [platform-savings-feed](./platform-savings-feed.md))
+- 出参 `200`:`{"items": [{masked_user, saved_amount_cents, time}]}`(条目同 [platform-savings-feed](../savings/platform-savings-feed.md))
+
+## GET /admin/api/marquee-seeds/real-records — 分页浏览当前模式下可展示的真实记录(#123)
+审核用:看「真实条」到底会拿哪些 `comparison_record` 上轮播(真实条**不按用户去重**,打乱+去连簇后混播;默认昵称归「无昵称」脱敏档,#122)。
+- 入参:`limit` / `cursor`(游标分页)
+- 出参 `200`:`{"items": [...], "next_cursor": int|null}`
+
+## GET /admin/api/marquee-seeds/mode — 首页轮播数据源模式
+出参:`{"mode": "mixed" | "real" | "seed"}`(混播 / 只真实 / 只种子)。
+
+## PATCH /admin/api/marquee-seeds/mode — 改数据源模式(带审计)
+- 入参:`{"mode": "mixed" | "real" | "seed"}`;operator 起。改动客户端重拉 feed 生效。
 
 ## POST /admin/api/marquee-seeds — 新增(带审计)
 入参 `OpsMarqueeSeedCreate`:`masked_user`(可选,空 / 不传 → 随机合成)、`min_cents`(必填,≥0)、`max_cents`(必填,≥min,≤1000 元)、`enabled`(默认 true)、`sort_order`(默认 0)。出参:新建的 `OpsMarqueeSeedOut`。`400`=金额非法。

docs/api/admin/admin-price-reports.md

@@ -0,0 +1,16 @@
+# /admin/api/price-reports — 上报更低价审核(#94)
+
+> 所属:Admin 子应用(前缀 `/admin/api/price-reports`) | 鉴权:读=admin,审=operator | 表 [price_report](../../database/price_report.md) | [← 返回 API 索引](../README.md)
+>
+> C 端提交/查询见 [report-submit](../other/report-submit.md) / [report-records](../other/report-records.md)。
+
+用户众包「上报更低价」的人工审核台:审截图与价格,通过发固定金币。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/price-reports` | 上报列表(状态筛选 + 游标分页,含截图、关联比价记录快照) |
+| `GET /admin/api/price-reports/summary` | 审核统计(pending/approved/rejected 计数) |
+| `POST /admin/api/price-reports/{report_id}/approve` | 通过 → 发固定金币(`grant_coins` 同事务)+ 带审计 |
+| `POST /admin/api/price-reports/{report_id}/reject` | 拒绝(填原因,用户端可见)+ 带审计 |

docs/api/admin/admin-roles.md

@@ -0,0 +1,19 @@
+# /admin/api/roles — 角色与可见页管理(RBAC,#117/#126)
+
+> 所属:Admin 子应用(前缀 `/admin/api`,独立 admin JWT) | 鉴权:**super_admin** | 表 [admin_role](../../database/admin_role.md) | [← 返回 API 索引](../README.md)
+
+后台 RBAC 的数据驱动层:内建三角色(`super_admin`/`finance`/`operator`,`is_builtin=true` 不可删)+ **自定义角色**(勾任意页面组合)。管理员的有效可见页 = `admin_user.pages_override`(个人覆盖,非空优先)∪ 否则取其角色 `pages`;`super_admin` 恒全通。
+
+## 端点
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/roles` | 角色列表:`[{id, name, label, pages, is_builtin, admin_count}]`(含每个角色的使用人数) |
+| `GET /admin/api/roles/catalog` | 页面权限目录(分组):全部可勾选的页面 key(来自 `app/admin/permissions.py` 常量,不落库),前端渲染勾选面板用 |
+| `POST /admin/api/roles` | 新增自定义角色 `{name, pages}`(**name(key)= label = 输入名称**;不能叫 `super_admin`,重名 `409`);带审计 |
+| `PATCH /admin/api/roles/{role_id}` | 改展示名/可见页(内建角色的 `pages` 也可调);带审计 |
+| `DELETE /admin/api/roles/{role_id}` | 删角色;**内建(`is_builtin`)与在用(有 `admin_user.role` 引用)不可删**(400);带审计 |
+
+## 说明
+- 管理员个人覆盖在 [`PATCH /admin/api/admins/{id}`](./admins/admin-admin-update.md) 的 `pages_override` 字段改,不在本组。
+- 加新后台页面要同步登记 `permissions.py` 目录,表里只存勾选结果(目录变更无需迁移)。

docs/api/admin/admins/admin-admin-update.md

@@ -8,12 +8,13 @@
 |---|---|---|---|
 | `admin_id` | int | ✓ | 目标管理员 id |
 
-**application/json**(三字段都可选,只改传了的;至少传一个):
+**application/json**(字段都可选,只改传了的;至少传一个):
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `role` | string | ✗ | 改角色,枚举:`super_admin` / `finance` / `operator` |
+| `role` | string | ✗ | 改角色:内建 `super_admin` / `finance` / `operator` **或自定义角色 name**(#117/#126,见 [admin-roles](../admin-roles.md)) |
+| `pages_override` | list[string] \| null | ✗ | 个人可见页覆盖(#126):非空优先于角色 pages;传 `null` 清覆盖回归角色 |
 | `status` | string | ✗ | 启停,枚举:`active`(启用)/ `disabled`(禁用) |
-| `password` | string | ✗ | 重置密码,8–72 字(传则覆盖原密码) |
+| `password` | string | ✗ | 重置密码,8–72 字(传则覆盖原密码,同时更新 `plain_password` 明文副本) |
 
 ## 出参
 响应 `200`:`AdminOut`（更新后的管理员)
@@ -24,9 +25,15 @@
 | `username` | string | 账号 |
 | `role` | string | 角色 |
 | `status` | string | 状态 |
+| `pages` | list[string] | **有效可见页**(pages_override 优先,否则角色 pages;super_admin 全量) |
 | `created_at` | datetime | 创建时间(UTC) |
 | `last_login_at` | datetime \| null | 上次登录时间 |
 
+---
+
+## DELETE /admin/api/admins/{admin_id} — 删除管理员(#126)
+物理删除(区别于禁用);**不可删自己**(`400`);带审计(`action=admin.delete`)。鉴权同本组(super_admin)。出参 `{"deleted": true}`。
+
 ## 错误码
 - `400` 不能禁用自己(`admin_id == 当前 admin.id` 且 `status=disabled`) / 无任何变更字段(三字段全空)
 - `401` 未带 admin token / token 无效或过期 / 管理员被禁用
@@ -35,5 +42,5 @@
 - `422` `role`/`status` 非法枚举 / `password` 长度不在 8–72
 
 ## 说明
-- 更新成功后写一条审计:`action=admin.update`、`target_type=admin`、`target_id=admin_id`、`detail` 为本次实际变更字段(如 `{"role": "...", "status": "...", "password": "reset"}`,密码只记 `reset` 不记明文)。见 [admin_audit_log](../database/admin_audit_log.md)。
-- 数据表见 [admin_user](../database/admin_user.md)。
+- 更新成功后写一条审计:`action=admin.update`、`target_type=admin`、`target_id=admin_id`、`detail` 为本次实际变更字段(如 `{"role": "...", "status": "...", "password": "reset"}`,密码只记 `reset` 不记明文)。见 [admin_audit_log](../../../database/admin_audit_log.md)。
+- 数据表见 [admin_user](../../../database/admin_user.md)。

docs/api/admin/feedbacks/admin-feedback-handle.md

@@ -1,6 +1,24 @@
-# POST /admin/api/feedbacks/{feedback_id}/handle — 标记反馈已处理
+# /admin/api/feedbacks — 反馈审核族(采纳/拒绝/标记处理/统计)
 
-> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过,`require_role("operator")`） | [← 返回 API 索引](../../README.md)
+> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过,`require_role("operator")`;summary 任意 admin） | [← 返回 API 索引](../../README.md)
+>
+> 列表见 [admin-feedbacks-list](./admin-feedbacks-list.md)。#94 引入 采纳(发金币)/拒绝 审核语义,#105 加运营回复 `admin_reply`;旧「标记已处理」保留。
+
+## POST /admin/api/feedbacks/{feedback_id}/approve — 采纳并发金币(#94)
+- body:`{reward_coins?(int,可 0), admin_reply?(string,用户可见), review_note?(string,内部)}`
+- 行为:`status → adopted`;`reward_coins > 0` 时走 `grant_coins` 同事务发币(流水 `coin_transaction`);写审计(`detail.after="adopted"`)。已终态(非 pending/new)→ `400`。
+- 出参:更新后的 FeedbackOut。
+
+## POST /admin/api/feedbacks/{feedback_id}/reject — 拒绝采纳(#94)
+- body:`{reject_reason(string,用户可见), admin_reply?, review_note?}`
+- 行为:`status → rejected`;写审计(`detail.after="rejected"`)。已终态 → `400`。
+
+## GET /admin/api/feedbacks/summary — 审核统计
+- 出参:各状态计数(`pending` / `adopted` / `rejected` / `handled`),审核台顶部卡片用;任意 admin 可读。
+
+---
+
+## POST /admin/api/feedbacks/{feedback_id}/handle — 标记反馈已处理(旧口径)
 
 ## 入参
 - 路径:`feedback_id`(int)
@@ -18,6 +36,6 @@
 - `422` `feedback_id` 非合法 int
 
 ## 说明
-- 写操作记审计 [admin_audit_log](../database/admin_audit_log.md):`action="feedback.handle"`、`target_type="feedback"`、`target_id=<feedback_id>`、`detail={"before": <原 status>, "after": "handled"}`、`ip=<客户端 IP>`。
+- 写操作记审计 [admin_audit_log](../../../database/admin_audit_log.md):`action="feedback.handle"`、`target_type="feedback"`、`target_id=<feedback_id>`、`detail={"before": <原 status>, "after": "handled"}`、`ip=<客户端 IP>`。
 - 状态变更与审计写入在同一事务(`commit=False` 后统一 `db.commit()`)。
-- 关联表 [feedback](../database/feedback.md)。
+- 关联表 [feedback](../../../database/feedback.md)。

docs/api/admin/users/admin-user-cash.md

@@ -10,6 +10,7 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `mode` | string | ✗ | `delta`(默认)=增减 / `set`=设为指定值 |
+| `account` | string | ✗ | 目标账户(#95):`coin_cash`(默认,金币兑换的现金)/ `invite_cash`(邀请奖励金)。两本账物理隔离、各调各 |
 | `amount_cents` | int | ✓ | `delta` 模式:现金变动(分,正=发放,负=扣减,不可为 0);`set` 模式:目标现金值(分,须 ≥ 0) |
 | `reason` | string | ✓ | 操作原因,1–128 字(必填,入审计与流水备注) |
 
@@ -28,7 +29,7 @@
 - 金额单位一律为**分**(`*_cents`);本接口只动现金余额,不涉及金币。
 - **set 模式**:读当前余额算出差值 `delta = target - 当前余额`,再复用同一套写入逻辑(故只写一笔差值流水)。目标值须 ≥ 0;差值为 0(已等于目标)直接拒绝。
 - 扣减保护:实际写入的 `delta < 0` 时若扣减后现金余额 < 0 直接拒绝(运营误操作保护);set 模式目标值 ≥ 0 天然不会扣成负。
-- 现金变动写流水 [cash_transaction](../database/cash_transaction.md):`biz_type` 实际差值为正记 `admin_grant`、为负记 `admin_deduct`(set 模式同理,不新增流水类型),`remark = admin:<reason>`(截断至 128 字)。
-- 写操作记审计 [admin_audit_log](../database/admin_audit_log.md):`action = user.cash.grant`,`target_type = user`,`target_id = user_id`,`detail = {amount_cents(=实际差值), balance_after_cents, reason}`;set 模式额外带 `{mode:"set", target_cents, before_cents}`。并记录操作 IP。
+- 现金变动按 `account` 写对应账本流水:`coin_cash` → [cash_transaction](../../../database/cash_transaction.md),`invite_cash` → [invite_cash_transaction](../../../database/invite_cash_transaction.md)(#95);`biz_type` 实际差值为正记 `admin_grant`、为负记 `admin_deduct`(set 模式同理,不新增流水类型),`remark = admin:<reason>`(截断至 128 字)。
+- 写操作记审计 [admin_audit_log](../../../database/admin_audit_log.md):`action = user.cash.grant`,`target_type = user`,`target_id = user_id`,`detail = {amount_cents(=实际差值), balance_after_cents, reason}`;set 模式额外带 `{mode:"set", target_cents, before_cents}`。并记录操作 IP。
 - 现金变动 + 审计在同一事务原子提交(改钱必留痕)。
-- 关联用户表 [user](../database/user.md);现金账户 [coin_account](../database/coin_account.md);现金流水 [cash_transaction](../database/cash_transaction.md)。
+- 关联用户表 [user](../../../database/user.md);现金账户 [coin_account](../../../database/coin_account.md);现金流水 [cash_transaction](../../../database/cash_transaction.md)。

docs/api/admin/users/admin-user-detail.md

@@ -38,6 +38,15 @@
 - `422` `user_id` 非整数
 
 ## 说明
-- 金币三项(`coin_balance` / `cash_balance_cents` / `total_coin_earned`)读 [coin_account](../database/coin_account.md);从未发生金币动作(账户不存在)时统一返回 0。
+- 金币三项(`coin_balance` / `cash_balance_cents` / `total_coin_earned`)读 [coin_account](../../../database/coin_account.md);从未发生金币动作(账户不存在)时统一返回 0。
 - 各 count 为聚合数,明细历史走带 `user_id` 过滤的分页接口(金币流水 / 现金流水 / 提现 / 比价 / 反馈)。
-- 关联用户表 [user](../database/user.md);金币账户 [coin_account](../database/coin_account.md);提现单 [withdraw_order](../database/withdraw_order.md);比价记录 [comparison_record](../database/comparison_record.md);反馈 [feedback](../database/feedback.md)。
+- 关联用户表 [user](../../../database/user.md);金币账户 [coin_account](../../../database/coin_account.md);提现单 [withdraw_order](../../../database/withdraw_order.md);比价记录 [comparison_record](../../../database/comparison_record.md);反馈 [feedback](../../../database/feedback.md)。
+
+---
+
+## 族内配套端点(提现详情页联查用)
+
+| 方法 + 路径 | 说明 |
+|---|---|
+| `GET /admin/api/users/{user_id}/reward-stats` | 用户提现/看广告统计(按时间窗口):提现审核时评估该用户金币来源是否健康 |
+| `GET /admin/api/users/{user_id}/coin-records` | 用户金币发放记录(按时间窗口分页):提现详情底部表,逐笔看发币来源 |

docs/api/admin/users/admin-user-status.md

@@ -21,5 +21,11 @@
 
 ## 说明
 - 业务写(改用户状态)与审计写在同一事务原子提交:改了就有痕、有痕就真改了。
-- 写操作记审计 [admin_audit_log](../database/admin_audit_log.md):`action = user.status.set`,`target_type = user`,`target_id = user_id`,`detail = {before, after}`,并记录操作 IP。
-- 关联用户表 [user](../database/user.md)。
+- 写操作记审计 [admin_audit_log](../../../database/admin_audit_log.md):`action = user.status.set`,`target_type = user`,`target_id = user_id`,`detail = {before, after}`,并记录操作 IP。
+- 关联用户表 [user](../../../database/user.md)。
+
+---
+
+## POST /admin/api/users/{user_id}/debug-trace — 开关调试链接权限
+- body:`{"enabled": true|false}` → 写 `user.debug_trace_enabled`(带审计 `action=user.debug_trace.set`)。
+- 开了的用户在比价完成弹窗 + 比价记录页可见「复制调试链接」按钮(trace_url);运营按用户灰度排障用。鉴权同本组(operator)。

docs/api/admin/withdraws/admin-withdraw-review.md

@@ -0,0 +1,25 @@
+# /admin/api/withdraws — 提现审核台(审核/批量/对账族)
+
+> 所属:Admin 子应用(前缀 `/admin/api/withdraws`) | 鉴权:读=admin,写=**finance** | 表 [withdraw_order](../../../database/withdraw_order.md) | [← 返回 API 索引](../../README.md)
+>
+> 列表见 [admin-withdraws-list](./admin-withdraws-list.md);单笔查单见 [admin-withdraw-refresh](./admin-withdraw-refresh.md);超时对账见 [admin-withdraw-reconcile](./admin-withdraw-reconcile.md)。本文覆盖其余审核台端点。
+
+提现状态机:`reviewing`(发起即扣款待审)→ 通过 `pending`(微信转账在途)→ `success`/`failed`(失败退款);拒绝 `rejected`(退款)。**#121 起按 `withdraw_order.source` 分账**:退款/流水落 `cash_transaction`(coin_cash)或 `invite_cash_transaction`(invite_cash)。
+
+## 端点
+
+| 方法 + 路径 | 鉴权 | 说明 |
+|---|---|---|
+| `GET /admin/api/withdraws/summary` | admin | 审核台统计:各状态计数(待审/在途/成功/失败/拒绝) |
+| `GET /admin/api/withdraws/health-check` | finance | 提现配置健康检查(证书/密钥路径/商户配置就位与否;暴露路径故限 finance+super) |
+| `GET /admin/api/withdraws/ledger-check` | admin | **资金账本校验**(#121):按 `source` 分账核对「提现单 ↔ 流水」金额闭环,邀请奖励金提现纳入对账 |
+| `GET /admin/api/withdraws/{out_bill_no}` | admin | 提现单详情(审核台抽屉;用户维度联查另走 `users/{id}/reward-stats` + `coin-records`) |
+| `POST /admin/api/withdraws/{out_bill_no}/approve` | finance | 审核通过 → 发起微信打款(`reviewing`→`pending`→查单归一化);带审计 |
+| `POST /admin/api/withdraws/{out_bill_no}/reject` | finance | 审核拒绝 → 按 source 退款 + `rejected`;带审计 |
+| `POST /admin/api/withdraws/bulk/refresh` | finance | 批量刷新查单(勾选多笔) |
+| `POST /admin/api/withdraws/bulk/approve` | finance | 批量审核通过并打款 |
+| `POST /admin/api/withdraws/bulk/reject` | finance | 批量审核拒绝并退款 |
+
+## 说明
+- 批量接口逐单处理、逐单落审计,单笔失败不中断整批(返回逐单结果)。
+- 结果不明时先查单再定夺、绝不盲目退款(防退款后又到账),同 C 端口径。

docs/api/intent/compare-intent-recognize.md

@@ -1,13 +1,13 @@
-# POST /api/v1/intent/recognize — 外卖比价 Phase 1 意图识别（透传到 pricebot）
+# POST /api/v1/intent/recognize — 外卖比价 Phase 1 意图识别（透传 + 首帧 harvest 建行）
 
-> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**无（MVP 阶段不鉴权）** | [← 返回 API 索引](../README.md)
+> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**软鉴权 OptionalUser**（带 JWT 则绑 `user_id`,不带也放行） | [← 返回 API 索引](../README.md)
 
 ## 入参
-任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。
+任意 JSON body,**不做 schema 校验**,原样透传给上游。后端从中读 `device_id`、`trace_id`、`step`、`device_info` 用于日志与落库。
 客户端实际传源平台购物车页的无障碍树采集结果（pricebot 协议里的 `screens`:`cart_page_1` / `cart_page_2`）。
 
 ## 出参
-pricebot-backend 的响应**原样返回**（JSON object）。典型含 `result`（店名）、`calibration`（含 `source_platform_id` / `items` / `price`），客户端在 `step=0` 把它透传进 `/price/step`。
+pricebot-backend 的响应**原样返回**（JSON object）,并在顶层补 `trace_id`。典型含 `result`（店名）、`calibration`（含 `source_platform_id` / `items` / `price`），客户端在 `step=0` 把它透传进 `/price/step`。
 
 ## 错误码
 - `400` body 不是合法 JSON
@@ -18,7 +18,7 @@ pricebot-backend 的响应**原样返回**（JSON object）。典型含 `result`
 
 外卖比价由客户端无障碍引擎在源平台（淘宝闪购 / 美团 / 京东外卖）购物车页点悬浮球触发 → 调本接口拿 `query` + `calibration` → 进入 `/price/step` 循环。
 
-⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）:`device_id` 透传给 pricebot 区分设备,后端拿不到 `user_id` → 行为暂绑不到登录用户。待补 JWT,见 [待办与技术债.md](../guides/待办与技术债.md) P1。
+**trace_id 签发 + harvest 建行(2026-07 起,`compare.py`)**:客户端首帧可不带 `trace_id`——app-server 用 uuid 签发、注入转发 body、回填响应顶层;**仅签发那帧**按 `trace_id` 建 [comparison_record](../../database/comparison_record.md) 的 `running` 行(幂等,best-effort),done / finalize 帧再补终态。**软鉴权**:带 Bearer 则记录绑 `user_id`,匿名行 `user_id` 暂空、由后续 `/compare/record` 上报补。
 
 **相关配置**:
 - `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`）

docs/api/intent/compare-price-step.md

@@ -1,22 +1,26 @@
-# POST /api/v1/price/step — 外卖比价 Phase 2 步进（透传到 pricebot）
+# POST /api/v1/price/step — 外卖比价 Phase 2 步进（透传 + done 帧 harvest 落库）
 
-> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**无（MVP 阶段不鉴权）** | [← 返回 API 索引](../README.md)
+> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**软鉴权 OptionalUser**（带 JWT 则绑 `user_id`,不带也放行） | [← 返回 API 索引](../README.md)
 
 ## 入参
-任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。
+任意 JSON body,**不做 schema 校验**,原样透传给上游。后端从中读 `device_id`、`trace_id`、`step`、`device_info` 用于日志与落库。
 客户端逐帧上报 `screen_state` + 上一步 `action_result`;`step=0` 还带 `query` + `calibration`（来自 Phase 1）。
 
 ## 出参
-pricebot-backend 的响应**原样返回**（JSON object）。含 `action`（tap / set_text / launch / wait / done…）、`continue`、`status`;最终 `done` 帧带 `comparison_results`（源 + 各目标平台到手价,按价升序）。
+pricebot-backend 的响应**原样返回**（JSON object）,并在顶层补 `trace_id`（见下「trace_id 签发」）。含 `action`（tap / set_text / launch / wait / done…）、`continue`、`status`、每帧顶层 `trace_url`;最终 `done` 帧带 `comparison_results`（源 + 各目标平台到手价,按价升序）。
 
 ## 错误码
 - `400` body 不是合法 JSON
 - `502` pricebot 上游不可达（网络错误）或返回 5xx
 
 ## 说明
-把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/price/step`（去掉 `/v1`,async httpx）。**多轮循环**:客户端按返回的 `action` 操作手机、再上报下一帧,直到 `continue=false`。真正的目标驱动比价逻辑（多目标平台串行复现订单、读到手价、聚合排序）在 **pricebot-backend**,本接口只是"透传壳"。
+把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/price/step`（去掉 `/v1`,共享 httpx 单例）。**多轮循环**:客户端按返回的 `action` 操作手机、再上报下一帧,直到 `continue=false`。真正的目标驱动比价逻辑（多目标平台串行复现订单、读到手价、聚合排序）在 **pricebot-backend**。
 
-⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）。
+**不再是纯透传壳(2026-07 起,`compare.py`)**:
+- **trace_id 签发**:客户端首帧可不带 `trace_id`——app-server 用 uuid 签发、注入转发 body、回填进响应顶层 `trace_id`,客户端后续帧都带它(老客户端自带则原样用)。
+- **harvest 落库**([comparison_record](../../database/comparison_record.md)):首帧(mint 时)建 `running` 行 → **done 帧** `harvest_done` 写 `success`/`failed` + 派生 `best_*`/`saved_amount_cents`。写库 best-effort(threadpool 独立 session),失败不连累透传。
+- **软鉴权**:新客户端带 Bearer → 记录绑 `user_id`;老客户端/匿名 → `user_id` 暂空,由其后续 `POST /compare/record` 上报补(灰度期两条写路径按 `trace_id` reconcile,success 不降级)。
+- 邀请发奖**不在这里**:#113 起口径为好友「比价并下单」,发放在 `POST /order/report`。
 
 **相关配置**:
 - `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`;生产部署应与 pricebot-backend 同内网——比价一单 30~80 步、逐帧多一跳,走公网延迟会累积）

docs/api/internal/internal.md

@@ -14,12 +14,13 @@
 
 | 方法 + 路径 | 落库 | 说明 |
 |---|---|---|
-| `POST /internal/price-observation` | [`price_observation`](../database/price_observation.md) | 比价 done 帧整批价格事实上报;`(trace_id, platform, scope)` 幂等,返回 `{inserted, skipped}` |
-| `GET /internal/store-mapping/lookup` | (只读 [`store_mapping`](../database/store_mapping.md)) | 比价前按 `source_platform`+`name`(+`lat`/`lng`)反查各目标平台已沉淀的店铺 id/deeplink;命中→pricebot 直接 deeplink 省现场搜店 |
+| `POST /internal/price-observation` | [`price_observation`](../../database/price_observation.md) | 比价 done 帧整批价格事实上报;`(trace_id, platform, scope)` 幂等,返回 `{inserted, skipped}` |
+| `GET /internal/store-mapping/lookup` | (只读 [`store_mapping`](../../database/store_mapping.md)) | 比价前按 `source_platform`+`name`(+`lat`/`lng`)反查各目标平台已沉淀的店铺 id/deeplink;命中→pricebot 直接 deeplink 省现场搜店 |
 | `POST /internal/store-mapping` | `store_mapping` | 跨平台「同一家店」身份映射上报;`trace_id` 幂等、填空合并,返回 `{inserted, row_id}` |
 | `POST /internal/store-mapping/invalidate` | `store_mapping` | 标记某平台 `shop_id` 的缓存 deeplink 失效(pricebot 撞错误页回退时报);当前支持 `taobao`/`jd`,其它平台 no-op,返回 `{ok, affected}` |
-| `POST /internal/launch-confirm-sample` | [`launch_confirm_sample`](../database/launch_confirm_sample.md) | 启动确认窗 LLM 兜底放行后回写样本(host 包 + 弹窗树 + plan + locale);**都上报、不去重**,返回 `{id}` |
-| `POST /internal/app-version` | [`app_config`](../database/app_config.md)(key=`latest_app_version`) | **发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256;客户端再 `GET /api/v1/platform/app-version` 读做 OTA。也是应急改版本信息(紧急下线/改 `apk_url`)入口 |
+| `POST /internal/launch-confirm-sample` | [`launch_confirm_sample`](../../database/launch_confirm_sample.md) | 启动确认窗 LLM 兜底放行后回写样本(host 包 + 弹窗树 + plan + locale);**都上报、不去重**,返回 `{id}` |
+| `GET /internal/launch-confirm-samples` | (只读 `launch_confirm_sample`) | 样本列表(#91,供 pricebot `distill_launch_confirm.py` 聚合沉淀回静态规则);可选筛 `exec_success` / `host_package` / `since_days`,`limit` 默认 1000 |
+| `POST /internal/app-version` | [`app_config`](../../database/app_config.md)(key=`latest_app_version`) | **发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256;客户端再 `GET /api/v1/platform/app-version` 读做 OTA。也是应急改版本信息(紧急下线/改 `apk_url`)入口 |
 
 ## 错误
 - `401` 密钥不匹配 / 缺失。

docs/api/invite/invite-bind.md

@@ -6,7 +6,7 @@
 
 ## POST /bind — 绑定邀请人
 
-把当前登录用户（被邀请人）绑定到某邀请码。支持三种归因路径：clipboard（首启读剪贴板）、manual（手动输入邀请码）、fingerprint（指纹兜底反查）。绑定成功双方各发 1 万金币。
+把当前登录用户（被邀请人）绑定到某邀请码。支持三种归因路径：clipboard（首启读剪贴板）、manual（手动输入邀请码）、fingerprint（指纹兜底反查）。**#113 起绑定只建关系、不发奖**——发奖后置到被邀请人「比价并实际下单」（`POST /order/report` 触发，给邀请人发**邀请奖励金**，`compare_reward_granted` 幂等闸一人一次）。
 
 ### 入参
 
@@ -46,14 +46,14 @@ Mock 入参（指纹兜底）:
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `status` | string | `success` / `already_bound` / `invalid_code` / `self_invite` / `not_eligible` / `fp_not_found` |
-| `coins_awarded` | int | 本次给当前用户（被邀请人）发的金币 |
+| `coins_awarded` | int | 兼容保留字段（#113 前"绑定即发金币"口径）。**#113 起新绑定恒 0**，前端不应再据此展示发奖 |
 | `message` | string | 给前端直接展示的文案 |
 
 Mock 出参:
 ```json
 {
   "status": "success",
-  "coins_awarded": 10000,
+  "coins_awarded": 0,
   "message": "邀请绑定成功"
 }
 ```

docs/api/invite/invite-invitees.md

@@ -25,7 +25,8 @@ GET /api/v1/invite/invitees?limit=5&offset=0
 | `items` | list[InviteeItem] | 被邀请人列表 |
 | `items[].display_name` | string | 显示名（昵称 → 微信昵称 → 脱敏手机号，后端已兜底） |
 | `items[].avatar_url` | string \| null | 头像 URL；null = 前端画默认色块 |
-| `items[].coins` | int | 这次邀请给邀请人发的金币 |
+| `items[].coins` | int | 这次邀请给邀请人发的金币（**历史留痕**：#113 前旧口径的发放额；新绑定恒 0） |
+| `items[].is_compared` | bool | 该好友是否已完成过一次比价（#113：好友列表据此分「邀请成功 / 去提醒」，在途列表只取 `false` 的） |
 | `items[].invited_at` | datetime | 邀请绑定时间（ISO 8601 UTC） |
 | `total` | int | 我邀请的总人数 |
 | `has_more` | bool | 还有下一页吗 |
@@ -37,13 +38,15 @@ Mock 出参:
     {
       "display_name": "省钱小王",
       "avatar_url": "/media/avatars/u2_f1e2d3c4b5a60708.jpg",
-      "coins": 10000,
+      "coins": 0,
+      "is_compared": true,
       "invited_at": "2026-06-28T14:30:00Z"
     },
     {
       "display_name": "138****1234",
       "avatar_url": null,
-      "coins": 10000,
+      "coins": 0,
+      "is_compared": false,
       "invited_at": "2026-07-01T09:15:00Z"
     }
   ],

docs/api/meituan/meituan-top-sales.md

@@ -2,20 +2,21 @@
 
 > 所属:美团 CPS 组(前缀 `/api/v1/meituan`,**全部无鉴权**) | 鉴权:无 | [← 返回 API 索引](../README.md)
 >
-> 数据来自离线库 [database/meituan_coupon](../database/meituan_coupon.md);**不实时打美团**(美团搜索对销量排序支持差、且有 402 限流)。
+> 数据来自离线库 [database/meituan_coupon](../../database/meituan_coupon.md);**不实时打美团**(美团搜索对销量排序支持差、且有 402 限流)。
 
 ## 入参
 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |---|---|---|---|---|
 | `page` | int | ❌ | 1 | ≥1 |
 | `page_size` | int | ❌ | 20 | 1–50 |
-| `platform` | int \| null | ❌ | null | 1 只外卖 / 2 只到店 / 不填=全部(全城销量) |
+| `platform` | int \| null | ❌ | null | 1 只外卖 / 2 只到店 / 不填=全部 |
+| `longitude` / `latitude` | float \| null | ❌(实际必带) | null | 设备坐标(#116):服务端离线反查城市(`utils/geo` + `meituan_city`)→ **只返回同城券**;老客户端不带坐标 → 返空 + `status=degraded`(不 422、不误返全城) |
 
 ## 出参
-响应 `200`:`{ items: CouponCard[], has_next: bool, search_id: null, status: "ok"|"empty"|"degraded" }`。`CouponCard` 见 [API 索引](./README.md#复用数据结构);`status` 语义见 [feed 接口](./meituan-feed.md#status-字段前端据此显示占位)。
+响应 `200`:`{ items: CouponCard[], has_next: bool, search_id: null, status: "ok"|"empty"|"degraded" }`。`CouponCard` 见 [API 索引](../README.md#复用数据结构);`status` 语义见 [feed 接口](./meituan-feed.md#status-字段前端据此显示占位)。
 
 ## 说明
-- 从 `meituan_coupon` 取 `sale_volume_num` 非空的券,`DISTINCT ON(dedup_key)` 跨源去重(每个「品牌|名|价」只留销量最高一条,同销量再按佣金),按销量降序分页;每页只对当前 ~20 条做 `from_raw` 解析(翻页快,不全表拉取)。
+- 从 `meituan_coupon` 取 `sale_volume_num` 非空 **且 `city_id` = 反查城市** 的券(#116,同城销量榜),`DISTINCT ON(dedup_key)` 跨源去重(每个「品牌|名|价」只留销量最高一条,同销量再按佣金),按销量降序分页;每页只对当前 ~20 条做 `from_raw` 解析(翻页快,不全表拉取)。
 - **不依赖 MT 凭证**(纯库查询)。库为空(prod 刚部署 / ETL 未跑完)→ `status=empty`;库查询异常 → `status=degraded`。均返 `200`、不抛 5xx。
 - **仅 PostgreSQL**(`DISTINCT ON` 为 PG 专用)。
 

docs/api/other/trace-finalize.md

@@ -1,9 +1,13 @@
-# POST /api/v1/trace/finalize — 比价 trace 收尾上云
+# POST /api/v1/trace/finalize + /trace/epilogue — 比价 trace 收尾族
 
-> 所属:透传端点（前缀 `/api/v1`，外卖比价） | 鉴权:无（MVP 阶段不鉴权） | [← 返回 API 索引](../README.md)
+> 所属:透传端点（前缀 `/api/v1`，外卖比价） | 鉴权:软鉴权 OptionalUser | [← 返回 API 索引](../README.md)
+
+## POST /api/v1/trace/finalize — 收尾上云(+夭折落库)
 
 透传到 pricebot-backend。用户终止 / Phase 1 未识别没走到 done 帧时，pricebot 没上云也没回传 `trace_url`。客户端收尾时打这个，pricebot 按 `trace_id` 一致性 hash 落到处理这条 trace 的同一进程（dir_cache 在那才能算对 trace 目录），打包上云返回 `{trace_url}`。
 
+**顺手夭折落库(2026-07 起)**:app-server 把该 trace 的 [comparison_record](../../database/comparison_record.md) `running` 行更新成夭折终态(`harvest_abort`,**不降级已 success**)。body 可带 `status`(`cancelled`/`failed`)+ `reason`;老客户端只带 `trace_id` → 默认 `cancelled`,其后续 `/compare/record` 上报再补精确态。
+
 ## 入参
 
 透传 pricebot，客户端按 pricebot 协议组装。关键字段：
@@ -41,5 +45,15 @@ Mock 出参:
 
 ## 说明
 - 一致性 hash 按 `trace_id` 路由到同一 pricebot 实例（确保 dir_cache 命中）
-- MVP 阶段不鉴权
+- 软鉴权（OptionalUser,同比价透传族）
 - 与 `/intent/recognize`、`/price/step` 等同属外卖比价透传族
+
+---
+
+## POST /api/v1/trace/epilogue — 结果页尾声帧(#112)
+
+App 收到 done、渲染完**结果页**后,把自己页面的截图(base64,body ~几百 KB)传给 pricebot 存进 trace 目录并触发重传——trace 里补上「用户实际看到的汇总页」(步骤帧只有目标 App 画面)。
+
+- **纯透传壳**:不建行、不落库(该 trace 的比价记录已由 done / finalize 落终态)。
+- 入参:`{device_id, trace_id, screenshot(base64), ...}`(pricebot 协议);出参:pricebot 原样响应。
+- 错误码同 finalize(`400` / `502`)。

docs/api/user/user-onboarding.md

@@ -61,7 +61,24 @@ Mock 入参:
 
 ---
 
+## POST /api/v1/user/onboarding/reset — 重置新手引导(#114)
+
+删除（当前账号, `device_id`）的完成标记 → 该设备下次登录/进 App 重走引导。给客户端「设置 → 重看新手引导」入口用（此前只能运营在 admin 删记录）。
+
+### 入参
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `device_id` | string | ✅ | 硬件级 ANDROID_ID（与 complete 一致） |
+
+### 出参
+```json
+{"ok": true}
+```
+幂等：无标记时也返回 ok。
+
+---
+
 ## 说明
-- 替代原 `force_onboarding`（按用户）→ 改设备维度后，运营删记录即触发重走
-- 幂等：重复标记不报错
+- 替代原 `force_onboarding`（按用户）→ 改设备维度后，运营删记录（或用户自己 reset）即触发重走
+- 幂等：重复标记 / 重复重置都不报错
 - `device_id` 为空时 `status` 一律返回未完成

docs/api/wallet/wallet-account.md

@@ -11,8 +11,9 @@
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `coin_balance` | int | 当前金币余额 |
-| `cash_balance_cents` | int | 当前现金余额（分） |
+| `cash_balance_cents` | int | 当前现金余额（分,金币兑换账） |
+| `invite_cash_balance_cents` | int | 邀请奖励金余额（分,与现金**物理隔离**的第二本账,#82;好友比价并下单发奖入账,提现走 `source=invite_cash`） |
 | `total_coin_earned` | int | 累计赚取金币 |
 
 ## 说明
-账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源。
+账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源;邀请页「奖励金」余额也读它。

docs/api/wallet/wallet-withdraw-orders.md

@@ -8,9 +8,10 @@
 |---|---|---|---|---|
 | `limit` | int | ❌ | 20 | 1–100 |
 | `cursor` | int | ❌ | null | 上一页末条 `id`,首页不传 |
+| `source` | string | ❌ | null | 按账户来源过滤:`coin_cash` / `invite_cash`;不传=全部(#121) |
 
 ## 出参
-响应 `200`:`{ items: WithdrawOrderOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](./README.md#游标分页约定)）
+响应 `200`:`{ items: WithdrawOrderOut[], next_cursor: int|null }`（分页见 [索引#游标分页约定](../README.md#游标分页约定)）
 
 **WithdrawOrderOut**
 
@@ -19,7 +20,7 @@
 | `id` | int | 单 id（也是游标） |
 | `out_bill_no` | string | 商户提现单号 |
 | `amount_cents` | int | 提现额（分） |
-| `status` | string | `pending` / `success` / `failed` |
+| `status` | string | `reviewing`(待审核)/ `pending` / `success` / `failed` / `rejected` |
 | `wechat_state` | string \| null | 微信侧原始状态 |
 | `fail_reason` | string \| null | 失败原因 |
 | `created_at` | datetime | 发起时间 |