运营后台后端:RBAC 权限管理 + 系统配置下发修复 + 比价记录店/商品搜索

一、RBAC 权限管理(角色 → 可见页面)
- 新增 admin_role 表 + 权限目录 permissions.py:角色持有一组页面 key,登录后左侧只展示这些页
- 内建角色 管理员(super_admin 全权锁定)/运营/财务/技术,页集对齐原型;key 承重(require_role 用),另加中文 label 展示
- 角色 CRUD 端点(仅 super_admin)+ 目录端点;登录/me 下发当前角色有效可见页
- admins 加删除、角色存在性校验;可复看已确定登录密码:UI 建的账号留存明文 plain_password,脚本建的超管不留存

二、系统配置下发修复
- 首页数据「保存即生效」:显式保存(apply_now)对 real/manual 直接落配置目标值、绕过只增不减护栏(修「改了 app 端不变」),护栏仍管自动 tick
- 首页轮播新增数据源三选一:mixed(真实优先+种子)/real(只真实)/seed(只种子),get_feed 分支 + /marquee-seeds/mode 端点
- 福利页 Tab 隐藏 任务/里程碑,及看广告的单次金币/每轮次数/信息流开关:CONFIG_DEFS 加 hidden + list_config 过滤,业务读取默认值不受影响

三、比价记录店/商品搜索
- comparison_record 加 product_names 派生列(从下单 items 拼商品名),迁移建列并回填历史行
- admin 比价记录列表店/商品分列可搜:走 product_names 普通列 LIKE,规避 SQLite JSON 中文 ensure_ascii 转义搜不到的坑

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

.env.example

@@ -29,7 +29,7 @@ JG_REQUEST_TIMEOUT_SEC=15
 
 # ===== 无障碍保护存活监控(pull 后置检测;本期不接推送)=====
 HEARTBEAT_MONITOR_ENABLED=true
-HEARTBEAT_TIMEOUT_MINUTES=10
+HEARTBEAT_TIMEOUT_MINUTES=60
 HEARTBEAT_SCAN_INTERVAL_SEC=60
 
 # ===== 短信 (mock 模式) =====

alembic/versions/761ef181ce7c_merge_jd_cps_order_fields_and_coupon_.py

@@ -0,0 +1,26 @@
+"""merge jd_cps_order_fields and coupon_session_origin_package heads
+
+Revision ID: 761ef181ce7c
+Revises: coupon_session_origin_package, jd_cps_order_fields
+Create Date: 2026-07-01 13:52:16.068808
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '761ef181ce7c'
+down_revision: Union[str, Sequence[str], None] = ('coupon_session_origin_package', 'jd_cps_order_fields')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

alembic/versions/admin_role_table.py

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

alembic/versions/admin_user_plain_password.py

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

alembic/versions/comparison_product_names.py

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

alembic/versions/comparison_record_trace_unique.py

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

alembic/versions/feedback_type_reply.py

@@ -0,0 +1,48 @@
+"""feedback 加反馈来源/场景/运营回复(source / scene / admin_reply)
+
+admin「用户反馈」页要展示并筛选「反馈类型」(比价反馈 / 普通反馈),并支持审核时给用户留言:
+  - source: 反馈来源入口(profile=「我的」页 / comparison=比价结果页)。NOT NULL,
+    旧数据 + 普通反馈默认 profile(server_default)。加索引供 admin 按类型筛选。
+  - scene: 比价反馈的问题场景(找错商品/优惠不对…),普通反馈为 NULL。
+  - admin_reply: 运营给用户的回复留言(用户端可见),随「我的反馈」历史下发。
+
+均为新增列(SQLite 原生支持 add_column);downgrade 的 drop_column 在 SQLite 走 batch 兜底。
+
+Revision ID: feedback_type_reply
+Revises: 761ef181ce7c
+Create Date: 2026-07-02 00:00:00.000000
+"""
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "feedback_type_reply"
+down_revision: str | Sequence[str] | None = "761ef181ce7c"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "feedback",
+        sa.Column(
+            "source",
+            sa.String(length=16),
+            nullable=False,
+            server_default="profile",
+        ),
+    )
+    op.add_column("feedback", sa.Column("scene", sa.String(length=32), nullable=True))
+    op.add_column("feedback", sa.Column("admin_reply", sa.String(length=256), nullable=True))
+    op.create_index("ix_feedback_source", "feedback", ["source"])
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("feedback") as batch_op:
+        batch_op.drop_index("ix_feedback_source")
+        batch_op.drop_column("admin_reply")
+        batch_op.drop_column("scene")
+        batch_op.drop_column("source")

app/admin/main.py

@@ -32,6 +32,7 @@ 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
@@ -98,6 +99,7 @@ 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)

app/admin/permissions.py

@@ -0,0 +1,80 @@
+"""admin 后台「页面权限目录」—— RBAC 的权限侧单一真源。
+
+一个权限 = 一个页面(= 左侧导航项)。角色持有一组 page key,登录后左侧只展示这些页(见前端
+layout.tsx 按 pages 过滤导航)。key 必须与前端路由一级对齐(/dashboard → "dashboard")。
+
+super_admin 为内建全权角色,恒可见全部页(effective_pages 特判)。新增页面 = 这里加一条 +
+前端导航加对应项(key 一致即可被各角色勾选可见)。
+"""
+from __future__ import annotations
+
+SUPER_ADMIN_ROLE = "super_admin"
+
+# 分组镜像前端导航(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)

app/admin/repositories/ad_audit.py

@@ -136,12 +136,16 @@ def _feed_scene_matches(rec: AdFeedRewardRecord, scene: str | None) -> bool:
     """该信息流记录是否落入请求的展示筛选 scene。
     - scene=="feed":ad_type in ("feed", NULL)(旧数据 NULL 视为 feed,向后兼容)
     - scene=="draw":ad_type=="draw"
+    - scene=="feed_all":所有信息流(feed/draw/NULL 都要)——业务已全切 Draw 信息流,收益报表把「Draw 信息流」
+      当作整个信息流口径(含历史误标 feed/NULL),用它避免筛选漏历史。
     - scene 为 None:不筛(两类都要)。
     """
     if scene == "feed":
         return rec.ad_type in (None, "feed")
     if scene == "draw":
         return rec.ad_type == "draw"
+    if scene == "feed_all":
+        return True
     return True
 
 
@@ -184,6 +188,7 @@ def _feed_rows(
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
+                "trace_id": rec.trace_id,
                 "app_env": rec.app_env,
                 "our_code_id": rec.our_code_id,
                 "created_at": rec.created_at,
@@ -209,6 +214,7 @@ def _feed_rows(
                 "record_id": rec.id,
                 "user_id": rec.user_id,
                 "ad_session_id": rec.ad_session_id,
+                "trace_id": rec.trace_id,
                 "app_env": rec.app_env,
                 "our_code_id": rec.our_code_id,
                 "created_at": rec.created_at,
@@ -241,7 +247,7 @@ def audit_rows(
     rows: list[dict] = []
     if scene in (None, "reward_video"):
         rows.extend(_reward_video_rows(db, date=date, user_id=user_id))
-    if scene in (None, "feed", "draw"):
+    if scene in (None, "feed", "draw", "feed_all"):
         rows.extend(_feed_rows(db, date=date, user_id=user_id, scene=scene))
     return rows
 

app/admin/repositories/ad_revenue.py

@@ -3,9 +3,11 @@
 只读。每行 = 一次广告事件(不再按用户聚合):
 - **激励视频**:一次观看 = 1 条展示(ad_ecpm)+ 1 条发奖(ad_reward),按 ad_session_id 合并成一行,
   直接给出 eCPM / 收益 + 状态 / 应发 / 实发 / 一致;点开看该条金币复算因子。
-- **信息流**:轮播每条展示各一行(impressionId 各自独立);整场发奖(ad_feed_reward,client_event_id)
-  与逐条展示无法对应,单独成「纯发奖」行。
-- 兜底:有展示无发奖(中途关 / 未达发奖)、有发奖无展示(未上报 eCPM)都各自成行。
+- **信息流(比价/领券)**:一次比价 / 一次领券 = 一条整场发奖(ad_feed_reward)一行,给出 eCPM /
+  发奖金币 + 应发 / 实发 / 一致;点开看金币复算因子。⚠️ draw 的逐条展示(ad_ecpm,impressionId 各自
+  独立、与整场发奖无公共键、无法归到「哪一次」)**不再单独占行**(2026-07 按「一次比价/领券放一块」调整)——
+  其展示数 / eCPM / 预估收益仍进全量统计(合计 / 趋势 / 分类大盘 / 穿山甲对照),只是主表不逐条铺开。
+- 兜底:激励视频有展示无发奖(中途关 / 未达发奖)、有发奖无展示(未上报 eCPM)仍各自成行。
 
 展示与收益来自 ad_ecpm_record(收益 = eCPM元 ÷ 1000);应发 / 实发金币复用金币审计逐条复算
 (ad_audit.audit_rows,与正式发奖同一公式口径,不另写公式)。合计与对账在全量上统计,
@@ -58,14 +60,6 @@ def _date_range(date_from: str, date_to: str) -> list[str]:
 _AUDIT_SCENES = {"reward_video", "feed", "draw"}
 
 
-def _event_ad_type(row: dict) -> str:
-    """纯发奖事件行的 ad_type:信息流行用 audit 带回的真实 ad_type(feed/draw),回退 feed;
-    激励视频行恒 reward_video。不再用 scene 硬映射,避免把 draw 丢成 feed。"""
-    if row["scene"] == "reward_video":
-        return "reward_video"
-    return row.get("ad_type") or "feed"
-
-
 # 发奖复算明细字段(展开下钻看「金币怎么算出来的」)——从 audit 行原样取这些 key。
 _REWARD_DETAIL_KEYS = (
     "record_id", "created_at", "status", "ecpm", "ecpm_factor", "units",
@@ -108,9 +102,14 @@ def ad_revenue_report(
     #    同时保留全量列表,未被展示合并的成「纯发奖」事件。
     reward_by_session: dict[tuple[int, str], list[dict]] = {}
     all_reward_rows: list[dict] = []
-    # 报表 ad_type 直接当 audit scene 用(取值一致);未知/无效 ad_type 不取发奖行。draw 在此被
-    # 正确传成 scene="draw",audit 会按 ad_type 筛出 Draw 发奖,不再丢成 feed。
-    audit_scene = ad_type if ad_type in _AUDIT_SCENES else None
+    # 报表 ad_type → audit scene:reward_video/feed 直传;**draw(前端「Draw 信息流」)映射成 feed_all**
+    # ——业务已全切 Draw,把「Draw 信息流」当作整个信息流口径(含历史误标 feed/NULL),否则筛选会漏历史。
+    if ad_type == "draw":
+        audit_scene = "feed_all"
+    elif ad_type in _AUDIT_SCENES:
+        audit_scene = ad_type
+    else:
+        audit_scene = None
     if ad_type is None or audit_scene is not None:
         for d in _date_range(date_from, date_to):
             for row in ad_audit.audit_rows(db, date=d, user_id=user_id, scene=audit_scene):
@@ -140,7 +139,10 @@ def ad_revenue_report(
     )
     if user_id is not None:
         stmt = stmt.where(AdEcpmRecord.user_id == user_id)
-    if ad_type is not None:
+    if ad_type == "draw":
+        # draw = 所有信息流展示(业务已全 Draw,含历史误标 feed);展示行只进统计,不占主表行
+        stmt = stmt.where(AdEcpmRecord.ad_type.in_(["draw", "feed"]))
+    elif ad_type is not None:
         stmt = stmt.where(AdEcpmRecord.ad_type == ad_type)
     for rec in db.execute(stmt).scalars():
         rwd = _pop_reward(rec.user_id, rec.ad_session_id)
@@ -165,6 +167,8 @@ def ad_revenue_report(
             ),
             "adn": rec.adn,
             "slot_id": rec.slot_id,
+            "sub_rewards": [],
+            "sub_count": 1,
         }
         if rwd is not None:
             ev.update({
@@ -184,33 +188,88 @@ def ad_revenue_report(
             })
         events.append(ev)
 
-    # 3) 未被展示合并的发奖行 → 「纯发奖」事件(信息流整场发奖 / 有发奖无展示)。
-    #    收益恒 0(收益只算展示侧,避免与展示行重复计)。
+    # 3) 未被展示合并的发奖行 → 事件:
+    #    - 激励视频(reward_video):逐条成「纯发奖」事件(每次一个 ad_session_id;有发奖无展示等)。
+    #    - 信息流(feed/draw):同一次比价/领券的多条广告共享**整场 ad_session_id**(客户端整场复用),
+    #      按 (user_id, ad_session_id) 聚成**一次比价 / 一次领券**父事件;sub_rewards 为组内逐条明细,
+    #      应发/实发取组内合计;业务已全 Draw → 类型统一 "draw"。session 缺失(极少旧数据)各自单独成组。
+    feed_groups: dict[tuple[int, str], list[dict]] = {}
     for row in all_reward_rows:
         if row["record_id"] in used_reward_ids:
             continue
+        if row["scene"] == "reward_video":
+            events.append({
+                "event_key": f"rwd-{row['record_id']}",
+                "report_date": row["_report_date"],
+                "user_id": row["user_id"],
+                "ad_type": "reward_video",
+                "feed_scene": row.get("feed_scene"),
+                "app_env": row.get("app_env"),
+                "our_code_id": row.get("our_code_id"),
+                "created_at": row["created_at"],
+                "hour": _cn_hour(row["created_at"]) if by_hour else None,
+                "has_impression": False,
+                "impressions": 0,
+                "ecpm": row["ecpm"],
+                "revenue_yuan": 0.0,
+                "adn": None,
+                "slot_id": None,
+                "has_reward": True,
+                "status": row["status"],
+                "expected_coin": int(row["expected_coin"]),
+                "actual_coin": int(row["actual_coin"]),
+                "matched": bool(row["matched"]),
+                "reward_detail": _reward_detail(row),
+                "sub_rewards": [],
+                "sub_count": 1,
+            })
+        else:
+            # 聚合单位 = 一次完整比价/领券流程:优先用 trace_id(比价带 comparisonTraceId、领券带 sessionTraceId,
+            # 整个流程不变;即使中途点广告致浮层关闭重弹、ad_session_id 变了,trace_id 仍不变 → 全流程聚成一行)。
+            # 无 trace_id(历史领券未上报 / 旧数据)回退整场 ad_session_id;再无则 record_id 各自成组、不误并。
+            grp_key = row.get("trace_id") or row.get("ad_session_id") or f"_rid-{row['record_id']}"
+            feed_groups.setdefault((row["user_id"], grp_key), []).append(row)
+
+    # 信息流分组 → 「一次比价 / 一次领券」父事件(收益恒 0:收益只算展示侧,避免与展示行重复计)。
+    for (uid, grp_key), group in feed_groups.items():
+        group.sort(key=lambda r: (r["created_at"], r["record_id"]))
+        rep = group[-1]  # 代表条(最新一条):时间/场景/应用/代码位取它
+        expected_sum = sum(int(g["expected_coin"]) for g in group)
+        actual_sum = sum(int(g["actual_coin"]) for g in group)
+        # 父行 eCPM:组内各条 eCPM(分)均值(展示用,各条不同);无有效值则取代表条
+        ecpm_fens = [rewards.parse_ecpm_fen(g["ecpm"]) for g in group if g.get("ecpm")]
+        avg_ecpm = str(round(sum(ecpm_fens) / len(ecpm_fens))) if ecpm_fens else rep.get("ecpm")
+        # 主表逐行显示用:这次发奖广告的预估收益之和(发奖侧 eCPM 折算,钳顶同展示侧)。只放进
+        # row_revenue_yuan 给主表逐行展示,不进 revenue_yuan/合计/趋势——避免与展示侧 total 重复计。
+        row_revenue = round(sum(
+            min(rewards.parse_ecpm_yuan(g["ecpm"]), rewards.AD_ECPM_MAX_FEN / 100.0) / 1000.0
+            for g in group if g.get("ecpm")
+        ), 6)
         events.append({
-            "event_key": f"rwd-{row['record_id']}",
-            "report_date": row["_report_date"],
-            "user_id": row["user_id"],
-            "ad_type": _event_ad_type(row),
-            "feed_scene": row.get("feed_scene"),
-            "app_env": row.get("app_env"),
-            "our_code_id": row.get("our_code_id"),
-            "created_at": row["created_at"],
-            "hour": _cn_hour(row["created_at"]) if by_hour else None,
+            "event_key": f"feedgrp-{uid}-{grp_key}",
+            "report_date": rep["_report_date"],
+            "user_id": uid,
+            "ad_type": "draw",  # 业务已全切 Draw 信息流,聚合行统一 draw
+            "feed_scene": rep.get("feed_scene"),
+            "app_env": rep.get("app_env"),
+            "our_code_id": rep.get("our_code_id"),
+            "created_at": rep["created_at"],
+            "hour": _cn_hour(rep["created_at"]) if by_hour else None,
             "has_impression": False,
             "impressions": 0,
-            "ecpm": row["ecpm"],
+            "ecpm": avg_ecpm,
             "revenue_yuan": 0.0,
+            "row_revenue_yuan": row_revenue,
             "adn": None,
             "slot_id": None,
             "has_reward": True,
-            "status": row["status"],
-            "expected_coin": int(row["expected_coin"]),
-            "actual_coin": int(row["actual_coin"]),
-            "matched": bool(row["matched"]),
-            "reward_detail": _reward_detail(row),
+            "status": rep["status"],  # 代表状态(逐条见展开)
+            "expected_coin": expected_sum,
+            "actual_coin": actual_sum,
+            "matched": all(bool(g["matched"]) for g in group),
+            "reward_detail": None,
+            "sub_rewards": [_reward_detail(g) for g in group],
+            "sub_count": len(group),
         })
 
     # 「场景」作为全局筛选(与 user_id/ad_type 一致):同时作用于明细、合计与 daily/hourly 趋势。
@@ -331,9 +390,20 @@ def ad_revenue_report(
     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 聚成一行(展开看逐条)。
+    # 信息流(draw/feed)的逐条展示(ad_ecpm,impressionId 各自独立、与整场发奖无公共键)不再单独占行
+    # ——其展示数 / eCPM / 预估收益已计入上面的全量统计(total_*、daily / hourly、type_stats、穿山甲对照),
+    # 只是主表不逐条铺开;逐条明细在父行展开里看(sub_rewards)。合计 / 趋势 / 分类大盘均基于全量 events,
+    # 不受此过滤影响;total / 分页只作用于主表行。
+    main_rows = [
+        e for e in events
+        if not (e["ad_type"] in ("draw", "feed") and e["has_impression"] and not e["has_reward"])
+    ]
+
     return {
-        "total": len(events),
-        "truncated": len(events) > offset + limit,
+        "total": len(main_rows),
+        "truncated": len(main_rows) > offset + limit,
         "total_impressions": total_impressions,
         "total_revenue_yuan": total_revenue_yuan,
         # 穿山甲后台收益合计(元):预估 revenue + 收益Api;非全量视图(带 user/类型/场景过滤)或无数据为 None。
@@ -347,5 +417,5 @@ def ad_revenue_report(
         "hourly": hourly,
         "type_stats": type_stats,
         "dau": dau,
-        "items": events[offset:offset + limit],
+        "items": main_rows[offset:offset + limit],
     }

app/admin/repositories/admin_role.py

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

app/admin/repositories/admin_user.py

@@ -20,12 +20,20 @@ def get_by_username(db: Session, username: str) -> AdminUser | None:
 
 
 def create_admin(
-    db: Session, *, username: str, password: str, role: str = "operator"
+    db: Session,
+    *,
+    username: str,
+    password: str,
+    role: str = "operator",
+    plain_password: str | None = None,
 ) -> AdminUser:
+    """建管理员。plain_password 非空则额外留存明文(后台 UI 建的账号传,供权限管理页复看);
+    脚本/起后台建账号不传(留 None → 前端不显示密码)。"""
     admin = AdminUser(
         username=username,
         password_hash=hash_password(password),
         role=role,
+        plain_password=plain_password,
     )
     db.add(admin)
     db.commit()

app/admin/repositories/mutations.py

@@ -65,16 +65,19 @@ def review_feedback(
     reward_coins: int | None = None,
     reject_reason: str | None = None,
     review_note: str | None = None,
+    admin_reply: str | None = None,
     commit: bool = True,
 ) -> Feedback:
-    """审核反馈:置 adopted/rejected + 记录奖励/原因/审核人/审核时间。
+    """审核反馈:置 adopted/rejected + 记录奖励/原因/回复留言/审核人/审核时间。
 
     发金币(wallet.grant_coins)由 router 在同一事务里调,确保状态、金币流水、审计一起提交。
+    admin_reply=给用户的回复留言(用户端可见),与 review_note(内部备注)区分。
     """
     feedback.status = status
     feedback.reward_coins = reward_coins
     feedback.reject_reason = reject_reason
     feedback.review_note = review_note
