后台权限管理支持「自定义」角色（后端） (#126)

admin_user 加 pages_override(可空 JSON)+ Alembic 迁移；role==custom 时可见页由逐页勾选决定，否则跟随角色。
create/update 收 pages_override(切回普通角色自动清空)，_validate_role 放行 custom 哨兵角色。
登录/me 下发有效页时优先用 override → 左侧导航按勾选即时生效。补 4 个用例，test_admin_roles 全绿。

配套前端 PR：shaguabijia-admin-web#admin-custom-perms。

---------

Co-authored-by: no_gen_mu <liujianhishen@gmail.com>
Reviewed-on: #126
Co-authored-by: liujiahui <liujiahui@wonderable.ai>
Co-committed-by: liujiahui <liujiahui@wonderable.ai>

app/admin/repositories/stats.py

@@ -30,11 +30,17 @@ from app.models.user import User
 from app.models.wallet import CoinTransaction, WithdrawOrder
 
 _BEIJING = timezone(timedelta(hours=8))
-COUPON_REWARD_BIZ_TYPES = ("reward_video", "ad_reward", "coupon", "coupon_reward")
+REWARD_VIDEO_BIZ_TYPES = ("reward_video", "ad_reward")
+# 领券/比价奖励金币的真实来源是信息流广告发奖(ad_feed_reward_record,按 feed_scene 分场景);
+# coin_transaction 里只有扁平的 feed_ad_reward、biz_type 不分 coupon/comparison,故这俩桶历史从未
+# 被写入,仅留作未来兜底,实际金额在下方按 feed_scene 汇总 ad_feed_reward_record 得出。reward_video/
+# ad_reward 是激励视频,单独成桶、不再混进领券奖励(历史误并会把激励视频金币双计进领券)。
+COUPON_REWARD_BIZ_TYPES = ("coupon", "coupon_reward")
 COMPARISON_REWARD_BIZ_TYPES = ("comparison", "compare_reward", "comparison_reward")
 EXCLUDED_REWARD_BIZ_TYPES = ("invite_inviter", "invite_invitee", "admin_grant")
 UNCLASSIFIED_FEED_BIZ_TYPES = ("feed_ad_reward",)
 REGULAR_TASK_EXCLUDED_BIZ_TYPES = (
+    *REWARD_VIDEO_BIZ_TYPES,
     *COUPON_REWARD_BIZ_TYPES,
     *COMPARISON_REWARD_BIZ_TYPES,
     *EXCLUDED_REWARD_BIZ_TYPES,
@@ -362,7 +368,7 @@ def dashboard_overview(
     period_reward_video_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
-        CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
+        CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
     )
     period_feed_ad_coin_total = _sum(
         CoinTransaction.amount,
@@ -384,15 +390,29 @@ def dashboard_overview(
         *period_coin_conds,
         CoinTransaction.biz_type.like("task_%"),
     )
+    # 领券/比价奖励金币 = biz_type 桶(历史空,兜底)+ 该场景信息流广告实发金币
+    # (ad_feed_reward_record.feed_scene,granted;reward_date 是北京日期串,与 period 同自然日窗口)。
     period_coupon_reward_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
         CoinTransaction.biz_type.in_(COUPON_REWARD_BIZ_TYPES),
+    ) + _sum(
+        AdFeedRewardRecord.coin,
+        AdFeedRewardRecord.status == "granted",
+        AdFeedRewardRecord.feed_scene == "coupon",
+        AdFeedRewardRecord.reward_date >= period_from.isoformat(),
+        AdFeedRewardRecord.reward_date <= period_to.isoformat(),
     )
     period_comparison_reward_coin_total = _sum(
         CoinTransaction.amount,
         *period_coin_conds,
         CoinTransaction.biz_type.in_(COMPARISON_REWARD_BIZ_TYPES),
+    ) + _sum(
+        AdFeedRewardRecord.coin,
+        AdFeedRewardRecord.status == "granted",
+        AdFeedRewardRecord.feed_scene == "comparison",
+        AdFeedRewardRecord.reward_date >= period_from.isoformat(),
+        AdFeedRewardRecord.reward_date <= period_to.isoformat(),
     )
     period_regular_task_coin_total = _sum(
         CoinTransaction.amount,
@@ -543,7 +563,7 @@ def dashboard_overview(
             "reward_video_coin_total": _sum(
                 CoinTransaction.amount,
                 CoinTransaction.amount > 0,
-                CoinTransaction.biz_type.in_(("reward_video", "ad_reward")),
+                CoinTransaction.biz_type.in_(REWARD_VIDEO_BIZ_TYPES),
             ),
             "reward_video_watch_count": _count(
                 AdRewardRecord,

app/admin/routers/ops_marquee_seed.py

@@ -19,6 +19,8 @@ from app.admin.schemas.ops_marquee_seed import (
     OpsMarqueeSeedCreate,
     OpsMarqueeSeedOut,
     OpsMarqueeSeedUpdate,
+    OpsRealRecordItem,
+    OpsRealRecordsOut,
     OpsSavingsFeedPreviewOut,
 )
 from app.models.admin import AdminUser
@@ -68,6 +70,22 @@ def preview_feed(
     return OpsSavingsFeedPreviewOut(items=ops_marquee.get_feed(db, limit=limit, mode=mode))
 
 
+@router.get("/real-records", response_model=OpsRealRecordsOut, summary="分页浏览当前模式下可展示的记录(审核用)")
+def list_real_records(
+    db: AdminDb,
+    mode: Annotated[str | None, Query(description="mixed/real/seed;不传=当前持久化模式")] = None,
+    offset: Annotated[int, Query(ge=0)] = 0,
+    limit: Annotated[int, Query(ge=1, le=50)] = 8,
+) -> OpsRealRecordsOut:
+    """分页列出**当前模式**下可在 app 轮播展示的全部记录(**不去重**):只真实=真实记录;只种子=各启用
+    种子按生成逻辑各出一行;混播=真实+种子。与 app 同口径洗牌+去连簇,固定种子→翻页稳定、能翻遍全部。
+    item.user_id=0 表示种子行。"""
+    if mode is not None and mode not in ops_marquee.FEED_MODES:
+        raise HTTPException(status_code=400, detail="mode 需为 mixed / real / seed")
+    items, total = ops_marquee.list_real_records(db, mode=mode, offset=offset, limit=limit)
+    return OpsRealRecordsOut(items=[OpsRealRecordItem(**it) for it in items], total=total)
+
+
 # 注:/mode 两个端点须在 /{seed_id} 之前注册,否则 PATCH /mode 会被 /{seed_id} 抢先按 id 解析。
 @router.get("/mode", summary="首页轮播数据源模式(mixed/real/seed)")
 def get_feed_mode(db: AdminDb) -> dict:

app/admin/schemas/ops_marquee_seed.py

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

app/repositories/ops_marquee.py

@@ -217,12 +217,28 @@ def _recent_real_rows(db: Session) -> list[tuple[int, int, str | None]]:
     return out
 
 
+def _shuffle_declustered(rows: list, rng: random.Random | None = None) -> list:
+    """洗牌 + 「去连簇」:先洗牌,再贪心重排让相邻两条尽量不是同一 user_id(元素 [0] 即 user_id)。
+    rng=None → 用全局 _rng(feed 每次新随机);传入 rng(如固定种子 Random)→ 排列确定(admin 稳定分页)。
+    减少同一用户连续出现;只有少数几个用户时 best-effort。"""
+    rng = rng or _rng
+    pool = list(rows)
+    rng.shuffle(pool)
+    result: list = []
+    while pool:
+        prev_uid = result[-1][0] if result else None
+        # 优先挑与上一条不同 user 的;挑不到(只剩同 user)才取第一个
+        idx = next((i for i, r in enumerate(pool) if r[0] != prev_uid), 0)
+        result.append(pool.pop(idx))
+    return result
+
+
 def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]:
     """返回最多 limit 条 {masked_user, saved_amount_cents, time(HH:MM:SS 北京)}。
 
     mode:显式传入(admin 预览指定模式)则用它、**不改持久化配置**;不传(客户端 /savings-feed)读
     持久化的 marquee_feed_mode;非法值一律回退到持久化模式。
-    真实条:success 且 0 < saved ≤ 上限,按 user 去重(同一用户只取最新一条,避免单人刷屏)。
+    真实条:success 且 0 < saved ≤ 上限,**不按 user 去重**(打乱 + 去连簇:相邻尽量不同用户、减少单人连刷)后取前 limit。
     不足用启用的种子补齐——**公平随机抽取** need 个(而非固定取前 N),让所有种子都有机会露出;
     种子用户名留空则随机合成(避开撞名),金额取**长尾随机**(小额居多、偶尔大额,更像真实分布)。
     真实 + 种子仍不满 limit → 内置合成条**补满**,保证轮播既不空也不稀疏。
@@ -235,19 +251,13 @@ def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]
     items: list[dict] = []
     used_names: set[str] = set()
 
-    # 真实条(mixed / real):取较多近期记录(带 ~30s 缓存)后按 user 去重;金额超上限的异常值已在查询剔除。
+    # 真实条(mixed / real):**不按 user 去重**——打乱 + 去连簇(相邻尽量不同用户、减少单人连刷)后取前
+    # limit;金额超上限的异常值已在查询剔除。同一用户可多条露出,但被打散、尽量不连续。
     if mode != "seed":
-        rows = _recent_real_rows(db)
-        seen_users: set[int] = set()
-        for uid, sc, nick in rows:
-            if uid in seen_users:
-                continue
-            seen_users.add(uid)
+        for uid, sc, nick in _shuffle_declustered(_recent_real_rows(db))[:limit]:
             name = _mask_real(nick, uid)
-            used_names.add(name)  # 真实名按昵称/id 稳定;偶发撞名可接受
+            used_names.add(name)  # 同一用户可多条,名字重复无害(used_names 仅供种子避重)
             items.append({"masked_user": name, "saved_amount_cents": int(sc)})
-            if len(items) >= limit:
-                break
 
     # 种子补位 + 合成兜底(mixed / seed):mixed 下补真实不足的部分,seed 下全量用种子/合成。
     # real 模式**跳过**——只出真实,不掺任何假数据(真实不足则少于 limit,为 0 时返回空)。
@@ -300,6 +310,78 @@ def get_feed(db: Session, limit: int = 8, mode: str | None = None) -> list[dict]
     return items
 
 
+# ===== admin 侧:分页浏览「当前模式下可展示的记录」(审核用,不去重) =====
+_REAL_BROWSE_CAP = 1000   # 真实记录一次最多纳入这么多去洗牌+分页(足够审核;防超大库全量洗牌)
+_BROWSE_SEED = 20260707   # 固定洗牌种子:同一批数据下排列恒定 → 翻页稳定、能翻遍全部
+
+
+def _seed_browse_row(seed: OpsMarqueeSeed) -> dict:
+    """把一条种子按其「生成逻辑」**确定性**生成一行浏览项(名字/金额按 seed.id 派生固定种子 → 翻页稳定)。
+    名字:运营手填的非模板名原样用,否则本地合成;金额:区间内确定性长尾取值。user_id=0(种子无真实用户)。"""
+    r = random.Random(_BROWSE_SEED * 1_000_003 + int(seed.id))
+    fixed = (seed.masked_user or "").strip()
+    name = fixed if (fixed and not fixed.startswith("用户****")) else _synth_name(r)
+    lo = max(0, int(seed.min_cents))
+    hi = max(lo, int(seed.max_cents))
+    amt = lo if hi <= lo else lo + int(round((hi - lo) * (r.random() ** 2.2)))
+    return {"masked_user": name, "saved_amount_cents": amt, "created_at": "", "user_id": 0}
+
+
+def list_real_records(
+    db: Session, mode: str | None = None, offset: int = 0, limit: int = 8
+) -> tuple[list[dict], int]:
+    """分页浏览「**当前模式**下可在 app 轮播展示的全部记录」,供 admin 逐页审核(**不去重**):
+      - 只真实:全部 success+省>0 的真实记录;
+      - 只种子:每条启用种子按生成逻辑各出一行;
+      - 混播:真实 + 种子 全部合在一起。
+    与 app 轮播同口径:先洗牌 + 去连簇(相邻尽量不同 user;种子各自独立、不算同 user);**固定种子** →
+    同批数据下排列恒定,翻页不跳、能翻遍全部。返回 (items, total);item.user_id=0 表示种子。"""
+    mode = mode if mode in FEED_MODES else get_feed_mode(db)
+    # pool: [(cluster_key, item)];cluster_key 供去连簇——真实=user_id、种子=各自唯一负数(互不聚簇)
+    pool: list[tuple[int, dict]] = []
+    if mode != "seed":
+        rows = db.execute(
+            select(
+                ComparisonRecord.user_id,
+                ComparisonRecord.saved_amount_cents,
+                User.nickname,
+                ComparisonRecord.created_at,
+            )
+            .join(User, User.id == ComparisonRecord.user_id)
+            .where(
+                ComparisonRecord.status == "success",
+                ComparisonRecord.saved_amount_cents > 0,
+                ComparisonRecord.saved_amount_cents <= _REAL_MAX_CENTS,
+            )
+            .order_by(ComparisonRecord.created_at.desc())
+            .limit(_REAL_BROWSE_CAP)
+        ).all()
+        for uid, sc, nick, ca in rows:
+            pool.append((
+                int(uid),
+                {
+                    "masked_user": _mask_real(nick, int(uid)),
+                    "saved_amount_cents": int(sc),
+                    "created_at": str(ca)[:16] if ca is not None else "",
+                    "user_id": int(uid),
+                },
+            ))
+    if mode != "real":
+        seeds = (
+            db.execute(select(OpsMarqueeSeed).where(OpsMarqueeSeed.enabled.is_(True)))
+            .scalars()
+            .all()
+        )
+        for i, s in enumerate(seeds):
+            pool.append((-(i + 1), _seed_browse_row(s)))  # 每个种子唯一 key → 互不聚簇
+    total = len(pool)
+    # 每次用同一固定种子新建 Random → 同批数据排列恒定(翻页稳定);同时相邻尽量不同 user。
+    ordered = _shuffle_declustered(pool, random.Random(_BROWSE_SEED))
+    off = max(0, offset)
+    items = [item for _key, item in ordered[off : off + limit]]
+    return items, total
+
+
 # ===== 运营侧:种子 CRUD =====
 def list_seeds(db: Session) -> list[OpsMarqueeSeed]:
     return list(

tests/test_admin_read.py

@@ -320,3 +320,92 @@ def test_read_apis_require_auth(admin_client: TestClient) -> None:
         "/admin/api/feedbacks",
     ]:
         assert admin_client.get(path).status_code == 401, path
+
+
+def test_period_comparison_reward_coin_from_feed_scene(
+    admin_client: TestClient, admin_token: str
+) -> None:
+    """比价奖励金币口径:按 ad_feed_reward_record.feed_scene='comparison' 的实发金币
+    (status=granted)汇总,而非查从不写入的 biz_type 桶(修复大盘该卡恒 0)。
+    too_short(未发奖)不计。"""
+    from app.models.ad_feed_reward import AdFeedRewardRecord
+
+    d = "2021-06-15"  # 独立历史日,隔离其它用例数据
+    db = SessionLocal()
+    try:
+        uid = user_repo.upsert_user_for_login(db, phone="13800008801", register_channel="sms").id
+        db.add(AdFeedRewardRecord(
+            client_event_id="cmp-fs-granted", user_id=uid, reward_date=d,
+            ecpm_raw="0", coin=123, feed_scene="comparison", status="granted",
+        ))
+        db.add(AdFeedRewardRecord(
+            client_event_id="cmp-fs-tooshort", user_id=uid, reward_date=d,
+            ecpm_raw="0", coin=99, feed_scene="comparison", status="too_short",
+        ))
+        db.commit()
+    finally:
+        db.close()
+
+    r = admin_client.get(
+        "/admin/api/stats/overview", params={"date_from": d, "date_to": d},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["period"]["coins"]["comparison_reward_coin_total"] == 123
+
+
+def test_period_coupon_reward_coin_from_feed_scene(
+    admin_client: TestClient, admin_token: str
+) -> None:
+    """领券奖励金币口径:按 ad_feed_reward_record.feed_scene='coupon' 的实发金币汇总。"""
+    from app.models.ad_feed_reward import AdFeedRewardRecord
+
+    d = "2021-06-16"
+    db = SessionLocal()
+    try:
+        uid = user_repo.upsert_user_for_login(db, phone="13800008802", register_channel="sms").id
+        db.add(AdFeedRewardRecord(
+            client_event_id="cpn-fs-granted", user_id=uid, reward_date=d,
+            ecpm_raw="0", coin=456, feed_scene="coupon", status="granted",
+        ))
+        db.commit()
+    finally:
+        db.close()
+
+    r = admin_client.get(
+        "/admin/api/stats/overview", params={"date_from": d, "date_to": d},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    assert r.json()["period"]["coins"]["coupon_reward_coin_total"] == 456
+
+
+def test_period_coupon_reward_excludes_reward_video(
+    admin_client: TestClient, admin_token: str
+) -> None:
+    """领券奖励金币不再把激励视频金币算进来(reward_video/ad_reward 从领券桶拆出);
+    激励视频仍单独计入 reward_video_coin_total。"""
+    from datetime import datetime
+
+    from app.models.wallet import CoinTransaction
+
+    d = "2021-06-17"
+    db = SessionLocal()
+    try:
+        uid = user_repo.upsert_user_for_login(db, phone="13800008803", register_channel="sms").id
+        db.add(CoinTransaction(
+            user_id=uid, amount=50, balance_after=50, biz_type="reward_video",
+            ref_id="rv-split-1", created_at=datetime(2021, 6, 17, 12, 0, 0),
+        ))
+        db.commit()
+    finally:
+        db.close()
+
+    r = admin_client.get(
+        "/admin/api/stats/overview", params={"date_from": d, "date_to": d},
+        headers=_auth(admin_token),
+    )
+    assert r.status_code == 200, r.text
+    coins = r.json()["period"]["coins"]
+    assert coins["coupon_reward_coin_total"] == 0        # 激励视频不计入领券奖励
+    assert coins["reward_video_coin_total"] == 50        # 仍计入激励视频卡