From c94a764bf79f00fcfe704e7a4308bc41abfa7d70 Mon Sep 17 00:00:00 2001 From: unknown <798648091@qq.com> Date: Wed, 22 Jul 2026 14:59:10 +0800 Subject: [PATCH] feat(admin): enforce monitoring page permissions --- alembic/versions/monitoring_audit_rbac.py | 56 +++++++++++++++++++ app/admin/deps.py | 29 ++++++++++ app/admin/permissions.py | 11 ++-- app/admin/routers/analytics_health.py | 4 +- app/admin/routers/audit.py | 6 +-- app/admin/routers/device_liveness.py | 6 +-- app/admin/routers/event_logs.py | 4 +- docs/api/admin/admin-audit-logs.md | 5 +- docs/api/admin/admin-device-liveness.md | 3 +- docs/api/admin/admin-event-logs.md | 3 +- tests/test_admin_roles.py | 65 ++++++++++++++++++++++- 11 files changed, 172 insertions(+), 20 deletions(-) create mode 100644 alembic/versions/monitoring_audit_rbac.py diff --git a/alembic/versions/monitoring_audit_rbac.py b/alembic/versions/monitoring_audit_rbac.py new file mode 100644 index 0000000..397c067 --- /dev/null +++ b/alembic/versions/monitoring_audit_rbac.py @@ -0,0 +1,56 @@ +"""补齐监控审计页面权限。 + +Revision ID: monitoring_audit_rbac +Revises: merge_signin_boost_main +Create Date: 2026-07-22 00:00:00.000000 +""" +from collections.abc import Sequence + +import sqlalchemy as sa +from sqlalchemy.dialects import postgresql + +from alembic import op + +revision: str = "monitoring_audit_rbac" +down_revision: str | Sequence[str] | None = "merge_signin_boost_main" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + +_JSON = sa.JSON().with_variant(postgresql.JSONB(), "postgresql") +_PAGE = "analytics-health" + + +def _role_table() -> sa.TableClause: + return sa.table( + "admin_role", + sa.column("name", sa.String), + sa.column("pages", _JSON), + ) + + +def upgrade() -> None: + role = _role_table() + conn = op.get_bind() + pages = conn.execute( + sa.select(role.c.pages).where(role.c.name == "tech") + ).scalar_one_or_none() + if pages is not None and _PAGE not in pages: + conn.execute( + role.update() + .where(role.c.name == "tech") + .values(pages=[*pages, _PAGE]) + ) + + +def downgrade() -> None: + role = _role_table() + conn = op.get_bind() + pages = conn.execute( + sa.select(role.c.pages).where(role.c.name == "tech") + ).scalar_one_or_none() + if pages is not None and _PAGE in pages: + conn.execute( + role.update() + .where(role.c.name == "tech") + .values(pages=[page for page in pages if page != _PAGE]) + ) diff --git a/app/admin/deps.py b/app/admin/deps.py index ee3d656..8d346f8 100644 --- a/app/admin/deps.py +++ b/app/admin/deps.py @@ -10,6 +10,8 @@ from fastapi import Depends, HTTPException, Request, status from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer from sqlalchemy.orm import Session +from app.admin.permissions import ALL_PAGE_KEYS, 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.security import AdminTokenError, decode_admin_token from app.db.session import get_db @@ -72,6 +74,33 @@ def require_role(*roles: str): return _checker +def require_page(page: str): + """页面权限守卫依赖工厂。 + + 左侧导航隐藏只是 UI，这个守卫确保直接调用 API 也必须持有对应页面权限。 + super_admin 恒通过；custom 读个人 pages_override；其余角色读 admin_role.pages。 + """ + if page not in ALL_PAGE_KEYS: + raise ValueError(f"unknown admin page permission: {page}") + + def _checker(admin: CurrentAdmin, db: AdminDb) -> AdminUser: + if admin.role == SUPER_ADMIN_ROLE: + return admin + pages = ( + sanitize_pages(admin.pages_override) + if admin.role == CUSTOM_ROLE + else role_repo.effective_pages_of(db, admin.role) + ) + if page not in pages: + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"page '{page}' not allowed", + ) + return admin + + return _checker + + def get_client_ip(request: Request) -> str: """取客户端 IP(审计日志用)。生产经 nginx 反代,优先 X-Forwarded-For 第一段;否则直连 IP。 diff --git a/app/admin/permissions.py b/app/admin/permissions.py index c0b4829..837e4be 100644 --- a/app/admin/permissions.py +++ b/app/admin/permissions.py @@ -21,7 +21,6 @@ PERMISSION_CATALOG: list[dict] = [ {"key": "ad-revenue-report", "label": "广告收益"}, {"key": "comparison-records", "label": "比价记录"}, {"key": "cps", "label": "CPS收益"}, - {"key": "device-liveness", "label": "设备存活"}, ]}, {"group": "奖励审核", "pages": [ {"key": "withdraws", "label": "提现审核"}, @@ -34,11 +33,15 @@ PERMISSION_CATALOG: list[dict] = [ {"key": "huawei-review", "label": "华为审核开关"}, {"key": "users", "label": "用户管理"}, ]}, - {"group": "其他", "pages": [ - {"key": "admins", "label": "权限管理"}, + {"group": "监控审计", "pages": [ + {"key": "device-liveness", "label": "设备存活"}, + {"key": "analytics-health", "label": "埋点成功率"}, {"key": "event-logs", "label": "埋点日志"}, {"key": "audit-logs", "label": "审计日志"}, ]}, + {"group": "其他", "pages": [ + {"key": "admins", "label": "权限管理"}, + ]}, ] # 全部页面 key(super_admin 有效可见 = 此全集;也用于校验角色 pages 合法性) @@ -58,7 +61,7 @@ BUILTIN_ROLES: list[dict] = [ "dashboard", "ad-revenue-report", "cps", "withdraws", ]}, {"name": "tech", "label": "技术", "pages": [ - "dashboard", "device-liveness", "config", "ad-revenue", "huawei-review", + "dashboard", "device-liveness", "analytics-health", "config", "ad-revenue", "huawei-review", "event-logs", "audit-logs", ]}, ] diff --git a/app/admin/routers/analytics_health.py b/app/admin/routers/analytics_health.py index 517feb3..a3bb85f 100644 --- a/app/admin/routers/analytics_health.py +++ b/app/admin/routers/analytics_health.py @@ -6,7 +6,7 @@ from typing import Annotated from fastapi import APIRouter, Depends, Query -from app.admin.deps import AdminDb, get_current_admin +from app.admin.deps import AdminDb, require_page from app.admin.repositories import analytics_health as repo from app.admin.schemas.analytics_health import ( HealthBreakdownRow, @@ -17,7 +17,7 @@ from app.admin.schemas.analytics_health import ( router = APIRouter( prefix="/admin/api/analytics-health", tags=["admin-analytics-health"], - dependencies=[Depends(get_current_admin)], + dependencies=[Depends(require_page("analytics-health"))], ) diff --git a/app/admin/routers/audit.py b/app/admin/routers/audit.py index dd7cace..3e35609 100644 --- a/app/admin/routers/audit.py +++ b/app/admin/routers/audit.py @@ -1,11 +1,11 @@ -"""admin 操作审计日志查询(所有 admin 可看:谁在何时对什么做了什么)。""" +"""admin 操作审计日志查询(需要 audit-logs 页面权限)。""" from __future__ import annotations from typing import Annotated from fastapi import APIRouter, Depends, Query -from app.admin.deps import AdminDb, get_current_admin +from app.admin.deps import AdminDb, require_page from app.admin.repositories import audit_log as audit_repo from app.admin.schemas.admin import AdminAuditLogOut from app.admin.schemas.common import CursorPage @@ -13,7 +13,7 @@ from app.admin.schemas.common import CursorPage router = APIRouter( prefix="/admin/api/audit-logs", tags=["admin-audit"], - dependencies=[Depends(get_current_admin)], + dependencies=[Depends(require_page("audit-logs"))], ) diff --git a/app/admin/routers/device_liveness.py b/app/admin/routers/device_liveness.py index 879697f..c48f86c 100644 --- a/app/admin/routers/device_liveness.py +++ b/app/admin/routers/device_liveness.py @@ -2,7 +2,7 @@ 数据源 device_liveness 表(心跳 last_heartbeat_at + liveness_state + kill_alert_pending, 见 app/models/device.py)。在线/掉线、掉线时长由 repo 按 HEARTBEAT_TIMEOUT_MINUTES 阈值派生。 -纯读:无写、无审计。任意登录管理员可看(同大盘/设备管理,无角色门)。 +纯读:无写、无审计。需要 device-liveness 页面权限。 """ from __future__ import annotations @@ -10,7 +10,7 @@ from typing import Annotated from fastapi import APIRouter, Depends, Query -from app.admin.deps import AdminDb, get_current_admin +from app.admin.deps import AdminDb, require_page from app.admin.repositories import queries from app.admin.schemas.common import CursorPage from app.admin.schemas.device import DeviceLivenessItem, DeviceLivenessStats @@ -18,7 +18,7 @@ from app.admin.schemas.device import DeviceLivenessItem, DeviceLivenessStats router = APIRouter( prefix="/admin/api/device-liveness", tags=["admin-device-liveness"], - dependencies=[Depends(get_current_admin)], + dependencies=[Depends(require_page("device-liveness"))], ) diff --git a/app/admin/routers/event_logs.py b/app/admin/routers/event_logs.py index eceb155..bc4d008 100644 --- a/app/admin/routers/event_logs.py +++ b/app/admin/routers/event_logs.py @@ -6,7 +6,7 @@ from typing import Annotated from fastapi import APIRouter, Depends, Query -from app.admin.deps import AdminDb, get_current_admin +from app.admin.deps import AdminDb, require_page from app.admin.repositories import queries from app.admin.schemas.analytics import AnalyticsEventOut from app.admin.schemas.common import CursorPage @@ -14,7 +14,7 @@ from app.admin.schemas.common import CursorPage router = APIRouter( prefix="/admin/api/event-logs", tags=["admin-event-logs"], - dependencies=[Depends(get_current_admin)], + dependencies=[Depends(require_page("event-logs"))], ) diff --git a/docs/api/admin/admin-audit-logs.md b/docs/api/admin/admin-audit-logs.md index 0ea9b19..fb7d800 100644 --- a/docs/api/admin/admin-audit-logs.md +++ b/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 + `audit-logs` 页面权限 | [← 返回 API 索引](../README.md) ## 入参（query） | 字段 | 类型 | 必填 | 默认 | 说明 | @@ -29,7 +29,8 @@ ## 错误码 - `401` 未带 admin token / token 无效或过期 / 管理员被禁用 +- `403` 当前管理员没有 `audit-logs` 页面权限 ## 说明 -- 整组(`/admin/api/audit-logs`)守卫为 `get_current_admin`,任意已登录 admin 均可查看,无角色限制。 +- 整组(`/admin/api/audit-logs`)守卫为 `require_page("audit-logs")`，默认仅超级管理员和技术角色可查看，也可由超管给自定义角色授权。 - 审计日志只增不改不删,任何写操作经 `write_audit` 落一条。数据表见 [admin_audit_log](../database/admin_audit_log.md)。 diff --git a/docs/api/admin/admin-device-liveness.md b/docs/api/admin/admin-device-liveness.md index 2af7bfd..edb0c78 100644 --- a/docs/api/admin/admin-device-liveness.md +++ b/docs/api/admin/admin-device-liveness.md @@ -1,6 +1,6 @@ # /admin/api/device-liveness — 设备存活监控(#80) -> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin | 表 [device_liveness](../../database/device_liveness.md) | [← 返回 API 索引](../README.md) +> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin + `device-liveness` 页面权限 | 表 [device_liveness](../../database/device_liveness.md) | [← 返回 API 索引](../README.md) 无障碍保护存活的后台视角:哪些设备开过保护(`ever_protected`)、现在在线还是掉线(心跳超时,#107 起阈值 1 小时)、首次开启时间(`first_protected_at`)。 @@ -13,3 +13,4 @@ ## 说明 - 「在线」= `last_heartbeat_at` 距今 < 超时阈值;掉线召回链路(worker 置 `kill_alert_pending` → 客户端 pull)见表文档。 +- 无 `device-liveness` 页面权限时返回 `403`。 diff --git a/docs/api/admin/admin-event-logs.md b/docs/api/admin/admin-event-logs.md index 9dd0c69..d39c6e6 100644 --- a/docs/api/admin/admin-event-logs.md +++ b/docs/api/admin/admin-event-logs.md @@ -1,6 +1,6 @@ # /admin/api/event-logs — 埋点日志(#83) -> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin | 表 [analytics_event](../../database/analytics_event.md) | [← 返回 API 索引](../README.md) +> 所属:Admin 子应用(前缀 `/admin/api`) | 鉴权:admin + `event-logs` 页面权限 | 表 [analytics_event](../../database/analytics_event.md) | [← 返回 API 索引](../README.md) 客户端埋点(`POST /api/v1/analytics/events` 批量上报)的后台检索页。 @@ -13,3 +13,4 @@ ## 说明 - 纯只读;无聚合报表(要分析导出后自己算)。 - 时间轴用 `client_ts`(事件真实发生时刻),入库时间受客户端攒批影响。 +- 无 `event-logs` 页面权限时返回 `403`。 diff --git a/tests/test_admin_roles.py b/tests/test_admin_roles.py index fc1603f..998a3f3 100644 --- a/tests/test_admin_roles.py +++ b/tests/test_admin_roles.py @@ -44,17 +44,78 @@ def operator_token() -> str: return _token("r_operator", "operator") +@pytest.fixture() +def tech_token() -> str: + return _token("r_tech", "tech") + + def _auth(t: str) -> dict: return {"Authorization": f"Bearer {t}"} def test_super_pages_all_operator_limited(admin_client, super_token, operator_token) -> None: su = admin_client.get("/admin/api/auth/me", headers=_auth(super_token)).json() - assert "admins" in su["pages"] and "dashboard" in su["pages"] # 超管全页 + assert "admins" in su["pages"] and "analytics-health" in su["pages"] # 超管全页 op = admin_client.get("/admin/api/auth/me", headers=_auth(operator_token)).json() assert "dashboard" in op["pages"] and "admins" not in op["pages"] # 运营看不到管理员页 +def test_monitoring_audit_catalog_and_api_permissions( + admin_client, super_token, operator_token, tech_token +) -> None: + catalog = admin_client.get( + "/admin/api/roles/catalog", headers=_auth(super_token) + ).json() + monitoring = next(group for group in catalog if group["group"] == "监控审计") + assert [page["key"] for page in monitoring["pages"]] == [ + "device-liveness", "analytics-health", "event-logs", "audit-logs", + ] + + # 运营默认只能查设备存活，不能绕过导航直调技术/审计接口。 + assert admin_client.get( + "/admin/api/device-liveness/stats", headers=_auth(operator_token) + ).status_code == 200 + for path in ( + "/admin/api/analytics-health/overview?date_from=2026-07-01T00:00:00Z&date_to=2026-07-02T00:00:00Z", + "/admin/api/event-logs", + "/admin/api/audit-logs", + ): + assert admin_client.get(path, headers=_auth(operator_token)).status_code == 403 + + # 技术角色默认拥有监控审计组全部四项权限。 + for path in ( + "/admin/api/device-liveness/stats", + "/admin/api/analytics-health/overview?date_from=2026-07-01T00:00:00Z&date_to=2026-07-02T00:00:00Z", + "/admin/api/event-logs", + "/admin/api/audit-logs", + ): + assert admin_client.get(path, headers=_auth(tech_token)).status_code == 200 + + +def test_custom_admin_api_permission_uses_pages_override(admin_client) -> None: + db = SessionLocal() + try: + admin = admin_repo.get_by_username(db, "r_monitoring_custom") + if admin is None: + admin = admin_repo.create_admin( + db, username="r_monitoring_custom", password="pass1234", role="custom" + ) + admin.password_hash = hash_password("pass1234") + admin.role = "custom" + admin.pages_override = ["event-logs"] + admin.status = "active" + db.commit() + finally: + db.close() + + token = admin_client.post( + "/admin/api/auth/login", + json={"username": "r_monitoring_custom", "password": "pass1234"}, + ).json()["access_token"] + assert admin_client.get("/admin/api/event-logs", headers=_auth(token)).status_code == 200 + assert admin_client.get("/admin/api/audit-logs", headers=_auth(token)).status_code == 403 + + def test_roles_endpoints_super_only(admin_client, super_token, operator_token) -> None: assert admin_client.get("/admin/api/roles", headers=_auth(super_token)).status_code == 200 assert admin_client.get("/admin/api/roles", headers=_auth(operator_token)).status_code == 403 @@ -123,7 +184,7 @@ def test_builtin_roles_labels_and_pages(admin_client, super_token) -> None: # 页集对齐 Prototypes/dashboard/permissions.md 的 ROLES assert set(roles["finance"]["pages"]) == {"dashboard", "ad-revenue-report", "cps", "withdraws"} assert set(roles["tech"]["pages"]) == { - "dashboard", "device-liveness", "config", "ad-revenue", "huawei-review", + "dashboard", "device-liveness", "analytics-health", "config", "ad-revenue", "huawei-review", "event-logs", "audit-logs", }