+    feedback.admin_reply = admin_reply
     feedback.reviewed_by_admin_id = reviewed_by_admin_id
     feedback.reviewed_at = datetime.now(CN_TZ).replace(tzinfo=None)
     if commit:

app/admin/repositories/queries.py

@@ -148,11 +148,14 @@ def list_comparison_records(
     phone: str | None = None,
     status: str | None = None,
     business_type: str | None = None,
+    store: str | None = None,
+    product: str | None = None,
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[ComparisonRecord], int | None, int]:
     """admin 比价记录列表(debug)。按 user_id 精确 或 phone 前缀定位用户 + status/业务类型筛,
-    offset 分页(创建时间倒序、id 兜底)。join User 取 phone/nickname 瞬态挂记录上。"""
+    store(店名)/product(商品名)子串模糊匹配,offset 分页(创建时间倒序、id 兜底)。
+    join User 取 phone/nickname 瞬态挂记录上。"""
     stmt = select(ComparisonRecord)
     if user_id is not None:
         stmt = stmt.where(ComparisonRecord.user_id == user_id)
@@ -166,6 +169,11 @@ 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)),
@@ -390,6 +398,7 @@ def list_all_withdraw_orders(
     *,
     user_id: int | None = None,
     status: str | None = None,
+    source: str | None = None,
     keyword: str | None = None,
     date_from: datetime | None = None,
     date_to: datetime | None = None,
@@ -409,6 +418,9 @@ def list_all_withdraw_orders(
         stmt = stmt.where(WithdrawOrder.user_id == user_id)
     if status:
         stmt = stmt.where(WithdrawOrder.status == status)
+    # 提现类型:coin_cash(福利页提现)/ invite_cash(邀请提现);None=全部
+    if source:
+        stmt = stmt.where(WithdrawOrder.source == source)
 
     kw = (keyword or "").strip()
     if kw:
@@ -534,6 +546,7 @@ def list_feedbacks(
     db: Session,
     *,
     status: str | None = None,
+    source: str | None = None,
     user_id: int | None = None,
     content: str | None = None,
     created_from: datetime | None = None,
@@ -543,13 +556,15 @@ def list_feedbacks(
     limit: int = 20,
     cursor: int | None = None,
 ) -> tuple[list[Feedback], int | None, int]:
-    """反馈工单列表。支持 状态 / 用户ID / 内容模糊 / 提交时间范围 筛选,按 id·提交时间排序。
-    **offset 分页**(cursor=offset):任意列排序下游标语义统一(同 [list_users]),代价是翻页期间
-    数据变动可能错位一条——admin 低频场景可接受。返回 (items, next_cursor, total),total 供页码分页。
-    created_at 为 timestamptz,日期入参统一转 tz-aware UTC 比较。"""
+    """反馈工单列表。支持 状态 / 反馈类型(source) / 用户ID / 内容模糊 / 提交时间范围 筛选,
+    按 id·提交时间排序。**offset 分页**(cursor=offset):任意列排序下游标语义统一(同 [list_users]),
+    代价是翻页期间数据变动可能错位一条——admin 低频场景可接受。返回 (items, next_cursor, total),
+    total 供页码分页。created_at 为 timestamptz,日期入参统一转 tz-aware UTC 比较。"""
     stmt = select(Feedback)
     if status:
         stmt = stmt.where(Feedback.status == status)
+    if source:
+        stmt = stmt.where(Feedback.source == source)
     if user_id is not None:
         stmt = stmt.where(Feedback.user_id == user_id)
     if content and content.strip():
@@ -806,6 +821,12 @@ def get_user_overview(db: Session, user_id: int) -> dict | None:
     }
 
 
+def _as_utc_naive(value: datetime) -> datetime:
+    """窗口入参 → UTC naive(= _as_utc 去时区),与库里按 naive UTC 存取的 created_at 同口径比较。
+    历史遗留:_window_conds 一直引用本函数却未定义(自定义区间会 NameError),此处补上。"""
+    return _as_utc(value).replace(tzinfo=None)
+
+
 def _window_conds(col, date_from: datetime | None, date_to: datetime | None) -> list:
     """把 [date_from, date_to] 转成对 col(created_at)的过滤条件;都为 None = 全量(注册至今)。"""
     conds = []
@@ -895,6 +916,13 @@ def user_reward_stats(
     }
 
 
+def _cn_wall_to_utc(dt: datetime) -> datetime:
+    """coin_transaction 存的是北京 wall-clock(naive,见 wallet.grant_coins「存北京 wall-clock」),转成 UTC naive,
+    与广告表(func.now() UTC)统一 —— 让本函数按同一绝对时刻排序、且前端 apiTime(把无时区时间当 UTC 再 +8 展示)
+    口径一致;否则签到会比实际多显示 8 小时(北京时间又被 +8)。"""
+    return dt.replace(tzinfo=rewards.CN_TZ).astimezone(timezone.utc).replace(tzinfo=None)
+
+
 def user_coin_records(
     db: Session,
     user_id: int,
@@ -915,6 +943,9 @@ def user_coin_records(
     offset = max(cursor or 0, 0)
     fetch = offset + limit + 1
     rows: list[dict] = []
+    # coin_transaction 存北京 wall-clock(其余表存 UTC);签到窗口边界 +8h 对齐北京,过滤/计数才不偏移 8 小时
+    signin_from = date_from + timedelta(hours=8) if date_from is not None else None
+    signin_to = date_to + timedelta(hours=8) if date_to is not None else None
 
     for rec in db.execute(
         select(AdRewardRecord)
@@ -958,7 +989,7 @@ def user_coin_records(
         .where(
             CoinTransaction.user_id == user_id,
             CoinTransaction.biz_type == "signin",
-            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+            *_window_conds(CoinTransaction.created_at, signin_from, signin_to),
         )
         .order_by(CoinTransaction.created_at.desc())
         .limit(fetch)
@@ -966,7 +997,8 @@ def user_coin_records(
         rows.append({
             "source": "signin",
             "source_label": "签到",
-            "created_at": rec.created_at,
+            # 北京 wall-clock → UTC,与广告记录统一(前端 apiTime 会 +8 回北京展示,不然签到会多 8 小时)
+            "created_at": _cn_wall_to_utc(rec.created_at),
             "ecpm": None,
             "coin": rec.amount,
         })
@@ -992,7 +1024,7 @@ def user_coin_records(
         + _count(
             CoinTransaction, CoinTransaction.user_id == user_id,
             CoinTransaction.biz_type == "signin",
-            *_window_conds(CoinTransaction.created_at, date_from, date_to),
+            *_window_conds(CoinTransaction.created_at, signin_from, signin_to),
         )
     )
     return rows[offset:offset + limit], (offset + limit if has_more else None), total

app/admin/routers/admins.py

@@ -5,6 +5,8 @@ from fastapi import APIRouter, Depends, HTTPException, Request
 
 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
+from app.admin.permissions import SUPER_ADMIN_ROLE
+from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.admin import AdminCreateRequest, AdminUpdateRequest
 from app.admin.schemas.auth import AdminOut
@@ -23,9 +25,23 @@ def _active_super_count(db: AdminDb) -> int:
     )
 
 
-@router.get("", response_model=list[AdminOut], summary="管理员列表")
+def _validate_role(db: AdminDb, role: str) -> None:
+    """角色必须是 super_admin 或 admin_role 表里已存在的角色,否则 400。"""
+    if role == SUPER_ADMIN_ROLE:
+        return
+    role_repo.ensure_builtin_roles(db)  # 空表(测试/全新库)兜底播种,再校验
+    if role_repo.get_role(db, role) is None:
+        raise HTTPException(status_code=400, detail=f"角色不存在: {role}")
+
+
+@router.get("", response_model=list[AdminOut], summary="管理员列表(含明文密码,super_admin 专属)")
 def list_admins(db: AdminDb) -> list[AdminOut]:
-    return [AdminOut.model_validate(a) for a in admin_repo.list_admins(db)]
+    out: list[AdminOut] = []
+    for a in admin_repo.list_admins(db):
+        item = AdminOut.model_validate(a)
+        item.password = a.plain_password  # 明文:仅本 super_admin 专属路由下发,供权限管理页复看
+        out.append(item)
+    return out
 
 
 @router.post("", response_model=AdminOut, summary="创建管理员")
@@ -34,8 +50,10 @@ 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)
     new = admin_repo.create_admin(
-        db, username=body.username, password=body.password, role=body.role
+        db, username=body.username, password=body.password, role=body.role,
+        plain_password=body.password,  # UI 建的账号留存明文,供权限管理页复看
     )
     write_audit(
         db, admin, action="admin.create", target_type="admin", target_id=new.id,
@@ -67,6 +85,9 @@ def update_admin(
     if demotes_super and _active_super_count(db) <= 1:
         raise HTTPException(status_code=400, detail="不能降级/禁用最后一个超级管理员")
 
+    if body.role is not None:
+        _validate_role(db, body.role)
+
     changes: dict = {}
     if body.role is not None and body.role != target.role:
         changes["role"] = {"before": target.role, "after": body.role}
@@ -77,6 +98,7 @@ def update_admin(
     if body.password is not None:
         changes["password"] = "reset"
         target.password_hash = hash_password(body.password)
+        target.plain_password = body.password  # 同步留存明文,权限管理页复看保持一致
     if not changes:
         raise HTTPException(status_code=400, detail="无任何变更字段")
     db.commit()
@@ -86,3 +108,27 @@ def update_admin(
         detail=changes, ip=get_client_ip(request), commit=True,
     )
     return AdminOut.model_validate(target)
+
+
+@router.delete("/{admin_id}", summary="删除管理员(带审计)")
+def delete_admin(admin_id: int, request: Request, admin: CurrentAdmin, db: AdminDb) -> dict:
+    target = admin_repo.get_by_id(db, admin_id)
+    if target is None:
+        raise HTTPException(status_code=404, detail="管理员不存在")
+    if admin_id == admin.id:
+        raise HTTPException(status_code=400, detail="不能删除自己")
+    # 防自锁:删掉某个 active super_admin 前,确认后仍至少剩 1 个,否则进「零可用超管」死局。
+    if (
+        target.role == "super_admin"
+        and target.status == "active"
+        and _active_super_count(db) <= 1
+    ):
+        raise HTTPException(status_code=400, detail="不能删除最后一个超级管理员")
+    username = target.username
+    db.delete(target)
+    db.commit()
+    write_audit(
+        db, admin, action="admin.delete", target_type="admin", target_id=admin_id,
+        detail={"username": username, "role": target.role}, ip=get_client_ip(request), commit=True,
+    )
+    return {"deleted": True}

app/admin/routers/auth.py

@@ -6,6 +6,7 @@ import logging
 from fastapi import APIRouter, Depends, HTTPException
 
 from app.admin.deps import AdminDb, CurrentAdmin
+from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.auth import AdminLoginRequest, AdminLoginResponse, AdminOut
 from app.admin.security import create_admin_token
@@ -17,6 +18,13 @@ 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 + 当前角色有效可见页(前端左侧导航按此过滤)。"""
+    out = AdminOut.model_validate(admin)
+    out.pages = role_repo.effective_pages_of(db, admin.role)
+    return out
+
+
 @router.post(
     "/login",
     response_model=AdminLoginResponse,
@@ -39,10 +47,10 @@ def login(req: AdminLoginRequest, db: AdminDb) -> AdminLoginResponse:
     return AdminLoginResponse(
         access_token=token,
         expires_in=expires_in,
-        admin=AdminOut.model_validate(admin),
+        admin=_admin_out_with_pages(admin, db),
     )
 
 
-@router.get("/me", response_model=AdminOut, summary="当前管理员")
-def me(admin: CurrentAdmin) -> AdminOut:
-    return AdminOut.model_validate(admin)
+@router.get("/me", response_model=AdminOut, summary="当前管理员(含有效可见页)")
+def me(admin: CurrentAdmin, db: AdminDb) -> AdminOut:
+    return _admin_out_with_pages(admin, db)

app/admin/routers/comparison.py

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

app/admin/routers/config.py

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

app/admin/routers/feedback.py

@@ -36,6 +36,8 @@ def _ensure_pending(fb: Feedback) -> None:
 def list_feedbacks(
     db: AdminDb,
     status: Annotated[str | None, Query()] = None,
+    # 反馈类型筛选:profile(普通反馈)/ comparison(比价反馈);None=全部
+    source: Annotated[str | None, Query(pattern="^(profile|comparison)$")] = None,
     user_id: Annotated[int | None, Query()] = None,
     content: Annotated[str | None, Query(max_length=100)] = None,
     created_from: Annotated[datetime | None, Query()] = None,
@@ -48,6 +50,7 @@ def list_feedbacks(
     items, next_cursor, total = queries.list_feedbacks(
         db,
         status=status,
+        source=source,
         user_id=user_id,
         content=content,
         created_from=created_from,
@@ -101,6 +104,7 @@ def approve_feedback(
         status="adopted",
         reward_coins=payload.reward_coins,
         review_note=payload.note,
+        admin_reply=payload.reply,
         reviewed_by_admin_id=admin.id,
         commit=False,
     )
@@ -123,6 +127,7 @@ def approve_feedback(
             "after": "adopted",
             "reward_coins": payload.reward_coins,
             "note": payload.note,
+            "reply": payload.reply,
         },
         ip=get_client_ip(request),
         commit=False,
@@ -152,6 +157,7 @@ def reject_feedback(
         status="rejected",
         reject_reason=payload.reason,
         review_note=payload.note,
+        admin_reply=payload.reply,
         reviewed_by_admin_id=admin.id,
         commit=False,
     )
@@ -166,6 +172,7 @@ def reject_feedback(
             "after": "rejected",
             "reason": payload.reason,
             "note": payload.note,
+            "reply": payload.reply,
         },
         ip=get_client_ip(request),
         commit=False,

app/admin/routers/ops_marquee_seed.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 from typing import Annotated
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
+from pydantic import BaseModel
 
 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, get_client_ip, get_current_admin, require_role
@@ -22,7 +23,11 @@ from app.admin.schemas.ops_marquee_seed import (
 )
 from app.models.admin import AdminUser
 from app.models.ops_marquee_seed import OpsMarqueeSeed
-from app.repositories import ops_marquee
+from app.repositories import app_config, ops_marquee
+
+
+class MarqueeModeUpdate(BaseModel):
+    mode: str  # mixed / real / seed
 
 router = APIRouter(
     prefix="/admin/api/marquee-seeds",
@@ -57,6 +62,33 @@ def preview_feed(
     return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit))
 
 
+# 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。
+@router.get("/mode", summary="首页轮播数据源模式(mixed/real/seed)")
+def get_feed_mode(db: AdminDb) -> dict:
+    """当前轮播取数模式:mixed=真实优先+种子补位(默认)/ real=只真实 / seed=只种子·合成。"""
+    return {"mode": ops_marquee.get_feed_mode(db)}
+
+
+@router.patch("/mode", summary="改首页轮播数据源模式(带审计)")
+def set_feed_mode(
+    body: MarqueeModeUpdate,
+    request: Request,
+    admin: Annotated[AdminUser, Depends(require_role("operator"))],
+    db: AdminDb,
+) -> dict:
+    if body.mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    before = ops_marquee.get_feed_mode(db)
+    app_config.set_value(db, "marquee_feed_mode", body.mode, admin_id=admin.id, commit=False)
+    write_audit(
+        db, admin, action="ops_marquee_seed.set_mode", target_type="config",
+        target_id="marquee_feed_mode", detail={"before": before, "after": body.mode},
+        ip=get_client_ip(request), commit=False,
+    )
+    db.commit()
+    return {"mode": body.mode}
+
+
 @router.post("", response_model=OpsMarqueeSeedOut, summary="新增轮播种子(带审计)")
 def create_seed(
     body: OpsMarqueeSeedCreate,

app/admin/routers/roles.py

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

app/admin/routers/withdraw.py

@@ -50,6 +50,8 @@ def list_withdraws(
     db: AdminDb,
     user_id: Annotated[int | None, Query()] = None,
     status: Annotated[str | None, Query()] = None,
+    # 提现类型筛选:coin_cash(福利页提现)/ invite_cash(邀请提现);None=全部
+    source: Annotated[str | None, Query(pattern="^(coin_cash|invite_cash)$")] = None,
     keyword: Annotated[str | None, Query(max_length=100)] = None,
     date_from: Annotated[datetime | None, Query()] = None,
     date_to: Annotated[datetime | None, Query()] = None,
@@ -69,6 +71,7 @@ def list_withdraws(
         db,
         user_id=user_id,
         status=status,
+        source=source,
         keyword=keyword,
         date_from=date_from,
         date_to=date_to,

app/admin/schemas/ad_revenue.py

@@ -94,6 +94,11 @@ class AdRevenueRow(BaseModel):
     impressions: int = Field(..., description="本行展示条数:有展示=1 / 纯发奖=0(供日汇总、趋势图复用)")
     ecpm: str | None = Field(None, description="eCPM 原始值(分/千次);展示行取展示值,纯发奖行取发奖采用值")
     revenue_yuan: float = Field(..., description="本次展示预估收益(元)= eCPM元 ÷ 1000;纯发奖行=0")
+    row_revenue_yuan: float | None = Field(
+        None,
+        description="主表逐行展示用的预估收益(元):一次比价/领券聚合行=该次发奖广告 eCPM 折算之和;"
+        "其它行为空(前端回退取 revenue_yuan)。不进合计/趋势,避免与展示侧重复计",
+    )
     adn: str | None = Field(None, description="实际填充 ADN 子渠道(pangle/gdt…);纯发奖行为空")
     slot_id: str | None = Field(None, description="底层 mediation rit(非我们配置的广告位 ID);纯发奖行为空")
     # ── 发奖侧 ──
@@ -106,6 +111,15 @@ class AdRevenueRow(BaseModel):
         None,
         description="发奖复算明细(eCPM/因子1/份数/LT/因子2/应发/实发/一致);点行展开下钻用,纯展示为空",
     )
+    sub_rewards: list[AdRevenueRecord] = Field(
+        default_factory=list,
+        description="一次比价/领券聚合行的组内逐条发奖明细(同一整场 ad_session_id 的多条广告);"
+        "点行展开渲染多行。激励视频/纯展示行为空(单条看 reward_detail)",
+    )
+    sub_count: int = Field(
+        1,
+        description="本行聚合的发奖条数:一次比价/领券=该次广告条数(≥1);激励视频/纯展示=1",
+    )
 
 
 class AdRevenueReportOut(BaseModel):

app/admin/schemas/admin.py

@@ -6,19 +6,19 @@ from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field
 
-_Role = Literal["super_admin", "finance", "operator"]
+# 角色不再硬编码枚举:改为任意角色名(自定义角色由 admin_role 表管理),存在性在路由层校验。
 
 
 class AdminCreateRequest(BaseModel):
     username: str = Field(..., min_length=3, max_length=64)
     password: str = Field(..., min_length=8, max_length=72)  # bcrypt ≤72 字节
-    role: _Role = "operator"
+    role: str = Field("operator", min_length=1, max_length=32)
 
 
 class AdminUpdateRequest(BaseModel):
     """改角色 / 启用禁用 / 重置密码,字段都可选(只改传了的)。"""
 
-    role: _Role | None = None
+    role: str | None = Field(None, min_length=1, max_length=32)
     status: Literal["active", "disabled"] | None = None
     password: str | None = Field(None, min_length=8, max_length=72)
 

app/admin/schemas/auth.py

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

app/admin/schemas/comparison.py

@@ -23,6 +23,7 @@ class AdminComparisonListItem(BaseModel):
     status: str
     information: str | None = None
     store_name: str | None = None
+    product_names: str | None = None   # 下单商品名派生串(顿号分隔;「商品」列展示 + 商品搜索)
     source_platform_name: str | None = None
     best_platform_name: str | None = None
     source_price_cents: int | None = None

app/admin/schemas/feedback.py

@@ -15,11 +15,17 @@ class FeedbackOut(BaseModel):
     user_id: int
     content: str
     contact: str
+    # 反馈来源入口:profile(「我的」页)/ comparison(比价结果页)——admin 展示/筛选「反馈类型」
+    source: str = "profile"
+    # 比价反馈的问题场景(找错商品/优惠不对…);普通反馈为 None
+    scene: str | None = None
     images: list[str] | None = None
     status: str
     reject_reason: str | None = None
     reward_coins: int | None = None
     review_note: str | None = None
+    # 运营给用户的回复留言(用户端可见,采纳/未采纳都可填)
+    admin_reply: str | None = None
     reviewed_by_admin_id: int | None = None
     reviewed_at: datetime | None = None
     created_at: datetime
@@ -39,12 +45,14 @@ class FeedbackApproveRequest(BaseModel):
         le=FEEDBACK_REWARD_MAX_COINS,
         description="采纳后发放金币数",
     )
-    note: str | None = Field(default=None, max_length=256, description="采纳要点/审核备注")
+    note: str | None = Field(default=None, max_length=256, description="采纳要点/审核备注(内部)")
+    reply: str | None = Field(default=None, max_length=256, description="给用户的回复留言,用户端可见")
 
 
 class FeedbackRejectRequest(BaseModel):
     reason: str = Field(min_length=1, max_length=256, description="未采纳原因,用户端可见")
     note: str | None = Field(default=None, max_length=256, description="运营内部审核备注")
+    reply: str | None = Field(default=None, max_length=256, description="给用户的回复留言,用户端可见")
 
 
 class FeedbackSummary(BaseModel):

app/admin/schemas/role.py

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

app/admin/schemas/user.py

@@ -17,6 +17,7 @@ class AdminUserListItem(BaseModel):
     status: str
     debug_trace_enabled: bool = False
     wechat_openid: str | None = None
+    wechat_nickname: str | None = None
     created_at: datetime
     last_login_at: datetime
 

app/admin/schemas/wallet.py

@@ -41,6 +41,8 @@ class WithdrawOrderOut(BaseModel):
     user_id: int
     out_bill_no: str
     amount_cents: int
+    # 提现类型:coin_cash(福利页提现,金币兑换的现金)/ invite_cash(邀请提现,邀请奖励金)
+    source: str = "coin_cash"
     user_name: str | None = None  # 提现实名(审核核对 + 打款用)
     status: str
     wechat_state: str | None = None

app/api/deps.py

@@ -54,5 +54,29 @@ 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)]

app/api/v1/auth.py

@@ -12,11 +12,11 @@ from __future__ import annotations
 
 import logging
 
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, HTTPException, Request, status
 
 from app.api.deps import CurrentUser, DbSession
 from app.core import test_account
-from app.core.ratelimit import enforce_rate_limit, rate_limit
+from app.core.ratelimit import enforce_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)之前 → 超限直接拦下、不真发短信。与路由上 IP 维度(10次/分钟)互补。
+    # 补「换手机号绕开单号 60s 冷却」的洞(冷却是单号维度,一机换号能绕);设备维度按机器封顶,
+    # 挡短信轰炸/烧钱。放在真发(send_code)之前 → 超限直接拦下、不真发短信。
     enforce_rate_limit(
         request,
         scope="sms-send-device",
@@ -125,7 +125,6 @@ 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)。
@@ -143,7 +142,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 次登录尝试。放在验证码校验
-    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破。与路由上 IP 维度的 sms-login 限流(同 IP)互补。
+    # **之前** → 输错验证码的失败尝试也计数,才挡得住撞库/爆破(另有单码失败 SMS_MAX_VERIFY_ATTEMPTS 次即作废兜底)。
     # ⚠️ 按设备而非手机号 → 一台机器换不同手机号刷登录也受限(防一机狂登多号);device_id 空(老客户端)时
     #    退化为该 IP 下所有空设备聚一桶,仍受限。
     enforce_rate_limit(

app/api/v1/compare.py

@@ -1,49 +1,114 @@
-"""外卖比价业务透传端点。
+"""外卖比价业务透传端点 + 后端 harvest 落库。
 
-把客户端的 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 绑定后才能做用户级画像)。
+把客户端 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)。
 
-- Phase 1 /intent/recognize:从源平台(淘宝闪购/美团/京东外卖)购物车页识别店名+菜品+
-  价格,一次性。
-- Phase 2 /price/step:多轮循环,在目标平台复现订单读到手价,直到 done。
+鉴权:软鉴权(OptionalUser)——新客户端带 JWT → 绑 user_id;老客户端不带 → user_id 暂空,
+由其后续 /compare/record 上报补(灰度期两条写路径按 trace_id reconcile,success 不被降级)。
 
-真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口只是透传壳。
-电商(ecom)那两个端点 food MVP 暂不需要,以后放开 scene 时再加 /ecom/intent/recognize
-和 /ecom/step 两行即可。
-
-pricebot 协议文档:
-  pricebot-backend/docs/main/02_api_protocol.md
+真正的目标驱动比价逻辑在 pricebot-backend(GoalEngine,另一个 repo),本接口是透传壳 + 落库。
+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"])
 
 
-async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
-    """把请求体原样转发给 pricebot-backend 的 {upstream_path}。
+# ============================================================
+# harvest 落库(阻塞 SQLAlchemy → run_in_threadpool,独立 SessionLocal,不阻塞事件循环;
+# 任何写库异常都吞掉、绝不连累比价透传返回 —— 同 coupon.py 现有 best-effort 写法)。
+# ============================================================
 
-    跟 coupon_step 同款透传壳:不鉴权、不做 schema 校验,仅读 device_id/trace_id/step
-    打日志。比价单帧是大上下文 / 逐帧 LLM,超时用 PRICEBOT_COMPARE_TIMEOUT_SEC(60s,
-    比领券的 30s 长)。
+
+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);后续帧不再写库。
     """
-    # 读原始字节,避免"反序列化→再序列化"的双重 JSON(省 ~一半透传 CPU,让 app-server
-    # 单 worker 也扛得住高并发)。只 json.loads 一次拿 trace_id 做亲和 + 打日志,转发时
-    # 直接发原始 bytes(content=raw),不重新 dumps。
     raw = await request.body()
     try:
         meta = json.loads(raw)
@@ -52,26 +117,41 @@ async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
     if not isinstance(meta, dict):
         meta = {}
 
-    # 按 trace_id 一致性 hash 选 pricebot 实例(同一比价的所有帧落同一进程,内存维护 state)
-    base = pick_pricebot(meta.get("trace_id"))
+    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)
     url = f"{base.rstrip('/')}{upstream_path}"
     timeout = settings.PRICEBOT_COMPARE_TIMEOUT_SEC
