feat(role): role bind

docs/SCALAR_GUIDE.md

@@ -149,6 +149,17 @@
 
 下一步依赖：`access_token`。
 
+（可选）使用 refresh_token 自动续期：
+
+- **POST** `/auth/refresh`
+- Tag：`Auth`
+- Header：无
+- Body：
+
+```json
+{ "refresh_token": "<opaque>" }
+```
+
 ### Step 3：获取当前租户信息（Tenant）
 
 **GET** `/tenants/me`
@@ -319,6 +330,133 @@ enabled_apps 维护建议：
 { "code": 0, "message": "Success", "data": [{ "id": "<role_id>", "name": "Admin", "description": "..." }], "trace_id": null }
 ```
 
+## Role & Permission Management
+
+本节补齐“角色（Role）与权限（Permission）管理”的完整指引，适用于横向扩展到多个应用（如 `cms` / `tms` / `iam` 等）。
+
+### 权限模型（可扩展到十几个应用）
+
+权限编码规范：
+- `permission.code` 统一采用：`${app_code}:${resource}:${action}`
+  - 示例：`cms:article:publish`、`tms:task:assign`、`iam:tenant:enabled_apps:write`
+- `app_code` 必须与应用注册表（app_registry）中的应用标识一致（本项目对应表为 `apps.id`）。
+- 支持通配符（需要在 `permissions.code` 中显式存储通配符权限并分配到角色）：
+  - `cms:*:*`：CMS 全权限
+  - `cms:article:*`：文章相关全权限
+
+> 说明：鉴权时支持通配符匹配（例如持有 `cms:article:*` 可满足 `cms:article:publish`），但只有当该通配符权限被写入 `permissions` 并绑定到角色时才会生效。
+
+数据库关系（ER 图）：
+
+```mermaid
+erDiagram
+  apps {
+    VARCHAR id PK
+    VARCHAR name
+    VARCHAR status
+  }
+  permissions {
+    UUID id PK
+    VARCHAR code
+    TEXT description
+    VARCHAR resource
+    VARCHAR action
+  }
+  users {
+    UUID id PK
+    UUID tenant_id FK
+    VARCHAR email
+  }
+  roles {
+    UUID id PK
+    UUID tenant_id FK
+    VARCHAR name
+    BOOLEAN is_system
+  }
+  role_permissions {
+    UUID role_id FK
+    UUID permission_id FK
+  }
+  user_roles {
+    UUID user_id FK
+    UUID role_id FK
+  }
+
+  apps ||--o{ permissions : namespaces
+  roles ||--o{ role_permissions : grants
+  permissions ||--o{ role_permissions : assigned
+  users ||--o{ user_roles : has
+  roles ||--o{ user_roles : assigned
+```
+
+应用区分方式：
+- 通过 `apps`（app_registry）维护“允许的应用标识”，并要求权限码的 `app_code` 与 `apps.id` 一致。
+- 在租户侧通过 `enabled_apps` 控制某租户开通哪些应用；登录/权限查询会按 `enabled_apps` 过滤应用级权限（例如 `cms:*:*` 会在租户未开通 `cms` 时被过滤）。
+
+### 1) 为 CMS 添加最小必要权限（SQL）
+
+脚本位置：`scripts/db/migrations/0006_cms_permissions.sql`
+
+包含权限项：
+- 文章：创建、编辑、发布
+- 栏目：管理
+- 媒体库：管理
+- 系统配置：管理
+
+### 2) 查询权限列表（分页/搜索）
+
+**GET** `/permissions?page=1&page_size=20&app_code=cms&search=article`
+
+- Tag：`Permission`
+- Header：`Authorization: Bearer <access_token>`
+- 需要权限：`role:read`
+
+### 3) 角色 CRUD（Role）
+
+创建角色：
+- **POST** `/roles`
+
+查询角色详情：
+- **GET** `/roles/{id}`
+
+更新角色：
+- **PATCH** `/roles/{id}`
+
+删除角色：
+- **DELETE** `/roles/{id}`
+
+说明：
+- 系统内置角色（`is_system=true`，如 `Admin`）不允许通过 API 修改/删除。
+
+### 4) 为角色批量绑定/解绑权限
+
+绑定权限（批量）：
+- **POST** `/roles/{id}/permissions/grant`
+- Body：
+
+```json
+{ "permission_codes": ["cms:article:create", "cms:article:publish"] }
+```
+
+解绑权限（批量）：
+- **POST** `/roles/{id}/permissions/revoke`
+
+### 5) 批量给用户授予/回收角色
+
+批量授予：
+- **POST** `/roles/{id}/users/grant`
+- Body：
+
+```json
+{ "user_ids": ["<user_id_1>", "<user_id_2>"] }
+```
+
+批量回收：
+- **POST** `/roles/{id}/users/revoke`
+
+审计说明：
+- 角色创建/更新/删除、角色-权限绑定/解绑、角色-用户授予/回收都会写入 `audit_logs`。
+
 ### Step 7：用户-角色绑定（User）
 
 用户注册后默认无角色；通常由具备 `user:write` 的管理员进行角色分配。