处理冲突

# Conflicts:
#	app/admin/repositories/ad_revenue.py
#	app/admin/repositories/stats.py

.env.example

@@ -32,13 +32,6 @@ HEARTBEAT_MONITOR_ENABLED=true
 HEARTBEAT_TIMEOUT_MINUTES=60
 HEARTBEAT_SCAN_INTERVAL_SEC=60
 
-# ===== OPPO 推送(厂商通道直连,提现审核通过等交易类通知)=====
-# OPPO 开放平台注册应用后分配, 服务端鉴权用 AppKey + MasterSecret(≠极光 JG_*)。
-# 缺任一 → oppo_push_configured=False, 推送静默跳过(不影响审核/打款)。
-OPPO_PUSH_APP_KEY=
-OPPO_PUSH_MASTER_SECRET=
-# 可选(一般不改): OPPO_PUSH_ENABLED=true / OPPO_PUSH_REQUEST_TIMEOUT_SEC=10
-
 # ===== 短信 (mock 模式) =====
 # mock = true 时,任意 6 位数字均通过,且 /sms/send 不真发短信(只 log)。
 # 后续接阿里云/腾讯云短信时,改成 false 并填供应商相关 key。

alembic/versions/11c44afbea58_analytics_selfstat_tables.py

@@ -1,72 +0,0 @@
-"""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/ad_ecpm_trace_id.py

@@ -1,44 +0,0 @@
-"""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

@@ -1,35 +0,0 @@
-"""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/comparison_llm_cost.py

@@ -1,33 +0,0 @@
-"""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

@@ -1,32 +0,0 @@
-"""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

@@ -1,37 +0,0 @@
-"""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/device_oppo_register_id.py

@@ -1,34 +0,0 @@
-"""device_liveness 加 oppo_register_id 列(OPPO 直连推送目标)
-
-提现审核通过等交易类通知走 OPPO 官方推送直连(≠极光)。客户端集成 OPPO SDK 后拿到 OPPO
-registerID, 经 device/register + heartbeat 上报, 存本列; 与极光 registration_id 并列,
-一台 OPPO 设备两套 token 并存。
-
-Revision ID: device_oppo_register_id
-Revises: comparison_llm_cost
-Create Date: 2026-07-15 00:00:00.000000
-
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = 'device_oppo_register_id'
-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:
-    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
-        batch_op.add_column(
-            sa.Column('oppo_register_id', sa.String(length=128), nullable=True)
-        )
-
-
-def downgrade() -> None:
-    with op.batch_alter_table('device_liveness', schema=None) as batch_op:
-        batch_op.drop_column('oppo_register_id')

alembic/versions/merge_pages_override_coupon_slot.py

@@ -1,28 +0,0 @@
-"""合并两个 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

@@ -1,29 +0,0 @@
-"""合并两个 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 改动。"""

app/admin/main.py

@@ -26,7 +26,6 @@ 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
@@ -98,7 +97,6 @@ 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,9 +9,6 @@ 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/admin_user.py

@@ -26,17 +26,14 @@ def create_admin(
     password: str,
     role: str = "operator",
     plain_password: str | None = None,
-    pages_override: list[str] | None = None,
 ) -> AdminUser:
     """建管理员。plain_password 非空则额外留存明文(后台 UI 建的账号传,供权限管理页复看);
-    脚本/起后台建账号不传(留 None → 前端不显示密码)。
-    pages_override:role=="custom" 时传专属可见页 key 列表;普通角色为 None。"""
+    脚本/起后台建账号不传(留 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

@@ -1,146 +0,0 @@
-"""埋点健康度聚合(埋点成功率 / 上报成功率)。
-
-只存原始累计快照,查询时在 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,21 +5,17 @@
 - 发起数 = 区间内全部 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, datetime
-from datetime import date as _date
+from datetime import UTC, date as _date, datetime
 
-from sqlalchemy import case, func, or_, select
+from sqlalchemy import func, or_, select
 from sqlalchemy.orm import Session
 
 from app.core import rewards
-from app.models.coupon_state import CouponClaimRecord, CouponSession
+from app.models.coupon_state import 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:
@@ -46,47 +42,7 @@ def _avg(vals: list[int]) -> int | None:
     return round(sum(vals) / len(vals)) if vals else None
 
 
-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:
+def _session_to_row(r, phone: str | None = None, nickname: str | None = None) -> dict:
     """CouponSession ORM → 明细行 dict(主表「领券数据」与「用户全部领券」抽屉共用)。"""
     return {
         "id": r.id,
@@ -105,7 +61,6 @@ def _session_to_row(r, phone: str | None = None, nickname: str | None = None, ad
         "started_at": r.started_at,
         "claimed_count": r.claimed_count,
         "trace_url": r.trace_url,
-        "ad_revenue_yuan": ad_revenue_yuan,
     }
 
 
@@ -129,7 +84,6 @@ 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,
@@ -139,8 +93,6 @@ 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"
@@ -163,8 +115,6 @@ 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())
@@ -181,7 +131,6 @@ 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),
     }
 
     # ── 按天趋势(柱=发起/完成数,线=平均耗时)──
@@ -248,11 +197,10 @@ 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, ad_revenue_yuan=rev_map.get(r.trace_id, 0.0)))
+        items.append(_session_to_row(r, phone, nickname))
 
     return {
         "summary": summary,
@@ -274,57 +222,4 @@ 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()
-    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}
+    return {"items": [_session_to_row(r) for r in rows], "total": int(total)}

app/admin/repositories/queries.py

@@ -25,14 +25,7 @@ from app.models.feedback import Feedback
 from app.models.onboarding import OnboardingCompletion
 from app.models.price_report import PriceReport
 from app.models.user import User
-from app.models.wallet import (
-    CashTransaction,
-    CoinAccount,
-    CoinTransaction,
-    InviteCashTransaction,
-    WithdrawOrder,
-)
-from app.repositories import ad_ecpm
+from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder
 
 # 「最近活跃」计入的行为事件(与大盘 DAU/留存活跃口径一致:开始比价 + 开始领券)
 _ACTIVE_EVENTS = (COMPARE_START_EVENT, COUPON_START_EVENT)
@@ -299,11 +292,6 @@ 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
 
 
@@ -858,19 +846,26 @@ def withdraw_risk_flags(
     return flags, score
 
 
-def _check_withdraw_ledger_side(
-    orders: list[WithdrawOrder], txns: list, *, withdraw_biz: str, refund_biz: str
-) -> dict:
-    """对某一本账(普通现金 / 邀请奖励金)做提现单 ↔ 流水的交叉校验。
+def withdraw_ledger_check(db: Session) -> dict:
+    cash_balance_total = int(
+        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
+    )
+    cash_txn_total = int(
+        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
+    )
 
-    orders 已按 source 过滤到本账;txns 是本账流水表里 withdraw_biz/refund_biz 两类流水。
-    规则:每单发起应有一条扣款流水(ref_id=out_bill_no);失败/拒绝单应有且仅一条退款流水;
-    非退款终态不应出现退款流水。四个计数全为 0 即本账自洽。
-    """
-    withdraw_refs = {txn.ref_id for txn in txns if txn.biz_type == withdraw_biz}
+    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
+    cash_txns = list(
+        db.execute(
+            select(CashTransaction).where(
+                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
+            )
+        ).scalars().all()
+    )
+    withdraw_refs = {txn.ref_id for txn in cash_txns if txn.biz_type == "withdraw"}
     refund_counts: dict[str, int] = {}
-    for txn in txns:
-        if txn.biz_type == refund_biz and txn.ref_id:
+    for txn in cash_txns:
+        if txn.biz_type == "withdraw_refund" and txn.ref_id:
             refund_counts[txn.ref_id] = refund_counts.get(txn.ref_id, 0) + 1
 
     missing_withdraw = 0
@@ -885,95 +880,24 @@ def _check_withdraw_ledger_side(
         if has_refund and order.status not in {"failed", "rejected"}:
             refund_on_non_terminal += 1
 
-    return {
-        "missing_withdraw": missing_withdraw,
-        "missing_refund": missing_refund,
-        "duplicate_refund": sum(1 for count in refund_counts.values() if count > 1),
-        "refund_on_non_terminal": refund_on_non_terminal,
-    }
-
-
-def withdraw_ledger_check(db: Session) -> dict:
-    """现金账本校验:两本物理隔离的账各自对账(产品红线:coin_cash / invite_cash 不串)。
-
-    普通现金:CoinAccount.cash_balance_cents ↔ cash_transaction(withdraw/withdraw_refund);
-    邀请奖励金:CoinAccount.invite_cash_balance_cents ↔ invite_cash_transaction
-              (invite_withdraw/invite_withdraw_refund)。
-    提现单按 source 分流到对应账核对——邀请提现的流水写在 invite_cash_transaction 表,
-    绝不能拿去和普通现金流水比(否则每笔邀请提现单都会被误报「缺扣款/缺退款流水」)。
-    分流口径与 create_withdraw 一致:仅 source==invite_cash 走邀请账,其余(含历史空值)归普通现金。
-    """
-    orders = list(db.execute(select(WithdrawOrder)).scalars().all())
-    coin_orders = [o for o in orders if o.source != "invite_cash"]
-    invite_orders = [o for o in orders if o.source == "invite_cash"]
-
-    # —— 普通现金账(coin_cash) ——
-    cash_balance_total = int(
-        db.execute(select(func.coalesce(func.sum(CoinAccount.cash_balance_cents), 0))).scalar_one()
-    )
-    cash_txn_total = int(
-        db.execute(select(func.coalesce(func.sum(CashTransaction.amount_cents), 0))).scalar_one()
-    )
-    cash_txns = list(
-        db.execute(
-            select(CashTransaction).where(
-                CashTransaction.biz_type.in_(("withdraw", "withdraw_refund"))
-            )
-        ).scalars().all()
-    )
-    coin = _check_withdraw_ledger_side(
-        coin_orders, cash_txns, withdraw_biz="withdraw", refund_biz="withdraw_refund"
-    )
-    cash_diff = cash_balance_total - cash_txn_total
-
-    # —— 邀请奖励金账(invite_cash,独立账户 + 独立流水表) ——
-    invite_balance_total = int(
-        db.execute(
-            select(func.coalesce(func.sum(CoinAccount.invite_cash_balance_cents), 0))
-        ).scalar_one()
-    )
-    invite_txn_total = int(
-        db.execute(
-            select(func.coalesce(func.sum(InviteCashTransaction.amount_cents), 0))
-        ).scalar_one()
-    )
-    invite_txns = list(
-        db.execute(
-            select(InviteCashTransaction).where(
-                InviteCashTransaction.biz_type.in_(("invite_withdraw", "invite_withdraw_refund"))
-            )
-        ).scalars().all()
-    )
-    invite = _check_withdraw_ledger_side(
-        invite_orders, invite_txns,
-        withdraw_biz="invite_withdraw", refund_biz="invite_withdraw_refund",
-    )
-    invite_diff = invite_balance_total - invite_txn_total
-
+    duplicate_refund = sum(1 for count in refund_counts.values() if count > 1)
+    diff = cash_balance_total - cash_txn_total
     ok = (
-        cash_diff == 0
-        and invite_diff == 0
-        and all(v == 0 for v in coin.values())
-        and all(v == 0 for v in invite.values())
+        diff == 0
+        and missing_withdraw == 0
+        and missing_refund == 0
+        and duplicate_refund == 0
+        and refund_on_non_terminal == 0
     )
     return {
         "ok": ok,
-        # 普通现金账(coin_cash:金币兑换的现金)
         "cash_balance_total_cents": cash_balance_total,
         "cash_transaction_total_cents": cash_txn_total,
-        "balance_diff_cents": cash_diff,
-        "missing_withdraw_txn_count": coin["missing_withdraw"],
-        "missing_refund_txn_count": coin["missing_refund"],
-        "duplicate_refund_txn_count": coin["duplicate_refund"],
-        "refund_txn_on_non_terminal_count": coin["refund_on_non_terminal"],
-        # 邀请奖励金账(invite_cash:与普通现金物理隔离,各自对账)
-        "invite_cash_balance_total_cents": invite_balance_total,
-        "invite_cash_transaction_total_cents": invite_txn_total,
-        "invite_balance_diff_cents": invite_diff,
-        "invite_missing_withdraw_txn_count": invite["missing_withdraw"],
-        "invite_missing_refund_txn_count": invite["missing_refund"],
-        "invite_duplicate_refund_txn_count": invite["duplicate_refund"],
-        "invite_refund_txn_on_non_terminal_count": invite["refund_on_non_terminal"],
+        "balance_diff_cents": diff,
+        "missing_withdraw_txn_count": missing_withdraw,
+        "missing_refund_txn_count": missing_refund,
+        "duplicate_refund_txn_count": duplicate_refund,
+        "refund_txn_on_non_terminal_count": refund_on_non_terminal,
     }
 
 

app/admin/repositories/stats.py

@@ -30,17 +30,11 @@ from app.models.user import User
 from app.models.wallet import CoinTransaction, WithdrawOrder
 
 _BEIJING = timezone(timedelta(hours=8))
-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")
+COUPON_REWARD_BIZ_TYPES = ("reward_video", "ad_reward", "coupon", "coupon_reward")
 COMPARISON_REWARD_BIZ_TYPES = ("comparison", "compare_reward", "comparison_reward")
 EXCLUDED_REWARD_BIZ_TYPES = ("invite_inviter", "invite_invitee", "admin_grant")
 UNCLASSIFIED_FEED_BIZ_TYPES = ("feed_ad_reward",)
 REGULAR_TASK_EXCLUDED_BIZ_TYPES = (
-    *REWARD_VIDEO_BIZ_TYPES,
     *COUPON_REWARD_BIZ_TYPES,
     *COMPARISON_REWARD_BIZ_TYPES,
     *EXCLUDED_REWARD_BIZ_TYPES,
@@ -368,7 +362,7 @@ def dashboard_overview(
     period_reward_video_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
-        CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
+        CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
     )
     period_feed_ad_coin_total = _sum(
         CoinTransaction.amount,
@@ -390,29 +384,15 @@ 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,
@@ -563,7 +543,7 @@ def dashboard_overview(
             "reward_video_coin_total": _sum(
                 CoinTransaction.amount,
                 CoinTransaction.amount > 0,
-                CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
+                CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
             ),
             "reward_video_watch_count": _count(
                 AdRewardRecord,

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 CUSTOM_ROLE, SUPER_ADMIN_ROLE, sanitize_pages
+from app.admin.permissions import SUPER_ADMIN_ROLE
 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,22 +26,14 @@ def _active_super_count(db: AdminDb) -> int:
 
 
 def _validate_role(db: AdminDb, role: str) -> None:
-    """角色必须是 super_admin / custom(自定义) / admin_role 表里已存在的角色,否则 400。"""
-    if role in (SUPER_ADMIN_ROLE, CUSTOM_ROLE):
+    """角色必须是 super_admin 或 admin_role 表里已存在的角色,否则 400。"""
+    if role == SUPER_ADMIN_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] = []
@@ -59,16 +51,13 @@ 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, "pages_override": override},
-        ip=get_client_ip(request), commit=True,
+        detail={"username": new.username, "role": new.role}, ip=get_client_ip(request), commit=True,
     )
     return AdminOut.model_validate(new)
 
@@ -100,8 +89,7 @@ def update_admin(
         _validate_role(db, body.role)
 
     changes: dict = {}
-    role_changed = body.role is not None and body.role != target.role
-    if role_changed:
+    if body.role is not None and body.role != target.role:
         changes["role"] = {"before": target.role, "after": body.role}
         target.role = body.role
     if body.status is not None and body.status != target.status:
@@ -111,17 +99,6 @@ 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

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

app/admin/routers/coupon_data.py

@@ -18,8 +18,6 @@ from app.admin.schemas.coupon_data import (
     CouponDataOut,
     CouponDataRow,
     CouponDataSummary,
-    CouponSlotRow,
-    CouponSlotsOut,
     CouponUserRecordsOut,
 )
 from app.core.rewards import cn_today
@@ -54,10 +52,6 @@ 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",
@@ -79,7 +73,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, statuses=status, granularity=granularity,
+        user=user, app_env=env, granularity=granularity,
         limit=limit, offset=offset, sort=sort,
     )
     return CouponDataOut(
@@ -93,35 +87,6 @@ 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,8 +19,6 @@ from app.admin.schemas.ops_marquee_seed import (
     OpsMarqueeSeedCreate,
     OpsMarqueeSeedOut,
     OpsMarqueeSeedUpdate,
-    OpsRealRecordItem,
-    OpsRealRecordsOut,
     OpsSavingsFeedPreviewOut,
 )
 from app.models.admin import AdminUser
@@ -59,31 +57,9 @@ def list_seeds(db: AdminDb) -> list[OpsMarqueeSeedOut]:
 def preview_feed(
     db: AdminDb,
     limit: Annotated[int, Query(ge=1, le=30)] = 8,
-    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
 ) -> OpsSavingsFeedPreviewOut:
-    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。
-
-    mode 显式指定则预览该模式(**不改持久化配置**,供前端切换开关时实时预览);不传则用当前持久化模式。
-    """
-    if mode is not None and mode not in ops_marquee.FEED_MODES:
-        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
-    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit, mode=mode))
-
-
-@router.get("/real-records", response_model=OpsRealRecordsOut, summary="分页浏览当前模式下可展示的记录(审核用)")
-def list_real_records(
-    db: AdminDb,
-    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
-    offset: Annotated[int, Query(ge=0)] = 0,
-    limit: Annotated[int, Query(ge=1, le=50)] = 8,
-) -> OpsRealRecordsOut:
-    """分页列出**当前模式**下可在 app 轮播展示的全部记录(**不去重**):只真实=真实记录;只种子=各启用
-    种子按生成逻辑各出一行;混播=真实+种子。与 app 同口径洗牌+去连簇,固定种子→翻页稳定、能翻遍全部。
-    item.user_id=0 表示种子行。"""
-    if mode is not None and mode not in ops_marquee.FEED_MODES:
-        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
-    items, total = ops_marquee.list_real_records(db, mode=mode, offset=offset, limit=limit)
-    return OpsRealRecordsOut(items=[OpsRealRecordItem(**it) for it in items], total=total)
+    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。"""
+    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit))
 
 
 # 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。

app/admin/routers/withdraw.py

@@ -37,7 +37,6 @@ from app.integrations import wxpay
 from app.models.admin import AdminUser
 from app.repositories import app_config
 from app.repositories import wallet as wallet_repo
-from app.services import push_notify
 
 router = APIRouter(
     prefix="/admin/api/withdraws",
@@ -316,9 +315,6 @@ def bulk_approve_withdraws(
             results.append(
                 WithdrawBulkItemResult(out_bill_no=out_bill_no, ok=True, status=order.status)
             )
-            # 审核通过 → OPPO 推送(fire-and-forget, 不阻塞批量审核; status=failed 已退款, 不推)
-            if order.status != "failed":
-                push_notify.notify_withdraw_approved_async(order.user_id)
         except wallet_repo.WithdrawOrderNotFound:
             db.rollback()
             results.append(
@@ -442,9 +438,6 @@ def approve_withdraw_order(
         },
         ip=get_client_ip(request), commit=True,
     )
-    # 审核通过 → OPPO 推送(fire-and-forget, 不阻塞审核响应; status=failed 是打款失败已退款, 不推)
-    if order.status != "failed":
-        push_notify.notify_withdraw_approved_async(order.user_id)
     return WithdrawOrderOut.model_validate(order)
 
 

app/admin/schemas/admin.py

@@ -13,18 +13,14 @@ 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

@@ -1,21 +0,0 @@
-"""埋点健康度 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,11 +21,8 @@ class AdminOut(BaseModel):
     created_at: datetime
     last_login_at: datetime | None = None
     # 该管理员当前角色的有效可见页(= 左侧导航项 key);仅登录 / /me 填充,列表接口默认空。
-    # 前端据此过滤左侧导航(super_admin = 全部页;role=="custom" = pages_override)。见 permissions.py。
+    # 前端据此过滤左侧导航(super_admin = 全部页)。见 app/admin/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,14 +36,11 @@ 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
 
 
@@ -74,5 +71,3 @@ 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,16 +19,6 @@ 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):
@@ -70,9 +60,6 @@ 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):
@@ -94,22 +81,3 @@ 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/ops_marquee_seed.py

