OneAuth/doc/permission_design.md

# VBase 权限模型设计文档

## 核心原则

1. **Policy（策略）**：定义"什么权限可以访问哪些接口"
2. **Role（角色）**：Policy 的集合，简化授权
3. **授权关系**：用户通过 Role 或直接与 Policy 关联，并携带数据范围

---

## 表结构关系

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│     Policy      │◄────┤   PolicyRoute    │     │      Role       │
│  (策略定义)      │     │  (策略路由绑定)   │     │   (角色定义)     │
└────────┬────────┘     └──────────────────┘     └────────┬────────┘
         │                                               │
         │ Many-to-Many                                  │ Many-to-Many
         │                                               │
         ▼                                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                    UserPermission (用户授权)                      │
│  ├─ user_id: 用户ID                                              │
│  ├─ policy_code: 策略代码 (或直接关联 Policy)                      │
│  ├─ role_id: 角色ID (可选，与 policy_code 二选一)                  │
│  ├─ resource: 资源类型 (project/org/...)                         │
│  ├─ resource_id: 具体资源ID (proj-123, * 表示所有)                  │
│  ├─ scope: 权限范围 (owner/admin/member)                         │
│  └─ expire_at: 过期时间 (可选)                                    │
└─────────────────────────────────────────────────────────────────┘
```

---

## 详细表设计

### 1. Policy（策略表）

定义权限的本质：对某资源可以执行什么操作

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | UUID |
| code | string | **唯一标识**，如 `project:read`, `project:write`, `project:admin` |
| resource | string | 资源类型：`user`, `org`, `project`, `*`(所有) |
| action | string | 操作类型：`create`, `read`, `update`, `delete`, `list`, `*`, `admin` |
| effect | string | `allow` / `deny` |
| scope | string | 作用域：`platform`(平台级) / `org`(组织级) |
| description | string | 描述 |

**示例数据：**

```sql
-- 项目相关权限
('p1', 'project:create', 'project', 'create', 'allow', 'org', '创建项目')
('p2', 'project:read',   'project', 'read',   'allow', 'org', '查看项目')
('p3', 'project:write',  'project', 'write',  'allow', 'org', '编辑项目(包含read)')
('p4', 'project:delete', 'project', 'delete', 'allow', 'org', '删除项目')
('p5', 'project:admin',  'project', 'admin',  'allow', 'org', '项目管理员(包含所有)')

-- 通配权限
('p9', 'project:*',      'project', '*',      'allow', 'org', '所有项目权限')
('p0', '*:*',            '*',       '*',      'allow', 'platform', '超级管理员')
```

**层级关系：**
```
project:admin > project:write > project:read
    │              │              └─ project:create, project:delete
    └──────────────┴──────────────────────────────────────────────
```

---

### 2. PolicyRoute（策略路由绑定表）

Policy 与具体接口的绑定关系。一个 Policy 可以绑定多个路由。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | UUID |
| policy_id | string | 关联 Policy.id |
| domain | string | 应用域，如 `vbase`, `myapp` |
| prefix | string | 路由前缀，如 `/api/v1` |
| pattern | string | 路由模式，如 `/projects`, `/projects/{id}` |
| method | string | HTTP 方法：`GET`, `POST`, `*`, ... |
| resource_id_param | string | 从 URL 提取资源ID的参数名，如 `id` |
| description | string | 接口描述 |

**示例数据：**

```sql
-- project:read 权限可以访问以下接口
('r1', 'p2', 'myapp', '/api/v1', '/projects',           'GET',    '',    '项目列表')
('r2', 'p2', 'myapp', '/api/v1', '/projects/{id}',      'GET',    'id',  '项目详情')
('r3', 'p2', 'myapp', '/api/v1', '/projects/{id}/logs', 'GET',    'id',  '项目日志')

-- project:write 权限
('r4', 'p3', 'myapp', '/api/v1', '/projects/{id}',      'PATCH',  'id',  '更新项目')
('r5', 'p3', 'myapp', '/api/v1', '/projects/{id}/env',  'PUT',    'id',  '更新环境变量')

-- project:create 权限
('r6', 'p1', 'myapp', '/api/v1', '/projects',           'POST',   '',    '创建项目')

-- project:admin 权限（包含所有）
('r7', 'p5', 'myapp', '/api/v1', '/projects/{id}/members', 'GET',  'id',  '成员管理')
('r8', 'p5', 'myapp', '/api/v1', '/projects/{id}/settings', '*', 'id',  '设置管理')
```

---

### 3. Role（角色表）

Policy 的集合，用于批量授权。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | UUID |
| org_id | string | 组织ID（系统角色为空） |
| code | string | 角色代码：`admin`, `developer`, `viewer`, `owner` |
| name | string | 角色名称 |
| policy_codes | string | 关联的 Policy code 列表，逗号分隔 |
| is_system | bool | 是否系统预设角色 |

**示例数据：**

```sql
-- 系统预设角色
('r1', '', 'owner',      '所有者',      'project:admin,org:admin,*:*', true)
('r2', '', 'admin',      '管理员',      'project:write,org:read,user:read', true)
('r3', '', 'developer',  '开发者',      'project:write,resource:read', true)
('r4', '', 'viewer',     '只读用户',    'project:read', true)

