OneAuth/doc/permission.md

# VBase 权限系统文档

## 1. 权限模型概述

VBase 是一个类似 **Supabase** 的 BaaS 平台，为 2C（个人开发者）和 2B（团队/企业）用户提供后端资源托管服务。权限系统采用 **RBAC + ABAC** 混合模型，支持三级权限体系：

- **平台级 (Platform)**: 用户管理自己的账号和数据
- **项目级 (Project)**: 项目内的成员管理和资源控制
- **资源级 (Resource)**: 具体资源的读写操作

---

## 2. 核心概念

### 2.1 权限层级

```
┌─────────────────────────────────────────────────────────────┐
│                    平台级权限 (Platform)                     │
│  - 管理自己的用户信息                                        │
│  - 创建新项目                                               │
│  - 管理第三方账号绑定                                        │
│  - 访问被邀请的项目                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ (进入项目上下文)
┌─────────────────────────────────────────────────────────────┐
│                    项目级权限 (Project)                      │
│  - 项目设置管理 (所有者/管理员)                               │
│  - 成员邀请和管理                                            │
│  - 资源创建和管理                                            │
│  - 查看项目统计信息                                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼ (访问具体资源)
┌─────────────────────────────────────────────────────────────┐
│                    资源级权限 (Resource)                     │
│  - 数据库读写操作                                            │
│  - 存储文件上传下载                                          │
│  - 函数调用和管理                                            │
│  - API 密钥管理                                              │
└─────────────────────────────────────────────────────────────┘
```

### 2.2 实体关系

```
User (平台用户)
  ├── Platform Permission (平台级权限)
  │     └── 默认: 管理自己的数据
  │
  └── OrgMember (项目成员关系)
        ├── Org/Project (项目)
        │     ├── Resource (项目资源)
        │     └── Resource (项目资源)
        │
        └── Role (项目角色)
              └── Policy (策略)
```

### 2.3 使用场景示例

**场景1: 个人开发者 (2C)**
```
小明 (User)
├── 个人信息管理 (平台级)
├── 我的项目A (Org)
│   ├── 数据库资源
│   └── 存储资源
└── 我的项目B (Org)
    └── ...
```

**场景2: 团队协作 (2B)**
```
CEO (User)
├── 拥有的项目: WebApp, MobileApp
└── 角色: 所有者 (Owner)

CTO (User)
├── 参与的项目: WebApp (Admin), MobileApp (Developer)
└── 角色: 管理员/开发者

员工A (User)
├── 参与的项目: WebApp (Developer)
└── 角色: 开发者
```

### 2.2 策略 (Policy)

策略是权限控制的最小单元，定义了对特定资源的操作权限。

**策略结构：**

```go
type Policy struct {
    Code        string // 策略编码，唯一标识
    Name        string // 策略名称
    Description string // 策略描述
    Resource    string // 资源类型: user/org/member/policy/role/*
    Action      string // 操作: create/read/update/delete/*
    Effect      string // 效果: allow/deny
    Condition   string // 条件表达式
    Priority    int    // 优先级: 数字越大优先级越高
    IsSystem    bool   // 是否系统策略
}
```

**策略分类：**

**平台级策略** (无 org_id 上下文)
| 策略 | 资源 | 操作 | 效果 | 条件 | 说明 |
|------|------|------|------|------|------|
| user:read:own | user | read | allow | owner | 读取自己的用户信息 |
| user:update:own | user | update | allow | owner | 更新自己的用户信息 |
| binding:manage | binding | * | allow | - | 管理第三方账号绑定 |
| org:create | org | create | allow | - | 创建新项目 |