+    step = meta.get("step")
 
     logger.info(
-        "compare %s device_id=%s trace_id=%s step=%s",
-        upstream_path,
-        meta.get("device_id"),
-        meta.get("trace_id"),
-        meta.get("step"),
+        "→ 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)},
     )
 
+    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] request failed: %s", e)
+        logger.error(
+            "← pricebot %s 不可达: %s", upstream_path, e,
+            extra={"phase": "resp", "endpoint": upstream_path, "step": step,
+                   "error": "upstream_unreachable"},
+        )
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
             detail=f"pricebot upstream unreachable: {e}",
@@ -79,49 +159,112 @@ async def _passthrough(request: Request, upstream_path: str) -> dict[str, Any]:
 
     if resp.status_code >= 500:
         logger.error(
-            "[pricebot] 5xx status=%d body=%s",
-            resp.status_code,
-            resp.text[:500],
+            "← 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"},
         )
         raise HTTPException(
             status_code=status.HTTP_502_BAD_GATEWAY,
             detail=f"pricebot upstream returned {resp.status_code}",
         )
 
-    return resp.json()
+    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
 
 
-@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/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/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/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/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("/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("/price/step", summary="外卖比价 Phase 2 步进 (透传到 pricebot)")
-async def price_step(request: Request) -> dict[str, Any]:
-    return await _passthrough(request, "/api/price/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("/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")
+@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

app/api/v1/compare_record.py

@@ -1,15 +1,13 @@
-"""比价记录 endpoint(「我的比价记录」数据源)。
+"""比价记录 endpoint(「我的比价记录」+ admin 数据源)。
 
 路由前缀 `/api/v1/compare`:
-  POST /record         上报一次比价结果(幂等:同 user+trace_id 覆盖)
+  POST /record         (灰度期兼容)老客户端上报,按 **trace_id** 幂等 + 不降级 success
   GET  /records        比价记录列表(游标分页)
   GET  /records/{id}   单条详情(含 raw_payload 全量)
 
-**均需鉴权**(CurrentUser)——与同文件无关的不鉴权透传 `compare.py` 分开:那个是
-转发壳(MVP 不鉴权),这里是按用户维度落库的业务接口,必须有 user_id。
-
-注:本轮只做 server 端,客户端(android 仓)在 done 帧后调 POST /record 上报的改动
-另起一轮(见 app-server docs/待办与技术债.md P1)。
+**均需鉴权**(CurrentUser)。⚠️ 写路径现以 `compare.py` 透传壳的**后端 harvest** 为主
+(帧0 建 running 行 → done/finalize 落终态,新客户端不再 POST);本 POST /record 仅灰度期
+给老客户端用,与 harvest 按 trace_id reconcile。新版覆盖够高后可下线本 POST(阶段3)。
 """
 from __future__ import annotations
 
@@ -21,16 +19,15 @@ 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,
-    ComparisonRecordPage,
     ComparisonRecordOut,
+    ComparisonRecordPage,
 )
+from app.services.pricebot_llm_calls import fetch_llm_calls
 
 logger = logging.getLogger("shagua.compare_record")
 
@@ -53,18 +50,8 @@ def report_record(
     # 任务做,不阻塞上报响应(顺带给 pricebot 落盘留足余量)。upsert 已 commit,后台用
     # 独立 session 按 record id 回填 llm_calls + 派生 llm_call_count/retry_count。
     background_tasks.add_task(_backfill_llm_calls, rec.id, rec.trace_id)
-    # 邀请 v2 发奖:被邀请人完成一次【成功】比价 → 给邀请人发邀请奖励金(幂等,只发一次)。
-    # best-effort:发奖异常不影响比价上报本身(rec 已 commit),只 log;邀请人补偿靠后续对账。
-    if rec.status == "success":
-        try:
-            reward = crud_invite.try_reward_on_compare(db, user.id)
-            if reward.status == "granted":
-                logger.info(
-                    "invite compare reward granted inviter=%s invitee=%s cents=%s",
-                    reward.inviter_user_id, user.id, reward.reward_cents,
-                )
-        except Exception as e:  # noqa: BLE001 best-effort,发奖失败不阻塞上报
-            logger.warning("invite compare reward failed invitee=%s: %s", user.id, e)
+    # 注:邀请发奖已从"比价成功"挪到"实际下单"(见 api/v1/order.py report_order)——
+    # 冰拍板:被邀请人完成比价并实际下单才算邀请成功,仅完成比价不再发奖。
     logger.info(
         "compare record user=%s trace=%s biz=%s status=%s saved=%s (llm_calls backfill queued)",
         user.id,

app/api/v1/feedback.py

@@ -31,7 +31,18 @@ router = APIRouter(prefix="/api/v1/feedback", tags=["feedback"])
 _MAX_IMAGES = 6
 _CONTENT_MAX = 200
 _CONTACT_MAX = 128
+_SCENE_MAX = 32
 _VALID_RECORD_STATUS = {"pending", "adopted", "rejected"}
+_VALID_SOURCES = {"profile", "comparison"}
+
+
+def _resolve_source(source: str, scene: str) -> str:
+    """反馈来源:客户端显式传的 source 优先(profile / comparison);未传或非法时,
+    按 scene 有无派生——比价结果页反馈才带 scene,故 scene 非空即视作 comparison。"""
+    src = source.strip().lower()
+    if src in _VALID_SOURCES:
+        return src
+    return "comparison" if scene.strip() else "profile"
 
 
 def _app_status(db_status: str) -> str:
@@ -46,10 +57,12 @@ def _record_out(fb) -> FeedbackRecordOut:
     return FeedbackRecordOut(
         id=fb.id,
         content=fb.content,
+        scene=getattr(fb, "scene", None),
         images=fb.images or [],
         status=_app_status(fb.status),
         reject_reason=getattr(fb, "reject_reason", None),
         reward_coins=getattr(fb, "reward_coins", None),
+        admin_reply=getattr(fb, "admin_reply", None),
         created_at=fb.created_at,
     )
 
@@ -61,6 +74,11 @@ async def submit_feedback(
     content: str = Form(...),
     # 原型改版后客户端不再采集联系方式;保留字段以兼容旧端 + 后续可能复用,默认空串。
     contact: str = Form(default=""),
+    # 反馈来源入口:profile(「我的」页)/ comparison(比价结果页)。新端显式传;旧端不带 →
+    # 空串 → 按 scene 有无派生。admin 据此展示/筛选「反馈类型」。
+    source: str = Form(default=""),
+    # 比价结果页反馈的「问题场景」(找错商品/优惠不对…);普通反馈不带 → 空串 → 存 NULL。
+    scene: str = Form(default=""),
     # 提交端环境快照(admin 反馈页展示「提交版本号」「机型OS版本」);旧端不带 → 空串 → 存 NULL。
     app_version: str = Form(default=""),
     device_model: str = Form(default=""),
@@ -76,6 +94,8 @@ async def submit_feedback(
         raise HTTPException(status_code=400, detail="反馈内容过长")
     if len(contact) > _CONTACT_MAX:
         raise HTTPException(status_code=400, detail="联系方式过长")
+    scene = scene.strip()[:_SCENE_MAX]
+    resolved_source = _resolve_source(source, scene)
 
     files = [f for f in (images or []) if f is not None and f.filename]
     if len(files) > _MAX_IMAGES:
@@ -91,10 +111,13 @@ async def submit_feedback(
 
     fb = feedback_repo.create_feedback(
         db, user_id=user.id, content=content, contact=contact, images=urls,
+        source=resolved_source, scene=scene or None,
         app_version=app_version.strip(), device_model=device_model.strip(),
         rom_name=rom_name.strip(), android_version=android_version.strip(),
     )
-    logger.info("feedback id=%d user_id=%d images=%d", fb.id, user.id, len(urls))
+    logger.info(
+        "feedback id=%d user_id=%d source=%s images=%d", fb.id, user.id, resolved_source, len(urls)
+    )
     return FeedbackOut.model_validate(fb)
 
 

app/api/v1/order.py

@@ -1,9 +1,14 @@
+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"])
 
 
@@ -15,6 +20,20 @@ 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,

app/api/v1/user.py

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

app/core/config.py

@@ -68,7 +68,7 @@ class Settings(BaseSettings):
 
     # 无障碍保护存活监控后台任务(pull 后置检测;本期不接推送)
     HEARTBEAT_MONITOR_ENABLED: bool = True       # 总开关
-    HEARTBEAT_TIMEOUT_MINUTES: int = 10          # 多久没心跳算掉线(≈3 个客户端心跳周期)
+    HEARTBEAT_TIMEOUT_MINUTES: int = 60          # 多久没心跳算掉线(1 小时,避免短暂离线误判被杀)
     HEARTBEAT_SCAN_INTERVAL_SEC: int = 60        # 扫描周期
 
     # ===== 短信 =====
@@ -81,7 +81,6 @@ 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 包全流程联调用)=====

app/core/config_schema.py

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

app/core/logging.py

@@ -2,9 +2,15 @@
 
 业务代码用 `logger = logging.getLogger("shagua.xxx")` 即可, 本模块在 main.py 启动时调一次。
 
-- 控制台(stdout): 人类可读文本, 给 systemd / 本地看。
-- 文件 `logs/app-server.log`: 单行 JSON, 供阿里云 SLS/Logtail 采集(JSON 模式零正则);
-  异常栈作为字段内嵌不换行 → 每条日志一行。
+- 控制台(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 等过滤聚合。
 - 环境变量:
   - LOG_JSON_CONSOLE=1   控制台也输出 JSON
   - LOG_DIR / LOG_FILE   改落盘路径(默认 logs/app-server.log)
@@ -17,13 +23,36 @@ 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 友好)。异常栈内嵌为字段, 整条仍是一行。"""
+    """LogRecord → 单行 JSON(SLS/Logtail 友好)。trace_id 提到顶层、extra 键平铺, 异常栈内嵌。"""
+
     def __init__(self, service: str = "app-server"):
         super().__init__()
         self.service = service
@@ -35,10 +64,17 @@ 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:
@@ -46,6 +82,15 @@ 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
 
 
@@ -63,14 +108,17 @@ 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(
-            logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+            TextFormatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
         )
+    console.addFilter(ctx_filter)
     root.addHandler(console)
 
     # 文件: 单行 JSON, 供 Logtail 采集(自动轮转, 单文件 10MB, 保留 5 个)
@@ -82,6 +130,7 @@ 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)
 
     # 第三方库降噪

app/integrations/sms.py

@@ -8,15 +8,16 @@
     校验)→ 鉴权复用极光一键登录的 `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. 单号每日 `SMS_DAILY_LIMIT_PER_PHONE` 条上限(本文件)
-  3. 单设备(device_id)每小时频控(api 层 auth.sms_send 内 enforce_rate_limit)+ 极光控制台 IP 白名单/防轰炸(运维侧)。
+  2. 单设备(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
@@ -26,7 +27,6 @@ import logging
 import secrets
 import time
 from dataclasses import dataclass
-from datetime import datetime
 from threading import Lock
 
 import httpx
@@ -56,22 +56,17 @@ 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]:
@@ -80,10 +75,6 @@ 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:
@@ -102,17 +93,9 @@ 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 不持锁)---
@@ -123,7 +106,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)

app/models/__init__.py

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

app/models/admin.py

@@ -25,6 +25,9 @@ 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(用户+反馈+大盘)
     role: Mapped[str] = mapped_column(String(20), nullable=False, default="operator")
     # active / disabled

app/models/admin_role.py

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

app/models/comparison.py

@@ -39,16 +39,19 @@ _JSON = JSON().with_variant(JSONB(), "postgresql")
 class ComparisonRecord(Base):
     __tablename__ = "comparison_record"
     __table_args__ = (
-        # 同一用户同一次比价(trace_id)只存一条:客户端重试/误点重复上报时幂等覆盖。
-        UniqueConstraint("user_id", "trace_id", name="uq_comparison_user_trace"),
+        # trace_id 由 app-server 签发、全局唯一 → 一次比价一行,后端 harvest 按它 upsert。
+        # (原 (user_id,trace_id) 复合唯一改为 trace_id 单列:harvest 帧0 建行时 user_id 可能暂缺。)
+        UniqueConstraint("trace_id", name="uq_comparison_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)
-    user_id: Mapped[int] = mapped_column(
-        Integer, ForeignKey("user.id"), index=True, nullable=False
+    # 后端 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
     )
     # 仍记录设备号(同一用户多设备的行为区分 / 与不鉴权期 device_id 数据对账)
     device_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
@@ -83,6 +86,10 @@ class ComparisonRecord(Base):
 
     # ===== 订单概要 =====
     store_name: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    # 下单商品名拼接串(顿号分隔,从 items[].name 去重派生),供 admin 列表「商品」列展示 + 商品名搜索。
+    # items 是 JSON(SQLite 下 json.dumps ensure_ascii 把中文转义,无法直接 CAST+LIKE),故另派生成普通
+    # 文本列——跨库 LIKE 一致、可加索引。写路径(upsert_record / harvest_done)落库时同步派生。
+    product_names: Mapped[str | None] = mapped_column(String(512), nullable=True)
     total_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
     skipped_dish_count: Mapped[int | None] = mapped_column(Integer, nullable=True)
 

app/models/feedback.py

@@ -23,6 +23,14 @@ class Feedback(Base):
     )
     content: Mapped[str] = mapped_column(Text, nullable=False)
     contact: Mapped[str] = mapped_column(String(128), nullable=False)
+    # 反馈来源入口:profile(「我的」页反馈入口)/ comparison(比价结果页反馈入口)。
+    # admin 据此展示/筛选「反馈类型」。旧数据与「我的」页反馈均为 profile(server_default)。
+    # 客户端显式传 source 优先;未传时由 scene 有无派生(见 api/v1/feedback.submit_feedback)。
+    source: Mapped[str] = mapped_column(
+        String(16), nullable=False, default="profile", server_default="profile", index=True
+    )
+    # 比价反馈的「问题场景」(找错商品/优惠不对/比价太慢…),比价结果页反馈才有;普通反馈为 NULL。
+    scene: Mapped[str | None] = mapped_column(String(32), nullable=True)
     # 截图 URL 列表(相对路径,如 ["/media/feedback/u1_ab12.jpg"]);无图为 None
     images: Mapped[list[str] | None] = mapped_column(JSON, nullable=True)
     # 提交时的端环境快照(admin 排查用;客户端改版带上后的新反馈才有,历史数据为 NULL)
@@ -36,6 +44,9 @@ class Feedback(Base):
     reward_coins: Mapped[int | None] = mapped_column(Integer, nullable=True)
     # 审核批注:采纳时可写采纳要点,未采纳时也可保留运营侧备注
     review_note: Mapped[str | None] = mapped_column(String(256), nullable=True)
+    # 运营给用户的回复留言(**用户端可见**,采纳/未采纳都可填,随「我的反馈」历史下发)。
+    # 与 review_note(内部备注,用户不可见)、reject_reason(未采纳原因)区分开。
+    admin_reply: Mapped[str | None] = mapped_column(String(256), nullable=True)
     reviewed_by_admin_id: Mapped[int | None] = mapped_column(
         Integer, ForeignKey("admin_user.id"), nullable=True
     )

app/repositories/comparison.py

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

app/repositories/feedback.py

@@ -17,6 +17,8 @@ def create_feedback(
     content: str,
     contact: str,
     images: list[str] | None,
+    source: str = "profile",
+    scene: str | None = None,
     app_version: str | None = None,
     device_model: str | None = None,
     rom_name: str | None = None,
@@ -26,6 +28,8 @@ def create_feedback(
         user_id=user_id,
         content=content,
         contact=contact,
+        source=source,
+        scene=scene or None,
         images=images or None,
         app_version=app_version or None,
         device_model=device_model or None,

app/repositories/invite.py

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

app/repositories/onboarding.py

@@ -5,7 +5,7 @@ device_id 为空(老客户端 / 取不到 ANDROID_ID)一律按"未完成"处理,
 """
 from __future__ import annotations
 
-from sqlalchemy import select
+from sqlalchemy import delete, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import Session
 
@@ -33,3 +33,18 @@ 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

app/repositories/ops_marquee.py

@@ -29,6 +29,17 @@ 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
+
+# 首页轮播数据源模式(存 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()
@@ -212,50 +223,56 @@ def get_feed(db: Session, limit: int = 8) -> list[dict]:
     展示时间统一「刷新」成相对现在的最近时刻(从 now 往前**随机抖动**递减),保证轮播永远像刚发生、
     节奏自然不机械(真实用户/金额不变,只换展示时间——避免旧测试数据 / 低谷期记录显示成过时时间)。
     """
-    # 真实条:取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
-    rows = _recent_real_rows(db)
+    mode = get_feed_mode(db)  # mixed / real / seed(运营可在「首页轮播种子」页切换)
 
     items: list[dict] = []
     used_names: set[str] = set()
-    seen_users: set[int] = set()
-    for uid, sc, nick in rows:
-        if uid in seen_users:
-            continue
-        seen_users.add(uid)
-        name = _mask_real(nick, uid)
-        used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
-        items.append({"masked_user": name, "saved_amount_cents": int(sc)})
-        if len(items) >= limit:
-            break
 
-    need = limit - len(items)
-    if need > 0:
-        seeds = db.execute(
-            select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
-        ).scalars().all()
-        # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
-        chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
-        _rng.shuffle(chosen)
-        for s in chosen:
-            # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
-            # 仅运营手动设的非模板真名才原样用。
-            fixed = (s.masked_user or "").strip()
-            name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
+    # 真实条(mixed / real):取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
+    if mode != "seed":
+        rows = _recent_real_rows(db)
+        seen_users: set[int] = set()
+        for uid, sc, nick in rows:
+            if uid in seen_users:
+                continue
+            seen_users.add(uid)
+            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 / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
+    # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
+    if mode != "real":
+        need = limit - len(items)
+        if need > 0:
+            seeds = db.execute(
+                select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True))
+            ).scalars().all()
+            # 公平随机抽取 need 个(池子够大则不放回抽样;否则全用并打散),让所有启用种子都有机会露出。
+            chosen = _rng.sample(seeds, need) if len(seeds) > need else list(seeds)
+            _rng.shuffle(chosen)
+            for s in chosen:
+                # 用户名:旧的「用户****xxx」统一模板名 / 留空 → 一律走新混合合成(避开同屏撞名、自愈历史种子);
+                # 仅运营手动设的非模板真名才原样用。
+                fixed = (s.masked_user or "").strip()
+                name = fixed if fixed and not fixed.startswith("用户****") else _unique_name(used_names)
+                used_names.add(name)
+                # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
+                lo = max(0, int(s.min_cents))
+                hi = max(lo, int(s.max_cents))
+                items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
+
+        # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
+        # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
+        while len(items) < limit:
+            name = _unique_name(used_names)
             used_names.add(name)
-            # 金额:在 [min,max] 取长尾随机值(小额居多、偶尔大额;固定金额则 min==max)。
-            lo = max(0, int(s.min_cents))
-            hi = max(lo, int(s.max_cents))
-            items.append({"masked_user": name, "saved_amount_cents": _skewed_amount(lo, hi)})
-
-    # 兜底:真实 + 种子仍凑不满 limit(种子被全停用 / 数量太少)→ 用内置合成补满,
-    # 保证轮播既不空也不稀疏(稀疏的几条循环同样像假)。
-    while len(items) < limit:
-        name = _unique_name(used_names)
-        used_names.add(name)
-        items.append({
-            "masked_user": name,
-            "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
-        })
+            items.append({
+                "masked_user": name,
+                "saved_amount_cents": _skewed_amount(_FALLBACK_MIN_CENTS, _FALLBACK_MAX_CENTS),
+            })
 
     # 统一赋「最近」时间:从 now 往前**随机抖动**递减,避免固定节奏被看出规律。
     # 首条几十秒前;其余多数 1~5 分钟,偶尔扎堆(20~55s)或较长(5~9 分钟),降序、像真实流水。

app/repositories/ops_stat.py

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

app/repositories/wallet.py

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

app/schemas/feedback.py

@@ -30,10 +30,14 @@ class FeedbackQrConfigOut(BaseModel):
 class FeedbackRecordOut(BaseModel):
     id: int
     content: str
+    # 比价反馈的问题场景(找错商品/优惠不对…);普通反馈为 None
+    scene: str | None = None
     images: list[str] = Field(default_factory=list)
     status: str
     reject_reason: str | None = None
     reward_coins: int | None = None
+    # 运营给用户的回复留言(用户端可见,采纳/未采纳都可能有)
+    admin_reply: str | None = None
     created_at: datetime
 
 

app/schemas/invite.py

@@ -69,6 +69,7 @@ class InviteeItem(BaseModel):
     avatar_url: str | None = None   # 头像 URL;null = 前端画默认色块
     coins: int                      # 这次邀请给我(邀请人)发的金币
     invited_at: datetime            # 邀请绑定时间(前端转"今天/3天前")
+    is_compared: bool = False       # 该好友是否已完成过一次比价(好友列表分"去提醒/邀请成功";在途列表只取 False)
 
 
 class InviteeListOut(BaseModel):

deploy/daily-exchange.service

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

deploy/daily-exchange.timer

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

docs/README.md

@@ -1,32 +1,83 @@
-# 后端文档库(docs/)
+# 文档索引
 
-`shaguabijia-app-server` 的文档都在这里。结构:**根目录放总览,其余按领域/用途分目录**。
+项目文档结构说明。后续大模型增补/更新文档时，按此分类找到对应目录。
 
-## 根目录
+---
 
-| 文档 | 作用 |
-|---|---|
-| [后端技术实现.md](./后端技术实现.md) | **后端技术方案总览**:业务概览、分层架构与目录、登录链路、美团 CPS、领券/比价透传、数据模型、配置与部署、已知问题。想了解"整个后端怎么回事"先看这份。 |
-| README.md | 本文件:文档库索引/传送门。 |
+## API 接口文档 (`api/`)
 
-## 子目录
+按业务领域分类，每个子目录对应一类接口。
 
-| 目录 | 作用 |
-|---|---|
-| [api/](./api/) | **API 接口文档**:"索引 + 一接口一文件"(组织方式见下)。想查"某个接口的协议"看这里。 |
-| [database/](./database/) | **数据库文档**:每张表一个文件(表结构/字段/索引/约定) + 两份迁移指南——[数据库迁移.md](./database/数据库迁移.md)(Alembic 操作:clone 后建表/日常升级/新增迁移/多 head 排查) + [postgres-migration.md](./database/postgres-migration.md)(SQLite → PostgreSQL 切换步骤,配套 `scripts/init_postgres.py`)。想"把库跑起来 / 改表结构 / 查某张表"看这里。 |
-| [integrations/](./integrations/) | **集成层实现文档**:穿山甲验签 / 微信支付 / 极光 / 短信 / 美团 CPS 等 SDK 集成的签名、加解密、协议细节与踩坑。想知道"接外部服务那块到底怎么实现"看这里。 |
-| [guides/](./guides/) | **开发 / 上线 / 功能 指南**:[待办与技术债.md](./guides/待办与技术债.md)(跨前后端 backlog,P1 鉴权/用户绑定、引擎移植待办等,"还欠什么、以后要补什么"看这份) + [看广告赚金币上线清单.md](./guides/看广告赚金币上线清单.md)(看广告发奖上线 checklist) + [邀请功能-实现原理与本地测试.md](./guides/邀请功能-实现原理与本地测试.md)(invite-mvp 实现原理 + 本地内网全链路测试) + [CPS发券分发与微信授权.md](./guides/CPS发券分发与微信授权.md)(**CPS 发券系统交接文档**:设群/建活动/生成落地页短链/美团对账/统计 + 微信网页授权拿 openid 做用户级统计;含数据流/表/平台差异/端点/配置/代码地图/排障/技术债)。 |
+### 分类目录
 
-## api/ 目录是怎么组织的(传送门式)
+| 目录 | 分类 | URL 前缀 | 说明 |
+|------|------|----------|------|
+| [api/auth/](api/auth/) | 认证 | `/api/v1/auth` | 用户登录（极光一键登录/短信验证码）、Token 刷新（access + refresh）、登出、当前用户信息查询 |
+| [api/ad/](api/ad/) | 广告 | `/api/v1/ad` | 穿山甲 S2S 回调验签发奖、激励视频/信息流广告奖励结算、eCPM 上报、发奖状态查询、测试发奖（仅本地） |
+| [api/wallet/](api/wallet/) | 钱包 | `/api/v1/wallet` | 账户资产查询（金币/现金余额）、金币与现金流水、兑换规则与执行、绑定/解绑微信、提现申请/状态/记录、免确认收款授权 |
+| [api/coupon/](api/coupon/) | 领券 | `/api/v1/coupon` | CPS 领券透传（step/session）、引导窗频控（should-show/shown/dismiss/reset）、每日完成状态、累计领券统计 |
+| [api/compare/](api/compare/) | 比价记录 | `/api/v1/compare` | 比价记录上报/列表/详情/统计、比价战绩里程碑查询及奖励领取（按成功比价数解锁金币） |
+| [api/savings/](api/savings/) | 省钱 | `/api/v1/savings` + `/api/v1/platform/savings-feed` | 省钱大作战（battle）、省钱明细/汇总、平台省钱动态 Feed |
+| [api/signin/](api/signin/) | 签到 | `/api/v1/signin` | 每日签到执行、签到加速（看广告多领）、签到状态查询 |
+| [api/tasks/](api/tasks/) | 任务 | `/api/v1/tasks` | 任务列表查询、任务奖励领取（按 task_key） |
+| [api/invite/](api/invite/) | 邀请 | `/api/v1/invite` | 邀请码/分享链接生成、已邀请列表、邀请绑定（支持 clipboard/manual/fingerprint 三种归因） |
+| [api/user/](api/user/) | 用户 | `/api/v1/user` | 个人资料编辑（昵称）、头像上传、新手引导状态/完成标记、注销账号 |
+| [api/device/](api/device/) | 设备 | `/api/v1/device` | 设备注册/推送 token 更新、无障碍存活心跳、掉线检测（后置 pull）、告警确认 |
+| [api/platform/](api/platform/) | 平台配置 | `/api/v1/platform` | 平台统计数据、Feature Flag 开关、广告配置（穿山甲 ID）、App 版本更新检查（OTA）；全部不鉴权 |
+| [api/intent/](api/intent/) | 意图/电商 | `/api/v1/intent` + `/api/v1/price` + `/api/v1/ecom` | 比价意图识别（Phase 1 单次/多帧/预券）、电商意图识别、比价步进（Phase 2） |
+| [api/meituan/](api/meituan/) | 美团 CPS | `/api/v1/meituan` | 美团券列表/信息流/推广链接/销量榜；全部无鉴权 |
+| [api/other/](api/other/) | 其它 | 分散 | 健康检查、CPS 短链重定向（含微信 OAuth）、反馈提交/配置/记录、埋点上报、订单上报、更低价上报、Trace 收尾 |
+| [api/admin/](api/admin/) | 管理后台 | `/admin/api` | Admin 独立子应用，二级目录按子资源拆分：`auth/`(登录)、`users/`(用户管理/财务操作)、`wallet/`(流水查询)、`withdraws/`(提现审核/对账)、`feedbacks/`(反馈处理)、`admins/`(管理员管理)、`ad/`(广告对账/收益)；单文件留根：审计日志、数据大盘、跑马灯种子、统计概览 |
+| [api/internal/](api/internal/) | 内部接口 | `/internal` | 服务间调用（pricebot→app-server）：价格事实回写、店铺映射、启动确认样本、App 版本写入；X-Internal-Secret 鉴权 |
 
-接口多了之后,单个大文件会臃肿、难维护,所以拆成 **一个索引 + 一个接口一个文件**:
+### 接口索引入口
 
-- **[api/README.md](./api/README.md) — 入口/传送门**
-  一张总览表列出**全部接口**(方法、路径、鉴权),每行链接到该接口的独立文档;另含**通用约定**(错误码、时间格式等)和**复用数据结构**(`TokenPair` / `UserOut` / `CouponCard` 等)。它本身不展开每个接口的细节,只负责"指路"。
-- **api/<模块>-<接口>.md — 单接口文档**
-  每个接口一个文件,只写自己的入参 / 出参 / 错误码 / 说明。命名按 `<模块>-<接口>`,如 `auth-jverify-login.md`、`coupon-step.md`、`meituan-feed.md`。
+完整接口列表（含路径、方法、鉴权方式）见 [api/README.md](api/README.md)。
 
-**查某个接口的协议**:先打开 [api/README.md](./api/README.md) 的总览表 → 找到接口 → 点链接进对应文档。
+### 文档命名规则
 
-> **新增接口时**:在 `api/` 下加一个 `<模块>-<接口>.md`,并到 `api/README.md` 总览表里补一行链接。这样索引始终是唯一的"传送门",细节各自独立、互不干扰。
+单端点文档按 URL 路径命名：`{prefix}-{resource}.md`（如 `wallet-withdraw.md`、`auth-sms-send.md`）。
+含子资源的合并文档按族命名（如 `device-liveness.md` 覆盖 register/heartbeat/liveness/liveness-ack 四个端点）。
+文件名唯一确定文档位置：大类目录 + 文件名前缀 → 直接匹配。
+
+---
+
+## 数据库文档 (`database/`)
+
+数据库表结构说明，每表一个文件，[database/OVERVIEW.md](database/OVERVIEW.md) 为索引入口。
+
+---
+
+## 第三方集成 (`integrations/`)
+
+外部 SDK/API 集成架构与实现说明：[integrations/README.md](integrations/README.md)。
+
+| 文件 | 说明 |
+|------|------|
+| [jiguang.md](integrations/jiguang.md) | 极光一键登录（REST 验证 + RSA 解密） |
+| [pangle.md](integrations/pangle.md) | 穿山甲广告 S2S 回调 |
+| [wxpay.md](integrations/wxpay.md) | 微信支付 V3（提现/授权） |
+| [meituan.md](integrations/meituan.md) | 美团 CPS 网关 |
+
+---
+
+## 开发指南 (`guides/`)
+
+| 文件 | 说明 |
+|------|------|
+| [邀请功能-实现原理与本地测试.md](guides/邀请功能-实现原理与本地测试.md) | 邀请系统实现细节 |
+| [CPS发券分发与微信授权.md](guides/CPS发券分发与微信授权.md) | CPS 发券 + 微信网页授权流程 |
+| [看广告赚金币上线清单.md](guides/看广告赚金币上线清单.md) | 广告功能上线检查清单 |
+| [待办与技术债.md](guides/待办与技术债.md) | 待办事项与技术债务 |
+
+---
+
+## 架构与设计 (`superpowers/`)
+
+需求规格与设计文档，按 `YYYY-MM-DD-<topic>-design.md` 命名。
+
+---
+
+## 后端技术实现 (`后端技术实现.md`)
+
+后端整体技术架构说明。

docs/api/README.md

@@ -3,7 +3,7 @@
 > Base URL:生产 `https://app-api.shaguabijia.com`;本地联调 `http://<开发机>:8770`
 > 协议:HTTP / JSON,请求与响应体均 `application/json`,字段统一 **snake_case**
 > 鉴权:需鉴权的接口在请求头带 `Authorization: Bearer <access_token>`
