citrus-cms/resources/views/guide/specific-permissions-module.md

# Specific Permissions Module Documentation

## Overview

The Specific Permissions Module is a configuration system that allows administrators to define granular permission settings for different user levels within the DevQMS application. This module provides a flexible way to control access to specific features and functionalities based on user roles.

## File Location

- **View File**: `resources/views/admin/type/settings/specific-permissions.blade.php`
- **Guide Documentation**: `resources/views/guide/specific-permissions-module.md`

## Features

### 1. Permission Management
- Define custom permission settings for different user levels
- Multi-select dropdown interface for easy configuration
- Real-time updates through form submission
- Integration with the existing settings system

### 2. User Level Integration
- Automatically retrieves available user levels from the system
- Dynamic option population in permission dropdowns
- Support for multiple user level selections per permission

### 3. Settings Storage
- Permissions are stored in the `settings` table
- JSON format for storing multiple values
- Persistent configuration across sessions

## Module Structure

### Permission Definitions

The module defines specific permissions in the `$permissions` array:

```php
$permissions = [
    'Weld Log ISO Upload Permission' => 'weld_log_iso_upload_permission',
    'Engineer Upload Permission' => 'engineer_upload_permission',
];
```

### Key Components

1. **Form Handler**: Processes permission updates via POST requests
2. **User Level Retrieval**: Gets available user levels from the system
3. **Settings Integration**: Uses the `firstOrUpdate` function for database operations
4. **Dynamic UI**: Select2 integration for enhanced user experience

## Technical Implementation

### Database Operations

```php
// Update settings when form is submitted
if(getisset("update")) {
    foreach($_POST AS $key => $value) {
        firstOrUpdate([
            'title' => $key,
            'html' => $value
        ],"settings",[
            'title' => $key
        ]);
    }
}
```

### User Level Integration

```php
// Retrieve available user levels
$userLevels = array_keys(levels());
```

### Frontend Integration

The module uses Select2 for enhanced dropdown functionality:

```javascript
$('.select2').select2({
    placeholder: "Select User Levels",
    allowClear: true,
    width: '100%'
});
```

## Usage

### 1. Accessing the Module

Navigate to the admin panel and access the specific permissions settings through the settings section.

### 2. Configuring Permissions

1. Select the desired user levels for each permission
2. Use the multi-select dropdown to choose multiple levels
3. Click "Update" to save changes

### 3. Permission Types

Currently supported permission types:

- **Weld Log ISO Upload Permission**: Controls access to ISO upload functionality in weld log module
- **Engineer Upload Permission**: Controls engineer-level upload permissions

## Integration with Other Modules

### Settings System Integration

The module integrates with the global settings system:

```php
// Retrieve permission settings
$selectedValues = j(setting($key));
```

### User Level System

Leverages the existing user level system:

```php
// Get user levels from the system
$userLevels = array_keys(levels());
```

## Adding New Permissions

To add new permission types:

1. **Update the permissions array**:
```php
$permissions = [
    'Weld Log ISO Upload Permission' => 'weld_log_iso_upload_permission',
    'Engineer Upload Permission' => 'engineer_upload_permission',
    'New Permission Name' => 'new_permission_key',
];
```

2. **The system will automatically**:
   - Create the form field
   - Add it to the database
   - Include it in the Select2 initialization

## Security Considerations

- All form submissions include CSRF protection
- Permission changes require admin-level access
- Settings are stored securely in the database
- User level validation is performed server-side

## Dependencies

- **Laravel Framework**: For form handling and database operations
- **Select2**: For enhanced dropdown functionality
- **jQuery**: For frontend interactions
- **Bootstrap**: For styling and modal functionality

## Future Enhancements

Potential improvements for the module:

1. **Permission Categories**: Group related permissions together
2. **Permission Inheritance**: Allow permissions to inherit from parent levels
3. **Audit Logging**: Track permission changes over time
4. **Bulk Operations**: Enable bulk permission updates
5. **Permission Templates**: Predefined permission sets for common scenarios

## Troubleshooting

### Common Issues

1. **Permissions not saving**: Check CSRF token and form submission
2. **User levels not appearing**: Verify the `levels()` function returns correct data
3. **Select2 not working**: Ensure jQuery and Select2 are properly loaded

### Debug Information

To debug permission settings:

```php
// Check current permission values
$permissionValue = setting('weld_log_iso_upload_permission');
var_dump($permissionValue);
```

## Related Documentation

- [User Level System Documentation](user-levels.md)
- [Settings System Documentation](settings-system.md)
- [Admin Panel Documentation](admin-panel.md)
- [Permission Control Middleware](permission-middleware.md)