OneAuth/docs/design.md

VBase 后端架构设计文档

1. 概览

VBase 是一个基于 Golang 的高性能后端基础框架，旨在提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。项目采用分层架构设计，基于 vigo 框架构建，支持 Session-based 认证、Cookie 令牌传送以及短信/邮箱验证码注册，强调代码的可维护性、扩展性和安全性。

2. 技术栈

• 语言: Golang 1.24+
• Web 框架: vigo (基于洋葱模型的高性能框架)
• ORM: GORM (支持 MySQL, PostgreSQL, SQLite)
• 配置管理: cfg 包 (YAML 配置文件 + 环境变量)
• 认证: Session + JWT (Access/Refresh Token)、Cookie 令牌传送
• 多因素认证: 短信/邮箱验证码注册
• 数据库: 默认为 SQLite，可按需切换 MySQL/PostgreSQL

3. 系统架构

项目遵循经典的洋葱模型和分层架构：

Request -> [Global Middlewares] -> [Router] -> [Group Middlewares] -> [Handler] -> [Service/Logic] -> [Model/DAO] -> Database
                                                                           |
Response <- [Global After Middleware] <------------------------------------+

3.1 目录结构

/
├── api/                # API 接口层 (路由定义、请求处理)
│   ├── auth/           # 认证相关接口 (登录、注册、刷新Token)
│   ├── oauth/          # OAuth2 Provider 接口
│   ├── role/           # 角色管理接口
│   ├── user/           # 用户管理接口
│   ├── settings/       # 系统设置接口
│   ├── verification/   # 短信/邮箱验证码接口
│   └── init.go         # 路由聚合与全局中间件配置
├── auth/               # 核心权限控制模块 (Scoped RBAC + Session 管理)
├── cfg/                # 配置与基础设施 (DB, Redis, JWT)
├── models/             # 数据模型定义 (GORM 结构体)
├── libs/               # 通用工具库 (jwt, cache, crypto, sms, email)
├── cli/                # 命令行入口
├── ui/                 # 嵌入式管理界面 (vhtml)
└── docs/               # 文档

4. 核心模块设计

4.1 认证与授权 (Auth Module)

Auth 模块是系统的核心安全组件，实现了基于作用域（Scope）的角色访问控制 (RBAC) 和资源级权限管理。

4.1.1 核心概念

• Scope (作用域): 权限隔离的边界，不同应用或模块可以拥有独立的权限体系（如 "vb", "app1"）。
• Permission (权限): 最小粒度的操作许可，格式为树状结构字符串。
  • 层级定义:
    • 奇数层: 资源类型 (Level 1: Create)
    • 偶数层: 资源实例 (Level 2: Read, Level 4: Write, Level 7: Admin)
  • 示例: org:orgA:project:projB
• Role (角色): 权限的集合。角色也属于特定 Scope。
• UserRole (用户-角色关联): 用户在特定 Scope 下拥有的角色。

4.1.2 权限验证机制

系统提供 auth.Auth 接口和 auth.Factory 工厂，支持多应用集成：

1. 获取实例: myAuth := auth.Factory.New("my_scope")
2. 基础权限: myAuth.RequireRead("resource:id") - 检查读取权限。
3. 层级检查:
   • Admin (Level 7): 拥有 * 或前缀匹配权限（向下继承）。
   • Standard: 精确匹配且满足 Level 要求。
4. 动态解析: 支持从 URL、Query、Header 解析 ID，如 org:{orgID}。

4.1.3 中间件流程

1. Login 中间件: 从 Cookie / Authorization Header / Query 提取 Token，解析 JWT 获取 UserID 和 SessionID，验证 Session 有效性（Redis 缓存 + DB 回退）。
2. Perm 中间件: 在业务 Handler 执行前拦截请求，调用 Check 进行鉴权，支持动态权限码解析（从 Path/Query/Header 获取参数）。

4.2 用户体系 (User Module)

• User: 核心用户实体，包含基本信息（用户名、密码、邮箱、手机号等），支持邮箱/手机验证状态追踪。
• Identity: 认证信息表，支持多种登录方式（密码、OAuth 第三方登录）关联到同一用户。
• Session: 登录会话管理，每次登录创建一个 Session，记录设备信息和 IP，支持版本号轮换（防止并发刷新互踢）和单独吊销。

4.3 OAuth2 服务 (OAuth Module)

实现了完整的 OAuth2 Provider 功能，支持第三方应用接入：

• Client: 第三方应用注册信息 (ClientID, ClientSecret)。
• AuthorizationCode: 授权码模式支持。
• Token: Access Token 和 Refresh Token 管理。
• Flows: 支持 Authorization Code, Client Credentials, Refresh Token 等标准流程。

5. 接口规范

5.1 API 文档

路由启用了 EnableApiDoc()，可通过 /_api.json 查看所有注册接口的完整文档（包括参数、响应、中间件信息）。

5.2 请求处理

• 参数解析: 利用 vigo 的泛型 Handler 机制，自动解析 Query, Path, Header, JSON Body 参数到结构体。
• 验证: 结构体 Tag (src, json, default) 定义参数源和默认值。

5.3 响应格式

统一使用 JSON 格式响应，由全局后置中间件 common.JsonResponse 处理：

成功响应:

{
  "code": 200,
  "data": { ... } // 或 null
}

错误响应:

{
  "code": 40001, // 400 + 01 (Bad Request + Invalid Argument)
  "message": "错误描述信息"
}

6. 数据库设计

所有模型以 vigo.Model 作为基类，统一包含以下字段：

• ID: UUID (varchar(36))
• CreatedAt: 创建时间
• UpdatedAt: 更新时间
• DeletedAt: 软删除标记（GORM）

6.1 核心表

表	说明
users	用户表（用户名、密码、邮箱、手机、验证状态）
identities	第三方身份绑定表
sessions	登录会话表（设备信息、IP、版本号轮换）
roles	角色表（系统/自定义）
permissions	权限表（作用域隔离、支持按用户/角色授权）
user_roles	用户-角色关联表

所有模型在 models/init.go 中注册，启动时通过 Init() 自动迁移 (AutoMigrate)。

7. 部署与运维

• 配置: 支持 YAML 配置文件和环境变量覆盖，默认 SQLite 无需额外配置即可运行。
• 运行: go run ./cli/*.go -p 4000 或 make run
• 数据库迁移: go run ./cli/main.go db migrate

8. 开发规范

1. 资源命名: 权限资源标识符必须使用 kebab-case 或 snake_case，使用冒号 : 分隔层级。
2. 错误处理: 优先使用 vigo.NewError 或预定义错误 (如 vigo.ErrNotFound)，以便统一处理 HTTP 状态码。
3. 测试: 编写集成测试脚本覆盖核心业务流程。