-> 最后更新:2026-06-23（补全此前缺整族的端点:device 无障碍存活监控、internal 内部回写、CPS 短链落地、report/invite/wxpay,及 platform/coupon/feedback/user 的零散读端点;device/internal/cps-redirect 三族新建单文件文档。上一次 2026-06-18 补录比价透传端点与 `meituan/top-sales`）
+> 最后更新: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)。
 
 ---
@@ -12,146 +12,154 @@
 
 | # | 方法 + 路径 | 鉴权 | 详情 |
 |---|---|---|---|
-| 1 | `GET /health` | 无 | [详情](./health.md) |
-| 2 | `POST /api/v1/auth/jverify-login` | 无 | [详情](./auth-jverify-login.md) |
-| 3 | `POST /api/v1/auth/sms/send` | 无 | [详情](./auth-sms-send.md) |
-| 4 | `POST /api/v1/auth/sms/login` | 无 | [详情](./auth-sms-login.md) |
-| 5 | `POST /api/v1/auth/refresh` | 无 | [详情](./auth-refresh.md) |
-| 6 | `GET /api/v1/auth/me` | Bearer | [详情](./auth-me.md) |
-| 7 | `POST /api/v1/auth/logout` | Bearer | [详情](./auth-logout.md) |
-| 8 | `POST /api/v1/coupon/step` | 无 | [详情](./coupon-step.md)（透传 pricebot + best-effort 写 `coupon_*` 三表） |
-| 8a | `POST /api/v1/coupon/prompt/shown` | 无 | 引导窗弹出即上报（按 device+package+日记 `shown`,今天这个 App 不再自动弹）(无单独文档) |
-| 8b | `POST /api/v1/coupon/prompt/dismiss` | 无 | 用户拒绝/关闭引导窗（透传链路看不到拒绝,客户端通知）(无单独文档) |
-| 8c | `GET /api/v1/coupon/prompt/should-show` | 无 | 切到外卖 App 时是否还应弹引导窗（`device_id`+`package`)(无单独文档) |
-| 8d | `POST /api/v1/coupon/prompt/reset` | 无 | 重置今日引导窗 engagement（开发测频控用)(无单独文档) |
-| 8e | `GET /api/v1/coupon/completed-today` | 无 | 这台设备今天是否已跑完整轮领券（首页「去领取」卡置灰源)(无单独文档) |
-| 8f | `POST /api/v1/coupon/completed-today/reset` | 无 | 重置今日已完成（开发用)(无单独文档) |
-| 8g | `GET /api/v1/coupon/stats` | Bearer | 累计领券数（「我的」页战绩卡;按 user_id 聚合,**鉴权**)(无单独文档) |
-| 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan-coupons.md) |
-| 10 | `POST /api/v1/meituan/feed` | 无 | [详情](./meituan-feed.md) |
-| 11 | `POST /api/v1/meituan/referral-link` | 无 | [详情](./meituan-referral-link.md) |
-| 11a | `POST /api/v1/meituan/top-sales` | 无 | [详情](./meituan-top-sales.md)（销量榜:离线库 `meituan_coupon` 按销量降序 + 跨源去重,不实时打美团） |
+| 1 | `GET /health` | 无 | [详情](./other/health.md) |
+| 2 | `POST /api/v1/auth/jverify-login` | 无 | [详情](./auth/auth-jverify-login.md) |
+| 3 | `POST /api/v1/auth/sms/send` | 无 | [详情](./auth/auth-sms-send.md) |
+| 4 | `POST /api/v1/auth/sms/login` | 无 | [详情](./auth/auth-sms-login.md) |
+| 5 | `POST /api/v1/auth/refresh` | 无 | [详情](./auth/auth-refresh.md) |
+| 6 | `GET /api/v1/auth/me` | Bearer | [详情](./auth/auth-me.md) |
+| 7 | `POST /api/v1/auth/logout` | Bearer | [详情](./auth/auth-logout.md) |
+| 8 | `POST /api/v1/coupon/step` | 无 | [详情](./coupon/coupon-step.md)（透传 pricebot + best-effort 写 `coupon_*` 三表） |
+| 8a | `POST /api/v1/coupon/prompt/shown` | 无 | [详情](./coupon/coupon-prompt.md)（引导窗弹出即上报） |
+| 8b | `POST /api/v1/coupon/prompt/dismiss` | 无 | [详情](./coupon/coupon-prompt.md)（用户拒绝/关闭引导窗） |
+| 8c | `GET /api/v1/coupon/prompt/should-show` | 无 | [详情](./coupon/coupon-prompt.md)（切到外卖 App 时是否还应弹引导窗） |
+| 8d | `POST /api/v1/coupon/prompt/reset` | 无 | [详情](./coupon/coupon-prompt.md)（重置今日引导窗 engagement,开发测频控用） |
+| 8e | `GET /api/v1/coupon/completed-today` | 无 | [详情](./coupon/coupon-completed-today.md)（这台设备今天是否已跑完整轮领券） |
+| 8f | `POST /api/v1/coupon/completed-today/reset` | 无 | [详情](./coupon/coupon-completed-today.md)（重置今日已完成,开发用） |
+| 8g | `GET /api/v1/coupon/stats` | Bearer | [详情](./coupon/coupon-stats.md)（累计领券数,「我的」页战绩卡） |
+| 8h | `POST /api/v1/coupon/session` | 无 | [详情](./coupon/coupon/coupon-session.md)（领券流水上报,admin 看板数据源） |
+| 9 | `POST /api/v1/meituan/coupons` | 无 | [详情](./meituan/meituan-coupons.md) |
+| 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)（销量榜:离线库 `meituan_coupon` 按销量降序 + 跨源去重,不实时打美团） |
 | **比价透传**（前缀 `/api/v1`,外卖 MVP；与 `coupon/step` 同为透传 pricebot-backend；下按 Phase 流程列,均不鉴权） |||
