Skip to main content

​
Overview

GIMA implements a comprehensive role-based access control (RBAC) system using Spatie Laravel Permission. The system defines four distinct roles with specific permissions, enabling secure and efficient workflow management across different user types.

​
Role Hierarchy

Admin

Full System ControlComplete access to all features and settings. Can manage users, roles, and all system data.

Supervisor

Management & OversightManages assets, assigns tasks to technicians, and oversees maintenance operations.

Técnico

Task ExecutionExecutes assigned maintenance tasks, records activities, and manages spare parts usage.

Reporter

Fault ReportingReports asset failures and views their own submitted reports. Read-only access to assets.

​
Permission System

Permissions in GIMA are defined in database/seeders/RolesSeeder.php and assigned to roles during system initialization.

​
Permission Categories

These permissions are available to all authenticated users:
  • crear reporte fallas: Submit fault reports for assets
  • ver mis reportes: View reports created by the user
  • ver catalogo activos: Read-only access to the asset catalog
Exclusive administrative capabilities:
  • gestionar usuarios: Full CRUD operations on users
  • gestion maestra: Manage master data (Locations, Spare Parts, Suppliers)
  • All permissions: Admins inherit every permission in the system
Management and coordination capabilities:
  • ver dashboard supervisor: Access supervisor dashboard
  • gestionar activos: Create, modify, and list assets
  • gestionar reportes: Assign fault reports to technicians
  • gestionar mantenimientos: Create and modify maintenance plans
  • Plus all shared permissions
Technical execution capabilities:
  • ver mis tareas: View assigned tasks
  • registrar actividad tecnica: Record task start, progress, and completion
  • registrar repuestos usados: Register spare parts usage and consumption
  • Plus all shared permissions

​
Role Definitions in Code

From database/seeders/RolesSeeder.php:source/database/seeders/RolesSeeder.php: 
// 1. Create the 4 base roles
$adminRole = Role::create(['name' => 'admin']);
$supervisorRole = Role::create(['name' => 'supervisor']);
$tecnicoRole = Role::create(['name' => 'tecnico']);
$reporterRole = Role::create(['name' => 'reporter']);

​
Admin Role Assignment

// Admin gets ALL permissions
$adminRole->givePermissionTo(Permission::all());
The Admin role automatically receives all current and future permissions, ensuring complete system access.

​
Supervisor Role Assignment

$supervisorRole->givePermissionTo([
    $permissionVerSupervisorDashboard,    // Dashboard access
    $permissionGestionarActivos,          // Asset management
    $permissionAsignarReportes,           // Report assignment
    $permissionGestionarMantenimientos,   // Maintenance planning
    $permissionCrearReporteFallas,        // Create reports
    $permissionVerCatalogoActivos,        // View asset catalog
    $permissionVerMisReportes             // View own reports
]);

​
Técnico Role Assignment

$tecnicoRole->givePermissionTo([
    $permissionVerMisTareas,              // View assigned tasks
    $permissionRegistrarActividadTecnica, // Record technical activities
    $permissionRegistrarRepuestosUsados,  // Register spare parts
    $permissionCrearReporteFallas,        // Create reports
    $permissionVerCatalogoActivos,        // View asset catalog
    $permissionVerMisReportes             // View own reports
]);

​
Reporter Role Assignment

$reporterRole->givePermissionTo([
    $permissionCrearReporteFallas,        // Create fault reports
    $permissionVerMisReportes,            // View own reports
    $permissionVerCatalogoActivos         // View asset catalog
]);

​
User Model Integration

The User model integrates Spatie’s permission system: 
use Spatie\Permission\Traits\HasRoles;
use Laravel\Sanctum\HasApiTokens;

class User extends Authenticatable
{
    use HasRoles;      // Enable role assignment
    use HasApiTokens;  // Enable Sanctum authentication
    
    protected $fillable = [
        'name',
        'email',
        'password',
        'telefono',
        'estado',
        'aprobado_por',
        'fecha_aprobacion',
    ];
}

​
User Approval Workflow

GIMA includes a user approval system where new users must be approved by an existing user (typically an Admin).
// Self-referential relationship for user approval
public function aprobador(): BelongsTo
{
    return $this->belongsTo(User::class, 'aprobado_por');
}

public function usuariosAprobados(): HasMany
{
    return $this->hasMany(User::class, 'aprobado_por');
}

​
Route Protection

