# Role-Based Access Control (RBAC) Implementation

## Overview

This document describes the implementation of a robust role-based access control system using the Spatie Laravel Permission package in the Lumen API. The system provides fine-grained permissions for both Flutter mobile app and web-based frontend consumption.

## Implementation Details

### 1. Package Installation

- **Package**: `spatie/laravel-permission` v6.21.0
- **Installation**: `composer require spatie/laravel-permission`

### 2. Database Structure

The implementation uses the following tables:

- `roles` - Stores role definitions
- `permissions` - Stores permission definitions  
- `role_has_permissions` - Many-to-many relationship between roles and permissions
- `model_has_roles` - Polymorphic relationship for user-role assignments
- `model_has_permissions` - Polymorphic relationship for direct user-permission assignments

### 3. Configuration

#### Permission Configuration (`config/permission.php`)
- **Default Guard**: `api`
- **Cache Store**: `array` (for Lumen compatibility)
- **Models**: Custom App\Role and App\Permission models

#### Service Provider Registration
- Added `Spatie\Permission\PermissionServiceProvider` to `bootstrap/app.php`
- Configured permission config in bootstrap

### 4. Model Updates

#### User Model (`app/User.php`)
- Added `HasRoles` trait from Spatie
- Maintained backward compatibility with existing methods:
  - `hasRole($role)` - Check if user has specific role
  - `hasAccess(array $permissions)` - Check if user has all permissions
  - `hasAtLeastAccess(array $permissions)` - Check if user has any permission
  - `getPermissions()` - Get all user permissions

#### Role Model (`app/Role.php`)
- Extends `Spatie\Permission\Models\Role`
- Maintains backward compatibility methods

#### Permission Model (`app/Permission.php`)
- Extends `Spatie\Permission\Models\Permission`
- Uses Spatie's built-in functionality

### 5. Permissions Structure

The system includes 71 granular permissions organized into categories:

#### User Management
- `view users`, `create users`, `edit users`, `delete users`

#### Role & Permission Management
- `view roles`, `create roles`, `edit roles`, `delete roles`, `assign roles`
- `view permissions`, `create permissions`, `edit permissions`, `delete permissions`, `assign permissions`

#### Inventory Management
- `view items`, `create items`, `edit items`, `delete items`, `manage stock`, `view inventory`

#### Sales Management
- `view sales`, `create sales`, `edit sales`, `delete sales`, `view sales reports`, `process refunds`

#### Customer Management
- `view customers`, `create customers`, `edit customers`, `delete customers`, `manage customer debts`

#### Supplier Management
- `view suppliers`, `create suppliers`, `edit suppliers`, `delete suppliers`, `manage supplier payments`

#### Financial Management
- `view accounts`, `create accounts`, `edit accounts`, `delete accounts`, `view financial reports`
- `manage deposits`, `manage withdrawals`, `manage transfers`

#### Employee Management
- `view employees`, `create employees`, `edit employees`, `delete employees`, `manage employee payments`, `view salaries`

#### Session Management
- `view sessions`, `manage sessions`, `close sessions`, `view session reports`

#### Department Management
- `view departments`, `create departments`, `edit departments`, `delete departments`

#### Settings Management
- `view settings`, `edit settings`, `manage configurations`

#### Reports
- `view all reports`, `export reports`, `view service reports`

#### Operations
- `pos operations`, `cashier operations`, `service operations`

#### System Administration
- `system administration`, `backup data`, `restore data`, `view system logs`

### 6. Role Definitions

#### Administrator
- **Description**: System Administrator with full access
- **Permissions**: All 71 permissions
- **Use Case**: Complete system access for IT administrators

#### Manager
- **Description**: Manager role with limited administrative access
- **Permissions**: 48 permissions (excluding system administration and user management)
- **Use Case**: Department managers with oversight capabilities

#### Cashier
- **Description**: Cashier role for POS operations
- **Permissions**: 13 permissions focused on sales and customer management
- **Use Case**: Point-of-sale operations

#### Service
- **Description**: Service agent role
- **Permissions**: 8 permissions for basic service operations
- **Use Case**: Customer service representatives

#### Employee
- **Description**: Basic employee role
- **Permissions**: 6 permissions for basic operations
- **Use Case**: General employees with minimal access

### 7. Controller Updates

