# VBase 集成指南

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

## 1. 安装

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

## 2. 初始化

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

```go
package main

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

// 1. 创建你的应用 Router
var Router = vigo.NewRouter()

// 2. 创建你的应用 Auth 实例 (指定 Scope)
var AppAuth = auth.Factory.New("my_app")

func init() {
    // 3. 挂载 VBase 路由 (提供登录、用户管理等基础接口)
    Router.Extend("/vb", vbase.Router)

    // 4. 配置数据库连接 (如果尚未配置)
    // export DSN="root:password@tcp(127.0.0.1:3306)/myapp?charset=utf8&parseTime=True"
}

func main() {
    // 5. 初始化数据库迁移
    if err := vbase.Init(); err != nil {
        panic(err)
    }

    // 6. 启动服务
    app := vigo.New("myapp", Router, cfg.Global, nil)
    panic(app.Run())
}
```

## 3. 使用权限系统

### 3.1 定义路由权限

使用 `AppAuth` 实例的中间件方法来保护你的路由。

```go
func init() {
    // 需要登录
    Router.Use(AppAuth.Login())

    // 资源操作示例
    // 假设你的资源是 "article"
    
    // 创建文章 (需要 "article" 的创建权限 Level 1)
    Router.Post("/articles", AppAuth.PermCreate("article"), CreateArticle)

    // 读取文章 (需要 "article:{id}" 的读取权限 Level 2)
    Router.Get("/articles/{id}", AppAuth.PermRead("article:{id}"), GetArticle)

    // 更新文章 (需要 "article:{id}" 的写入权限 Level 4)
    Router.Put("/articles/{id}", AppAuth.PermWrite("article:{id}"), UpdateArticle)

    // 删除文章 (需要 "article:{id}" 的管理员权限 Level 7)
    Router.Delete("/articles/{id}", AppAuth.PermAdmin("article:{id}"), DeleteArticle)
}
```

### 3.2 业务逻辑授权

在创建资源时，通常需要授予创建者管理权限。

```go
func CreateArticle(x *vigo.X, req *ArticleReq) (*Article, error) {
    // 1. 获取当前用户
    userID := AppAuth.UserID(x)
    
    // 2. 创建资源逻辑...
    article := &Article{Title: req.Title, AuthorID: userID}
    db.Create(article)

    // 3. 授予权限
    // 授予用户对该文章的管理员权限 (Level 7)
    // 这样用户后续可以读取、修改、删除该文章
    permissionID := fmt.Sprintf("article:%s", article.ID)
    if err := AppAuth.Grant(x.Context(), userID, permissionID, auth.LevelAdmin); err != nil {
        // 处理错误 (通常记录日志)
        x.Log.Error("Failed to grant permission", "err", err)
    }

    return article, nil
}
```

### 3.3 复杂场景：项目成员管理

假设你有一个项目管理系统，用户可以被邀请加入项目。

```go
// 邀请成员接口
func InviteMember(x *vigo.X, req *InviteReq) error {
    // 检查当前用户是否有权限邀请 (通常需要管理员权限)
    // 这一步由路由中间件 PermAdmin("project:{id}") 保证
    
    // 授予被邀请人读取权限 (Level 2)
    permID := fmt.Sprintf("project:%s", req.ProjectID)
    return AppAuth.Grant(x.Context(), req.TargetUserID, permID, auth.LevelRead)
}
```

## 4. 配置说明

VBase 使用 `cfg` 包管理配置，支持环境变量。

- `DB_DSN`: 数据库连接字符串
- `DB_TYPE`: 数据库类型 (mysql, postgres, sqlite)
- `JWT_SECRET`: JWT 签名密钥 (生产环境务必修改)
- `JWT_ISSUER`: Token 签发者

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