后台权限管理支持「自定义」角色：按人存 pages_override，可见页逐页勾选并即时生效

admin_user 加 pages_override(可空 JSON)+ Alembic 迁移;role=="custom" 时可见页由这份逐页勾选决定,否则跟随角色。create/update 收 pages_override(切回普通角色自动清空),_validate_role 放行 custom 哨兵角色。登录/me 下发有效页时优先用 override → 左侧导航直接按勾选生效。补 4 个用例覆盖建/改/切回/切入,test_admin_roles 全绿。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-08 19:44:03 +08:00
11 changed files with 170 additions and 123 deletions
@@ -0,0 +1,35 @@
+"""admin_user 加 pages_override 列(「自定义」权限:按人存专属可见页 key 列表)
+
+权限管理页新增「自定义」角色:选它时该成员的可见页不跟随任何共享角色,而由逐页勾选决定,
+存这个人专属的一份页 key 列表。仅 role == "custom" 时有效;普通角色为 None(可见页跟随角色)。
+PG 用 JSONB,SQLite 退化为通用 JSON(同 admin_audit_log.detail / comparison_record.raw_payload)。
+
+Revision ID: admin_user_pages_override
+Revises: admin_user_plain_password
+Create Date: 2026-07-08 00:00:00.000000
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import JSONB
+
+from alembic import op
+
+revision: str = "admin_user_pages_override"
+down_revision: str | Sequence[str] | None = "admin_user_plain_password"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+# 与 app/models/admin.py 的 _JSON 一致:PG JSONB / 其它 JSON
+_JSON = sa.JSON().with_variant(JSONB(), "postgresql")
+
+
+def upgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.add_column(sa.Column("pages_override", _JSON, nullable=True))
+
+
+def downgrade() -> None:
+    with op.batch_alter_table("admin_user", schema=None) as batch_op:
+        batch_op.drop_column("pages_override")
@@ -9,6 +9,9 @@ super_admin 为内建全权角色,恒可见全部页(effective_pages 特判)。
 from __future__ import annotations

 SUPER_ADMIN_ROLE = "super_admin"
+# 「自定义」哨兵角色:不是 admin_role 表里的行,而是标记「这个人的可见页由 pages_override 决定」。
+# admin_user.role == CUSTOM_ROLE 时,有效可见页取 admin_user.pages_override(见 auth._admin_out_with_pages)。
+CUSTOM_ROLE = "custom"

 # 分组镜像前端导航(app/(main)/layout.tsx 的 NAV_GROUPS);key = 路由一级
 PERMISSION_CATALOG: list[dict] = [
@@ -26,14 +26,17 @@ def create_admin(
    password: str,
    role: str = "operator",
    plain_password: str | None = None,
+    pages_override: list[str] | None = None,
 ) -> AdminUser:
    """建管理员。plain_password 非空则额外留存明文(后台 UI 建的账号传,供权限管理页复看);
-    脚本/起后台建账号不传(留 None → 前端不显示密码)。"""
+    脚本/起后台建账号不传(留 None → 前端不显示密码)。
+    pages_override:role=="custom" 时传专属可见页 key 列表;普通角色为 None。"""
    admin = AdminUser(
        username=username,
        password_hash=hash_password(password),
        role=role,
        plain_password=plain_password,
+        pages_override=pages_override,
    )
    db.add(admin)
    db.commit()
@@ -30,17 +30,11 @@ from app.models.user import User
 from app.models.wallet import CoinTransaction, WithdrawOrder

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

 from app.admin.audit import write_audit
 from app.admin.deps import AdminDb, CurrentAdmin, get_client_ip, require_role
-from app.admin.permissions import SUPER_ADMIN_ROLE
+from app.admin.permissions import CUSTOM_ROLE, SUPER_ADMIN_ROLE, sanitize_pages
 from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.admin import AdminCreateRequest, AdminUpdateRequest
@@ -26,14 +26,22 @@ def _active_super_count(db: AdminDb) -> int:


 def _validate_role(db: AdminDb, role: str) -> None:
-    """角色必须是 super_admin 或 admin_role 表里已存在的角色,否则 400。"""
-    if role == SUPER_ADMIN_ROLE:
+    """角色必须是 super_admin / custom(自定义) / admin_role 表里已存在的角色,否则 400。"""
+    if role in (SUPER_ADMIN_ROLE, CUSTOM_ROLE):
        return
    role_repo.ensure_builtin_roles(db)  # 空表(测试/全新库)兜底播种,再校验
    if role_repo.get_role(db, role) is None:
        raise HTTPException(status_code=400, detail=f"角色不存在: {role}")


+def _clean_override(role: str, pages_override: list[str] | None) -> list[str] | None:
+    """按最终角色算出该存的 pages_override:custom → 勾选集(过滤非法 key,可空列表);
+    非 custom → None(切回普通角色即清空自定义页)。"""
+    if role == CUSTOM_ROLE:
+        return sanitize_pages(pages_override)
+    return None
+
+
@router.get("", response_model=list[AdminOut], summary="管理员列表(含明文密码,super_admin 专属)")
 def list_admins(db: AdminDb) -> list[AdminOut]:
    out: list[AdminOut] = []