**项目级策略** (需要 org_id 上下文)
| 策略 | 资源 | 操作 | 效果 | 条件 | 说明 |
|------|------|------|------|------|------|
| org:admin | * | * | allow | org_owner | 项目所有者拥有所有权限 |
| org:update | org | update | allow | admin | 更新项目设置 |
| member:read | member | read | allow | member | 读取项目成员列表 |
| member:manage | member | * | allow | admin | 管理项目成员 |
| resource:create | resource | create | allow | developer | 创建项目资源 |
| resource:delete | resource | delete | allow | admin | 删除项目资源 |

### 2.4 角色 (Role)

角色是一组策略的集合，在项目级别定义。

**角色结构：**

```go
type Role struct {
    ID          string   // 角色ID
    OrgID       string   // 所属项目
    Name        string   // 角色名称
    Description string   // 角色描述
    PolicyIDs   []string // 关联的策略ID列表
    Scope       string   // 作用域: project/resource
    IsSystem    bool     // 是否系统角色
}
```

**系统内置角色：**

| 角色 | 适用对象 | 权限范围 | 说明 |
|------|----------|----------|------|
| **owner** | 项目所有者 | 全部权限 | 项目的创建者，拥有所有权限，可删除项目 |
| **admin** | 管理员 | 项目级管理 | 管理项目设置、成员、资源，但不能删除项目 |
| **developer** | 开发者 | 资源级操作 | 创建和管理资源（数据库、存储、函数） |
| **viewer** | 访客 | 只读访问 | 只能查看项目和资源信息，不能修改 |

### 2.4 条件 (Condition)

条件用于实现 ABAC，支持以下类型：

| 条件 | 说明 | 使用场景 |
|------|------|----------|
| "" | 无条件，始终匹配 | 通用权限 |
| "owner" | 资源所有者 | 只能操作自己的数据 |
| "org_member" | 组织成员 | 组织内数据访问 |
| "org_owner" | 组织所有者 | 所有者权限判断 |

---

## 3. 权限检查流程

### 3.1 流程图

```
┌─────────────────┐
│   请求进入       │
│  user, org,     │
│  resource, action│
└────────┬────────┘
         │
         ▼
┌─────────────────┐    命中     ┌─────────────────┐
│   检查缓存       │────────────→│  返回缓存结果    │
│   Redis         │             │  allow/deny     │
└────────┬────────┘             └─────────────────┘
         │ 未命中
         ▼
┌─────────────────┐
│ 1. 检查组织所有者 │────────┐
└────────┬────────┘        │
         │ 是              │
         ▼                 │
   ┌──────────┐            │
   │ 返回 Allow│────────────┘
   └──────────┘
         │ 否
         ▼
┌─────────────────┐
│ 2. 获取用户角色  │
│   从 OrgMember   │
│   获取 role_ids  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 3. 获取角色策略  │
│   解析所有策略   │
│   去重合并      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 4. 检查 Deny 策略│────────┐
│   高优先级优先   │        │
└────────┬────────┘        │
         │ 匹配 Deny       │
         ▼                 │
   ┌──────────┐            │
   │返回 Deny │────────────┘
   │ 缓存结果  │
   └──────────┘
         │ 无 Deny
         ▼
┌─────────────────┐
│ 5. 检查 Allow 策略│────────┐
└────────┬────────┘        │
         │ 匹配 Allow      │
         ▼                 │
   ┌──────────┐            │
   │返回 Allow│────────────┘
   │ 缓存结果  │
   └──────────┘
         │ 无 Allow
         ▼
┌─────────────────┐
│ 6. 默认拒绝      │────────→ 返回 Deny
└─────────────────┘            缓存结果
```

### 3.2 决策规则

1. **Deny 优先**: 如果匹配到 Deny 策略，直接拒绝
2. **显式 Allow**: 必须匹配到 Allow 策略才允许
3. **默认拒绝**: 未匹配到任何策略时拒绝
4. **优先级**: 高优先级策略优先匹配

---

## 4. 使用指南

### 4.1 检查权限

**代码示例：**

