OneAuth/doc/integration.md

# VBase 集成指南

## 1. 引入路由

```go
import "github.com/veypi/vbase/api"

func main() {
    // 挂载 vbase 路由到 /api/v1/vb
    rootRouter.Extend("/api/v1/vb", api.Router)
}
```

## 2. 集成配置

配置自动从 vigo 的 config.toml 读取：

```toml
[vbase]
jwt_secret = "your-secret-key"
jwt_expire = 7200          # token 过期时间(秒)
refresh_expire = 604800    # refresh token 过期时间(秒)
bcrypt_cost = 10           # 密码加密强度

[vbase.redis]
addr = "localhost:6379"    # 留空或填 memory 使用内存缓存
password = ""
db = 0
```

或在代码中自定义：

```go
import "github.com/veypi/vbase/cfg"

cfg.Config.JWTSecret = "your-secret"
cfg.Config.JWTExpire = 7200
```

## 3. 配置策略

创建组织时自动初始化默认策略：

```go
import "github.com/veypi/vbase/api/middleware"

// 创建组织后调用
middleware.InitOrgPolicies(orgID)
```

默认创建的策略：
| 策略 | 资源 | 操作 | 条件 | 说明 |
|------|------|------|------|------|
| policy:manage | policy | * | admin | 管理策略 |
| role:manage | role | * | admin | 管理角色 |
| user:update | user | update | owner | 只能改自己 |

自定义策略：

```go
import "github.com/veypi/vbase/models"

policy := &models.Policy{
    Code:     "project:delete",
    Name:     "删除项目",
    Resource: "project",
    Action:   "delete",
    Effect:   models.PolicyEffectAllow,
    Condition: "owner",  // 只有所有者能删
    Scope:    models.PolicyScopeOrg,
}
cfg.DB().Create(policy)
```

## 4. 使用鉴权

### 4.1 全局中间件（已内置）

```go
// api/init.go 已自动配置：
Router.Use(middleware.AuthRequired())   // JWT 认证
Router.Use(middleware.OrgContext())     // 组织上下文
```

### 4.2 公开接口（跳过认证）

```go
Router.Get("/public", vigo.SkipBefore, "公开接口", handler)
```

### 4.3 接口级权限控制

```go
import "github.com/veypi/vbase/api/middleware"

// 需要管理员权限
Router.Post("/users", middleware.RequireAdmin(), "创建用户", createUser)

// 基于 Policy 的细粒度控制
Router.Post("/projects", middleware.Permission("project", "create"), "创建项目", createProject)

// 带所有者检查（用户只能改自己的数据）
Router.Patch("/users/{id}", middleware.PermissionWithOwner("user", "update", "owner_id"), "更新用户", updateUser)

// 管理员或所有者
Router.Delete("/projects/{id}", middleware.AdminOrOwner("owner_id"), "删除项目", deleteProject)
```

### 4.4 代码中手动检查

```go
func myHandler(x *vigo.X, req *Req) error {
    checker := middleware.NewChecker(x)

    // 检查是否为管理员
    if !checker.IsOrgAdmin() {
        return vigo.ErrForbidden
    }

    // 检查具体权限
    if err := checker.RequirePermission("resource", "write"); err != nil {
        return err
    }

    return nil
}
```

## 5. 完整示例

```go
package main

import (
    "github.com/veypi/vbase/api"
    "github.com/veypi/vbase/api/middleware"
    "github.com/veypi/vigo"
)

func main() {
    r := vigo.NewRouter()

    // 1. 挂载 vbase
    r.Extend("/api/vb", api.Router)

    // 2. 业务路由加权限
    project := r.SubRouter("/projects")
    project.Use(middleware.AuthRequired())

    project.Get("/", middleware.Permission("project", "list"), "项目列表", listProjects)
    project.Post("/", middleware.Permission("project", "create"), "创建项目", createProject)
    project.Patch("/{id}", middleware.PermissionWithOwner("project", "update", "owner_id"), "更新项目", updateProject)
    project.Delete("/{id}", middleware.AdminOrOwner("owner_id"), "删除项目", deleteProject)

    vigo.Run(r)
}
```