shaguabijia-app-server/docs/api/admin/admin-roles.md

/admin/api/roles — 角色与可见页管理(RBAC,#117/#126)

所属:Admin 子应用(前缀 /admin/api,独立 admin JWT) | 鉴权:super_admin | 表 admin_role | ← 返回 API 索引

后台 RBAC 的数据驱动层:内建三角色(super_admin/finance/operator,is_builtin=true 不可删)+ 自定义角色(勾任意页面组合)。管理员的有效可见页 = admin_user.pages_override(个人覆盖,非空优先)∪ 否则取其角色 pages;super_admin 恒全通。

端点

方法 + 路径	说明
GET /admin/api/roles	角色列表:[{id, name, label, pages, is_builtin, admin_count}](含每个角色的使用人数)
GET /admin/api/roles/catalog	页面权限目录(分组):全部可勾选的页面 key(来自 app/admin/permissions.py 常量,不落库),前端渲染勾选面板用
POST /admin/api/roles	新增自定义角色 {name, pages}(name(key)= label = 输入名称;不能叫 super_admin,重名 409);带审计
PATCH /admin/api/roles/{role_id}	改展示名/可见页(内建角色的 pages 也可调);带审计
DELETE /admin/api/roles/{role_id}	删角色;内建(is_builtin)与在用(有 admin_user.role 引用)不可删(400);带审计

说明

• 管理员个人覆盖在 PATCH /admin/api/admins/{id} 的 pages_override 字段改,不在本组。
• 加新后台页面要同步登记 permissions.py 目录,表里只存勾选结果(目录变更无需迁移)。