chore(scripts): 新增 mock 比价记录灌库脚本(端上走查用)

给指定用户灌一批真实感外卖比价记录,填充首页「上次比价」横幅 / 比价记录页 / 省钱战绩卡。 trace_id 固定幂等,重跑覆盖同号;第 1 条落在 4 分钟新鲜窗口,其余铺近 7 天。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
feat(meituan-cps): 经纬度→城市离线反查 + rec/销量最高按城市过滤
2026-07-04 16:03:54 +08:00 · 2026-07-04 16:00:06 +08:00
108 changed files with 655 additions and 3742 deletions
@@ -1,69 +0,0 @@
-"""admin_role 表(RBAC 角色 → 可见页面)+ 种子内建角色
-
-新增后台 RBAC:角色持有一组页面 key,登录后左侧只展示这些页。super_admin 内建全权(pages 存空、
-effective_pages 特判为全部)、不可编辑删除;operator/finance 播默认页集,可由 super_admin 增删改。
-admin_user.role 弱引用本表 name。全新环境顺序应用即得三条内建角色。
-
-Revision ID: admin_role_table
-Revises: comparison_product_names
-Create Date: 2026-07-04 00:00:00.000000
-"""
-from collections.abc import Sequence
-
-import sqlalchemy as sa
-from sqlalchemy.dialects import postgresql
-
-from alembic import op
-
-revision: str = "admin_role_table"
-down_revision: str | Sequence[str] | None = "comparison_product_names"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-_JSON = sa.JSON().with_variant(postgresql.JSONB(), "postgresql")
-
-# 与 app/admin/permissions.py 的 BUILTIN_ROLES 同口径(迁移内联一份,不耦合 app 常量)。
-# 页集对齐 Prototypes/dashboard/permissions.md 的 ROLES。key 承重(require_role),label 为展示名。
-_BUILTIN = [
-    {"name": "super_admin", "label": "管理员", "pages": [], "is_builtin": True},
-    {"name": "operator", "label": "运营", "pages": [
-        "dashboard", "coupon-data", "ad-revenue-report", "comparison-records",
-        "cps", "device-liveness", "price-reports", "feedbacks",
-    ], "is_builtin": False},
-    {"name": "finance", "label": "财务", "pages": [
-        "dashboard", "ad-revenue-report", "cps", "withdraws",
-    ], "is_builtin": False},
-    {"name": "tech", "label": "技术", "pages": [
-        "dashboard", "device-liveness", "config", "ad-revenue", "event-logs", "audit-logs",
-    ], "is_builtin": False},
-]
-
-
-def upgrade() -> None:
-    op.create_table(
-        "admin_role",
-        sa.Column("id", sa.Integer(), primary_key=True, autoincrement=True),
-        sa.Column("name", sa.String(length=32), nullable=False),
-        sa.Column("label", sa.String(length=32), nullable=False, server_default=""),
-        sa.Column("pages", _JSON, nullable=False),
-        sa.Column("is_builtin", sa.Boolean(), nullable=False, server_default=sa.false()),
-        sa.Column(
-            "created_at", sa.DateTime(timezone=True),
-            server_default=sa.func.now(), nullable=False,
-        ),
-    )
-    op.create_index("ix_admin_role_name", "admin_role", ["name"], unique=True)
-
-    tbl = sa.table(
-        "admin_role",
-        sa.column("name", sa.String),
-        sa.column("label", sa.String),
-        sa.column("pages", _JSON),
-        sa.column("is_builtin", sa.Boolean),
-    )
-    op.bulk_insert(tbl, _BUILTIN)
-
-
-def downgrade() -> None:
-    op.drop_index("ix_admin_role_name", table_name="admin_role")
-    op.drop_table("admin_role")
@@ -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")
@@ -1,29 +0,0 @@
-"""admin_user 加 plain_password 列(明文登录密码,仅后台 UI 建/重置的账号留存)
-
-权限管理页需能复看某成员已确定的登录密码转交本人。系统只存哈希无法反推,故对「后台 UI 创建/重置」
-的管理员额外留存一份明文;脚本/起后台建的超管为 None(前端不显示密码)。旧账号无此列值 → 同样不显示。
-
-Revision ID: admin_user_plain_password
-Revises: admin_role_table
-Create Date: 2026-07-04 00:00:00.000000
-"""
-from collections.abc import Sequence
-
-import sqlalchemy as sa
-
-from alembic import op
-
-revision: str = "admin_user_plain_password"
-down_revision: str | Sequence[str] | None = "admin_role_table"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def upgrade() -> None:
-    with op.batch_alter_table("admin_user", schema=None) as batch_op:
-        batch_op.add_column(sa.Column("plain_password", sa.String(length=128), nullable=True))
-
-
-def downgrade() -> None:
-    with op.batch_alter_table("admin_user", schema=None) as batch_op:
-        batch_op.drop_column("plain_password")
@@ -1,70 +0,0 @@
-"""comparison_record 加 product_names 列(下单商品名派生串)+ 回填历史行
-
-admin 比价记录页要把原「店/商品」一列拆成「店」+「商品」两列、并支持按商品名搜索。
-items 是 JSON(SQLite 下 json.dumps ensure_ascii 会把中文转义存成 \\uXXXX,无法直接 CAST+LIKE
-命中中文),故把商品名派生成普通文本列,跨库 LIKE 一致、可索引。
-
-写路径(upsert_record / harvest_done)已同步派生;本迁移建列并从已存 items 回填历史行。
-全新环境顺序应用即得空列 + 回填(表本为空,回填 no-op)。
-
-Revision ID: comparison_product_names
-Revises: comparison_record_trace_unique
-Create Date: 2026-07-04 00:00:00.000000
-"""
-
-import json
-from collections.abc import Sequence
-
-import sqlalchemy as sa
-
-from alembic import op
-
-revision: str = "comparison_product_names"
-down_revision: str | Sequence[str] | None = "comparison_record_trace_unique"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _product_names(items) -> str | None:
-    """items([{name,...}]) → 顿号分隔的商品名串(去重保序)。与 repositories.comparison
-    ._product_names_from_items 同口径,迁移内联一份避免耦合 app 代码。"""
-    if isinstance(items, str):  # SQLite: items 以 JSON 文本存,取回是 str
-        try:
-            items = json.loads(items)
-        except (ValueError, TypeError):
-            return None
-    if not isinstance(items, list) or not items:
-        return None
-    names: list[str] = []
-    for it in items:
-        name = it.get("name") if isinstance(it, dict) else None
-        if not name:
-            continue
-        s = str(name).strip()
-        if s and s not in names:
-            names.append(s)
-    joined = "、".join(names)
-    return joined[:500] or None
-
-
-def upgrade() -> None:
-    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
-        batch_op.add_column(sa.Column("product_names", sa.String(length=512), nullable=True))
-
-    # 回填:从已存 items 派生商品名。items 小(菜名列表),一次取回即可;只更新有商品名的行。
-    bind = op.get_bind()
-    rows = bind.execute(
-        sa.text("SELECT id, items FROM comparison_record")
-    ).fetchall()
-    for rid, items in rows:
-        pn = _product_names(items)
-        if pn:
-            bind.execute(
-                sa.text("UPDATE comparison_record SET product_names = :pn WHERE id = :id"),
-                {"pn": pn, "id": rid},
-            )
-
-
-def downgrade() -> None:
-    with op.batch_alter_table("comparison_record", schema=None) as batch_op:
-        batch_op.drop_column("product_names")
@@ -1,49 +0,0 @@
-"""comparison_record: 唯一键 (user_id,trace_id) → trace_id 单列 + user_id 可空
-
-Revision ID: comparison_record_trace_unique
-Revises: feedback_type_reply
-Create Date: 2026-07-03 12:00:00.000000
-
-比价记录改「后端 harvest」：app-server 在帧0(pricebot 出 trace_id)即建行，随 done/finalize
-逐步补全，客户端不再 POST 记录。故本表要两处调整：
-  1. user_id 改**可空**——harvest 建行那刻(软鉴权 / 老客户端匿名)可能还没有 user_id。
-  2. 唯一键 (user_id, trace_id) → **trace_id 单列**——trace_id 由 app-server 签发、全局唯一，
-     一次比价一行；harvest 建行时 user_id 还没有，不能再用复合键去重。
-
-⚠️ 上线前(QA)务必确认 comparison_record 无重复 trace_id：旧复合唯一键**允许**同 trace_id
-   跨不同 user_id（实际上客户端 UUID 从不重复，但约束没拦），若真有重复,建 trace 单列唯一会失败。
-   查:  SELECT trace_id, COUNT(*) c FROM comparison_record GROUP BY trace_id HAVING c > 1;
-
-SQLite 不支持直接 drop/alter 约束/列，用 batch_alter_table（建临时表+拷数据+换名），
-与 coupon_engage_per_package / store_mapping_* 同款；Postgres 直接执行原生 ALTER。
-"""
-from typing import Sequence, Union
-
-from alembic import op
-import sqlalchemy as sa
-
-
-# revision identifiers, used by Alembic.
-revision: str = 'comparison_record_trace_unique'
-down_revision: Union[str, Sequence[str], None] = 'feedback_type_reply'
-branch_labels: Union[str, Sequence[str], None] = None
-depends_on: Union[str, Sequence[str], None] = None
-
-
-def upgrade() -> None:
-    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
-        # harvest 帧0 建行时 user_id 可能暂缺 → 放开非空。
-        batch_op.alter_column('user_id', existing_type=sa.Integer(), nullable=True)
-        # 复合唯一 → trace_id 单列唯一。
-        batch_op.drop_constraint('uq_comparison_user_trace', type_='unique')
-        batch_op.create_unique_constraint('uq_comparison_trace', ['trace_id'])
-
-
-def downgrade() -> None:
-    with op.batch_alter_table('comparison_record', schema=None) as batch_op:
-        batch_op.drop_constraint('uq_comparison_trace', type_='unique')
-        batch_op.create_unique_constraint(
-            'uq_comparison_user_trace', ['user_id', 'trace_id']
-        )
-        # 回退非空前提是当时无 null user_id 行(harvest 期可能有孤儿行,回滚需先清理)。
-        batch_op.alter_column('user_id', existing_type=sa.Integer(), nullable=False)
@@ -32,7 +32,6 @@ from app.admin.routers.feedback_qr import router as feedback_qr_router
 from app.admin.routers.onboarding import router as onboarding_router
 from app.admin.routers.ops_marquee_seed import router as ops_marquee_seed_router
 from app.admin.routers.price_report import router as price_report_router
-from app.admin.routers.roles import router as roles_router
 from app.admin.routers.users import router as users_router
 from app.admin.routers.wallet import router as wallet_router
 from app.admin.routers.withdraw import router as withdraw_router
@@ -99,7 +98,6 @@ admin_app.include_router(feedback_router)
 admin_app.include_router(event_logs_router)
 admin_app.include_router(feedback_qr_router)
 admin_app.include_router(admins_router)
-admin_app.include_router(roles_router)
 admin_app.include_router(audit_router)
 admin_app.include_router(config_router)
 admin_app.include_router(comparison_router)
@@ -1,83 +0,0 @@
-"""admin 后台「页面权限目录」—— RBAC 的权限侧单一真源。
-
-一个权限 = 一个页面(= 左侧导航项)。角色持有一组 page key,登录后左侧只展示这些页(见前端
-layout.tsx 按 pages 过滤导航)。key 必须与前端路由一级对齐(/dashboard → "dashboard")。
-
-super_admin 为内建全权角色,恒可见全部页(effective_pages 特判)。新增页面 = 这里加一条 +
-前端导航加对应项(key 一致即可被各角色勾选可见)。
-"""
-from __future__ import annotations
-
-SUPER_ADMIN_ROLE = "super_admin"
-# 「自定义」哨兵角色:不是 admin_role 表里的行,而是标记「这个人的可见页由 pages_override 决定」。
-# admin_user.role == CUSTOM_ROLE 时,有效可见页取 admin_user.pages_override(见 auth._admin_out_with_pages)。
-CUSTOM_ROLE = "custom"
-
-# 分组镜像前端导航(app/(main)/layout.tsx 的 NAV_GROUPS);key = 路由一级
-PERMISSION_CATALOG: list[dict] = [
-    {"group": "看板", "pages": [
-        {"key": "dashboard", "label": "数据大盘"},
-        {"key": "coupon-data", "label": "领券数据"},
-        {"key": "ad-revenue-report", "label": "广告收益"},
-        {"key": "comparison-records", "label": "比价记录"},
-        {"key": "cps", "label": "CPS收益"},
-        {"key": "device-liveness", "label": "设备存活"},
-    ]},
-    {"group": "奖励审核", "pages": [
-        {"key": "withdraws", "label": "提现审核"},
-        {"key": "price-reports", "label": "低价审核"},
-        {"key": "feedbacks", "label": "用户反馈"},
-    ]},
-    {"group": "数据配置", "pages": [
-        {"key": "config", "label": "系统配置"},
-        {"key": "ad-revenue", "label": "广告配置"},
-        {"key": "users", "label": "用户管理"},
-    ]},
-    {"group": "其他", "pages": [
-        {"key": "admins", "label": "权限管理"},
-        {"key": "event-logs", "label": "埋点日志"},
-        {"key": "audit-logs", "label": "审计日志"},
-    ]},
-]
-
-# 全部页面 key(super_admin 有效可见 = 此全集;也用于校验角色 pages 合法性)
-ALL_PAGE_KEYS: list[str] = [p["key"] for g in PERMISSION_CATALOG for p in g["pages"]]
-_ALL_SET = set(ALL_PAGE_KEYS)
-
-# 内建角色定义(种子 / ensure 兜底的单一真源):(key, 中文展示名, 默认可见页)。
-# 页集对齐 Prototypes/dashboard/permissions.md 的 ROLES;super_admin 恒全权(pages 空、bypass)。
-# key 承重(require_role / admin_user.role),勿改;label 为 UI 展示名。
-BUILTIN_ROLES: list[dict] = [
-    {"name": SUPER_ADMIN_ROLE, "label": "管理员", "pages": []},
-    {"name": "operator", "label": "运营", "pages": [
-        "dashboard", "coupon-data", "ad-revenue-report", "comparison-records",
-        "cps", "device-liveness", "price-reports", "feedbacks",
-    ]},
-    {"name": "finance", "label": "财务", "pages": [
-        "dashboard", "ad-revenue-report", "cps", "withdraws",
-    ]},
-    {"name": "tech", "label": "技术", "pages": [
-        "dashboard", "device-liveness", "config", "ad-revenue", "event-logs", "audit-logs",
-    ]},
-]
-
-# 内建 key → 中文展示名(展示 / 自愈用)
-BUILTIN_LABELS: dict[str, str] = {r["name"]: r["label"] for r in BUILTIN_ROLES}
-
-
-def sanitize_pages(pages: list[str] | None) -> list[str]:
-    """过滤掉不在目录里的 key(去重、保序),防脏数据/目录收缩后的悬空 key。"""
-    seen: set[str] = set()
-    out: list[str] = []
-    for k in pages or []:
-        if k in _ALL_SET and k not in seen:
-            seen.add(k)
-            out.append(k)
-    return out
-
-
-def effective_pages(role_name: str, role_pages: list[str] | None) -> list[str]:
-    """某角色的有效可见页:super_admin → 全部;其余 → 其 pages 与目录取交(自愈悬空 key)。"""
-    if role_name == SUPER_ADMIN_ROLE:
-        return list(ALL_PAGE_KEYS)
-    return sanitize_pages(role_pages)
@@ -385,33 +385,10 @@ def ad_revenue_report(
        for k, v in type_map.items()
    }

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

    # 主表「逐行」= 单次广告行为(2026-07 按「一次比价/领券放一块」聚合):激励视频 = 一次观看一行(展示+发奖
    # 按 ad_session_id 合并);一次比价 / 一次领券 = 该次整场多条广告按 ad_session_id 聚成一行(展开看逐条)。
@@ -439,7 +416,6 @@ def ad_revenue_report(
        "daily": daily,
        "hourly": hourly,
        "type_stats": type_stats,
-        "scene_stats": scene_stats,
        "dau": dau,
        "items": main_rows[offset:offset + limit],
    }
@@ -1,81 +0,0 @@
-"""admin_role 表 CRUD + 「角色 → 有效可见页」解析。"""
-from __future__ import annotations
-
-from sqlalchemy import select
-from sqlalchemy.orm import Session
-
-from app.admin.permissions import (
-    ALL_PAGE_KEYS,
-    BUILTIN_ROLES,
-    SUPER_ADMIN_ROLE,
-    sanitize_pages,
-)
-from app.models.admin_role import AdminRole
-
-
-def ensure_builtin_roles(db: Session) -> None:
-    """空表时播种内建角色(管理员/运营/财务/技术)。幂等:表非空即 no-op。
-    给 create_all 环境(测试 / 未跑迁移的全新库)兜底,迁移已播种则不重复。
-    仅 super_admin 为 is_builtin(锁定不可改删);运营/财务/技术可编辑页/删除。"""
-    if db.execute(select(AdminRole.id).limit(1)).first() is not None:
-        return
-    db.add_all([
-        AdminRole(
-            name=r["name"], label=r["label"], pages=list(r["pages"]),
-            is_builtin=(r["name"] == SUPER_ADMIN_ROLE),
-        )
-        for r in BUILTIN_ROLES
-    ])
-    db.commit()
-
-
-def list_roles(db: Session) -> list[AdminRole]:
-    ensure_builtin_roles(db)
-    # super_admin(内建)恒排最前,其余按创建序
-    return list(
-        db.execute(
-            select(AdminRole).order_by(AdminRole.is_builtin.desc(), AdminRole.id)
-        ).scalars().all()
-    )
-
-
-def get_role(db: Session, name: str) -> AdminRole | None:
-    return db.execute(
-        select(AdminRole).where(AdminRole.name == name)
-    ).scalar_one_or_none()
-
-
-def create_role(db: Session, *, name: str, label: str, pages: list[str]) -> AdminRole:
-    # 自定义角色:name(key)= label = 用户输入的名称
-    role = AdminRole(name=name, label=label, pages=sanitize_pages(pages), is_builtin=False)
-    db.add(role)
-    db.commit()
-    db.refresh(role)
-    return role
-
-
-def update_role(
-    db: Session, role: AdminRole, *, label: str | None = None, pages: list[str] | None = None
-) -> AdminRole:
-    # 只改展示名 label + 可见页;name(key)不可变(admin_user.role / require_role 承重)
-    if label is not None:
-        role.label = label
-    if pages is not None:
-        role.pages = sanitize_pages(pages)
-    db.commit()
-    db.refresh(role)
-    return role
-
-
-def delete_role(db: Session, role: AdminRole) -> None:
-    db.delete(role)
-    db.commit()
-
-
-def effective_pages_of(db: Session, role_name: str) -> list[str]:
-    """某角色名的有效可见页:super_admin → 全部;其余 → 查表 pages 与目录取交。"""
-    if role_name == SUPER_ADMIN_ROLE:
-        return list(ALL_PAGE_KEYS)
-    ensure_builtin_roles(db)
-    role = get_role(db, role_name)
-    return sanitize_pages(role.pages if role else None)
@@ -20,23 +20,12 @@ def get_by_username(db: Session, username: str) -> AdminUser | None:


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

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


@@ -103,6 +83,10 @@ def _pick(row: dict[str, Any], *keys: str) -> Any:
        if key in row and row[key] is not None:
            return row[key]
    return None
+    try:
+        return datetime.fromtimestamp(int(ts), tz=timezone.utc)
+    except (ValueError, OSError, TypeError):
+        return None


 # ───────────── 群 ─────────────
@@ -11,7 +11,6 @@ from zoneinfo import ZoneInfo
 from sqlalchemy import Select, asc, case, desc, func, or_, select
 from sqlalchemy.orm import Session

-from app.admin.repositories.stats import COMPARE_START_EVENT, COUPON_START_EVENT
 from app.core import rewards
 from app.core.config import settings
 from app.models.ad_feed_reward import AdFeedRewardRecord
@@ -19,22 +18,12 @@ from app.models.ad_reward import AdRewardRecord
 from app.models.admin import AdminAuditLog
 from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
-from app.models.coupon_state import CouponPromptEngagement
 from app.models.device import DeviceLiveness
 from app.models.feedback import Feedback
 from app.models.onboarding import OnboardingCompletion
 from app.models.price_report import PriceReport
 from app.models.user import User
-from app.models.wallet import (
-    CashTransaction,
-    CoinAccount,
-    CoinTransaction,
-    InviteCashTransaction,
-    WithdrawOrder,
-)
-
-# 「最近活跃」计入的行为事件(与大盘 DAU/留存活跃口径一致:开始比价 + 开始领券)
-_ACTIVE_EVENTS = (COMPARE_START_EVENT, COUPON_START_EVENT)
+from app.models.wallet import CashTransaction, CoinAccount, CoinTransaction, WithdrawOrder

 # 折算成可提现现金时,非广告金币来源的排除集(广告单独统计、人工调整不算"赚取")
 _NON_TASK_BIZ_TYPES = ("reward_video", "feed_ad_reward", "admin_grant", "admin_deduct")