#### RoleController (`app/Http/Controllers/RoleController.php`)
- Updated to use Spatie methods:
  - `assignUserRoles()` - Uses `syncRoles()`
  - `assignRolePermissions()` - Uses `syncPermissions()`
- Maintains existing API endpoints for backward compatibility

#### AuthController
- Existing `hasRole()` checks continue to work due to backward compatibility

### 8. Middleware

#### RolePermissionMiddleware (`app/Http/Middleware/RolePermissionMiddleware.php`)
- Provides route-level permission checking
- Supports both role and permission parameters
- Returns standardized JSON responses

#### Registration
```php
$app->routeMiddleware([
    'role' => App\Http\Middleware\RolePermissionMiddleware::class,
    'permission' => App\Http\Middleware\RolePermissionMiddleware::class,
]);
```

### 9. Usage Examples

#### Assigning Roles to Users
```php
// Assign single role
$user->assignRole('administrator');

// Assign multiple roles
$user->assignRole(['manager', 'cashier']);

// Sync roles (replace all existing roles)
$user->syncRoles(['administrator']);
```

#### Checking Permissions
```php
// Check single permission
if ($user->hasPermissionTo('view users')) {
    // User can view users
}

// Check multiple permissions (all required)
if ($user->hasAccess(['view users', 'create users'])) {
    // User has both permissions
}

// Check multiple permissions (any required)
if ($user->hasAtLeastAccess(['view users', 'view sales'])) {
    // User has at least one permission
}
```

#### Checking Roles
```php
// Check single role
if ($user->hasRole('administrator')) {
    // User is administrator
}

// Check multiple roles
if ($user->hasAnyRole(['manager', 'administrator'])) {
    // User has manager or administrator role
}
```

#### Route Middleware Usage
```php
// Require specific role
Route::get('/admin', ['middleware' => 'role:administrator', 'uses' => 'AdminController@index']);

// Require specific permission
Route::get('/users', ['middleware' => 'permission:view users', 'uses' => 'UserController@index']);

// Require both role and permission
Route::get('/reports', ['middleware' => 'role:manager,permission:view all reports', 'uses' => 'ReportController@index']);
```

### 10. API Endpoints

The following endpoints are available for role and permission management:

#### Roles
- `GET /roles` - List all roles
- `POST /roles` - Create new role
- `PUT /roles/{id}` - Update role
- `DELETE /roles/{id}` - Delete role
- `GET /roles/{id}/permissions` - Get role permissions
- `POST /roles/{id}/permissions` - Assign permissions to role

#### Users
- `POST /users/{id}/roles` - Assign roles to user
- `GET /users/{id}/roles` - Get user roles
- `GET /auth/user-permissions` - Get authenticated user permissions

#### Permissions
- `GET /permissions` - List all permissions

### 11. Migration and Seeding

#### Migration
- Created `2025_10_06_010535_create_permission_tables.php`
- Drops existing tables and creates Spatie-compatible structure

#### Seeding
- Created `SeedPermissionsCommand` for seeding permissions and roles
- Available via: `php artisan seed:permissions`

### 12. Backward Compatibility

The implementation maintains full backward compatibility with existing code:

- All existing `hasRole()` calls continue to work
- Existing `hasAccess()` and `hasAtLeastAccess()` methods preserved
- API endpoints maintain same structure
- Database migration handles existing data

### 13. Performance Considerations

- Uses array cache store for Lumen compatibility
- Permissions are cached for performance
- Database indexes on foreign keys for efficient queries
- Polymorphic relationships for flexible user assignments

### 14. Security Features

- Guard-based separation (API guard)
- Granular permission system
- Role hierarchy support
- Direct permission assignment capability
- Audit trail through database relationships

### 15. Testing

The implementation has been tested with:
- Database table creation and seeding
- Role-permission relationships
- User-role assignments
- Permission checking methods
- Backward compatibility methods

### 16. Future Enhancements

Potential improvements for future versions:

1. **Team-based permissions** - Enable multi-tenant support
2. **Permission groups** - Organize permissions into logical groups
3. **Temporary permissions** - Time-based permission assignments
4. **Audit logging** - Track permission and role changes
5. **Permission inheritance** - Hierarchical permission structures

## Conclusion

The implementation provides a robust, scalable, and maintainable role-based access control system that supports both Flutter mobile app and web-based frontend consumption. The system maintains backward compatibility while providing modern, granular permission management capabilities.