@@ -51,13 +59,16 @@ def create_admin(
    if admin_repo.get_by_username(db, body.username) is not None:
        raise HTTPException(status_code=409, detail="用户名已存在")
    _validate_role(db, body.role)
+    override = _clean_override(body.role, body.pages_override)
    new = admin_repo.create_admin(
        db, username=body.username, password=body.password, role=body.role,
        plain_password=body.password,  # UI 建的账号留存明文,供权限管理页复看
+        pages_override=override,
    )
    write_audit(
        db, admin, action="admin.create", target_type="admin", target_id=new.id,
-        detail={"username": new.username, "role": new.role}, ip=get_client_ip(request), commit=True,
+        detail={"username": new.username, "role": new.role, "pages_override": override},
+        ip=get_client_ip(request), commit=True,
    )
    return AdminOut.model_validate(new)

@@ -89,7 +100,8 @@ def update_admin(
        _validate_role(db, body.role)

    changes: dict = {}
-    if body.role is not None and body.role != target.role:
+    role_changed = body.role is not None and body.role != target.role
+    if role_changed:
        changes["role"] = {"before": target.role, "after": body.role}
        target.role = body.role
    if body.status is not None and body.status != target.status:
@@ -99,6 +111,17 @@ def update_admin(
        changes["password"] = "reset"
        target.password_hash = hash_password(body.password)
        target.plain_password = body.password  # 同步留存明文,权限管理页复看保持一致
+
+    # 自定义可见页:按「最终角色」(target.role,已应用完角色变更)决定该存什么。
+    # - 切到/维持 custom 且传了 pages_override → 用勾选集;切到 custom 没传 → 清成空列表。
+    # - 切回普通角色 → 清空 override(_clean_override 返回 None)。
+    # - 角色没变、只传 pages_override(编辑现有 custom 用户的勾选)→ 也更新。
+    if role_changed or body.pages_override is not None:
+        new_override = _clean_override(target.role, body.pages_override)
+        if new_override != target.pages_override:
+            changes["pages_override"] = {"before": target.pages_override, "after": new_override}
+            target.pages_override = new_override
+
    if not changes:
        raise HTTPException(status_code=400, detail="无任何变更字段")
    db.commit()
@@ -6,6 +6,7 @@ import logging
 from fastapi import APIRouter, Depends, HTTPException

 from app.admin.deps import AdminDb, CurrentAdmin
+from app.admin.permissions import CUSTOM_ROLE, sanitize_pages
 from app.admin.repositories import admin_role as role_repo
 from app.admin.repositories import admin_user as admin_repo
 from app.admin.schemas.auth import AdminLoginRequest, AdminLoginResponse, AdminOut
@@ -19,9 +20,13 @@ router = APIRouter(prefix="/admin/api/auth", tags=["admin-auth"])


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


@@ -13,14 +13,18 @@ class AdminCreateRequest(BaseModel):
    username: str = Field(..., min_length=3, max_length=64)
    password: str = Field(..., min_length=8, max_length=72)  # bcrypt ≤72 字节
    role: str = Field("operator", min_length=1, max_length=32)
+    # 仅当 role == "custom":这个人专属可见页 key 列表(逐页勾选结果)。其余角色不传/忽略。
+    pages_override: list[str] | None = None


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

    role: str | None = Field(None, min_length=1, max_length=32)
    status: Literal["active", "disabled"] | None = None
    password: str | None = Field(None, min_length=8, max_length=72)
+    # 改成/更新「自定义」可见页;role 切回普通角色时后端会清空 override(见路由)。
+    pages_override: list[str] | None = None


 class AdminAuditLogOut(BaseModel):
@@ -21,8 +21,11 @@ class AdminOut(BaseModel):
    created_at: datetime
    last_login_at: datetime | None = None
    # 该管理员当前角色的有效可见页(= 左侧导航项 key);仅登录 / /me 填充,列表接口默认空。
-    # 前端据此过滤左侧导航(super_admin = 全部页)。见 app/admin/permissions.py。
+    # 前端据此过滤左侧导航(super_admin = 全部页;role=="custom" = pages_override)。见 permissions.py。
    pages: list[str] = []
+    # 「自定义」可见页原始勾选集(role=="custom" 时非空);列表接口下发,供权限管理页编辑回填勾选。
+    # 普通角色为 None。from_attributes 自动从 ORM 列取。
+    pages_override: list[str] | None = None
    # 明文登录密码:仅「管理员账号列表」(super_admin 专属路由)填充,供权限管理页编辑时复看;
    # 无留存(脚本建的超管 / 旧账号)为 None → 前端不显示。登录 / /me 不下发(保持 None)。
    password: str | None = None
@@ -28,8 +28,11 @@ class AdminUser(Base):
    # 明文登录密码:仅「后台 UI 创建/重置」的管理员留存,供超管在权限管理页复看转交。
    # 脚本/起后台时建的超管账号不写(为 None → 前端「不显示密码」)。⚠️ 内部工具便利取舍,见 create/list。
    plain_password: Mapped[str | None] = mapped_column(String(128), nullable=True)
-    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)
+    # super_admin(全权+管账号)/ finance(钱:提现+金币)/ operator(用户+反馈+大盘)/ custom(按人自定义)
    role: Mapped[str] = mapped_column(String(20), nullable=False, default="operator")
+    # 「自定义」权限:仅当 role == "custom" 时有效,存这个人专属的可见页 key 列表(不共享给他人)。
+    # 非 custom 用户为 None → 可见页跟随角色。登录/`/me` 下发有效页时,非空即优先用它(见 auth._admin_out_with_pages)。
+    pages_override: Mapped[list | None] = mapped_column(_JSON, nullable=True)
    # active / disabled
    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")

@@ -320,92 +320,3 @@ 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        # 仍计入激励视频卡
@@ -150,3 +150,80 @@ def test_create_admin_rejects_unknown_role(admin_client, super_token) -> None:
        headers=_auth(super_token),
    )
    assert r.status_code == 400
+
+
+def _login_pages(username: str, password: str = "pass1234") -> list[str]:
+    """以某账号登录,取下发的有效可见页(左侧导航过滤依据)。"""
+    c = TestClient(admin_app)
+    return c.post(
+        "/admin/api/auth/login", json={"username": username, "password": password}
+    ).json()["admin"]["pages"]
+
+
+def test_custom_role_create_pages_take_effect(admin_client, super_token) -> None:
+    # 建「自定义」账号:role=custom + 勾选页(含一个非法 key,应被过滤)
+    r = admin_client.post(
+        "/admin/api/admins",
+        json={
+            "username": "cust_user", "password": "pass1234", "role": "custom",
+            "pages_override": ["dashboard", "withdraws", "xx-bad"],
+        },
+        headers=_auth(super_token),
+    )
+    assert r.status_code == 200, r.text
+    # 登录下发的 pages == 勾选集(非法 key 过滤),真正驱动左侧导航
+    assert set(_login_pages("cust_user")) == {"dashboard", "withdraws"}
+    # 账号列表回显原始勾选集(供编辑回填),同样已过滤
+    admins = {a["username"]: a for a in admin_client.get("/admin/api/admins", headers=_auth(super_token)).json()}
+    assert set(admins["cust_user"]["pages_override"]) == {"dashboard", "withdraws"}
+    assert admins["cust_user"]["role"] == "custom"
+
+
+def test_custom_role_update_and_switch_back_clears_override(admin_client, super_token) -> None:
+    admin_client.post(
+        "/admin/api/admins",
+        json={
+            "username": "cust_sw", "password": "pass1234", "role": "custom",
+            "pages_override": ["dashboard"],
+        },
+        headers=_auth(super_token),
+    )
+    aid = next(
+        a["id"] for a in admin_client.get("/admin/api/admins", headers=_auth(super_token)).json()
+        if a["username"] == "cust_sw"
+    )
+    # 只改勾选集(角色不变)→ 生效
+    u = admin_client.patch(
+        f"/admin/api/admins/{aid}", json={"pages_override": ["dashboard", "feedbacks"]},
+        headers=_auth(super_token),
+    )
+    assert u.status_code == 200, u.text
+    assert set(_login_pages("cust_sw")) == {"dashboard", "feedbacks"}
+    # 切回普通角色 operator → override 清空,pages 跟随角色(运营页集,且不含 admins)
+    u2 = admin_client.patch(
+        f"/admin/api/admins/{aid}", json={"role": "operator"}, headers=_auth(super_token)
+    )
+    assert u2.status_code == 200, u2.text
+    admins = {a["username"]: a for a in admin_client.get("/admin/api/admins", headers=_auth(super_token)).json()}
+    assert admins["cust_sw"]["pages_override"] is None
+    pages = set(_login_pages("cust_sw"))
+    assert "feedbacks" in pages and "admins" not in pages  # 运营口径,自定义页已不生效
+
+
+def test_switch_operator_to_custom_sets_override(admin_client, super_token) -> None:
+    admin_client.post(
+        "/admin/api/admins",
+        json={"username": "op2cust", "password": "pass1234", "role": "operator"},
+        headers=_auth(super_token),
+    )
+    aid = next(
+        a["id"] for a in admin_client.get("/admin/api/admins", headers=_auth(super_token)).json()
+        if a["username"] == "op2cust"
+    )
+    u = admin_client.patch(
+        f"/admin/api/admins/{aid}",
+        json={"role": "custom", "pages_override": ["config"]},
+        headers=_auth(super_token),
+    )
+    assert u.status_code == 200, u.text
+    assert set(_login_pages("op2cust")) == {"config"}