mirror of https://github.com/veypi/OneAuth.git
docs: Add CLAUDE.md for Claude Code guidance
- Add project overview with tech stack (Go 1.24+, Vigo framework, GORM)
- Document common commands (make run, db operations, tests)
- Describe onion model request flow and middleware stages
- Explain RBAC permission system format and usage
- Document multi-tenancy patterns (B2C/B2B/Platform)
- Add API response format and error code conventions
- Include Vigo handler pattern with parameter binding
- Document vhtml frontend structure
master
veypi
7 days ago
parent
b0322047cd
commit
63792b449f
@ -0,0 +1,164 @@
|
||||
# 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, organization (multi-tenant), RBAC permissions, and OAuth2 authentication services.
|
||||
|
||||
- **Language**: Go 1.24+
|
||||
- **Framework**: Vigo (onion-model middleware)
|
||||
- **ORM**: GORM (MySQL, PostgreSQL, SQLite supported)
|
||||
- **Authentication**: JWT + OAuth2
|
||||
- **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/...
|
||||
```
|
||||
|
||||
Tests in `tests/` use an in-memory SQLite database with mock Redis. The `ensureUsers(t)` helper sets up test users (admin, user1, user2) with tokens stored in globals (`AdminToken`, `User1Token`, etc.).
|
||||
|
||||
## Architecture
|
||||
|
||||
### Onion Model Request Flow
|
||||
|
||||
```
|
||||
Request -> [Global Before Middlewares] -> [Router] -> [Handler] -> [Service] -> [Model] -> Database
|
||||
|
|
||||
Response <- [Global After Middleware] <--------+
|
||||
```
|
||||
|
||||
Key middleware stages:
|
||||
|
||||
- **Before**: Authentication, preprocessing, context injection (parent hooks run before child hooks)
|
||||
- **Handler**: Business logic, returns data (does not write response directly)
|
||||
- **After**: Response formatting (parent hooks run after child hooks)
|
||||
|
||||
### Directory Structure
|
||||
|
||||
```
|
||||
├── api/ # REST API handlers and routing
|
||||
│ ├── auth/ # Login, register, refresh token, SMS
|
||||
│ ├── oauth/ # OAuth2 provider endpoints
|
||||
│ ├── org/ # Organization/tenant management
|
||||
│ ├── role/ # Role management
|
||||
│ ├── user/ # User management
|
||||
│ └── init.go # Router aggregation
|
||||
├── auth/ # Core RBAC permission system
|
||||
│ ├── auth.go # Permission checking implementation
|
||||
│ └── middleware.go # Auth middleware
|
||||
├── cfg/ # Configuration (DB, Redis, JWT settings)
|
||||
├── models/ # GORM data models
|
||||
│ ├── auth.go # Role, Policy, UserRole models
|
||||
│ ├── user.go # User, Identity, Session models
|
||||
│ ├── org.go # Org, OrgMember 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 (RBAC)
|
||||
|
||||
Permission format: `resource:action` or `app:resource:action`
|
||||
|
||||
Examples: `user:read`, `org:create`, `oauth-client:delete`
|
||||
|
||||
**Important**: Resource identifiers must NOT contain colons (use kebab-case or snake_case).
|
||||
|
||||
Permission middleware usage:
|
||||
|
||||
```go
|
||||
// Basic permission
|
||||
Router.Post("/articles", AppAuth.Perm("article:create"), createArticle)
|
||||
|
||||
// Owner check - allows if user is resource owner
|
||||
Router.Patch("/articles/{id}", AppAuth.PermWithOwner("article:update", "id"), updateArticle)
|
||||
|
||||
// Wildcard support
|
||||
AppAuth.AddRole("admin", "Admin", "*:*") // All permissions
|
||||
```
|
||||
|
||||
### Multi-Tenancy (Org)
|
||||
|
||||
Organizations provide data isolation. Three usage patterns:
|
||||
|
||||
1. **B2C (Single Tenant)**: Ignore Org, bind roles to global (`org_id=""`)
|
||||
2. **B2B SaaS (Multi-Tenant)**: Require `X-Org-ID` header on all business APIs
|
||||
3. **Platform (Hybrid)**: Merchant side uses Org, consumer side is global
|
||||
|
||||
The `AuthMiddleware` extracts `X-Org-ID` header and loads user's roles for that org context.
|
||||
|
||||
### API Response Format
|
||||
|
||||
All responses are JSON formatted by `common.JsonResponse` middleware:
|
||||
|
||||
**Success:**
|
||||
|
||||
```json
|
||||
{"code": 200, "data": { ... }}
|
||||
```
|
||||
|
||||
**Error:**
|
||||
|
||||
```json
|
||||
{ "code": 40001, "message": "Error description" }
|
||||
```
|
||||
|
||||
Error codes combine HTTP status (3 digits) + scenario (2 digits), e.g., `40001` = Bad Request + invalid argument.
|
||||
|
||||
### Configuration
|
||||
|
||||
Configuration is loaded from:
|
||||
|
||||
1. Config file (`-f ./cfg/dev.yml`)
|
||||
2. Environment variables (uppercase with underscores, e.g., `DB_DSN`, `JWT_SECRET`)
|
||||
|
||||
Key config in `cfg/cfg.go`:
|
||||
|
||||
- `DB`: Database connection (type: mysql/postgres/sqlite)
|
||||
- `Redis`: Use `memory` for development
|
||||
- `Key`: System encryption key (32+ chars recommended)
|
||||
- `JWT`: Token expiry settings
|
||||
- `InitAdmin`: Auto-create admin on first run (empty password = first registered user becomes admin)
|
||||
|
||||
### Handler Pattern (Vigo Framework)
|
||||
|
||||
Handlers use generics with automatic parameter binding:
|
||||
|
||||
```go
|
||||
type CreateReq struct {
|
||||
Name string `json:"name" src:"json"` // Required
|
||||
Email *string `json:"email" src:"json"` // Optional (pointer)
|
||||
Page int `src:"query" default:"1"` // Query param with default
|
||||
}
|
||||
|
||||
func CreateUser(x *vigo.X, req *CreateReq) (*User, error) {
|
||||
// Business logic
|
||||
return user, nil // Framework handles JSON response
|
||||
}
|
||||
```
|
||||
|
||||
Parameter sources: `path`, `query`, `header`, `json`, `form`. Non-pointer fields are required by default.
|
||||
|
||||
### Frontend (vhtml)
|
||||
|
||||
The admin UI is in `ui/` using the vhtml framework:
|
||||
|
||||
- Pages in `ui/page/` (e.g., `user_list.html` → route `/user_list`)
|
||||
- Components as HTML files, referenced with hyphens (e.g., `<form-user_create>` for `/ui/form/user_create.html`)
|
||||
- Routes defined in `ui/routes.js`
|
||||
- Access UI at `/vb/` path when server is running
|
||||
|
||||
Full API documentation is available at `/_api.json` when the server is running.
|
||||
Loading…
Reference in New Issue