OneAuth/docs/integration.md

# VBase 集成指南

本文档介绍如何将 VBase 作为基础库集成到现有的 Golang 项目中，并使用其权限管理系统。

## 1. 安装

```bash
go get github.com/veypi/vbase
```

## 2. 初始化

在你的应用入口文件（如 `main.go`）中进行初始化。

```go
package main

import (
	"github.com/veypi/vbase"
	"github.com/veypi/vbase/cfg"
	"github.com/veypi/vigo"
)

func main() {
	// cfg.Global 已包含默认配置（SQLite 内存数据库）
	// 可通过环境变量或 YAML 文件覆盖
	app := vigo.New("myapp", vbase.Router, cfg.Global, vigo.WithInit(vbase.Init))
	panic(app.Run())
}
```

VBase 自带嵌入式管理界面，启动后访问 `/vb/` 即可使用。

### 2.1 挂载路由

VBase Router 已内置所有 API 路由（`/api/auth`、`/api/users`、`/api/roles`、`/api/oauth`、`/api/settings` 等）和 UI 路由（`/vb/`、`/v/`、`/vhtml/`）。

如果你的应用需要自定义路由，将 VBase Router 挂载到你的 Router 上：

```go
var Router = vigo.NewRouter()

func init() {
	// 将 VBase 挂载到 /vb 前缀
	Router.Extend("/vb", vbase.Router)
}
```

## 3. 使用权限系统

VBase 通过 `cfg.Auth` 提供全局权限管理实例。所有中间件方法前缀为 `Require*`。

### 3.1 定义路由权限

```go
func init() {
	// 所有路由需要登录
	Router.Use(cfg.Auth.Login())

	// 资源操作示例
	// 创建文章 (需要 "article" 的创建权限 Level 1)
	Router.Post("/articles", cfg.Auth.RequireCreate("article"), CreateArticle)

	// 读取文章 (需要对特定实例的读取权限 Level 2)
	Router.Get("/articles/{id}", cfg.Auth.RequireRead("article:{id}"), GetArticle)

	// 更新文章 (需要对特定实例的写入权限 Level 4)
	Router.Put("/articles/{id}", cfg.Auth.RequireWrite("article:{id}"), UpdateArticle)

	// 删除文章 (需要对特定实例的管理员权限 Level 7)
	Router.Delete("/articles/{id}", cfg.Auth.RequireAdmin("article:{id}"), DeleteArticle)
}
```

### 3.2 权限码动态解析

权限码支持动态占位符，从不同来源获取值：

| 语法 | 来源 | 示例 |
|------|------|------|
| `{key}` 或 `{key@ctx}` | Context | `{appID}` |
| `{key@path}` | 路径参数 | `{appID@path}` |
| `{key@query}` | Query 参数 | `{appID@query}` |
| `{key@header}` | Header | `{Authorization@header}` |

### 3.3 业务逻辑授权

在创建资源时，授予创建者管理权限：

```go
func CreateArticle(x *vigo.X, req *ArticleReq) (*Article, error) {
	userID := cfg.Auth.UserID(x)

	article := &Article{Title: req.Title, AuthorID: userID}
	cfg.DB().Create(article)

	// 授予用户对该文章的管理员权限 (Level 7)
	permID := "article:" + article.ID
	cfg.Auth.Grant(x.Context(), userID, permID, auth.LevelAdmin)

	return article, nil
}
```

### 3.4 多 Scope 权限隔离

不同业务模块通过 Scope 实现权限隔离：

```go
// 为不同应用创建独立的 Provider
var AppA_Auth = auth.Factory.New("app_a")
var AppB_Auth = auth.Factory.New("app_b")

// AppA 的用户权限不会影响 AppB
```

## 4. Session 管理

VBase 使用 Session + JWT 双 Token 机制：

- **Access Token**：短期有效（默认 15 分钟），用于 API 认证
- **Refresh Token**：长期有效（默认 30 天），用于刷新 Access Token
- **Session**：记录登录设备信息和 IP，支持版本号轮换防止并发刷新互踢

Token 默认通过 HttpOnly Cookie 传送。Session 可通过 `auth.RevokeSession`、`auth.RevokeOtherSessions`、`auth.RevokeAllSessions` 管理。

## 5. 配置说明

VBase 默认使用 SQLite 内存数据库（`/tmp/vbase.db`），无需任何外部依赖即可运行。

配置文件示例（`config.yaml`）：

```yaml
db:
  type: "sqlite"
  dsn: "/tmp/vbase.db"

redis:
  addr: "memory"

key: "your-secret-key-min-32-characters"

jwt:
  access_expiry: 900
  refresh_expiry: 2592000
  issuer: "vbase"
  cookie_prefix: "vb_"
```

更多配置详情请参考 [配置文档](./configuration.md)。