# 鉴权与授权模块设计 (Authentication & Authorization)

`auth` 模块为 VBase 应用提供了灵活且强大的权限控制系统。它摒弃了隐式的“所有权猜测”，转而采用**显式授权**（ACL）和**手动鉴权**相结合的策略，以确保系统的安全性和可维护性。

## 1. 核心鉴权机制概览

我们提供三种层级的鉴权方式，分别适用于不同的业务场景：

| 方式 | 描述 | 适用场景 | 示例 |
| :--- | :--- | :--- | :--- |
| **全局中间件** (`Perm`) | 检查用户是否拥有某种**全局能力**（基于角色）。 | 管理后台、列表查询、无需特定资源ID的操作。 | `user:read` (查看所有用户) |
| **简单手动鉴权** (Manual) | 在业务代码中直接检查资源字段（如 `OwnerID`）。 | **高频/私有资源**（如订单、日志），逻辑简单且追求高性能。 | 修改自己的订单 |
| **复杂资源鉴权** (`PermOnResource`) | 基于数据库 ACL 表检查用户对**特定实例**的权限。 | **高价值/共享资源**（如项目、组织），需要精细控制和跨用户授权。 | 修改项目成员 |

---

## 2. 基础：上下文与中间件

### 2.1 认证中间件 (AuthMiddleware)

认证中间件仅负责验证 JWT Token 的有效性，并将核心的用户 ID 注入到请求上下文中。为了保持高性能，它**不会**预加载用户详情、角色或组织信息。

### 2.2 上下文访问

请使用 `auth` 包提供的辅助函数来访问上下文中的认证信息：

```go
func MyHandler(x *vigo.X) {
    // 1. 获取当前用户 ID (核心，所有认证请求都可用)
    userID := auth.GetUserID(x) 
    
    if userID == "" {
        // 未登录
        return vigo.ErrUnauthorized
    }

    // 2. 获取当前组织 ID 
    // 注意：仅当路由使用了 LoadOrg 中间件，或手动调用了 LoadOrg 后才可用
    orgID  := auth.GetOrgID(x)  
    
    // 3. 获取在当前组织中的角色列表
    // 注意：仅当路由使用了 LoadOrg 中间件后可用
    roles := auth.GetOrgRoles(x)
}
```

### 2.3 组织上下文加载 (LoadOrg)

对于需要组织上下文的接口（如 `/api/orgs/{org_id}/...`），使用 `LoadOrg` 中间件按需加载组织信息。

- **行为**: 自动从 Path (`{org_id}`), Query (`?org_id=`), Header (`X-Org-ID`) 中解析组织 ID。
- **验证**: 检查当前用户是否为该组织的有效成员。
- **注入**: 将 OrgID 和用户在该组织的角色注入上下文。

```go
// 路由注册示例
// 对于需要组织上下文的接口，显式添加 LoadOrg 中间件
Router.Get("/{org_id}", "获取组织详情", auth.VBaseAuth.LoadOrg, auth.VBaseAuth.Perm("org:read"), get)
```

---

## 3. 场景一：全局/类别权限 (Perm 中间件)

用于控制“谁能进入这个门”。不关心具体操作哪个数据，只关心你有没有这个资格。

- **原理**: 检查用户的角色（Role）是否包含指定权限。
- **配置**: 通常在路由定义时使用。

```go
// 只有管理员 (拥有 user:delete 权限) 可以删除用户
Router.Delete("/{user_id}", auth.VBaseAuth.Perm("user:delete"), DeleteUser)

// 只有拥有 user:read 权限的人可以查看列表
Router.Get("/", auth.VBaseAuth.Perm("user:read"), ListUsers)
```

---

## 4. 场景二：简单手动鉴权 (Manual Check)

对于大多数业务场景（如电商订单、个人博客文章），资源的所有权非常明确且单一。此时，直接在业务代码中判断 `UserID` 字段是最简单、最高效的方式。

**推荐范式：**

```go
// 更新文章 (PATCH /articles/{id})
func UpdateArticle(x *vigo.X) {
    // 1. 获取 ID
    articleID := x.PathParams.Get("id")
    currentUserID := auth.GetUserID(x)
    
    // 2. 查库获取资源
    article := db.GetArticle(articleID)
    
    // 3. 【核心鉴权逻辑】
    // 允许条件：(我是作者) OR (我是管理员/有特权)
    if article.OwnerID != currentUserID {
        // 如果不是作者，再检查是否有全局权限进行兜底
        if !auth.VBaseAuth.CheckPerm(x.Context(), currentUserID, "", "article:update", "") {
             return vigo.ErrForbidden
        }
    }
    
    // 4. 执行更新
    db.Save(article)
}
```

**优点**:
- **零开销**: 不需要额外的 ACL 表查询。
- **逻辑清晰**: 鉴权逻辑与业务逻辑紧密结合，不易出错。

---

## 5. 场景三：复杂资源鉴权 (PermOnResource 中间件)

对于像“项目协作”、“共享文档”这样需要多人协作、权限动态分配的资源，简单的字段判断就不够用了。这时我们需要引入 ACL (Access Control List)。

### 5.1 使用方法

**路由配置**:
告诉中间件去检查 `user_permissions` 表，看当前用户对这个 `project_id` 是否有 `project:update` 权限。

```go
// 这里的 "project_id" 是 URL 路径参数的 key
Router.Patch("/{project_id}", auth.VBaseAuth.PermOnResource("project:update", "project_id"), UpdateProject)
```

### 5.2 授权 (Grant)

在创建资源时，必须**显式**授予创建者权限。

```go
func CreateProject(x *vigo.X) {
    // ... 创建项目逻辑 ...
    project := db.CreateProject(...)

    // 【关键】赋予创建者对该资源的全部权限
    // 权限ID "project:*" 表示对该项目的所有操作权限
    auth.VBaseAuth.GrantResourcePerm(x.Context(), currentUserID, orgID, "project:*", project.ID)
}
```

---

## 6. 设计决策记录 (ADR)

### 6.1 废弃隐式所有权推断 (PermWithOwner)
我们移除了曾尝试自动推断资源所有权的 `PermWithOwner` 中间件。因为在中间件层无法准确知道资源的 `OwnerID` 字段名，也无法处理复杂的“多所有者”场景，这导致了安全漏洞和难以调试的错误。现在我们推荐使用 **Manual Check** 模式。

### 6.2 上下文精简
为了减少内存占用和数据库压力，Request Context (`vigo.X`) 中现在**仅**包含最核心的 `UserID`。其他的非核心信息（如组织信息、详细的用户资料）都改为**按需加载**（On-Demand）或通过特定中间件（如 `LoadOrg`）加载。

### 6.3 组织信息解耦
组织信息的获取逻辑已从核心 `AuthMiddleware` 中剥离，移至 `LoadOrg` 中间件。这意味着不涉及组织业务的接口（如个人资料、系统设置）不再承担加载组织信息的额外开销。