-- 组织自定义角色
('r5', 'org-123', 'pm', '项目经理', 'project:admin', false)
```

---

### 4. UserPermission（用户授权表）

核心授权表，记录"谁对什么资源有什么权限"。

| 字段 | 类型 | 说明 |
|------|------|------|
| id | string | UUID |
| user_id | string | 用户ID |
| org_id | string | 组织ID（可选） |
| **policy_code** | string | **策略代码**（如 `project:read`） |
| **resource** | string | **资源类型**（如 `project`） |
| **resource_id** | string | **具体资源ID**（如 `proj-123` 或 `*`） |
| granted_by | string | 授权来源：`role`(通过角色) / `direct`(直接授权) |
| source_id | string | 来源ID（Role ID 或留空） |
| expire_at | timestamp | 过期时间（可选，永久有效为空） |
| created_at | timestamp | 创建时间 |

**关键设计：**
- `resource_id = *` 表示对该类型所有资源的权限
- 数据级权限通过具体的 `resource_id` 实现
- 用户最终权限 = 直接授权 + 角色授权 的并集

**示例数据：**

```sql
-- 场景：用户 A
-- 1. 是项目 1 的 admin（直接授权）
('up1', 'user-a', 'org-1', 'project:admin', 'project', 'proj-1', 'direct', '', null)

-- 2. 是项目 2 的只读成员（直接授权）
('up2', 'user-a', 'org-1', 'project:read', 'project', 'proj-2', 'direct', '', null)

-- 3. 通过 developer 角色获得对所有项目的 write 权限
('up3', 'user-a', 'org-1', 'project:write', 'project', '*', 'role', 'role-dev-id', null)

-- 4. 临时授权，3天后过期
('up4', 'user-a', 'org-1', 'project:admin', 'project', 'proj-3', 'direct', '', '2025-02-20 00:00:00')
```

---

## 权限检查流程

```
请求: GET /api/v1/projects/proj-123/settings
      Header: X-Org-ID: org-1

      │
      ▼
┌─────────────────────────────────────┐
│ 1. 路由匹配                          │
│    domain=myapp + method=GET +      │
│    pattern=/projects/{id}/settings   │
│                                     │
│    找到: PolicyRoute.r8             │
│    对应: Policy.p5 (project:admin)  │
│    提取: resource_id = "proj-123"   │
└─────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────┐
│ 2. 获取用户权限列表                   │
│    SELECT * FROM user_permissions   │
│    WHERE user_id = 'user-a'         │
│      AND resource = 'project'       │
│      AND (resource_id = 'proj-123'  │
│           OR resource_id = '*')     │
└─────────────────────────────────────┘
      │
      ▼
┌─────────────────────────────────────┐
│ 3. 权限层级匹配                        │
│    需要的权限: project:admin          │
│                                     │
│    用户有的权限:                      │
│    - project:admin (proj-1) ❌       │
│    - project:read (proj-2)   ❌       │
│    - project:write (*)       ❌       │
│      (write < admin)                │
│                                     │
│    结果: 拒绝 ❌                     │
└─────────────────────────────────────┘
      │
      ▼
拒绝，返回 X-Required-URL: /apply-perm?resource=project&action=admin&id=proj-123
```

---

## 场景覆盖

### 场景1：用户是项目 owner，拥有所有权限
```sql
INSERT INTO user_permissions (user_id, policy_code, resource, resource_id)
VALUES ('user-a', 'project:admin', 'project', 'proj-1')
-- 自动包含 project:read/write/delete/create
```

### 场景2：平台管理员，拥有所有资源的所有权限
```sql
-- 方案一：通配符
INSERT INTO user_permissions (user_id, policy_code, resource, resource_id)
VALUES ('admin', '*:*', '*', '*')

-- 方案二：绑定 owner 角色
-- Role.owner 包含 policy_codes: '*:*'
```

### 场景3：组织管理员，拥有组织内所有项目权限
```sql
-- 组织 admin 角色包含 project:*
-- 在组织上下文内生效
INSERT INTO user_permissions (user_id, org_id, policy_code, resource, resource_id, granted_by)
VALUES ('user-a', 'org-1', 'project:*', 'project', '*', 'role')
```

### 场景4：用户加入多个项目，权限不同
```sql
-- 项目1: admin
INSERT INTO user_permissions VALUES ('u1', 'project:admin', 'project', 'proj-1', ...)

-- 项目2: read
INSERT INTO user_permissions VALUES ('u1', 'project:read', 'project', 'proj-2', ...)

-- 项目3: write
INSERT INTO user_permissions VALUES ('u1', 'project:write', 'project', 'proj-3', ...)
```

---

## 与旧方案对比

| 维度 | 旧方案 (RoutePolicy) | 新方案 (Policy + UserPermission) |
|------|---------------------|--------------------------------|
| 核心思想 | 接口白名单 | 资源操作权限 |
| 配置粒度 | 每个接口单独配置 | 按 Resource + Action 配置 |
| 数据级权限 | 难实现 | 通过 resource_id 字段 |
| 通配授权 | 不支持 | 支持 `*` |
| 层级权限 | 无 | admin > write > read |
| 新增接口成本 | 高（需给所有角色加策略） | 低（绑定到 Policy 即可）|
| 角色数量 | 多（每项目配角色） | 少（复用系统角色 + 数据范围）|

---

请确认此设计后，我开始修改代码。