-| 12 | `POST /api/v1/intent/recognize` | 无 | [详情](./compare-intent-recognize.md)（Phase 1 意图识别,单次,多数源） |
-| 12a | `POST /api/v1/intent/precoupon/step` | 无 | Phase 0 意图识别前先用券,仅美团源(透传,无单独文档) |
-| 12b | `POST /api/v1/intent/step` | 无 | Phase 1 多帧意图识别,仅淘宝源,循环到 done(透传,无单独文档) |
-| 13 | `POST /api/v1/price/step` | 无 | [详情](./compare-price-step.md)（Phase 2 步进） |
-| 13a | `POST /api/v1/trace/finalize` | 无 | 比价 trace 收尾上云,终止/未识别拿 trace_url(透传,无单独文档) |
+| 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-record-report.md) |
-| 12b | `GET /api/v1/compare/records` | Bearer | [详情](./compare-records.md) |
-| 12c | `GET /api/v1/compare/records/{id}` | Bearer | [详情](./compare-record-detail.md) |
-| 12e | `GET /api/v1/compare/stats` | Bearer | [详情](./compare-stats.md)（「我的」页省钱战绩卡:完成比价数 + 累计发现可省） |
+| 12a | `POST /api/v1/compare/record` | Bearer | [详情](./compare/compare-record-report.md) |
+| 12b | `GET /api/v1/compare/records` | Bearer | [详情](./compare/compare-records.md) |
+| 12c | `GET /api/v1/compare/records/{id}` | Bearer | [详情](./compare/compare-record-detail.md) |
+| 12e | `GET /api/v1/compare/stats` | Bearer | [详情](./compare/compare-stats.md)（「我的」页省钱战绩卡:完成比价数 + 累计发现可省） |
 | **比价战绩里程碑**（前缀 `/api/v1/compare`；福利页「记录比价战绩」,按成功比价数解锁逐档发金币） |||