```go
import "github.com/veypi/vbase/internal/service"

func SomeHandler(x *vigo.X) error {
    userID := middleware.CurrentUser(x)
    orgID := middleware.CurrentOrg(x)

    checker := service.NewPermissionChecker()
    result, err := checker.Check(userID, orgID, "user", "update", map[string]any{
        "owner_id": targetUserID,
    })

    if err != nil || !result.Allowed {
        return vigo.ErrForbidden.WithString(result.Reason)
    }

    // 继续处理...
}
```

### 4.2 创建自定义策略

```go
policy := &model.Policy{
    Code:        "custom:resource:action",
    Name:        "自定义策略",
    Description: "允许特定用户操作",
    Resource:    "resource_name",
    Action:      "action_name",  // create/read/update/delete
    Effect:      model.EffectAllow,
    Condition:   "owner",        // owner/org_member/空
    Priority:    50,
}

model.DB.Create(policy)
```

### 4.3 创建角色并授权

```go
// 创建角色
role := &model.Role{
    OrgID:       orgID,
    Name:        "部门管理员",
    Description: "管理部门成员",
    PolicyIDs:   "policy1,policy2,policy3",
}
model.DB.Create(role)

// 分配给用户
member := &model.OrgMember{
    OrgID:   orgID,
    UserID:  userID,
    RoleIDs: role.ID,
}
model.DB.Create(member)
```

---

## 5. 系统内置策略

### 5.1 用户相关

```go
// 读取自己
SysPolicyUserReadOwn = "sys:user:read:own"
Resource:  "user"
Action:    "read"
Condition: "owner"

// 更新自己
SysPolicyUserUpdateOwn = "sys:user:update:own"
Resource:  "user"
Action:    "update"
Condition: "owner"

// 删除自己
SysPolicyUserDeleteOwn = "sys:user:delete:own"
Resource:  "user"
Action:    "delete"
Condition: "owner"
```

### 5.2 组织相关

```go
// 组织管理员
SysPolicyOrgAdmin = "sys:org:admin"
Resource:  "*"
Action:    "*"
Condition: "org_owner"
Priority:  100

// 读取组织
SysPolicyOrgRead = "sys:org:read"
Resource:  "org"
Action:    "read"
Condition: "org_member"
```

### 5.3 成员相关

```go
// 读取成员
SysPolicyMemberRead = "sys:member:read"
Resource:  "member"
Action:    "read"
Condition: "org_member"

// 管理成员
SysPolicyMemberManage = "sys:member:manage"
Resource:  "member"
Action:    "*"
Condition: ""
```

### 5.4 角色策略相关

```go
// 读取角色
SysPolicyRoleRead = "sys:role:read"
Resource:  "role"
Action:    "read"
Condition: "org_member"

// 管理角色
SysPolicyRoleManage = "sys:role:manage"
Resource:  "role"
Action:    "*"
Condition: ""

// 读取策略
SysPolicyPolicyRead = "sys:policy:read"
Resource:  "policy"
Action:    "read"
Condition: ""

// 管理策略
SysPolicyPolicyManage = "sys:policy:manage"
Resource:  "policy"
Action:    "*"
Condition: ""
```

---

## 6. 权限缓存

### 6.1 缓存机制

```
缓存键: perm:{user_id}:{org_id}:{resource}:{action}
TTL: 1分钟
值: "allow" 或 "deny"
```

### 6.2 缓存失效

以下操作会触发缓存清除：

- 用户角色变更
- 角色策略变更
- 策略内容变更
- 组织成员变更

```go
// 清除用户权限缓存
service.ClearUserPermissionCache(userID)

// 清除组织权限缓存
service.ClearOrgPermissionCache(orgID)
```

### 6.3 缓存命中率优化

- 权限变更频率低，1分钟 TTL 平衡了性能和实时性
- 批量操作时建议先清除缓存，操作完成后统一刷新

---

## 7. 最佳实践

### 7.1 策略设计

