OneAuth/docs/integration.md

VBase 集成文档

本文档介绍如何将 VBase 集成到您的 Golang (Vigo) 项目中，快速实现用户管理、权限控制和组织架构功能。

1. 快速集成 (Quick Start)

集成 VBase 仅需简单几步：

1.1 引入依赖

在您的项目中引入 VBase：

import "github.com/veypi/vbase"

1.2 挂载路由

在您的项目根路由初始化处，挂载 VBase 路由：

// 您的项目初始化代码
func init() {
    // 挂载 vbase 路由到 /vbase 路径下
    // 这样 vbase 的 API 将可以通过 /vb/api/auth/login 等访问
    MyRouter.Extend("/vb", vbase.Router)
}

1.3 配置数据库

确保您的项目已经配置了 GORM 数据库连接，VBase 将复用该连接。

// VBase 会自动读取您的配置，前提是您使用了兼容的配置结构或手动设置
vbase.Config.SetDB(yourDB) 
// 或者直接集成到您的项目配置中，由vigo.Flags 自动加载
type AppConfig struct {
    Vbase any
}
var Config = *AppConfig{
    Vbase: vbase.Config,
}

---

2. 详细集成方案

2.1 路由集成

VBase 提供了一个标准的 vigo.Router 实例，包含所有用户、组织、权限相关的 API。

package main

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

var Router = vigo.NewRouter()

func init() {
    // 1. 挂载 VBase 路由
    // 建议挂载在独立的前缀下，避免路由冲突
    Router.Extend("/vb", vbase.Router)
}

2.2 权限系统集成

VBase 提供了强大的 RBAC (基于角色的访问控制) 权限系统。

2.2.1 初始化应用权限

在您的应用中，使用 vbase.Auth.New 创建应用专属的权限实例。

import (
    "github.com/veypi/vbase"
    "github.com/veypi/vbase/models"
)

// 定义您的应用权限实例
var AppAuth = vbase.Auth.New("my_app", models.AppConfig{
    Name:        "My Application",
    Description: "我的应用描述",
    // 定义应用的默认角色
    DefaultRoles: []models.RoleDefinition{
        {
            Code: "admin",
            Name: "管理员",
            Policies: []string{"*:*"}, // 拥有所有权限
        },
        {
            Code: "editor",
            Name: "编辑",
            Policies: []string{"article:create", "article:update"},
        },
    },
})

2.2.2 使用权限中间件

使用 vbase.AuthMiddleware 进行认证，并结合 AppAuth.Perm 进行权限检查。

func init() {
    // 1. 全局认证中间件 (解析 Token, 注入 user_id, org_id)
    Router.Use(vbase.AuthMiddleware())
    Router.Get("/info", "获取app信息", vigo.SkipBefore, getInfo)
    // 2. 路由权限控制
    // 检查 "article:create" 权限
    Router.Post("/articles", "发布文章", AppAuth.Perm("article:create"), createArticle)
    
    // 检查资源所有权 (确保用户只能修改自己的文章)
    // 检查 "article:update" 权限，且文章的 owner_id 必须等于当前用户 ID
    Router.Patch("/articles/{id}", "更新文章", AppAuth.PermWithOwner("article:update", "id"), updateArticle)
}

2.3 配置管理

VBase 允许自定义部分配置。

import "github.com/veypi/vbase"

func main() {
    // 获取配置单例
    cfg := vbase.Config
    
    // 启用调试模式
    cfg.Debug = true
    
    // 设置 JWT 密钥 (建议从环境变量读取)
    cfg.JwtSecret = "your-secret-key"
    
    // 自定义短信服务提供商 (可选)
    // vbase.Config.SetSmsProvider(...)
}

2.4 上下文使用

通过 vbase.AuthMiddleware 认证后，您可以在 Handler 中通过 *vigo.X 获取用户信息。

func MyHandler(x *vigo.X) error {
    // 获取当前用户 ID
    userID := x.Get("user_id").(string)
    
    // 获取当前组织 ID (如果有)
    orgID := x.Get("org_id").(string)
    
    // ... 业务逻辑
}