-| 12d | `GET /api/v1/compare/milestones` | Bearer | [详情](./compare-milestones.md) |
-| 12e | `POST /api/v1/compare/milestones/{milestone}/claim` | Bearer | [详情](./compare-milestone-claim.md) |
+| 12d | `GET /api/v1/compare/milestones` | Bearer | [详情](./compare/compare-milestones.md) |
+| 12e | `POST /api/v1/compare/milestones/{milestone}/claim` | Bearer | [详情](./compare/compare-milestone-claim.md) |
 | **设备 / 无障碍存活监控**（前缀 `/api/v1/device`；心跳超时检出 + 掉线召回,#65） |||
-| D1 | `POST /api/v1/device/register` | Bearer | [详情](./device-liveness.md)（注册设备/更新极光 push token） |
-| D2 | `POST /api/v1/device/heartbeat` | Bearer | [详情](./device-liveness.md)（无障碍服务存活心跳,心跳也能自注册） |
-| D3 | `GET /api/v1/device/liveness` | Bearer | [详情](./device-liveness.md)（进 App 查本机是否被判掉线过） |
-| D4 | `POST /api/v1/device/liveness/ack` | Bearer | [详情](./device-liveness.md)（确认已弹引导,清掉线告警） |
+| D1 | `POST /api/v1/device/register` | Bearer | [详情](./device/device-liveness.md)（注册设备/更新极光 push token） |
+| D2 | `POST /api/v1/device/heartbeat` | Bearer | [详情](./device/device-liveness.md)（无障碍服务存活心跳,心跳也能自注册） |
+| D3 | `GET /api/v1/device/liveness` | Bearer | [详情](./device/device-liveness.md)（进 App 查本机是否被判掉线过） |
+| D4 | `POST /api/v1/device/liveness/ack` | Bearer | [详情](./device/device-liveness.md)（确认已弹引导,清掉线告警） |
 | **上报更低价**（前缀 `/api/v1/report`；众包纠偏,人工审核发奖） |||
-| R1 | `POST /api/v1/report` | Bearer | 提交上报（multipart:`comparison_record_id`/`reported_platform_id`/`reported_price`(元) + 1~4 张截图;原最低价反查 `comparison_record.best_*` 校验须更低）(无单独文档) |
-| R2 | `GET /api/v1/report/records` | Bearer | 上报记录列表（`?status=` pending/approved/rejected 可选筛选）(无单独文档) |
+| R1 | `POST /api/v1/report` | Bearer | [详情](./other/report-submit.md)（提交上报更低价,multipart:比价记录ID+平台+价格+截图1-4张） |
+| R2 | `GET /api/v1/report/records` | Bearer | [详情](./other/report-records.md)（上报记录列表,?status=pending/approved/rejected 可选筛选） |
 | **好友邀请**（前缀 `/api/v1/invite`；注册即生效,双方各发 1 万金币） |||
-| I1 | `GET /api/v1/invite/me` | Bearer | 我的邀请码 + 分享链接 + 已邀人数/已得金币(无单独文档) |
-| I2 | `GET /api/v1/invite/invitees` | Bearer | 我邀请的人列表（`limit`/`offset` 分页）(无单独文档) |
-| I3 | `POST /api/v1/invite/landing-track` | 无 | 落地页 `dl.html` 访问上报指纹(剪贴板归因兜底;浏览器无 token)(无单独文档) |
-| I4 | `POST /api/v1/invite/bind` | Bearer | 绑定邀请人;支持 clipboard/manual 邀请码 + fingerprint 指纹反查三种归因(无单独文档) |
+| 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） |
+| I4 | `POST /api/v1/invite/bind` | Bearer | [详情](./invite/invite-bind.md)（绑定邀请人;支持 clipboard/manual 邀请码+fingerprint 指纹反查三种归因） |
 | **钱包 / 我的资产**（前缀 `/api/v1/wallet`） |||
-| 14 | `GET /api/v1/wallet/account` | Bearer | [详情](./wallet-account.md) |
-| 15 | `GET /api/v1/wallet/coin-transactions` | Bearer | [详情](./wallet-coin-transactions.md) |
-| 16 | `GET /api/v1/wallet/cash-transactions` | Bearer | [详情](./wallet-cash-transactions.md) |
-| 17 | `GET /api/v1/wallet/exchange-info` | 无 | [详情](./wallet-exchange-info.md) |
-| 18 | `POST /api/v1/wallet/exchange` | Bearer | [详情](./wallet-exchange.md) |
-| 19 | `POST /api/v1/wallet/bind-wechat` | Bearer | [详情](./wallet-bind-wechat.md) |
-| 20 | `POST /api/v1/wallet/unbind-wechat` | Bearer | [详情](./wallet-unbind-wechat.md) |
-| 21 | `GET /api/v1/wallet/withdraw-info` | Bearer | [详情](./wallet-withdraw-info.md) |
-| 22 | `POST /api/v1/wallet/withdraw` | Bearer | [详情](./wallet-withdraw.md) |
-| 23 | `GET /api/v1/wallet/withdraw/status` | Bearer | [详情](./wallet-withdraw-status.md) |
-| 24 | `GET /api/v1/wallet/withdraw-orders` | Bearer | [详情](./wallet-withdraw-orders.md) |
+| 14 | `GET /api/v1/wallet/account` | Bearer | [详情](./wallet/wallet-account.md) |
+| 15 | `GET /api/v1/wallet/coin-transactions` | Bearer | [详情](./wallet/wallet-coin-transactions.md) |
+| 16 | `GET /api/v1/wallet/cash-transactions` | Bearer | [详情](./wallet/wallet-cash-transactions.md) |
+| 17 | `GET /api/v1/wallet/exchange-info` | 无 | [详情](./wallet/wallet-exchange-info.md) |
+| 18 | `POST /api/v1/wallet/exchange` | Bearer | [详情](./wallet/wallet-exchange.md) |
+| 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) |
+| 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) |
+| 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)（关闭免确认到账,解除授权） |
 | **签到**（前缀 `/api/v1/signin`） |||
-| 25 | `GET /api/v1/signin/status` | Bearer | [详情](./signin-status.md) |
-| 26 | `POST /api/v1/signin` | Bearer | [详情](./signin-do.md) |
-| 26a | `POST /api/v1/signin/boost` | Bearer | [详情](./signin-boost.md) |
+| 25 | `GET /api/v1/signin/status` | Bearer | [详情](./signin/signin-status.md) |
+| 26 | `POST /api/v1/signin` | Bearer | [详情](./signin/signin-do.md) |
+| 26a | `POST /api/v1/signin/boost` | Bearer | [详情](./signin/signin-boost.md) |
 | **任务**（前缀 `/api/v1/tasks`） |||
-| 27 | `GET /api/v1/tasks` | Bearer | [详情](./tasks-list.md) |
-| 28 | `POST /api/v1/tasks/{task_key}/claim` | Bearer | [详情](./tasks-claim.md) |
+| 27 | `GET /api/v1/tasks` | Bearer | [详情](./tasks/tasks-list.md) |
+| 28 | `POST /api/v1/tasks/{task_key}/claim` | Bearer | [详情](./tasks/tasks-claim.md) |
 | **省钱**（前缀 `/api/v1/savings`） |||
-| 29 | `GET /api/v1/savings/summary` | Bearer | [详情](./savings-summary.md) |
-| 30 | `GET /api/v1/savings/battle` | Bearer | [详情](./savings-battle.md) |
-| 31 | `GET /api/v1/savings/records` | Bearer | [详情](./savings-records.md) |
+| 29 | `GET /api/v1/savings/summary` | Bearer | [详情](./savings/savings-summary.md) |
+| 30 | `GET /api/v1/savings/battle` | Bearer | [详情](./savings/savings-battle.md) |
+| 31 | `GET /api/v1/savings/records` | Bearer | [详情](./savings/savings-records.md) |
 | **看广告发奖**（前缀 `/api/v1/ad`） |||
-| 32 | `GET /api/v1/ad/pangle-callback` | 验签 | [详情](./ad-pangle-callback.md) |
-| 33 | `GET /api/v1/ad/reward-status` | Bearer | [详情](./ad-reward-status.md) |
-| 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad-test-grant.md) |
-| 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad-ecpm-report.md) |
-| 35a | `POST /api/v1/ad/feed-reward` | Bearer | [详情](./ad-feed-reward.md) |
-| 35b | `POST /api/v1/ad/reward-noshow` | Bearer | [详情](./ad-reward-noshow.md)(激励视频提前关闭/未发奖留痕,只记原因不发币) |
-| 35c | `GET /api/v1/ad/feed-reward/units` | Bearer | 信息流广告今日已发份数/上限(配合 `feed-reward` 看进度)(无单独文档) |
+| 32 | `GET /api/v1/ad/pangle-callback` | 验签 | [详情](./ad/ad-pangle-callback.md) |
+| 33 | `GET /api/v1/ad/reward-status` | Bearer | [详情](./ad/ad-reward-status.md) |
+| 34 | `POST /api/v1/ad/test-grant` | Bearer | [详情](./ad/ad-test-grant.md) |
+| 35 | `POST /api/v1/ad/ecpm-report` | Bearer | [详情](./ad/ad-ecpm-report.md) |
+| 35a | `POST /api/v1/ad/feed-reward` | Bearer | [详情](./ad/ad-feed-reward.md) |
+| 35b | `POST /api/v1/ad/reward-noshow` | Bearer | [详情](./ad/ad-reward-noshow.md)(激励视频提前关闭/未发奖留痕,只记原因不发币) |
+| 35c | `GET /api/v1/ad/feed-reward/units` | Bearer | [详情](./ad/ad-feed-reward.md)（信息流广告今日已发份数/上限,配合 feed-reward 看进度） |
+| 35d | `POST /api/v1/ad/watch-report` | Bearer | [详情](./ad/ad-watch-report.md)（上报激励视频观看时长,旧客户端兼容） |
 | **用户资料**（前缀 `/api/v1/user`） |||
-| 35 | `PATCH /api/v1/user/profile` | Bearer | [详情](./user-profile.md) |
-| 36 | `POST /api/v1/user/avatar` | Bearer | [详情](./user-avatar.md) |
-| 36a | `POST /api/v1/user/onboarding/complete` | Bearer | 标记新手引导完成（按 账号+device_id 幂等,跨卸载重装持久）(无单独文档) |
-| 36b | `GET /api/v1/user/onboarding/status` | Bearer | 查该 (账号,设备) 是否走过引导（运营在 admin 删记录即触发重走）(无单独文档) |
-| 37 | `DELETE /api/v1/user` | Bearer | [详情](./user-delete.md) |
+| 35 | `PATCH /api/v1/user/profile` | Bearer | [详情](./user/user-profile.md) |
+| 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 删记录即触发重走） |
+| 37 | `DELETE /api/v1/user` | Bearer | [详情](./user/user-delete.md) |
 | **帮助与反馈**（前缀 `/api/v1/feedback`） |||
