# VBase 后端架构设计文档

## 1. 概览

VBase 是一个基于 Golang 的高性能后端基础框架，旨在提供一套标准化的用户管理、作用域权限控制（Scoped RBAC）和 OAuth2 认证服务。项目采用分层架构设计，基于 `vigo` 框架构建，强调代码的可维护性、扩展性和安全性。

## 2. 技术栈

- **语言**: Golang 1.22+
- **Web 框架**: [vigo](https://github.com/veypi/vigo) (基于洋葱模型的高性能框架)
- **ORM**: GORM (支持 MySQL, PostgreSQL, SQLite 等)
- **配置管理**: `cfg` 包 (支持环境变量、配置文件)
- **认证**: JWT (JSON Web Token) + OAuth2
- **数据库**: 关系型数据库 (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/           # 用户管理接口
│   └── init.go         # 路由聚合与全局中间件配置
├── auth/               # 核心权限控制模块 (Scoped RBAC 实现)
├── cfg/                # 配置与基础设施 (DB, Redis, Log)
├── models/             # 数据模型定义 (GORM 结构体)
├── libs/               # 通用工具库
├── cli/                # 命令行入口
└── 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.PermRead("resource:id")` - 检查读取权限。
3.  **层级检查**:
    - **Admin (Level 7)**: 拥有 `*` 或前缀匹配权限（向下继承）。
    - **Standard**: 精确匹配且满足 Level 要求。
4.  **动态解析**: 支持从 URL、Query、Header 解析 ID，如 `org:{orgID}`。

#### 4.1.3 中间件流程

1.  **LoginMiddleware**: 解析 JWT Token，提取 UserID。
2.  **PermMiddleware**: 在业务 Handler 执行前拦截请求，调用 `Check` 进行鉴权。

### 4.2 用户体系 (User Module)

- **User**: 核心用户实体，包含基本信息 (昵称、头像、邮箱等)。
- **Identity**: 认证信息表，支持多种登录方式 (密码、OAuth、验证码等) 关联到同一用户。
- **Session**: 用户会话管理，用于记录登录状态和刷新 Token。

### 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 请求处理

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

### 5.2 响应格式

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

**成功响应**:
```json
{
  "code": 200,
  "data": { ... } // 或 null
}
```

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

## 6. 数据库设计

推荐使用 `vigo.Model` 作为基类，统一包含以下字段：
- `ID`: UUID (varchar(36))
- `CreatedAt`: 创建时间
- `UpdatedAt`: 更新时间
- `DeletedAt`: 软删除标记

所有模型在 `models/init.go` 中注册，支持服务启动时自动迁移 (`AutoMigrate`)。

## 7. 部署与运维

- **配置**: 支持 `.env` 文件和环境变量覆盖。
- **构建**: `go build -o vbase cli/main.go`
- **运行**: `./vbase -p 8080`

## 8. 开发规范

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