# Admin Permission System Documentation

## Overview

This document outlines the comprehensive role-based access control (RBAC) system implemented for the Afghan Market Admin Panel.

## Role Hierarchy

### 1. Super Admin
- **Access**: Full system access
- **Permissions**: All available permissions
- **Purpose**: System administrators and owners

### 2. Admin
- **Access**: Most administrative functions
- **Restrictions**: Cannot manage other admins, roles, permissions, or system settings
- **Purpose**: Day-to-day operations management

### 3. Manager
- **Access**: View and edit most content
- **Restrictions**: Limited deletion capabilities, no system configuration
- **Purpose**: Content and operations management

### 4. Operator
- **Access**: Basic operations and content management
- **Restrictions**: Read-only access to most configuration, can perform basic edits
- **Purpose**: Customer service and basic operations

### 5. Viewer
- **Access**: Read-only access to all modules
- **Restrictions**: Cannot make any changes
- **Purpose**: Reporting and monitoring

## Permission Categories

### Dashboard Access
- `view dashboard` - View dashboard interface and analytics
- `access dashboard` - Access the admin dashboard (required for all dashboard access)

### Products & Catalog
- `view products` - View product listings and details
- `create products` - Add new products
- `edit products` - Modify existing products
- `delete products` - Remove products
- `export products` - Export product data

### Categories
- `view categories` - View category listings
- `create categories` - Add new categories
- `edit categories` - Modify existing categories
- `delete categories` - Remove categories

### Packages
- `view packages` - View package listings and details
- `create packages` - Add new packages
- `edit packages` - Modify existing packages
- `delete packages` - Remove packages
- `export packages` - Export package data

### Orders Management
- `view orders` - View order listings and details
- `create orders` - Create new orders (admin)
- `edit orders` - Modify order status and details
- `delete orders` - Remove orders
- `export orders` - Export order data

### Delivery & Logistics
- `view delivery staff` - View delivery staff listings
- `create delivery staff` - Add new delivery staff
- `edit delivery staff` - Modify delivery staff details
- `delete delivery staff` - Remove delivery staff
- `view delivery costs` - View delivery cost settings
- `create delivery costs` - Add new delivery cost rules
- `edit delivery costs` - Modify delivery cost rules
- `delete delivery costs` - Remove delivery cost rules

### Marketing & Promotions
- `view coupons` - View discount coupons
- `create coupons` - Create new discount coupons
- `edit coupons` - Modify existing coupons
- `delete coupons` - Remove coupons
- `view deals of the day` - View daily deals
- `create deals of the day` - Create new daily deals
- `edit deals of the day` - Modify daily deals
- `delete deals of the day` - Remove daily deals
- `manage deals of the day` - Toggle deal status
- `view advertisements` - View advertisements
- `create advertisements` - Create new advertisements
- `edit advertisements` - Modify advertisements
- `delete advertisements` - Remove advertisements

### Financial Management
- `view payment gateways` - View payment gateway settings
- `create payment gateways` - Add new payment gateways
- `edit payment gateways` - Modify payment gateway settings
- `delete payment gateways` - Remove payment gateways
- `view conversion rates` - View currency conversion rates
- `create conversion rates` - Add new conversion rates
- `edit conversion rates` - Modify conversion rates
- `delete conversion rates` - Remove conversion rates
- `view currencies` - View currency listings
- `create currencies` - Add new currencies
- `edit currencies` - Modify currency details
- `delete currencies` - Remove currencies
- `manage currencies` - Set default currency

### User Management
- `view users` - View customer listings and details
- `create users` - Create new customer accounts
- `edit users` - Modify customer details
- `delete users` - Remove customer accounts
- `manage user credits` - Adjust customer credit balances

### Admin & Security
- `view admins` - View admin user listings
- `create admins` - Create new admin accounts
- `edit admins` - Modify admin details
- `delete admins` - Remove admin accounts
- `view roles` - View role listings
- `create roles` - Create new roles
- `edit roles` - Modify existing roles
- `delete roles` - Remove roles
- `view permissions` - View permission listings
- `create permissions` - Create new permissions
- `edit permissions` - Modify existing permissions
- `delete permissions` - Remove permissions
- `assign roles` - Assign roles to users