-| 38 | `POST /api/v1/feedback` | Bearer | [详情](./feedback.md) |
-| 38a | `GET /api/v1/feedback/config` | Bearer | 反馈页「加群二维码」卡配置（开关 + 二维码图 + 三行文案）(无单独文档) |
-| 38b | `GET /api/v1/feedback/records` | Bearer | 我的反馈历史（pending/adopted/rejected）(无单独文档) |
+| 38 | `POST /api/v1/feedback` | Bearer | [详情](./other/feedback.md) |
+| 38a | `GET /api/v1/feedback/config` | Bearer | [详情](./other/feedback-config.md)（反馈页「加群二维码」卡配置:开关+二维码图+三行文案） |
+| 38b | `GET /api/v1/feedback/records` | Bearer | [详情](./other/feedback-records.md)（我的反馈历史,pending/adopted/rejected） |
+| **埋点 & 订单上报**（前缀分散;全部 Bearer 除 analytics/events 不强制登录） |||
+| E1 | `POST /api/v1/analytics/events` | 无 | [详情](./other/analytics-events.md)（批量上报埋点事件,不强制登录,每批最多200条） |
+| E2 | `POST /api/v1/order/report` | Bearer | [详情](./other/order-report.md)（上报归因订单,比价后5分钟内点链接+支付金额与比价价相差≤1元） |
 | **首页门面数据 / 客户端配置**（前缀 `/api/v1/platform`；全平台展示数字 + 运营开关,**全部不鉴权**,登录前可读） |||
-| 39 | `GET /api/v1/platform/stats` | 无 | [详情](./platform-stats.md) |
-| 40 | `GET /api/v1/platform/savings-feed` | 无 | [详情](./platform-savings-feed.md) |
-| 40a | `GET /api/v1/platform/flags` | 无 | 客户端运营 feature flag（比价/领券期广告开关等),拉取后缓存(无单独文档) |
-| 40b | `GET /api/v1/platform/ad-config` | 无 | 客户端拉广告配置（穿山甲 app_id + 各位 ID + 各场景开关;不含验签密钥）(无单独文档) |
-| 40c | `GET /api/v1/platform/app-version` | 无 | 最新 App 版本（OTA 检查更新;与本机 versionCode 比）(无单独文档) |
+| 39 | `GET /api/v1/platform/stats` | 无 | [详情](./platform/platform-stats.md) |
+| 40 | `GET /api/v1/platform/savings-feed` | 无 | [详情](./savings/platform-savings-feed.md) |
+| 40a | `GET /api/v1/platform/flags` | 无 | [详情](./platform/platform-flags.md)（客户端运营 feature flag,比价/领券期广告开关等,拉取后缓存） |
+| 40b | `GET /api/v1/platform/ad-config` | 无 | [详情](./platform/platform-ad-config.md)（客户端拉广告配置:穿山甲 app_id+各位ID+各场景开关;不含验签密钥） |
+| 40c | `GET /api/v1/platform/app-version` | 无 | [详情](./platform/platform-app-version.md)（最新 App 版本,OTA 检查更新;与本机 versionCode 比） |
 | **微信支付回调**（前缀 `/api/v1/wxpay`） |||
 | W1 | `POST /api/v1/wxpay/transfer-auth-notify` | 无 | 免确认收款授权结果通知（一期 stub:仅应答 200 不验签不改账,授权状态靠主动查询兜底)(无单独文档) |
 | **CPS 群发短链落地**（**无前缀**,挂域名根;公网不鉴权） |||
-| C1 | `GET /c/{code}` | 无 | [详情](./cps-redirect.md)（短链落地:微信授权拿 openid + 记点击 + 302 跳/淘宝 H5 落地页） |
-| C2 | `POST /c/{code}/copy` | 无 | [详情](./cps-redirect.md)（淘宝落地页点「复制口令」记 `copy`） |
-| C3 | `GET /wx/oauth/cb` | 无 | [详情](./cps-redirect.md)（微信网页授权回调;upsert `cps_wx_user` + 种 cookie,`include_in_schema=False`） |
-| C4 | `GET /MP_verify_*.txt` | 无 | [详情](./cps-redirect.md)（微信「网页授权域名」归属校验文件,`include_in_schema=False`） |
+| C1 | `GET /c/{code}` | 无 | [详情](./other/cps-redirect.md)（短链落地:微信授权拿 openid + 记点击 + 302 跳/淘宝 H5 落地页） |
+| C2 | `POST /c/{code}/copy` | 无 | [详情](./other/cps-redirect.md)（淘宝落地页点「复制口令」记 `copy`） |
+| C3 | `GET /wx/oauth/cb` | 无 | [详情](./other/cps-redirect.md)（微信网页授权回调;upsert `cps_wx_user` + 种 cookie,`include_in_schema=False`） |
+| C4 | `GET /MP_verify_*.txt` | 无 | [详情](./other/cps-redirect.md)（微信「网页授权域名」归属校验文件,`include_in_schema=False`） |
 | **内部回写端点**（前缀 `/internal`;pricebot/发布流程→app-server,**`X-Internal-Secret` 头**,非客户端接口） |||
-| N1 | `POST /internal/price-observation` | 内部密钥 | [详情](./internal.md)（比价价格事实批量落 `price_observation`） |
-| N2 | `GET /internal/store-mapping/lookup` | 内部密钥 | [详情](./internal.md)（按源平台店名反查目标平台已沉淀店铺 id/deeplink） |
-| N3 | `POST /internal/store-mapping` | 内部密钥 | [详情](./internal.md)（跨平台店铺身份映射落 `store_mapping`） |
-| N4 | `POST /internal/store-mapping/invalidate` | 内部密钥 | [详情](./internal.md)（标记某平台 shopId 缓存 deeplink 失效） |
-| N5 | `POST /internal/launch-confirm-sample` | 内部密钥 | [详情](./internal.md)（启动确认窗兜底样本落 `launch_confirm_sample`） |
-| N6 | `POST /internal/app-version` | 内部密钥 | [详情](./internal.md)（发布流程写最新 App 版本,落 `app_config`） |
+| N1 | `POST /internal/price-observation` | 内部密钥 | [详情](./internal/internal.md)（比价价格事实批量落 `price_observation`） |
+| N2 | `GET /internal/store-mapping/lookup` | 内部密钥 | [详情](./internal/internal.md)（按源平台店名反查目标平台已沉淀店铺 id/deeplink） |
+| N3 | `POST /internal/store-mapping` | 内部密钥 | [详情](./internal/internal.md)（跨平台店铺身份映射落 `store_mapping`） |
+| 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`） |
 | **静态资源**（StaticFiles 挂载,见下方 `/media` 静态服务） |||
 | - | `GET /media/avatars/<file>` | 无 | 用户头像;返回二进制图片 |
 | - | `GET /media/feedback/<file>` | 无 | 反馈截图;返回二进制图片 |
 | **运营后台 Admin**（独立子应用 `app/admin/`,前缀 `/admin/api`,独立进程 + 独立 admin JWT。鉴权列:`admin`=任意已登录管理员,`operator`/`finance`/`super_admin`=需对应角色（`super_admin` 恒通过）） |||
-| A1 | `POST /admin/api/auth/login` | 无 | [详情](./admin-auth-login.md) |
-| A2 | `GET /admin/api/auth/me` | admin | [详情](./admin-auth-me.md) |
-| A3 | `GET /admin/api/stats/overview` | admin | [详情](./admin-stats-overview.md) |
-| A4 | `GET /admin/api/users` | admin | [详情](./admin-users-list.md) |
-| A5 | `GET /admin/api/users/{user_id}` | admin | [详情](./admin-user-detail.md) |
-| A6 | `POST /admin/api/users/{user_id}/status` | operator | [详情](./admin-user-status.md) |
-| A7 | `POST /admin/api/users/{user_id}/coins` | finance | [详情](./admin-user-coins.md) |
-| A8 | `POST /admin/api/users/{user_id}/cash` | finance | [详情](./admin-user-cash.md) |
-| A9 | `GET /admin/api/wallet/coin-transactions` | admin | [详情](./admin-wallet-coin-transactions.md) |
-| A10 | `GET /admin/api/wallet/cash-transactions` | admin | [详情](./admin-wallet-cash-transactions.md) |
-| A11 | `GET /admin/api/withdraws` | admin | [详情](./admin-withdraws-list.md) |
-| A12 | `POST /admin/api/withdraws/reconcile` | finance | [详情](./admin-withdraw-reconcile.md) |
-| A13 | `POST /admin/api/withdraws/{out_bill_no}/refresh` | finance | [详情](./admin-withdraw-refresh.md) |
-| A14 | `GET /admin/api/feedbacks` | admin | [详情](./admin-feedbacks-list.md) |
-| A15 | `POST /admin/api/feedbacks/{feedback_id}/handle` | operator | [详情](./admin-feedback-handle.md) |
-| A16 | `GET /admin/api/admins` | super_admin | [详情](./admin-admins-list.md) |
-| A17 | `POST /admin/api/admins` | super_admin | [详情](./admin-admin-create.md) |
-| A18 | `PATCH /admin/api/admins/{admin_id}` | super_admin | [详情](./admin-admin-update.md) |
-| A19 | `GET /admin/api/audit-logs` | admin | [详情](./admin-audit-logs.md) |
-| A20 | `GET /admin/api/dashboard-display` | admin | [详情](./admin-dashboard-display.md) |
-| A21 | `PATCH /admin/api/dashboard-display/{metric}` | operator | [详情](./admin-dashboard-display.md) |
-| A22 | `GET /admin/api/marquee-seeds` | admin | [详情](./admin-marquee-seeds.md) |
-| A23 | `POST /admin/api/marquee-seeds` | operator | [详情](./admin-marquee-seeds.md) |
-| A24 | `PATCH /admin/api/marquee-seeds/{seed_id}` | operator | [详情](./admin-marquee-seeds.md) |
-| A25 | `DELETE /admin/api/marquee-seeds/{seed_id}` | operator | [详情](./admin-marquee-seeds.md) |
-| A26 | `POST /admin/api/marquee-seeds/bulk` | operator | [详情](./admin-marquee-seeds.md) |
-| A27 | `GET /admin/api/marquee-seeds/preview` | admin | [详情](./admin-marquee-seeds.md) |
-| A28 | `GET /admin/api/ad-coin-audit` | admin | [详情](./admin-ad-coin-audit.md)(看广告金币公式复算对账,只读) |
-| A29 | `GET /admin/api/ad-revenue-report` | admin | [详情](./admin-ad-revenue-report.md)(广告收益报表:按用户/日期/类型/应用/代码位 聚合 条数/收益/金币,只读) |
+| 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` 允许客户端传值覆盖默认渠道——见各接口"备注"。
@@ -201,8 +209,8 @@
 |---|---|---|
 | `id` | int | 用户主键 |
 | `phone` | string | 手机号(注销账号后变 `deleted_<id>` 占位释放唯一约束) |
-| `nickname` | string \| null | 昵称,经 [`PATCH /api/v1/user/profile`](./user-profile.md) 修改 |
-| `avatar_url` | string \| null | 头像相对 URL(`/media/avatars/...`),经 [`POST /api/v1/user/avatar`](./user-avatar.md) 上传 |
+| `nickname` | string \| null | 昵称,经 [`PATCH /api/v1/user/profile`](./user/user-profile.md) 修改 |
+| `avatar_url` | string \| null | 头像相对 URL(`/media/avatars/...`),经 [`POST /api/v1/user/avatar`](./user/user-avatar.md) 上传 |
 | `register_channel` | string | 注册渠道:`jverify` / `sms` |
 | `status` | string | `active` / `disabled` / `deleted` |
 | `created_at` | datetime | 注册时间 |

docs/api/ad/ad-ecpm-report.md

@@ -1,6 +1,6 @@
 # POST /api/v1/ad/ecpm-report — 上报本次广告展示的 eCPM（内部收益统计）
 
-> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
 ## 入参
 请求体:`EcpmReportIn`

docs/api/ad/ad-pangle-callback.md

@@ -1,6 +1,6 @@
 # GET /api/v1/ad/pangle-callback — 穿山甲 GroMore 激励视频发奖回调(S2S)
 
-> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:**无 JWT,靠验签**（穿山甲 GroMore 服务器调用） | 限流:同 IP ≤300 次/分 | [← 返回 API 索引](./README.md)
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:**无 JWT,靠验签**（穿山甲 GroMore 服务器调用） | 限流:同 IP ≤300 次/分 | [← 返回 API 索引](../README.md)
 >
 > ⚠️ 我们客户端用 `useMediation(true)`(GroMore 融合),回调走 **GroMore 广告位层级**(规范见 supportcenter/26240),**不是**联盟代码位层级(5416)。两者密钥、响应格式都不同,别混。后台配置入口:**GroMore 聚合管理 → 搜广告位ID → 编辑 → 勾选「服务端激励回调」**(广告位层级配了就别再在代码位层级重复配,会冲突)。
 >

docs/api/ad/ad-reward-status.md

@@ -1,6 +1,6 @@
 # GET /api/v1/ad/reward-status — 今日看广告发奖进度
 
-> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
 ## 入参
 无（用户由 token 确定）。

docs/api/ad/ad-test-grant.md

@@ -1,6 +1,6 @@
 # POST /api/v1/ad/test-grant — [仅本地联调]模拟穿山甲回调发奖
 
-> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤60 次/分 | [← 返回 API 索引](./README.md)
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤60 次/分 | [← 返回 API 索引](../README.md)
 >
 > ⚠️ **仅本地联调**,受 `AD_REWARD_TEST_GRANT_ENABLED` 开关控制,**生产必须关闭**（默认 False → 一律 404）。
 

docs/api/ad/ad-watch-report.md

@@ -0,0 +1,46 @@
+# POST /api/v1/ad/watch-report — 上报激励视频观看时长
+
+> 所属:Ad 组（前缀 `/api/v1/ad`） | 鉴权:Bearer | 限流:同 IP ≤120 次/分 | [← 返回 API 索引](../README.md)
+
+客户端在激励视频关闭（onAdClose）后上报本次实际观看秒数，服务端累计到当日总时长。当前产品只保留每日 500 次上限，DAILY_AD_WATCH_SECONDS_LIMIT=0 表示时长闸不启用；该接口仍保留用于旧客户端兼容和排查观看时长。
+
+## 入参
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `seconds` | int | ✅ (≥0) | 本次观看秒数，服务端夹 [0, MAX_SINGLE_WATCH_SECONDS] |
+
+Mock 入参:
+```json
+{
+  "seconds": 28
+}
+```
+
+## 出参
+
+响应 `200`:`WatchReportOut`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `watched_seconds_today` | int | 今日累计观看秒数 |
+| `watch_seconds_limit` | int | 每日上限（秒）；0 表示当前未启用时长闸 |
+| `watch_seconds_remaining` | int | 今日剩余可观看秒数 |
+
+Mock 出参:
+```json
+{
+  "watched_seconds_today": 128,
+  "watch_seconds_limit": 0,
+  "watch_seconds_remaining": 0
+}
+```
+
+## 错误码
+- `401` 未鉴权 / token 失效
+- `422` `seconds` 缺或为负
+
+## 说明
+- 鉴权靠 Bearer，`user_id` 取自 JWT（不信 body）
+- 后端只做累计 + 上限裁切，不据此发奖（发奖靠 S2S 回调）
+- `watch_seconds_limit=0` 时客户端不据此拦截，按每日 500 次上限走

docs/api/admin/ad/admin-ad-coin-audit.md

@@ -1,6 +1,6 @@
 # Admin 看广告金币审计
 
-> 所属:Admin 组(前缀 `/admin/api/ad-coin-audit`) | 鉴权:Admin Bearer(任意已登录 admin,只读) | [← 返回 API 索引](./README.md)
+> 所属:Admin 组(前缀 `/admin/api/ad-coin-audit`) | 鉴权:Admin Bearer(任意已登录 admin,只读) | [← 返回 API 索引](../../README.md)
 
 把「看视频赚金币」(`ad_reward_record`)和「比价信息流广告」(`ad_feed_reward_record`)两类发奖记录,用与**正式发奖完全相同**的公式 [`app/core/rewards.py` `calculate_ad_reward_coin`](../../app/core/rewards.py) 复算一遍 `expected_coin`,与实际入账的 `actual_coin` 对比,核对金币公式是否生效。**纯只读对账**,不发币、不改任何数据。
 

