后台：新增监控审计权限分组并加强接口鉴权 (#159)

## 变更
- 权限目录新增一级分组“监控审计”，统一设备存活、埋点成功率、埋点日志和审计日志。
- 补齐 `analytics-health` 页面权限，技术角色默认拥有四项监控审计权限；运营默认仅保留设备存活。
- 新增服务端 `require_page` 守卫，四组 API 不再只依赖前端隐藏导航，直接调用也会校验角色或个人页面权限。
- 增加迁移，为存量技术角色补上 `analytics-health` 权限，并同步接口文档。

## 验证
- 改动文件 `ruff check` 通过。
- `tests/test_admin_roles.py tests/test_analytics_health.py`: 24 passed。
- Alembic 从空库 upgrade 到 head，再 downgrade 本迁移：通过。
- 全量测试：443 passed、6 failed；6 项失败在干净 `origin/main` 上原样复现（主干为 442 passed、6 failed），与本 PR 无关。

---------

Co-authored-by: unknown <798648091@qq.com>
Reviewed-on: #159
Co-authored-by: linkeyu <linkeyu@wonderable.ai>
Co-committed-by: linkeyu <linkeyu@wonderable.ai>

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。
 

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",
     ]},
 ]

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"))],
 )
 
 

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"))],
 )
 
 

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"))],
 )
 
 

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"))],
 )