feat(flow): unify member-group-permission admin workflow and docs

app/api/admin.py

@@ -1,4 +1,6 @@
-from fastapi import APIRouter, Depends, HTTPException, status
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
 from sqlalchemy.orm import Session
 
 from app.db.session import get_db
@@ -9,7 +11,12 @@ from app.repositories.permissions_repo import PermissionsRepository
 from app.repositories.sites_repo import SitesRepository
 from app.repositories.systems_repo import SystemsRepository
 from app.repositories.users_repo import UsersRepository
-from app.schemas.permissions import PermissionGrantRequest, PermissionRevokeRequest
+from app.schemas.permissions import (
+    DirectPermissionListResponse,
+    DirectPermissionRow,
+    PermissionGrantRequest,
+    PermissionRevokeRequest,
+)
 from app.security.api_client_auth import require_api_client
 
 router = APIRouter(prefix="/admin", tags=["admin"])
@@ -98,3 +105,42 @@ def revoke_permission(
         site_id=site_id,
     )
     return {"deleted": deleted, "result": "revoked"}
+
+
+@router.get("/permissions/direct", response_model=DirectPermissionListResponse)
+def list_direct_permissions(
+    _: ApiClient = Depends(require_api_client),
+    db: Session = Depends(get_db),
+    keyword: str | None = Query(default=None),
+    scope_type: str | None = Query(default=None),
+    limit: int = Query(default=200, ge=1, le=500),
+    offset: int = Query(default=0, ge=0),
+) -> DirectPermissionListResponse:
+    perms_repo = PermissionsRepository(db)
+    items, total = perms_repo.list_direct_permissions(
+        keyword=keyword,
+        scope_type=scope_type,
+        limit=limit,
+        offset=offset,
+    )
+    return DirectPermissionListResponse(
+        items=[DirectPermissionRow(**item) for item in items],
+        total=total,
+        limit=limit,
+        offset=offset,
+    )
+
+
+@router.delete("/permissions/direct/{permission_id}")
+def delete_direct_permission(
+    permission_id: str,
+    _: ApiClient = Depends(require_api_client),
+    db: Session = Depends(get_db),
+) -> dict[str, int | str]:
+    try:
+        normalized_permission_id = str(UUID(permission_id))
+    except ValueError:
+        raise HTTPException(status_code=status.HTTP_400_BAD_REQUEST, detail="invalid_permission_id")
+    perms_repo = PermissionsRepository(db)
+    deleted = perms_repo.revoke_by_permission_id(normalized_permission_id)
+    return {"deleted": deleted, "result": "revoked"}