# Role-Based Permission System Guide

## Overview

Aapke system mein ek comprehensive role-based permission system hai jo aapko allow karta hai:
- Custom roles create karne ke liye
- Har role ko alag-alag permissions assign karne ke liye
- Users aur employees ko roles assign karne ke liye
- Login ke baad users ko sirf unke assigned permissions ke according kaam karne ke liye

## System Structure

### Database Tables

1. **`roles`** - Sabhi roles store hote hain
   - `role_id` - Unique identifier
   - `role_code` - Unique code (e.g., 'super_admin', 'hr_admin', 'branch_manager')
   - `role_name` - Display name
   - `role_description` - Description
   - `is_system_role` - System role hai ya custom (0 = custom, 1 = system)

2. **`permissions`** - Sabhi available permissions
   - `permission_id` - Unique identifier
   - `permission_code` - Unique code (e.g., 'EMPLOYEE_VIEW', 'PAYROLL_CREATE')
   - `permission_name` - Display name
   - `permission_module` - Module name (e.g., 'employee', 'payroll', 'attendance')
   - `permission_description` - Description

3. **`role_permissions`** - Roles aur permissions ka mapping
   - `role_id` - Role reference
   - `permission_id` - Permission reference

4. **`users`** - User accounts
   - `user_id` - Unique identifier
   - `role_id` - Assigned role
   - `employee_id` - Linked employee (optional)

5. **`employees`** - Employee records
   - `employee_id` - Unique identifier
   - Can be linked to users via `user_id` or `employee_id` in users table

## Default Roles

System mein yeh default roles hain:

1. **SUPER_ADMIN** - Full system access (sab permissions)
2. **HR_ADMIN** - HR management access
3. **HR_MANAGER** - HR operations management
4. **HR_OFFICER** - HR daily operations
5. **MANAGER** - Department manager
6. **EMPLOYEE** - Regular employee

## How to Use

### 1. Custom Role Create Karna

**Step 1:** Login karein as Super Admin

**Step 2:** Settings → Role Management → Add Role

**Step 3:** Form fill karein:
- **Role Code:** Unique code (lowercase, numbers, underscore only)
  - Example: `branch_manager`, `department_head`, `accountant`
- **Role Name:** Display name
  - Example: `Branch Manager`, `Department Head`, `Accountant`
- **Description:** Role ka description

**Step 4:** Permissions select karein:
- Module-wise permissions dikhengi
- Checkbox se select karein jo permissions chahiye
- "Select All" / "Deselect All" buttons available hain

**Step 5:** "Create Role" button click karein

### 2. Role Edit Karna (Permissions Add/Remove)

**Step 1:** Settings → Role Management

**Step 2:** Role ke saamne "Role Editor" button click karein

**Step 3:** Permissions modify karein:
- Check/uncheck permissions
- Role name aur description bhi edit kar sakte hain

**Step 4:** "Update Role" button click karein

### 3. User ko Role Assign Karna

**Method 1: User Edit Page se**
- Settings → User Management
- User ke saamne "Edit" button click karein
- "Role" dropdown se role select karein
- "Update User" button click karein

**Method 2: Employee ko Role Assign Karna**
- Employee → Employee List
- Employee ke saamne actions se "Assign Role" option
- Ya direct: Employee → Assign Role to Employee
- Employee aur Role select karein
- "Assign Role" button click karein

### 4. Permission Create Karna

**Step 1:** Settings → Permission Setup

**Step 2:** "Add Permission" button click karein

**Step 3:** Form fill karein:
- **Permission Code:** Uppercase with underscores (e.g., `EMPLOYEE_DELETE`)
- **Permission Name:** Display name (e.g., `Delete Employee`)
- **Module:** Module name (e.g., `employee`, `payroll`)
- **Description:** Optional description

**Step 4:** "Create Permission" button click karein

## Available Permissions

### Employee Module
- `EMPLOYEE_VIEW` - View employees
- `EMPLOYEE_CREATE` - Create employee
- `EMPLOYEE_EDIT` - Edit employee
- `EMPLOYEE_DELETE` - Delete employee
- `EMPLOYEE_ROLE_ASSIGN` - Assign role to employee

### Attendance Module
- `ATTENDANCE_VIEW` - View attendance
- `ATTENDANCE_CREATE` - Create attendance
- `ATTENDANCE_EDIT` - Edit attendance
- `ATTENDANCE_DELETE` - Delete attendance

### Leave Module
- `LEAVE_VIEW` - View leaves
- `LEAVE_CREATE` - Create leave
- `LEAVE_APPROVE` - Approve leave
- `LEAVE_REJECT` - Reject leave

