mirror of https://github.com/veypi/OneAuth.git
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
99 lines
3.2 KiB
Markdown
99 lines
3.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
VBase is a Go-based identity authentication and permission management framework built on the [Vigo](https://github.com/veypi/vigo) web framework (onion-model middleware architecture). It provides user management, scoped RBAC permissions, and OAuth2 authentication services.
|
|
|
|
- **Language**: Go 1.24+
|
|
- **Framework**: Vigo (onion-model middleware)
|
|
- **ORM**: GORM (MySQL, PostgreSQL, SQLite supported)
|
|
- **Authentication**: JWT + OAuth2
|
|
- **Permissions**: Scoped RBAC (Role-Based Access Control)
|
|
- **Frontend**: vhtml (embedded HTML-based UI at `/vb/`)
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Run development server (default port 4001)
|
|
make run
|
|
|
|
# Database operations
|
|
go run ./cli/main.go db migrate
|
|
go run ./cli/main.go db drop
|
|
|
|
# Run integration tests
|
|
go test -v ./tests/...
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Onion Model Request Flow
|
|
|
|
```
|
|
Request -> [Global Before Middlewares] -> [Router] -> [Handler] -> [Service] -> [Model] -> Database
|
|
|
|
|
Response <- [Global After Middleware] <--------+
|
|
```
|
|
|
|
### Directory Structure
|
|
|
|
```
|
|
├── api/ # REST API handlers and routing
|
|
│ ├── auth/ # Login, register, refresh token
|
|
│ ├── oauth/ # OAuth2 provider endpoints
|
|
│ ├── role/ # Role management
|
|
│ ├── user/ # User management
|
|
│ └── init.go # Router aggregation
|
|
├── auth/ # Core Scoped RBAC permission system
|
|
│ ├── auth.go # Permission checking implementation
|
|
│ └── design.md # Permission system design doc
|
|
├── cfg/ # Configuration (DB, Redis, JWT settings)
|
|
├── models/ # GORM data models
|
|
│ ├── auth.go # Role, Permission, UserRole models
|
|
│ ├── user.go # User, Identity, Session models
|
|
│ └── init.go # Model registration and migrations
|
|
├── libs/ # Utilities (cache, crypto, jwt, sms, email)
|
|
├── ui/ # Frontend admin interface (vhtml framework)
|
|
├── cli/ # Application entry point
|
|
└── tests/ # Go integration tests
|
|
```
|
|
|
|
### Permission System (Scoped RBAC)
|
|
|
|
The system uses a scoped permission model where permissions are isolated by `Scope` (e.g., "vb" for VBase, "app1" for external apps).
|
|
|
|
**Permission Format**: `resource:instance:sub-resource:sub-instance` (Tree structure)
|
|
|
|
**Levels**:
|
|
- Level 1: Create (Odd layers)
|
|
- Level 2: Read (Even layers)
|
|
- Level 4: Write (Even layers)
|
|
- Level 7: Admin (Even layers, inherited downwards)
|
|
|
|
**Key Interfaces**:
|
|
- `auth.Factory.New(scope)`: Get scoped auth instance.
|
|
- `auth.PermRead(code)`, `auth.PermWrite(code)`: Middleware checks.
|
|
- `auth.Grant(ctx, userID, permID, level)`: Grant permission.
|
|
|
|
### API Response Format
|
|
|
|
All responses are JSON formatted by `common.JsonResponse` middleware:
|
|
|
|
**Success:**
|
|
```json
|
|
{"code": 200, "data": { ... }}
|
|
```
|
|
|
|
**Error:**
|
|
```json
|
|
{ "code": 40001, "message": "Error description" }
|
|
```
|
|
|
|
### Frontend (vhtml)
|
|
|
|
The admin UI is in `ui/` using the vhtml framework:
|
|
- Access UI at `/vb/` path when server is running
|
|
- Routes defined in `ui/routes.js`
|