@@ -62,16 +62,3 @@ 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/wallet.py

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

app/api/v1/ad.py

@@ -286,7 +286,6 @@ 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,18 +6,13 @@ POST /api/v1/analytics/events — 批量接收新手引导(及后续)埋点,appe
 """
 from __future__ import annotations
 
-import logging
-
-from fastapi import APIRouter, HTTPException, Request
+from fastapi import APIRouter, 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:
@@ -34,13 +29,3 @@ 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/compare_record.py

@@ -27,7 +27,6 @@ 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")
@@ -82,8 +81,6 @@ 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,16 +81,7 @@ def _record_claims_blocking(
     device_id: str, user_id: int | None, trace_id: str | None, results: list[dict]
 ) -> None:
     with SessionLocal() as db:
-        # 取本次 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)
-            )
+        coupon_repo.record_claims(db, device_id, user_id, trace_id, results)
 
 
 def _mark_completed_blocking(

app/api/v1/device.py

@@ -40,7 +40,6 @@ def register_device(
         user_id=user.id,
         device_id=req.device_id,
         registration_id=req.registration_id,
-        oppo_register_id=req.oppo_register_id,
         platform=req.platform,
         app_version=req.app_version,
     )
@@ -65,7 +64,6 @@ def report_heartbeat(
         device_id=req.device_id,
         accessibility_enabled=req.accessibility_enabled,
         registration_id=req.registration_id,
-        oppo_register_id=req.oppo_register_id,
     )
     return OkResponse()
 

app/api/v1/wallet.py

@@ -43,7 +43,6 @@ from app.schemas.welfare import (
     WithdrawRequest,
     WithdrawResultOut,
     WithdrawStatusOut,
-    WithdrawTierOut,
 )
 
 logger = logging.getLogger("shagua.wallet")
@@ -174,15 +173,8 @@ def unbind_wechat(
     return UnbindWechatResultOut(bound=False)
 
 
-@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:
+@router.get("/withdraw-info", response_model=WithdrawInfoOut, summary="提现额度/绑定状态/免确认开关")
+def withdraw_info(user: CurrentUser, db: DbSession) -> WithdrawInfoOut:
     u = db.get(User, user.id)
     # 顺带同步免确认授权状态(捕获首单确认后已生效的授权 pending→active),让开关展示实时
     auth = crud_wallet.sync_transfer_auth(db, user.id)
@@ -193,7 +185,6 @@ def withdraw_info(
         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)],
     )
 
 
@@ -227,9 +218,6 @@ 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/api/v1/wx_mp.py

@@ -1,106 +0,0 @@
-"""微信服务号消息接收回调 /wx/mp/callback(裸路径, 非 /api/v1)。
-
-对应公众平台"设置与开发 → 基本配置 → 服务器配置"里填的 URL。
-  GET  : URL 接入验证 → 校验 signature → 原样返回 echostr(明文)
-  POST : 收用户消息(安全模式密文) → msg_signature 验签 → AES 解密 → 解析 XML
-         图片消息(MsgType=image): 打日志(openid/PicUrl/MediaId) + 用 PicUrl 下载落盘
-         其余消息/事件: 记一条日志忽略。一律返回 "success"(微信据此不再重试)。
-
-MVP 只做"收到图片并落盘"证明链路通;后续接:识别平台+订单 → 打 pending_compare 标记
-→ 心跳带回前端弹窗,以及 openid↔device 绑定。任何异常都返回 "success"、不让微信重试轰炸。
-"""
-from __future__ import annotations
-
-import logging
-import xml.etree.ElementTree as ET
-from pathlib import Path
-
-import httpx
-from fastapi import APIRouter, Request
-from fastapi.responses import PlainTextResponse
-
-from app.core.config import settings
-from app.integrations import wx_mp_crypto
-
-logger = logging.getLogger("shagua.wx_mp")
-
-router = APIRouter(prefix="/wx/mp", tags=["wx-mp"])
-
-# 收到的截图暂存目录(MVP 验证用;接上识别后可改为不落盘或定期清理)
-_INBOX = Path(settings.MEDIA_ROOT) / "wx_inbox"
-
-
-@router.get("/callback", include_in_schema=False)
-async def verify(
-    signature: str = "", timestamp: str = "", nonce: str = "", echostr: str = ""
-) -> PlainTextResponse:
-    """微信 URL 接入验证:校验 signature 通过则原样返回 echostr。"""
-    if not settings.WX_MP_TOKEN:
-        logger.warning("wx_mp verify: WX_MP_TOKEN 未配置")
-        return PlainTextResponse("", status_code=503)
-    if wx_mp_crypto.verify_url_signature(
-        settings.WX_MP_TOKEN, timestamp, nonce, signature
-    ):
-        return PlainTextResponse(echostr)
-    logger.warning("wx_mp verify: signature 校验失败 ts=%s nonce=%s", timestamp, nonce)
-    return PlainTextResponse("invalid signature", status_code=403)
-
-
-@router.post("/callback", include_in_schema=False)
-async def receive(request: Request) -> PlainTextResponse:
-    """收用户消息(安全模式)。任何异常都吞掉返回 success,不让微信重试轰炸,靠日志排查。"""
-    if not settings.wx_mp_callback_configured:
-        logger.warning("wx_mp receive: 回调凭证未配齐(Token/AESKey/AppID)")
-        return PlainTextResponse("success")
-    try:
-        body = (await request.body()).decode("utf-8")
-        qp = request.query_params
-        # 安全模式外层 XML 只有 ToUserName + Encrypt。来源=微信服务器(HTTPS)+ 下面验签,
-        # 且 stdlib ET 不扩展外部实体, XXE 不适用。
-        encrypt = ET.fromstring(body).findtext("Encrypt") or ""
-        if not wx_mp_crypto.verify_msg_signature(
-            settings.WX_MP_TOKEN,
-            qp.get("timestamp", ""),
-            qp.get("nonce", ""),
-            encrypt,
-            qp.get("msg_signature", ""),
-        ):
-            logger.warning("wx_mp receive: msg_signature 校验失败")
-            return PlainTextResponse("success")
-        xml = wx_mp_crypto.decrypt_message(
-            settings.WX_MP_AES_KEY, settings.WX_MP_APPID, encrypt
-        )
-        await _handle_message(ET.fromstring(xml))
-    except Exception:
-        logger.exception("wx_mp receive: 处理异常")
-    return PlainTextResponse("success")
-
-
-async def _handle_message(root: ET.Element) -> None:
-    openid = root.findtext("FromUserName") or ""
-    msg_type = root.findtext("MsgType") or ""
-    if msg_type == "image":
-        pic_url = root.findtext("PicUrl") or ""
-        media_id = root.findtext("MediaId") or ""
-        logger.info(
-            "wx_mp 收到图片: openid=%s media_id=%s pic_url=%s", openid, media_id, pic_url
-        )
-        await _download(pic_url, openid, media_id)
-    else:
-        logger.info("wx_mp 收到消息(暂忽略): openid=%s type=%s", openid, msg_type)
-
-
-async def _download(pic_url: str, openid: str, media_id: str) -> None:
-    """用 PicUrl 直接下载图片落盘。PicUrl 是临时公网链接,无需 access_token / IP 白名单。"""
-    if not pic_url:
-        return
-    try:
-        _INBOX.mkdir(parents=True, exist_ok=True)
-        async with httpx.AsyncClient(timeout=15) as client:
-            resp = await client.get(pic_url)
-            resp.raise_for_status()
-        dest = _INBOX / f"{openid[:12]}_{media_id[:16]}.jpg"
-        dest.write_bytes(resp.content)
-        logger.info("wx_mp 图片已落盘: %s (%d bytes)", dest, len(resp.content))
-    except Exception:
-        logger.exception("wx_mp 图片下载失败 pic_url=%s", pic_url)

app/core/config.py

@@ -71,34 +71,6 @@ class Settings(BaseSettings):
     HEARTBEAT_TIMEOUT_MINUTES: int = 60          # 多久没心跳算掉线(1 小时,避免短暂离线误判被杀)
     HEARTBEAT_SCAN_INTERVAL_SEC: int = 60        # 扫描周期
 
-    # ===== OPPO 推送(厂商通道直连) =====
-    # 直连 OPPO PUSH 服务端 API(api.push.oppomobile.com), 不经极光。凭证来自 OPPO 开放平台
-    # 注册应用后分配(≠极光 JG_*)。两步鉴权: 先 /server/v1/auth 用 sha256(app_key+timestamp+
-    # master_secret) 换 auth_token(缓存 24h), 再带 auth_token 调 /message/notification/unicast
-    # 单推。提现审核通过等交易类通知走这条。未配凭证 → oppo_push_configured=False, 发送方静默
-    # 跳过(不连累审核/打款)。
-    OPPO_PUSH_ENABLED: bool = True               # 总开关(配了凭证也能置 False 全局停发)
-    OPPO_PUSH_APP_KEY: str = ""
-    OPPO_PUSH_MASTER_SECRET: str = ""
-    OPPO_PUSH_AUTH_ENDPOINT: str = "https://api.push.oppomobile.com/server/v1/auth"
-    OPPO_PUSH_UNICAST_ENDPOINT: str = (
-        "https://api.push.oppomobile.com/server/v1/message/notification/unicast"
-    )
-    OPPO_PUSH_REQUEST_TIMEOUT_SEC: int = 10
-    # 通知点击行为(OPPO click_action_type; 0=启动应用首页)。交易类通知点开进首页即可。
-    OPPO_PUSH_CLICK_ACTION_TYPE: int = 0
-    # 通知渠道 id(Android 8+ NotificationChannel): 【客户端创建的渠道】+【OPPO 管理台登记】+
-    # 【服务端此值】三方必须一致, 否则真机可能不展示。客户端 OppoPushHelper.CHANNEL_ID 同值。
-    OPPO_PUSH_CHANNEL_ID: str = "push_oplus_category_content"
-    # OPPO 新消息分类(Android 12+ 触达; 提现属 ACCOUNT 账号资产变化)。默认空=不带该字段——
-    # 它依赖 OPPO 管理台的消息分类资质, 未开通就带上可能反被限制, 确认资质后再填(如 "ACCOUNT")。
-    OPPO_PUSH_CATEGORY: str = ""
-
-    @property
-    def oppo_push_configured(self) -> bool:
-        """OPPO 推送凭证是否齐备(app_key + master_secret)。缺任一 → 发送方静默跳过。"""
-        return bool(self.OPPO_PUSH_APP_KEY and self.OPPO_PUSH_MASTER_SECRET)
-
     # ===== 短信 =====
     SMS_MOCK: bool = True
     SMS_CODE_TTL_SEC: int = 300
@@ -164,12 +136,6 @@ class Settings(BaseSettings):
     # (不跳授权、不拿 openid),整套微信代码保留。审核通过后 .env 置 true + 重启即启用,无需改代码。
     WX_MP_OAUTH_ENABLED: bool = False
 
-    # ===== 微信服务号(消息接收回调) =====
-    # 用户发消息给服务号 → 微信 POST 到 /wx/mp/callback(安全模式:Token 验签 + AESKey 解密)。
-    # 区别于上面的网页授权(那是落地页拿 openid);这里是被动收用户主动发来的消息(截图比价入口)。
-    WX_MP_TOKEN: str = ""            # 公众平台"服务器配置"的 Token(URL 验签 + 消息验签)
-    WX_MP_AES_KEY: str = ""          # EncodingAESKey(43 位, 消息 AES-256-CBC 加解密)
-
     @property
     def wx_mp_configured(self) -> bool:
         """服务号网页授权凭证齐全(缺则落地页不发起授权,降级为无 openid)。"""
@@ -180,11 +146,6 @@ class Settings(BaseSettings):
         """落地页是否真正发起微信授权 = 凭证齐全 且 总开关开。"""
         return self.wx_mp_configured and self.WX_MP_OAUTH_ENABLED
 
-    @property
-    def wx_mp_callback_configured(self) -> bool:
-        """消息接收回调凭证齐全(Token + AESKey + AppID)。缺则回调端点拒绝处理消息。"""
-        return bool(self.WX_MP_TOKEN and self.WX_MP_AES_KEY and self.WX_MP_APPID)
-
     # ===== 微信支付(商家转账到零钱 / 提现)=====
     # 真实凭证放 .env(已 gitignore),证书 .pem 放 secrets/。WECHAT_APP_ID 同时用于
     # 微信登录(code 换 openid)与转账,必须与 App 端开放平台 appid 一致。

app/core/config_schema.py

@@ -96,19 +96,4 @@ 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/rewards.py

@@ -6,7 +6,6 @@
 from __future__ import annotations
 
 from datetime import date, datetime, timedelta, timezone
-from typing import NamedTuple
 
 # 业务时区:签到的"今天"按北京时间算,不能用 UTC。
 # 否则 UTC+8 的凌晨 0~8 点会被算成 UTC 的前一天,导致签到日期错位。
@@ -53,30 +52,6 @@ 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/integrations/oppo_push.py

@@ -1,183 +0,0 @@
-"""OPPO 推送服务端直连(厂商通道)。
-
-不经极光, 直接调 OPPO PUSH 服务端 API(api.push.oppomobile.com)。提现审核通过等交易类
-通知走这条。凭证来自 OPPO 开放平台(app_key/master_secret, 见 settings.OPPO_PUSH_*)。
-
-两步鉴权(OPPO 协议):
-  1. POST /server/v1/auth  用 sign=sha256(app_key+timestamp+master_secret) 换 auth_token
-     (有效期 24h)。token 进程内缓存复用, 到期前自动重取。
-  2. POST /server/v1/message/notification/unicast  header 带 auth_token, 按单个
-     registration_id(OPPO 的 registerID) 定向推送一条通知栏消息。
-
-发送 best-effort: 未配凭证 / 网络失败 / OPPO 返错都抛 OppoPushError, 由调用方(push_notify)
-吞掉只记日志, 绝不连累审核/打款主流程。风格对齐 integrations/sms.py(httpx 同步 + 未配降级)。
-"""
-from __future__ import annotations
-
-import hashlib
-import json
-import logging
-import time
-from dataclasses import dataclass
-from threading import Lock
-
-import httpx
-
-from app.core.config import settings
-
-logger = logging.getLogger("shagua.oppo_push")
-
-# OPPO target_type 枚举: 2 = 按 registration_id 单推
-_TARGET_TYPE_REGISTRATION_ID = 2
-# auth_token 官方有效期 24h; 提前 1h 视为过期重取, 留刷新余量(避免边界请求踩到刚过期)
-_TOKEN_TTL_SEC = 24 * 3600
-_TOKEN_REFRESH_MARGIN_SEC = 3600
-
-
-class OppoPushError(Exception):
-    """OPPO 推送失败(未配置 / 鉴权失败 / 网络错误 / OPPO 返错)。调用方 best-effort 吞。"""
-
-
-@dataclass
-class _CachedToken:
-    token: str
-    expires_at: float   # epoch 秒(= 取到 token 的时刻 + 24h)
-
-
-# 进程内存 token 缓存(单 worker 有效; 多 worker 各自缓存, 各自换 token, OPPO 侧无副作用)
-_token_cache: _CachedToken | None = None
-_token_lock = Lock()
-
-
-def _sign(app_key: str, timestamp_ms: int, master_secret: str) -> str:
-    """OPPO 鉴权签名: sha256(app_key + timestamp + master_secret) 十六进制小写。"""
-    raw = f"{app_key}{timestamp_ms}{master_secret}"
-    return hashlib.sha256(raw.encode("utf-8")).hexdigest()
-
-
-def _parse_oppo_response(resp: httpx.Response, phase: str) -> dict | None:
-    """解析 OPPO 统一响应 {code, message, data}: code==0 返 data, 否则抛 OppoPushError。"""
-    try:
-        body = resp.json()
-    except Exception as e:
-        raise OppoPushError(
-            f"OPPO {phase} 响应非 JSON(http={resp.status_code}): {resp.text[:200]}"
-        ) from e
-    if body.get("code") != 0:
-        raise OppoPushError(
-            f"OPPO {phase} 失败 code={body.get('code')} message={body.get('message')!r}"
-        )
-    return body.get("data")
-
-
-def _fetch_auth_token() -> str:
-    """调 /server/v1/auth 换 auth_token。失败抛 OppoPushError。"""
-    timestamp_ms = int(time.time() * 1000)   # 毫秒时间戳(OPPO 允许 ±10 分钟误差)
-    sign = _sign(
-        settings.OPPO_PUSH_APP_KEY, timestamp_ms, settings.OPPO_PUSH_MASTER_SECRET
-    )
-    try:
-        resp = httpx.post(
-            settings.OPPO_PUSH_AUTH_ENDPOINT,
-            data={
-                "app_key": settings.OPPO_PUSH_APP_KEY,
-                "sign": sign,
-                "timestamp": timestamp_ms,
-            },
-            timeout=settings.OPPO_PUSH_REQUEST_TIMEOUT_SEC,
-        )
-    except httpx.HTTPError as e:
-        raise OppoPushError(f"OPPO auth 网络错误: {e}") from e
-
-    data = _parse_oppo_response(resp, "auth")
-    token = (data or {}).get("auth_token")
-    if not token:
-        raise OppoPushError(f"OPPO auth 未返回 auth_token: {resp.text[:200]}")
-    return token
-
-
-def _get_auth_token(force_refresh: bool = False) -> str:
-    """取 auth_token(缓存优先; 到期或 force_refresh 才重取)。线程安全。"""
-    global _token_cache
-    now = time.time()
-    with _token_lock:
-        cache = _token_cache
-        if (
-            not force_refresh
-            and cache is not None
-            and now < cache.expires_at - _TOKEN_REFRESH_MARGIN_SEC
-        ):
-            return cache.token
-        token = _fetch_auth_token()
-        _token_cache = _CachedToken(token=token, expires_at=now + _TOKEN_TTL_SEC)
-        return token
-
-
-def send_notification(
-    registration_id: str,
-    title: str,
-    content: str,
-    *,
-    click_action_type: int | None = None,
-) -> str:
-    """向单个 OPPO registerID 推一条通知栏消息, 返回 OPPO message_id。
-
-    失败(未配置 / 鉴权 / 网络 / OPPO 返错)一律抛 OppoPushError, 由调用方吞。
-    unicast 首次失败时强刷一次 token 重试(覆盖 token 被 OPPO 提前失效的情况); 网络错误不重试。
-    """
-    if not settings.OPPO_PUSH_ENABLED:
-        raise OppoPushError("OPPO 推送总开关关闭(OPPO_PUSH_ENABLED=false)")
-    if not settings.oppo_push_configured:
-        raise OppoPushError("OPPO 推送未配置(缺 OPPO_PUSH_APP_KEY/OPPO_PUSH_MASTER_SECRET)")
-    if not registration_id:
-        raise OppoPushError("registration_id 为空")
-
-    if click_action_type is None:
-        click_action_type = settings.OPPO_PUSH_CLICK_ACTION_TYPE
-    notification = {
-        "title": title,
-        "content": content,
-        "click_action_type": click_action_type,
-    }
-    # channel_id: Android 8+ 通知渠道(客户端已建同名渠道 + OPPO 管理台登记, 三方一致才展示)。
-    if settings.OPPO_PUSH_CHANNEL_ID:
-        notification["channel_id"] = settings.OPPO_PUSH_CHANNEL_ID
-    # category: OPPO 新消息分类(默认空不带; 依赖管理台资质, 见 config 注释)。
-    if settings.OPPO_PUSH_CATEGORY:
-        notification["category"] = settings.OPPO_PUSH_CATEGORY
-    message = {
-        "target_type": _TARGET_TYPE_REGISTRATION_ID,
-        "target_value": registration_id,
-        "notification": notification,
-    }
-    # OPPO unicast body 是 form 编码, message 字段为 JSON 字符串
-    payload = {"message": json.dumps(message, ensure_ascii=False)}
-
-    last_err: OppoPushError | None = None
-    for attempt in range(2):
-        token = _get_auth_token(force_refresh=(attempt == 1))
-        try:
-            resp = httpx.post(
-                settings.OPPO_PUSH_UNICAST_ENDPOINT,
-                data=payload,
-                headers={"auth_token": token},
-                timeout=settings.OPPO_PUSH_REQUEST_TIMEOUT_SEC,
-            )
-        except httpx.HTTPError as e:
-            # 网络错误与 token 无关, 不强刷重试
-            raise OppoPushError(f"OPPO unicast 网络错误: {e}") from e
-        try:
-            data = _parse_oppo_response(resp, "unicast")
-        except OppoPushError as e:
-            last_err = e
-            if attempt == 0:
-                logger.warning("[OPPO] unicast 失败(%s), 强刷 token 重试一次", e)
-                continue
-            raise
-        message_id = (data or {}).get("message_id", "")
-        logger.info(
-            "[OPPO] 推送成功 regId=%s… message_id=%s", registration_id[:12], message_id
-        )
-        return message_id
-    # 理论到不了(第二次失败已 raise); 防御性收尾
-    raise last_err or OppoPushError("OPPO unicast 重试后仍失败")

app/integrations/wx_mp_crypto.py

@@ -1,69 +0,0 @@
-"""微信服务号消息接收回调的验签与解密(安全模式)。
-
-服务号"服务器配置"选安全模式后:
-  - URL 接入验证(GET): sha1(sort(token, timestamp, nonce)) == signature → 原样返回 echostr
-  - 消息(POST): body 里 <Encrypt> 是密文;
-      msg_signature = sha1(sort(token, timestamp, nonce, encrypt))
-      密文 AES-256-CBC 解出: random(16B) + msg_len(4B big-endian) + msg + appid, 去 PKCS7(块=32) padding
-
-只做验签 + 解密(收消息)。被动回复(加密)MVP 不需要 —— 收到后走客服消息异步回执。
-密钥/口令来自 settings(WX_MP_TOKEN / WX_MP_AES_KEY / WX_MP_APPID),本模块只做纯算法、不读配置。
-"""
-from __future__ import annotations
-
-import base64
-import hashlib
-import hmac
-
-from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
-
-
-def verify_url_signature(token: str, timestamp: str, nonce: str, signature: str) -> bool:
-    """GET 接入验证:token/timestamp/nonce 三者字典序排序拼接后 sha1。"""
-    return _consteq(_sha1(token, timestamp, nonce), signature)
-
-
-def verify_msg_signature(
-    token: str, timestamp: str, nonce: str, encrypt: str, msg_signature: str
-) -> bool:
-    """POST 消息验签:四者(含密文 encrypt)字典序排序拼接后 sha1。"""
-    return _consteq(_sha1(token, timestamp, nonce, encrypt), msg_signature)
-
-
-def decrypt_message(aes_key_b64: str, expected_appid: str, encrypt_b64: str) -> str:
-    """解密 <Encrypt> 密文, 返回明文消息 XML。appid 不符抛 ValueError。
-
-    aes_key_b64: EncodingAESKey(43 位, 不含结尾 '='), 补 '=' 后 base64 解出 32 字节 AES-256 key。
-    """
-    aes_key = base64.b64decode(aes_key_b64 + "=")  # 43 → 32 bytes
-    iv = aes_key[:16]
-    decryptor = Cipher(algorithms.AES(aes_key), modes.CBC(iv)).decryptor()
-    plain = decryptor.update(base64.b64decode(encrypt_b64)) + decryptor.finalize()
-    plain = _pkcs7_unpad(plain)
-
-    # random(16) + msg_len(4, big-endian) + msg(msg_len) + from_appid
-    content = plain[16:]
-    msg_len = int.from_bytes(content[:4], "big")
-    msg = content[4 : 4 + msg_len]
-    from_appid = content[4 + msg_len :].decode("utf-8")
-    if expected_appid and from_appid != expected_appid:
-        raise ValueError(f"appid mismatch: {from_appid!r} != {expected_appid!r}")
-    return msg.decode("utf-8")
-
-
-def _sha1(*parts: str) -> str:
-    return hashlib.sha1("".join(sorted(parts)).encode("utf-8")).hexdigest()
-
-
-def _consteq(a: str, b: str) -> bool:
-    return hmac.compare_digest(a, b)
-
-
-def _pkcs7_unpad(data: bytes) -> bytes:
-    """微信用块大小 32 的 PKCS7,末字节即 padding 长度(1..32)。越界则原样返回(容错)。"""
-    if not data:
-        return data
-    pad = data[-1]
-    if pad < 1 or pad > 32:
-        return data
-    return data[:-pad]

app/main.py

@@ -39,7 +39,6 @@ from app.api.v1.signin import router as signin_router
 from app.api.v1.tasks import router as tasks_router
 from app.api.v1.user import router as user_router
 from app.api.v1.wallet import router as wallet_router
-from app.api.v1.wx_mp import router as wx_mp_router
 from app.api.v1.wxpay import router as wxpay_router
 from app.core.config import settings
 from app.core.daily_exchange_worker import (
@@ -141,8 +140,6 @@ app.include_router(internal_launch_confirm_router)
 app.include_router(platform_router)
 # CPS 群发短链跳转 /c/{code}(公网无鉴权:记点击 → 302 跳美团)
 app.include_router(cps_redirect_router)
-# 微信服务号消息接收回调 /wx/mp/callback(公网无鉴权:微信服务器验签, 截图比价入口)
-app.include_router(wx_mp_router)
 
 # 用户上传文件(头像)静态服务。生产可改由 nginx 直接 serve MEDIA_ROOT。
 _media_root = Path(settings.MEDIA_ROOT)

app/models/__init__.py

@@ -7,10 +7,6 @@ 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

app/models/ad_ecpm.py

@@ -32,9 +32,6 @@ 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,11 +28,8 @@ class AdminUser(Base):
     # 明文登录密码:仅「后台 UI 创建/重置」的管理员留存,供超管在权限管理页复看转交。
     # 脚本/起后台时建的超管账号不写(为 None → 前端「不显示密码」)。⚠️ 内部工具便利取舍,见 create/list。
     plain_password: Mapped[str | None] = mapped_column(String(128), nullable=True)
-    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)/ custom(按人自定义)
+    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)
     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_selfstat.py

@@ -1,59 +0,0 @@
-"""埋点/上报成功率自报计数快照表(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,12 +137,6 @@ 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,9 +66,6 @@ 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)
@@ -243,10 +240,6 @@ 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/device.py

