revamping documentation
This commit is contained in:
316
docs/api/rbac-visual-guide.md
Normal file
316
docs/api/rbac-visual-guide.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# RBAC Architecture Visual Guide
|
||||
|
||||
## System Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PLATFORM LEVEL │
|
||||
│ │
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ Admin Users │ │ Vendor Users │ │
|
||||
│ │ role="admin" │ │ role="vendor" │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Full platform │ │ • Can own/join │ │
|
||||
│ │ access │ │ vendors │ │
|
||||
│ │ • Cannot access │ │ • Cannot access │ │
|
||||
│ │ vendor portal │ │ admin portal │ │
|
||||
│ └──────────────────┘ └──────────────────┘ │
|
||||
│ │ │
|
||||
└──────────────────────────────────────────────┼──────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ VENDOR LEVEL │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ Vendor: ACME │ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────────────┐ │ │
|
||||
│ │ │ Owner │ │ Team Members │ │ │
|
||||
│ │ │ user_type= │ │ user_type= │ │ │
|
||||
│ │ │ "owner" │ │ "member" │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ • All perms │ │ • Role-based perms │ │ │
|
||||
│ │ │ • Can invite │ │ • Manager/Staff/etc │ │ │
|
||||
│ │ │ • Can remove │ │ • Can be invited │ │ │
|
||||
│ │ │ • Cannot be │ │ • Can be removed │ │ │
|
||||
│ │ │ removed │ │ │ │ │
|
||||
│ │ └──────────────┘ └──────────────────────┘ │ │
|
||||
│ │ │ │ │
|
||||
│ │ ▼ │ │
|
||||
│ │ ┌──────────────────────────────┐ │ │
|
||||
│ │ │ Roles │ │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ • Manager (many perms) │ │ │
|
||||
│ │ │ • Staff (moderate perms) │ │ │
|
||||
│ │ │ • Support (limited perms) │ │ │
|
||||
│ │ │ • Viewer (read-only) │ │ │
|
||||
│ │ │ • Custom (owner-defined) │ │ │
|
||||
│ │ └──────────────────────────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ CUSTOMER LEVEL │
|
||||
│ (Separate from Users) │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||
│ │ Customers (per vendor) │ │
|
||||
│ │ │ │
|
||||
│ │ • Vendor-scoped authentication │ │
|
||||
│ │ • Can self-register │ │
|
||||
│ │ • Access own account + shop catalog │ │
|
||||
│ │ • Cannot access admin/vendor portals │ │
|
||||
│ └──────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Team Invitation Flow
|
||||
|
||||
```
|
||||
┌──────────┐
|
||||
│ Owner │
|
||||
│ (ACME) │
|
||||
└────┬─────┘
|
||||
│
|
||||
│ 1. Click "Invite Team Member"
|
||||
│ Email: jane@example.com
|
||||
│ Role: Manager
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ System Creates: │
|
||||
│ • User account │
|
||||
│ • VendorUser │
|
||||
│ • Invitation token │
|
||||
└────┬────────────────┘
|
||||
│
|
||||
│ 2. Email sent to jane@example.com
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Jane clicks link │
|
||||
│ /invitation/accept? │
|
||||
│ token=abc123... │
|
||||
└────┬─────────────────┘
|
||||
│
|
||||
│ 3. Jane sets password
|
||||
│ Enters name
|
||||
│
|
||||
▼
|
||||
┌─────────────────────┐
|
||||
│ Account Activated: │
|
||||
│ • User.is_active │
|
||||
│ • VendorUser. │
|
||||
│ is_active │
|
||||
└────┬────────────────┘
|
||||
│
|
||||
│ 4. Jane can now login
|
||||
│
|
||||
▼
|
||||
┌──────────────────────┐
|
||||
│ Jane logs in to │
|
||||
│ ACME vendor portal │
|
||||
│ with Manager perms │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
## Permission Check Flow
|
||||
|
||||
```
|
||||
┌────────────────┐
|
||||
│ User makes │
|
||||
│ request to: │
|
||||
│ POST /products │
|
||||
└───────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ FastAPI Dependency: │
|
||||
│ require_vendor_permission( │
|
||||
│ "products.create" │
|
||||
│ ) │
|
||||
└───────┬────────────────────────┘
|
||||
│
|
||||
│ 1. Get vendor from request.state
|
||||
│ 2. Get user from JWT
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ Is user a member of vendor? │
|
||||
└───────┬────────────────────────┘
|
||||
│
|
||||
├─ No ──> ❌ VendorAccessDeniedException
|
||||
│
|
||||
▼ Yes
|
||||
┌────────────────────────────────┐
|
||||
│ Is user the owner? │
|
||||
└───────┬────────────────────────┘
|
||||
│
|
||||
├─ Yes ──> ✅ Allow (owners have all perms)
|
||||
│
|
||||
▼ No
|
||||
┌────────────────────────────────┐
|
||||
│ Get user's role and │
|
||||
│ permissions from VendorUser │
|
||||
└───────┬────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌────────────────────────────────┐
|
||||
│ Does role contain │
|
||||
│ "products.create"? │
|
||||
└───────┬────────────────────────┘
|
||||
│
|
||||
├─ No ──> ❌ InsufficientVendorPermissionsException
|
||||
│
|
||||
▼ Yes
|
||||
┌────────────────────────────────┐
|
||||
│ ✅ Allow request │
|
||||
│ Handler executes │
|
||||
└────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Database Relationships
|
||||
|
||||
```
|
||||
┌──────────────────┐
|
||||
│ users │
|
||||
│ │
|
||||
│ id (PK) │◄────┐
|
||||
│ email │ │
|
||||
│ role │ │
|
||||
│ ('admin' or │ │
|
||||
│ 'vendor') │ │
|
||||
└──────────────────┘ │
|
||||
│ │
|
||||
│ owner_user_id │
|
||||
│ │
|
||||
▼ │
|
||||
┌──────────────────┐ │
|
||||
│ vendors │ │
|
||||
│ │ │
|
||||
│ id (PK) │ │
|
||||
│ vendor_code │ │
|
||||
│ owner_user_id ──┼─────┘
|
||||
└──────────────────┘
|
||||
│
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ vendor_users │ │ roles │
|
||||
│ │ │ │
|
||||
│ id (PK) │ │ id (PK) │
|
||||
│ vendor_id (FK) │ │ vendor_id (FK) │
|
||||
│ user_id (FK) │ │ name │
|
||||
│ role_id (FK) ───┼────►│ permissions │
|
||||
│ user_type │ │ (JSON) │
|
||||
│ ('owner' or │ └──────────────────┘
|
||||
│ 'member') │
|
||||
│ invitation_* │
|
||||
│ is_active │
|
||||
└──────────────────┘
|
||||
|
||||
Separate hierarchy:
|
||||
|
||||
┌──────────────────┐
|
||||
│ customers │
|
||||
│ │
|
||||
│ id (PK) │
|
||||
│ vendor_id (FK) │
|
||||
│ email │
|
||||
│ hashed_password │
|
||||
│ (vendor-scoped) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## Permission Naming Convention
|
||||
|
||||
```
|
||||
Resource.Action
|
||||
|
||||
Examples:
|
||||
✓ dashboard.view
|
||||
✓ products.view
|
||||
✓ products.create
|
||||
✓ products.edit
|
||||
✓ products.delete
|
||||
✓ products.import
|
||||
✓ products.export
|
||||
✓ orders.view
|
||||
✓ orders.edit
|
||||
✓ orders.cancel
|
||||
✓ orders.refund
|
||||
✓ customers.view
|
||||
✓ customers.edit
|
||||
✓ reports.financial
|
||||
✓ team.invite
|
||||
✓ team.remove
|
||||
✓ settings.edit
|
||||
```
|
||||
|
||||
## Role Presets
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ OWNER │
|
||||
│ ALL PERMISSIONS (automatic, not stored in role) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ MANAGER │
|
||||
│ Most permissions except: │
|
||||
│ • team.invite/remove (owner only) │
|
||||
│ • Critical settings (owner only) │
|
||||
│ │
|
||||
│ Has: products.*, orders.*, customers.*, reports.* │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ STAFF │
|
||||
│ Day-to-day operations: │
|
||||
│ • products.view/create/edit │
|
||||
│ • stock.view/edit │
|
||||
│ • orders.view/edit │
|
||||
│ • customers.view │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ SUPPORT │
|
||||
│ Customer service focus: │
|
||||
│ • orders.view/edit │
|
||||
│ • customers.view/edit │
|
||||
│ • products.view (read-only) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ VIEWER │
|
||||
│ Read-only access: │
|
||||
│ • *.view permissions only │
|
||||
│ • No edit/create/delete │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌──────────────────────────────────────────────────────────────┐
|
||||
│ MARKETING │
|
||||
│ Marketing & analytics focus: │
|
||||
│ • customers.view/export │
|
||||
│ • marketing.* (all marketing actions) │
|
||||
│ • reports.view │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Security Boundaries
|
||||
|
||||
```
|
||||
❌ BLOCKED ✅ ALLOWED
|
||||
|
||||
Admin → Vendor Portal Admin → Admin Portal
|
||||
Vendor → Admin Portal Vendor → Vendor Portal
|
||||
Customer → Admin Portal Customer → Shop Catalog
|
||||
Customer → Vendor Portal Customer → Own Account
|
||||
|
||||
Cookie Isolation:
|
||||
admin_token (path=/admin) ← Only sent to /admin/*
|
||||
vendor_token (path=/vendor) ← Only sent to /vendor/*
|
||||
customer_token (path=/shop) ← Only sent to /shop/*
|
||||
```
|
||||
Reference in New Issue
Block a user