### Payroll Module
- `PAYROLL_VIEW` - View payroll
- `PAYROLL_CREATE` - Create payroll
- `PAYROLL_CALCULATE` - Calculate payroll
- `PAYROLL_APPROVE` - Approve payroll
- `PAYROLL_LOCK` - Lock payroll

### Reports Module
- `REPORTS_VIEW` - View reports

### Settings Module
- `SETTINGS_VIEW` - View settings
- `SETTINGS_EDIT` - Edit settings

### User Management
- `USER_MANAGE` - Manage users

### Site Management
- `SITE_MANAGE` - Manage sites

### MIS Module
- `MIS_VIEW` - View MIS reports
- `MIS_CREATE` - Create MIS reports
- `MIS_EDIT` - Edit MIS reports
- `MIS_DELETE` - Delete MIS reports

## Code Usage

### Permission Check in PHP Code

```php
// Check if user has permission
if (hasPermission('EMPLOYEE_VIEW')) {
    // Show employee list
}

// Require permission (redirects if not available)
requirePermission('EMPLOYEE_CREATE');
```

### Role Check in PHP Code

```php
// Check if user is Super Admin
if (isSuperAdmin()) {
    // Super admin code
}

// Check if user is HR Admin
if (isHRAdmin()) {
    // HR admin code
}

// Check if user is Employee
if (isEmployee()) {
    // Employee code
}
```

## Best Practices

1. **Role Naming:**
   - Role codes lowercase mein rakhein
   - Descriptive names use karein
   - Example: `branch_manager`, `department_head`

2. **Permission Naming:**
   - Permission codes uppercase mein rakhein
   - Format: `MODULE_ACTION`
   - Example: `EMPLOYEE_VIEW`, `PAYROLL_CREATE`

3. **Security:**
   - System roles (SUPER_ADMIN, HR_ADMIN) ko delete mat karein
   - Custom roles delete kar sakte hain agar koi user assign nahi hai
   - Always permission checks use karein sensitive operations ke liye

4. **Testing:**
   - Naya role create karne ke baad test karein
   - Different users ke saath login karke verify karein
   - Permissions properly work kar rahe hain ya nahi check karein

## Common Scenarios

### Scenario 1: Branch Manager Role Create Karna

1. Role create karein: `branch_manager`
2. Permissions assign karein:
   - `EMPLOYEE_VIEW`
   - `EMPLOYEE_EDIT`
   - `ATTENDANCE_VIEW`
   - `ATTENDANCE_CREATE`
   - `LEAVE_VIEW`
   - `LEAVE_APPROVE`
   - `REPORTS_VIEW`
3. Branch manager user ko yeh role assign karein

### Scenario 2: Accountant Role Create Karna

1. Role create karein: `accountant`
2. Permissions assign karein:
   - `PAYROLL_VIEW`
   - `PAYROLL_CREATE`
   - `PAYROLL_CALCULATE`
   - `REPORTS_VIEW`
3. Accountant user ko yeh role assign karein

### Scenario 3: Department Head Role Create Karna

1. Role create karein: `department_head`
2. Permissions assign karein:
   - `EMPLOYEE_VIEW`
   - `ATTENDANCE_VIEW`
   - `LEAVE_VIEW`
   - `LEAVE_APPROVE`
   - `REPORTS_VIEW`
3. Department head user ko yeh role assign karein

## Troubleshooting

### Issue: User ko permission nahi mil raha

**Solution:**
1. Check karein user ko role assign hai ya nahi
2. Check karein role mein permission hai ya nahi
3. Session refresh karein (logout/login)
4. Database mein directly check karein:
   ```sql
   SELECT p.permission_code 
   FROM permissions p
   INNER JOIN role_permissions rp ON p.permission_id = rp.permission_id
   INNER JOIN users u ON rp.role_id = u.role_id
   WHERE u.user_id = [USER_ID];
   ```

### Issue: Role delete nahi ho raha

**Solution:**
- Check karein koi user ko yeh role assign hai ya nahi
- Agar hai to pehle un users ko different role assign karein
- Phir role delete kar sakte hain

### Issue: Permission check kaam nahi kar raha

**Solution:**
1. Check karein `hasPermission()` function properly call ho raha hai
2. Session mein permissions load ho rahe hain ya nahi check karein
3. Permission code exactly match karta hai ya nahi verify karein (case-sensitive)

## Support

Agar koi issue ho to:
1. Error logs check karein: `error_log` files
2. Database queries verify karein
3. Session data check karein

## Important Notes

- **Existing code break nahi hoga** - Sabhi existing functions aur code kaam karte rahenge
- **Backward compatible** - Purane code ke saath compatible hai
- **Flexible** - Aap easily custom roles aur permissions add kar sakte hain
- **Secure** - Proper permission checks har jagah implement kiye gaye hain