@@ -44,9 +44,6 @@ class DeviceLiveness(Base):
     device_id: Mapped[str] = mapped_column(String(128), index=True, nullable=False)
     # 极光推送 registration id;拿到才填(JCollectionAuth 同意后才下发)
     registration_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
-    # OPPO 官方推送 SDK(HeytapPushManager)的 registerID; 直连 OPPO 厂商通道用(≠极光 registration_id)。
-    # 一台 OPPO 设备两套 token 并存: 极光走极光自有/其它厂商通道, 这个走 OPPO 直连(提现审核通过等交易通知)。
-    oppo_register_id: Mapped[str | None] = mapped_column(String(128), nullable=True)
     platform: Mapped[str] = mapped_column(String(16), nullable=False, default="android")
     app_version: Mapped[str | None] = mapped_column(String(32), nullable=True)
 

app/repositories/ad_ecpm.py

@@ -10,7 +10,6 @@ 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
 
@@ -25,7 +24,6 @@ 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:
@@ -45,7 +43,6 @@ 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,
@@ -108,27 +105,3 @@ 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,19 +176,10 @@ 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=reward_biz, ref_id=client_event_id,
-        remark=reward_remark,
+        biz_type="feed_ad_reward", ref_id=client_event_id,
+        remark="信息流广告奖励",
     )
     rec = AdFeedRewardRecord(
         client_event_id=client_event_id,

app/repositories/analytics_selfstat.py

@@ -1,38 +0,0 @@
-"""自报计数快照落库。一次事务:插 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,22 +147,12 @@ 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:
     """一批券领取结果幂等写入,返回写入(新增 + 更新)条数。
 
@@ -196,15 +186,12 @@ 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, app_env=app_env,
-                vendor=r.get("vendor"), coupon_name=r.get("name"),
+                status=status, vendor=r.get("vendor"), coupon_name=r.get("name"),
                 claimed_count=count, trace_id=trace_id, reason=r.get("reason"),
                 extra=r,
             ))