Routes are protected using role middleware from Spatie Permission:

​
Admin-Only Routes

Route::prefix('admin')
    ->middleware('role:admin')
    ->group(function () {
        Route::get('dashboard', function () {
            return response()->json([
                'mensaje' => 'Hola Admin, tienes control total.'
            ]);
        });
    });

​
Multi-Role Routes

// Technical routes accessible by Técnico, Supervisor, and Admin
Route::prefix('tecnica')
    ->middleware('role:tecnico|supervisor|admin')
    ->group(function () {
        Route::get('ordenes-trabajo', function () {
            return response()->json([
                'mensaje' => 'Listado de órdenes de trabajo'
            ]);
        });
    });

​
Supervisor Routes

Route::prefix('supervision')
    ->middleware('role:supervisor|admin')
    ->group(function () {
        Route::get('auditoria', function () {
            return response()->json([
                'mensaje' => 'Auditoría de calidad'
            ]);
        });
    });

​
Permission Checking

​
In Controllers

// Check if user has specific permission
if ($user->can('gestionar activos')) {
    // User can manage assets
}

// Check if user has specific role
if ($user->hasRole('supervisor')) {
    // User is a supervisor
}

// Check if user has any of the given roles
if ($user->hasAnyRole(['admin', 'supervisor'])) {
    // User is admin or supervisor
}

​
In Blade Templates

@can('gestionar usuarios')
    <a href="/admin/usuarios">Manage Users</a>
@endcan

@role('admin')
    <button>Admin Panel</button>
@endrole

​
In API Responses

public function perfil(Request $request)
{
    $user = $request->user();
    
    return response()->json([
        'user' => $user,
        'roles' => $user->getRoleNames(),
        'permissions' => $user->getAllPermissions()->pluck('name')
    ]);
}

​
Role Comparison Matrix

PermissionAdminSupervisorTécnicoReporter
User Management
Gestionar usuarios✅❌❌❌
Asset Management
Gestionar activos✅✅❌❌
Ver catálogo activos✅✅✅✅
Maintenance
Gestionar mantenimientos✅✅❌❌
Ver mis tareas✅✅✅❌
Registrar actividad técnica✅✅✅❌
Reports
Crear reporte fallas✅✅✅✅
Gestionar reportes✅✅❌❌
Ver mis reportes✅✅✅✅
Inventory
Registrar repuestos usados✅✅✅❌
Gestión maestra✅❌❌❌
Dashboards
Ver dashboard supervisor✅✅❌❌

​
Default Test Users

The seeder creates default users for testing: 
// Admin user
$admin = User::create([
    'name' => 'Admin User',
    'email' => '[email protected]',
    'password' => Hash::make('12345678'),
]);
$admin->assignRole($adminRole);

// Supervisor user
$supervisor = User::create([
    'name' => 'Roberto Supervisor',
    'email' => '[email protected]',
    'password' => Hash::make('12345678'),
]);
$supervisor->assignRole($supervisorRole);

// Técnico user
$tecnico = User::create([
    'name' => 'Juan Técnico',
    'email' => '[email protected]',
    'password' => Hash::make('12345678'),
]);
$tecnico->assignRole($tecnicoRole);

// Reporter user
$reporter = User::create([
    'name' => 'Ana Reportes',
    'email' => '[email protected]',
    'password' => Hash::make('12345678'),
]);
$reporter->assignRole($reporterRole);
These test credentials should be changed or removed in production environments.

​
Permission Cache

Spatie Permission caches permissions for performance. Clear the cache when modifying permissions: 
use Spatie\Permission\PermissionRegistrar;

// Clear permission cache
app()[PermissionRegistrar::class]->forgetCachedPermissions();
The cache is automatically cleared in RolesSeeder.php:source/database/seeders/RolesSeeder.php at line 21.

​
Best Practices

Principle of Least Privilege

Assign users the minimum permissions needed for their role. Avoid granting unnecessary access.

Role Naming

Use lowercase, singular names for roles (admin, not Admin or admins) to match Spatie conventions.

Permission Naming

Use descriptive, action-based names (gestionar activos, not assets or manage).

Middleware Protection

Always protect routes with auth:sanctum and role middleware. Never rely on client-side checks alone.

​
Next Steps

Architecture

Learn about system architecture

Asset Management

Understand asset lifecycle

Authentication

API authentication guide

Build docs developers (and LLMs) love

Get started for freeTalk to us