@@ -87,86 +76,6 @@ def offset_paginate(
    return items, next_cursor, total


-def _last_active_parts():
-    """「最近活跃」的两个按 user_id 预聚合派生表(最近开始比价/领券事件、最近领券发起)。
-
-    活跃口径与大盘 DAU/留存一致(2026-07-05 产品定:进入 App≈登录 last_login_at +
-    发起比价 real_compare_start + 发起领券 real_coupon_start/claim_started)。
-    用 LEFT JOIN 预聚合而非相关标量子查询:后者在 PG 上对 users 每行各跑一个 SubPlan
-    (排序键、range 筛选、offset_paginate 的 count 三处叠加),埋点表大了会拖垮列表接口;
-    预聚合借 analytics_event.event 索引只扫两类 start 事件,每次查询聚合一次。
-    """
-    ev_agg = (
-        select(
-            AnalyticsEvent.user_id.label("user_id"),
-            func.max(AnalyticsEvent.created_at).label("last_at"),
-        )
-        .where(
-            AnalyticsEvent.user_id.is_not(None),
-            AnalyticsEvent.event.in_(_ACTIVE_EVENTS),
-        )
-        .group_by(AnalyticsEvent.user_id)
-        .subquery()
-    )
-    eng_agg = (
-        select(
-            CouponPromptEngagement.user_id.label("user_id"),
-            func.max(CouponPromptEngagement.created_at).label("last_at"),
-        )
-        .where(
-            CouponPromptEngagement.user_id.is_not(None),
-            CouponPromptEngagement.engage_type == "claim_started",
-        )
-        .group_by(CouponPromptEngagement.user_id)
-        .subquery()
-    )
-    return ev_agg, eng_agg
-
-
-def _norm_utc(dt: datetime | None) -> datetime | None:
-    """naive 视为 UTC 补 tzinfo(SQLite 读回 naive、PG 读回 aware,混着 max() 会 TypeError)。"""
-    if dt is None:
-        return None
-    return dt if dt.tzinfo is not None else dt.replace(tzinfo=timezone.utc)
-
-
-def _attach_last_active(db: Session, users: list[User]) -> None:
-    """给本页用户瞬态挂 last_active_at(非 DB 列,供 AdminUserListItem from_attributes 读)。
-
-    口径同 [_last_active_expr];按本页 user_id 批量两次 GROUP BY,防 N+1。
-    """
-    uids = [u.id for u in users]
-    if not uids:
-        return
-    ev_map = dict(
-        db.execute(
-            select(AnalyticsEvent.user_id, func.max(AnalyticsEvent.created_at))
-            .where(
-                AnalyticsEvent.user_id.in_(uids),
-                AnalyticsEvent.event.in_(_ACTIVE_EVENTS),
-            )
-            .group_by(AnalyticsEvent.user_id)
-        ).all()
-    )
-    eng_map = dict(
-        db.execute(
-            select(CouponPromptEngagement.user_id, func.max(CouponPromptEngagement.created_at))
-            .where(
-                CouponPromptEngagement.user_id.in_(uids),
-                CouponPromptEngagement.engage_type == "claim_started",
-            )
-            .group_by(CouponPromptEngagement.user_id)
-        ).all()
-    )
-    for u in users:
-        candidates = [
-            _norm_utc(u.last_login_at),
-            _norm_utc(ev_map.get(u.id)),
-            _norm_utc(eng_map.get(u.id)),
-        ]
-        u.last_active_at = max((c for c in candidates if c is not None), default=None)
-
-
 def list_users(
    db: Session,
    *,
@@ -178,34 +87,16 @@ def list_users(
    created_to: datetime | None = None,
    last_login_from: datetime | None = None,
    last_login_to: datetime | None = None,
-    last_active_from: datetime | None = None,
-    last_active_to: datetime | None = None,
    sort_by: str = "id",
    sort_order: str = "desc",
    limit: int = 20,
    cursor: int | None = None,
 ) -> tuple[list[User], int | None, int]:
-    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录·最近活跃
-    时间范围筛选,按 id·注册时间·最近登录·最近活跃排序;每页附带计算列 last_active_at
-    (口径见 [_last_active_expr])。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
+    """用户列表(admin 全量)。支持手机号前缀 / 渠道 / 状态 / 昵称模糊 / 注册·最近登录时间范围筛选,
+    按 id·注册时间·最近登录排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一,
    代价是翻页期间数据变动可能错位一条——admin 低频场景可接受(同 [list_all_withdraw_orders])。
    日期入参统一转 tz-aware UTC 比较(列为 timestamptz,见 _as_utc)。"""
-    # 最近活跃 = max(最近登录, 最近行为事件, 最近领券发起)。PG 用 GREATEST;SQLite 标量 max()
-    # 任一参数 NULL 即返回 NULL,故 LEFT JOIN 未命中侧 coalesce 到 last_login_at 兜底
-    # (注册即登录,该列恒非空)。派生表 1:1(按 user_id 聚合),outerjoin 不会放大行数,
-    # offset_paginate 的 count 不受影响。
-    ev_agg, eng_agg = _last_active_parts()
-    greatest = func.greatest if db.get_bind().dialect.name == "postgresql" else func.max
-    last_active = greatest(
-        User.last_login_at,
-        func.coalesce(ev_agg.c.last_at, User.last_login_at),
-        func.coalesce(eng_agg.c.last_at, User.last_login_at),
-    )
-    stmt = (
-        select(User)
-        .outerjoin(ev_agg, ev_agg.c.user_id == User.id)
-        .outerjoin(eng_agg, eng_agg.c.user_id == User.id)
-    )
+    stmt = select(User)
    if phone:
        stmt = stmt.where(User.phone.like(f"{phone}%"))  # 前缀匹配
    if register_channel:
@@ -222,25 +113,16 @@ def list_users(
        stmt = stmt.where(User.last_login_at >= _as_utc(last_login_from))
    if last_login_to is not None:
        stmt = stmt.where(User.last_login_at <= _as_utc(last_login_to))
-    if last_active_from is not None:
-        stmt = stmt.where(last_active >= _as_utc(last_active_from))
-    if last_active_to is not None:
-        stmt = stmt.where(last_active <= _as_utc(last_active_to))

    sort_cols = {
        "id": User.id,
        "created_at": User.created_at,
        "last_login_at": User.last_login_at,
-        "last_active_at": last_active,
    }
    sort_col = sort_cols.get(sort_by, User.id)
    order_fn = asc if sort_order == "asc" else desc
    id_order = asc(User.id) if sort_order == "asc" else desc(User.id)
-    items, next_cursor, total = offset_paginate(
-        db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor
-    )
-    _attach_last_active(db, items)
-    return items, next_cursor, total
+    return offset_paginate(db, stmt, (order_fn(sort_col), id_order), limit=limit, cursor=cursor)


 def _attach_user_info(db: Session, records: list[ComparisonRecord | Feedback | PriceReport]) -> None:
@@ -266,14 +148,11 @@ def list_comparison_records(
    phone: str | None = None,
    status: str | None = None,
    business_type: str | None = None,
-    store: str | None = None,
-    product: str | None = None,
    limit: int = 20,
    cursor: int | None = None,
 ) -> tuple[list[ComparisonRecord], int | None, int]:
    """admin 比价记录列表(debug)。按 user_id 精确 或 phone 前缀定位用户 + status/业务类型筛,
-    store(店名)/product(商品名)子串模糊匹配,offset 分页(创建时间倒序、id 兜底)。
-    join User 取 phone/nickname 瞬态挂记录上。"""
+    offset 分页(创建时间倒序、id 兜底)。join User 取 phone/nickname 瞬态挂记录上。"""
    stmt = select(ComparisonRecord)
    if user_id is not None:
        stmt = stmt.where(ComparisonRecord.user_id == user_id)
@@ -287,11 +166,6 @@ def list_comparison_records(
        stmt = stmt.where(ComparisonRecord.status == status)
    if business_type:
        stmt = stmt.where(ComparisonRecord.business_type == business_type)
-    if store:
-        stmt = stmt.where(ComparisonRecord.store_name.like(f"%{store}%"))
-    if product:
-        # 商品名搜 product_names 派生文本列(非 items JSON:SQLite 下 JSON 中文被转义无法直接 LIKE)。
-        stmt = stmt.where(ComparisonRecord.product_names.like(f"%{product}%"))
    items, next_cursor, total = offset_paginate(
        db, stmt,
        (desc(ComparisonRecord.created_at), desc(ComparisonRecord.id)),
@@ -852,19 +726,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
@@ -879,95 +760,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,
    }


@@ -5,23 +5,17 @@ user.last_login_at / comparison_record.status / withdraw_order.status)要加索
 """
 from __future__ import annotations

-from collections import Counter
 from datetime import date, datetime, time, timedelta, timezone
 from decimal import Decimal, InvalidOperation

-from sqlalchemy import case, func, select
+from sqlalchemy import func, select
 from sqlalchemy.orm import Session

-from app.admin.repositories.coupon_data import _percentile
 from app.models.ad_feed_reward import AdFeedRewardRecord
 from app.models.ad_reward import AdRewardRecord
 from app.models.analytics_event import AnalyticsEvent
 from app.models.comparison import ComparisonRecord
-from app.models.coupon_state import (
-    CouponClaimRecord,
-    CouponPromptEngagement,
-    CouponSession,
-)
+from app.models.coupon_state import CouponPromptEngagement
 from app.models.cps_order import CpsOrder
 from app.models.feedback import Feedback
 from app.models.savings import SavingsRecord
@@ -30,17 +24,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,
@@ -67,10 +55,29 @@ def _beijing_today_start_utc() -> datetime:
 def today_dau(db: Session) -> int:
    """今日活跃用户数(DAU):登录 + 开始比价 + 开始领券,按用户去重。

-    = period_active_dau(今天, 今天);历史 / 多天窗口用 period_active_dau 传区间(广告收益报表复用)。
+    广告收益报表复用这个函数;历史窗口 DAU 由 dashboard_overview 的 period 口径另算。
    """
    today_bj = datetime.now(_BEIJING).date()
-    return period_active_dau(db, today_bj, today_bj)
+    today_start = _beijing_today_start_utc()
+    tomorrow_start = today_start + timedelta(days=1)
+    login_user_ids = _id_set(
+        db,
+        select(User.id).where(User.last_login_at >= today_start, User.last_login_at < tomorrow_start),
+    )
+    compare_start_user_ids = _event_user_ids(
+        db, (COMPARE_START_EVENT,), today_start, tomorrow_start
+    )
+    coupon_event_user_ids = _event_user_ids(
+        db, (COUPON_START_EVENT,), today_start, tomorrow_start
+    )
+    coupon_claim_user_ids = _id_set(
+        db,
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date == today_bj,
+            CouponPromptEngagement.engage_type == "claim_started",
+        ),
+    )
+    return len(login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids)


 def _default_period_end() -> date:
@@ -127,56 +134,6 @@ def _event_user_ids(
    )


-def _period_active_user_ids(
-    db: Session,
-    *,
-    start_utc: datetime,
-    end_utc: datetime,
-    period_from: date,
-    period_to: date,
-) -> set[int]:
-    """区间去重活跃用户 id 集合:登录(last_login_at)+ 开始比价(real_compare_start)+
-    开始领券(real_coupon_start / claim_started)。
-
-    user / analytics_event 用 UTC aware 边界 [start_utc, end_utc);coupon_prompt_engagement
-    的 engage_date 是北京自然日 date 列,用 [period_from, period_to] 闭区间。今日 / 历史 / 多天通用。
-    """
-    login_user_ids = _id_set(
-        db,
-        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc),
-    )
-    compare_start_user_ids = _event_user_ids(db, (COMPARE_START_EVENT,), start_utc, end_utc)
-    coupon_event_user_ids = _event_user_ids(db, (COUPON_START_EVENT,), start_utc, end_utc)
-    coupon_claim_user_ids = _id_set(
-        db,
-        select(CouponPromptEngagement.user_id).where(
-            CouponPromptEngagement.engage_date >= period_from,
-            CouponPromptEngagement.engage_date <= period_to,
-            CouponPromptEngagement.engage_type == "claim_started",
-        ),
-    )
-    return login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
-
-
-def period_active_dau(db: Session, date_from: date, date_to: date) -> int:
-    """任意北京自然日区间 [date_from, date_to] 的去重活跃用户数。
-
-    与数据大盘 period.users.active 同口径(登录 + 开始比价 + 开始领券);广告收益报表按所选
-    日期区间(含今日)复用,ARPU = 区间预估收益 ÷ 本数。全局口径,不随用户 / 类型 / 场景筛选变化。
-    """
-    period_from, period_to = _normalize_period(date_from, date_to)
-    start_utc, end_utc, _start_local, _end_local = _period_bounds(period_from, period_to)
-    return len(
-        _period_active_user_ids(
-            db,
-            start_utc=start_utc,
-            end_utc=end_utc,
-            period_from=period_from,
-            period_to=period_to,
-        )
-    )
-
-
 def _commission_rate_percent(raw: str | None) -> Decimal | None:
    """美团 commissionRate 原值: "300"=3%, "10"=0.1%;也兼容 "3%"。"""
    if raw is None:
@@ -304,19 +261,31 @@ def dashboard_overview(
    period_new_user_ids = _user_id_set(
        select(User.id).where(User.created_at >= start_utc, User.created_at < end_utc)
    )
-    period_active_user_ids = _period_active_user_ids(
-        db,
-        start_utc=start_utc,
-        end_utc=end_utc,
-        period_from=period_from,
-        period_to=period_to,
+    login_user_ids = _user_id_set(
+        select(User.id).where(User.last_login_at >= start_utc, User.last_login_at < end_utc)
+    )
+    compare_start_user_ids = _event_user_ids(
+        db, (COMPARE_START_EVENT,), start_utc, end_utc
+    )
+    coupon_event_user_ids = _event_user_ids(
+        db, (COUPON_START_EVENT,), start_utc, end_utc
+    )
+    coupon_claim_user_ids = _user_id_set(
+        select(CouponPromptEngagement.user_id).where(
+            CouponPromptEngagement.engage_date >= period_from,
+            CouponPromptEngagement.engage_date <= period_to,
+            CouponPromptEngagement.engage_type == "claim_started",
+        )
+    )
+    period_active_user_ids = (
+        login_user_ids | compare_start_user_ids | coupon_event_user_ids | coupon_claim_user_ids
+    )
+    period_retained_new_user_ids = period_new_user_ids & period_active_user_ids
+    period_retention_rate = (
+        round(len(period_retained_new_user_ids) / len(period_new_user_ids), 4)
+        if period_new_user_ids
+        else None
    )
-    # 留存口径(2026-07-05 产品改):次日留存——窗口内每天 D,取 **D-1 日(前日)新增**用户,
-    # 统计其 D 日活跃(登录/开始比价/开始领券)比例,逐日累加。默认窗口=昨日单天,即
-    # 「前日新增用户的昨日留存」。原口径(窗口内新增∩窗口内活跃)在单日窗口下≈100% 无意义
-    # (注册即登录,当天新增必然当天活跃)。逐日 cohort 在下方 trend 循环内顺带累计。
-    retention_cohort_total = 0
-    retention_retained_total = 0
    trend_points: list[dict] = []
    for cur_date in _date_range(period_from, period_to):
        day_start_utc, day_end_utc, day_start_local, day_end_local = _period_bounds(
@@ -326,26 +295,33 @@ def dashboard_overview(
            ComparisonRecord.created_at >= day_start_local,
            ComparisonRecord.created_at < day_end_local,
        )
-        daily_active_user_ids = _period_active_user_ids(
-            db,
-            start_utc=day_start_utc,
-            end_utc=day_end_utc,
-            period_from=cur_date,
-            period_to=cur_date,
-        )
-        # 次日留存:cohort = 前一日(D-1)新增用户,留存 = 其中当日(D)活跃者(口径见上)。
-        cohort_ids = _user_id_set(
+        daily_login_user_ids = _user_id_set(
            select(User.id).where(
-                User.created_at >= day_start_utc - timedelta(days=1),
-                User.created_at < day_end_utc - timedelta(days=1),
+                User.last_login_at >= day_start_utc,
+                User.last_login_at < day_end_utc,
+            )
+        )
+        daily_compare_start_user_ids = _event_user_ids(
+            db, (COMPARE_START_EVENT,), day_start_utc, day_end_utc
+        )
+        daily_coupon_event_user_ids = _event_user_ids(
+            db, (COUPON_START_EVENT,), day_start_utc, day_end_utc
+        )
+        daily_coupon_claim_user_ids = _user_id_set(
+            select(CouponPromptEngagement.user_id).where(
+                CouponPromptEngagement.engage_date == cur_date,
+                CouponPromptEngagement.engage_type == "claim_started",
            )
        )
-        retention_cohort_total += len(cohort_ids)
-        retention_retained_total += len(cohort_ids & daily_active_user_ids)
        trend_points.append(
            {
                "date": cur_date,
-                "active_users": len(daily_active_user_ids),
+                "active_users": len(
+                    daily_login_user_ids
+                    | daily_compare_start_user_ids
+                    | daily_coupon_event_user_ids
+                    | daily_coupon_claim_user_ids
+                ),
                "new_users": _count(
                    User,
                    User.created_at >= day_start_utc,
@@ -354,11 +330,6 @@ def dashboard_overview(
                "comparisons": _count(ComparisonRecord, *daily_comparison_conds),
            }
        )
-    period_retention_rate = (
-        round(retention_retained_total / retention_cohort_total, 4)
-        if retention_cohort_total
-        else None
-    )

    period_coin_conds = (
        CoinTransaction.created_at >= start_local,
@@ -368,7 +339,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 +361,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,
@@ -456,98 +413,6 @@ def dashboard_overview(
        else None
    )

-    # ===== 领券核心数据(2026-07-05 产品新增)=====
-    # 数据源:coupon_session(一次领券一行,started_date 北京自然日)+ coupon_claim_record
-    # (一券/点位一天一条终态,claim_date 北京自然日)。点位与 session 不按 trace_id 关联——
-    # record_claims 更新路径不覆盖 trace_id(同设备同券同日重跑归第一次的 trace),按
-    # (device_id, 自然日) 桶关联才可靠;同桶多次发起共享同一份点位终态。
-    period_coupon_sessions = db.execute(
-        select(
-            CouponSession.device_id,
-            CouponSession.started_date,
-            CouponSession.status,
-            CouponSession.elapsed_ms,
-        ).where(
-            CouponSession.started_date >= period_from,
-            CouponSession.started_date <= period_to,
-            # 只统计正式环境,同「领券数据」页默认口径(防 debug 包调试数据串台;
-            # 命中 ix_coupon_session_date_env)。点位表无 app_env 列,但点位指标只经
-            # 下方 prod session 触达的 (device, 日) 桶进入统计,随之收敛到 prod。
-            CouponSession.app_env == "prod",
-        )
-    ).all()
-    coupon_started = len(period_coupon_sessions)
-    coupon_completed_elapsed = sorted(
-        s.elapsed_ms
-        for s in period_coupon_sessions
-        if s.status == "completed" and s.elapsed_ms is not None
-    )
-    # 点位桶:(device, 日) → (点位总数, 成功点位数)。成功口径与「我的」页累计领券一致
-    # (sum_claimed_count,2026-06-15 产品定):success + already_claimed(已领过=持有券)都算成功。
-    point_buckets: dict[tuple[str, date], tuple[int, int]] = {
-        (dev, d): (int(total), int(succ or 0))
-        for dev, d, total, succ in db.execute(
-            select(
-                CouponClaimRecord.device_id,
-                CouponClaimRecord.claim_date,
-                func.count(),
-                func.sum(
-                    case(
-                        (CouponClaimRecord.status.in_(("success", "already_claimed")), 1),
-                        else_=0,
-                    )
-                ),
-            )
-            .where(
-                CouponClaimRecord.claim_date >= period_from,
-                # 上界放宽一天:跨零点场次(23:5x 发起)的点位 claim_date 落在发起日+1,
-                # 桶只经下方 session 触达的键参与计数,放宽不会引入无关数据。
-                CouponClaimRecord.claim_date <= period_to + timedelta(days=1),
-            )
-            .group_by(CouponClaimRecord.device_id, CouponClaimRecord.claim_date)
-        ).all()
-    }
-    # 全部领成功的次数:completed 且其 (device, 日) 桶内点位全部成功(桶为空不算)。
-    coupon_all_success = 0
-    completed_bucket_totals: list[int] = []
-    session_bucket_keys: set[tuple[str, date]] = set()
-    for s in period_coupon_sessions:
-        key = (s.device_id, s.started_date)
-        if key not in point_buckets:
-            # 跨零点回退:发起日桶不存在(点位终态全部落在次日)时取 (device, 发起日+1)。
-            # 仅在发起日桶完全缺失时回退,避免抢占该设备次日 session 自己的桶。
-            next_key = (s.device_id, s.started_date + timedelta(days=1))
-            if next_key in point_buckets:
-                key = next_key
-        bucket = point_buckets.get(key)
-        if bucket is not None:
-            session_bucket_keys.add(key)
-        if s.status != "completed" or bucket is None:
-            continue
-        total, succ = bucket
-        completed_bucket_totals.append(total)
-        if total > 0 and succ == total:
-            coupon_all_success += 1
-    # 每次发起的应领点位数:取「完成过的领券」实际点位数的众数(done 帧会给所有点位终态,
-    # 完成场的点位数=当前配置的全量点位数;数据自校准,配置改点位数无需改代码)。本期无完成场
-    # 时给不出,点位成功率置空。
-    coupon_points_per_session = (
-        Counter(completed_bucket_totals).most_common(1)[0][0]
-        if completed_bucket_totals
-        else None
-    )
-    # 成功点位数:本期 session 触达过的 (device, 日) 桶内成功点位之和(桶级去重,同桶重试不重复计)。
-    coupon_point_success = sum(point_buckets[k][1] for k in session_bucket_keys)
-    # 点位成功率 = 成功点位数 / (发起数 × 应领点位数):中途退出未跑到的点位不产生记录,
-    # 但发起数×点位数把它们计入分母 → 视为失败,符合产品口径;重试会拉低该率(分母按次数计)。
-    coupon_point_success_rate = (
-        round(
-            min(1.0, coupon_point_success / (coupon_started * coupon_points_per_session)), 4
-        )
-        if coupon_started and coupon_points_per_session
-        else None
-    )
-
    return {
        "users": {
            "total": _count(User),
@@ -563,7 +428,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,
@@ -611,13 +476,11 @@ def dashboard_overview(
            "users": {
                "new": len(period_new_user_ids),
                "active": len(period_active_user_ids),
-                "retained_new_users": retention_retained_total,
-                "retention_cohort": retention_cohort_total,
+                "retained_new_users": len(period_retained_new_user_ids),
                "retention_rate": period_retention_rate,
                "retention_note": (
-                    "次日留存:窗口内每天取前一日新增用户,统计其当日活跃"
-                    "(登录/开始比价/开始领券,按用户去重)比例,逐日累加;"
-                    "默认窗口=昨日,即前日新增用户的昨日留存"
+                    "口径:登录(last_login_at)+开始比价(real_compare_start)+"
+                    "开始领券(real_coupon_start/claim_started),按用户去重"
                ),
            },
            "comparison": {
@@ -628,17 +491,6 @@ def dashboard_overview(
                "average_duration_ms": period_avg_duration_ms,
                "average_saved_cents": period_avg_saved_cents,
            },
-            "coupon": {
-                "started": coupon_started,
-                "all_success": coupon_all_success,
-                "success_rate": (
-                    round(coupon_all_success / coupon_started, 4) if coupon_started else None
-                ),
-                "point_success": coupon_point_success,
-                "points_per_session": coupon_points_per_session,
-                "point_success_rate": coupon_point_success_rate,
-                "median_elapsed_ms": _percentile(coupon_completed_elapsed, 50),
-            },
            "coins": {
                "granted_total": _sum(CoinTransaction.amount, *period_coin_conds),
                "reward_video_coin_total": period_reward_video_coin_total,
@@ -91,7 +91,6 @@ def get_ad_revenue_report(
        daily=[AdRevenueDaily(**d) for d in result["daily"]],
        hourly=[AdRevenueHourly(**h) for h in result["hourly"]],
        type_stats={k: AdRevenueTypeStat(**v) for k, v in result["type_stats"].items()},
-        scene_stats={k: AdRevenueTypeStat(**v) for k, v in result["scene_stats"].items()},
        dau=result["dau"],
        total=result["total"],
        truncated=result["truncated"],
@@ -5,8 +5,6 @@ from fastapi import APIRouter, Depends, HTTPException, Request

 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
-from app.admin.permissions import CUSTOM_ROLE, SUPER_ADMIN_ROLE, sanitize_pages
-from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.admin import AdminCreateRequest, AdminUpdateRequest
 from app.admin.schemas.auth import AdminOut
@@ -25,31 +23,9 @@ 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):
-        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 专属)")
+@router.get("", response_model=list[AdminOut], summary="管理员列表")
 def list_admins(db: AdminDb) -> list[AdminOut]:
-    out: list[AdminOut] = []
-    for a in admin_repo.list_admins(db):
-        item = AdminOut.model_validate(a)
-        item.password = a.plain_password  # 明文:仅本 super_admin 专属路由下发,供权限管理页复看
-        out.append(item)
-    return out
+    return [AdminOut.model_validate(a) for a in admin_repo.list_admins(db)]


@router.post("", response_model=AdminOut, summary="创建管理员")
@@ -58,17 +34,12 @@ def create_admin(
 ) -> AdminOut:
    if admin_repo.get_by_username(db, body.username) is not None:
        raise HTTPException(status_code=409, detail="用户名已存在")
-    _validate_role(db, body.role)
-    override = _clean_override(body.role, body.pages_override)
    new = admin_repo.create_admin(
-        db, username=body.username, password=body.password, role=body.role,
-        plain_password=body.password,  # UI 建的账号留存明文,供权限管理页复看
-        pages_override=override,
+        db, username=body.username, password=body.password, role=body.role
    )
    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)

@@ -96,12 +67,8 @@ def update_admin(
    if demotes_super and _active_super_count(db) <= 1:
        raise HTTPException(status_code=400, detail="不能降级/禁用最后一个超级管理员")

-    if body.role is not None:
-        _validate_role(db, body.role)
-
    changes: dict = {}
-    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:
@@ -110,18 +77,6 @@ def update_admin(
    if body.password is not None:
        changes["password"] = "reset"
        target.password_hash = hash_password(body.password)
-        target.plain_password = body.password  # 同步留存明文,权限管理页复看保持一致
-
-    # 自定义可见页:按「最终角色」(target.role,已应用完角色变更)决定该存什么。
-    # - 切到/维持 custom 且传了 pages_override → 用勾选集;切到 custom 没传 → 清成空列表。
-    # - 切回普通角色 → 清空 override(_clean_override 返回 None)。
-    # - 角色没变、只传 pages_override(编辑现有 custom 用户的勾选)→ 也更新。
-    if role_changed or body.pages_override is not None:
-        new_override = _clean_override(target.role, body.pages_override)
-        if new_override != target.pages_override:
-            changes["pages_override"] = {"before": target.pages_override, "after": new_override}
-            target.pages_override = new_override
-
    if not changes:
        raise HTTPException(status_code=400, detail="无任何变更字段")
    db.commit()
@@ -131,27 +86,3 @@ def update_admin(
        detail=changes, ip=get_client_ip(request), commit=True,
    )
    return AdminOut.model_validate(target)
-
-
-@router.delete("/{admin_id}", summary="删除管理员(带审计)")
-def delete_admin(admin_id: int, request: Request, admin: CurrentAdmin, db: AdminDb) -> dict:
-    target = admin_repo.get_by_id(db, admin_id)
-    if target is None:
-        raise HTTPException(status_code=404, detail="管理员不存在")
-    if admin_id == admin.id:
-        raise HTTPException(status_code=400, detail="不能删除自己")
-    # 防自锁:删掉某个 active super_admin 前,确认后仍至少剩 1 个,否则进「零可用超管」死局。
-    if (
-        target.role == "super_admin"
-        and target.status == "active"
-        and _active_super_count(db) <= 1
-    ):
-        raise HTTPException(status_code=400, detail="不能删除最后一个超级管理员")
-    username = target.username
-    db.delete(target)
-    db.commit()
-    write_audit(
-        db, admin, action="admin.delete", target_type="admin", target_id=admin_id,
-        detail={"username": username, "role": target.role}, ip=get_client_ip(request), commit=True,
-    )
-    return {"deleted": True}
@@ -6,8 +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
 from app.admin.security import create_admin_token
@@ -19,17 +17,6 @@ logger = logging.getLogger("shagua.admin.auth")
 router = APIRouter(prefix="/admin/api/auth", tags=["admin-auth"])


-def _admin_out_with_pages(admin, db: AdminDb) -> AdminOut:  # noqa: ANN001
-    """AdminOut + 有效可见页(前端左侧导航按此过滤)。
-    role=="custom" → 用这个人的 pages_override(按人自定义,过滤悬空 key);其余走角色解析。"""
-    out = AdminOut.model_validate(admin)
-    if admin.role == CUSTOM_ROLE:
-        out.pages = sanitize_pages(admin.pages_override)
-    else:
-        out.pages = role_repo.effective_pages_of(db, admin.role)
-    return out
-
-
@router.post(
    "/login",
    response_model=AdminLoginResponse,
@@ -52,10 +39,10 @@ def login(req: AdminLoginRequest, db: AdminDb) -> AdminLoginResponse:
    return AdminLoginResponse(
        access_token=token,
        expires_in=expires_in,
-        admin=_admin_out_with_pages(admin, db),
+        admin=AdminOut.model_validate(admin),
    )


-@router.get("/me", response_model=AdminOut, summary="当前管理员(含有效可见页)")
-def me(admin: CurrentAdmin, db: AdminDb) -> AdminOut:
-    return _admin_out_with_pages(admin, db)
+@router.get("/me", response_model=AdminOut, summary="当前管理员")
+def me(admin: CurrentAdmin) -> AdminOut:
+    return AdminOut.model_validate(admin)
@@ -32,15 +32,12 @@ def list_comparison_records(
    phone: Annotated[str | None, Query(description="手机号前缀")] = None,
    status: Annotated[str | None, Query(pattern="^(success|failed|cancelled)$")] = None,
    business_type: Annotated[str | None, Query()] = None,
-    store: Annotated[str | None, Query(description="店名子串模糊匹配")] = None,
-    product: Annotated[str | None, Query(description="商品名子串模糊匹配")] = None,
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
    cursor: Annotated[int | None, Query()] = None,
 ) -> CursorPage[AdminComparisonListItem]:
    items, next_cursor, total = queries.list_comparison_records(
        db, user_id=user_id, phone=phone, status=status,
-        business_type=business_type, store=store, product=product,
-        limit=limit, cursor=cursor,
+        business_type=business_type, limit=limit, cursor=cursor,
    )
    return CursorPage(
        items=[AdminComparisonListItem.model_validate(r) for r in items],
@@ -55,14 +55,9 @@ def _item(db, key: str) -> ConfigItemOut:
    raise HTTPException(status_code=404, detail="未知配置项")


-@router.get("", response_model=list[ConfigItemOut], summary="所有可配项 + 当前值(不含 hidden)")
+@router.get("", response_model=list[ConfigItemOut], summary="所有可配项 + 当前值")
 def list_config(db: AdminDb) -> list[ConfigItemOut]:
-    # hidden 项(已下线/由专用页管理,如福利页任务·里程碑·看广告调参、首页轮播数据源)不在本页渲染。
-    return [
-        ConfigItemOut(**item)
-        for item in app_config.list_all(db)
-        if not CONFIG_DEFS[item["key"]].get("hidden")
-    ]
+    return [ConfigItemOut(**item) for item in app_config.list_all(db)]


@router.patch("/{key}", response_model=ConfigItemOut, summary="改某项配置(带审计)")
@@ -8,7 +8,6 @@ from __future__ import annotations
 from typing import Annotated

 from fastapi import APIRouter, Depends, HTTPException, Query, Request
-from pydantic import BaseModel

 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
@@ -19,17 +18,11 @@ from app.admin.schemas.ops_marquee_seed import (
    OpsMarqueeSeedCreate,
    OpsMarqueeSeedOut,
    OpsMarqueeSeedUpdate,
-    OpsRealRecordItem,
-    OpsRealRecordsOut,
    OpsSavingsFeedPreviewOut,
 )
 from app.models.admin import AdminUser
 from app.models.ops_marquee_seed import OpsMarqueeSeed
-from app.repositories import app_config, ops_marquee
-
-
-class MarqueeModeUpdate(BaseModel):
-    mode: str  # mixed / real / seed
+from app.repositories import ops_marquee

 router = APIRouter(
    prefix="/admin/api/marquee-seeds",
@@ -59,58 +52,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)
-
-
-# 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。
-@router.get("/mode", summary="首页轮播数据源模式(mixed/real/seed)")
-def get_feed_mode(db: AdminDb) -> dict:
-    """当前轮播取数模式:mixed=真实优先+种子补位(默认)/ real=只真实 / seed=只种子·合成。"""
-    return {"mode": ops_marquee.get_feed_mode(db)}
-
-
-@router.patch("/mode", summary="改首页轮播数据源模式(带审计)")
-def set_feed_mode(
-    body: MarqueeModeUpdate,
-    request: Request,
-    admin: Annotated[AdminUser, Depends(require_role("operator"))],
-    db: AdminDb,
-) -> dict:
-    if body.mode not in ops_marquee.FEED_MODES:
-        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
-    before = ops_marquee.get_feed_mode(db)
-    app_config.set_value(db, "marquee_feed_mode", body.mode, admin_id=admin.id, commit=False)
-    write_audit(
-        db, admin, action="ops_marquee_seed.set_mode", target_type="config",
-        target_id="marquee_feed_mode", detail={"before": before, "after": body.mode},
-        ip=get_client_ip(request), commit=False,
-    )
-    db.commit()
-    return {"mode": body.mode}
+    """返回客户端实际会看到的 feed(真实记录会插队、种子随机抽取/金额随机/名字合成),供运营对效果。"""
+    return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit))


@router.post("", response_model=OpsMarqueeSeedOut, summary="新增轮播种子(带审计)")
@@ -1,129 +0,0 @@
-"""admin RBAC 角色管理(仅 super_admin):列角色 / 权限目录 / 增删改角色。均写审计。
-
-角色 = 一组「可见页面」(见 app/admin/permissions.py)。角色登录后台后左侧只展示其 pages 对应导航项。
-只有 super_admin(内建全权角色)能进本组端点(dependencies=require_role() 无参 = 仅 super_admin)。
-"""
-from __future__ import annotations
-
-from fastapi import APIRouter, Depends, HTTPException, Request
-from sqlalchemy import func, select
-
-from app.admin.audit import write_audit
-from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
-from app.admin.permissions import (
-    PERMISSION_CATALOG,
-    SUPER_ADMIN_ROLE,
-    effective_pages,
-    sanitize_pages,
-)
-from app.admin.repositories import admin_role as role_repo
-from app.admin.schemas.role import (
-    PermissionGroup,
-    RoleCreateRequest,
-    RoleOut,
-    RoleUpdateRequest,
-)
-from app.models.admin import AdminUser
-from app.models.admin_role import AdminRole
-
-router = APIRouter(
-    prefix="/admin/api/roles",
-    tags=["admin-roles"],
-    dependencies=[Depends(require_role())],  # 无参 = 仅 super_admin
-)
-
-
-def _usage_counts(db: AdminDb) -> dict[str, int]:
-    rows = db.execute(
-        select(AdminUser.role, func.count(AdminUser.id)).group_by(AdminUser.role)
-    ).all()
-    return {r: c for r, c in rows}
-
-
-def _to_out(role: AdminRole, usage: dict[str, int]) -> RoleOut:
-    return RoleOut(
-        id=role.id,
-        name=role.name,
-        label=role.label or role.name,
-        pages=effective_pages(role.name, role.pages),
-        is_builtin=role.is_builtin,
-        in_use=usage.get(role.name, 0),
-    )
-
-
-@router.get("", response_model=list[RoleOut], summary="角色列表(含可见页 + 使用数)")
-def list_roles(db: AdminDb) -> list[RoleOut]:
-    usage = _usage_counts(db)
-    return [_to_out(r, usage) for r in role_repo.list_roles(db)]
-
-
-@router.get("/catalog", response_model=list[PermissionGroup], summary="页面权限目录(分组)")
-def get_catalog() -> list[PermissionGroup]:
-    return [PermissionGroup(**g) for g in PERMISSION_CATALOG]
-
-
-@router.post("", response_model=RoleOut, summary="新增角色(带审计)")
-def create_role(
-    body: RoleCreateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
-) -> RoleOut:
-    name = body.name.strip()
-    if not name:
-        raise HTTPException(status_code=400, detail="角色名称不能为空")
-    if name == SUPER_ADMIN_ROLE:
-        raise HTTPException(status_code=400, detail="super_admin 为内建角色,不能新建")
-    if role_repo.get_role(db, name) is not None:
-        raise HTTPException(status_code=409, detail="角色名称已存在")
-    # 自定义角色:name(key)= label = 输入名称
-    role = role_repo.create_role(db, name=name, label=name, pages=body.pages)
-    write_audit(
-        db, admin, action="role.create", target_type="role", target_id=str(role.id),
-        detail={"name": name, "pages": role.pages}, ip=get_client_ip(request), commit=True,
-    )
-    return _to_out(role, _usage_counts(db))
-
-
-@router.patch("/{role_id}", response_model=RoleOut, summary="改角色(展示名/可见页,带审计)")
-def update_role(
-    role_id: int, body: RoleUpdateRequest, request: Request, admin: CurrentAdmin, db: AdminDb
-) -> RoleOut:
-    role = db.get(AdminRole, role_id)
-    if role is None:
-        raise HTTPException(status_code=404, detail="角色不存在")
-    if role.is_builtin:
-        raise HTTPException(status_code=400, detail="内建角色「管理员」不可编辑")
-
-    new_label = body.label.strip() if body.label is not None else None
-    changes: dict = {}
-    if new_label and new_label != role.label:
-        changes["label"] = {"before": role.label, "after": new_label}
-    if body.pages is not None:
-        changes["pages"] = {"before": role.pages, "after": sanitize_pages(body.pages)}
-    if not changes:
-        raise HTTPException(status_code=400, detail="无任何变更字段")
-
-    # 只改展示名 + 可见页;key(name)不可变,故无需级联 admin_user.role
-    role_repo.update_role(db, role, label=new_label, pages=body.pages)
-    write_audit(
-        db, admin, action="role.update", target_type="role", target_id=str(role_id),
-        detail=changes, ip=get_client_ip(request), commit=True,
-    )
-    return _to_out(role, _usage_counts(db))
-
-
-@router.delete("/{role_id}", summary="删角色(带审计;内建/在用不可删)")
-def delete_role(role_id: int, request: Request, admin: CurrentAdmin, db: AdminDb) -> dict:
-    role = db.get(AdminRole, role_id)
-    if role is None:
-        raise HTTPException(status_code=404, detail="角色不存在")
-    if role.is_builtin:
-        raise HTTPException(status_code=400, detail="内建角色不可删除")
-    used = _usage_counts(db).get(role.name, 0)
-    if used > 0:
-        raise HTTPException(status_code=400, detail=f"该角色仍有 {used} 名管理员在用,请先改派再删")
-    name = role.name
-    role_repo.delete_role(db, role)
-    write_audit(
-        db, admin, action="role.delete", target_type="role", target_id=str(role_id),
-        detail={"name": name}, ip=get_client_ip(request), commit=True,
-    )
-    return {"deleted": True}
@@ -42,12 +42,7 @@ def list_users(
    created_to: Annotated[datetime | None, Query()] = None,
    last_login_from: Annotated[datetime | None, Query()] = None,
    last_login_to: Annotated[datetime | None, Query()] = None,
-    # 最近活跃(登录/发起比价/发起领券取最大,见 queries._last_active_expr)筛选与排序
-    last_active_from: Annotated[datetime | None, Query()] = None,
-    last_active_to: Annotated[datetime | None, Query()] = None,
-    sort_by: Annotated[
-        str, Query(pattern="^(id|created_at|last_login_at|last_active_at)$")
-    ] = "id",
+    sort_by: Annotated[str, Query(pattern="^(id|created_at|last_login_at)$")] = "id",
    sort_order: Annotated[str, Query(pattern="^(asc|desc)$")] = "desc",
    limit: Annotated[int, Query(ge=1, le=100)] = 20,
    cursor: Annotated[int | None, Query()] = None,
@@ -56,7 +51,6 @@ def list_users(
        db, phone=phone, register_channel=register_channel, status=status,
        nickname=nickname, created_from=created_from, created_to=created_to,
        last_login_from=last_login_from, last_login_to=last_login_to,
-        last_active_from=last_active_from, last_active_to=last_active_to,
        sort_by=sort_by, sort_order=sort_order, limit=limit, cursor=cursor,
    )
    return CursorPage(
@@ -136,16 +136,9 @@ class AdRevenueReportOut(BaseModel):
        default_factory=dict,
        description="按广告类型(ad_type)小计 {ad_type: {impressions, revenue_yuan}};前端取 draw / reward_video 做分类大盘",
    )
-    scene_stats: dict[str, AdRevenueTypeStat] = Field(
-        default_factory=dict,
-        description="按信息流场景(feed_scene)小计 {comparison/coupon/welfare: {impressions, revenue_yuan}};"
-        "全量统计(不受分页截断),供数据大盘「领券广告 / 比价广告」卡;feed_scene 为空的事件不计入",
-    )
    dau: int | None = Field(
        None,
-        description="所选日期区间的去重活跃用户数(口径同数据大盘 period.users.active:登录 + 开始比价 + "
-        "开始领券)。按 date_from~date_to 区间统计,含今日、近 7 天、近 30 天等任意区间;全局口径,"
-        "不随 user_id / ad_type / feed_scene / app_env 筛选变化",
+        description="今日活跃用户数(复用大盘口径,last_login_at);**仅查询=今日单天时有值**,历史/多天为 null",
    )
    total: int = Field(..., description="广告事件总数(全量,不受分页影响;= 当前筛选下的分页总条数)")
    truncated: bool = Field(..., description="当前页之后是否还有更多事件(len(events) > offset + limit)")
@@ -6,25 +6,21 @@ from typing import Literal

 from pydantic import BaseModel, ConfigDict, Field

-# 角色不再硬编码枚举:改为任意角色名(自定义角色由 admin_role 表管理),存在性在路由层校验。
+_Role = Literal["super_admin", "finance", "operator"]


 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
+    role: _Role = "operator"


 class AdminUpdateRequest(BaseModel):
-    """改角色 / 启用禁用 / 重置密码 / 自定义可见页,字段都可选(只改传了的)。"""
+    """改角色 / 启用禁用 / 重置密码,字段都可选(只改传了的)。"""

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


 class AdminLoginResponse(BaseModel):
@@ -23,7 +23,6 @@ class AdminComparisonListItem(BaseModel):
    status: str
    information: str | None = None
    store_name: str | None = None
-    product_names: str | None = None   # 下单商品名派生串(顿号分隔;「商品」列展示 + 商品搜索)
    source_platform_name: str | None = None
    best_platform_name: str | None = None
    source_price_cents: int | None = None
@@ -43,10 +43,7 @@ class DashboardComparison(BaseModel):
 class DashboardPeriodUsers(BaseModel):
    new: int
    active: int
-    # 次日留存(2026-07-05 起):retained_new_users = 窗口内逐日「前一日新增且当日活跃」用户数之和,
-    # retention_cohort = 对应的前一日新增基数之和,retention_rate = 两者之比。
    retained_new_users: int
-    retention_cohort: int = 0
    retention_rate: float | None = None
    retention_note: str

@@ -60,24 +57,6 @@ class DashboardPeriodComparison(BaseModel):
    average_saved_cents: int | None = None


-class DashboardPeriodCoupon(BaseModel):
-    """领券核心数据(2026-07-05 产品新增)。点位=一张券(coupon_claim_record 一天一条终态);
-    成功口径 success+already_claimed(与「我的」页累计领券一致)。"""
-
-    started: int = 0
-    # 全部领成功的次数:completed 且当日该设备全部点位成功
-    all_success: int = 0
-    success_rate: float | None = None
-    # 本期 session 触达的点位中成功的条数(同设备同日去重)
-    point_success: int = 0
-    # 每次发起的应领点位数(本期完成场实际点位数的众数;无完成场为空)
-    points_per_session: int | None = None
-    # 点位成功率 = point_success / (started × points_per_session);未跑到的点位计入分母视为失败
-    point_success_rate: float | None = None
-    # 耗时中位数(仅 completed 的 elapsed_ms,同「领券数据」页口径)
-    median_elapsed_ms: int | None = None
-
-
 class DashboardPeriodCoins(BaseModel):
    granted_total: int
    reward_video_coin_total: int = 0
@@ -106,7 +85,6 @@ class DashboardPeriod(BaseModel):
    date_to: date
    users: DashboardPeriodUsers
    comparison: DashboardPeriodComparison
-    coupon: DashboardPeriodCoupon = DashboardPeriodCoupon()
    coins: DashboardPeriodCoins
    cash: DashboardPeriodCash
    trend: list[DashboardTrendPoint] = []
@@ -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                # 满足条件的真实记录总数(算页数用)
@@ -1,35 +0,0 @@
-"""admin RBAC 角色 + 权限目录 schemas。"""
-from __future__ import annotations
-
-from pydantic import BaseModel, Field
-
-
-class PermissionPage(BaseModel):
-    key: str
-    label: str
-
-
-class PermissionGroup(BaseModel):
-    group: str
-    pages: list[PermissionPage]
-
-
-class RoleOut(BaseModel):
-    id: int
-    name: str             # 角色 key(承重,不可变)
-    label: str            # 展示名(UI 显示)
-    pages: list[str]      # 有效可见页 key(super_admin = 全部页)
-    is_builtin: bool      # 内建角色(super_admin):不可编辑/删除
-    in_use: int           # 使用该角色的管理员数(删除前端提示 / 拦截用)
-
-
-class RoleCreateRequest(BaseModel):
-    # 新增自定义角色:name 即用户输入的名称(同时作 key 与展示名)
-    name: str = Field(..., min_length=1, max_length=32)
-    pages: list[str] = Field(default_factory=list)
-
-
-class RoleUpdateRequest(BaseModel):
-    # 只改展示名 + 可见页;key 不可变
-    label: str | None = Field(None, min_length=1, max_length=32)
-    pages: list[str] | None = None
@@ -20,9 +20,6 @@ class AdminUserListItem(BaseModel):
    wechat_nickname: str | None = None
    created_at: datetime
    last_login_at: datetime
-    # 最近活跃 = max(最近登录, 最近发起比价, 最近发起领券);列表页由 queries._attach_last_active
-    # 瞬态挂上。其他复用本 schema 的入口(用户 360 等)没挂该属性 → None(前端显示 '-')。
-    last_active_at: datetime | None = None


 class AdminUserOverview(BaseModel):
@@ -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):
@@ -54,29 +54,5 @@ def get_current_user(
    return user


-def get_current_user_optional(
-    credentials: Annotated[HTTPAuthorizationCredentials | None, Depends(_bearer)],
-    db: Annotated[Session, Depends(get_db)],
-) -> User | None:
-    """软鉴权:有合法 Bearer 就返回 user,否则(无 header / 无效 token / 用户禁用)一律返回
-    None,**不 raise**。
-
-    比价 step / finalize 灰度期用:新客户端带 JWT → 拿到 user_id 绑定 harvest 行;
-    老客户端(不带 JWT)→ None,harvest 行 user_id 暂空,由其后续 /compare/record 上报补齐。
-    等新版覆盖率够高,再把这几条端点从软鉴权收紧成硬 get_current_user。
-    """
-    if credentials is None or credentials.scheme.lower() != "bearer":
-        return None
-    try:
-        payload = decode_token(credentials.credentials, expected_type="access")
-        user = db.get(User, int(payload["sub"]))
-    except (TokenError, KeyError, ValueError, TypeError):
-        return None
-    if user is None or user.status != "active":
-        return None
-    return user
-
-
 CurrentUser = Annotated[User, Depends(get_current_user)]
-OptionalUser = Annotated[User | None, Depends(get_current_user_optional)]
 DbSession = Annotated[Session, Depends(get_db)]
@@ -12,11 +12,11 @@ from __future__ import annotations

 import logging

-from fastapi import APIRouter, HTTPException, Request, status
+from fastapi import APIRouter, Depends, HTTPException, Request, status

 from app.api.deps import CurrentUser, DbSession
 from app.core import test_account
-from app.core.ratelimit import enforce_rate_limit
+from app.core.ratelimit import enforce_rate_limit, rate_limit
 from app.core.security import TokenError, decode_token, issue_token_pair
 from app.integrations.jiguang import JiguangError, mask_phone, verify_and_get_phone
 from app.integrations.sms import SmsError, send_code, verify_code
@@ -41,7 +41,7 @@ router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 # 手机号登录防刷:同一设备(device_id) + 同一 IP 每小时最多的登录尝试次数(成功/失败都计)。
 SMS_LOGIN_MAX_PER_HOUR = 5
 # 发码防刷:同一设备(device_id) + 同一 IP 每小时最多的发码次数。
-# 堵「换手机号绕开单号 60s 冷却」的洞 —— 冷却是单号维度,一机换号能绕开。
+# 堵「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞 —— 那两道是单号维度,一机换号能绕开。
 SMS_SEND_MAX_PER_HOUR_PER_DEVICE = 5


@@ -100,8 +100,8 @@ def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
        return SmsSendResponse(sent=True, mock=True, cooldown_sec=0)

    # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_SEND_MAX_PER_HOUR_PER_DEVICE 次发码。
-    # 补「换手机号绕开单号 60s 冷却」的洞(冷却是单号维度,一机换号能绕);设备维度按机器封顶,
-    # 挡短信轰炸/烧钱。放在真发(send_code)之前 → 超限直接拦下、不真发短信。
+    # 补「换手机号绕开单号 60s 冷却 / 单号每日上限」的洞(那两道是单号维度,一机换号能绕);设备维度按机器封顶,
+    # 挡短信轰炸/烧钱。放在真发(send_code)之前 → 超限直接拦下、不真发短信。与路由上 IP 维度(10次/分钟)互补。
    enforce_rate_limit(
        request,
        scope="sms-send-device",
@@ -125,6 +125,7 @@ def sms_send(req: SmsSendRequest, request: Request) -> SmsSendResponse:
    "/sms/login",
    response_model=TokenWithUser,
    summary="手机号+验证码登录",
+    dependencies=[Depends(rate_limit(20, 60, "sms-login"))],  # 防撞库爆破(另有单码失败次数上限)
 )
 def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWithUser:
    # 测试账号:免验证码登录 + 每日上限 + 每次都走新手引导(详见 app/core/test_account.py)。
@@ -142,7 +143,7 @@ def sms_login(req: SmsLoginRequest, request: Request, db: DbSession) -> TokenWit
        return _login_response(user, onboarding_completed=False, force_onboarding=True)

    # 防刷:同一设备(device_id) + 同一 IP 每小时最多 SMS_LOGIN_MAX_PER_HOUR 次登录尝试。放在验证码校验
-    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破(另有单码失败 SMS_MAX_VERIFY_ATTEMPTS 次即作废兜底)。
+    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破。与路由上 IP 维度的 sms-login 限流(同 IP)互补。
    # ⚠️ 按设备而非手机号 → 一台机器换不同手机号刷登录也受限(防一机狂登多号);device_id 空(老客户端)时
    #    退化为该 IP 下所有空设备聚一桶,仍受限。
    enforce_rate_limit(
@@ -1,114 +1,49 @@
-"""外卖比价业务透传端点 + 后端 harvest 落库。
+"""外卖比价业务透传端点。

-把客户端 POST /api/v1/intent/* 和 /api/v1/price/step 转发给 pricebot,同时**由 app-server
-在透传里直接落库比价记录**(不再靠客户端 POST /compare/record):
-  - 帧0(客户端首帧不带 trace_id)→ app-server 用 uuid 签发 trace_id、注入转发 body、回给
-    客户端;并按 trace_id 建 running 行(harvest_running)。
-  - 最终 done 帧 → 更新成 success/failed + 结果(harvest_done)。发奖不在这里:#113 已把
-    邀请奖口径从「比价」移到「实际下单」(order.py)。
-  - /trace/finalize(用户终止/Phase1 未识别,无 done)→ 更新成 cancelled/failed
-    (harvest_abort,**不降级 success**)。
-trace_url 从 pricebot 响应**顶层 trace_url** 取(pricebot 每帧都带,见其 goal_engine.process_step)。
+把客户端的 POST /api/v1/intent/recognize 和 /api/v1/price/step 请求原样转发给
+pricebot-backend 的 /api/intent/recognize 和 /api/price/step。MVP 阶段**不鉴权**
+(同 coupon/step,见 docs/待办与技术债.md P1:device_id 透传区分设备,待补 JWT +
+device_id↔user_id 绑定后才能做用户级画像)。

-鉴权:软鉴权(OptionalUser)——新客户端带 JWT → 绑 user_id;老客户端不带 → user_id 暂空,
-由其后续 /compare/record 上报补(灰度期两条写路径按 trace_id reconcile,success 不被降级)。
+- Phase 1 /intent/recognize:从源平台(淘宝闪购/美团/京东外卖)购物车页识别店名+菜品+
+  价格,一次性。
+- Phase 2 /price/step:多轮循环,在目标平台复现订单读到手价,直到 done。

-真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口是透传壳 + 落库。
-pricebot 协议文档: pricebot-backend/docs/main/02_api_protocol.md
+真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口只是透传壳。
+电商(ecom)那两个端点 food MVP 暂不需要,以后放开 scene 时再加 /ecom/intent/recognize
+和 /ecom/step 两行即可。
+
+pricebot 协议文档:
+  pricebot-backend/docs/main/02_api_protocol.md
 """
 from __future__ import annotations

 import json
 import logging
-import time
-import uuid
 from typing import Any

 import httpx
 from fastapi import APIRouter, HTTPException, Request, status
-from fastapi.concurrency import run_in_threadpool

-from app.api.deps import OptionalUser
 from app.core.config import settings
-from app.core.logging import trace_id_ctx
 from app.core.pricebot_client import get_pricebot_client
 from app.core.pricebot_router import pick_pricebot
-from app.db.session import SessionLocal
-from app.repositories import comparison as crud_compare

 logger = logging.getLogger("shagua.compare")

 router = APIRouter(prefix="/api/v1", tags=["compare"])


-# ============================================================
-# harvest 落库(阻塞 SQLAlchemy → run_in_threadpool,独立 SessionLocal,不阻塞事件循环;
-# 任何写库异常都吞掉、绝不连累比价透传返回 —— 同 coupon.py 现有 best-effort 写法)。
-# ============================================================
+async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
+    """把请求体原样转发给 pricebot-backend 的 {upstream_path}。

-
-def _harvest_running_blocking(
-    trace_id: str, user_id: int | None, business_type: str,
-    device_id: str | None, device_info: dict | None, trace_url: str | None,
-) -> None:
-    with SessionLocal() as db:
-        crud_compare.harvest_running(
-            db, trace_id=trace_id, user_id=user_id, business_type=business_type,
-            device_id=device_id, device_info=device_info, trace_url=trace_url,
-        )
-    logger.info(
-        "harvest running row (user=%s)", user_id,
-        extra={"phase": "harvest_running", "status": "running", "user_id": user_id},
-    )
-
-
-def _harvest_done_blocking(
-    trace_id: str, user_id: int | None, done_params: dict, business_type: str,
-    device_id: str | None, device_info: dict | None, trace_url: str | None,
-) -> None:
-    with SessionLocal() as db:
-        rec, newly_success = crud_compare.harvest_done(
-            db, trace_id=trace_id, user_id=user_id, done_params=done_params,
-            business_type=business_type, device_id=device_id,
-            device_info=device_info, trace_url=trace_url,
-        )
-        logger.info(
-            "harvest done → %s saved=%s newly=%s", rec.status,
-            rec.saved_amount_cents, newly_success,
-            extra={"phase": "harvest_done", "status": rec.status,
-                   "saved_cents": rec.saved_amount_cents,
-                   "best_platform": rec.best_platform_id, "newly_success": newly_success,
-                   "user_id": user_id},
-        )
-        # 不在此处发邀请奖:#113 已把发奖口径从「比价」移到「实际下单」(order.py),harvest
-        # 只记录比价、不发奖。否则比价先于下单 + try_reward 幂等闸会让奖落在「比价」这步,
-        # 架空 #113 的「下单才发奖」防刷意图(newly_success 仅留作日志观测)。
-
-
-def _harvest_abort_blocking(
-    trace_id: str, status_hint: str, reason: str | None, trace_url: str | None,
-) -> None:
-    with SessionLocal() as db:
-        rec = crud_compare.harvest_abort(
-            db, trace_id=trace_id, status=status_hint, reason=reason, trace_url=trace_url,
-        )
-    logger.info(
-        "harvest abort → %s", (rec.status if rec else "no-row"),
-        extra={"phase": "harvest_abort",
-               "status": (rec.status if rec else None), "reason": reason},
-    )
-
-
-async def _forward(
-    request: Request, upstream_path: str, user, *, harvest_first_frame: bool = True,
-) -> tuple[dict[str, Any], str, dict[str, Any]]:
-    """透传给 pricebot 的 {upstream_path},并 mint trace_id + 首帧建 running 行。
-    返回 (resp_json, trace_id, meta)。
-
-    - 客户端首帧不带 trace_id → app-server 用 uuid 签发、写进转发 body、回填进响应顶层
-      `trace_id`(客户端据此拿到后续帧都带上)。带了(老客户端 / 后续帧)→ 原样用、走原始 bytes 快路。
-    - 仅**本次 mint(=首帧)**建 running 行(idempotent);后续帧不再写库。
+    跟 coupon_step 同款透传壳:不鉴权、不做 schema 校验,仅读 device_id/trace_id/step
+    打日志。比价单帧是大上下文 / 逐帧 LLM,超时用 PRICEBOT_COMPARE_TIMEOUT_SEC(60s,
+    比领券的 30s 长)。
    """
+    # 读原始字节,避免"反序列化→再序列化"的双重 JSON(省 ~一半透传 CPU,让 app-server
+    # 单 worker 也扛得住高并发)。只 json.loads 一次拿 trace_id 做亲和 + 打日志,转发时
+    # 直接发原始 bytes(content=raw),不重新 dumps。
    raw = await request.body()
    try:
        meta = json.loads(raw)
@@ -117,41 +52,26 @@ async def _forward(
    if not isinstance(meta, dict):
        meta = {}

-    trace_id = meta.get("trace_id")
-    minted = False
-    if not trace_id:
-        trace_id = str(uuid.uuid4())
-        meta["trace_id"] = trace_id
-        raw = json.dumps(meta).encode()  # 仅首帧重新序列化(注入 trace_id);后续帧走原始 bytes
-        minted = True
-
-    # 请求级 trace_id 贯穿:此后本请求(含 run_in_threadpool 里的 harvest)每行日志自动带 trace_id
-    trace_id_ctx.set(trace_id)
-
-    base = pick_pricebot(trace_id)
+    # 按 trace_id 一致性 hash 选 pricebot 实例(同一比价的所有帧落同一进程,内存维护 state)
+    base = pick_pricebot(meta.get("trace_id"))
    url = f"{base.rstrip('/')}{upstream_path}"
    timeout = settings.PRICEBOT_COMPARE_TIMEOUT_SEC
-    step = meta.get("step")

    logger.info(
-        "→ pricebot %s step=%s%s", upstream_path, step, " [mint]" if minted else "",
-        extra={"phase": "forward", "endpoint": upstream_path, "step": step,
-               "device_id": meta.get("device_id"), "minted": minted,
-               "query": meta.get("query"), "user_id": (user.id if user else None)},
+        "compare %s device_id=%s trace_id=%s step=%s",
+        upstream_path,
+        meta.get("device_id"),
+        meta.get("trace_id"),
+        meta.get("step"),
    )

-    t0 = time.monotonic()
    try:
        client = get_pricebot_client()
        resp = await client.post(
            url, content=raw, headers={"Content-Type": "application/json"}, timeout=timeout
        )
    except httpx.RequestError as e:
-        logger.error(
-            "← pricebot %s 不可达: %s", upstream_path, e,
-            extra={"phase": "resp", "endpoint": upstream_path, "step": step,
-                   "error": "upstream_unreachable"},
-        )
+        logger.error("[pricebot] request failed: %s", e)
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail=f"pricebot upstream unreachable: {e}",
@@ -159,112 +79,49 @@ async def _forward(

    if resp.status_code >= 500:
        logger.error(
-            "← pricebot %s 5xx=%d", upstream_path, resp.status_code,
-            extra={"phase": "resp", "endpoint": upstream_path, "step": step,
-                   "http_status": resp.status_code, "error": "upstream_5xx"},
+            "[pricebot] 5xx status=%d body=%s",
+            resp.status_code,
+            resp.text[:500],
        )
        raise HTTPException(
            status_code=status.HTTP_502_BAD_GATEWAY,
            detail=f"pricebot upstream returned {resp.status_code}",
        )

-    resp_json = resp.json()
-    cost_ms = int((time.monotonic() - t0) * 1000)
-    if not isinstance(resp_json, dict):
-        return {}, trace_id, meta
-    # 回传 app-server 签发的 trace_id(新客户端首帧据此拿到,后续帧都带上它)
-    resp_json.setdefault("trace_id", trace_id)
-    _action = resp_json.get("action") or {}
-    logger.info(
-        "← pricebot %s cmd=%s cont=%s %dms", upstream_path,
-        _action.get("command"), resp_json.get("continue"), cost_ms,
-        extra={"phase": "resp", "endpoint": upstream_path, "step": step,
-               "command": _action.get("command"), "continue": resp_json.get("continue"),
-               "cost_ms": cost_ms},
-    )
-
-    # 首帧建 running 行(仅本次 mint;老客户端自带 trace_id → 不 mint → 由 done / 其 POST 建行)
-    if minted and harvest_first_frame:
-        try:
-            await run_in_threadpool(
-                _harvest_running_blocking, trace_id,
-                (user.id if user else None), "food",
-                meta.get("device_id"), meta.get("device_info"),
-                resp_json.get("trace_url"),
-            )
-        except Exception as e:  # noqa: BLE001
-            logger.warning("harvest_running failed trace=%s: %s", trace_id, e)
-
-    return resp_json, trace_id, meta
+    return resp.json()


-@router.post("/intent/recognize", summary="外卖比价 Phase 1 意图识别 (透传 + 建 running 行)")
-async def intent_recognize(request: Request, user: OptionalUser) -> dict[str, Any]:
-    resp, _, _ = await _forward(request, "/api/intent/recognize", user)
-    return resp
+@router.post("/intent/recognize", summary="外卖比价 Phase 1 意图识别 (透传到 pricebot)")
+async def intent_recognize(request: Request) -> dict[str, Any]:
+    return await _passthrough(request, "/api/intent/recognize")


-@router.post("/intent/step", summary="外卖比价 Phase 1 多帧意图识别 (透传, 仅淘宝源)")
-async def intent_step(request: Request, user: OptionalUser) -> dict[str, Any]:
-    resp, _, _ = await _forward(request, "/api/intent/step", user)
-    return resp
+@router.post("/intent/step", summary="外卖比价 Phase 1 多帧意图识别 (透传到 pricebot, 仅淘宝源)")
+async def intent_step(request: Request) -> dict[str, Any]:
+    # 多帧版意图识别(展开+滚动采集→提取): 循环调用直到 done(done 帧顶层带
+    # result+calibration)。目前仅淘宝源走这条, 其它源走上面单次 /intent/recognize。
+    return await _passthrough(request, "/api/intent/step")


-@router.post("/intent/precoupon/step", summary="外卖比价 Phase 0 识别前先用券 (透传, 仅美团源)")
-async def intent_precoupon_step(request: Request, user: OptionalUser) -> dict[str, Any]:
-    resp, _, _ = await _forward(request, "/api/intent/precoupon/step", user)
-    return resp
+@router.post(
+    "/intent/precoupon/step",
+    summary="外卖比价 Phase 0 意图识别前先用券 (透传到 pricebot, 仅美团源)",
+)
+async def intent_precoupon_step(request: Request) -> dict[str, Any]:
+    # 美团源平台『意图识别前先用券』多帧循环: 客户端在调 /intent/recognize 之前先循环
+    # 调本端点到 done(continue=false)。订单页底部有『点击使用X红包』就自动选最大免费券
+    # 用上, 已用券/无券则首帧秒过。与 /intent/step 同属 intent 域, 复用同一透传壳。
+    return await _passthrough(request, "/api/intent/precoupon/step")


-@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传 + done 落库)")
-async def price_step(request: Request, user: OptionalUser) -> dict[str, Any]:
-    resp, trace_id, meta = await _forward(request, "/api/price/step", user)
-    # 最终 done 帧(command=done 且 continue=false)→ harvest 更新成终态。
-    # (单平台中途 done 被 pricebot 改写成 wait+continue=true,不会命中这里,同 coupon 语义。)
-    action = resp.get("action") or {}
-    if action.get("command") == "done" and not resp.get("continue", True):
-        done_params = action.get("params") or {}
-        try:
-            await run_in_threadpool(
-                _harvest_done_blocking, trace_id, (user.id if user else None),
-                done_params, "food",
-                meta.get("device_id"), meta.get("device_info"),
-                resp.get("trace_url") or done_params.get("trace_url"),
-            )
-        except Exception as e:  # noqa: BLE001
-            logger.warning("harvest_done failed trace=%s: %s", trace_id, e)
-    return resp
+@router.post("/price/step", summary="外卖比价 Phase 2 步进 (透传到 pricebot)")
+async def price_step(request: Request) -> dict[str, Any]:
+    return await _passthrough(request, "/api/price/step")


-@router.post("/trace/epilogue", summary="比价结果页尾声帧 (透传到 pricebot, 用户视角截图入 trace)")
-async def trace_epilogue(request: Request, user: OptionalUser) -> dict[str, Any]:
-    # App 收到 done、渲染完结果页后,把自己页面的截图(base64)传给 pricebot 存进 trace
-    # 目录并触发重传 —— trace 里补上"用户实际看到的汇总页"(步骤帧只有目标 App 画面)。
-    # body ~几百 KB(截图 base64), 纯透传壳(harvest_first_frame=False:不建行/不落库,
-    # 该 trace 的记录已由 done/finalize 落终态)。#112 原走 _passthrough,合并到 harvest
-    # 分支后统一走 _forward(_passthrough 已并入它)。
-    resp, _, _ = await _forward(
-        request, "/api/trace/epilogue", user, harvest_first_frame=False,
-    )
-    return resp
-
-
-@router.post("/trace/finalize", summary="比价 trace 收尾上云 (透传 + 夭折落库)")
-async def trace_finalize(request: Request, user: OptionalUser) -> dict[str, Any]:
-    # 用户终止 / Phase1 未识别没到 done 帧: pricebot 打包半截上云返回 {trace_url};
-    # app-server 顺手把该 trace 的 running 行更新成夭折终态(**不降级 success**)。
-    # 客户端 finalize body 带 status(cancelled/failed)+ reason;老客户端只带 trace_id →
-    # 默认 cancelled,其后续 /compare/record 上报再补精确态。
-    resp, trace_id, meta = await _forward(
-        request, "/api/trace/finalize", user, harvest_first_frame=False,
-    )
-    try:
-        await run_in_threadpool(
-            _harvest_abort_blocking, trace_id,
-            (meta.get("status") or "cancelled"),
-            (meta.get("reason") or meta.get("information")),
-            (resp.get("trace_url") if isinstance(resp, dict) else None),
-        )
-    except Exception as e:  # noqa: BLE001
-        logger.warning("harvest_abort failed trace=%s: %s", trace_id, e)
-    return resp
+@router.post("/trace/finalize", summary="比价 trace 收尾上云 (透传到 pricebot, 终止/未识别拿 trace_url)")
+async def trace_finalize(request: Request) -> dict[str, Any]:
+    # 用户终止 / Phase1 未识别没走到 done 帧, pricebot 没上云也没回传 trace_url。客户端收尾时
+    # 打这个, _passthrough 按 trace_id 一致性 hash 落到处理这条 trace 的同一 pricebot 进程
+    # (dir_cache 在那, 才能算对 trace 目录), 由后者打包上云返回 {trace_url}。
+    return await _passthrough(request, "/api/trace/finalize")
@@ -1,13 +1,15 @@
-"""比价记录 endpoint(「我的比价记录」+ admin 数据源)。
+"""比价记录 endpoint(「我的比价记录」数据源)。

 路由前缀 `/api/v1/compare`:
-  POST /record         (灰度期兼容)老客户端上报,按 **trace_id** 幂等 + 不降级 success
+  POST /record         上报一次比价结果(幂等:同 user+trace_id 覆盖)
  GET  /records        比价记录列表(游标分页)
  GET  /records/{id}   单条详情(含 raw_payload 全量)

-**均需鉴权**(CurrentUser)。⚠️ 写路径现以 `compare.py` 透传壳的**后端 harvest** 为主
-(帧0 建 running 行 → done/finalize 落终态,新客户端不再 POST);本 POST /record 仅灰度期
-给老客户端用,与 harvest 按 trace_id reconcile。新版覆盖够高后可下线本 POST(阶段3)。
+**均需鉴权**(CurrentUser)——与同文件无关的不鉴权透传 `compare.py` 分开:那个是
+转发壳(MVP 不鉴权),这里是按用户维度落库的业务接口,必须有 user_id。
+
+注:本轮只做 server 端,客户端(android 仓)在 done 帧后调 POST /record 上报的改动
+另起一轮(见 app-server docs/待办与技术债.md P1)。
 """
 from __future__ import annotations

@@ -19,15 +21,16 @@ from app.api.deps import CurrentUser, DbSession
 from app.db.session import SessionLocal
 from app.models.comparison import ComparisonRecord
 from app.repositories import comparison as crud_compare
+from app.repositories import invite as crud_invite
+from app.services.pricebot_llm_calls import fetch_llm_calls
 from app.schemas.compare_record import (
    CompareStatsOut,
    ComparisonRecordCreatedOut,
    ComparisonRecordDetailOut,
    ComparisonRecordIn,
-    ComparisonRecordOut,
    ComparisonRecordPage,
+    ComparisonRecordOut,
 )
-from app.services.pricebot_llm_calls import fetch_llm_calls

 logger = logging.getLogger("shagua.compare_record")

@@ -50,8 +53,18 @@ def report_record(
    # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
    # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
    background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
-    # 注:邀请发奖已从"比价成功"挪到"实际下单"(见 api/v1/order.py report_order)——
-    # 冰拍板:被邀请人完成比价并实际下单才算邀请成功,仅完成比价不再发奖。
+    # 邀请 v2 发奖:被邀请人完成一次【成功】比价 → 给邀请人发邀请奖励金(幂等,只发一次)。
+    # best-effort:发奖异常不影响比价上报本身(rec 已 commit),只 log;邀请人补偿靠后续对账。
+    if rec.status == "success":
+        try:
+            reward = crud_invite.try_reward_on_compare(db, user.id)
+            if reward.status == "granted":
+                logger.info(
+                    "invite compare reward granted inviter=%s invitee=%s cents=%s",
+                    reward.inviter_user_id, user.id, reward.reward_cents,
+                )
+        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞上报
+            logger.warning("invite compare reward failed invitee=%s: %s", user.id, e)
    logger.info(
        "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
        user.id,
@@ -1,14 +1,9 @@
-import logging
-
 from fastapi import APIRouter

 from app.api.deps import CurrentUser, DbSession
-from app.repositories import invite as crud_invite
 from app.repositories import savings as crud_savings
 from app.schemas.order import OrderReportOut, OrderReportRequest

-logger = logging.getLogger("shagua.order")
-
 router = APIRouter(prefix="/api/v1/order", tags=["order"])


@@ -20,20 +15,6 @@ router = APIRouter(prefix="/api/v1/order", tags=["order"])
 def report_order(req: OrderReportRequest, user: CurrentUser, db: DbSession) -> OrderReportOut:
    # 记账唯一真相表是 savings_record(source='compare')。
    rec, duplicated = crud_savings.create_from_report(db, user.id, req)
-    # 邀请 v2 发奖:被邀请人【实际下单】(而非仅完成比价)才给邀请人发邀请奖励金(幂等,只发一次)。
-    # 触发点从"比价成功上报"挪到这里(冰:完成比价并实际下单才算成功)。仅首次真实上报触发,
-    # 重复上报(duplicated)跳过。best-effort:发奖异常不影响订单上报本身(rec 已 commit),只 log;
-    # try_reward_on_compare 自带 compare_reward_granted 幂等闸,漏发靠后续对账补。
-    if not duplicated:
-        try:
-            reward = crud_invite.try_reward_on_compare(db, user.id)
-            if reward.status == "granted":
-                logger.info(
-                    "invite order reward granted inviter=%s invitee=%s cents=%s",
-                    reward.inviter_user_id, user.id, reward.reward_cents,
-                )
-        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞订单上报
-            logger.warning("invite order reward failed invitee=%s: %s", user.id, e)
    return OrderReportOut(
        id=rec.id,
        platform=rec.platform or req.platform,
@@ -69,18 +69,6 @@ def complete_onboarding(
    return OkResponse()


-@router.post("/onboarding/reset", response_model=OkResponse, summary="重置新手引导(删该 设备+账号 完成标记,下次登录重走)")
-def reset_onboarding(
-    req: OnboardingCompleteRequest, user: CurrentUser, db: DbSession
-) -> OkResponse:
-    """删该 (当前账号, device_id) 的引导完成标记 → 下次登录 onboarding_completed=false,客户端重走。
-    与 /onboarding/complete 互逆。device_id 取客户端硬件级 ANDROID_ID(与登录/complete 一致)。
-    幂等:无记录也返回 ok。仅删自己(当前 JWT 用户)这台设备的记录,不影响别的账号/设备。"""
-    deleted = onboarding_repo.delete_completion(db, user_id=user.id, device_id=req.device_id)
-    logger.info("onboarding reset user_id=%d device_len=%d deleted=%d", user.id, len(req.device_id), deleted)
-    return OkResponse()
-
-
@router.get(
    "/onboarding/status",
    response_model=OnboardingStatusResponse,
@@ -81,6 +81,7 @@ class Settings(BaseSettings):
    SMS_SIGN_ID: int = 31729       # 极光短信签名 ID(非机密,可被 .env 覆盖)
    SMS_TEMPLATE_ID: int = 1       # 极光短信模板 ID(变量名 code,有效期 5 分钟)
    SMS_CODE_LENGTH: int = 6       # 验证码位数(本服务生成;前端 code 字段 4-8 位兼容)
+    SMS_DAILY_LIMIT_PER_PHONE: int = 10   # 单手机号每日发送上限(防刷 + 控费)
    SMS_MAX_VERIFY_ATTEMPTS: int = 5      # 单个验证码最多校验失败次数,超过即作废(防爆破)

    # ===== 测试账号(release 包全流程联调用)=====
@@ -11,10 +11,7 @@ from typing import Any

 from app.core import rewards as r

-# type 约定(给前端渲染编辑控件用):int / int_list / dict_str_int / bool / enum
-# hidden=True:仍是合法可配项(业务照常 get_value / admin 可经专用端点读写),但**不在通用
-#   「系统配置」页渲染**(admin/routers/config.py:list_config 按此过滤)。用于把已下线/已改由
-#   专用页管理的项从福利页 Tab 收起,同时保留后端默认值与写入能力。
+# type 约定(给前端渲染编辑控件用):int / int_list / dict_str_int / bool
 CONFIG_DEFS: dict[str, dict[str, Any]] = {
    "signin_rewards": {
        "default": list(r.SIGNIN_REWARDS), "label": "签到 7 天金币档位",
@@ -33,21 +30,18 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
        "default": r.WITHDRAW_MAX_CENTS, "label": "提现最高额(分)",
        "group": "钱包", "type": "int",
    },
-    # 从福利页 Tab 收起(hidden)的项:任务 / 里程碑 整组 + 看广告组里的「单次金币(遗留展示值)/
-    # 每轮次数 / 比价领券信息流广告开关 comparing_ad_enabled」。key 与默认值保留、后端业务照常读取,
-    # 仅不在配置页渲染。看广告组保留可见的:每日上限 / 单次金币上限 / 关闭后冷却。
    "task_rewards": {
        "default": dict(r.TASK_REWARDS), "label": "一次性任务奖励",
-        "group": "任务", "type": "dict_str_int", "help": "task_key → 金币。", "hidden": True,
+        "group": "任务", "type": "dict_str_int", "help": "task_key → 金币。",
    },
    "record_milestones": {
        "default": list(r.RECORD_MILESTONES), "label": "比价里程碑金币档位",
-        "group": "里程碑", "type": "int_list", "hidden": True,
+        "group": "里程碑", "type": "int_list",
        "help": "累计成功比价第 1~N 档解锁发的金币。",
    },
    "ad_reward_coin": {
        "default": r.AD_REWARD_COIN, "label": "看广告单次金币",
-        "group": "看广告", "type": "int", "hidden": True,
+        "group": "看广告", "type": "int",
        "help": "历史兼容/测试展示值;正式发放按 eCPM 公式计算。",
    },
    "ad_daily_limit": {
@@ -60,7 +54,7 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
    },
    "ad_round_count": {
        "default": r.VIDEO_ROUND_REQUIRED_COUNT, "label": "每轮看广告次数",
-        "group": "看广告", "type": "int", "hidden": True, "help": "当前为 1,表示每次广告关闭后触发短冷却。",
+        "group": "看广告", "type": "int", "help": "当前为 1,表示每次广告关闭后触发短冷却。",
    },
    "ad_cooldown_sec": {
        "default": r.VIDEO_ROUND_COOLDOWN_SECONDS, "label": "广告关闭后冷却(秒)",
@@ -73,7 +67,7 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
    },
    "comparing_ad_enabled": {
        "default": True, "label": "比价/领券期信息流广告",
-        "group": "看广告", "type": "bool", "hidden": True,
+        "group": "看广告", "type": "bool",
        "help": (
            "开启后,比价进行中 + 领券等候期会在悬浮窗展示穿山甲信息流广告(变现行为);"
            "关闭则全程不出广告。客户端按 app 启动 / 每场比价开始时拉取并缓存,故为「最终一致」的"
@@ -90,10 +84,4 @@ CONFIG_DEFS: dict[str, dict[str, Any]] = {
            "提现页「批量对账」手动按钮不受影响。"
        ),
    },
-    # 首页轮播数据源(hidden:不进通用配置 Tab,由「首页轮播种子」页的专用端点 /marquee-seeds/mode 读写)。
-    "marquee_feed_mode": {
-        "default": "mixed", "label": "首页轮播数据源",
-        "group": "首页轮播", "type": "enum", "hidden": True,
-        "help": "mixed=真实优先+种子补位(默认);real=只用真实比价记录;seed=只用种子/合成(演示)。",
-    },
 }
@@ -2,15 +2,9 @@

 业务代码用 `logger = logging.getLogger("shagua.xxx")` 即可, 本模块在 main.py 启动时调一次。

- 控制台(stdout): 人类可读文本, 给 systemd / 本地看; 有 trace 时行尾附 `trace=xxx`。
- 文件 `logs/app-server.log`: 单行 JSON, 供**阿里云 SLS / Logtail** 采集(JSON 模式零正则);
-  异常栈内嵌为字段不换行 → 每条日志一行。
- **结构化字段(SLS 可直接查/聚合)**:
-  - `trace_id`: 请求级贯穿——在入口 `trace_id_ctx.set(...)` 后, 本请求内**每一行日志**(含
-    run_in_threadpool 里的 harvest, contextvars 自动拷进线程)都自动带上, 无需手写。
-    SLS 里 `trace_id: "xxx"` 一查即得整条比价链路, 按 time 升序即请求顺序。
-  - 任意 `logger.info(msg, extra={"phase": ..., "step": ..., "command": ...})` 的 extra
-    键都会平铺进 JSON 顶层 → SLS 可按 phase/step/command/cost_ms 等过滤聚合。
+- 控制台(stdout): 人类可读文本, 给 systemd / 本地看。
+- 文件 `logs/app-server.log`: 单行 JSON, 供阿里云 SLS/Logtail 采集(JSON 模式零正则);
+  异常栈作为字段内嵌不换行 → 每条日志一行。
 - 环境变量:
  - LOG_JSON_CONSOLE=1   控制台也输出 JSON
  - LOG_DIR / LOG_FILE   改落盘路径(默认 logs/app-server.log)
@@ -23,36 +17,13 @@ import json
 import logging
 import os
 import sys
-from contextvars import ContextVar
 from datetime import datetime
 from logging.handlers import RotatingFileHandler
 from pathlib import Path


-# 请求级 trace_id:入口(如 compare.py 透传壳)set 之后, 本请求上下文(含 run_in_threadpool
-# 拷贝出去的线程)内所有日志自动带上。默认空串 = 非请求上下文(启动/后台 worker)。
-trace_id_ctx: ContextVar[str] = ContextVar("trace_id", default="")
-
-
-# 标准 LogRecord 属性 + 格式化期附加项:凡不在此集合的 record 属性都视为业务 extra, 平铺进 JSON。
-_RESERVED = set(
-    logging.LogRecord("", 0, "", 0, "", (), None).__dict__
-) | {"message", "asctime", "trace_id", "taskName"}
-
-
-class _ContextFilter(logging.Filter):
-    """把 trace_id_ctx 注入每条 record(供两个 formatter 取用)。挂在 handler 上,
-    命中每条(含 propagate 上来的)记录, 在 format 之前置好 record.trace_id。"""
-
-    def filter(self, record: logging.LogRecord) -> bool:
-        if not hasattr(record, "trace_id"):
-            record.trace_id = trace_id_ctx.get()
-        return True
-
-
 class JsonFormatter(logging.Formatter):
-    """LogRecord → 单行 JSON(SLS/Logtail 友好)。trace_id 提到顶层、extra 键平铺, 异常栈内嵌。"""
-
+    """把 LogRecord 序列化成单行 JSON(SLS/Logtail 友好)。异常栈内嵌为字段, 整条仍是一行。"""
    def __init__(self, service: str = "app-server"):
        super().__init__()
        self.service = service
@@ -64,17 +35,10 @@ class JsonFormatter(logging.Formatter):
            "level": record.levelname,
            "service": self.service,
            "logger": record.name,
+            "func": record.funcName,
+            "line": record.lineno,
+            "message": record.getMessage(),
        }
-        tid = getattr(record, "trace_id", "") or trace_id_ctx.get()
-        if tid:
-            data["trace_id"] = tid
-        # 业务 extra 字段(phase / step / endpoint / command / cost_ms / status ...)平铺进顶层
-        for k, v in record.__dict__.items():
-            if k not in _RESERVED and not k.startswith("_"):
-                data[k] = v
-        data["func"] = record.funcName
-        data["line"] = record.lineno
-        data["message"] = record.getMessage()
        if record.exc_info:
            data["exception"] = self.formatException(record.exc_info)
        if record.stack_info:
@@ -82,15 +46,6 @@ class JsonFormatter(logging.Formatter):
        return json.dumps(data, ensure_ascii=False, default=str)


-class TextFormatter(logging.Formatter):
-    """控制台文本:标准行 + 有 trace_id 时行尾附 `trace=xxx`(无 trace 的启动/后台日志不加噪)。"""
-
-    def format(self, record: logging.LogRecord) -> str:
-        base = super().format(record)
-        tid = getattr(record, "trace_id", "") or trace_id_ctx.get()
-        return f"{base} trace={tid}" if tid else base
-
-
 _CONFIGURED = False


@@ -108,17 +63,14 @@ def setup_logging(debug: bool = False) -> None:
    for h in list(root.handlers):
        root.removeHandler(h)

-    ctx_filter = _ContextFilter()
-
    # 控制台: 默认文本(systemd/本地看); LOG_JSON_CONSOLE=1 时输出 JSON
    console = logging.StreamHandler(sys.stdout)
    if os.getenv("LOG_JSON_CONSOLE") == "1":
        console.setFormatter(JsonFormatter(service))
    else:
        console.setFormatter(
-            TextFormatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+            logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
        )
-    console.addFilter(ctx_filter)
    root.addHandler(console)

    # 文件: 单行 JSON, 供 Logtail 采集(自动轮转, 单文件 10MB, 保留 5 个)
@@ -130,7 +82,6 @@ def setup_logging(debug: bool = False) -> None:
        log_file, maxBytes=10 * 1024 * 1024, backupCount=5, encoding="utf-8",
    )
    file_handler.setFormatter(JsonFormatter(service))
-    file_handler.addFilter(ctx_filter)
    root.addHandler(file_handler)

    # 第三方库降噪
@@ -8,16 +8,15 @@
    校验)→ 鉴权复用极光一键登录的 `JG_APP_KEY`/`JG_MASTER_SECRET`(同一极光应用)。

 验证码存储:**进程内存**(单 worker uvicorn 够用)。重启丢失(用户重发即可)。多
-worker / 多机时内存不共享 → 冷却、校验都会失效,届时迁移到 DB/Redis。
+worker / 多机时内存不共享 → 冷却、每日上限、校验都会失效,届时迁移到 DB/Redis。
 见 docs/待办与技术债.md。

-防刷两层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
+防刷三层(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权):
  1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(本文件)
-  2. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
+  2. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限(本文件)
+  3. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
     ⚠️ 原「单 IP 频控(rate_limit 依赖)」2026-06-26 按产品要求删除、改设备维度;但 device_id 客户端可伪造/轮换,
        脚本轮换 id 能绕过本层 → 挡脚本狂发主要靠极光控制台侧(+ 可选 nginx 限流)。
-     ⚠️ 原「单号每日上限」2026-07-03 按精简要求删除(mentor 定:登录风控只留单号冷却 + 单设备频控);
-        单号维度现仅剩 60s 冷却,「换号轰炸」由单设备频控封顶。
 另:单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废(防爆破),验过即作废(一次性)。
 """
 from __future__ import annotations
@@ -27,6 +26,7 @@ import logging
 import secrets
 import time
 from dataclasses import dataclass
+from datetime import datetime
 from threading import Lock

 import httpx
@@ -56,17 +56,22 @@ class _CodeRecord:
 # 进程内存(单 worker 有效;多 worker 不共享,见模块 docstring)
 _codes: dict[str, _CodeRecord] = {}            # phone -> 当前有效验证码
 _last_sent: dict[str, float] = {}              # phone -> 上次发送 epoch(冷却)
+_daily_count: dict[str, tuple[str, int]] = {}  # phone -> (date_str, 当日发送数)
 _lock = Lock()
 _GC_THRESHOLD = 10000  # 任一内存 dict 超此阈值,send 时顺手清过期项(防无限增长,仿 ratelimit)


+def _today() -> str:
+    return datetime.now().strftime("%Y-%m-%d")
+
+
 def _gen_code() -> str:
    """生成 N 位数字验证码(用 secrets 而非 random;允许前导 0)。"""
    return "".join(secrets.choice("0123456789") for _ in range(settings.SMS_CODE_LENGTH))


 def _gc(now: float) -> None:
-    """顺手清理过期内存项,防两个 dict 无限增长。仅在持锁时调用,且某 dict 超
+    """顺手清理过期内存项,防三个 dict 无限增长。仅在持锁时调用,且某 dict 超
    _GC_THRESHOLD 才扫它(低频,开销可忽略)。"""
    if len(_codes) > _GC_THRESHOLD:
        for p in [p for p, r in _codes.items() if now > r.expires_at]:
@@ -75,6 +80,10 @@ def _gc(now: float) -> None:
        cutoff = now - settings.SMS_SEND_INTERVAL_SEC
        for p in [p for p, ts in _last_sent.items() if ts < cutoff]:
            _last_sent.pop(p, None)
+    if len(_daily_count) > _GC_THRESHOLD:
+        today = _today()
+        for p in [p for p, (d, _c) in _daily_count.items() if d != today]:
+            _daily_count.pop(p, None)


 def send_code(phone: str) -> int:
@@ -93,9 +102,17 @@ def send_code(phone: str) -> int:
            remain = int(settings.SMS_SEND_INTERVAL_SEC - elapsed)
            raise SmsError(f"发送过于频繁,请 {remain}s 后再试")

+        today = _today()
+        day, cnt = _daily_count.get(phone, ("", 0))
+        if day != today:
+            cnt = 0
+        if cnt >= settings.SMS_DAILY_LIMIT_PER_PHONE:
+            raise SmsError("今日验证码发送次数已达上限,请明天再试")
+
        code = _gen_code()
-        # 预占:先记冷却/存码,释放锁后再发网络(发失败保留冷却,见下)
+        # 预占:先记冷却/计数/存码,释放锁后再发网络(发失败保留冷却+计数,见下)
        _last_sent[phone] = now
+        _daily_count[phone] = (today, cnt + 1)
        _codes[phone] = _CodeRecord(code=code, expires_at=now + settings.SMS_CODE_TTL_SEC)

    # --- lock 外:真正发送(网络 IO 不持锁)---
@@ -106,7 +123,7 @@ def send_code(phone: str) -> int:
            _send_via_jiguang(phone, code)
            logger.info("[SMS] sent to %s****", phone[:3])
    except Exception as e:
-        # 发送失败:**保留冷却**(失败也限速,挡住余额不足/签名失效时
+        # 发送失败:**保留冷却 + 每日计数**(失败也限速,挡住余额不足/签名失效时
        # 前端重试狂打极光),只清掉没发出去的码(用户收不到,留着无意义且占内存)。
        with _lock:
            _codes.pop(phone, None)
@@ -5,7 +5,6 @@ from app.models.ad_pangle_revenue import AdPangleDailyRevenue  # noqa: F401
 from app.models.ad_reward import AdRewardRecord  # noqa: F401
 from app.models.ad_watch_log import AdWatchLog  # noqa: F401
 from app.models.admin import AdminAuditLog, AdminUser  # noqa: F401
-from app.models.admin_role import AdminRole  # noqa: F401
 from app.models.analytics_event import AnalyticsEvent  # noqa: F401
 from app.models.app_config import AppConfig  # noqa: F401
 from app.models.comparison import ComparisonRecord  # noqa: F401
@@ -25,14 +25,8 @@ class AdminUser(Base):
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    username: Mapped[str] = mapped_column(String(64), unique=True, index=True, nullable=False)
    password_hash: Mapped[str] = mapped_column(String(255), nullable=False)
-    # 明文登录密码:仅「后台 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")

@@ -1,42 +0,0 @@
-"""admin 角色 → 可见页面(权限)映射表。
-
-RBAC 的「角色」侧:每个角色持有一组「页面 key」(= 左侧导航项),决定该角色登录后台后左边能看到
-哪些页。super_admin 是内建全权角色(is_builtin=True),恒可见全部页(effective_pages 里特判,
-不依赖本表存的 pages)、不可编辑/删除。其余角色(含 operator/finance)可由 super_admin 增删改。
-
-admin_user.role 存的是本表的 name(字符串弱引用,不建外键——与既有 require_role 字符串口径一致;
-删除在用角色由业务层拦截,见 routers/roles.py)。页面 key 清单见 app/admin/permissions.py。
-"""
-from __future__ import annotations
-
-from datetime import datetime
-
-from sqlalchemy import JSON, Boolean, DateTime, Integer, String, func
-from sqlalchemy.dialects.postgresql import JSONB
-from sqlalchemy.orm import Mapped, mapped_column
-
-from app.db.base import Base
-
-_JSON = JSON().with_variant(JSONB(), "postgresql")
-
-
-class AdminRole(Base):
-    __tablename__ = "admin_role"
-
-    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    # 角色标识 key(不可变,承重):admin_user.role 引用它、require_role 按它鉴权。
-    # 内建 = super_admin/operator/finance/tech(英文,勿改);自定义 = 创建时的名称。
-    name: Mapped[str] = mapped_column(String(32), unique=True, index=True, nullable=False)
-    # 展示名(可改):内建 = 管理员/运营/财务/技术;自定义默认 = name。UI 一律展示 label。
-    label: Mapped[str] = mapped_column(String(32), nullable=False, default="")
-    # 该角色可见页面 key 列表(= 左侧导航项),见 app/admin/permissions.py 的 PERMISSION_CATALOG
-    pages: Mapped[list] = mapped_column(_JSON, nullable=False, default=list)
-    # 内建角色(当前仅 super_admin):不可编辑/删除,恒全权
-    is_builtin: Mapped[bool] = mapped_column(Boolean, nullable=False, default=False)
-
-    created_at: Mapped[datetime] = mapped_column(
-        DateTime(timezone=True), server_default=func.now(), nullable=False
-    )
-
-    def __repr__(self) -> str:  # pragma: no cover
-        return f"<AdminRole name={self.name} pages={len(self.pages)} builtin={self.is_builtin}>"
@@ -39,19 +39,16 @@ _JSON = JSON().with_variant(JSONB(), "postgresql")
 class ComparisonRecord(Base):
    __tablename__ = "comparison_record"
    __table_args__ = (
-        # trace_id 由 app-server 签发、全局唯一 → 一次比价一行,后端 harvest 按它 upsert。
-        # (原 (user_id,trace_id) 复合唯一改为 trace_id 单列:harvest 帧0 建行时 user_id 可能暂缺。)
-        UniqueConstraint("trace_id", name="uq_comparison_trace"),
+        # 同一用户同一次比价(trace_id)只存一条:客户端重试/误点重复上报时幂等覆盖。
+        UniqueConstraint("user_id", "trace_id", name="uq_comparison_user_trace"),
        # 首页轮播 / 省钱战绩聚合都按 status='success' 过滤 + created_at 近期排序;
        # 复合索引避免随数据量增大退化成全表扫(单列 created_at 索引不含 status)。
        Index("ix_comparison_status_created", "status", "created_at"),
    )

    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
-    # 后端 harvest 在帧0(pricebot 出 trace_id)即建行,软鉴权下 user_id 可能暂缺(老客户端/匿名)→ 可空。
-    # C 端「我的比价记录」按 user_id 过滤天然排除 null-user 行;admin 全看(含孤儿行)。
-    user_id: Mapped[int | None] = mapped_column(
-        Integer, ForeignKey("user.id"), index=True, nullable=True
+    user_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("user.id"), index=True, nullable=False
    )
    # 仍记录设备号(同一用户多设备的行为区分 / 与不鉴权期 device_id 数据对账)
    device_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
@@ -86,10 +83,6 @@ class ComparisonRecord(Base):

    # ===== 订单概要 =====
    store_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
-    # 下单商品名拼接串(顿号分隔,从 items[].name 去重派生),供 admin 列表「商品」列展示 + 商品名搜索。
-    # items 是 JSON(SQLite 下 json.dumps ensure_ascii 把中文转义,无法直接 CAST+LIKE),故另派生成普通
-    # 文本列——跨库 LIKE 一致、可加索引。写路径(upsert_record / harvest_done)落库时同步派生。
-    product_names: Mapped[str | None] = mapped_column(String(512), nullable=True)
    total_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
    skipped_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)

@@ -24,23 +24,6 @@ def _yuan_to_cents(yuan: float | None) -> int | None:
    return round(yuan * 100)


-def _product_names_from_items(items: list | None) -> str | None:
-    """下单商品 items([{name, qty, specs?}])→ 顿号分隔的商品名串(去重保序),
-    供 admin「商品」列展示 + 商品名 LIKE 搜索。空 / 无名 → None;超列宽(512)截断留余量。"""
-    if not items:
-        return None
-    names: list[str] = []
-    for it in items:
-        name = it.get("name") if isinstance(it, dict) else None
-        if not name:
-            continue
-        s = str(name).strip()
-        if s and s not in names:
-            names.append(s)
-    joined = "、".join(names)
-    return joined[:500] or None
-
-
 def _derive(payload: ComparisonRecordIn) -> dict:
    """从上报 payload 派生结构化列(best/saved/is_source_best/status)。"""
    results = payload.comparison_results
@@ -91,19 +74,12 @@ def _derive(payload: ComparisonRecordIn) -> dict:
 def upsert_record(
    db: Session, *, user_id: int, payload: ComparisonRecordIn
 ) -> ComparisonRecord:
-    """按 **trace_id** 幂等写入(唯一键已从 user_id+trace_id 改为 trace_id):已存在则合并
-    (回填 null user_id + 覆盖字段,但**不降级 success**),否则新建。
-
-    灰度期老客户端 POST /compare/record 走这条,与后端 harvest 按 trace_id reconcile;
-    新客户端不再 POST(改由 compare.py 透传壳 harvest 落库)。
-    """
+    """按 (user_id, trace_id) 幂等写入:已存在则覆盖(更完整的重试上报胜出),否则新建。"""
    derived = _derive(payload)
-    items = [it.model_dump(exclude_none=True) for it in payload.items]
    fields = dict(
        device_id=payload.device_id,
        business_type=payload.business_type,
        store_name=payload.store_name,
-        product_names=_product_names_from_items(items),
        source_platform_id=payload.source_platform_id,
        source_platform_name=payload.source_platform_name,
        source_package=payload.source_package,
@@ -112,7 +88,7 @@ def upsert_record(
        trace_url=payload.trace_url,
        total_dish_count=payload.total_dish_count,
        skipped_dish_count=payload.skipped_dish_count,
-        items=items,
+        items=[it.model_dump(exclude_none=True) for it in payload.items],
        comparison_results=[r.model_dump() for r in payload.comparison_results],
        skipped_dish_names=list(payload.skipped_dish_names),
        # 客户端环境 / 性能(debug,客户端上报;旧客户端为 None)
@@ -134,29 +110,14 @@ def upsert_record(
        **derived,
    )

-    # 按 trace_id 定位(唯一键已改 trace_id)：后端 harvest 可能已建行,这里的客户端上报
-    # (灰度期老客户端 / 新客户端不再走这条)与之 reconcile。
    existing = db.execute(
        select(ComparisonRecord).where(
+            ComparisonRecord.user_id == user_id,
            ComparisonRecord.trace_id == payload.trace_id,
        )
    ).scalar_one_or_none()

    if existing is not None:
-        # 不降级:harvest 或更早上报已落成 success,收尾期 fromFailure 的 cancelled/failed
-        # 不许把它盖回去(老 comparisonReported bug 的服务端兜底)——只补 user_id / trace_url。
-        if existing.status == "success" and fields.get("status") != "success":
-            if existing.user_id is None and user_id is not None:
-                existing.user_id = user_id
-            if fields.get("trace_url"):
-                existing.trace_url = fields["trace_url"]
-            db.commit()
-            db.refresh(existing)
-            return existing
-        # 只**填**空缺 user_id、不 reassign:trace_id 全局唯一,一条 trace 只属一个用户;
-        # 绝不把已有归属的记录改判给另一个上报者(仅 harvest 建的 null-user 行在此绑上)。
-        if existing.user_id is None:
-            existing.user_id = user_id
        for k, v in fields.items():
            setattr(existing, k, v)
        db.commit()
@@ -178,203 +139,6 @@ def upsert_record(
    return rec


-# ============================================================
-# 后端 harvest：app-server 从 pricebot 透传响应里直接落库(不靠客户端上报)。
-# 帧0 建行(running) → 最终 done 更新(success/failed) → finalize 更新(aborted)。
-# 全按 trace_id upsert；success 行永不被后到的 failed/aborted 降级。
-# ============================================================
-
-
-def _derive_from_results(results: list[dict]) -> dict:
-    """从 done 帧 comparison_results(pricebot 原始 dict 列表)派生结构化列。
-    等价 _derive,但吃原始字段(is_source/price/rank/platform_id/store_name...)而非 pydantic 对象。"""
-    priced = [r for r in results if r.get("price") is not None]
-    best = None
-    if priced:
-        best = min(
-            priced,
-            key=lambda r: (r.get("rank") if r.get("rank") is not None else 10**9, r["price"]),
-        )
-    src_row = next((r for r in results if r.get("is_source")), None)
-
-    source_price_cents = None
-    if src_row is not None and src_row.get("price") is not None:
-        source_price_cents = _yuan_to_cents(src_row["price"])
-    best_price_cents = _yuan_to_cents(best["price"]) if best else None
-    saved_amount_cents = None
-    if source_price_cents is not None and best_price_cents is not None:
-        saved_amount_cents = source_price_cents - best_price_cents
-
-    has_valid_target = any(
-        (not r.get("is_source")) and r.get("price") is not None for r in results
-    )
-    return {
-        "source_platform_id": (src_row or {}).get("platform_id"),
-        "source_platform_name": (src_row or {}).get("platform_name"),
-        "source_package": (src_row or {}).get("package"),
-        "source_price_cents": source_price_cents,
-        "best_platform_id": best.get("platform_id") if best else None,
-        "best_platform_name": best.get("platform_name") if best else None,
-        "best_price_cents": best_price_cents,
-        "saved_amount_cents": saved_amount_cents,
-        "is_source_best": best.get("is_source") if best else None,
-        "store_name": (src_row or {}).get("store_name") or None,
-        "status": "success" if has_valid_target else "failed",
-    }
-
-
-def _device_cols_from_info(device_info: dict | None) -> dict:
-    """step 帧 device_info({locale,brand,model,android_version,rom_version})→ 表列。
-    step 帧只带这几项;rom_name / android_sdk / app_version / 耗时步数 harvest 拿不到 → 留 None
-    (灰度期老客户端 fromComparison 会补齐;要新客户端也全带需扩 collectDeviceInfo,后续)。"""
-    d = device_info or {}
-    rv = str(d.get("rom_version") or "")
-    return {
-        "device_model": d.get("model") or None,
-        "device_manufacturer": d.get("brand") or None,
-        "android_version": d.get("android_version") or None,
-        "rom_version": int(rv) if rv.isdigit() else None,
-    }
-
-
-def _get_by_trace(db: Session, trace_id: str) -> ComparisonRecord | None:
-    return db.execute(
-        select(ComparisonRecord).where(ComparisonRecord.trace_id == trace_id)
-    ).scalar_one_or_none()
-
-
-def harvest_running(
-    db: Session,
-    *,
-    trace_id: str,
-    user_id: int | None,
-    business_type: str = "food",
-    device_id: str | None = None,
-    device_info: dict | None = None,
-    trace_url: str | None = None,
-) -> ComparisonRecord:
-    """帧0(或任一尚未建行的帧)建/补 running 行。幂等:已存在只补空缺(user_id/trace_url/
-    device_id/机型),绝不动已落定的 status / 结果。"""
-    rec = _get_by_trace(db, trace_id)
-    if rec is None:
-        rec = ComparisonRecord(
-            trace_id=trace_id,
-            user_id=user_id,
-            business_type=business_type or "food",
-            device_id=device_id,
-            status="running",
-            trace_url=trace_url,
-            created_at=datetime.now(CN_TZ).replace(tzinfo=None),
-            **_device_cols_from_info(device_info),
-        )
-        db.add(rec)
-        db.commit()
-        db.refresh(rec)
-        return rec
-    changed = False
-    if rec.user_id is None and user_id is not None:
-        rec.user_id = user_id
-        changed = True
-    if not rec.trace_url and trace_url:
-        rec.trace_url = trace_url
-        changed = True
-    if rec.device_id is None and device_id:
-        rec.device_id = device_id
-        changed = True
-    for k, v in _device_cols_from_info(device_info).items():
-        if getattr(rec, k) is None and v is not None:
-            setattr(rec, k, v)
-            changed = True
-    if changed:
-        db.commit()
-        db.refresh(rec)
-    return rec
-
-
-def harvest_done(
-    db: Session,
-    *,
-    trace_id: str,
-    user_id: int | None,
-    done_params: dict,
-    business_type: str = "food",
-    device_id: str | None = None,
-    device_info: dict | None = None,
-    trace_url: str | None = None,
-) -> tuple[ComparisonRecord, bool]:
-    """最终 done 帧:running 行 → 终态(success/failed)+结果+trace_url。
-    返回 (记录, 是否本次**新**落成 success)——供调用方据此幂等发一次邀请奖。
-    行不存在(理论上帧0已建;防御)则新建。"""
-    results = done_params.get("comparison_results") or []
-    derived = _derive_from_results(results)
-    # 菜品:pricebot 已把源单菜品塞进 comparison_results[源行].items
-    items = next((r.get("items") or [] for r in results if r.get("is_source")), [])
-    fields = dict(
-        business_type=business_type or "food",
-        information=done_params.get("information") or None,
-        # best_deeplink 来自客户端剪贴板采集,harvest 拿不到 → 留空(灰度期 fromComparison 会补;
-        # 纯 harvest 行「再次比价」退化为按 package 拉起 App。要精确深链需客户端另传,后续)。
-        trace_url=trace_url or done_params.get("trace_url"),
-        total_dish_count=done_params.get("total_dish_count"),
-        skipped_dish_count=done_params.get("skipped_dish_count"),
-        skipped_dish_names=list(done_params.get("skipped_dish_names") or []),
-        comparison_results=results,
-        items=items,
-        product_names=_product_names_from_items(items),
-        raw_payload=done_params,
-        **derived,
-        **_device_cols_from_info(device_info),
-    )
-
-    rec = _get_by_trace(db, trace_id)
-    was_success = rec is not None and rec.status == "success"
-    if rec is None:
-        rec = ComparisonRecord(
-            trace_id=trace_id,
-            user_id=user_id,
-            created_at=datetime.now(CN_TZ).replace(tzinfo=None),
-            device_id=device_id,
-            **fields,
-        )
-        db.add(rec)
-    else:
-        if user_id is not None and rec.user_id is None:
-            rec.user_id = user_id
-        if device_id and rec.device_id is None:
-            rec.device_id = device_id
-        for k, v in fields.items():
-            setattr(rec, k, v)
-    db.commit()
-    db.refresh(rec)
-    newly_success = (rec.status == "success") and not was_success
-    return rec, newly_success
-
-
-def harvest_abort(
-    db: Session,
-    *,
-    trace_id: str,
-    status: str,
-    reason: str | None,
-    trace_url: str | None = None,
-) -> ComparisonRecord | None:
-    """finalize(用户终止/超时/异常,无 done 帧):running 行 → aborted/failed + trace_url。
-    **不降级 success**:行已 success(收尾取消那种 finalize 后到)只 refresh trace_url。
-    行不存在(极少:帧0没建成)→ 返回 None,不凭空造。"""
-    rec = _get_by_trace(db, trace_id)
-    if rec is None:
-        return None
-    if trace_url and not rec.trace_url:
-        rec.trace_url = trace_url
-    if rec.status != "success":
-        rec.status = status or "cancelled"
-        if reason:
-            rec.information = reason
-    db.commit()
-    db.refresh(rec)
-    return rec
-
-
 def _ordered_shop_names(db: Session, user_id: int) -> set[str]:
    """该用户「真实下单」(source='compare')覆盖到的店名集合,用来给比价记录打「已下单」。

@@ -304,9 +304,6 @@ def get_invitees(
            "avatar_url": u.avatar_url or u.wechat_avatar_url or None,
            "coins": rel.inviter_coin,      # v3 起恒 0(邀请人收益改走邀请奖励金)
            "invited_at": rel.created_at,
-            # 是否已完成过一次比价(= 已发过邀请奖励金)。客户端据此:好友列表分"去提醒/邀请成功"、
-            # 在途列表只取未比价(is_compared=False)、算在途好友数与在途收益(未比价数×2元)。
-            "is_compared": bool(rel.compare_reward_granted),
        })
    has_more = offset + len(rows) < int(total)
    return items, int(total), has_more
@@ -5,7 +5,7 @@ device_id 为空(老客户端 / 取不到 ANDROID_ID)一律按"未完成"处理,
 """
 from __future__ import annotations

-from sqlalchemy import delete, select
+from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session

@@ -33,18 +33,3 @@ def mark_completed(db: Session, *, user_id: int, device_id: str) -> None:
    except IntegrityError:
        # 并发 / 重复提交撞唯一约束:已有行即视为成功。
        db.rollback()
-
-
-def delete_completion(db: Session, *, user_id: int, device_id: str) -> int:
-    """删该 (账号, 设备) 的引导完成标记 → 下次登录 is_completed=False → 客户端重走。
-    与 [mark_completed] 互逆。device_id 为空忽略(返 0);无记录也幂等(返 0)。返回删除行数。"""
-    if not device_id:
-        return 0
-    result = db.execute(
-        delete(OnboardingCompletion).where(
-            OnboardingCompletion.user_id == user_id,
-            OnboardingCompletion.device_id == device_id,
-        )
-    )
-    db.commit()
-    return result.rowcount
@@ -29,18 +29,6 @@ from app.core.rewards import CN_TZ
 from app.models.comparison import ComparisonRecord
 from app.models.ops_marquee_seed import OpsMarqueeSeed
 from app.models.user import User
-from app.repositories import app_config
-from app.repositories.user import is_default_nickname
-
-# 首页轮播数据源模式(存 app_config.marquee_feed_mode):
-#   mixed=真实优先+种子补位+合成兜底(默认,原行为);real=只真实(不足则少/空);seed=只种子+合成兜底。
-FEED_MODES = ("mixed", "real", "seed")
-
-
-def get_feed_mode(db: Session) -> str:
-    """读首页轮播数据源模式;非法/未配置回退 mixed(= 原行为)。"""
-    mode = app_config.get_value(db, "marquee_feed_mode")
-    return mode if mode in FEED_MODES else "mixed"

 # feed 运行时随机源(每次请求结果不同 = 轮播想要的「鲜活感」)
 _rng = random.Random()
@@ -141,12 +129,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,79 +202,60 @@ 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
+    # 真实条:取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
+    rows = _recent_real_rows(db)

    items: list[dict] = []
    used_names: set[str] = set()
+    seen_users: set[int] = set()
+    for uid, sc, nick in rows:
+        if uid in seen_users:
+            continue
+        seen_users.add(uid)
+        name = _mask_real(nick, uid)
+        used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
+        items.append({"masked_user": name, "saved_amount_cents": int(sc)})
+        if len(items) >= limit:
+            break

-    # 真实条(mixed / real):**不按 user 去重**——打乱 + 去连簇(相邻尽量不同用户、减少单人连刷)后取前
-    # limit;金额超上限的异常值已在查询剔除。同一用户可多条露出,但被打散、尽量不连续。
-    if mode != "seed":
-        for uid, sc, nick in _shuffle_declustered(_recent_real_rows(db))[:limit]:
-            name = _mask_real(nick, uid)
-            used_names.add(name)  # 同一用户可多条,名字重复无害(used_names 仅供种子避重)
-            items.append({"masked_user": name, "saved_amount_cents": int(sc)})
-
-    # 种子补位 + 合成兜底(mixed / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
-    # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
-    if mode != "real":
-        need = limit - len(items)
-        if need > 0:
-            seeds = db.execute(
-                select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
-            ).scalars().all()
-            # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
-            chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
-            _rng.shuffle(chosen)
-            for s in chosen:
-                # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
-                # 仅运营手动设的非模板真名才原样用。
-                fixed = (s.masked_user or "").strip()
-                name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
-                used_names.add(name)
-                # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
-                lo = max(0, int(s.min_cents))
-                hi = max(lo, int(s.max_cents))
-                items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
-
-        # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
-        # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
-        while len(items) < limit:
-            name = _unique_name(used_names)
+    need = limit - len(items)
+    if need > 0:
+        seeds = db.execute(
+            select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
+        ).scalars().all()
+        # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
+        chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
+        _rng.shuffle(chosen)
+        for s in chosen:
+            # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
+            # 仅运营手动设的非模板真名才原样用。
+            fixed = (s.masked_user or "").strip()
+            name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
            used_names.add(name)
-            items.append({
-                "masked_user": name,
-                "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
-            })
+            # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
+            lo = max(0, int(s.min_cents))
+            hi = max(lo, int(s.max_cents))
+            items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
+
+    # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
+    # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
+    while len(items) < limit:
+        name = _unique_name(used_names)
+        used_names.add(name)
+        items.append({
+            "masked_user": name,
+            "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
+        })

    # 统一赋「最近」时间:从 now 往前**随机抖动**递减,避免固定节奏被看出规律。
    # 首条几十秒前;其余多数 1~5 分钟,偶尔扎堆(20~55s)或较长(5~9 分钟),降序、像真实流水。
@@ -310,78 +276,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(
@@ -318,14 +318,11 @@ def update_config(
        row.random_current = _monotonic(row, random_initial)
        row.random_last_tick_at = now
    elif apply_now:
-        # 立即更新:不等钟点,马上刷新一次。
-        # random:走一档增长;real/manual:直接落到「配置目标值」(manual_value / max(真实,保底)),
-        # **显式保存即所见即所得,绕过「只增不减」护栏**——运营手动改值就是要按配置显示(含调小)。
-        # (护栏仍作用于自动 tick 的 _refresh:防门面在两次保存之间被真实刷新/自增长悄悄缩水。)
+        # 立即更新:不等钟点,马上刷新一次
        if row.mode == "random" and row.random_current is not None:
            row.random_current = _grow(row, row.random_current, 1)
        else:
-            row.random_current = _current_target(db, row)
+            row.random_current = _monotonic(row, _current_target(db, row))
        row.random_last_tick_at = now
    elif row.random_current is None:
        # 首次无值:按当前模式播种,使配置后立即有合理展示值
@@ -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)
@@ -296,9 +296,6 @@ def daily_auto_exchange(db: Session) -> dict:
    - **逐用户独立事务**:单个用户异常 rollback 不影响其他人;exchange_coins_to_cash 内部按用户 commit。
    返回统计 dict(scanned/converted/skipped_done/skipped_dust/failed/total_cents)。
    """
-    # ⚠️「今天」写死北京时(rewards.cn_today() = datetime.now(CN_TZ).date(), CN_TZ=+8),与服务器/用户
-    #   时区无关(用户 2026-07-01 硬约束:兑换一律北京 0 点日切)。**禁止**改成 date.today() / 裸
-    #   datetime.now().date()——那会跟随进程本地时区,服务器非 CST 时会在错误的"天"兑/重复兑。
    today = rewards.cn_today()
    stats = {
        "scanned": 0, "converted": 0, "skipped_done": 0,
@@ -69,7 +69,6 @@ class InviteeItem(BaseModel):
    avatar_url: str | None = None   # 头像 URL;null = 前端画默认色块
    coins: int                      # 这次邀请给我(邀请人)发的金币
    invited_at: datetime            # 邀请绑定时间(前端转"今天/3天前")
-    is_compared: bool = False       # 该好友是否已完成过一次比价(好友列表分"去提醒/邀请成功";在途列表只取 False)


 class InviteeListOut(BaseModel):
@@ -19,9 +19,6 @@ Type=oneshot
 User=root
 WorkingDirectory=/opt/shaguabijia-app-server
 Environment="PATH=/opt/shaguabijia-app-server/.venv/bin:/usr/bin:/bin"
-# 写死北京时:兑换的"当天/0 点"一律按北京时,不随服务器 OS 时区漂(用户 2026-07-01 硬约束)。
-# 脚本内的日期判断本就走 rewards.cn_today()(CN_TZ=+8),这里再把进程 TZ 也钉成北京,双保险。
-Environment="TZ=Asia/Shanghai"
 EnvironmentFile=/opt/shaguabijia-app-server/.env
 ExecStart=/opt/shaguabijia-app-server/.venv/bin/python -m scripts.daily_auto_exchange --once
 SyslogIdentifier=daily-exchange
@@ -4,10 +4,8 @@
 Description=Run daily auto-exchange coins->cash at midnight

 [Timer]
-# 每天【北京时】0 点跑,写死时区(用户 2026-07-01 硬约束:兑换一律北京 0 点,不随服务器本地时区漂)。
-# systemd OnCalendar 支持尾缀时区;不写时区会按服务器 OS 本地时区触发 → 服务器非 CST 时会在错误时刻兑。
-# 客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
-OnCalendar=*-*-* 00:00:00 Asia/Shanghai
+# 每天 0 点跑。客户端文案已注明「可能存在延迟」,可按需改 00:05 错开整点扎堆。
+OnCalendar=*-*-* 00:00:00
 # 服务器宕机/重启后,补跑错过的那一轮(而不是干等次日)。
 Persistent=true
 AccuracySec=1min
@@ -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`）。

@@ -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)。
@@ -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` 入库为空导致大盘时间窗漏算。
@@ -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)见表文档。
@@ -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`(事件真实发生时刻),入库时间受客户端攒批影响。
@@ -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`=金额非法。
@@ -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` | 拒绝(填原因,用户端可见)+ 带审计 |
@@ -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` 目录,表里只存勾选结果(目录变更无需迁移)。
@@ -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)。
@@ -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)。
@@ -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)。
@@ -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)。
@@ -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)。
@@ -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 端口径。
@@ -2,10 +2,10 @@

 > 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)

-比价 `done` 帧后上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。
+比价 `done` 帧后,客户端用**带 JWT 的通道**上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。

-> ⚠️ **灰度定位(2026-07)**：写 `comparison_record` 现以透传壳 `compare.py` 的**后端 harvest** 为主(帧0 建 `running` 行 → done/finalize 落终态,新客户端不再 POST)。本接口降级为**老客户端兼容**通道,与 harvest 按 `trace_id` reconcile(**success 不被降级**);新版覆盖够高后可下线本 POST。
-> 与软鉴权透传端点 [`/api/v1/price/step`](./compare-price-step.md) 不同：那是转发壳(顺带 harvest 落库),本接口按用户维度显式上报,**必须鉴权**。
+> ⚠️ 与不鉴权的透传端点 [`/api/v1/price/step`](./compare-price-step.md) 不同：那是转发壳，本接口按用户维度落库，**必须鉴权**。
+> 本轮只做 server 端；客户端在 done 帧后调本接口的改动另起一轮（见 [待办与技术债.md](../guides/待办与技术债.md) P1）。

 ## 入参（JSON body）

@@ -13,7 +13,7 @@

 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |---|---|---|---|---|
-| `trace_id` | string | ✅ | — | 一次比价的唯一标识(app-server 帧0 签发)。**幂等键(trace_id 单列唯一)**：同 trace_id 重复上报覆盖、返回同一 id;与 harvest 行按它 reconcile |
+| `trace_id` | string | ✅ | — | pricebot 侧 trace_id。**幂等键**：同用户同 trace_id 重复上报覆盖、返回同一 id |
 | `business_type` | string | ❌ | `food` | `food`(外卖,当前唯一接通) / `ecom`(电商) / `coupon`(领券) |
 | `device_id` | string \| null | ❌ | null | 设备号 |
 | `store_name` | string \| null | ❌ | null | 店铺名（外卖,来自 calibration.result） |
@@ -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`）
@@ -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 步、逐帧多一跳,走公网延迟会累积）
@@ -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` 密钥不匹配 / 缺失。
@@ -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": "邀请绑定成功"
 }
 ```
@@ -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"
    }
  ],
@@ -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 专用)。

@@ -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`)。
@@ -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` 一律返回未完成
@@ -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 | 累计赚取金币 |

 ## 说明
-账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源;邀请页「奖励金」余额也读它。
+账户不存在时自动创建（零余额）。福利页「我的资产」卡的数据源。
@@ -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 | 发起时间 |
@@ -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 | ❌ | **客户端幂等键（商户单号）**:同号重试不重复转账;不传则服务端生成 |

@@ -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`,并发/重试不会双扣。

 ---

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

@@ -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 | 整场比价累计观看秒数(轮播各条相加) |
@@ -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")` 等旧代码路径仍工作,内建角色名不可改。
@@ -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` 管用户/反馈/大盘。具体守卫见各接口文档。
@@ -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` 只是入库时刻(受攒批影响)。
@@ -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 跨用户现金流水。
@@ -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` 原子条件扣减,并发/重试不会超额。
@@ -1,25 +1,25 @@
 # 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'` 条数),还被「上报更低价」反查原最低价。
+每完成一次比价(外卖/电商/领券),客户端在 done 帧后用**带 JWT** 的通道上报一条。App「我的比价记录」列表/详情的数据源,也是比价战绩里程碑解锁进度的计数源(`status='success'` 条数),还被「上报更低价」反查原最低价。

 > 与 `savings_record` 的区别:本表是「每一次**比价行为**的完整明细」(不省钱、甚至失败也记);`savings_record` 是「真正**下单成交**省了多少」。两表独立、互不喂数据。
 > 与 [`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(upsert,幂等)**:`POST /compare/record`(`upsert_record`)。按 `(user_id, 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) |
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | 被 `price_report.comparison_record_id` 引用 |
-| `user_id` | Integer | FK→user.id, index, **nullable**(2026-07 从 NOT NULL 放开) | 归属用户。后端 harvest 帧0 建行时(软鉴权 / 老客户端匿名)可能暂缺 → 可空;C 端「我的比价记录」按 `user_id` 过滤天然排除 null 行,admin 全看(含孤儿行) |
+| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
 | `device_id` | String(64) | nullable | 设备号(多设备区分 / 与不鉴权期对账) |
 | `business_type` | String(16) | NOT NULL, default `food`, index | 取值:`food`(当前唯一接通)/ `ecom` / `coupon` |
-| `trace_id` | String(64) | NOT NULL, **UNIQUE** | 一次比价的唯一标识。**由 app-server 帧0 用 uuid 签发**(注入转发 body + 回填响应顶层给客户端;老客户端自带),全局唯一 = harvest upsert 键 + 关联 pricebot 调试落盘 |
+| `trace_id` | String(64) | NOT NULL | pricebot 侧 trace_id(关联调试落盘 + 幂等键) |
 | `trace_url` | String(512) | nullable | 本次比价公网调试链接(`price.shaguabijia.com/traces/{dir}/`);dir 名含 pricebot 落盘时分秒,前端/server 拼不出必须存。查看接口按 `user.debug_trace_enabled`(或本机 agent 调试 `include_trace`)决定返不返回。旧记录 / 未开上云为 null |
 | `source_platform_id` / `_name` | String(32) | nullable | 源平台代号 / 中文名 |
 | `source_package` | String(128) | nullable | 源平台 Android 包名 |
@@ -30,9 +30,8 @@
 | `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** |
+| `status` | String(16) | NOT NULL, default `success` | 取值:`success`(有非源且有价的目标结果)/ `failed`(出错/没采到目标价)。**里程碑只数 success** |
 | `information` | String(256) | nullable | done 帧文案;成功=摘要,失败=具体原因(前端失败时当原因展示) |
 | `items` | JSON(PG: JSONB) | NOT NULL, default [] | 下单菜品 `[{name, qty, specs?}]` |
 | `comparison_results` | JSON(PG: JSONB) | NOT NULL, default [] | 逐平台对比 `[{platform_id,platform_name,package,price(元),is_source,rank,coupon_saved(元),coupon_name,applied_coupons}]`;`coupon_saved`=该平台主优惠额(美团红包/淘宝平台红包/京东百亿补贴,只取一笔),`coupon_name`=优惠来源名(展示用),`applied_coupons`=`[{name,amount}]` 多券明细 |
@@ -51,8 +50,7 @@
 - 被 `comparison_milestone_claim` 间接依赖:解锁进度 = 本表 `status='success'` 计数。

 ## 索引与约束
- PK `id`;index `user_id`、`business_type`、`created_at`;复合 index `ix_comparison_status_created`(`status`, `created_at`)(按 `status='success'` 过滤 + 近期排序的聚合/轮播,避免随数据量退化为全表扫);UNIQUE(`trace_id`) = `uq_comparison_trace`(harvest 按它 upsert,一次比价一行)。
-  > 2026-07 迁移 `comparison_record_trace_unique`:唯一键从复合 `uq_comparison_user_trace`(`user_id`,`trace_id`)改为 `trace_id` 单列——harvest 帧0 建行时 user_id 可能暂缺,不能再用复合键去重。上线前须确认历史无重复 `trace_id`(`SELECT trace_id,COUNT(*) c FROM comparison_record GROUP BY trace_id HAVING c>1`),否则建单列唯一会失败。
+- PK `id`;index `user_id`、`business_type`、`created_at`;复合 index `ix_comparison_status_created`(`status`, `created_at`)(按 `status='success'` 过滤 + 近期排序的聚合/轮播,避免随数据量退化为全表扫);UNIQUE(`user_id`, `trace_id`) = `uq_comparison_user_trace`(幂等覆盖)。

 ## 注意
 - 4 个 JSON 列用 `JSON().with_variant(JSONB(),"postgresql")`(SQLite 退化 JSON)。结构化金额列存「分」,`comparison_results.price`/`coupon_saved` 原样存「元」。
@@ -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` 只做时刻留痕,不用来算时长。
@@ -1,7 +1,6 @@
 # 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 内存态跑、不落库**）。三表各管一件事：

@@ -2,7 +2,7 @@

 > 模型 `app/models/cps_order.py` · 仓库 `app/admin/repositories/cps.py`(`reconcile_orders` / `_map_order_fields` / `list_orders`、统计 `group_stats`) · 接口 admin `POST /admin/api/cps/orders/reconcile`、`GET /admin/api/cps/orders`、`GET /admin/api/cps/stats` · [← 索引](./README.md) · [总览](./OVERVIEW.md)

-从联盟 API 按时间窗拉回、按 `sid` 归群的订单明细,是 CPS 群发漏斗的**最下游"赚了多少佣金"**:用户点 [`cps_link`](./cps_link.md)(携群 [`cps_group`](./cps_group.md) 的 `sid`)下单后,联盟把订单连同 `sid` 回传,这里按 `sid` 归群做对账,与 [`cps_click`](./cps_click.md) 的点击量在 `group_stats` 汇成"点击→下单→佣金"漏斗。**平台覆盖**:初版仅美团(`query_order`);#90(2026-06-30)接入**京东联盟**订单(拉单进同一张表,`platform='jd'`,配 `jd_*`/`external_*` 列,喂数据大盘);淘宝仍无对账 API,统计里对账字段显示 `-`。
+从美团联盟 `query_order` 按时间窗拉回、按 `sid` 归群的订单明细,是 CPS 群发漏斗的**最下游"赚了多少佣金"**:用户点 [`cps_link`](./cps_link.md)(携群 [`cps_group`](./cps_group.md) 的 `sid`)下单后,美团把订单连同 `sid` 回传,这里按 `sid` 归群做对账,与 [`cps_click`](./cps_click.md) 的点击量在 `group_stats` 汇成"点击→下单→佣金"漏斗。**仅美团有此表**——淘宝/京东无对账 API,统计里对账字段显示 `-`。

 ## 用在哪 / 增删改查
 - **C/U(upsert)**:`POST /admin/api/cps/orders/reconcile`(`reconcile_orders`,需 `finance` 角色)。调 `meituan.query_order(sid?, start_time, end_time, page, limit=100)` 分页拉单(`max_pages=200` 防死循环),每条经 `_map_order_fields` 转字段,按 `order_id` **upsert**:不存在则 insert,存在则逐字段覆盖(订单状态会随时间变 付款→完成→结算/退款,重复拉则更新)。返回 `{fetched, inserted, updated, pages}`。`order_id` 全局唯一即幂等键。
@@ -15,10 +15,7 @@
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join / 源字段) |
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | |
-| `platform` | String(20) | index, NOT NULL, default `meituan` | 订单来源联盟:`meituan` / `jd`(#90)。统计/大盘按它分平台 |
-| `order_id` | String(64) | **UNIQUE, index, NOT NULL** | 订单号(美团加密串 `orderId`;京东为联盟订单号)。upsert 幂等键 |
-| `external_order_id` | String(128) | index, nullable | 平台原始订单号(#90,京东 `orderId`;美团 null) |
-| `external_row_id` | String(128) | index, nullable | 平台订单行号(#90,京东一单多 sku 时区分行;美团 null) |
+| `order_id` | String(64) | **UNIQUE, index, NOT NULL** | 美团订单号(加密串),`orderId`。upsert 幂等键 |
 | `sid` | String(64) | index, **nullable** | 渠道追踪位 = 群 `sid`,源 `sid`。**按它归群聚合**;历史无 sid 订单为空 |
 | `act_id` | String(64) | index, nullable | 活动物料 ID,源 `actId`(转字符串) |
 | `biz_line` | Integer | nullable | 业务线,源 `businessLine`。`1=外卖` |
@@ -28,14 +25,9 @@
 | `commission_rate` | String(16) | nullable | 佣金率,源 `commissionRate`。`"300"=3%`、`"10"=0.1%`(原样字符串,前端解释) |
 | `refund_price_cents` | Integer | nullable | 退款金额(分),源 `refundPrice`(元) |
 | `refund_profit_cents` | Integer | nullable | 退款佣金(分),源 `refundProfit`(元) |
-| `estimated_commission_cents` | Integer | nullable | 预估佣金(分,#90 京东口径;美团用 `commission_cents`) |
-| `actual_commission_cents` | Integer | nullable | 实际/结算佣金(分,#90 京东口径) |
-| `mt_status` | String(8) | index, nullable | 美团订单状态,源 `status`:`2`付款 `3`完成 `4`取消 `5`风控 `6`结算;京东订单为 null |
-| `jd_valid_code` | String(16) | index, nullable | 京东订单有效码(#90,联盟 `validCode`,判有效/无效/风控);美团订单为 null |
+| `mt_status` | String(8) | index, nullable | 美团订单状态,源 `status`:`2`付款 `3`完成 `4`取消 `5`风控 `6`结算 |
 | `invalid_reason` | String(128) | nullable | 失效原因,源 `invalidReason` |
 | `product_name` | String(512) | nullable | 商品名,源 `productName`(超 500 截断) |
-| `settle_month` | String(16) | nullable | 结算月份(#90 京东) |
-| `site_id` / `position_id` / `pid` | String(128) | nullable | 京东推广位维度(#90):站点/推广位/联盟 pid,归因用 |
 | `pay_time` | DateTime(tz) | index, nullable | 付款时间,源 `payTime`(秒级 ts)。统计按时间窗过滤的就是它 |
 | `mt_update_time` | DateTime(tz) | nullable | 美团侧更新时间,源 `updateTime`(秒级 ts) |
 | `raw` | JSON / JSONB | NOT NULL, default `{}` | `query_order` 单条原始 dataList,留底排查/补字段 |
@@ -56,5 +48,4 @@
 - **"未归群"独立行**:`group_stats` 遍历完所有群后,对剩下的、有订单但 `sid` 不属任何现存群的 sid(历史遗留如 `wonderableai`、或别处来源、或群被删),单列一行 `group_id=None`、有对账无点击。所以本表 `sid` 可空/可孤立是设计内的,不是脏数据。
 - **金额/时间统一转换的原因**:`query_order` 返回金额是「元」字符串、时间是秒级 ts;`_yuan_to_cents`(Decimal 防浮点,`"null"`/空 → None)与 `_ts_to_dt`(转 tz-aware UTC,前端按北京展示)在入库时归一,与全站"金额存分、时间存 tz-aware"口径对齐。`raw` 整条留底,字段不够时不用重拉。
 - **upsert 而非 append**:同一订单会被多次拉到(状态变化),按 `order_id` 覆盖即可拿到最新状态;`reconcile` 可重复跑(幂等)。
- **平台边界的演变**:初版(`277f9b1`)只服务美团;#90(2026-06-30)接入**京东联盟**拉单进同一张表(`platform='jd'` + `external_*`/`jd_valid_code`/`estimated|actual_commission_cents` 等列,有效性按 `jd_valid_code` 判,喂 admin 数据大盘的京东收益)。**淘宝仍无对账 API**,统计对账列给 `None`(前端显示 `-`)。
- **#119 修 `pay_time` 缺失**:早期美团拉单部分订单 `payTime` 空导致 `pay_time` 为 null → 大盘按时间窗过滤漏算美团收益;#119 起入库补齐/回填,时间窗统计以 `pay_time` 为准。
+- **本表自始至终只服务美团**:初版(`277f9b1`)就定型,`3a40f61` 接淘宝/京东时**没动本表**——那俩平台无对账 API,统计里对账列直接给 `None`(前端显示 `-`)。这是"对账 = 美团专属"的边界。
@@ -9,7 +9,7 @@
 ## 用在哪 / 增删改查
 - **C / U(upsert)**:`register_or_update`(`POST /device/register`,App 拿到 push token 时调)按 `(user_id, device_id)` upsert,只在传入非空时更新 `registration_id`/`platform`/`app_version`;`touch_heartbeat`(`POST /device/heartbeat`,无障碍服务存活时周期调,**心跳也能自注册**)在 `accessibility_enabled=true` 时刷 `last_heartbeat_at`、置 `ever_protected=true`、状态机重置回 `alive`、清 `notified_at`(掉线恢复→下次再断才再推一条)。
 - **U(worker)**:`mark_notified`(`heartbeat_monitor_worker` 检出掉线后)置 `liveness_state='notified'` + `notified_at` + **`kill_alert_pending=True`**;`ack_kill_alert`(`POST /device/liveness/ack`,客户端弹过引导后)清 `kill_alert_pending`(幂等)。
- **R**:`list_overdue`(worker 扫描:`ever_protected=true` + `liveness_state='alive'` + `last_heartbeat_at` 早于 `now - timeout`)→ 掉线设备列表;`get_device`(`GET /device/liveness`,客户端进 App 拉本机是否被判掉线过);admin `GET /admin/api/device-liveness/stats` + 列表(#80,后台「设备存活监控」页:总数/在线/掉线卡片 + 明细)。
+- **R**:`list_overdue`(worker 扫描:`ever_protected=true` + `liveness_state='alive'` + `last_heartbeat_at` 早于 `now - timeout`)→ 掉线设备列表;`get_device`(`GET /device/liveness`,客户端进 App 拉本机是否被判掉线过)。
 - **D**:无。

 ## 字段
@@ -22,7 +22,6 @@
 | `platform` | String(16) | NOT NULL, default `android` | |
 | `app_version` | String(32) | nullable | 上报时 App 版本 |
 | `ever_protected` | Boolean | NOT NULL, default false | 收到过 service 心跳即 true(=该设备开过无障碍,功能对它有意义)。`list_overdue` 的过滤前提 |
-| `first_protected_at` | DateTime(tz) | nullable | **首次**开启无障碍(首次收到心跳)的时刻(#80);置 `ever_protected=true` 时一并写、之后不再变。admin 设备存活监控用它算「开启保护耗时/转化」 |
 | `last_heartbeat_at` | DateTime(tz) | index, nullable | 最近一次 service 心跳时间(存活证明);超时即视为保护掉线 |
 | `last_report_protection_on` | Boolean | NOT NULL, default false | 最近一次上报的无障碍开关状态(观测用) |
 | `liveness_state` | String(16) | NOT NULL, default `unknown` | 状态机:`unknown` → `alive`(收到 service 心跳)→ `silent`/`notified`(扫描发现超时并已推送);心跳恢复 handler 重置回 `alive` |
@@ -41,4 +40,4 @@
 ## 注意
 - **`kill_alert_pending` 为什么和 `liveness_state` 解耦**:服务随 App 重启会先发心跳把 `state` 重置回 `alive`,若复用 `state` 判「待提醒」,客户端进 App 这一刻可能恰好已被重置 → 漏看这次掉线。故另设一个只由 worker 置、只由客户端 ack 清的标记,规避竞态。
 - **`list_overdue` 本期不要求有 `registration_id`**:本期只做终端打印检测、未真推送,没接极光 token 的设备也要检出。
- 心跳超时阈值由 worker 的 `timeout_minutes` 决定(不在表里);#107 起默认 **1 小时**(原 10 分钟误报率高:息屏/省电模式下心跳会正常停发)。
+- 心跳超时阈值由 worker 的 `timeout_minutes` 决定(不在表里)。
@@ -1,14 +1,14 @@
-# feedback — 用户帮助与反馈(含审核发奖)
+# feedback — 用户帮助与反馈

-> 模型 `app/models/feedback.py` · 仓库 `app/repositories/feedback.py` · 接口 C 端 [feedback](../api/other/feedback.md) / [feedback-records](../api/other/feedback-records.md);admin `GET /admin/api/feedbacks`、`/summary`、`POST /{id}/approve|reject|handle`(`app/admin/routers/feedback.py`) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/feedback.py` · 仓库 `app/repositories/feedback.py` · 接口 [feedback](../api/feedback.md) · admin [admin-feedbacks-list](../api/admin-feedbacks-list.md) / [admin-feedback-handle](../api/admin-feedback-handle.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

-App「帮助与反馈」每次提交写一行。2026-06 起演进为**轻审核工单**:运营在后台采纳(`adopted`,可发金币)/拒绝(`rejected`,填原因)并可写**运营回复**(#105),C 端「我的反馈」列表把状态与回复展示给用户;提交侧自动采集**来源/场景 + 端环境**(App 版本/机型/ROM/Android 版本,#94)供排障。与 `price_report`(结构化上报更低价)不同,本表是**自由文本**反馈。
+App「帮助与反馈」每次提交写一行。`content` 必填;`contact` 原必填,**原型改版后客户端不再采集,新数据存空串**(列保持 NOT NULL、免迁移,历史数据仍有值);`images` 为可选截图(≤6 张)。后台人工处理后置 `handled`。与 `price_report`(结构化上报更低价)不同,本表是**自由文本**反馈。

 ## 用在哪 / 增删改查
- **C(插入)**:`POST /api/v1/feedback`(multipart:`content` + 可选 `contact`/`images`/`source`/`scene`;客户端自动带 `app_version`/`device_model`/`rom_name`/`android_version`)→ `status='pending'`。截图经 `core.media` 落 `/media/feedback/`。
- **U(更新,admin,均写 `admin_audit_log`)**:`approve`(→`adopted`,可选发金币 `reward_coins`,走 `grant_coins` 同事务)/ `reject`(→`rejected`,`reject_reason`)/ `handle`(→`handled`,旧口径「标记已处理」保留)。三者均可写 `admin_reply`(用户可见回复)与 `review_note`(内部备注)。
+- **C(插入)**:`POST /api/v1/feedback`(multipart:`content` + 可选 `contact` + 可选 `images`;`create_feedback`)。截图先经 `core.media` 落 `/media/feedback/` 拿相对路径,再随反馈写入,`status='new'`。
+- **U(更新)**:admin 处理反馈 `update_feedback_status` → `status='handled'`(同事务写 `admin_audit_log`)。
 - **D**:无。
- **R**:C 端 `GET /api/v1/feedback/records`(我的反馈历史,展示状态/回复/奖励);admin 列表(状态/来源筛选)+ `summary`(各状态计数)。
+- **R**:admin 反馈列表(可按 `status` 筛)。C 端当前无"我的反馈列表"读接口。

 ## 字段
 | 列 | 类型 | 约束 / 默认 | 说明(取值 / join) |
@@ -16,31 +16,17 @@ App「帮助与反馈」每次提交写一行。2026-06 起演进为**轻审核
 | `id` | Integer | PK, autoincrement | |
 | `user_id` | Integer | FK→user.id, index, NOT NULL | 提交用户 |
 | `content` | Text | NOT NULL | 反馈正文 |
-| `contact` | String(128) | NOT NULL | 联系方式。客户端改版后不再采集,新数据为空串;列仍 NOT NULL |
-| `source` | String(16) | NOT NULL, default `profile`, index | 提交入口来源(#105):`profile`(设置/我的页普通反馈)/ 比价场景值;客户端显式传优先,未传由 `scene` 有无派生 |
-| `scene` | String(32) | nullable | 比价反馈的「问题场景」(找错商品/优惠不对/比价太慢…,#105);比价结果页反馈才有,普通反馈为 NULL |
-| `images` | JSON | nullable | 截图相对 URL 列表 `/media/feedback/...` |
-| `app_version` | String(32) | nullable | 提交时 App versionName(#94) |
-| `device_model` | String(64) | nullable | 机型 Build.MODEL(#94) |
-| `rom_name` | String(32) | nullable | ROM(OemDetector:ColorOS/MIUI/…,#94) |
-| `android_version` | String(16) | nullable | Android 版本(#94) |
-| `status` | String(16) | NOT NULL, default `pending`, index | `pending`(待处理)/ `adopted`(已采纳,#94)/ `rejected`(已拒绝)/ `handled`(旧「已处理」口径,兼容保留;历史另有 `new`) |
-| `reject_reason` | String(256) | nullable | 拒绝原因(用户可见) |
-| `reward_coins` | Integer | nullable | 采纳发的金币数(未发为 null;发币走 `coin_transaction`) |
-| `review_note` | String(256) | nullable | 运营内部备注(不外露) |
-| `admin_reply` | String(256) | nullable | **运营回复**(用户可见,#105;C 端反馈历史展示) |
-| `reviewed_by_admin_id` | Integer | nullable | 审核管理员 id(软指 `admin_user.id`) |
-| `reviewed_at` | DateTime(tz) | nullable | 审核时间 |
+| `contact` | String(128) | NOT NULL | 联系方式(微信/QQ/手机)。客户端改版后不再采集,新数据为空串;列仍 NOT NULL |
+| `images` | JSON | nullable | 截图相对 URL 列表 `/media/feedback/...`;无图为 NULL |
+| `status` | String(16) | NOT NULL, default `new` | 取值:`new`(待处理)/ `handled`(已处理) |
 | `created_at` | DateTime(tz) | server_default now(), index | 提交时间 |

 ## 关系 / Join Key
 - `user_id` → `user.id`(多对一)。
- admin 审核动作被 `admin_audit_log` 记录(`target_type='feedback'`);`reviewed_by_admin_id` 软指 `admin_user.id`(无硬 FK)。
- 采纳发奖时写 `coin_transaction`(发币入口 `grant_coins` 同事务)。
+- admin 处理时被 `admin_audit_log` 记录(`target_type='feedback'`、`target_id`=本行 id)。

 ## 索引与约束
- PK `id`;index `user_id`、`status`、`created_at`。
+- PK `id`;index `user_id`、`created_at`。

 ## 注意
 - `images` 用通用 `JSON`(本表**未**用 JSONB variant,与 comparison/savings 不同)。
- 状态机是单向的:`pending → adopted/rejected/handled`。`approve`/`reject` 只接受 `pending`(或历史 `new`)态,重复审核报 400;旧口径 `handle` **幂等不校验原状态**(重复调用结果一致)。
@@ -1,42 +0,0 @@
-# invite_cash_transaction — 邀请奖励金流水账本(分)
-
-> 模型 `app/models/wallet.py`(`InviteCashTransaction`) · 仓库 `app/repositories/wallet.py`(`grant_invite_cash` / 提现路径按 `source` 分账) · 接口 [wallet-account](../api/wallet/wallet-account.md)(余额)/ [wallet-withdraw](../api/wallet/wallet-withdraw.md)(`source=invite_cash` 提现) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
-
-**邀请奖励金**(现金,分)的流水账本,与金币兑换的 `cash_transaction` **物理隔离**、结构同构:`balance_after_cents` 记的是 `coin_account.invite_cash_balance_cents`。隔离原因:邀请奖励金有独立的发放口径(好友**比价并下单**才发,#113)与独立的提现对账(`withdraw_order.source='invite_cash'`,#121),混在现金账本里无法分账校验。#82 新增(2026-06-27)。
-
-## 用在哪 / 增删改查
- **C(插入)**:每次奖励金变动一笔:
-
-  | 动作 / endpoint | `biz_type` | `amount_cents` | `ref_id` 指向 |
-  |---|---|---|---|
-  | 好友比价并下单发奖(`POST /order/report` → `invite.try_reward_on_compare` → `grant_invite_cash`) | `invite_reward` | + | 被邀请人 `user.id`(字符串) |
-  | 发起提现 `POST /wallet/withdraw`(`source=invite_cash`) | `invite_withdraw` | − | `withdraw_order.out_bill_no` |
-  | 该提现失败/审核拒绝退款 | `invite_withdraw_refund` | + | `withdraw_order.out_bill_no` |
-  | admin 手动调整 `POST /admin/api/users/{id}/cash`(`account=invite_cash`,#95) | `admin_grant` / `admin_deduct` | + / − | null(原因记 `remark`=`admin:<reason>`) |
-
- **U / D**:无。账本只追加。
- **R**:admin 用户 360 / 提现资金账本校验 `GET /admin/api/withdraws/ledger-check`(按 `source` 分账对账,#121);C 端邀请页战绩(`invite.get_reward_stats`:余额 + 累计已提)。
-
-## 字段
-| 列 | 类型 | 约束 / 默认 | 说明 |
-|---|---|---|---|
-| `id` | Integer | PK, autoincrement | |
-| `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户(= 邀请人) |
-| `amount_cents` | Integer | NOT NULL | 本笔变动(分);正=入账(发奖/退款),负=出账(提现) |
-| `balance_after_cents` | Integer | NOT NULL | 本笔后奖励金余额(= 当时 `coin_account.invite_cash_balance_cents`) |
-| `biz_type` | String(32) | NOT NULL | `invite_reward` / `invite_withdraw` / `invite_withdraw_refund` |
-| `ref_id` | String(64) | nullable | 见上表:发奖=被邀请人 id;提现/退款=`withdraw_order.out_bill_no` |
-| `remark` | String(128) | nullable | 用户可见备注(如「好友比价奖励」「提现到微信零钱(待审核)」) |
-| `created_at` | DateTime(tz) | server_default now(), index | |
-
-## 关系 / Join Key
- `user_id` → `user.id`(多对一,硬 FK)。
- `ref_id` →(withdraw 类)`withdraw_order.out_bill_no`(软关联;该单 `source='invite_cash'`)/(invite_reward)被邀请人 `user.id`。
- 与 `invite_relation` 的联动:发奖同事务置 `invite_relation.compare_reward_granted=true`(幂等闸,一个被邀请人只发一次)。
-
-## 索引与约束
- PK `id`;index `user_id`、`created_at`。
-
-## 注意
- **唯一变动入口 `wallet.grant_invite_cash`**:更新 `coin_account.invite_cash_balance_cents` + 写本表,**不 commit**,调用方同事务提交(与 `grant_coins` 同款约定)。
- 提现按 `source` 走不同账本:`coin_cash` → `cash_transaction`,`invite_cash` → 本表;`withdraw_order` 两种共用一张表靠 `source` 列区分。
@@ -2,16 +2,15 @@

 > 模型 `app/models/invite.py`(`InviteRelation`) · 仓库 `app/repositories/invite.py` · 接口 `app/api/v1/invite.py`:`POST /api/v1/invite/bind`(写)、`GET /api/v1/invite/me`(战绩)、`GET /api/v1/invite/invitees`(列表) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

-一行 = 一次**成功的**邀请绑定。被邀请人(B)用邀请人(A)的邀请码完成绑定后写入,**绑定关系注册即生效,但绑定本身不发奖**(#113 起):发奖后置到 B **完成比价并实际下单**(`POST /order/report` → `try_reward_on_compare`),给 A 发**邀请奖励金**(入独立账本 [invite_cash_transaction](./invite_cash_transaction.md),非金币),本表 `compare_reward_granted` 做幂等闸。数据来自 `bind()`,触发它的归因来源有三种(`channel`)。这是邀请功能的**结果表 / 账本**;邀请码本身存在 `user.invite_code`,不在这张表。
+一行 = 一次**成功的**邀请绑定。被邀请人(B)用邀请人(A)的邀请码完成绑定后写入,**注册即生效**:同一事务里给 A、B 各发 1 万金币(= 1 元,可提现)。数据来自 `bind()`,触发它的归因来源有三种(`channel`)。这是邀请功能的**结果表 / 账本**;邀请码本身存在 `user.invite_code`,不在这张表。

 ## 用在哪 / 增删改查
- **C(插入)**:`POST /api/v1/invite/bind`(`bind_invite`)→ `invite_repo.bind()`。过四道防线后建一行 `status='effective'`。**#113 起绑定只建关系、不发奖**(`inviter_coin`/`invitee_coin` 新行恒 0)。
-  - **幂等键 = `invitee_user_id` 唯一**:一个 B 只能被绑一次,重复请求返回 `already_bound`(仿 `ad_reward_record.trans_id` 思路)。并发下两请求同时插同一 invitee → 后者撞唯一约束 `IntegrityError`,`bind()` rollback 后改判 `already_bound` 兜底。
-  - 四道防线(`bind()` 内):① invitee 已绑 → `already_bound`;② 无效码 / 邀请人非 `active` → `invalid_code`;③ 自邀(inviter==invitee)→ `self_invite`;④ 新人闸 `_is_new_user`(B 的 `created_at` 在 `rewards.INVITE_NEW_USER_WINDOW_HOURS`=72h 内)→ 否则 `not_eligible`。
- **U(发奖,#113)**:B 比价后下单 `POST /order/report` → `try_reward_on_compare(invitee_user_id)`:`compare_reward_granted=False` 才发 → 置 `True` + 记 `compare_reward_cents`/`compare_rewarded_at`,**同事务** `wallet.grant_invite_cash` 给 A 入邀请奖励金 → "置闸 + 入账"原子,一个 B 只发一次。
- **D**:无。
+- **C(插入)**:`POST /api/v1/invite/bind`(`bind_invite`)→ `invite_repo.bind()`。过四道防线后建一行 `status='effective'`,**同事务**复用 `wallet.grant_coins` 给双方发金币(`grant_coins` 只 flush,由 `bind()` 统一 commit)→ "建关系 + 双方加金币"原子。
+  - **幂等键 = `invitee_user_id` 唯一**:一个 B 只能被绑一次,重复请求返回 `already_bound`,不重复发奖(仿 `ad_reward_record.trans_id` 思路)。并发下两请求同时插同一 invitee → 后者撞唯一约束 `IntegrityError`,`bind()` rollback 后改判 `already_bound` 兜底。
+  - 四道防线(`bind()` 内):① invitee 已绑 → `already_bound`;② 无效码 / 邀请人非 `active` → `invalid_code`;③ 自邀(inviter==invitee)→ `self_invite`;④ 新人闸 `_is_new_user`(B 的 `created_at` 在 `rewards.INVITE_NEW_USER_WINDOW_HOURS`=72h 内)→ 否则 `not_eligible`。只有全过才插行 + 发奖。
+- **U / D**:无。这张表只增不改不删(纯账本)。
 - **R**:
-  - `GET /api/v1/invite/me`(`my_invite`)→ `get_stats(inviter_id)`:`count(*)` 得已邀人数、`sum(inviter_coin)` 得累计金币(历史口径);另调 `get_reward_stats` 出邀请奖励金余额/累计已提(读 `coin_account.invite_cash_balance_cents` + `withdraw_order(source=invite_cash)`)。
+  - `GET /api/v1/invite/me`(`my_invite`)→ `get_stats(inviter_id)`:`count(*)` 得已邀人数、`sum(inviter_coin)` 得累计金币。
  - `GET /api/v1/invite/invitees`(`my_invitees`)→ `get_invitees(inviter_id, limit, offset)`:join `user` 出被邀请人列表(倒序分页),名字降级兜底 `nickname → wechat_nickname → 脱敏手机号`,`coins` 取 `inviter_coin`。

 ## 字段
@@ -21,18 +20,15 @@
 | `inviter_user_id` | Integer | FK→user.id, index, NOT NULL | 邀请人(A) |
 | `invitee_user_id` | Integer | FK→user.id, **UNIQUE**, index, NOT NULL | 被邀请人(B)。**唯一 = 幂等键**,一个 B 只能被归因一次 |
 | `channel` | String(16) | NOT NULL, default `clipboard` | 归因来源:`clipboard`(剪贴板自动)/ `manual`(手动填码)/ `fingerprint`(指纹反查兜底)。入库前 `[:16]` 截断 |
-| `status` | String(16) | NOT NULL, default `effective` | 当前只有 `effective`(绑定关系注册即生效)。「发奖后置」没有走 status,而是用下面的 `compare_reward_granted` 闸表达 |
-| `inviter_coin` | Integer | NOT NULL, default 0 | **历史留痕**(#113 前"绑定即发金币"时代给 A 发的金币,当时=10000);#113 起新绑定恒 0 |
-| `invitee_coin` | Integer | NOT NULL, default 0 | 同上,给 B 发的金币历史留痕;新绑定恒 0 |
-| `compare_reward_granted` | Boolean | NOT NULL, default false | **发奖幂等闸**(#113):B 首次「比价并下单」后置 true,一个 B 只给 A 发一次邀请奖励金 |
-| `compare_reward_cents` | Integer | NOT NULL, default 0 | 实发的邀请奖励金(分,留痕;改常量不影响历史行) |
-| `compare_rewarded_at` | DateTime(tz) | nullable | 发奖时间 |
+| `status` | String(16) | NOT NULL, default `effective` | 当前只有 `effective`(注册即生效)。**预留** `pending`/`effective`:将来若改"完成首单才生效"时启用 |
+| `inviter_coin` | Integer | NOT NULL, default 0 | 本次给 A 发的金币(记账留痕,=`rewards.INVITE_INVITER_COINS`=10000) |
+| `invitee_coin` | Integer | NOT NULL, default 0 | 本次给 B 发的金币(=`rewards.INVITE_INVITEE_COINS`=10000) |
 | `created_at` | DateTime(tz) | server_default now(), index | 绑定时间(= 列表倒序键) |

 ## 关系 / Join Key
 - `inviter_user_id` → `user.id`(硬 FK,多对一):一个 A 可邀多个 B。
 - `invitee_user_id` → `user.id`(硬 FK,**一对一**,唯一约束):一个 B 至多一行。
- 流水关联:**#113 前**的绑定发金币落 `coin_transaction`(`biz_type='invite_inviter'`/`'invite_invitee'`,`ref_id` 互指对方)——现为历史类型,新绑定不再产生;**#113 起**发奖落 [`invite_cash_transaction`](./invite_cash_transaction.md)(`biz_type='invite_reward'`,`ref_id=被邀请人 id`)。
+- 发金币时落 `coin_transaction`:`biz_type='invite_inviter'`(给 A,`ref_id=invitee.id`)/ `biz_type='invite_invitee'`(给 B,`ref_id=inviter.id`),双方 `ref_id` 互指对方便于对账。
 - `get_invitees` 用 `InviteRelation JOIN user ON user.id = invitee_user_id` 取被邀请人资料;`total` 单独 `count` 算 `has_more`。

 ## 索引与约束
@@ -43,8 +39,8 @@

 ## 注意
 - **防重复发奖三道**(`repositories/invite.py` docstring):① `invitee_user_id` 唯一(应用层 `_relation_of_invitee` 先查 + DB 唯一约束并发兜底);② 自邀屏蔽;③ 手机号天然唯一(每个 B = 一个真实手机号账号)= 限制刷量规模。
- **`status` 当前恒为 `effective`**(绑定关系维度);「发奖后置」由 `compare_reward_granted` 闸表达,没有引入 `pending` 状态。
- **金币留痕字段已冻结**:`inviter_coin`/`invitee_coin` 只反映 #113 前旧口径的历史发放额,便于对账;新奖励额看 `compare_reward_cents`。
+- **`status` 当前恒为 `effective`**:产品取"注册即生效"而非"完成首单才生效",`pending` 取值是为后者预留、目前不写入。
+- **`inviter_coin`/`invitee_coin` 是留痕字段**:写死当时发的金币值,即便日后改奖励常量,历史行仍保留发奖时的额度,便于对账。
 - **`channel` 三种取值**:`clipboard`(deferred-deeplink 主路径,落地页写剪贴板、首启读回)/ `manual`(用户在邀请页手输)/ `fingerprint`(剪贴板被覆盖时走指纹兜底,见 [invite_fingerprint](./invite_fingerprint.md));三者都汇入同一个 `bind()`,只 `channel` 不同。
- **风控演进**:#24 时代的缺口是"注册即发 1 万可提现金币、接码批量刷"——**#113 把发奖后置到真实比价+下单**(且发的是邀请奖励金独立账本),批量注册空号不再直接得利,刷奖成本显著抬高;inviter 总数上限等进一步风控仍待补。
+- **风控缺口(#24 设计文档「上线前还差什么」标注)**:1 万金币可提现且**邀请人无总数上限**,接码平台批量注册新号绑同码即可刷;上线前需加 inviter 上限 + 基础风控。当前 MVP 仅靠"手机号唯一 + 72h 新人闸"挡。
 - **alembic 多 head**:本表迁移 `invite_code_and_relation`(`down_revision=11a1d08c6f55`)与 `coupon_state_tables` 是同一父的兄弟迁移,合 main 前需建 merge 迁移,否则 prod `alembic upgrade head` 撞 `Multiple head revisions`(#24 设计文档已警示）。
@@ -1,6 +1,6 @@
 # withdraw_order — 提现单(现金 → 微信零钱)

-> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-withdraw](../api/wallet/wallet-withdraw.md) / [wallet-withdraw-status](../api/wallet/wallet-withdraw-status.md) / [wallet-withdraw-orders](../api/wallet/wallet-withdraw-orders.md) · admin [admin-withdraws-list](../api/admin/withdraws/admin-withdraws-list.md) / [admin-withdraw-refresh](../api/admin/withdraws/admin-withdraw-refresh.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)
+> 模型 `app/models/wallet.py` · 仓库 `app/repositories/wallet.py` · 接口 [wallet-withdraw](../api/wallet-withdraw.md) / [wallet-withdraw-status](../api/wallet-withdraw-status.md) / [wallet-withdraw-orders](../api/wallet-withdraw-orders.md) · admin [admin-withdraws-list](../api/admin-withdraws-list.md) / [admin-withdraw-refresh](../api/admin-withdraw-refresh.md) · [← 索引](./README.md) · [总览](./OVERVIEW.md)

 用户把现金余额提到微信零钱的工单。**含人工审核**(2026-06 起):发起即扣现金、进 `reviewing` 待审核、**不打款**;管理员后台审核通过才真正发起微信商家转账,拒绝则退款。

@@ -26,8 +26,7 @@ reviewing ──admin 审核拒绝──▶ rejected(已退款)
 |---|---|---|---|
 | `id` | Integer | PK, autoincrement | |
 | `user_id` | Integer | FK→user.id, index, NOT NULL | 归属用户 |
-| `out_bill_no` | String(64) | UNIQUE, index, NOT NULL | 商户单号(幂等键 + 微信查单键)。客户端可传(`[0-9A-Za-z_-]{8,32}`),不传则服务端 `uuid4().hex`。**被 `cash_transaction.ref_id` / `invite_cash_transaction.ref_id` 引用**(按 `source` 落对应账本) |
-| `source` | String(16) | NOT NULL, default `coin_cash` | 提现账户来源(#121 分账):`coin_cash`(金币兑换的现金,扣 `coin_account.cash_balance_cents`、流水落 `cash_transaction`)/ `invite_cash`(邀请奖励金,扣 `invite_cash_balance_cents`、流水落 [`invite_cash_transaction`](./invite_cash_transaction.md)) |
+| `out_bill_no` | String(64) | UNIQUE, index, NOT NULL | 商户单号(幂等键 + 微信查单键)。客户端可传(`[0-9A-Za-z_-]{8,32}`),不传则服务端 `uuid4().hex`。**被 `cash_transaction.ref_id` 引用** |
 | `amount_cents` | Integer | NOT NULL | 提现金额(分) |
 | `user_name` | String(64) | nullable | 提现实名;微信**达额转账要求实名**,发起时存下、审核打款时传给微信 |
 | `status` | String(16) | NOT NULL, default `reviewing` | 归一化状态:`reviewing`(待审核,已扣款未打款)/ `pending`(打款在途)/ `success` / `failed`(打款失败已退)/ `rejected`(审核拒绝已退) |
@@ -40,7 +39,7 @@ reviewing ──admin 审核拒绝──▶ rejected(已退款)

 ## 关系 / Join Key
 - `user_id` → `user.id`(多对一)。
- `out_bill_no` ← 被流水 `ref_id` 引用,**账本按 `source` 分**:`coin_cash` 单 → `cash_transaction`(`withdraw` − / `withdraw_refund` +);`invite_cash` 单 → `invite_cash_transaction`(`invite_withdraw` − / `invite_withdraw_refund` +)。admin `GET /admin/api/withdraws/ledger-check` 按 source 分账做「单 ↔ 流水」对账(#121)。
+- `out_bill_no` ← 被 `cash_transaction.ref_id` 引用(发起 `withdraw` 一笔 −,失败/拒绝 `withdraw_refund` 一笔 +)。
 - 打款方式依赖 `wechat_transfer_authorization`(用户有生效授权 → 免确认转账,否则确认模式)。

 ## 索引与约束
@@ -16,9 +16,9 @@
 ## 函数 / 异常
 | 函数 | 行为 |
 |---|---|
-| `send_code(phone) -> int` | 防刷检查(冷却)→ `secrets` 生成 N 位码 → **预占**(冷却/存码)→ mock 打日志 / real 调极光 → 失败**回滚预占**。返回距下次可发秒数 |
+| `send_code(phone) -> int` | 防刷检查(冷却 + 每日上限)→ `secrets` 生成 N 位码 → **预占**(冷却/计数/存码)→ mock 打日志 / real 调极光 → 失败**回滚预占**。返回距下次可发秒数 |
 | `verify_code(phone, code) -> bool` | mock 放行任意 6 位;real 比对存码,匹配即作废,失败累计到上限作废 |
-| `SmsError(msg, status_code)` | `status_code` 决定 HTTP 码:过频 **429**、供应商失败 **503**、号码无效 **400** |
+| `SmsError(msg, status_code)` | `status_code` 决定 HTTP 码:过频/每日超限 **429**、供应商失败 **503**、号码无效 **400** |

 ## 配置
 | 配置项 | 默认 | 说明 |
@@ -30,16 +30,17 @@
 | `SMS_SIGN_ID` | 31729 | 极光签名 ID |
 | `SMS_TEMPLATE_ID` | 1 | 极光模板 ID(变量名 `code`) |
 | `SMS_CODE_LENGTH` | 6 | 验证码位数(本服务生成;前端 code 4-8 位兼容) |
+| `SMS_DAILY_LIMIT_PER_PHONE` | 10 | 单号每日发送上限(防刷 + 控费) |
 | `SMS_MAX_VERIFY_ATTEMPTS` | 5 | 单码最多校验失败次数,超过作废(防爆破) |

 > **鉴权复用极光一键登录**:`/v1/messages` 用 `base64(JG_APP_KEY:JG_MASTER_SECRET)` 做 HTTP Basic Auth——短信与一键登录是**同一个极光应用**(同 AppKey)。**上线不需要额外凭证,只需 `SMS_MOCK=false`**(`JG_*` 一键登录已配)。

 ## 防刷(短信花钱 + `/sms/send` 在登录前无法 JWT 鉴权)
-> 2026-07-03 精简:登录风控只留「单号冷却 + 单设备频控」两道主策略(删单号每日上限、删登录纯 IP `rate_limit`);单码失败上限属验证码安全底线,保留。
-1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却(单号维度)
-2. 单设备(`device_id` + IP)每小时频控:`/sms/send` ≤ `SMS_SEND_MAX_PER_HOUR_PER_DEVICE`(5)、`/sms/login` ≤ `SMS_LOGIN_MAX_PER_HOUR`(5)——堵「换号绕开单号冷却」+ 挡登录撞库,在 `app/api/v1/auth.py` 内 `enforce_rate_limit`
-3. 单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废 + 验过即作废(一次性)
-4. 运维侧建议在极光控制台叠加:**IP 白名单**(只许服务器 IP)+ **防轰炸设置**
+1. 单号 `SMS_SEND_INTERVAL_SEC` 冷却
+2. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限
+3. 单 IP 频控:`/sms/send` 挂 `rate_limit(10,60)`、`/sms/login` 挂 `rate_limit(20,60)`
+4. 单码校验失败 `SMS_MAX_VERIFY_ATTEMPTS` 次即作废
+5. 运维侧建议在极光控制台叠加:**IP 白名单**(只许服务器 IP)+ **防轰炸设置**

 ## 极光错误码(节选,映射在 `_send_via_jiguang`)
 | code | 含义 | 处理 |
@@ -55,4 +56,4 @@
 3. 真机发一条验证:收到短信 + 能登录

 ## 已知局限
-**验证码存进程内存**:单 worker uvicorn 够用;重启丢码(用户重发即可);**多 worker / 多机不共享 → 冷却 / 校验失效**,扩 worker 前迁移到 DB/Redis。见 [待办与技术债](../guides/待办与技术债.md)。
+**验证码存进程内存**:单 worker uvicorn 够用;重启丢码(用户重发即可);**多 worker / 多机不共享 → 冷却 / 每日上限 / 校验失效**,扩 worker 前迁移到 DB/Redis。见 [待办与技术债](../guides/待办与技术债.md)。
@@ -3,7 +3,7 @@
 > 域名:`app-api.shaguabijia.com`(HTTPS,nginx 反代)
 > 仓库:`shaguabijia-app-server`
 > 接口协议详见 [`docs/api/`](./api/)(索引 + 一接口一文件)
-> 最后更新:2026-07-09(§1/§6.2 比价透传改「软鉴权 + trace_id 签发 + harvest 落库」不再是纯透传;§3 目录树补全到当前 22 个 v1 路由 + core 三 worker + utils/geo;§1 补 邀请奖励金/埋点/领券看板/设备存活;§5 美团 feed/top-sales 按城市过滤 #116;§7 45 张表、98 迁移;§8 部署对齐 ecs1 git-clone + systemd 定时器;§10 刷新。上一次 2026-06-23)
+> 最后更新:2026-06-23(§7 数据模型改为指向 OVERVIEW、§5 美团 CPS 对齐多 tab feed/4 接口、§6 厘清 coupon/step 有写库副作用 ≠ 纯透传壳、§6.5 补 `/internal/app-version`、Alembic 迁移数更新)

 ---

@@ -13,23 +13,17 @@

 | 能力 | 说明 |
 |---|---|
-| **账号与登录** | 极光一键登录 + 短信验证码登录(SMS_MOCK 切换)→ 签发 JWT;新手引导标记(设备+账号,含用户自助重置 #114) |
+| **账号与登录** | 极光一键登录 + 短信验证码登录(mock)→ 签发 JWT |
 | **用户资料** | 昵称 / 头像(上传图片含魔数嗅探) / 注销账号(软删除+匿名化) |
-| **美团 CPS 选品** | feed 多 tab(rec 离线库 / distance 实时)+ 销量榜,**按设备坐标离线反查城市、只出同城券**(#116);点击换推广链接(分佣);未配凭证降级返空 |
-| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,不鉴权,前端已接通)+ best-effort 写领券三表;`/coupon/session` 领券任务流水(admin 看板,#99) |
-| **外卖比价透传 + 落库** | `/intent/*` + `/price/step` + `/trace/finalize`、`/trace/epilogue` 透传 pricebot,**软鉴权 + 首帧签发 trace_id + harvest 三段式落 `comparison_record`**(2026-07 起,见 §6.2) |
-| **金币 / 现金钱包** | 金币账户/流水/兑换/微信绑定/提现单;**邀请奖励金独立账本**(#82,与现金物理隔离,`source` 分账提现 #121) |
-| **好友邀请** | 邀请码/落地页指纹归因;发奖口径=好友**比价并下单**(#113,发邀请奖励金) |
+| **美团 CPS 选品** | 透传美团联盟优惠券(外卖/到店)、点击换取推广链接(分佣)、未配凭证时降级返空 |
+| **领券透传** | `/coupon/step` 透传到 pricebot-backend(一键领券核心,MVP 不鉴权,前端已接通) |
+| **外卖比价透传** | `/intent/recognize` + `/price/step` 透传到 pricebot-backend(food MVP,MVP 不鉴权) |
+| **金币 / 现金钱包** | 金币账户/流水/兑换/微信绑定/提现单 11 端点 |
 | **签到 + 任务 + 省钱战绩** | 福利模块 |
-| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 信息流/Draw 结算(ad_type/feed_scene 分场景)+ 穿山甲后台收益日表拉取(#92) |
-| **帮助与反馈** | 反馈工单(来源/场景/端环境采集 + admin 采纳发币/拒绝/运营回复,#94/#105)+ 静态 `/media` 服务 |
-| **埋点** | `/analytics/events` 批量上报落 `analytics_event`(#83) |
-| **设备存活监控** | 无障碍心跳 + 掉线检出(worker,超时 1h #107)+ 召回 ack;admin 存活看板(#80) |
-| **平台配置 / OTA** | `/platform/*`:门面统计、feature flags、广告配置下发、App 版本检查更新(全不鉴权) |
-| **CPS 群发联盟** | `/c/{code}` 短链落地 + 微信授权 + 联盟对账(美团+京东 #90),运营台在 admin |
-| **运营后台 admin** | 独立子应用(8771,独立 JWT):用户/钱包/提现审核/反馈/大盘/收益报表/领券看板/RBAC 自定义角色(#117/#126)等,全量端点见 [api/README](./api/README.md) Admin 段 |
+| **看广告发奖** | 穿山甲 GroMore 激励视频 S2S 回调(SHA256 验签)+ 4 态 CTA 冷却 |
+| **帮助与反馈** | 用户提交反馈(含截图)+ 静态 `/media` 服务 |

-**"比价/领券"的执行核心在 pricebot-backend**(另一个 repo),本服务对 step 类接口做透传;但 2026-07 起比价透传**不再是纯壳**——app-server 直接负责比价记录落库(§6.2)。无爬虫、无 LLM,业务模型已扩展到 **45 张业务表**(见 §7 / [database/OVERVIEW.md](./database/OVERVIEW.md))。仓库根另有 `h5/`(mine 我的页 + shared bridge/api,#89,H5 化的我的页静态资源)。
+**本服务自身没有"比价"实现**——比价/领券业务的核心都在 pricebot-backend(另一个 repo),本服务对 step 类接口做"透传壳"。无爬虫、无 LLM,但**有钱包/福利等业务模型**(数据模型从早期 1 张 `user` 表已扩展到 **40 张业务表**,见 §7 / [database/OVERVIEW.md](./database/OVERVIEW.md))。

 ---

@@ -58,56 +52,81 @@

 ```
 app/
-├── main.py                  # FastAPI 入口:注册 21 个 v1 router + 4 个 internal router、CORS、
-│                            #   lifespan(预热 pricebot client + 离线地理库,启 3 个后台 worker)、
-│                            #   /media 静态服务 + /media/shaguabijia.apk 官网直链(强制下载头)
+├── main.py                  # FastAPI 入口:注册全部 router、CORS、/health、lifespan
 ├── api/
-│   ├── deps.py              # 共享依赖:get_current_user / OptionalUser(软鉴权) / get_db
-│   ├── internal/            # server→server 内部端点(X-Internal-Secret):app_version / launch_confirm / price / store
-│   └── v1/                  # 接口层(薄),21 个路由文件:
-│       ├── auth.py user.py feedback.py            # 登录 / 资料+引导(含 reset #114) / 反馈工单
-│       ├── coupon.py                              # 领券透传 step + session 流水 + prompt/completed 频控族
-│       ├── compare.py                             # 比价透传 + trace_id 签发 + harvest 落库(§6.2)
-│       ├── compare_record.py compare_milestone.py # 比价记录(鉴权兜底上报/列表/详情/stats)+ 里程碑
-│       ├── meituan.py                             # CPS 选品 4 端点(feed 多 tab / top-sales 按城市 #116)
-│       ├── wallet.py wxpay.py                     # 钱包/提现(source 分账 #121)/transfer-auth 族 + 微信回调 stub
-│       ├── signin.py tasks.py savings.py          # 福利
-│       ├── ad.py                                  # 激励视频 S2S + 信息流/Draw 结算 + eCPM/noshow/watch
-│       ├── invite.py order.py report.py           # 邀请 / 支付归因(触发邀请发奖 #113) / 上报更低价
-│       ├── analytics.py device.py platform.py     # 埋点 #83 / 无障碍存活 #65 / 门面+flags+ad-config+OTA
-│       └── cps_redirect.py                        # /c/{code} 短链落地 + 微信 OAuth(挂域名根)
-├── admin/                   # 运营后台独立子应用(8771,独立 JWT;app.main 不 import 它)
-│   ├── main.py deps.py security.py permissions.py # 入口 / 鉴权链 / RBAC 页面目录(#117)
-│   └── routers/             # 23 个路由:users wallet withdraw feedback(+qr) dashboard comparison
-│                            #   coupon_data device_liveness event_logs price_report onboarding
-│                            #   ops_marquee_seed ops_stat_config ad_audit ad_revenue ad_config
-│                            #   config admins roles(#126) audit auth cps
-├── schemas/                 # Pydantic 契约(17 个文件,与客户端对齐字段看这里)
-├── integrations/            # 外部 SDK(重逻辑):jiguang / meituan(S-Ca 签名) / sms / pangle / wxpay
-├── core/                    # 基础设施:config(+config_schema 运营可配项定义) / security / ratelimit /
-│   │                        #   rewards / media / logging / ad_cooldown / test_account(测试号免验证码 #69)
-│   ├── pricebot_router.py   # pricebot 多实例一致性 hash(ketama 1000 虚节点,按 trace_id 亲和)
-│   ├── pricebot_client.py   # 共享 httpx AsyncClient 单例(#87:免每请求重建 SSL 上下文、绕进程代理)
-│   ├── withdraw_reconcile_worker.py  # 提现对账 worker(lifespan 启动)
-│   ├── heartbeat_monitor_worker.py   # 无障碍心跳掉线检出 worker(#65,超时 1h #107)
-│   └── daily_exchange_worker.py      # 金币自动兑换 worker
-├── utils/                   # geo.py(离线经纬度→城市反查,~2.5M 行 CSV+KDTree,启动预热)
-│                            #   + meituan_city.py(城市→美团 city_id,#116)
-├── repositories/            # 数据访问 + 事务(28 个文件;comparison.py 含 harvest_running/done/abort 三段)
-├── models/                  # ORM 表结构(34 个文件,45 张业务表,见 database/OVERVIEW.md)
-└── db/                      # DeclarativeBase + engine/get_db(非 SQLite 启 pool 10+20)
+│   ├── deps.py              # 共享依赖:get_current_user(鉴权)、get_db(注入 session)
+│   └── v1/                  # 接口层(薄):解析请求 → 调 repositories/integration → 组装响应 + HTTP 错误码
+│       ├── auth.py          # 登录 6 端点(极光一键登录 / 短信 send+login / refresh / me / logout)
+│       ├── user.py          # 用户资料 3 端点(改昵称 / 上传头像 / 注销账号)
+│       ├── feedback.py      # 帮助与反馈 1 端点(提交反馈含截图)
+│       ├── coupon.py        # 领券透传 /coupon/step(转发 pricebot,MVP 不鉴权)
+│       ├── compare.py       # 外卖比价透传 /intent/recognize + /price/step(转发 pricebot,MVP 不鉴权)
+│       ├── compare_record.py# 比价记录 3 端点(上报 /compare/record + 列表 /compare/records + 详情;鉴权,区别于上面透传)
+│       ├── meituan.py       # 美团 3 端点 + feed 拼接(_interleave / _TOPIC_ROUNDS),未配 MT_CPS 凭证降级返空
+│       ├── wallet.py        # 钱包/提现 11 端点(余额/流水/兑换/绑微信/提现/查单)
+│       ├── signin.py        # 签到 2 端点(状态 / 执行签到)
+│       ├── tasks.py         # 一次性任务 2 端点(列表 / 领取)
+│       ├── savings.py       # 省钱 3 端点(汇总 / 战绩 / 明细)
+│       └── ad.py            # 看广告发奖 3 端点(穿山甲 S2S 回调 / 进度+本轮冷却 / 联调发奖)
+├── schemas/                 # Pydantic:API 收发的数据契约(与客户端对齐字段看这里)
+│   ├── auth.py
+│   ├── user.py              # 改昵称请求 + OkResponse
+│   ├── feedback.py          # 反馈出参(请求是 multipart,在 router 直接校验)
+│   ├── meituan.py
+│   ├── welfare.py           # 钱包/签到/任务/省钱 收发模型
+│   ├── compare_record.py    # 比价记录上报/列表/详情 收发模型(字段对齐 pricebot calibration + done.params)
+│   └── ad.py                # 看广告发奖收发模型
+├── integrations/            # 外部服务/SDK 客户端(重逻辑:签名/加解密/外部 HTTP)
+│   ├── jiguang.py           # 极光 REST 验 token + RSA 解密(多 padding 试错)
+│   ├── meituan.py           # 美团 CPS 网关签名 + query_coupon / get_referral_link
+│   ├── sms.py               # 短信验证码(mock,进程内存冷却表)
+│   ├── pangle.py            # 穿山甲激励视频发奖回调验签(SHA256,2026-05 从 core 移入)
+│   └── wxpay.py             # 微信支付 V3 商家转账(提现)+ code 换 openid(2026-05 从 core 移入)
+├── core/                    # 基础设施(无外部业务集成)
+│   ├── config.py            # pydantic-settings
+│   ├── security.py          # JWT 签发/校验
+│   ├── ratelimit.py         # 同 IP 滑动窗口限流依赖
+│   ├── rewards.py           # 发奖/兑换/提现额度等业务常量与换算(2026-05 加 VIDEO_ROUND_REQUIRED_COUNT / VIDEO_ROUND_COOLDOWN_SECONDS)
+│   ├── media.py             # 用户上传文件(头像/反馈截图)落盘 + 魔数嗅探 + 随机文件名
+│   └── logging.py
+├── repositories/            # 数据访问 + 事务(早期叫 crud,2026-05 统一并入此目录)
+│   ├── user.py              # get_user_by_id / by_phone / upsert_for_login / update_nickname / set_avatar_url / soft_delete_account
+│   ├── feedback.py          # 提交反馈写库
+│   ├── wallet.py            # 账户/流水/兑换/提现单(调 integrations/wxpay)
+│   ├── signin.py            # 签到记录 / 连续天数 / 档位
+│   ├── task.py              # 一次性任务领取
+│   ├── savings.py           # 省钱汇总 / 战绩 / 明细
+│   ├── comparison.py        # 比价记录 upsert(user_id+trace_id 幂等)+ best/saved/status 派生 + 分页
+│   └── ad_reward.py         # 看广告发奖(按 trans_id 幂等 + 每日上限 + 本轮冷却派生)
+├── models/                  # ORM 表结构
+│   ├── user.py              # user(含微信 openid/nickname/avatar)
+│   ├── feedback.py          # 用户反馈(content/contact/images JSON 列/status)
+│   ├── wallet.py            # 金币账户 / 金币流水 / 现金流水 / 提现单
+│   ├── signin.py            # 签到记录
+│   ├── task.py              # 任务领取记录
+│   ├── savings.py           # 省钱明细 / 店铺菜品 / dishes(PG 上 JSONB)
+│   ├── comparison.py        # 比价记录(完整明细;含 4 个 JSON(B) 列 + raw_payload;独立于 savings)
+│   └── ad_reward.py         # 看广告发奖记录
+└── db/
+    ├── base.py              # DeclarativeBase
+    └── session.py           # engine + get_db(非 SQLite 时启 pool: size=10/overflow=20/recycle=3600)

-h5/                          # H5 静态页(#89):mine 我的页 + shared bridge/api
-alembic/                     # 数据库迁移(98 个,含 14+ merge;单 head,见 §7)
-deploy/                      # systemd:app-server + admin 两服务;定时器 meituan-etl(选品 ETL)/
-│                            #   pangle-revenue(穿山甲收益,每天 10:30 #100)/daily-exchange;nginx 配置
-secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git)
-scripts/                     # init_postgres / migrate.sh / create_admin / 美团券 ETL(pull_meituan_coupons +
-│                            #   load_meituan_coupon_tsv) / sync_pangle_revenue(#92) / publish_apk /
-│                            #   reconcile_withdraws / reset_* / sim_pangle_callback / seed_mock_*(造数)
-tests/                       # pytest(外部集成全 monkeypatch,不打真 HTTP)
-run.sh                       # 本地启动(钉定 .venv 解释器 #75,先迁移再起服务)
-docs/api/ docs/database/ docs/integrations/ docs/guides/   # 文档(各自带索引)
+alembic/                     # 数据库迁移(versions/ 11+ 个迁移含 feedback_table / convert_dishes_jsonb / merge 等)
+deploy/                      # systemd(.service) + nginx(.conf)
+secrets/                     # 极光 RSA 私钥 / 微信支付证书(不入 git,仅 .gitkeep 占位)
+scripts/
+  ├── init_postgres.py       # 一键 PG 初始化:建用户 + 建库 + 写 .env + 跑迁移(2026-05 新增,见已知 bug §10)
+  ├── migrate.sh             # 单独跑 alembic upgrade head(部署/CI 用)
+  ├── reset_signin.py        # 重置今日签到
+  ├── reset_welfare.py       # 重置福利数据
+  ├── reconcile_withdraws.py # 提现对账
+  └── sim_pangle_callback.py # 模拟穿山甲回调
+tests/                       # pytest(auth / health / welfare / withdraw / ad_reward / coupon_proxy / compare_proxy)
+run.sh                       # 本地启动脚本(自动先跑迁移再起服务)
+docs/api/                    # API 接口文档(索引 README + 一接口一文件)
+docs/integrations/           # 集成层实现文档(SDK 签名/加解密/协议细节)
+docs/database/数据库迁移.md           # Alembic 迁移指南(如何建表/升级/新增迁移)
+docs/database/postgres-migration.md   # SQLite → PostgreSQL 切换指南(配套 scripts/init_postgres.py)
 ```

 > **命名说明**:`api/v1/` 的 `v1` 用于 URL 版本化(移动端无法强制即时升级,需新旧版本并存能力);`integrations` 装外部 SDK 集成、`repositories` 装数据访问、`core` 装基础设施,三者分离。**数据访问层统一在 `repositories/`**(早期叫 `crud/`,2026-05 已整体并入,`crud/` 不再存在)。`coupon.py` 是领券透传,勿与 `meituan.py` 里的 `coupons`(券列表)混淆。
@@ -150,7 +169,7 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 短信冷却表存进程内存(`--workers 1` 下够用,多 worker/重启即失效)。

-**real 模式(`SMS_MOCK=false`,生产)**:自定义验证码——本服务 `secrets` 生成 6 位码 → 极光 `/v1/messages` 只负责发 → 本地校验(一次性 / 防爆破),鉴权**复用 `JG_APP_KEY`/`JG_MASTER_SECRET`**(短信与一键登录同一极光应用,**上线只需 `SMS_MOCK=false`**)。防刷(单号冷却 + 单设备频控 + 单码失败次数;2026-07-03 精简删单号每日上限与登录纯 IP 限流)+ 错误码 429/503/400。详见 [integrations/sms](./integrations/sms.md)。
+**real 模式(`SMS_MOCK=false`,生产)**:自定义验证码——本服务 `secrets` 生成 6 位码 → 极光 `/v1/messages` 只负责发 → 本地校验(一次性 / 防爆破),鉴权**复用 `JG_APP_KEY`/`JG_MASTER_SECRET`**(短信与一键登录同一极光应用,**上线只需 `SMS_MOCK=false`**)。防刷四层(单号冷却 + 单号每日上限 + 单 IP `rate_limit` + 单码失败次数)+ 错误码 429/503/400。详见 [integrations/sms](./integrations/sms.md)。

 ### 4.3 Token 与刷新

@@ -171,15 +190,15 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 ### 5.2 对外四个接口

-> 接口级入参/出参/各 tab 行为详见 [api/meituan/meituan-feed.md](./api/meituan/meituan-feed.md) 等,本节只讲后端形态。
+> 接口级入参/出参/各 tab 行为详见 [api/meituan-feed.md](./api/meituan-feed.md) 等,本节只讲后端形态。

 - `coupons`:对外的搜索/榜单接口(底层 `query_coupon`),**客户端暂未接入**。
 - `feed`:首页推荐流,**已是多 tab**(入参 `tab`):
-  - `rec` 智能推荐:走**离线库 `meituan_coupon`**(筛佣金率≥3%、`DISTINCT ON` 去重、按销量降序分页),**纯库查询、不打美团、不依赖 MT 凭证**(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。**#116 起按城市过滤**:设备经纬度经 `utils/geo`(离线反查,启动预热)+ `meituan_city` 映射成美团 `city_id`,只出同城券;拿不到坐标/城市 → 返空 + `status=degraded`。
+  - `rec` 智能推荐:走**离线库 `meituan_coupon`**(筛佣金率≥3%、`DISTINCT ON` 去重、按销量降序分页),**纯库查询、不打美团、不依赖 MT 凭证**(实测同城热销中位佣金 ~0.8%,实时筛≥3% 每页剩 0–1 条又撞 402,故从库出)。不显示距离。
  - `distance` 距离最近:实时拉外卖+到店两路,按用户坐标由近及远。
  - 默认(空 tab):旧的逐轮分页混合 feed(2 外卖 + 1 到店交叉,写死 3 页爆款/今日必推/精选+限时,第 4 页返空),**仅老客户端兼容**。
  - 任何失败场景返 `200` + 空 `items` + `status=degraded`(不抛 5xx)。
- `top-sales`:独立的销量榜接口,离线库 `meituan_coupon` 按销量降序 + 跨源去重 + **同城过滤**(#116,同 rec 的城市反查),**不实时打美团**。
+- `top-sales`:独立的销量榜接口,离线库 `meituan_coupon` 按销量降序 + 跨源去重,**不实时打美团**。
 - `referral-link`:换推广链接,客户端取 `link_map["3"]`(deeplink)优先跳美团 App。
 - `query_coupon`:底层取数(被 `coupons`/`distance` feed 共用),不直接对外。

@@ -193,7 +212,7 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 ## 6. 领券透传(coupon/step)

-产品"一键领券"的核心接入点,**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。但 `coupon/step` **不是纯透传壳**:它在转发 pricebot 之余,还**best-effort 写库**。(比价透传 `compare.py` 2026-07 起同样带落库副作用,见 §6.2——现在全站已没有"只转发不写库"的透传端点,只有 `trace/epilogue` 例外。)
+产品"一键领券"的核心接入点,**真正的领券逻辑不在本服务**——在另一个 repo `pricebot-backend`(GoalEngine + 事件驱动)。但 `coupon/step` **不是纯透传壳**:它在转发 pricebot 之余,还**best-effort 写库**(纯透传壳是 `compare.py` 的 `intent/recognize`、`price/step`,它们只转发不写库)。

 ```
 客户端 → POST /api/v1/coupon/step  (任意 JSON body,含 device_id/trace_id/step)
@@ -212,29 +231,6 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert
 - **错误**:body 非合法 JSON → 400;pricebot 不可达或返回 5xx → 502。
 - **配置**:`PRICEBOT_BASE_URL`(默认 `http://localhost:8000`)、`PRICEBOT_REQUEST_TIMEOUT_SEC`(默认 30s,因领券单帧最多 wait 6s)。
 - **现状**:**前端已接通**——首页「去领取」→ `CouponPromptDialog` → 权限检查 → 无障碍引擎 `startCouponClaim` → 循环调本接口,逐张券下发 launch/wait/done。pricebot-backend 不在本目录。
- **配套**:`POST /coupon/session`(#99)由客户端**独立两段上报**(发起建行/收尾更新)落 `coupon_session` 流水,供 admin「领券数据」看板算发起数/完成率/中途流失/耗时——与 step 透传链路解耦。
-
---
-
-## 6.2 外卖比价透传:软鉴权 + trace_id 签发 + harvest 落库(2026-07)
-
-`compare.py` 的 `/intent/recognize`、`/intent/step`、`/intent/precoupon/step`、`/price/step`、`/trace/finalize`、`/trace/epilogue` 透传 pricebot 之余,**由 app-server 直接落库比价记录**(不再依赖客户端 POST /compare/record):
-
-```
-客户端首帧(可不带 trace_id)
-  → compare._forward:app-server 用 uuid 签发 trace_id、注入转发 body、回填响应顶层
-  → [harvest_running] 仅 mint 那帧:按 trace_id 建 comparison_record 的 running 行
-  → 后续帧原样透传(原始 bytes 快路,不再写库)
-  → done 帧(price/step)→ [harvest_done] 写 success/failed + 派生 best_*/saved_amount_cents
-  → 用户终止/未识别 → 客户端打 /trace/finalize → [harvest_abort] 写 cancelled/failed(不降级已 success)
-  → /trace/epilogue(#112):App 结果页截图透传入 trace,纯透传、不落库
-```
-
- **软鉴权(OptionalUser)**:新客户端带 JWT → 记录绑 `user_id`;老客户端不带 → `user_id` 暂空,由其后续带 JWT 的 `POST /compare/record` 上报补齐(灰度期两条写路径按 `trace_id` reconcile)。
- **写库全 best-effort**:`run_in_threadpool` + 独立 SessionLocal,失败只 warning、绝不连累比价返回(同 coupon.py 口径)。
- **trace_url** 从 pricebot 响应顶层取(pricebot 每帧都带);查看权限按 `user.debug_trace_enabled` 控制。
- **邀请发奖不在 harvest**:#113 口径 = 好友「比价并下单」,发放在 `POST /order/report`(`invite.try_reward_on_compare`,`compare_reward_granted` 幂等闸,发**邀请奖励金**入独立账本)。
- 透传基建:`core/pricebot_router.pick_pricebot`(按 trace_id 一致性 hash 选实例)+ `core/pricebot_client`(共享 httpx 单例,#87)。

 ---

@@ -244,13 +240,13 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 **启动确认窗兜底样本**(2026-06):国产 ROM 打开别的 App 时弹"想要打开 XX"确认窗,pricebot 对没见过文案(繁体/英文/ROM 改版)的窗用 LLM 兜底放行后,把样本 POST 到 [`/internal/launch-confirm-sample`](../app/api/internal/launch_confirm.py) 落 `launch_confirm_sample` 表(host 包 + 弹窗树 + LLM plan + 设备 locale/机型),供研发定期人工沉淀回 pricebot 的规则 yaml(回到快路径)。**需 pricebot 与 app-server 两边 `.env` 配同一 `INTERNAL_API_SECRET` 才生效**(未配则 pricebot 侧跳过上报、不影响比价/领券)。

-> 同类内部回写端点(同走 `X-Internal-Secret`)还有:`/internal/price-observation`(价格观测)、`/internal/store-mapping` + `/store-mapping/lookup` + `/store-mapping/invalidate`(跨平台店铺映射沉淀/反查/失效)等 pricebot 比价资产沉淀;`GET /internal/launch-confirm-samples`(#91,样本列表供 pricebot `distill_launch_confirm.py` 聚合沉淀回静态规则);以及 **`/internal/app-version`(OTA)**——**发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256 落 `app_config`,客户端再 `GET /api/v1/platform/app-version` 读做检查更新。完整 7 个内部端点见 [api/internal/internal.md](./api/internal/internal.md)。
+> 同类内部回写端点(同走 `X-Internal-Secret`)还有:`/internal/price-observation`(价格观测)、`/internal/store-mapping` + `/store-mapping/lookup` + `/store-mapping/invalidate`(跨平台店铺映射沉淀/反查/失效)等 pricebot 比价资产沉淀;以及 **`/internal/app-version`(OTA)**——**发布流程**(非 pricebot)出 APK 后写最新版本号/下载链接/sha256 落 `app_config`,客户端再 `GET /api/v1/platform/app-version` 读做检查更新。完整 6 个内部端点见 [api/internal.md](./api/internal.md)。

 ---

 ## 7. 数据模型

-**完整表清单不在本文维护**(避免双份漂移)——共 **45 张业务表** + `alembic_version` 框架表,逐表字段级说明 + 跨表关系/写入路径见 **[database/OVERVIEW.md](./database/OVERVIEW.md)**(总览)与 [database/README.md](./database/README.md)(一表一文件索引)。生产 PG / 开发可回退 SQLite。2026-06 下旬以来新增:`coupon_session`(#99)、`analytics_event`(#83)、`invite_cash_transaction`(#82)、`admin_role`(#117)、`ad_pangle_daily_revenue`(#92)。
+**完整表清单不在本文维护**(避免双份漂移)——共 **40 张业务表** + `alembic_version` 框架表,逐表字段级说明 + 跨表关系/写入路径见 **[database/OVERVIEW.md](./database/OVERVIEW.md)**(总览)与 [database/README.md](./database/README.md)(一表一文件索引)。生产 PG / 开发可回退 SQLite。

 本文只保留分层与高频维度的速查:数据访问统一在 `repositories/`,ORM 表结构在 `models/`(钱包/福利在 `wallet.py`/`signin.py`/`task.py`、比价在 `comparison.py`、领券今日状态在 `coupon_state.py`、CPS 群发在 `cps_*.py`、pricebot 内部沉淀在 `price_observation.py`/`store_mapping.py`/`launch_confirm_sample.py`、无障碍存活在 `device.py`)。下面单列最常用的 `user` 表字段。

@@ -269,15 +265,15 @@ POST /api/v1/auth/sms/login  { phone, code } → 任意 6 位通过 → upsert

 `upsert_user_for_login`:phone 存在则更新 `last_login_at`,不存在则注册(注册即登录)。

-**Alembic 迁移**:`alembic/versions/` 当前 **98 个迁移文件**(含 14+ 个合并迁移),当前单一 head `admin_user_pages_override`(2026-07-08,#126)。多人/多分支并行改表频繁产生多 head,靠 `alembic merge` 收敛回单 head。规模随改表增长,**别背具体链**,以 `alembic history`/`alembic heads` 实时输出为准。⚠️ revision id 长度 ≤32 字符(`alembic_version` 列宽,超长部署时截断报错——0.2.1 实踩)。详见 [数据库迁移.md](./database/数据库迁移.md)。
+**Alembic 迁移**:`alembic/versions/` 当前约 **78 个迁移文件**(含 14 个合并迁移),当前单一 head `4dc2af7ebe74`(2026-06-23 合并 #65 device 链 + comparison token 列两条并行链)。多人/多分支并行改表频繁产生多 head,靠 `alembic merge` 收敛回单 head。规模随改表增长,**别背具体链**,以 `alembic history`/`alembic heads` 实时输出为准。详见 [数据库迁移.md](./database/数据库迁移.md)。

 ---

 ## 8. 配置与部署

-配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`(默认 SQLite,生产应切 PG)、JWT(+独立 `ADMIN_JWT_SECRET`)、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / 多实例 `PRICEBOT_INSTANCES` / `PRICEBOT_REQUEST_TIMEOUT_SEC=30` / `PRICEBOT_COMPARE_TIMEOUT_SEC=60`)**、**内部密钥(`INTERNAL_API_SECRET`,internal 族)**、穿山甲(`PANGLE_*`,含收益 API)、微信支付(`WXPAY_*`)、**媒体存储(`MEDIA_ROOT=./data/media` / `MEDIA_URL_PREFIX=/media`)**、CORS;运营可覆盖的业务常量在 `core/config_schema.py` 定义、`app_config` 表落值(admin `GET/PATCH /config`)。
+配置见 `core/config.py`(pydantic-settings 读 `.env`)。分组:环境、`DATABASE_URL`(默认 SQLite,生产应切 PG)、JWT、极光(`JG_*`)、短信(`SMS_MOCK` 默认 true)、美团(`MT_CPS_*`)、**pricebot 上游(`PRICEBOT_BASE_URL` / `PRICEBOT_REQUEST_TIMEOUT_SEC=30` / `PRICEBOT_COMPARE_TIMEOUT_SEC=60`)**、**媒体存储(`MEDIA_ROOT=./data/media` / `MEDIA_URL_PREFIX=/media`)**、CORS。

-**生产部署(2026-06-06 起在 ecs1)**:双 systemd 服务 `shaguabijia-app-server.service`(uvicorn `127.0.0.1:8770`,`--workers 1`)+ `shaguabijia-admin.service`(8771),WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,nginx 443 反代 `app-api.shaguabijia.com` → 8770。**无 Docker**。**PostgreSQL 16** 同机部署。代码走 **git clone(main 分支)+ Gitea 只读部署密钥**,日常发布用服务器上的 `deploy` 一键命令 / `release.sh` 发车 / deploy.shaguabijia.com 发车台(不再 rsync 整目录;`secrets/` 私钥证书单独放置、不入 git)。
+**生产部署**:systemd `shaguabijia-app-server.service`(WorkingDirectory `/opt/shaguabijia-app-server`,`EnvironmentFile=.env`,uvicorn 监听 `127.0.0.1:8770`,`--workers 1`)+ nginx 443 反代 → 8770。**无 Docker**。**PostgreSQL 16** 同机部署。

 ```bash
 # 首次 PG 初始化(新机器或新环境):
@@ -285,13 +281,12 @@ ssh server "sudo apt install -y postgresql-16 && sudo systemctl enable --now pos
 ssh server "cd /opt/shaguabijia-app-server && .venv/bin/python scripts/init_postgres.py"
 # 该脚本会建业务用户 + 建库 + 写 .env 的 DATABASE_URL + 跑 alembic upgrade head

-# 日常部署(deploy 一键命令等价动作):
-ssh server "cd /opt/shaguabijia-app-server && git pull && .venv/bin/alembic upgrade head \
-  && systemctl restart shaguabijia-app-server shaguabijia-admin"
+# 后续日常部署:
+rsync -avz --exclude='.venv' --exclude='__pycache__' --exclude='data' --exclude='secrets/*.pem' ./ server:/opt/shaguabijia-app-server/
+scp secrets/jverify_rsa_private.pem server:/opt/shaguabijia-app-server/secrets/   # 私钥单独传,不入 git
+ssh server "cd /opt/shaguabijia-app-server && .venv/bin/alembic upgrade head && systemctl restart shaguabijia-app-server"
 ```

-**systemd 定时器**(`deploy/`,各带 .md 运维手册):`meituan-etl`(美团 CPS 选品 ETL → `meituan_coupon`,rec/top-sales 数据源)、`pangle-revenue`(穿山甲 GroMore 后台收益拉取,每天 10:30,#100)、`daily-exchange`(金币自动兑换;lifespan 里另有 in-process worker,两套并存以部署材料为准)。
-
 完整 PG 切换流程见 [docs/database/postgres-migration.md](./database/postgres-migration.md)。

 **生产 checklist(均为上线必查)**:
@@ -330,8 +325,8 @@ conda activate price          # 首次:pip install -e .
 | logout 无服务端失效 | 靠客户端清 token;后续加 jti 黑名单表(注销账号也是同问题——软删后旧 token 仍能用到自然过期) |
 | 美团接口无鉴权 + sid 可覆盖 | 评估加鉴权/锁定 sid(注意首页要求未登录可见) |
 | 美团接口未配凭证降级 | 未配 `MT_CPS_APP_KEY` 时 3 端点返空(不报 502),`/feed` 跟"已配但调用失败"路径无法区分——见 [integrations/meituan](./integrations/meituan.md) |
-| 领券/比价依赖 pricebot | 执行核心在 pricebot-backend;比价透传 2026-07 起带 harvest 落库(§6.2),领券 `coupon/step` 带三表副作用,均非纯壳 |
-| 领券 step 仍不鉴权;比价已软鉴权 | 比价透传族改 OptionalUser:带 JWT 即绑 `user_id`(用户级画像已能落到比价记录);`coupon/step` 仍拿不到 user_id(device 维度),老客户端比价记录靠 `/compare/record` 兜底补绑。见 [待办与技术债.md](./guides/待办与技术债.md) |
+| 领券/比价依赖 pricebot | `coupon/step` / `intent/recognize` / `price/step` 仅透传,真正逻辑在 pricebot-backend;前端已接通领券链路,比价 food MVP 也已接通 |
+| agent 系列接口 MVP 不鉴权 | 拿不到 user_id → 无法采集"哪个用户领了/买了什么"用户级画像(商业模式核心资产)。见 [待办与技术债.md](./guides/待办与技术债.md) P1 |
 | SMS 已接极光(2026-06-03) | real 模式自定义验证码,上线只需 `SMS_MOCK=false`(复用极光凭证)。详见 [integrations/sms](./integrations/sms.md) |
 | 短信冷却存内存 | 扩 worker 前需迁移到 Redis |
 | `MEDIA_ROOT` 进程内 serve | 头像/反馈截图当前用 FastAPI StaticFiles,生产建议 nginx 直 serve 该目录 |
@@ -68,14 +68,7 @@ def test_list_config(admin_client: TestClient, token: str) -> None:
    r = admin_client.get("/admin/api/config", headers=_auth(token))
    assert r.status_code == 200, r.text
    items = {i["key"]: i for i in r.json()}
-    # 非 hidden 项照常返回;看广告组保留可见的:每日上限 / 单次金币上限 / 关闭后冷却。
-    assert "signin_rewards" in items and "ad_daily_limit" in items and "ad_cooldown_sec" in items
-    # hidden 项(任务/里程碑、首页轮播数据源、看广告组的单次金币/每轮次数/信息流广告开关)不在配置页返回。
-    for hidden_key in (
-        "task_rewards", "record_milestones", "marquee_feed_mode",
-        "ad_reward_coin", "ad_round_count", "comparing_ad_enabled",
-    ):
-        assert hidden_key not in items, f"{hidden_key} 应被 hidden 过滤"
+    assert "signin_rewards" in items and "ad_daily_limit" in items
    assert items["signin_rewards"]["value"] == [
        200, 200, 300, 200, 400, 400, 800,
    ]
--- a/Show More
+++ b/Show More