@@ -248,47 +235,6 @@ 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(
@@ -375,31 +321,3 @@ 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/device.py

@@ -22,18 +22,16 @@ def register_or_update(
     user_id: int,
     device_id: str,
     registration_id: str | None,
-    oppo_register_id: str | None = None,
     platform: str = "android",
     app_version: str | None = None,
 ) -> DeviceLiveness:
-    """注册设备或更新其 registration_id / oppo_register_id / 元信息。upsert by (user_id, device_id)。"""
+    """注册设备或更新其 registration_id / 元信息。upsert by (user_id, device_id)。"""
     device = _get(db, user_id=user_id, device_id=device_id)
     if device is None:
         device = DeviceLiveness(
             user_id=user_id,
             device_id=device_id,
             registration_id=registration_id,
-            oppo_register_id=oppo_register_id,
             platform=platform or "android",
             app_version=app_version,
         )
@@ -41,8 +39,6 @@ def register_or_update(
     else:
         if registration_id:
             device.registration_id = registration_id
-        if oppo_register_id:
-            device.oppo_register_id = oppo_register_id
         if platform:
             device.platform = platform
         if app_version:
@@ -59,13 +55,11 @@ def touch_heartbeat(
     device_id: str,
     accessibility_enabled: bool,
     registration_id: str | None,
-    oppo_register_id: str | None = None,
 ) -> DeviceLiveness:
     """处理一次心跳(心跳也能自注册)。
 
     service 心跳或 accessibility_enabled=true 时,刷新存活并把状态机重置回 alive、
-    清掉 notified_at(掉线恢复 → 下次再断才会再推一条)。registration_id / oppo_register_id
-    非空时顺带更新(客户端拿到 push token 后每次心跳带上, 后端最终一致)。
+    清掉 notified_at(掉线恢复 → 下次再断才会再推一条)。
     """
     now = datetime.now(timezone.utc)
     device = _get(db, user_id=user_id, device_id=device_id)
@@ -75,8 +69,6 @@ def touch_heartbeat(
 
     if registration_id:
         device.registration_id = registration_id
-    if oppo_register_id:
-        device.oppo_register_id = oppo_register_id
     device.last_report_protection_on = accessibility_enabled
 
     if accessibility_enabled:
@@ -126,25 +118,6 @@ def get_device(db: Session, *, user_id: int, device_id: str) -> DeviceLiveness |
     return _get(db, user_id=user_id, device_id=device_id)
 
 
-def list_oppo_register_ids_by_user(db: Session, *, user_id: int) -> list[str]:
-    """取某用户所有设备已登记的 OPPO registerID(去重保序, 非空)。
-
-    提现审核通过推送用: 一个用户可能多台设备, 每台都推; 没 OPPO token 的设备(非 OPPO 机 /
-    未集成 OPPO SDK)自然不在列。空列表 = 该用户没有可推的 OPPO 设备。
-    """
-    stmt = select(DeviceLiveness.oppo_register_id).where(
-        DeviceLiveness.user_id == user_id,
-        DeviceLiveness.oppo_register_id.is_not(None),
-    )
-    seen: set[str] = set()
-    out: list[str] = []
-    for rid in db.execute(stmt).scalars().all():
-        if rid and rid not in seen:
-            seen.add(rid)
-            out.append(rid)
-    return out
-
-
 def ack_kill_alert(db: Session, *, user_id: int, device_id: str) -> None:
     """客户端已弹过「开启自启动」引导 → 清「待提醒」标记(幂等; 下次真掉线 worker 再置)。"""
     device = _get(db, user_id=user_id, device_id=device_id)

app/repositories/ops_marquee.py

@@ -30,7 +30,6 @@ from app.models.comparison import ComparisonRecord
 from app.models.ops_marquee_seed import OpsMarqueeSeed
 from app.models.user import User
 from app.repositories import app_config
-from app.repositories.user import is_default_nickname
 
 # 首页轮播数据源模式(存 app_config.marquee_feed_mode):
 #   mixed=真实优先+种子补位+合成兜底(默认,原行为);real=只真实(不足则少/空);seed=只种子+合成兜底。
@@ -141,12 +140,9 @@ def _synth_masked_name(rng: random.Random) -> str:
 
 def _mask_real(nickname: str | None, user_id: int) -> str:
     """真实用户脱敏(对齐 PRD「用户标识打码规则」):设过昵称→昵称脱敏(中英文皆可);
-    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。
-
-    创建时自动分配的默认昵称(「用户」+9 位随机,见 user.is_default_nickname)不算用户主动设的昵称,
-    按「无昵称」处理走 id 规则(产品决策 2026-07:默认昵称归入「没昵称」档)。"""
+    没昵称→「用户」+5星+id 后 2 位(用户*****08),按 user_id 稳定、刷新不变脸。"""
     nick = (nickname or "").strip()
-    if nick and not is_default_nickname(nick):
+    if nick:
         return _mask_nickname(nick)
     return _mask_anon(user_id)
 
@@ -217,47 +213,34 @@ 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]:
+def get_feed(db: Session, limit: int = 8) -> list[dict]:
     """返回最多 limit 条 {masked_user, saved_amount_cents, time(HH:MM:SS 北京)}。
 
-    mode:显式传入(admin 预览指定模式)则用它、**不改持久化配置**;不传(客户端 /savings-feed)读
-    持久化的 marquee_feed_mode;非法值一律回退到持久化模式。
-    真实条:success 且 0 < saved ≤ 上限,**不按 user 去重**(打乱 + 去连簇:相邻尽量不同用户、减少单人连刷)后取前 limit。
+    真实条:success 且 0 < saved ≤ 上限,按 user 去重(同一用户只取最新一条,避免单人刷屏)。
     不足用启用的种子补齐——**公平随机抽取** need 个(而非固定取前 N),让所有种子都有机会露出;
     种子用户名留空则随机合成(避开撞名),金额取**长尾随机**(小额居多、偶尔大额,更像真实分布)。
     真实 + 种子仍不满 limit → 内置合成条**补满**,保证轮播既不空也不稀疏。
     展示时间统一「刷新」成相对现在的最近时刻(从 now 往前**随机抖动**递减),保证轮播永远像刚发生、
     节奏自然不机械(真实用户/金额不变,只换展示时间——避免旧测试数据 / 低谷期记录显示成过时时间)。
     """
-    # 预览可显式指定模式(所见=选中模式,不依赖 PATCH 落库时序);None/非法 → 读持久化配置。
-    mode = mode if mode in FEED_MODES else get_feed_mode(db)  # mixed / real / seed
+    mode = get_feed_mode(db)  # mixed / real / seed(运营可在「首页轮播种子」页切换)
 
     items: list[dict] = []
     used_names: set[str] = set()
 
-    # 真实条(mixed / real):**不按 user 去重**——打乱 + 去连簇(相邻尽量不同用户、减少单人连刷)后取前
-    # limit;金额超上限的异常值已在查询剔除。同一用户可多条露出,但被打散、尽量不连续。
+    # 真实条(mixed / real):取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
     if mode != "seed":
-        for uid, sc, nick in _shuffle_declustered(_recent_real_rows(db))[:limit]:
+        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)
             name = _mask_real(nick, uid)
-            used_names.add(name)  # 同一用户可多条,名字重复无害(used_names 仅供种子避重)
+            used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
             items.append({"masked_user": name, "saved_amount_cents": int(sc)})
+            if len(items) >= limit:
+                break
 
     # 种子补位 + 合成兜底(mixed / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
     # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
@@ -310,78 +293,6 @@ 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/user.py

@@ -42,22 +42,6 @@ def _gen_nickname() -> str:
     )
 
 
-def is_default_nickname(nickname: str | None) -> bool:
-    """是否为创建时自动分配的默认昵称(= "用户" + 9 位字母数字,见 [_gen_nickname])。
-
-    这类不是用户主动设置的昵称,展示脱敏时按「无昵称」处理(走 id 规则,见 ops_marquee._mask_real)。
-    精确匹配生成格式(前缀 + 定长字母数字集),不误伤真人以「用户」开头的昵称(如「用户体验师」含汉字、
-    长度也不符)。用户改过昵称即不再匹配。"""
-    if not nickname:
-        return False
-    s = nickname.strip()
-    return (
-        len(s) == len(_NICKNAME_PREFIX) + _NICKNAME_LEN
-        and s.startswith(_NICKNAME_PREFIX)
-        and all(c in _NICKNAME_ALPHABET for c in s[len(_NICKNAME_PREFIX):])
-    )
-
-
 def get_user_by_username(db: Session, username: str) -> User | None:
     return db.execute(
         select(User).where(User.username == username)

app/repositories/wallet.py

@@ -11,7 +11,7 @@ import unicodedata
 import uuid
 from datetime import datetime, timedelta, timezone
 
-from sqlalchemy import func, select, update
+from sqlalchemy import select, update
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -67,10 +67,6 @@ class WithdrawTooFrequentError(Exception):
     """提现申请过于频繁,或已有未完成提现单。"""
 
 
-class WithdrawTierUnavailableError(Exception):
-    """该档位今日不可提:次数已满,或今天已选了其他额度(7-9 福利页档位规则)。"""
-
-
 class WithdrawTransferError(Exception):
     """调用微信转账失败(已退回余额)。"""
 
@@ -609,89 +605,6 @@ 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对齐):
-      - 新人档(0.1/0.3):账号历史一次性——只要发起过(**任意状态**,含被拒/失败,"发起就算")
-        即视为已用,直接**从返回列表消失**;两档各自独立互不影响,不参与"每日选一个额度"互斥。
-      - 常规档(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),
-            )
-        ).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,
@@ -747,19 +660,6 @@ 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,12 +63,6 @@ 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

@@ -1,34 +0,0 @@
-"""自报计数上报 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/device.py

@@ -9,7 +9,6 @@ from pydantic import BaseModel, ConfigDict
 class DeviceRegisterRequest(BaseModel):
     device_id: str
     registration_id: str | None = None
-    oppo_register_id: str | None = None
     platform: str = "android"
     app_version: str | None = None
 
@@ -19,7 +18,6 @@ class HeartbeatRequest(BaseModel):
     source: str = "service"          # service | app
     accessibility_enabled: bool = True
     registration_id: str | None = None
-    oppo_register_id: str | None = None
 
 
 class DeviceOut(BaseModel):
@@ -28,7 +26,6 @@ class DeviceOut(BaseModel):
     id: int
     device_id: str
     registration_id: str | None
-    oppo_register_id: str | None
     ever_protected: bool
     liveness_state: str
     last_heartbeat_at: datetime | None

app/schemas/welfare.py

@@ -75,21 +75,6 @@ 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="单次最高提现(分)")
@@ -99,10 +84,6 @@ 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

@@ -1,53 +0,0 @@
-"""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}

app/services/push_notify.py

@@ -1,74 +0,0 @@
-"""推送通知编排(查设备 push token → 调厂商推送)。
-
-薄编排层: repositories(取 token) + integrations(发送) 的粘合, 供 api / admin router 调用。
-所有发送 best-effort —— 失败只 log, 绝不抛给调用方(不连累审核/打款等主流程)。
-
-当前只有 OPPO 直连一条通道(提现审核通过通知)。后续加华为/vivo 等厂商时, 在这里按设备
-token 做通道分发, 上层业务函数(notify_withdraw_approved 等)不感知通道差异。
-"""
-from __future__ import annotations
-
-import logging
-import threading
-
-from sqlalchemy.orm import Session
-
-from app.db.session import SessionLocal
-from app.integrations import oppo_push
-from app.integrations.oppo_push import OppoPushError
-from app.repositories import device as device_repo
-
-logger = logging.getLogger("shagua.push_notify")
-
-_WITHDRAW_APPROVED_TITLE = "提现审核通过"
-_WITHDRAW_APPROVED_CONTENT = "您的提现申请已审核通过，款项将很快到账，请留意微信零钱。"
-
-
-def notify_withdraw_approved(db: Session, *, user_id: int) -> int:
-    """提现审核通过 → 给该用户所有 OPPO 设备各推一条通知。返回成功推送的设备数。
-
-    best-effort: 未配 OPPO / 无 OPPO 设备 / 单设备发送失败都不抛, 只 log。审核主流程绝不受影响。
-    调用方仍应包一层 try/except 兜底本函数自身的意外异常(如 DB 查询失败)。
-    """
-    reg_ids = device_repo.list_oppo_register_ids_by_user(db, user_id=user_id)
-    if not reg_ids:
-        logger.info("[push] withdraw_approved user_id=%s 无 OPPO 设备, 跳过", user_id)
-        return 0
-
-    sent = 0
-    for rid in reg_ids:
-        try:
-            oppo_push.send_notification(
-                rid, _WITHDRAW_APPROVED_TITLE, _WITHDRAW_APPROVED_CONTENT
-            )
-            sent += 1
-        except OppoPushError as e:
-            logger.warning(
-                "[push] withdraw_approved user_id=%s regId=%s… 发送失败: %s",
-                user_id, rid[:12], e,
-            )
-    logger.info(
-        "[push] withdraw_approved user_id=%s 推送 %d/%d 台 OPPO 设备",
-        user_id, sent, len(reg_ids),
-    )
-    return sent
-
-
-def notify_withdraw_approved_async(user_id: int) -> None:
-    """fire-and-forget 版: 后台守护线程新开 session 发推送, 不阻塞审核响应(对齐 best-effort)。
-
-    审核 approve 已同步调微信转账, 推送不该再把外部 API 耗时叠进响应(多设备/OPPO 慢时最坏
-    N×timeout)。线程内必须新开 SessionLocal —— 请求级 session 在响应返回后即关, 不能跨线程用。
-    起线程失败也只 log, 绝不连累审核。
-    """
-    def _run() -> None:
-        try:
-            with SessionLocal() as db:
-                notify_withdraw_approved(db, user_id=user_id)
-        except Exception:  # noqa: BLE001 - 后台线程绝不抛
-            logger.warning("[push] withdraw_approved async 异常 user_id=%s", user_id, exc_info=True)
-
-    try:
-        threading.Thread(target=_run, name=f"oppo-push-{user_id}", daemon=True).start()
-    except Exception:  # noqa: BLE001 - 起线程失败也绝不连累审核
-        logger.warning("[push] withdraw_approved async 起线程失败 user_id=%s", user_id, exc_info=True)

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-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）
+> 最后更新: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 入参/出参示例）
 > 架构:`app/api/v1/` 只放很轻的接口层;穿山甲/微信支付/极光/短信/美团等 SDK 集成的重逻辑在 `app/integrations/`,实现细节见 [docs/integrations/](../integrations/README.md)。
 
 ---
@@ -27,18 +27,17 @@
 | 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-session.md)（领券流水上报,admin 看板数据源） |
+| 8h | `POST /api/v1/coupon/session` | 无 | [详情](./coupon/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)（`rec` tab 离线库 + **按城市过滤** #116） |
+| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan/meituan-feed.md) |
 | 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan/meituan-referral-link.md) |
-| 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） |
+| 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） |
 | **比价记录**（前缀 `/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) |
@@ -55,7 +54,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`；绑定注册即生效但**不发奖**,#113 起好友「比价并下单」才给邀请人发**邀请奖励金**,经 `POST /order/report` 触发） |||
+| **好友邀请**（前缀 `/api/v1/invite`；注册即生效,双方各发 1 万金币） |||
 | 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） |
@@ -69,9 +68,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)（`source` 分账:coin_cash / invite_cash,#121） |
+| 22 | `POST /api/v1/wallet/withdraw` | Bearer | [详情](./wallet/wallet-withdraw.md) |
 | 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)（可按 `source` 过滤） |
+| 24 | `GET /api/v1/wallet/withdraw-orders` | Bearer | [详情](./wallet/wallet-withdraw-orders.md) |
 | 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)（关闭免确认到账,解除授权） |
@@ -100,7 +99,6 @@
 | 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) |
@@ -129,37 +127,43 @@
 | 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`=需对应角色;#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) |
+| **运营后台 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)(广告收益报表:按用户/日期/类型/应用/代码位 聚合 条数/收益/金币,只读) |
 | - | `GET /admin/api/health` | 无 | admin 健康检查(无单独文档) |
 
 > ⚠️ 美团三个接口当前**无鉴权**,且 `referral-link` 的 `sid` 允许客户端传值覆盖默认渠道——见各接口"备注"。
-> `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` 模块注释)。
+> `coupon/step` 及外卖比价的 `intent/recognize`、`intent/precoupon/step`、`intent/step`、`price/step`、`trace/finalize` 都透传到 pricebot-backend,**MVP 阶段均不鉴权**(device_id 透传,待补 JWT——见 `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

@@ -1,17 +0,0 @@
-# /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

@@ -1,28 +0,0 @@
-# /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

@@ -1,15 +0,0 @@
-# /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

@@ -1,15 +0,0 @@
-# /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](../savings/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](./platform-savings-feed.md);表见 [ops_marquee_seed](../database/ops_marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
 
 ## 复用结构 OpsMarqueeSeedOut
 | 字段 | 类型 | 说明 |
@@ -19,20 +19,9 @@
 出参 `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](../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 生效。
+- 出参 `200`:`{"items": [{masked_user, saved_amount_cents, time}]}`(条目同 [platform-savings-feed](./platform-savings-feed.md))
 
 ## 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

@@ -1,16 +0,0 @@
-# /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

@@ -1,19 +0,0 @@
-# /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,13 +8,12 @@
 |---|---|---|---|
 | `admin_id` | int | ✓ | 目标管理员 id |
 
-**application/json**(字段都可选,只改传了的;至少传一个):
+**application/json**(三字段都可选,只改传了的;至少传一个):
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
-| `role` | string | ✗ | 改角色:内建 `super_admin` / `finance` / `operator` **或自定义角色 name**(#117/#126,见 [admin-roles](../admin-roles.md)) |
-| `pages_override` | list[string] \| null | ✗ | 个人可见页覆盖(#126):非空优先于角色 pages;传 `null` 清覆盖回归角色 |
+| `role` | string | ✗ | 改角色,枚举:`super_admin` / `finance` / `operator` |
 | `status` | string | ✗ | 启停,枚举:`active`(启用)/ `disabled`(禁用) |
-| `password` | string | ✗ | 重置密码,8–72 字(传则覆盖原密码,同时更新 `plain_password` 明文副本) |
+| `password` | string | ✗ | 重置密码,8–72 字(传则覆盖原密码) |
 
 ## 出参
 响应 `200`:`AdminOut`（更新后的管理员)
@@ -25,15 +24,9 @@
 | `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 无效或过期 / 管理员被禁用
@@ -42,5 +35,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,24 +1,6 @@
-# /admin/api/feedbacks — 反馈审核族(采纳/拒绝/标记处理/统计)
+# POST /admin/api/feedbacks/{feedback_id}/handle — 标记反馈已处理
 
-> 所属: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 — 标记反馈已处理(旧口径)
+> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过,`require_role("operator")`） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 - 路径:`feedback_id`(int)
@@ -36,6 +18,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,7 +10,6 @@
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `mode` | string | ✗ | `delta`(默认)=增减 / `set`=设为指定值 |
-| `account` | string | ✗ | 目标账户(#95):`coin_cash`(默认,金币兑换的现金)/ `invite_cash`(邀请奖励金)。两本账物理隔离、各调各 |
 | `amount_cents` | int | ✓ | `delta` 模式:现金变动(分,正=发放,负=扣减,不可为 0);`set` 模式:目标现金值(分,须 ≥ 0) |
 | `reason` | string | ✓ | 操作原因,1–128 字(必填,入审计与流水备注) |
 
@@ -29,7 +28,7 @@
 - 金额单位一律为**分**(`*_cents`);本接口只动现金余额,不涉及金币。
 - **set 模式**:读当前余额算出差值 `delta = target - 当前余额`,再复用同一套写入逻辑(故只写一笔差值流水)。目标值须 ≥ 0;差值为 0(已等于目标)直接拒绝。
 - 扣减保护:实际写入的 `delta < 0` 时若扣减后现金余额 < 0 直接拒绝(运营误操作保护);set 模式目标值 ≥ 0 天然不会扣成负。
-- 现金变动按 `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。
+- 现金变动写流水 [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。
 - 现金变动 + 审计在同一事务原子提交(改钱必留痕)。
-- 关联用户表 [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,15 +38,6 @@
 - `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)。
-
----
-
-## 族内配套端点(提现详情页联查用)
-
-| 方法 + 路径 | 说明 |
-|---|---|
-| `GET /admin/api/users/{user_id}/reward-stats` | 用户提现/看广告统计(按时间窗口):提现审核时评估该用户金币来源是否健康 |
-| `GET /admin/api/users/{user_id}/coin-records` | 用户金币发放记录(按时间窗口分页):提现详情底部表,逐笔看发币来源 |
+- 关联用户表 [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)。

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

@@ -21,11 +21,5 @@
 
 ## 说明
 - 业务写(改用户状态)与审计写在同一事务原子提交:改了就有痕、有痕就真改了。
-- 写操作记审计 [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)。
+- 写操作记审计 [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)。

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

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

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

@@ -1,26 +1,22 @@
-# POST /api/v1/price/step — 外卖比价 Phase 2 步进（透传 + done 帧 harvest 落库）
+# POST /api/v1/price/step — 外卖比价 Phase 2 步进（透传到 pricebot）
 
-> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**软鉴权 OptionalUser**（带 JWT 则绑 `user_id`,不带也放行） | [← 返回 API 索引](../README.md)
+> 所属:Compare 组（前缀 `/api/v1`,外卖比价） | 鉴权:**无（MVP 阶段不鉴权）** | [← 返回 API 索引](../README.md)
 
 ## 入参
-任意 JSON body,**不做 schema 校验**,原样透传给上游。后端从中读 `device_id`、`trace_id`、`step`、`device_info` 用于日志与落库。
+任意 JSON body,**不做 schema 校验**,原样透传给上游。后端仅从中读 `device_id`、`trace_id`、`step` 用于日志。
 客户端逐帧上报 `screen_state` + 上一步 `action_result`;`step=0` 还带 `query` + `calibration`（来自 Phase 1）。
 
 ## 出参
-pricebot-backend 的响应**原样返回**（JSON object）,并在顶层补 `trace_id`（见下「trace_id 签发」）。含 `action`（tap / set_text / launch / wait / done…）、`continue`、`status`、每帧顶层 `trace_url`;最终 `done` 帧带 `comparison_results`（源 + 各目标平台到手价,按价升序）。
+pricebot-backend 的响应**原样返回**（JSON object）。含 `action`（tap / set_text / launch / wait / done…）、`continue`、`status`;最终 `done` 帧带 `comparison_results`（源 + 各目标平台到手价,按价升序）。
 
 ## 错误码
 - `400` body 不是合法 JSON
 - `502` pricebot 上游不可达（网络错误）或返回 5xx
 
 ## 说明
-把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/price/step`（去掉 `/v1`,共享 httpx 单例）。**多轮循环**:客户端按返回的 `action` 操作手机、再上报下一帧,直到 `continue=false`。真正的目标驱动比价逻辑（多目标平台串行复现订单、读到手价、聚合排序）在 **pricebot-backend**。
+把请求体原样转发到 `PRICEBOT_BASE_URL` 的 `/api/price/step`（去掉 `/v1`,async httpx）。**多轮循环**:客户端按返回的 `action` 操作手机、再上报下一帧,直到 `continue=false`。真正的目标驱动比价逻辑（多目标平台串行复现订单、读到手价、聚合排序）在 **pricebot-backend**,本接口只是"透传壳"。
 
-**不再是纯透传壳(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`。
+⚠️ **MVP 阶段不鉴权**（同 `coupon/step`）。
 
 **相关配置**:
 - `PRICEBOT_BASE_URL`（默认 `http://localhost:8000`;生产部署应与 pricebot-backend 同内网——比价一单 30~80 步、逐帧多一跳,走公网延迟会累积）

docs/api/internal/internal.md

@@ -14,13 +14,12 @@
 
 | 方法 + 路径 | 落库 | 说明 |
 |---|---|---|
-| `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}` |
-| `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`)入口 |
+| `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`)入口 |
 
 ## 错误
 - `401` 密钥不匹配 / 缺失。

docs/api/invite/invite-bind.md

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

docs/api/invite/invite-invitees.md

@@ -25,8 +25,7 @@ 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 | 这次邀请给邀请人发的金币（**历史留痕**：#113 前旧口径的发放额；新绑定恒 0） |
-| `items[].is_compared` | bool | 该好友是否已完成过一次比价（#113：好友列表据此分「邀请成功 / 去提醒」，在途列表只取 `false` 的） |
+| `items[].coins` | int | 这次邀请给邀请人发的金币 |
 | `items[].invited_at` | datetime | 邀请绑定时间（ISO 8601 UTC） |
 | `total` | int | 我邀请的总人数 |
 | `has_more` | bool | 还有下一页吗 |
@@ -38,15 +37,13 @@ Mock 出参:
     {
       "display_name": "省钱小王",
       "avatar_url": "/media/avatars/u2_f1e2d3c4b5a60708.jpg",
-      "coins": 0,
-      "is_compared": true,
+      "coins": 10000,
       "invited_at": "2026-06-28T14:30:00Z"
     },
     {
       "display_name": "138****1234",
       "avatar_url": null,
-      "coins": 0,
-      "is_compared": false,
+      "coins": 10000,
       "invited_at": "2026-07-01T09:15:00Z"
     }
   ],

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

@@ -2,21 +2,20 @@
 
 > 所属:美团 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 只到店 / 不填=全部 |
-| `longitude` / `latitude` | float \| null | ❌(实际必带) | null | 设备坐标(#116):服务端离线反查城市(`utils/geo` + `meituan_city`)→ **只返回同城券**;老客户端不带坐标 → 返空 + `status=degraded`(不 422、不误返全城) |
+| `platform` | int \| null | ❌ | null | 1 只外卖 / 2 只到店 / 不填=全部(全城销量) |
 
 ## 出参
-响应 `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` 非空 **且 `city_id` = 反查城市** 的券(#116,同城销量榜),`DISTINCT ON(dedup_key)` 跨源去重(每个「品牌|名|价」只留销量最高一条,同销量再按佣金),按销量降序分页;每页只对当前 ~20 条做 `from_raw` 解析(翻页快,不全表拉取)。
+- 从 `meituan_coupon` 取 `sale_volume_num` 非空的券,`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,13 +1,9 @@
-# POST /api/v1/trace/finalize + /trace/epilogue — 比价 trace 收尾族
+# POST /api/v1/trace/finalize — 比价 trace 收尾上云
 
-> 所属:透传端点（前缀 `/api/v1`，外卖比价） | 鉴权:软鉴权 OptionalUser | [← 返回 API 索引](../README.md)
-
-## POST /api/v1/trace/finalize — 收尾上云(+夭折落库)
+> 所属:透传端点（前缀 `/api/v1`，外卖比价） | 鉴权:无（MVP 阶段不鉴权） | [← 返回 API 索引](../README.md)
 
 透传到 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 协议组装。关键字段：
@@ -45,15 +41,5 @@ Mock 出参:
 
 ## 说明
 - 一致性 hash 按 `trace_id` 路由到同一 pricebot 实例（确保 dir_cache 命中）
-- 软鉴权（OptionalUser,同比价透传族）
+- MVP 阶段不鉴权
 - 与 `/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,24 +61,7 @@ Mock 入参:
 
 ---
 
-## POST /api/v1/user/onboarding/reset — 重置新手引导(#114)
-
-删除（当前账号, `device_id`）的完成标记 → 该设备下次登录/进 App 重走引导。给客户端「设置 → 重看新手引导」入口用（此前只能运营在 admin 删记录）。
-
-### 入参
-| 字段 | 类型 | 必填 | 说明 |
-|---|---|---|---|
-| `device_id` | string | ✅ | 硬件级 ANDROID_ID（与 complete 一致） |
-
-### 出参
-```json
-{"ok": true}
-```
-幂等：无标记时也返回 ok。
-
----
-
 ## 说明
-- 替代原 `force_onboarding`（按用户）→ 改设备维度后，运营删记录（或用户自己 reset）即触发重走
-- 幂等：重复标记 / 重复重置都不报错
+- 替代原 `force_onboarding`（按用户）→ 改设备维度后，运营删记录即触发重走
+- 幂等：重复标记不报错
 - `device_id` 为空时 `status` 一律返回未完成

docs/api/wallet/wallet-account.md

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

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

@@ -8,10 +8,9 @@
 |---|---|---|---|---|
 | `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**
 
@@ -20,7 +19,7 @@
 | `id` | int | 单 id（也是游标） |
 | `out_bill_no` | string | 商户提现单号 |
 | `amount_cents` | int | 提现额（分） |
-| `status` | string | `reviewing`(待审核)/ `pending` / `success` / `failed` / `rejected` |
+| `status` | string | `pending` / `success` / `failed` |
 | `wechat_state` | string \| null | 微信侧原始状态 |
 | `fail_reason` | string \| null | 失败原因 |
 | `created_at` | datetime | 发起时间 |

docs/api/wallet/wallet-withdraw.md

@@ -2,14 +2,13 @@
 
 > 所属:Wallet 组（前缀 `/api/v1/wallet`） | 鉴权:Bearer | 限流:同 IP ≤20 次/分 | [← 返回 API 索引](../README.md)
 >
-> 集成实现:见 [integrations/wxpay](../../integrations/wxpay.md)（微信 V3 商家转账、签名、实名加密）。
+> 集成实现:见 [integrations/wxpay](../integrations/wxpay.md)（微信 V3 商家转账、签名、实名加密）。
 
 ## 入参
 
 | 字段 | 类型 | 必填 | 说明 |
 |---|---|---|---|
 | `amount_cents` | int | ✅（>0） | 提现金额（分）,须落在 `[min_cents, max_cents]` |
-| `source` | string | ❌（默认 `coin_cash`） | 提现账户来源(#121 分账):`coin_cash`(金币兑换的现金)/ `invite_cash`(邀请奖励金)。按它扣对应余额、流水落对应账本([cash_transaction](../../database/cash_transaction.md) / [invite_cash_transaction](../../database/invite_cash_transaction.md)) |
 | `user_name` | string | ❌ | 实名（达额时微信商家转账要求,可空） |
 | `out_bill_no` | string | ❌ | **客户端幂等键（商户单号）**:同号重试不重复转账;不传则服务端生成 |
 

docs/database/OVERVIEW.md

@@ -2,7 +2,7 @@
 
 > 跨表视角。单表字段级细节看同目录 `<表名>.md`(索引见 [README](./README.md))。
 > 本文专门回答三件「跨表」的事:**① 每块 App 功能用到哪些表 ② 什么操作往哪张表写 ③ 表和表怎么连(join key,含没有外键约束、靠业务字段对齐的语义关联)**。
-> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **45 张业务表** + `alembic_version`(框架的迁移版本指针)。注意「比价/领券**过程**」始终在 pricebot 内存态跑、**不落库**——只有**结果**回 app-server 才落库:领券结果落 `coupon_*` 三张今日状态表 + `coupon_session` 任务流水(#99);比价记录 2026-07 起**由 app-server 透传壳 harvest 直接落库**(`comparison_record`:帧0 建 running 行 → done/finalize 写终态,老客户端带 JWT 的 `POST /compare/record` 仅作兜底),pricebot 另经 `app/api/internal/` server→server 把客观价格/门店事实落 `price_observation`/`store_mapping`(不鉴权、匿名也记)+ 启动确认窗兜底样本落 `launch_confirm_sample`。此外好友邀请(`invite_*` 2 张 + 独立账本 `invite_cash_transaction`)与 CPS 群发联盟(`cps_*` 6 张,含落地页微信身份 `cps_wx_user`;`cps_order` 已含京东联盟单)是两个独立子系统。无障碍存活监控 `device_liveness`(#65)按用户设备维度记心跳、检掉线召回;客户端埋点落 `analytics_event`(#83)。
+> **范围**:业务表全部在 `shaguabijia-app-server`(SQLAlchemy 2.0 + SQLite 开发 / PostgreSQL 生产)。`pricebot-backend`(比价/领券 Agent)是纯内存态、**无任何表**;Android 客户端只有 EncryptedSharedPreferences / SharedPreferences、**无关系库**。共 **40 张业务表** + `alembic_version`(框架的迁移版本指针)。注意「比价/领券**过程**」始终在 pricebot 内存态跑、**不落库**——只有**结果**回 app-server 才落库:领券结果落 `coupon_*` 三张今日状态表;比价结果分两路——客户端带 JWT 上报「我的记录」落 `comparison_record`,pricebot 另经 `app/api/internal/` server→server 把客观价格/门店事实落 `price_observation`/`store_mapping`(不鉴权、匿名也记)+ 启动确认窗兜底样本落 `launch_confirm_sample`。此外好友邀请(`invite_*` 2 张)与美团 CPS 群发联盟(`cps_*` 6 张,含落地页微信身份 `cps_wx_user`)是两个独立子系统。无障碍存活监控 `device_liveness`(#65)按用户设备维度记心跳、检掉线召回。
 
 ---
 
@@ -12,7 +12,7 @@
 | App 位置 / 动作 | 表 | 说明 |
 |---|---|---|
 | 比价/领券**过程**(看屏→决策→操作) | （无） | 在 pricebot-backend 内存态跑,**过程不落库**;只有结果回到 app-server 才落库 |
-| 「我的比价记录」列表 / 详情 | [`comparison_record`](./comparison_record.md) | **app-server 透传壳 harvest 落库**(2026-07 起):帧0 建 `running` 行 → done 帧写 success/failed → `trace/finalize` 写 cancelled/failed;老客户端带 JWT 的 `POST /compare/record` 兜底 |
+| 「我的比价记录」列表 / 详情 | [`comparison_record`](./comparison_record.md) | 每次比价 done 后客户端带 JWT 上报一条完整明细 |
 | 比价战绩里程碑(逐档领金币) | [`comparison_milestone_claim`](./comparison_milestone_claim.md) | 累计成功比价 N 次解锁;进度读 `comparison_record` 计数 |
 | profile「累计省了 / 省钱战绩 / 省钱明细」 | [`savings_record`](./savings_record.md) | 真实下单归因(source=compare)+ 无真实数据时 demo 兜底 |
 | 「上报更低价」提交 / 列表 | [`price_report`](./price_report.md) | 众包纠偏:用户举证某平台更便宜,人工审核发奖 |
@@ -27,7 +27,6 @@
 | 切外卖 App 时是否弹领券引导窗 | [`coupon_prompt_engagement`](./coupon_state.md) | 今天 engage 过(点领/点拒)就不再弹;判断维度 device_id |
 | 首页「去领取」卡是否置灰 | [`coupon_daily_completion`](./coupon_state.md) | 今天跑完整轮(到 done)就置灰;判断维度 device_id |
 | 每张券领取结果留痕 | [`coupon_claim_record`](./coupon_state.md) | 资产/画像/排查/CPS;当前**不参与**判断 |
-| (admin 领券看板)一次领券任务全程流水 | [`coupon_session`](./coupon_session.md) | 客户端 `POST /coupon/session` 两段上报(发起建行/收尾更新);发起数、完成率、中途流失、平均耗时都从这算(#99) |
 
 ### 钱包 / 福利(看广告赚钱闭环)
 | App 位置 / 动作 | 表 | 说明 |
@@ -38,9 +37,7 @@
 | 每日签到 | [`signin_record`](./signin_record.md) + [`signin_boost_record`](./signin_boost_record.md) | 7 天循环发币;签到后看广告可膨胀一次 |
 | 一次性任务(开消息提醒等) | [`user_task`](./user_task.md) | 领一次发币 |
 | 看激励视频赚金币 | [`ad_reward_record`](./ad_reward_record.md) + [`ad_watch_log`](./ad_watch_log.md) + [`ad_ecpm_record`](./ad_ecpm_record.md) | 独立数据流:发奖 / 旧版观看时长 / 收益对账 |
-| 信息流/Draw 广告结算 | [`ad_feed_reward_record`](./ad_feed_reward_record.md) | 每展示满 10 秒累计一份奖励,完成后一次性入账;`ad_type`(feed/draw)+`feed_scene`(compare/coupon)分形态/场景 |
-| (无 App UI)穿山甲后台收益对账 | [`ad_pangle_daily_revenue`](./ad_pangle_daily_revenue.md) | 定时脚本拉 GroMore 数据 API 落日表(#92);admin 收益报表/大盘的「真实收益」侧 |
-| 好友比价并下单发奖 / 邀请奖励金 | [`invite_cash_transaction`](./invite_cash_transaction.md) + `coin_account.invite_cash_balance_cents` | 与现金**物理隔离**的第二本账(#82/#113):`POST /order/report` 触发 `invite_reward` 入账;`source=invite_cash` 提现出账 |
+| 信息流广告结算 | [`ad_feed_reward_record`](./ad_feed_reward_record.md) | 每展示满 10 秒累计一份奖励,完成后一次性入账 |
 | 金币兑现金 | `coin_account` + `coin_transaction` + `cash_transaction` | exchange_out + exchange_in 两笔流水 |
 | 提现到微信零钱 | [`withdraw_order`](./withdraw_order.md) + [`wechat_transfer_authorization`](./wechat_transfer_authorization.md) + `cash_transaction` | 人工审核 + 微信商家转账 |
 | 绑定微信(提现前置) | `user`.wechat_* | openid 唯一,一微信一账号 |
@@ -56,9 +53,8 @@
 ### 好友邀请(注册增长)
 | App 位置 / 动作 | 表 | 说明 |
 |---|---|---|
-| 输入/剪贴板邀请码绑定 | [`invite_relation`](./invite_relation.md) | 注册即生效(**绑定不发奖**,#113);`invitee_user_id` 唯一;`compare_reward_granted` 幂等闸=好友**比价并下单**后才给邀请人发奖励金 |
+| 输入/剪贴板邀请码绑定 | [`invite_relation`](./invite_relation.md) | 注册即生效,邀请人+被邀请人各发 1 万金币;`invitee_user_id` 唯一=幂等防重复发奖 |
 | 落地页访问指纹(剪贴板归因兜底) | [`invite_fingerprint`](./invite_fingerprint.md) | 剪贴板没拿到码时,用 (ip+机型+屏幕) 7 天内反查邀请人 |
-| 邀请奖励金入账/提现 | [`invite_cash_transaction`](./invite_cash_transaction.md) | 独立账本(见上钱包节);余额在 `coin_account.invite_cash_balance_cents` |
 
 ### 美团 CPS 群发联盟(私域社群比价,运营后台驱动 · 群发选品→点击→对账漏斗)
 | 后台/用户动作 | 表 | 说明 |
@@ -70,19 +66,10 @@
 | 微信内打开落地页授权 | [`cps_wx_user`](./cps_wx_user.md) | 服务号网页授权拿 openid(base 静默)/ 昵称头像 unionid(userinfo,点领券触发),记首次来源群 |
 | 定时拉美团联盟订单对账 | [`cps_order`](./cps_order.md) | `query_order` 按 sid 归群,串成点击→下单→佣金漏斗 |
 
-### 埋点 / 首页门面 / 选品缓存
-| 位置 / 动作 | 表 | 说明 |
-|---|---|---|
-| 客户端行为埋点 | [`analytics_event`](./analytics_event.md) | `POST /analytics/events` 批量上报,一事件一行(#83);admin「埋点日志」检索 |
-| 首页三统计数字 | [`ops_stat_config`](./ops_stat_config.md) | real/manual/random 三模式,admin 配 |
-| 首页轮播(省钱动态) | [`ops_marquee_seed`](./ops_marquee_seed.md) | 种子条目,与真实 `comparison_record` 混播(数据源模式 mixed/real/seed 可切) |
-| 首页推荐/销量榜离线选品 | [`meituan_coupon`](./meituan_coupon.md) | 美团 CPS 券缓存,定时 ETL 灌入;`feed?tab=rec` 与 `top-sales` 纯库出、不实时打美团 |
-
 ### 运营后台 admin(独立子应用 `app/admin/`,端口 8771,独立鉴权)
 | 后台模块 | 表 | 说明 |
 |---|---|---|
-| 管理员账号 / 登录 | [`admin_user`](./admin_user.md) | 与 C 端 `user` 完全隔离,独立 JWT + RBAC;`pages_override` 个人可见页覆盖 |
-| 角色 / 可见页配置 | [`admin_role`](./admin_role.md) | 内建三角色 + 自定义角色(#117/#126);`admin_user.role` 按名引用 |
+| 管理员账号 / 登录 | [`admin_user`](./admin_user.md) | 与 C 端 `user` 完全隔离,独立 JWT + RBAC |
 | 操作审计 | [`admin_audit_log`](./admin_audit_log.md) | 每个写操作落一条,只增不改不删 |
 | 运营可配置项(改奖励常量) | [`app_config`](./app_config.md) | 空表 = 用代码默认;后台改了即覆盖 |
 | 用户/钱包/提现/反馈管理 | 跨读写上面的 C 端表 | 见下「写入路径」admin 段 |
@@ -105,8 +92,8 @@
 | 签到膨胀 `POST /signin/boost` | `signin_boost_record`(C) + `coin_account`(U) + `coin_transaction`(C `signin_boost`) | 同事务;同日一次 |
 | 领任务 `POST /tasks/claim` | `user_task`(C) + `coin_account`(U) + `coin_transaction`(C `task_<key>`) | 同事务 |
 | 金币兑现金 `POST /wallet/exchange` | `coin_account`(U) + `coin_transaction`(C `exchange_out` −) + `cash_transaction`(C `exchange_in` +) | 同事务 |
-| 发起提现 `POST /wallet/withdraw` | `withdraw_order`(C `reviewing`,记 `source`) + `coin_account`(U 按 source 扣对应余额) + 流水(C −:`cash_transaction.withdraw` 或 `invite_cash_transaction.invite_withdraw`) | 同事务,**不打款**;#121 按 `source` 分账 |
-| 查提现状态 / 用户取消 `GET /wallet/withdraw/status` | `withdraw_order`(U) + 失败→对应账本退款流水(C `withdraw_refund` / `invite_withdraw_refund` +) | |
+| 发起提现 `POST /wallet/withdraw` | `withdraw_order`(C `reviewing`) + `coin_account`(U 扣现金) + `cash_transaction`(C `withdraw` −) | 同事务,**不打款** |
+| 查提现状态 / 用户取消 `GET /wallet/withdraw/status` | `withdraw_order`(U) + 失败→`cash_transaction`(C `withdraw_refund` +) | |
 | 穿山甲发奖 S2S 回调 `POST /ad/pangle-callback` | `ad_reward_record`(C)+ granted→`coin_account`(U)+`coin_transaction`(C `reward_video`/`signin_boost`) | `trans_id` 幂等 |
 | 看广告时长上报 `POST /ad/watch-report` | `ad_watch_log`(C) | |
 | 广告 eCPM 上报 `POST /ad/ecpm-report` | `ad_ecpm_record`(C) | |
@@ -114,17 +101,13 @@
 | 注册设备 / 更新 push token `POST /device/register` | `device_liveness`(C/U upsert) | `(user_id, device_id)` 幂等;只在传入非空时更新 `registration_id`/版本 |
 | 无障碍服务心跳 `POST /device/heartbeat` | `device_liveness`(C/U) | 心跳也能自注册;`accessibility_enabled=true` 时刷 `last_heartbeat_at`、置 `alive`、清 `notified_at` |
 | 客户端 ack 掉线提醒 `POST /device/liveness/ack` | `device_liveness`(U) | 清 `kill_alert_pending`(幂等;下次真掉线 worker 再置) |
-| 比价透传(帧0 / done / finalize)`POST /intent/recognize`、`/price/step`、`/trace/finalize` | `comparison_record`(C `running` → U 终态) | **harvest 三段式**(2026-07):帧0 mint trace_id 建 running 行 → done 写 success/failed → finalize 写 cancelled/failed(不降级 success);best-effort,写失败不连累透传 |
-| 比价 done 上报 `POST /compare/record`(老客户端兜底) | `comparison_record`(C 或 U) | `trace_id` 幂等覆盖(唯一键已从 `(user_id,trace_id)` 改单列) |
+| 比价 done 上报 `POST /compare/record` | `comparison_record`(C 或 U) | `(user_id, trace_id)` 幂等覆盖 |
 | 领里程碑 `POST /compare/milestone/claim` | `comparison_milestone_claim`(C) | **当前不发币**(coin_awarded=0) |
-| 支付归因上报 `POST /order/report` | `savings_record`(C `source=compare`)+ 触发邀请发奖:`invite_relation`(U `compare_reward_granted`)+`coin_account`(U invite_cash)+`invite_cash_transaction`(C `invite_reward`) | `(user_id, client_event_id)` 幂等;#113 邀请发奖口径=好友**比价并下单**,`compare_reward_granted` 幂等闸,同事务 |
-| 批量埋点 `POST /analytics/events` | `analytics_event`(C 批量) | 不强制登录;每批 ≤200 条 |
-| 领券任务流水 `POST /coupon/session` | `coupon_session`(C/U upsert) | `trace_id` 幂等:发起建行、收尾更新同一行(#99) |
-| 重置新手引导 `POST /user/onboarding/reset` | `onboarding_completion`(**D** 该 设备+账号 行) | #114,删完成标记 → 下次登录重走引导 |
+| 支付归因上报 `POST /order/report` | `savings_record`(C `source=compare`) | `(user_id, client_event_id)` 幂等 |
 | 首次进 profile 省钱页且无真实记录 | `savings_record`(C `source=demo`) | 懒种子,`ensure_seeded` 按 user 幂等 |
 | 上报更低价 `POST /report` | `price_report`(C) | 读 `comparison_record.best_price_cents` 校验 |
 | 提交反馈 `POST /feedback` | `feedback`(C) | |
-| 绑定邀请 `POST /invite/bind` | `invite_relation`(C `effective`) | `invitee_user_id` 唯一幂等。**#113 起绑定不发奖**——发奖延后到好友比价并下单(`POST /order/report` 行),发的是邀请奖励金非金币 |
+| 绑定邀请 `POST /invite/bind` | `invite_relation`(C `effective`) + `coin_account`(U×2) + `coin_transaction`(C `invite_inviter` + `invite_invitee`) | 同事务;`invitee_user_id` 唯一幂等,双方各发 1 万金币 |
 | 落地页归因 `POST /invite/landing-track` | `invite_fingerprint`(C) | 剪贴板归因兜底线索,登录后用 (ip+机型+屏幕) 反查 |
 | 领券首帧 `POST /api/v1/coupon/step`(step=0) | `coupon_prompt_engagement`(C/U `claim_started`) | `(device_id, package, 北京日)` 幂等;best-effort |
 | 领券每帧结果 `POST /api/v1/coupon/step` | `coupon_claim_record`(C/U) | `(device_id, coupon_id, 北京日)` 幂等;best-effort |
@@ -138,17 +121,11 @@
 | 后台操作 | 写入 | 操作 |
 |---|---|---|
 | 手动增减金币 | `coin_account`(U)+`coin_transaction`(C `admin_grant`/`admin_deduct`)+`admin_audit_log`(C) | 同事务 |
-| 手动增减现金(#95 支持目标账户) | `coin_account`(U 按 `account` 选列)+ 流水(C:`cash_transaction` 或 `invite_cash_transaction`,`admin_grant`/`admin_deduct`)+`admin_audit_log`(C) | 同事务;`account=coin_cash`/`invite_cash` 两本账各调各 |
-| 改用户状态(禁用/启用)/ 调试链接权限 | `user`(U `status` / `debug_trace_enabled`)+`admin_audit_log`(C) | 同事务 |
-| 审核通过提现(含批量) | `withdraw_order`(U→pending/success/failed)+`wechat_transfer_authorization`(C/U)+失败时按 source 退款流水+`admin_audit_log`(C) | |
-| 审核拒绝提现(含批量) | `withdraw_order`(U→rejected)+按 source 退款流水(C `withdraw_refund`/`invite_withdraw_refund`)+`admin_audit_log`(C) | |
-| 反馈采纳/拒绝/标记处理 | `feedback`(U→adopted/rejected/handled + `admin_reply`/`reject_reason`)+采纳发币时 `coin_account`(U)+`coin_transaction`(C)+`admin_audit_log`(C) | 同事务(#94/#105) |
-| 上报更低价审核 | `price_report`(U→approved/rejected)+通过发币 `coin_account`(U)+`coin_transaction`(C)+`admin_audit_log`(C) | 同事务 |
-| 改运营配置 / 广告配置 / 反馈页二维码 | `app_config`(C/U)+`admin_audit_log`(C) | 同事务 |
-| 轮播种子/数据源模式 | `ops_marquee_seed`(C/U/D)+`app_config`(模式 mixed/real/seed)+`admin_audit_log`(C) | #122/#123 预览/浏览只读 |
-| 角色管理(#117/#126) | `admin_role`(C/U/D)+`admin_audit_log`(C) | 内建/在用角色不可删 |
-| 管理员管理 | `admin_user`(C/U/**D** #126)+`admin_audit_log`(C) | 删除为物理删,不可删自己 |
-| CPS 建群/活动/生成短链/拉单对账 | `cps_group`/`cps_activity`(C/U/D)、`cps_link`(C)、`cps_order`(C/U upsert;美团 `query_order` + 京东联盟 #90) | 见 CPS 段 |
+| 改用户状态(禁用/启用) | `user`(U)+`admin_audit_log`(C) | 同事务 |
+| 审核通过提现 | `withdraw_order`(U→pending/success/failed)+`wechat_transfer_authorization`(C/U)+失败时`cash_transaction`(refund)+`admin_audit_log`(C) | |
+| 审核拒绝提现 | `withdraw_order`(U→rejected)+`cash_transaction`(C `withdraw_refund`)+`admin_audit_log`(C) | |
+| 处理反馈 | `feedback`(U)+`admin_audit_log`(C) | 同事务 |
+| 改运营配置 | `app_config`(C/U)+`admin_audit_log`(C) | 同事务 |
 | 任意写操作 | `admin_audit_log`(C,**永不 U/D**) | |
 
 > 没有任何表会被业务流程物理 DELETE。注销是软删(改 user 行),其余只 C/U(领券 `/prompt/reset`、`/completed-today/reset` 是开发用删除,非业务流程)。
@@ -160,9 +137,7 @@
 | 后台批量生成短链 `POST /admin/api/cps/referral-links` | `cps_link`(C) | 每 群×活动 一条;美团经 `sid` 转链拿 `target_url`(同群同活动重复生成产生多条) |
 | 用户点群发短链 `GET /c/{code}` / `POST /c/{code}/copy` | `cps_click`(C `visit`/`copy`) | 公开端点不鉴权;`group_id`/`sid` 从 link 冗余进来免 join |
 | 微信落地页授权回调 `GET /wx/oauth/cb` | `cps_wx_user`(C/U upsert) | 按 `openid` 幂等;base 拿 openid,userinfo 补昵称/unionid(非 None 才覆盖);任何失败兜底回落地页不阻断领券 |
-| 定时拉联盟订单对账(美团 `query_order` + 京东联盟 #90) | `cps_order`(C/U upsert) | 按 `sid` 归群;`order_id` 幂等(状态会变,重复拉则更新);京东单 `platform='jd'` + `jd_valid_code` 判有效 |
-| 定时拉穿山甲 GroMore 后台收益(#92,systemd 每天 10:30) | `ad_pangle_daily_revenue`(C/U upsert) | 收益报表/大盘「真实收益」侧;与客户端上报的 eCPM 侧互为对照 |
-| 定时 ETL 灌美团 CPS 选品库 | `meituan_coupon`(C/U) | `feed?tab=rec` / `top-sales` 纯库出的数据源 |
+| 定时拉美团联盟订单对账 | `cps_order`(C/U upsert) | `query_order` 按 `sid` 归群;`order_id` 幂等(状态会变,重复拉则更新) |
 | pricebot 比价 done 内部上报 `POST /internal/price-observation` | `price_observation`(C 批量) | `(trace_id,platform,scope)` 幂等;**不走 JWT、靠 `X-Internal-Secret`**(未配→503) |
 | pricebot 比价 done 内部上报 `POST /internal/store-mapping` | `store_mapping`(C/U 填空合并) | `trace_id` 幂等;另有 `lookup` 反查 + `invalidate` deeplink 失效标记(淘宝/京东) |
 | pricebot LLM 兜底放行启动确认窗后上报 `POST /internal/launch-confirm-sample` | `launch_confirm_sample`(C) | **都上报、不去重**;靠 `X-Internal-Secret`(未配→503) |
@@ -175,7 +150,7 @@
 ## 三、表间关系 & Join Key
 
 ### 硬外键(数据库 FK 约束)
-- **19 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`invite_cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`signin_record`、`signin_boost_record`、`user_task`、`comparison_record`(2026-07 起 `user_id` **可空**——harvest 帧0 建行时软鉴权可能拿不到)、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback`、`device_liveness`。
+- **18 张用户维度表 `.user_id` → `user.id`**:`coin_account`(同时是 PK)、`coin_transaction`、`cash_transaction`、`withdraw_order`、`wechat_transfer_authorization`(同时是 PK)、`signin_record`、`signin_boost_record`、`user_task`、`comparison_record`、`comparison_milestone_claim`、`savings_record`、`ad_reward_record`、`ad_watch_log`、`ad_ecpm_record`、`ad_feed_reward_record`、`price_report`、`feedback`、`device_liveness`。
 - `admin_audit_log.admin_id` → `admin_user.id`。
 - `price_report.comparison_record_id` → `comparison_record.id`(可空:关联记录被删后仍留上报历史)。
 - **邀请两表** → `user.id`:`invite_relation.inviter_user_id`、`invite_relation.invitee_user_id`(唯一)、`invite_fingerprint.inviter_user_id`——注意 FK 列名是 `inviter`/`invitee_user_id`,不是 `user_id`。
@@ -198,24 +173,13 @@
 
   | biz_type | ref_id 指向 | amount 符号 |
   |---|---|---|
-  | `withdraw` / `withdraw_refund` | `withdraw_order.out_bill_no`(`source=coin_cash` 的单) | − / + |
+  | `withdraw` / `withdraw_refund` | `withdraw_order.out_bill_no` | − / + |
   | `exchange_in` | null | + |
-  | `admin_grant` / `admin_deduct` | null(原因在 `remark`=`admin:<reason>`) | + / − |
-
-- **`invite_cash_transaction.ref_id`**(邀请奖励金账本,#82):
-
-  | biz_type | ref_id 指向 | amount 符号 |
-  |---|---|---|
-  | `invite_reward` | 被邀请人 `user.id`(字符串) | + |
-  | `invite_withdraw` / `invite_withdraw_refund` | `withdraw_order.out_bill_no`(`source=invite_cash` 的单) | − / + |
-  | `admin_grant` / `admin_deduct` | null | + / − |
 
 - **`comparison_record.store_name` ≈ `savings_record.shop_name`**:无 id 关联,按**店名字符串相等**给比价记录打「已下单」标记(瞬态,不写库)。两边店名同源 = 比价意图识别阶段的门店 query,语义=**店级**(同店比价多次会一并标已下单)。
 - **广告流会话关联**:`ad_reward_record.ad_session_id` 可与 `ad_ecpm_record.ad_session_id` 对齐;`ad_watch_log` 仍是旧版兼容统计,不逐条参与发奖。
 - **里程碑解锁进度不存库**:`comparison_milestone_claim` 只记「哪几档已领」;进度 = `comparison_record` 里 `status='success'` 的 `count`。
-- **领券三表无硬 FK,全靠软关联**:`coupon_prompt_engagement` / `coupon_daily_completion` / `coupon_claim_record` 的 `user_id` **软指** `user.id`(可空、有登录态才记、不进唯一键、不阻塞判断);`trace_id` **软指** pricebot work_logs(排查回指);唯一键都以 `device_id` + 北京自然日为主(详见 [`coupon_state.md`](./coupon_state.md))。[`coupon_session`](./coupon_session.md)(#99)同口径:`trace_id` 唯一 upsert、`user_id` 软指(admin 明细 LEFT JOIN 出手机号)。
-- **`analytics_event`**(#83)与 **`coupon_session`** 均无硬 FK:埋点/流水不鉴权也收,`device_id`/`user_id` 只作维度。
-- **`admin_user.role` 按名语义引用 `admin_role.name`**(无硬 FK,#117):删除保护在应用层(在用/内建角色不可删);个人 `pages_override` 优先于角色 `pages`。
+- **领券三表无硬 FK,全靠软关联**:`coupon_prompt_engagement` / `coupon_daily_completion` / `coupon_claim_record` 的 `user_id` **软指** `user.id`(可空、有登录态才记、不进唯一键、不阻塞判断);`trace_id` **软指** pricebot work_logs(排查回指);唯一键都以 `device_id` + 北京自然日为主(详见 [`coupon_state.md`](./coupon_state.md))。
 - **`onboarding_completion.(user_id, device_id)`**:`user_id` 语义关联 `user.id`(无硬 FK,同 `coupon_*` 设备表),`device_id` = 客户端硬件级 `ANDROID_ID`(≠ 领券 per-install `device_id`)。登录读、走完引导写,决定是否再展示新手引导。
 - **CPS 群发 6 表全靠 `sid` / id / `openid` 语义串联(无硬 FK)**:`cps_link.group_id`→`cps_group.id`、`cps_link.activity_id`→`cps_activity.id`、`cps_click.link_id`→`cps_link.id`、`cps_wx_user.first_group_id`→`cps_group.id`;**点击与订单无法对到单笔**,只在群维度(`sid`)汇合——`cps_order.sid` ≈ `cps_group.sid` ≈ `cps_link.sid` ≈ `cps_click.sid`(仅美团有 sid,淘宝/京东无)。统计按群聚合,故 `group_id`/`sid` 冗余进 `cps_click` 免 join。`cps_wx_user` 按 `openid` 自成用户身份维度,与 `cps_click`/`cps_order` 无 id 级 join。
 - **比价沉淀两表(`price_observation` / `store_mapping`)**:`trace_id` 软指 pricebot work_logs(与 `comparison_record.trace_id` 同源但不互 join,各存各视角);`source_user_id` / `source_device_id` 软指用户/设备(可空,匿名也记)。`store_mapping.lookup` 靠**店名字符串精确相等** + geo 取最近,非 id 级 join。
@@ -224,10 +188,10 @@
 ```
 user ─1:1─ coin_account
 user ─1:1─ wechat_transfer_authorization
-user ─1:N─ { coin_transaction, cash_transaction, invite_cash_transaction, withdraw_order,
-            signin_record, signin_boost_record, user_task, comparison_record(user_id 可空),
-            comparison_milestone_claim, savings_record, ad_reward_record, ad_watch_log,
-            ad_ecpm_record, ad_feed_reward_record, price_report, feedback, device_liveness }
+user ─1:N─ { coin_transaction, cash_transaction, withdraw_order, signin_record,
+            signin_boost_record, user_task, comparison_record, comparison_milestone_claim,
+            savings_record, ad_reward_record, ad_watch_log, ad_ecpm_record, ad_feed_reward_record,
+            price_report, feedback, device_liveness }
                                              (device_liveness 硬 FK; (user_id,device_id) 唯一)
 user ─1:N─ onboarding_completion             (user_id, 无硬 FK; (user_id,device_id) 去重)
 comparison_record ─1:N─ price_report        (comparison_record_id, 可空)
@@ -235,11 +199,6 @@ admin_user ─1:N─ admin_audit_log
 app_config                                   (独立, 无外键, key 为主键)
 coupon_prompt_engagement / coupon_daily_completion / coupon_claim_record
                                              (独立, 无硬 FK; 维度=device_id+北京日, user_id/trace_id 仅软关联)
-coupon_session                               (独立, 无硬 FK; trace_id 唯一=一次领券任务一行, #99)
-analytics_event                              (独立, 无硬 FK; 埋点事件流, device/user 仅维度, #83)
-admin_role ◀──语义(role 按 name 引用, 无FK)── admin_user   (pages_override 个人覆盖, #117/#126)
-ops_stat_config / ops_marquee_seed / meituan_coupon / ad_pangle_daily_revenue
-                                             (独立运营/缓存/对账表, 无外键)
 user ─1:N─ invite_relation                   (inviter_user_id 硬 FK);  invitee_user_id ─1:1─ user (唯一硬 FK)
 user ─1:N─ invite_fingerprint                (inviter_user_id 硬 FK)
 cps_activity / cps_group ──语义(无FK)──▶ cps_link ─1:N─ cps_click
@@ -253,13 +212,13 @@ launch_confirm_sample                        (独立, 无硬 FK; 都上报不去
 
 ## 四、资金模型(金币 / 现金 / 提现,三层)
 
-1. **余额快照** `coin_account`:`coin_balance`(金币个数)+ `cash_balance_cents`(现金分)+ `invite_cash_balance_cents`(邀请奖励金分,#82),一用户一行,读取展示用。
-2. **流水账本** `coin_transaction` / `cash_transaction` / `invite_cash_transaction`:每次变动写一笔,`balance_after*` 记变动后余额,可逐笔回溯对账。**现金与邀请奖励金是两本物理隔离的账**——发放口径与提现对账各自独立。
-3. **唯一变动入口**:金币走 `repositories/wallet.grant_coins`,邀请奖励金走 `grant_invite_cash`——都是「更新快照 + 写流水,**不 commit**,由调用方同一事务 commit」。signin / signin_boost / task / ad_reward / feed_ad_reward / exchange / admin 走 `grant_coins`;`invite_reward` / admin 调整走 `grant_invite_cash`,靠 `biz_type` 区分来源。
+1. **余额快照** `coin_account`:`coin_balance`(金币个数)+ `cash_balance_cents`(现金分),一用户一行,读取展示用。
+2. **流水账本** `coin_transaction` / `cash_transaction`:每次变动写一笔,`balance_after*` 记变动后余额,可逐笔回溯对账。
+3. **唯一发金币入口** `repositories/wallet.grant_coins`:更新快照 + 写流水,**不 commit**,由调用方在同一事务里 commit(保证"记录"和"加币"原子化)。signin / signin_boost / task / ad_reward / feed_ad_reward / exchange / admin 都走它,靠 `biz_type` 区分来源。
 
 - **汇率**:`10000 金币 = 1 元 = 100 分`(`rewards.COIN_PER_YUAN`);兑换额必须是整分倍数。
-- **提现状态机**:`reviewing`(发起即原子扣款、待人工审核、**不打款**)→ 审核通过 `pending`(微信转账在途)→ `success` / `failed`(失败自动退款);审核拒绝 `rejected`(退款)。**按 `withdraw_order.source` 分账**(#121):`coin_cash` 单的扣款/退款写 `cash_transaction`,`invite_cash` 单写 `invite_cash_transaction`;`out_bill_no` 幂等,孤儿 pending 单由 `reconcile_pending_withdraws` 对账兜底,admin `withdraws/ledger-check` 分账校验「单 ↔ 流水」。
-- **防超额**:扣款用带条件 `UPDATE ... WHERE <对应余额列> >= amount`(按 source 选 `cash_balance_cents` / `invite_cash_balance_cents`),并发/重试不会双扣。
+- **提现状态机**:`reviewing`(发起即原子扣现金、待人工审核、**不打款**)→ 审核通过 `pending`(微信转账在途)→ `success` / `failed`(失败自动退款);审核拒绝 `rejected`(退款)。扣款/退款都写 `cash_transaction`,`out_bill_no` 幂等,孤儿 pending 单由 `reconcile_pending_withdraws` 对账兜底。
+- **防超额**:扣现金用带条件 `UPDATE ... WHERE cash_balance_cents >= amount`,并发/重试不会双扣。
 
 ---
 

docs/database/README.md

@@ -3,13 +3,13 @@
 > 数据库:SQLite 起步(`data/app.db`),生产可切 PostgreSQL(改 `DATABASE_URL`)。
 > ORM:SQLAlchemy 2.0(`app/models/`),迁移:Alembic(`alembic/versions/`,`render_as_batch` 兼容 SQLite)。
 > 金额字段一律存**整数**:金币=个数,现金=**分**(`*_cents`)。时间列 `DateTime(timezone=True)`。
-> 最后更新:2026-07-09(补 5 张新表文档并入索引:`coupon_session`(#99 领券任务流水)、`analytics_event`(#83 埋点)、`invite_cash_transaction`(#82 邀请奖励金账本)、`admin_role`(#117/#126 RBAC 角色)、`ad_pangle_daily_revenue`(#92,文档已有、补进索引);同步改动列:`comparison_record.product_names`、`withdraw_order.source`、`coin_account.invite_cash_balance_cents`、`feedback` 审核/环境列、`cps_order` 京东列、`device_liveness.first_protected_at`、`ad_feed_reward_record.ad_type/feed_scene`、`admin_user.plain_password/pages_override`。上一次 2026-06-23)
+> 最后更新:2026-06-23(补 3 张表文档:`device_liveness`(#65 无障碍存活监控)、`cps_wx_user`(CPS 落地页微信身份)、`launch_confirm_sample`(启动确认窗兜底样本);`comparison_record` 补 `input_tokens`/`output_tokens`。上一次 2026-06-17 补全 CPS 群发 5 张 `cps_*` + 好友邀请 2 张 `invite_*` + 比价沉淀 `price_observation`/`store_mapping` 并全表 review 对齐 model;含 [OVERVIEW 总览](./OVERVIEW.md))
 
 > 🧭 **先看 [OVERVIEW.md — 表 × 功能 × 关系](./OVERVIEW.md)**:跨表的「每块功能用哪些表 / 什么操作写哪张表 / 表间 join key」都在那;本页只做**单表索引**,点进每张表的详情看字段级说明。
 
 ---
 
-## 表总览(45 张业务表 + `alembic_version` 框架表)
+## 表总览(40 张业务表 + `alembic_version` 框架表)
 
 ### 账号 / 反馈
 | 表 | 用途 | 模型 | 文档 |
@@ -22,7 +22,7 @@
 ### 好友邀请(注册增长)
 | 表 | 用途 | 模型 | 文档 |
 |---|---|---|---|
-| `invite_relation` | 邀请绑定关系(注册即生效但**绑定不发奖** #113;好友比价并下单后发邀请奖励金,`compare_reward_granted` 幂等闸;`invitee_user_id` 唯一) | `models/invite.py` | [详情](./invite_relation.md) |
+| `invite_relation` | 邀请绑定关系(注册即生效,双方各发1万金币;`invitee_user_id` 唯一=幂等防重复发奖) | `models/invite.py` | [详情](./invite_relation.md) |
 | `invite_fingerprint` | 剪贴板归因失败时的指纹兜底(落地页记 ip+屏幕+机型,登录后反查邀请人) | `models/invite_fingerprint.py` | [详情](./invite_fingerprint.md) |
 
 ### 钱包 / 福利(看广告赚钱闭环)
@@ -30,9 +30,8 @@
 |---|---|---|---|
 | `coin_account` | 金币+现金余额快照(一用户一行) | `models/wallet.py` | [详情](./coin_account.md) |
 | `coin_transaction` | 金币流水账本 | `models/wallet.py` | [详情](./coin_transaction.md) |
-| `cash_transaction` | 现金流水账本(分,金币兑换账) | `models/wallet.py` | [详情](./cash_transaction.md) |
-| `invite_cash_transaction` | 邀请奖励金流水账本(分,与现金物理隔离;好友比价并下单发奖 + `source=invite_cash` 提现) | `models/wallet.py` | [详情](./invite_cash_transaction.md) |
-| `withdraw_order` | 提现单(现金→微信零钱,含人工审核态;`source` 分账 coin_cash/invite_cash) | `models/wallet.py` | [详情](./withdraw_order.md) |
+| `cash_transaction` | 现金流水账本(分) | `models/wallet.py` | [详情](./cash_transaction.md) |
+| `withdraw_order` | 提现单(现金→微信零钱,含人工审核态) | `models/wallet.py` | [详情](./withdraw_order.md) |
 | `wechat_transfer_authorization` | 微信免确认转账授权(一用户一行) | `models/wallet.py` | [详情](./wechat_transfer_authorization.md) |
 | `signin_record` | 签到记录(7 天循环) | `models/signin.py` | [详情](./signin_record.md) |
 | `signin_boost_record` | 签到后看广告膨胀记录 | `models/signin.py` | [详情](./signin_boost_record.md) |
@@ -40,8 +39,7 @@
 | `ad_reward_record` | 看激励视频发奖记录(S2S 回调,trans_id 幂等) | `models/ad_reward.py` | [详情](./ad_reward_record.md) |
 | `ad_watch_log` | 看广告观看时长(旧版兼容字段) | `models/ad_watch_log.py` | [详情](./ad_watch_log.md) |
 | `ad_ecpm_record` | 广告展示 eCPM 上报(收益对账) | `models/ad_ecpm.py` | [详情](./ad_ecpm_record.md) |
-| `ad_feed_reward_record` | 信息流/Draw 广告结算记录(10 秒一份,client_event_id 幂等;`ad_type`+`feed_scene` 分形态/场景) | `models/ad_feed_reward.py` | [详情](./ad_feed_reward_record.md) |
-| `ad_pangle_daily_revenue` | 穿山甲 GroMore 后台收益日表(定时拉取,收益报表/大盘真实收益源,#92) | `models/ad_pangle_revenue.py` | [详情](./ad_pangle_daily_revenue.md) |
+| `ad_feed_reward_record` | 信息流广告结算记录(10 秒一份,client_event_id 幂等) | `models/ad_feed_reward.py` | [详情](./ad_feed_reward_record.md) |
 
 ### 比价 / 省钱
 | 表 | 用途 | 模型 | 文档 |
@@ -64,7 +62,6 @@
 | `coupon_prompt_engagement` | 领券引导窗频控源(今日是否已 engage,按 device+package+日) | `models/coupon_state.py` | [详情](./coupon_state.md) |
 | `coupon_daily_completion` | 首页「去领取」置灰源(今日是否已跑完整轮) | `models/coupon_state.py` | [详情](./coupon_state.md) |
 | `coupon_claim_record` | 每张券领取结果沉淀(资产/画像/排查,不参与判断) | `models/coupon_state.py` | [详情](./coupon_state.md) |
-| `coupon_session` | 一次领券任务一行的全程流水(发起/终态/耗时/机型,admin 领券看板数据源,#99) | `models/coupon_state.py` | [详情](./coupon_session.md) |
 
 ### 美团 CPS 券缓存
 | 表 | 用途 | 模型 | 文档 |
@@ -87,16 +84,10 @@
 | `ops_stat_config` | 首页三统计展示配置(real/manual/random) | `models/ops_stat_config.py` | [详情](./ops_stat_config.md) |
 | `ops_marquee_seed` | 首页轮播种子(真实不足时兜底混播) | `models/ops_marquee_seed.py` | [详情](./ops_marquee_seed.md) |
 
-### 埋点
-| 表 | 用途 | 模型 | 文档 |
-|---|---|---|---|
-| `analytics_event` | 客户端埋点事件流(批量上报,一事件一行;admin 埋点日志检索,#83) | `models/analytics_event.py` | [详情](./analytics_event.md) |
-
 ### 运营后台 admin(独立子应用 `app/admin/`,独立鉴权)
 | 表 | 用途 | 模型 | 文档 |
 |---|---|---|---|
-| `admin_user` | 管理员账号(独立 JWT + RBAC;`pages_override` 个人可见页覆盖) | `models/admin.py` | [详情](./admin_user.md) |
-| `admin_role` | 后台角色→可见页配置(内建三角色 + 自定义角色,#117/#126) | `models/admin_role.py` | [详情](./admin_role.md) |
+| `admin_user` | 管理员账号(独立 JWT + RBAC) | `models/admin.py` | [详情](./admin_user.md) |
 | `admin_audit_log` | 操作审计日志(只追加) | `models/admin.py` | [详情](./admin_audit_log.md) |
 | `app_config` | 运营可配置项(覆盖 rewards 常量) | `models/app_config.py` | [详情](./app_config.md) |
 

docs/database/ad_feed_reward_record.md

@@ -11,8 +11,6 @@
 | `id` | Integer | PK | 自增主键 |
 | `client_event_id` | String(64) | UNIQUE, NOT NULL | 客户端幂等事件 id |
 | `ad_session_id` | String(64) | index, nullable | 客户端生成的一次信息流广告会话 id |
-| `ad_type` | String(16) | nullable, default `feed` | 广告形态:`feed`(信息流)/ `draw`(Draw 视频流)。旧数据 NULL 视为 feed(迁移随 #83 入库) |
-| `feed_scene` | String(16) | nullable | 展示场景:`compare`(比价期)/ `coupon`(领券期)。比价与领券共用同一 Draw 代码位,收益/大盘按它分场景归集(#125 修比价/领券奖励金币恒 0 即改按本列汇总) |
 | `user_id` | Integer | FK → `user.id`, index, NOT NULL | 用户 |
 | `reward_date` | String(10) | index, NOT NULL | 北京时间日期 `YYYY-MM-DD` |
 | `duration_seconds` | Integer | NOT NULL | 整场比价累计观看秒数(轮播各条相加) |

docs/database/admin_role.md

@@ -1,32 +0,0 @@
-# admin_role — 运营后台角色(RBAC 可见页配置)
-
-> 模型 `app/models/admin_role.py` · 仓库 `app/admin/repositories/admin_role.py` · 权限目录 `app/admin/permissions.py` · 接口 admin `GET/POST /admin/api/roles`、`PATCH/DELETE /admin/api/roles/{id}`、`GET /admin/api/roles/catalog`(`app/admin/routers/roles.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
-
-运营后台的**角色 → 可见页面**配置表。#117 把 RBAC 从「代码写死三角色」升级为数据驱动:内建角色(`super_admin`/`finance`/`operator`)种子进表(`is_builtin=true`,不可删),`super_admin` 可另建**自定义角色**(#126)勾选任意页面组合。`admin_user.role` 存角色 `name` 按名引用本表;单个管理员还可用 `admin_user.pages_override` 在角色之上覆盖个人可见页。
-
-## 用在哪 / 增删改查
-- **C(插入)**:内建三角色随迁移种子;`POST /admin/api/roles`(super_admin)新建自定义角色。
-- **U(更新)**:`PATCH /admin/api/roles/{id}` 改展示名/可见页(内建角色的 `pages` 也可调)。
-- **D(删除)**:`DELETE /admin/api/roles/{id}`——**内建角色与在用角色(有 admin_user.role 引用)不可删**。
-- **R**:登录/每次 admin 鉴权时按 `admin_user.role` 查本表算有效可见页(`pages_override` 非空则以覆盖为准);`GET /admin/api/roles/catalog` 返回全部可配页面目录(分组,来自 `permissions.py` 常量,不落库)。
-
-## 字段
-| 列 | 类型 | 约束 / 默认 | 说明 |
-|---|---|---|---|
-| `id` | Integer | PK, autoincrement | |
-| `name` | String(32) | UNIQUE, index, NOT NULL | 角色标识(被 `admin_user.role` 按名引用):内建 `super_admin`/`finance`/`operator`;**自定义角色 name(key)= label = 创建时的输入名称**(不能叫 super_admin,重名 409) |
-| `label` | String(32) | NOT NULL, default `""` | 展示名(后台下拉里显示) |
-| `pages` | JSON | NOT NULL, default `[]` | 可见页面 key 列表(全集见 `permissions.py` 目录;前端按它渲染菜单,后端接口守卫同源校验)。**`super_admin` 行 pages 存空数组**,有效可见页特判为全部 |
-| `is_builtin` | Boolean | NOT NULL, default false | 内建角色标记(不可删;`super_admin` 恒过所有守卫,不依赖 pages) |
-| `created_at` | DateTime(tz) | server_default now() | |
-
-## 关系 / Join Key
-- ← `admin_user.role` **按 `name` 语义引用**(无硬 FK;删除保护在应用层:在用角色不可删)。
-- 与 `admin_user.pages_override` 的关系:有效可见页 = `pages_override`(个人覆盖,非空优先)∪ 否则取角色 `pages`;`super_admin` 无视两者恒全通。
-
-## 索引与约束
-- PK `id`;UNIQUE+index `name`。
-
-## 注意
-- 页面 key 目录维护在代码 `app/admin/permissions.py`(加新后台页面要同步登记),表里只存勾选结果——目录变更不需要迁移。
-- 角色守卫兼容旧语义:`require_role("finance")` 等旧代码路径仍工作,内建角色名不可改。

docs/database/admin_user.md

@@ -1,13 +1,13 @@
 # admin_user — 运营后台管理员账号
 
-> 模型 `app/models/admin.py` · 仓库 `app/admin/repositories/admin_user.py` · 接口 [admin-auth-login](../api/admin/auth/admin-auth-login.md) / [admin-admins-list](../api/admin/admins/admin-admins-list.md) / [admin-admin-create](../api/admin/admins/admin-admin-create.md) / [admin-admin-update](../api/admin/admins/admin-admin-update.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/admin.py` · 仓库 `app/admin/repositories/admin_user.py` · 接口 [admin-auth-login](../api/admin-auth-login.md) / [admin-admins-list](../api/admin-admins-list.md) / [admin-admin-create](../api/admin-admin-create.md) / [admin-admin-update](../api/admin-admin-update.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
 
 运营后台(`app/admin/` 子应用,端口 8771)的管理员账号,与 App 用户(`user` 表)**完全隔离**:独立 JWT secret、独立鉴权链。密码 bcrypt 存哈希,带角色做 RBAC 权限分级。
 
 ## 用在哪 / 增删改查
 - **C(插入)**:① 首个管理员用 `scripts/create_admin.py` 命令行创建(无自助注册);② `super_admin` 在后台「管理员管理」`POST` 新建子管理员。
-- **U(更新)**:登录成功刷 `last_login_at`;`super_admin` 改他人 `role`/`status`/重置密码/`pages_override`(`admin-admin-update`)。
-- **D**:`DELETE /admin/api/admins/{id}`(#126,super_admin,带审计;不可删自己)。禁用仍走 `status='disabled'`(token 立即失效)。
+- **U(更新)**:登录成功刷 `last_login_at`;`super_admin` 改他人 `role`/`status`/重置密码(`admin-admin-update`)。
+- **D**:无(禁用走 `status='disabled'`,token 立即失效)。
 - **R**:每个 admin 请求经 `admin/deps` 解 admin token 查本表(校验 `status=='active'` + 角色守卫);管理员列表。
 
 ## 字段
@@ -15,10 +15,8 @@
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | 被 `admin_audit_log.admin_id` 引用 |
 | `username` | String(64) | UNIQUE, index, NOT NULL | 登录名 |
-| `password_hash` | String(255) | NOT NULL | bcrypt 哈希(⚠️ bcrypt 72 字节截断) |
-| `plain_password` | String(128) | nullable | **明文密码副本**(#117,`super_admin` 在管理员列表可见,便于线下派发/找回;创建/重置密码时同步写)。安全上是有意取舍:后台仅内网+super_admin 可见 |
-| `role` | String(20) | NOT NULL, default `operator` | 角色名,按 `name` 引用 [`admin_role`](./admin_role.md)(#117 起数据驱动):内建 `super_admin`(恒全权)/ `finance` / `operator`,或自定义角色(#126) |
-| `pages_override` | JSON | nullable | **个人可见页覆盖**(#126):非空时优先于角色 `pages`;NULL=跟随角色。页面 key 目录见 `app/admin/permissions.py` |
+| `password_hash` | String(255) | NOT NULL | bcrypt 哈希(明文不落库;⚠️ bcrypt 72 字节截断) |
+| `role` | String(20) | NOT NULL, default `operator` | 取值:`super_admin`(全权+管账号)/ `finance`(钱:提现+金币)/ `operator`(用户+反馈+大盘) |
 | `status` | String(20) | NOT NULL, default `active` | 取值:`active` / `disabled`(禁用后 token 立即失效) |
 | `created_at` | DateTime(tz) | server_default now(), NOT NULL | 创建时间 |
 | `last_login_at` | DateTime(tz) | nullable | 最近登录时间(登录成功时更新) |
@@ -32,4 +30,4 @@
 
 ## 注意
 - **鉴权隔离**:admin token `typ=admin` + 独立 `ADMIN_JWT_SECRET`(≠ App 的 `JWT_SECRET_KEY`),App 用户 token 无法当 admin 用;admin 无 refresh,过期(默认 12h)重登。
-- **RBAC**:`super_admin` 恒过所有角色守卫(`require_role`);`finance` 管钱、`operator` 管用户/反馈/大盘;#117 起可见页由 [`admin_role`](./admin_role.md)`.pages` 数据驱动 + `pages_override` 个人覆盖,自定义角色见 `POST /admin/api/roles`。具体守卫见各接口文档。
+- **RBAC**:`super_admin` 恒过所有角色守卫(`require_role`);`finance` 管钱、`operator` 管用户/反馈/大盘。具体守卫见各接口文档。

docs/database/analytics_event.md

@@ -1,39 +0,0 @@
-# analytics_event — 客户端埋点事件流
-
-> 模型 `app/models/analytics_event.py` · 仓库 `app/repositories/analytics.py` · 接口 C 端 `POST /api/v1/analytics/events`([analytics-events](../api/other/analytics-events.md),批量,不强制登录);admin `GET /admin/api/event-logs`(`app/admin/routers/event_logs.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
-
-客户端行为埋点的落地表,**一事件一行**(append-only)。客户端攒批上报(每批 ≤200 条),服务端展开逐条插入;`props` 装事件自带的任意维度。当前主要供 admin「埋点日志」检索与手工分析,无自动聚合任务。#83 新增(2026-06-27)。
-
-## 用在哪 / 增删改查
-- **C(插入)**:`POST /api/v1/analytics/events`(不强制登录:带 JWT 则记 `user_id`,匿名只记 `device_id`)。服务端补 `client_ip`。
-- **U / D**:无。只追加。
-- **R**:admin `GET /admin/api/event-logs`(游标分页,可按 `event`/`device_id`/`user_id` 筛)。
-
-## 字段
-| 列 | 类型 | 约束 / 默认 | 说明 |
-|---|---|---|---|
-| `id` | Integer | PK, autoincrement | |
-| `event` | String(64) | index, NOT NULL | 事件名(客户端约定,如页面曝光/点击类事件名) |
-| `props` | JSON | nullable | 事件属性(任意维度,客户端原样传) |
-| `device_id` | String(64) | index, NOT NULL | 客户端 per-install id(匿名也有) |
-| `user_id` | Integer | index, nullable | 登录态才有。**无硬 FK** |
-| `session_id` | String(64) | index, nullable | 客户端会话 id(一次冷启动一个) |
-| `client_ts` | BigInteger | NOT NULL | 事件发生时间(客户端 epoch ms) |
-| `sent_at` | BigInteger | nullable | 客户端上报时间(epoch ms);与 `client_ts` 差 = 攒批延迟 |
-| `page` | String(64) | nullable | 事件所在页面 |
-| `client_ip` | String(64) | nullable | 服务端从请求头取 |
-| `oem` / `os` / `model` | String | nullable | 厂商 / 系统版本 / 机型 |
-| `app_ver` | String(32) | nullable | App versionName |
-| `network` | String(16) | nullable | 网络类型(wifi/cellular) |
-| `channel` | String(32) | nullable | 分发渠道 |
-| `created_at` | DateTime(tz) | server_default now() | 入库时间 |
-
-## 关系 / Join Key
-- `user_id` 软指 `user.id`、`device_id` 与其他表的 per-install id 同源——均无硬 FK(埋点不鉴权、匿名也收,不能被外键约束卡住)。
-
-## 索引与约束
-- PK `id`;index `event`、`device_id`、`user_id`、`session_id`。
-
-## 注意
-- 每批最多 200 条,超出整批 422;单条字段超长按模型截断口径处理。
-- 时间轴分析用 `client_ts`(事件真实发生时刻),`created_at` 只是入库时刻(受攒批影响)。

docs/database/cash_transaction.md

@@ -1,20 +1,17 @@
 # cash_transaction — 现金流水账本(分)
 
-> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-cash-transactions](../api/wallet/wallet-cash-transactions.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-cash-transactions](../api/wallet-cash-transactions.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
 
 现金每变动一笔就记一行(单位:**分**,记变动后余额)。金币兑现金、提现、提现退款都落这里。**只增不改不删**。
 
-> **只管「金币兑换现金」这本账**(`coin_account.cash_balance_cents`)。**邀请奖励金**是另一本物理隔离的账 → [`invite_cash_transaction`](./invite_cash_transaction.md)(同构表);`source=invite_cash` 的提现流水**不落本表**。
-
 ## 用在哪 / 增删改查
-- **C(插入)**:四个来源,每次写一笔:
+- **C(插入)**:三个来源,每次写一笔:
 
   | 动作 / endpoint | `biz_type` | `amount_cents` | `ref_id` 指向 |
   |---|---|---|---|
   | 金币兑现金 `POST /wallet/exchange` | `exchange_in` | + | null(配套 `coin_transaction.exchange_out`) |
-  | 发起提现 `POST /wallet/withdraw`(`source=coin_cash`) | `withdraw` | −(扣现金) | `withdraw_order.out_bill_no` |
+  | 发起提现 `POST /wallet/withdraw` | `withdraw` | −(扣现金) | `withdraw_order.out_bill_no` |
   | 提现失败/取消/审核拒绝退款 | `withdraw_refund` | +(退回) | `withdraw_order.out_bill_no` |
-  | admin 手动调整 `POST /admin/api/users/{id}/cash`(`account=coin_cash`) | `admin_grant` / `admin_deduct` | + / − | null(原因记 `remark`=`admin:<reason>`) |
 
 - **U / D**:无。账本只追加。
 - **R**:`GET /wallet/cash-transactions`(现金明细,`id` 倒序游标);admin 跨用户现金流水。

docs/database/coin_account.md

@@ -1,6 +1,6 @@
 # coin_account — 金币 + 现金余额快照
 
-> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-account](../api/wallet/wallet-account.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-account](../api/wallet-account.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
 
 一用户一行的余额快照,App「资产卡 / 钱包」读它展示。每次余额变动都另写一笔流水(`coin_transaction` / `cash_transaction`)并记 `balance_after`,出问题逐笔回溯。`user_id` 既是主键也是外键(一对一)。详见 [总览 §四 资金模型](./OVERVIEW.md#四资金模型金币--现金--提现三层)。
 
@@ -15,8 +15,7 @@
 |---|---|---|---|
 | `user_id` | Integer | **PK + FK→user.id** | 用户(一用户一行);既是主键也是外键 |
 | `coin_balance` | Integer | NOT NULL, default 0 | 当前金币余额(个数);= 历次 `coin_transaction.amount` 之和 |
-| `cash_balance_cents` | Integer | NOT NULL, default 0 | 当前现金余额(分,**金币兑换账本**);= 历次 `cash_transaction.amount_cents` 之和 |
-| `invite_cash_balance_cents` | Integer | NOT NULL, default 0 | 当前**邀请奖励金**余额(分,与现金物理隔离的第二本现金账);= 历次 [`invite_cash_transaction`](./invite_cash_transaction.md)`.amount_cents` 之和。好友比价并下单发奖入账(#113),`source=invite_cash` 提现出账(#121) |
+| `cash_balance_cents` | Integer | NOT NULL, default 0 | 当前现金余额(分);= 历次 `cash_transaction.amount_cents` 之和 |
 | `total_coin_earned` | Integer | NOT NULL, default 0 | 累计赚取金币(**只增不减**,仅正向 grant 累加),用于"历史总收益"展示 |
 | `updated_at` | DateTime(tz) | server_default now(), onupdate now() | 最后更新时间 |
 
@@ -28,5 +27,5 @@
 - PK `user_id`(同时是 FK→user.id)。
 
 ## 注意
-- **唯一发金币入口** `wallet.grant_coins`:更新本表 + 写 `coin_transaction`,**不 commit**,由调用方同事务提交(发币与业务记录原子化)。邀请奖励金同款:**唯一变动入口 `wallet.grant_invite_cash`**(更新 `invite_cash_balance_cents` + 写 `invite_cash_transaction`)。
-- 扣现金用 `UPDATE ... WHERE <对应余额列> >= amount` 原子条件扣减(按提现 `source` 选 `cash_balance_cents` 或 `invite_cash_balance_cents`),并发/重试不会超额。
+- **唯一发金币入口** `wallet.grant_coins`:更新本表 + 写 `coin_transaction`,**不 commit**,由调用方同事务提交(发币与业务记录原子化)。
+- 扣现金用 `UPDATE ... WHERE cash_balance_cents >= amount` 原子条件扣减,并发/重试不会超额。

docs/database/comparison_record.md

@@ -1,6 +1,6 @@
 # comparison_record — 比价记录(每次比价完整明细)
 
-> 模型 `app/models/comparison.py` · 仓库 `app/repositories/comparison.py` · 接口 [compare-record-report](../api/compare/compare-record-report.md) / [compare-records](../api/compare/compare-records.md) / [compare-record-detail](../api/compare/compare-record-detail.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/comparison.py` · 仓库 `app/repositories/comparison.py` · 接口 [compare-record-report](../api/compare-record-report.md) / [compare-records](../api/compare-records.md) / [compare-record-detail](../api/compare-record-detail.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
 
 每完成一次比价(外卖/电商/领券)记一行。**写入以 app-server 后端 harvest 为主**(2026-07 起):比价透传壳 `compare.py` 在帧0(pricebot 出 trace_id)即建 `running` 行,随 done / `trace/finalize` 逐步补全成终态,客户端不再主动 POST 记录;老客户端仍可走**带 JWT** 的 `POST /compare/record` 兜底(灰度期两条写路径按 `trace_id` reconcile)。App「我的比价记录」列表/详情的数据源,也是比价战绩里程碑解锁进度的计数源(`status='success'` 条数),还被「上报更低价」反查原最低价。
 
@@ -8,9 +8,9 @@
 > 与 [`price_observation`](./price_observation.md) / `store_mapping` 的区别:本表是**用户视角**(登录后按 `user_id` 存「我的比价记录」);后两张是 server 侧无条件沉淀的**平台/门店视角客观事实**(价格事实 / 跨平台店铺身份映射),与本表 `trace_id` 同源但不互相 join,各存各的视角。
 
 ## 用在哪 / 增删改查
-- **C / U(harvest 为主,按 `trace_id` 幂等)**:透传壳 `compare.py` 三段式落库(`app/repositories/comparison.py`)——`harvest_running`(帧0 建 `running` 行)→ `harvest_done`(done 帧转 `success`/`failed` + 派生 `best_*`/`saved_amount_cents`;`newly_success` 仅留日志观测,**不在此发邀请奖**——#113 已把发奖口径移到「实际下单」`POST /order/report`)→ `harvest_abort`(`trace/finalize` 转 `cancelled`/`failed`,**不降级已 success**)。老客户端仍可 `POST /compare/record`(`upsert_record`,按 `trace_id` 查、整行覆盖)兜底。`best_*`/`saved_amount_cents`/`is_source_best`/`status` 一律由 `_derive` 从 `comparison_results` 算出(协议已按 price 升序、rank=1 最便宜),不信客户端自算。
+- **C / U(harvest 为主,按 `trace_id` 幂等)**:透传壳 `compare.py` 三段式落库(`app/repositories/comparison.py`)——`harvest_running`(帧0 建 `running` 行)→ `harvest_done`(done 帧转 `success`/`failed` + 派生 `best_*`/`saved_amount_cents` + 返 `newly_success` 供幂等发邀请奖)→ `harvest_abort`(`trace/finalize` 转 `cancelled`/`failed`,**不降级已 success**)。老客户端仍可 `POST /compare/record`(`upsert_record`,按 `trace_id` 查、整行覆盖)兜底。`best_*`/`saved_amount_cents`/`is_source_best`/`status` 一律由 `_derive` 从 `comparison_results` 算出(协议已按 price 升序、rank=1 最便宜),不信客户端自算。
 - **D**:无(关联的 `price_report` 也只把 `comparison_record_id` 置空,不删本表)。
-- **R**:`GET /compare/records`(列表,`created_at` 倒序游标 + 「已下单」标记)、`GET /compare/records/{id}`(详情,限本人);`count_success` 给里程碑;`get_stats`(`status='success'` 计数 + `saved_amount_cents` 求和)给 [`GET /compare/stats`](../api/compare/compare-stats.md) 喂「我的」页省钱战绩卡(完成比价 + 累计发现可省,**比价口径**);`report.py` 反查 `best_*`;admin 大盘/明细。
+- **R**:`GET /compare/records`(列表,`created_at` 倒序游标 + 「已下单」标记)、`GET /compare/records/{id}`(详情,限本人);`count_success` 给里程碑;`get_stats`(`status='success'` 计数 + `saved_amount_cents` 求和)给 [`GET /compare/stats`](../api/compare-stats.md) 喂「我的」页省钱战绩卡(完成比价 + 累计发现可省,**比价口径**);`report.py` 反查 `best_*`;admin 大盘/明细。
 
 ## 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
@@ -30,7 +30,6 @@
 | `saved_amount_cents` | Integer | nullable | 源价 − 最优价(可 0/负:源平台本就最便宜) |
 | `is_source_best` | Boolean | nullable | 源平台就是最便宜(= 这次没省到) |
 | `store_name` | String(128) | nullable | 店铺名。**与 `savings_record.shop_name` 按字符串相等关联**,给本记录打「已下单」 |
-| `product_names` | String(512) | nullable | 菜品/商品名拼接串(`items[].name` 顿号连接,超长截断),**专供 admin 比价记录按店/商品模糊搜索**(#117:对 JSON 列做 LIKE 不可移植,冗余成扁平列;写入时随 harvest/upsert 同步生成)。C 端不读它 |
 | `total_dish_count` / `skipped_dish_count` | Integer | nullable | 菜品总数 / 目标平台没找到被跳过数 |
 | `status` | String(16) | NOT NULL, default `success` | 取值:`running`(harvest 帧0 建行、比价进行中)/ `success`(有非源且有价的目标结果)/ `failed`(出错/没采到目标价)/ `cancelled`(用户终止 / Phase1 未识别,`harvest_abort` 写,**不降级已 success**)。**里程碑只数 success** |
 | `information` | String(256) | nullable | done 帧文案;成功=摘要,失败=具体原因(前端失败时当原因展示) |
@@ -40,8 +39,6 @@
 | `raw_payload` | JSON(PG: JSONB) | nullable | 客户端原始上报全量(calibration + done.params),取数兜底 |
 | `input_tokens` | Integer | nullable | 本次 LLM 累计输入 token = Σ `llm_calls[].usage.prompt_tokens`(server 收上报后从 `llm_calls` 累加;旧记录/未采集为 null) |
 | `output_tokens` | Integer | nullable | 本次 LLM 累计输出 token = Σ `llm_calls[].usage.completion_tokens`(同上) |
-| `llm_cost_yuan` | Float | nullable | 本次比价 LLM 总成本(元),回填时按「当时价」逐模型算好冻结(见 `services/llm_cost.py`);旧记录/未回填为 null → 前端回退「估算成本」 |
-| `llm_price_snapshot` | JSON(PG: JSONB) | nullable | 算成本所用单价快照 `{mode, prices:{model:{input_per_1m,output_per_1m,_source}}}`;`app_config` 只存当前价、不留历史,故冻结当时价供审计/复算 |
 | `created_at` | DateTime(tz) | server_default now(), index | 时间 |
 
 > `ordered`(已下单)是**瞬态字段**,不在表里:`list_records` 读取时按 `store_name ∈ 该用户 source='compare' 的 savings_record.shop_name 集合` 现挂到实例上供出参用。

docs/database/coupon_session.md

@@ -1,44 +0,0 @@
-# coupon_session — 领券任务全程流水(admin「领券数据」看板数据源)
-
-> 模型 `app/models/coupon_state.py`(`CouponSession`) · 仓库 `app/repositories/coupon_state.py`(`upsert_session`) · 接口 C 端 `POST /api/v1/coupon/session`([coupon-session](../api/coupon/coupon-session.md));admin `GET /admin/api/coupon-data/*`(聚合看板 + 明细,`app/admin/routers/coupon_data.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
-
-**一次领券任务一行**(`trace_id` 唯一),记从发起(`started`)到收尾(`completed`/`failed`/`abandoned`)的全程:总耗时、各平台耗时、领到张数、机型/ROM、发起来源。与同文件的三张「今日状态」表([coupon_state](./coupon_state.md))分工不同:那三张按「设备×日」管**频控/置灰**,本表按「一次任务」管**漏斗与体验指标**——admin「领券数据」看板的发起数、完成率、中途流失(started 无终态)、平均耗时都从这算。#99 新增(2026-06-30)。
-
-## 用在哪 / 增删改查
-- **C / U(upsert,按 `trace_id`)**:客户端 `POST /api/v1/coupon/session` **两段上报**——发起时建行(`status='started'`,带 platforms/origin_package/机型),收尾时按同 `trace_id` 更新同一行(终态 + `elapsed_ms` + `platform_elapsed` + `claimed_count`)。发起即落库 → 收尾丢失(App 被杀/断网)的行永远停在 `started` = 中途流失,可量化。
-- **D**:无。
-- **R**:admin `GET /admin/api/coupon-data`(按 `started_date` × `app_env` 聚合趋势/漏斗 + 逐条明细,join `user` 出手机号)+ `GET /admin/api/coupon-data/user-records`(用户抽屉:某用户全部领券记录)。
-
-## 字段
-| 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
-|---|---|---|---|
-| `id` | Integer | PK, autoincrement | |
-| `trace_id` | String(64) | NOT NULL, **UNIQUE**(`uq_coupon_session_trace`) | 一次领券唯一 id(客户端 UUID,全程贯穿),upsert 幂等键;与 pricebot work_logs / `coupon_claim_record.trace_id` 同源 |
-| `device_id` | String(64) | NOT NULL | 客户端 per-install id |
-| `user_id` | Integer | index, nullable | 登录态才带(admin join `user` 出手机号/昵称);匿名领券为空。**无硬 FK** |
-| `status` | String(16) | NOT NULL | `started`(发起)/ `completed` / `failed` / `abandoned`(用户中止)。`started` 无终态 = 中途流失 |
-| `app_env` | String(16) | index, nullable | `prod` / `dev`(客户端 BuildConfig.DEBUG)。admin 报表默认只看 prod,防测试数据串台 |
-| `platforms` | JSON(PG: JSONB) | nullable | 发起勾选平台 `["meituan-waimai", ...]`;空=全领 |
-| `origin_package` | String(64) | nullable | 发起来源外卖 App 包名;null=App 内(傻瓜比价首页)发起,非空=切到美团/淘宝/京东被弹券引导发起。admin「发起平台」列据此区分 |
-| `device_model` | String(128) | nullable | 机型(Build.MANUFACTURER + MODEL) |
-| `rom` | String(64) | nullable | ROM(OemDetector,如 `ColorOS 14`) |
-| `started_at` | DateTime(tz) | NOT NULL | 发起时刻(客户端墙钟) |
-| `started_date` | Date | NOT NULL | 发起的 Asia/Shanghai 自然日;admin 按天聚合/筛选(复合索引) |
-| `finished_at` | DateTime(tz) | nullable | 收尾时刻(服务端 now);未收尾(流失)为空 |
-| `elapsed_ms` | Integer | nullable | 全程耗时(客户端点发起→收尾计时,权威);平均/分位只统计 completed |
-| `platform_elapsed` | JSON(PG: JSONB) | nullable | 各平台领券耗时 `{"meituan-waimai": 3200, ...}`(ms) |
-| `claimed_count` | Integer | nullable | 本次领到张数(收尾上报) |
-| `trace_url` | String(512) | nullable | pricebot 公网调试链接(admin 明细可点开复盘) |
-| `created_at` / `updated_at` | DateTime(tz) | server_default now() / +onupdate | |
-
-## 关系 / Join Key
-- `user_id` 软指 `user.id`(无硬 FK,可空;admin 明细 LEFT JOIN 出手机号)。
-- `trace_id` 与 pricebot work_logs、[`coupon_claim_record`](./coupon_state.md).`trace_id` 同源(一次任务),无 id 级 join。
-- `device_id` 与领券三表同源(per-install id)。
-
-## 索引与约束
-- PK `id`;UNIQUE `trace_id`;index `user_id`、`app_env`;复合 index `ix_coupon_session_date_env`(`started_date`, `app_env`)= admin 看板主查询路径。
-
-## 注意
-- 写库 best-effort 口径与领券三表一致:上报失败不影响领券本身(且本表数据源是客户端**独立上报**,不是 `/coupon/step` 透传顺手写)。
-- `elapsed_ms` 以客户端计时为准(墙钟差不影响);`finished_at - started_at` 只做时刻留痕,不用来算时长。

docs/database/coupon_state.md

@@ -1,16 +1,14 @@
-# coupon_state — 领券状态表(今日状态三张 + 领券流水 coupon_session)
+# coupon_state — 领券今日状态三张表(弹窗频控 / 首页置灰 / 领券记录)
 
 > 模型 `app/models/coupon_state.py` · 仓库 `app/repositories/coupon_state.py` · 接口 `app/api/v1/coupon.py`(prefix `/api/v1/coupon`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
-> 同模型文件里还有第四张表 [`coupon_session`](./coupon_session.md)(一次领券任务一行的全程流水,admin「领券数据」看板数据源,#99)——维度与本文三张「设备×日」状态表不同,单独成文。
 
 领券（优惠券自动化）联动产生的三张「今日状态」表，都挂在领券透传端点 `POST /api/v1/coupon/step` 这条链路上（pricebot 跑领券，结果回 app-server 落库；**领券过程本身在 pricebot 内存态跑、不落库**）。三表各管一件事：
 
 - **`coupon_prompt_engagement`** — 弹窗频控源。按 `(device, App 包名, 自然日)` 记「今天**这个 App** 是否对领券引导窗表达过**意向**」（弹出即记 `shown` / 点「一键领取」=`claim_started` / 点拒绝关闭=`dismissed` 都算）。切到外卖 App 时据此决定弹不弹：今天**该 App** engage 过就不再弹该 App。频控维度自 2026-06-14 起含 `package`，美团/淘宝/京东各自独立、互不压制。
 - **`coupon_daily_completion`** — 首页置灰源。按 `(device, 自然日)` 记「今天是否已**跑完整轮**领券（到 done 帧）」。首页「去领取」卡据此置灰：今天跑完了就不能再领。
 - **`coupon_claim_record`** — 资产沉淀层。按 `(device, 券, 自然日)` 记每张券的领取结果（success/already_claimed/failed/skipped），**纯沉淀**（资产/画像/排查/CPS 归因），当前**不参与**「要不要领 / 弹不弹」的判断。
-- **`coupon_session`** — admin「领券数据」看板数据源（**独立流水表,不是「今日状态」表**）。按 `trace_id` 一次领券一行，走 `POST /api/v1/coupon/session` 两段上报（发起/收尾），记全程耗时 + 各平台耗时 + `platform_success`（成功平台,算整单②/点位③成功率）。详见下方专节。
 
-前三张「今日状态」表的共同口径：
+三表共同口径：
 - **判断维度是 `device_id`，不是 `user_id`**：券发到的是设备上登录的那个外卖账号，device 比 user 更贴近「哪个登录环境」，且 `device_id` 全链路现成、不依赖领券鉴权（领券 MVP 阶段 `/coupon/step` 不鉴权）。客户端 `getOrCreateDeviceId` 生成存 SP，**卸载重装会变 → 当新设备重新弹一次**（产品预期）。
 - **日期 = `Asia/Shanghai` 自然日**（`claim_date` / `engage_date` / `complete_date`，`repositories/coupon_state.today_cn()`）。每日可领的券（签到/天天红包）靠这天然每天一条。
 - **`user_id` 可空**：领券登录态有就记（资产/画像），可空、**不进唯一键、不阻塞判断**。
@@ -92,7 +90,7 @@
 ### 用在哪 / 增删改查
 - **C / U（幂等 upsert）**：`record_claims`，由 `POST /api/v1/coupon/step` 写入。一帧的券结果来自 pricebot 的 `last_coupon_result`（最后一张）+ `action.params.coupon_results`（全量）——**会重复带同一张券**，端点 `_extract_coupon_results` 先**按 `coupon_id` 去重**（全量覆盖单张），仓库再靠唯一键幂等：已有则更新 `status`/`reason`/`claimed_count`/`extra`（以最后一次为准），否则插入。
 - **U / D**：无业务删除。
-- **R**：`GET /admin/api/coupon-data/coupons`（`coupon_slot_report`）—— admin「按券成功率」表,按 `coupon_id` 聚合 成功/(成功+失败)（`skipped` 排除,设备-天口径,按 `app_env` 过滤）。见设计 §13。
+- **R**：**当前无读取端点**（纯写入沉淀，未来做去重/归因/画像时再用）。
 
 ### 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
@@ -103,7 +101,6 @@
 | `coupon_id` | String(64) | NOT NULL | 券标识（取自 pricebot 结果） |
 | `claim_date` | **Date** | NOT NULL | **北京时间**自然日（`today_cn()`）；每日可领的券靠它天然每天一条 |
 | `status` | String(24) | NOT NULL | `success` / `already_claimed` / `failed` / `skipped`（原样取 pricebot coupon 结果） |
-| `app_env` | String(16) | index, 可空 | 领券所属 session 环境 `prod`/`dev`（`/step` 按 `trace_id` 取 `coupon_session.app_env` 打标）；旧行 NULL（不回填）。admin「按券成功率」表按它过滤。见设计 §13 |
 | `vendor` | String(48) | 可空 | 券提供方 |
 | `coupon_name` | String(128) | 可空 | 取 pricebot `name` |
 | `claimed_count` | Integer | 可空 | 这张领到几张（pricebot `display_count`，给不出时 None；兼容 `claimed_count`） |
@@ -123,49 +120,7 @@
 
 ---
 
-## coupon_session — 领券任务流水（一次领券一行,admin「领券数据」看板数据源）
-
-`trace_id` 唯一,一次领券一行。与上面三张「今日状态」表不同:本表走 `POST /api/v1/coupon/session`(客户端**两段上报**:发起 `started` 建行、收尾 `completed`/`failed`/`abandoned` 按 `trace_id` 更新同一行),记从发起到收尾的全程耗时 + 各平台耗时 + 机型/ROM。发起即落库 → admin 可算「发起数」与中途流失（started 无终态 = 未完成）。
-
-### 用在哪 / 增删改查
-- **C / U（幂等 upsert）**：`upsert_coupon_session`,由 `POST /api/v1/coupon/session` 两段上报。**状态只前进**（started 帧重复到不覆盖已有终态）;终态补 `finished_at`。
-- **U（并集写）**：`merge_session_platform_success`,由 `POST /api/v1/coupon/step` 每逢**带券结果的帧**调用——把本帧「成功平台」（`status∈{success,already_claimed}` 的券 → `coupon_id` 前缀映射平台）**并入** `platform_success`（并集幂等,无新平台不写;读不到该 trace 行则跳过）。复用 `record_claims` 的同一 `SessionLocal`,不新增连接。
-- **R**：admin `GET /admin/api/coupon-data`（`coupon_data_report`）—— 发起/完成数、耗时分位、**整单成功率②/点位成功率③**、按天/小时趋势、逐条明细;`GET /admin/api/coupon-data/user-records` 某用户全部领券。
-
-### 字段
-| 列 | 类型 | 约束 / 默认 | 说明 |
-|---|---|---|---|
-| `id` | Integer | PK, autoincrement | |
-| `trace_id` | String(64) | NOT NULL, UNIQUE | 一次领券唯一 id（客户端 UUID,全程贯穿）,upsert 键 |
-| `device_id` | String(64) | NOT NULL | |
-| `user_id` | Integer | index, 可空 | 登录态才带（admin join 用户表出手机号/昵称）;匿名领券为空 |
-| `status` | String(16) | NOT NULL | `started` / `completed` / `failed` / `abandoned`;started 无终态 = 中途流失 |
-| `app_env` | String(16) | index, 可空 | `prod` / `dev`;admin 报表默认只看 prod（防测试串台） |
-| `platforms` | JSON | 可空 | 发起勾选平台 `["meituan-waimai",…]`（空 = 全领三档）;**③点位成功率的分母来源** |
-| `origin_package` | String(64) | 可空 | 发起来源外卖 App 包名;null = App 内（傻瓜比价首页）发起,非空 = 外卖侧弹券 |
-| `device_model` | String(128) | 可空 | Build.MANUFACTURER + MODEL |
-| `rom` | String(64) | 可空 | OemDetector,如 "ColorOS 14" |
-| `started_at` | DateTime(tz) | NOT NULL | 发起时刻（客户端墙钟）;明细「时间」列、趋势 X 轴 |
-| `started_date` | **Date** | NOT NULL | 发起的**北京**自然日;admin 按天聚合/筛选（索引） |
-| `finished_at` | DateTime(tz) | 可空 | 收尾时刻（服务端 now）;未收尾（流失）为空 |
-| `elapsed_ms` | Integer | 可空 | 全程耗时（ms,客户端点发起→收尾）;均值/分位只统计 completed |
-| `platform_elapsed` | JSON | 可空 | 各平台领券耗时 `{"meituan-waimai":3200,…}`（ms） |
-| `claimed_count` | Integer | 可空 | 领到总张数（收尾帧带） |
-| `platform_success` | JSON（PG JSONB） | 可空 | **本次至少领到一张（`status∈{success,already_claimed}`）的平台 id 列表**,如 `["meituan-waimai","jd-waimai"]`。`/step` 逐帧按 `trace_id` **并集**写入（`merge_session_platform_success`）;旧行 NULL 视作空集。admin 据此算整单成功率②（`platforms`⊆`platform_success`）/点位成功率③（Σ交集/Σ勾选）。设计:[领券成功率指标](../guides/领券成功率指标-设计与埋点.md) |
-| `trace_url` | String(512) | 可空 | pricebot done 帧回传的公网 trace 链接;未到 done（failed/abandoned）为空 |
-| `created_at` | DateTime(tz) | server_default now() | |
-| `updated_at` | DateTime(tz) | server_default now(), onupdate now() | |
-
-### 索引与约束
-- PK `id`；index `user_id`、`app_env`；UNIQUE(`trace_id`) = `uq_coupon_session_trace`；Index(`started_date`, `app_env`) = `ix_coupon_session_date_env`（admin 主聚合/筛选）。
-
-### 注意
-- `platform_success` 是**布尔性质**的平台集,跨帧**并集**天然幂等 → `/step` 每帧并入不重复计;失败/中途退出的 session 也能拿到崩溃前已成的平台。写放大 ≈ 领券券数（仅带券结果的帧写）。
-- 成功率**基数 = 区间全部 session**（含 abandoned/failed）,与「发起数」同基数（设计 §3）。`coupon_id → 平台` 用前缀（`mt_`/`tb_`·`ele_`·`elm_`/`jd_`）,与客户端 `couponIdToPlatform` 同词表。
-
----
-
-## 今日状态三表共性小结
+## 三表共性小结
 - 数据流向：客户端 → `POST /api/v1/coupon/step`（透传给 pricebot）→ 结果回写这三张表（best-effort，写库失败不影响领券）。
 - 唯一键都含 `device_id` + 某个北京自然日列（engagement 还含 `package`，按 App 频控）；`user_id` 永远是可空旁路（资产留痕，不进唯一键、不阻塞判断）。
 - 无硬外键：`user_id` 软指 `user.id`、`trace_id` 软指 pricebot work_logs（详见 [OVERVIEW → 表间关系 & Join Key](./OVERVIEW.md)）。