### Content Management
- `view company profile` - View company information
- `edit company profile` - Modify company details
- `view footer pages` - View footer page content
- `edit footer pages` - Modify footer page content

### Customer Support
- `view chat qa` - View chat Q&A database
- `create chat qa` - Add new Q&A entries
- `edit chat qa` - Modify Q&A entries
- `delete chat qa` - Remove Q&A entries
- `view chat conversations` - View customer chat conversations
- `manage chat conversations` - Respond to and manage chats
- `assign chat conversations` - Assign chats to staff members

### Communications
- `view notifications` - View notification history
- `create notifications` - Create new notifications
- `edit notifications` - Modify existing notifications
- `delete notifications` - Remove notifications
- `send notifications` - Send notifications to users
- `view newsletter subscriptions` - View newsletter subscribers
- `delete newsletter subscriptions` - Remove subscribers
- `export newsletter subscriptions` - Export subscriber data

### System Configuration
- `view settings` - View system settings
- `create settings` - Add new system settings
- `edit settings` - Modify system settings
- `delete settings` - Remove system settings
- `view credit settings` - View credit system settings
- `edit credit settings` - Modify credit system rules
- `view credit transactions` - View credit transaction history
- `manage credit transactions` - Manage credit transactions

### System Administration
- `view backup` - View backup listings
- `create backup` - Create system backups
- `restore backup` - Restore from backup
- `view reports` - View system reports
- `export reports` - Export report data

## Implementation Details

### Middleware Usage
All controllers use Laravel's permission middleware to protect routes:

```php
$this->middleware('permission:view products')->only(['index', 'show']);
$this->middleware('permission:create products')->only(['store']);
$this->middleware('permission:edit products')->only(['update']);
$this->middleware('permission:delete products')->only(['destroy']);
```

### Policy Integration
Model policies are implemented for fine-grained access control:

```php
public function update($user, Product $product): bool
{
    return $user->hasPermissionTo('edit products');
}
```

### Super Admin Bypass
The system includes a super admin bypass in `AuthServiceProvider`:

```php
Gate::before(function ($user, string $ability) {
    if ($user->hasRole('super-admin')) {
        return true;
    }
    return null;
});
```

## Security Features

1. **Permission-based Access Control**: Every action requires specific permission
2. **Role Hierarchy**: Clear separation of responsibilities
3. **Policy Integration**: Model-level authorization
4. **Super Admin Bypass**: Ensures system owners always have access
5. **Automatic Role Assignment**: Existing admins automatically get super-admin role

## Best Practices

1. **Principle of Least Privilege**: Users should only have permissions they need
2. **Regular Audits**: Review user permissions regularly
3. **Role-based Assignment**: Assign roles rather than individual permissions
4. **Documentation**: Keep permission documentation updated
5. **Testing**: Test permission changes thoroughly

## Database Tables

- `permissions` - Available permissions
- `roles` - User roles
- `model_has_permissions` - User permissions
- `model_has_roles` - User role assignments
- `role_has_permissions` - Role permission assignments

## Usage Examples

### Checking Permissions in Code
```php
// Check if user has permission
if ($user->hasPermissionTo('edit products')) {
    // Allow product editing
}

// Check if user has role
if ($user->hasRole('admin')) {
    // Allow admin actions
}
```

### Protecting Routes
```php
// In controller constructor
$this->middleware('permission:view products')->only(['index', 'show']);

// In routes file
Route::get('/products', [ProductController::class, 'index'])
    ->middleware('permission:view products');
```

## Maintenance

1. **Add New Permissions**: Update `RolesAndPermissionsSeeder.php`
2. **Create New Roles**: Add to seeder with appropriate permissions
3. **Update Policies**: Modify model policies for new features
4. **Run Seeder**: `php artisan db:seed --class=RolesAndPermissionsSeeder`
5. **Clear Cache**: `php artisan cache:clear` and `php artisan config:clear`

This permission system ensures secure, granular access control throughout the admin panel while maintaining flexibility for future growth.