fca3326e34
- 更新 changelog.md: v0.2.0 记录 M2-M8 全部完成，路线图更新 - 新增 5 篇指南: RBAC、组织管理、审计日志、通知模块、质量横切 - 新增 5 篇 API 文档: RBAC(11)、Org(5)、Audit(1)、Settings(7)、Notification(7) - 更新 api/overview.md: 完整 37 端点列表 - 更新 config.ts: 侧边栏分组 + 11 页 SEO 元数据
213 lines
2.8 KiB
Markdown
213 lines
2.8 KiB
Markdown
---
|
|
title: RBAC API | 角色权限管理接口 - MengStack官方文档
|
|
---
|
|
|
|
# RBAC 接口
|
|
|
|
所有接口需要认证，并携带 `X-Tenant-ID` 头。
|
|
|
|
## 列出权限
|
|
|
|
**`GET /api/v1/rbac/permissions`**
|
|
|
|
### 查询参数
|
|
|
|
| 参数 | 类型 | 必填 | 说明 |
|
|
|------|------|------|------|
|
|
| `module` | string | 否 | 按模块筛选 |
|
|
|
|
### 响应
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"code": "auth:user:read",
|
|
"name": "查看用户",
|
|
"module": "auth",
|
|
"description": "查看用户列表和详情"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 创建角色
|
|
|
|
**`POST /api/v1/rbac/roles`**
|
|
|
|
### 请求体
|
|
|
|
```json
|
|
{
|
|
"name": "editor",
|
|
"description": "内容编辑者"
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 必填 |
|
|
|------|------|------|
|
|
| `name` | string | 是 |
|
|
| `description` | string | 否 |
|
|
|
|
### 响应
|
|
|
|
返回 `RoleDTO`（含 `permissions` 数组）。
|
|
|
|
### 错误
|
|
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 400 | 参数校验失败 |
|
|
| 409 | 角色名已存在 |
|
|
|
|
---
|
|
|
|
## 列出角色
|
|
|
|
**`GET /api/v1/rbac/roles`**
|
|
|
|
### 响应
|
|
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"tenant_id": "550e8400-...",
|
|
"name": "admin",
|
|
"description": "系统管理员",
|
|
"is_system": true,
|
|
"permissions": [...]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 获取角色详情
|
|
|
|
**`GET /api/v1/rbac/roles/:id`**
|
|
|
|
### 路径参数
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `id` | int | 角色 ID |
|
|
|
|
### 响应
|
|
|
|
返回 `RoleDTO`。
|
|
|
|
---
|
|
|
|
## 更新角色
|
|
|
|
**`PUT /api/v1/rbac/roles/:id`**
|
|
|
|
### 请求体
|
|
|
|
```json
|
|
{
|
|
"name": "senior-editoror",
|
|
"description": "高级编辑"
|
|
}
|
|
```
|
|
|
|
| 字段 | 类型 | 必填 |
|
|
|------|------|------|
|
|
| `name` | string | 否 |
|
|
| `description` | string | 否 |
|
|
|
|
---
|
|
|
|
## 删除角色
|
|
|
|
**`DELETE /api/v1/rbac/roles/:id`**
|
|
|
|
### 错误
|
|
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 403 | 系统角色不可删除 |
|
|
|
|
---
|
|
|
|
## 设置角色权限
|
|
|
|
**`PUT /api/v1/rbac/roles/:id/permissions`**
|
|
|
|
### 请求体
|
|
|
|
```json
|
|
{
|
|
"permission_ids": [1, 2, 3, 5]
|
|
}
|
|
```
|
|
|
|
覆盖该角色的全部权限。
|
|
|
|
---
|
|
|
|
## 获取角色权限
|
|
|
|
**`GET /api/v1/rbac/roles/:id/permissions`**
|
|
|
|
### 响应
|
|
|
|
返回 `PermissionDTO` 数组。
|
|
|
|
---
|
|
|
|
## 分配角色给用户
|
|
|
|
**`POST /api/v1/rbac/users/:userId/roles`**
|
|
|
|
### 路径参数
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `userId` | int | 用户 ID |
|
|
|
|
### 请求体
|
|
|
|
```json
|
|
{
|
|
"role_id": 2
|
|
}
|
|
```
|
|
|
|
### 错误
|
|
|
|
| 状态码 | 说明 |
|
|
|--------|------|
|
|
| 409 | 用户已拥有该角色 |
|
|
|
|
---
|
|
|
|
## 移除用户角色
|
|
|
|
**`DELETE /api/v1/rbac/users/:userId/roles/:roleId`**
|
|
|
|
### 路径参数
|
|
|
|
| 参数 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| `userId` | int | 用户 ID |
|
|
| `roleId` | int | 角色 ID |
|
|
|
|
---
|
|
|
|
## 获取用户角色
|
|
|
|
**`GET /api/v1/rbac/users/:userId/roles`**
|
|
|
|
### 响应
|
|
|
|
返回 `RoleDTO` 数组，包含该用户在此租户下的所有角色及权限。
|