docs/api/admin/ad/admin-ad-revenue-report.md

@@ -1,6 +1,6 @@
 # Admin 广告收益报表
 
-> 所属:Admin 组(前缀 `/admin/api/ad-revenue-report`) | 鉴权:Admin Bearer(任意已登录 admin,只读) | [← 返回 API 索引](./README.md)
+> 所属:Admin 组(前缀 `/admin/api/ad-revenue-report`) | 鉴权:Admin Bearer(任意已登录 admin,只读) | [← 返回 API 索引](../../README.md)
 
 按 **用户 × 日期 × 广告类型 × 我们的应用 × 我们的代码位** 聚合,回答「每个用户某天、每类广告(激励视频 / 信息流 / 历史 Draw)分别**看了多少条**、**收益多少**、按现算法**发了多少金币**、广告来自**哪个应用的哪个代码位**」。**纯只读**,不发币、不改数据,也**不改发奖逻辑**。
 

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

@@ -1,6 +1,6 @@
 # GET /admin/api/audit-logs — 审计日志(谁改了什么,游标分页)
 
-> 所属:Admin·Audit 组（前缀 `/admin/api/audit-logs`） | 鉴权:Bearer admin_token（角色:任意已登录 admin） | [← 返回 API 索引](./README.md)
+> 所属:Admin·Audit 组（前缀 `/admin/api/audit-logs`） | 鉴权:Bearer admin_token（角色:任意已登录 admin） | [← 返回 API 索引](../README.md)
 
 ## 入参（query）
 | 字段 | 类型 | 必填 | 默认 | 说明 |

docs/api/admin/admin-dashboard-display.md

@@ -1,6 +1,6 @@
 # Admin 首页数据配置 — 三统计展示模式
 
-> 所属:Admin 组（前缀 `/admin/api/dashboard-display`） | 鉴权:Admin Bearer（改需 operator/super） | [← 返回 API 索引](./README.md)
+> 所属:Admin 组（前缀 `/admin/api/dashboard-display`） | 鉴权:Admin Bearer（改需 operator/super） | [← 返回 API 索引](../README.md)
 
 配置客户端首页三个门面数字（帮助用户 / 完成比价 / 累计节省）的展示模式。每个指标可独立选 real/manual/random。用户侧读取见 [platform-stats](./platform-stats.md);表见 [ops_stat_config](../database/ops_stat_config.md)。
 

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

@@ -1,6 +1,6 @@
 # Admin 首页轮播种子管理
 
-> 所属:Admin 组（前缀 `/admin/api/marquee-seeds`） | 鉴权:Admin Bearer（改需 operator/super) | [← 返回 API 索引](./README.md)
+> 所属:Admin 组（前缀 `/admin/api/marquee-seeds`） | 鉴权:Admin Bearer（改需 operator/super) | [← 返回 API 索引](../README.md)
 
 管理首页轮播「真实+种子混播」的兜底种子。种子是「生成规则」:`masked_user` 可空(空→feed 随机合成名)、金额是 `[min_cents, max_cents]` 区间(feed 每次随机取值)。用户侧 feed 见 [platform-savings-feed](./platform-savings-feed.md);表见 [ops_marquee_seed](../database/ops_marquee_seed.md)。金额单位:分(前端 ÷100 显示元)。
 

docs/api/admin/admin-stats-overview.md

@@ -1,6 +1,6 @@
 # GET /admin/api/stats/overview — 大盘核心指标
 
-> 所属:Admin·数据大盘 组（前缀 `/admin/api/stats`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](./README.md)
+> 所属:Admin·数据大盘 组（前缀 `/admin/api/stats`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](../README.md)
 
 ## 入参
 无

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

@@ -1,6 +1,6 @@
 # POST /admin/api/admins — 创建管理员
 
-> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](./README.md)
+> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 **application/json**:

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

@@ -1,6 +1,6 @@
 # PATCH /admin/api/admins/{admin_id} — 改角色/启停/重置密码
 
-> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](./README.md)
+> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 **路径参数**:

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

@@ -1,6 +1,6 @@
 # GET /admin/api/admins — 管理员列表
 
-> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](./README.md)
+> 所属:Admin·Accounts 组（前缀 `/admin/api/admins`） | 鉴权:Bearer admin_token（角色:super_admin） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 无（按 `id` 升序返回全部,无分页）

docs/api/admin/auth/admin-auth-login.md

@@ -1,6 +1,6 @@
 # POST /admin/api/auth/login — 管理员登录
 
-> 所属:Admin·Auth 组（前缀 `/admin/api/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+> 所属:Admin·Auth 组（前缀 `/admin/api/auth`） | 鉴权:无 | [← 返回 API 索引](../../README.md)
 
 ## 入参
 **application/json**:

docs/api/admin/auth/admin-auth-me.md

@@ -1,6 +1,6 @@
 # GET /admin/api/auth/me — 当前管理员
 
-> 所属:Admin·Auth 组（前缀 `/admin/api/auth`） | 鉴权:Bearer admin_token（角色:任意已登录 admin） | [← 返回 API 索引](./README.md)
+> 所属:Admin·Auth 组（前缀 `/admin/api/auth`） | 鉴权:Bearer admin_token（角色:任意已登录 admin） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 无（身份取自 Header token）

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

@@ -1,6 +1,6 @@
 # POST /admin/api/feedbacks/{feedback_id}/handle — 标记反馈已处理
 
-> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过,`require_role("operator")`） | [← 返回 API 索引](./README.md)
+> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过,`require_role("operator")`） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 - 路径:`feedback_id`(int)

docs/api/admin/feedbacks/admin-feedbacks-list.md

@@ -1,6 +1,6 @@
 # GET /admin/api/feedbacks — 反馈工单列表(offset 分页 + 筛选/排序)
 
-> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 `require_role`,仅 `get_current_admin`） | [← 返回 API 索引](./README.md)
+> 所属:Admin·反馈 组（前缀 `/admin/api/feedbacks`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 `require_role`,仅 `get_current_admin`） | [← 返回 API 索引](../../README.md)
 
 ## 入参（query）
 | 字段 | 类型 | 必填 | 默认 | 说明 |

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

@@ -1,6 +1,6 @@
 # POST /admin/api/users/{user_id}/cash — 手动增减/设值现金(带审计)
 
-> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`finance`,`super_admin` 恒通过) | [← 返回 API 索引](./README.md)
+> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`finance`,`super_admin` 恒通过) | [← 返回 API 索引](../../README.md)
 
 主要用于给无现金用户直接发钱、好让其测试提现链路。
 

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

@@ -1,6 +1,6 @@
 # POST /admin/api/users/{user_id}/coins — 手动增减/设值金币(带审计)
 
-> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`finance`,`super_admin` 恒通过) | [← 返回 API 索引](./README.md)
+> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`finance`,`super_admin` 恒通过) | [← 返回 API 索引](../../README.md)
 
 ## 入参
 - 路径:`user_id`(int)

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

@@ -1,6 +1,6 @@
 # GET /admin/api/users/{user_id} — 用户 360 详情
 
-> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](./README.md)
+> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](../../README.md)
 
 ## 入参
 - 路径:`user_id`(int)

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

@@ -1,6 +1,6 @@
 # POST /admin/api/users/{user_id}/status — 封禁/解封用户
 
-> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过) | [← 返回 API 索引](./README.md)
+> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:`operator`,`super_admin` 恒通过) | [← 返回 API 索引](../../README.md)
 
 ## 入参
 - 路径:`user_id`(int)

docs/api/admin/users/admin-users-list.md

@@ -1,6 +1,6 @@
 # GET /admin/api/users — 用户列表(筛选+排序+分页)
 
-> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](./README.md)
+> 所属:Admin·用户 组（前缀 `/admin/api/users`） | 鉴权:Bearer admin_token（角色:任意已登录管理员,无 require_role） | [← 返回 API 索引](../../README.md)
 
 ## 入参（query）
 | 字段 | 类型 | 必填 | 默认 | 说明 |

docs/api/admin/wallet/admin-wallet-cash-transactions.md

@@ -1,6 +1,6 @@
 # GET /admin/api/wallet/cash-transactions — 现金流水(游标分页)
 
-> 所属:Admin·钱包 组（前缀 `/admin/api/wallet`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](./README.md)
+> 所属:Admin·钱包 组（前缀 `/admin/api/wallet`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](../../README.md)
 
 跨用户查询全量现金流水，可按 `user_id` / `biz_type` 过滤。游标分页（`id` 倒序）。金额单位一律为**分**。
 

docs/api/admin/wallet/admin-wallet-coin-transactions.md

@@ -1,6 +1,6 @@
 # GET /admin/api/wallet/coin-transactions — 金币流水(游标分页)
 
-> 所属:Admin·钱包 组（前缀 `/admin/api/wallet`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](./README.md)
+> 所属:Admin·钱包 组（前缀 `/admin/api/wallet`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](../../README.md)
 
 跨用户查询全量金币流水，可按 `user_id` / `biz_type` 过滤。游标分页（`id` 倒序）。
 

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

@@ -1,6 +1,6 @@
 # POST /admin/api/withdraws/reconcile — 批量对账(扫超时 pending 单)
 
-> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:`finance`，`super_admin` 恒通过） | [← 返回 API 索引](./README.md)
+> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:`finance`，`super_admin` 恒通过） | [← 返回 API 索引](../../README.md)
 
 扫描创建时间超过 `older_than_minutes` 分钟、仍为 `pending` 的提现单，逐单调微信查单并归一化（成功落 `success`；失败/已撤销则退款落 `failed`；查到 `WAIT_USER_CONFIRM` 视为用户放弃，撤单+退款）。用于解开"扣了款但转账没发起/没确认"的孤儿单。单笔失败不影响其余（内部 rollback 后继续，下轮再试）。
 

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

@@ -1,6 +1,6 @@
 # POST /admin/api/withdraws/{out_bill_no}/refresh — 单笔提现重试查单
 
-> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:`finance`，`super_admin` 恒通过） | [← 返回 API 索引](./README.md)
+> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:`finance`，`super_admin` 恒通过） | [← 返回 API 索引](../../README.md)
 
 对单笔提现单调微信查单并归一化:`SUCCESS`→`success`；`FAIL`/`CANCELLED`/`CLOSED`→退款+`failed`；查到 `WAIT_USER_CONFIRM` 视为用户放弃（`cancel_if_unconfirmed=True`），撤单+退款；`ACCEPTED`/`PROCESSING` 等仍在途则保持 `pending`。已是终态的单直接返回、不再查。
 

docs/api/admin/withdraws/admin-withdraws-list.md

@@ -1,6 +1,6 @@
 # GET /admin/api/withdraws — 提现单列表(游标分页)
 
-> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，列表为只读，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](./README.md)
+> 所属:Admin·提现 组（前缀 `/admin/api/withdraws`） | 鉴权:Bearer admin_token（角色:任意已登录管理员，列表为只读，仅需 `get_current_admin`，无 `require_role`） | [← 返回 API 索引](../../README.md)
 
 跨用户查询全量提现单，可按 `user_id` / `status` 过滤。游标分页（`id` 倒序）。
 

docs/api/auth/auth-jverify-login.md

@@ -1,6 +1,6 @@
 # POST /api/v1/auth/jverify-login — 极光一键登录
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](../README.md)
 >
 > 集成实现:见 [integrations/jiguang](../integrations/jiguang.md)（极光核验链路、RSA 解密策略、私钥配对踩坑）。
 

docs/api/auth/auth-logout.md

@@ -1,6 +1,6 @@
 # POST /api/v1/auth/logout — 登出
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:Bearer access_token | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:Bearer access_token | [← 返回 API 索引](../README.md)
 
 ## 入参
 无

docs/api/auth/auth-me.md

@@ -1,6 +1,6 @@
 # GET /api/v1/auth/me — 获取当前登录用户
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:Bearer access_token | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:Bearer access_token | [← 返回 API 索引](../README.md)
 
 ## 入参
 无（身份取自 Header token）

docs/api/auth/auth-refresh.md

@@ -1,6 +1,6 @@
 # POST /api/v1/auth/refresh — 刷新 token
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无（凭 body 里的 refresh_token） | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无（凭 body 里的 refresh_token） | [← 返回 API 索引](../README.md)
 
 ## 入参
 

docs/api/auth/auth-sms-login.md

@@ -1,6 +1,6 @@
 # POST /api/v1/auth/sms/login — 手机号 + 验证码登录
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](../README.md)
 >
 > 集成实现:见 [integrations/sms](../integrations/sms.md)（验证码校验逻辑）。
 

docs/api/auth/auth-sms-send.md

@@ -1,6 +1,6 @@
 # POST /api/v1/auth/sms/send — 发送短信验证码
 
-> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](./README.md)
+> 所属:Auth 组（前缀 `/api/v1/auth`） | 鉴权:无 | [← 返回 API 索引](../README.md)
 >
 > 集成实现:见 [integrations/sms](../integrations/sms.md)（mock 模式、频控、接真供应商 TODO）。
 

docs/api/compare/compare-milestone-claim.md

@@ -1,6 +1,6 @@
 # POST /api/v1/compare/milestones/{milestone}/claim — 领取比价战绩里程碑奖励
 
-> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
 领取某一档(第 `milestone` 次)。⚠️ **当前不真发金币**(产品定,后续整体删除该功能):仍写
 `comparison_milestone_claim`((user_id, milestone) 唯一)标记该档已领、**每档只能领一次**,但不调

docs/api/compare/compare-milestones.md

@@ -1,6 +1,6 @@
 # GET /api/v1/compare/milestones — 比价战绩里程碑进度
 
-> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
 福利页「记录比价战绩」的数据源。返回各档(第 1~6 次)解锁/领取状态。
 

docs/api/compare/compare-record-detail.md

@@ -1,6 +1,6 @@
 # GET /api/v1/compare/records/{record_id} — 比价记录详情
 
-> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
 单条比价记录详情，在列表项基础上额外带 `raw_payload`（客户端上报的原始全量），供未来 UI 展示任意细节。
 

docs/api/compare/compare-record-report.md

@@ -1,11 +1,11 @@
 # POST /api/v1/compare/record — 上报一次比价结果(幂等)
 
-> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](./README.md)
+> 所属:比价记录组（前缀 `/api/v1/compare`） | 鉴权:Bearer | [← 返回 API 索引](../README.md)
 
-比价 `done` 帧后,客户端用**带 JWT 的通道**上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。
+比价 `done` 帧后上报一条比价结果,落 `comparison_record` 表，作为「我的比价记录」数据源 + 用户级行为画像。
 
-> ⚠️ 与不鉴权的透传端点 [`/api/v1/price/step`](./compare-price-step.md) 不同：那是转发壳，本接口按用户维度落库，**必须鉴权**。
-> 本轮只做 server 端；客户端在 done 帧后调本接口的改动另起一轮（见 [待办与技术债.md](../guides/待办与技术债.md) P1）。
+> ⚠️ **灰度定位(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 落库),本接口按用户维度显式上报,**必须鉴权**。
 
 ## 入参（JSON body）
 
@@ -13,7 +13,7 @@
 
 | 字段 | 类型 | 必填 | 默认 | 说明 |
 |---|---|---|---|---|
-| `trace_id` | string | ✅ | — | pricebot 侧 trace_id。**幂等键**：同用户同 trace_id 重复上报覆盖、返回同一 id |
+| `trace_id` | string | ✅ | — | 一次比价的唯一标识(app-server 帧0 签发)。**幂等键(trace_id 单列唯一)**：同 trace_id 重复上报覆盖、返回同一 id;与 harvest 行按它 reconcile |
 | `business_type` | string | ❌ | `food` | `food`(外卖,当前唯一接通) / `ecom`(电商) / `coupon`(领券) |
 | `device_id` | string \| null | ❌ | null | 设备号 |
 | `store_name` | string \| null | ❌ | null | 店铺名（外卖,来自 calibration.result） |