Car-Repairs-Shop/PERMISSIONS.md

Role-Based User Permission System Documentation

Overview

This car repairs shop application now includes a comprehensive role-based permission system that provides fine-grained access control across all modules. The system supports:

• Hierarchical Roles: Users can have multiple roles with different permissions
• Direct Permissions: Users can have permissions assigned directly, bypassing roles
• Branch-Based Access: Permissions can be scoped to specific branches
• Module-Based Organization: Permissions are organized by functional modules

Database Structure

Core Tables

1. roles - Defines available roles in the system
2. permissions - Defines granular permissions organized by modules
3. role_permissions - Links roles to their permissions
4. user_roles - Assigns roles to users (with optional branch scoping)
5. user_permissions - Assigns direct permissions to users

Available Roles

Role	Display Name	Description
admin	Administrator	Full system access across all branches
manager	Branch Manager	Full access within assigned branch
service_supervisor	Service Supervisor	Supervises service operations and technicians
service_coordinator	Service Coordinator	Coordinates service workflow and scheduling
service_advisor	Service Advisor	Interfaces with customers and manages service requests
parts_manager	Parts Manager	Manages inventory and parts ordering
technician	Technician	Performs vehicle service and repairs
quality_inspector	Quality Inspector	Performs quality inspections and audits
customer_service	Customer Service	Handles customer inquiries and support

Permission Modules

Job Cards

• job-cards.view - View job cards in own branch
• job-cards.view-all - View job cards across all branches
• job-cards.view-own - View only assigned job cards
• job-cards.create - Create new job cards
• job-cards.update - Update job cards in own branch
• job-cards.update-all - Update job cards across all branches
• job-cards.update-own - Update only assigned job cards
• job-cards.delete - Delete job cards
• job-cards.approve - Approve job cards for processing
• job-cards.assign-technician - Assign technicians to job cards

Customers

• customers.view - View customer information
• customers.create - Create new customers
• customers.update - Update customer information
• customers.delete - Delete customers

Vehicles

• vehicles.view - View vehicle information
• vehicles.create - Register new vehicles
• vehicles.update - Update vehicle information
• vehicles.delete - Delete vehicles

Inventory

• inventory.view - View inventory items
• inventory.create - Add new inventory items
• inventory.update - Update inventory items
• inventory.delete - Delete inventory items
• inventory.stock-movements - Manage stock movements
• inventory.purchase-orders - Manage purchase orders

Service Orders

• service-orders.view - View service orders
• service-orders.create - Create new service orders
• service-orders.update - Update service orders
• service-orders.delete - Delete service orders
• service-orders.approve - Approve service orders

Appointments

• appointments.view - View appointments
• appointments.create - Schedule new appointments
• appointments.update - Update appointments
• appointments.delete - Cancel appointments

Technicians

• technicians.view - View technician information
• technicians.create - Add new technicians
• technicians.update - Update technician information
• technicians.delete - Remove technicians
• technicians.assign-work - Assign work to technicians
• technicians.view-performance - View technician performance reports

Reports

• reports.view - View all reports
• reports.financial - View financial and revenue reports
• reports.operational - View operational and performance reports
• reports.export - Export reports to various formats

User Management

• users.view - View user accounts
• users.create - Create new user accounts
• users.update - Update user information
• users.delete - Delete user accounts
• users.manage-roles - Assign and remove user roles

System Administration

• system.settings - Configure system settings
• system.maintenance - Perform system maintenance tasks

Usage Examples

In Controllers/Livewire Components

// Check permission in component mount method
public function mount()
{
    $this->authorize('create', JobCard::class);
}

// Check permission in methods
public function save()
{
    if (!auth()->user()->hasPermission('job-cards.create')) {
        abort(403, 'You do not have permission to create job cards.');
    }
    // ... rest of the method
}

// Filter data based on permissions
public function loadData()
{
    $user = auth()->user();
    
    if ($user->hasPermission('job-cards.view-all')) {
        $this->jobCards = JobCard::all();
    } elseif ($user->hasPermission('job-cards.view')) {
        $this->jobCards = JobCard::where('branch_code', $user->branch_code)->get();
    } else {
        $this->jobCards = JobCard::where('service_advisor_id', $user->id)->get();
    }
}

