# 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

```php
// 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

```php
// 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

```blade
{{-- 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

```php
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
```bash
# 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
```bash
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

```bash
# 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.