1. **最小权限原则**: 只授予完成任务所需的最小权限
2. **职责分离**: 敏感操作需要多个角色共同完成
3. **策略命名规范**: `{resource}:{action}:{condition}`

### 7.2 角色设计

```
组织层级角色体系:
├── owner (所有者)
│     └── 全部权限
├── admin (管理员)
│     └── 管理成员、角色、策略
├── manager (部门经理)
│     └── 管理部门成员
└── member (普通成员)
      └── 基础访问权限
```

### 7.3 权限检查位置

**Controller 层检查:**
```go
func Handler(x *vigo.X) error {
    // 先检查权限
    if !hasPermission(x, "resource", "action") {
        return vigo.ErrForbidden
    }
    // 执行业务逻辑
}
```

**Service 层检查（数据级）:**
```go
func UpdateUser(userID string, data map[string]any) error {
    // 检查是否是本人或管理员
    if !isOwner(userID) && !hasAdminRole() {
        return ErrForbidden
    }
    // 执行更新
}
```

### 7.4 权限测试

```go
func TestPermissionCheck(t *testing.T) {
    tests := []struct {
        name     string
        userID   string
        orgID    string
        resource string
        action   string
        data     map[string]any
        want     bool
    }{
        {
            name:     "owner can update own profile",
            userID:   "user1",
            orgID:    "",
            resource: "user",
            action:   "update",
            data:     map[string]any{"owner_id": "user1"},
            want:     true,
        },
        {
            name:     "user cannot update others profile",
            userID:   "user1",
            orgID:    "",
            resource: "user",
            action:   "update",
            data:     map[string]any{"owner_id": "user2"},
            want:     false,
        },
    }

    checker := service.NewPermissionChecker()
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result, _ := checker.Check(tt.userID, tt.orgID, tt.resource, tt.action, tt.data)
            if result.Allowed != tt.want {
                t.Errorf("Check() = %v, want %v", result.Allowed, tt.want)
            }
        })
    }
}
```

---

## 8. 故障排查

### 8.1 权限检查失败

**检查步骤：**

1. 确认用户已登录
2. 确认用户是组织成员
3. 检查用户角色
4. 检查角色绑定的策略
5. 检查策略的 Effect 和 Condition

**调试日志：**

```go
// 开启调试日志
checker := service.NewPermissionChecker()
result, err := checker.Check(userID, orgID, resource, action, data)
log.Printf("Permission check: user=%s, resource=%s, action=%s, allowed=%v, reason=%s",
    userID, resource, action, result.Allowed, result.Reason)
```

### 8.2 缓存问题

```bash
# 清除 Redis 权限缓存
redis-cli KEYS "perm:*" | xargs redis-cli DEL

# 或重启应用（开发环境）
```

### 8.3 权限不生效

1. 检查策略是否保存成功
2. 检查角色是否正确绑定策略
3. 检查用户是否正确分配角色
4. 检查缓存是否已清除

---

## 9. 扩展开发

### 9.1 添加自定义条件

```go
// 在 permission.go 中扩展 evaluateCondition
func (pc *PermissionChecker) evaluateCondition(p *model.Policy, userID, orgID string, resourceData map[string]any) bool {
    switch p.Condition {
    case "owner":
        // 现有逻辑...
    case "custom_condition":
        // 自定义条件逻辑
        return checkCustomCondition(userID, orgID, resourceData)
    default:
        return true
    }
}
```

### 9.2 添加资源类型

```go
// 在 policy.go 中添加资源常量
const (
    ResourceUser    = "user"
    ResourceOrg     = "org"
    ResourceMember  = "member"
    ResourceCustom  = "custom_resource"  // 新增
)
```

---

## 10. 参考

- [RBAC 模型](https://en.wikipedia.org/wiki/Role-based_access_control)
- [ABAC 模型](https://en.wikipedia.org/wiki/Attribute-based_access_control)
- [NIST RBAC 标准](https://csrc.nist.gov/projects/role-based-access-control)