In Routes

// Protect routes with permission middleware
Route::get('/job-cards', JobCardIndex::class)
    ->middleware('permission:job-cards.view');

Route::get('/job-cards/create', JobCardCreate::class)
    ->middleware('permission:job-cards.create');

// Protect with role middleware
Route::prefix('admin')->middleware('role:admin,manager')->group(function () {
    Route::get('/settings', AdminSettings::class);
});

In Blade Templates

{{-- Using Blade directives --}}
@hasPermission('job-cards.create')
    <a href="{{ route('job-cards.create') }}" class="btn btn-primary">
        Create Job Card
    </a>
@endhasPermission

@hasRole('admin|manager')
    <div class="admin-panel">
        {{-- Admin content --}}
    </div>
@endhasRole

@hasAnyPermission('reports.view|reports.financial')
    <a href="{{ route('reports.index') }}">View Reports</a>
@endhasAnyPermission

{{-- Using permission component --}}
<x-permission-check permission="job-cards.update">
    <button wire:click="updateJobCard">Update</button>
</x-permission-check>

<x-permission-check role="service_supervisor">
    <div class="supervisor-tools">
        {{-- Supervisor-only tools --}}
    </div>
</x-permission-check>

In Policies

class JobCardPolicy
{
    public function view(User $user, JobCard $jobCard): bool
    {
        // Admin can view all
        if ($user->hasPermission('job-cards.view-all')) {
            return true;
        }
        
        // Branch-level access
        if ($user->hasPermission('job-cards.view') && 
            $jobCard->branch_code === $user->branch_code) {
            return true;
        }
        
        // Own records only
        if ($user->hasPermission('job-cards.view-own') && 
            $jobCard->service_advisor_id === $user->id) {
            return true;
        }
        
        return false;
    }
}

Artisan Commands

Assign Role to User

# Assign role without branch restriction
php artisan user:assign-role user@example.com admin

# Assign role with branch restriction
php artisan user:assign-role user@example.com service_advisor --branch=ACC

Seed Roles and Permissions

php artisan db:seed --class=RolesAndPermissionsSeeder

User Management Interface

The system includes a web interface for managing user roles and permissions:

• URL: /user-management
• Permission Required: users.view
• Features:
  • Search and filter users
  • Assign/remove roles
  • Grant/revoke direct permissions
  • Set branch-specific access
  • Activate/deactivate users

Permission Hierarchy

1. Super Admin: admin role bypasses all permission checks
2. Direct Permissions: Override role-based permissions
3. Role Permissions: Standard role-based access
4. Branch Scoping: Permissions can be limited to specific branches

Security Features

• Branch Isolation: Users can only access data within their assigned branch (unless granted cross-branch permissions)
• Temporal Permissions: Roles and permissions can have expiration dates
• Audit Trail: All role and permission changes are timestamped
• Middleware Protection: Routes are protected at the middleware level
• Policy-Based Authorization: Model operations use Laravel policies for fine-grained control

Best Practices

1. Use Roles for Common Patterns: Assign permissions to roles rather than directly to users
2. Branch Scoping: Always consider branch-level access when designing features
3. Least Privilege: Grant only the minimum permissions required for a user's job function
4. Regular Audits: Periodically review user permissions and remove unnecessary access
5. Policy Classes: Use Laravel policies for complex authorization logic
6. Middleware First: Apply middleware protection to routes before implementing view-level checks

Troubleshooting

Common Issues

1. Permission Denied Errors: Check that the user has the required permission and that their role is active
2. Branch Access Issues: Verify that the user's branch_code matches the resource's branch_code
3. Middleware Conflicts: Ensure middleware is applied in the correct order
4. Cache Issues: Clear application cache after changing permissions: php artisan cache:clear

Debug Commands

# Check user's roles and permissions
php artisan tinker
>>> $user = User::find(1);
>>> $user->getAllPermissions();
>>> $user->roles;

This permission system provides a robust foundation for controlling access to all features in your car repairs shop application while maintaining flexibility for different organizational structures and workflows.