# Permission Management System
**Date**: November 24, 2024  
**Version**: 2.0

## Overview

The Permission Management System has been completely overhauled to solve two critical problems:

1. **Keeping permissions synced** with actual controller usage
2. **Organizing permissions** in a hierarchical, maintainable structure

## What Was Implemented

### 1. Permission Scanner (`scripts/scan_permissions.php`)

Automatically scans all controllers for `checkPermission()` calls and syncs with the database.

**Features:**
- Discovers all permissions used in controllers
- Auto-creates missing permissions
- Reports unused permissions (those in DB but not used)
- Provides coverage statistics
- Exports scan results to JSON

**Usage:**
```bash
# Dry run (preview only)
php scripts/scan_permissions.php

# Apply changes to database
php scripts/scan_permissions.php --live

# Export results to JSON
php scripts/scan_permissions.php --export
```

**Output includes:**
- List of all discovered permissions
- Missing permissions (in code but not in DB)
- Unused permissions (in DB but not in code)
- Coverage percentage
- Permissions by module breakdown

### 2. Hierarchical Permission Groups (Database)

**Migration**: `database/migrations/081_permission_groups.sql`

**New Tables:**
- `permission_groups` - Hierarchical group structure
  - Supports parent/child relationships
  - Display order for sorting
  - Icons and colors for visual distinction
  - System flag for protected groups

**Columns Added:**
- `permissions.group_id` - Links permissions to groups

**Default Groups Created:**
```
📱 App Grid (Quick Access)      [Level 0 - Success color]
🏢 Departments                    [Level 0 - Primary color]
   ├─ 🧮 Accounting
   ├─ 👥 CRM
   ├─ 👤 HR
   ├─ 📦 Inventory
   ├─ ⚙️ Manufacturing
   ├─ 🛒 Purchases
   └─ 📈 Sales
🛠️ Tools                          [Level 0 - Info color]
   ├─ 📄 Documents
   ├─ 🎧 Help Desk
   ├─ 📋 Projects
   └─ 📊 Reports
🔒 Administration                [Level 0 - Danger color]
   ├─ ⚙️ Settings & System
   ├─ 🛡️ Security
   └─ 📢 Announcements
```

**View Created:**
- `vw_permission_groups_hierarchy` - Recursive CTE for easy hierarchy queries

### 3. Permission Group Manager

**New Files:**
- `models/PermissionGroup.php` - Model for group operations
- `controllers/PermissionGroupController.php` - CRUD controller
- `views/permission_groups/index.php` - Hierarchical list view
- `views/permission_groups/edit.php` - Edit with permission assignment

**Routes Added:**
- `GET /permission-groups` - List all groups
- `GET /permission-groups/create` - Create form
- `POST /permission-groups/store` - Save new group
- `GET /permission-groups/{id}` - View details
- `GET /permission-groups/{id}/edit` - Edit form
- `POST /permission-groups/{id}/update` - Update group
- `POST /permission-groups/{id}/delete` - Delete group
- `POST /permission-groups/{id}/assign-permissions` - Assign permissions (AJAX)
- `POST /permission-groups/reorder` - Reorder groups (AJAX)

**Features:**
- Create nested permission groups
- Assign icons and colors to groups
- Drag-and-drop reordering (frontend ready)
- Bulk permission assignment via modal
- Protected system groups cannot be deleted
- Circular reference prevention

### 4. Enhanced Role Editor

**Updated Files:**
- `controllers/RoleController.php` - Now loads permission groups
- `views/roles/edit.php` - Uses dynamic hierarchical display

**Changes:**
- ❌ Removed hardcoded category arrays
- ✅ Dynamic loading from permission_groups table
- ✅ Shows permissions organized by groups
- ✅ Two-level hierarchy display (parent > children)
- ✅ "Ungrouped Permissions" section for unassigned perms
- ✅ "Manage Groups" button links to group manager
- ✅ Color-coded groups (success, primary, danger, etc.)
- ✅ Icons displayed for each group

## How It Works

### Permission Discovery Flow

1. **Scan Controllers**
   ```bash
   php scripts/scan_permissions.php
   ```

2. **Review Missing Permissions**
   - Scanner finds `checkPermission('module.action')` calls
   - Compares against `permissions` table
   - Lists missing permissions

3. **Auto-Create Missing** (with --live flag)
   - Generates descriptions automatically
   - Assigns to module based on naming
   - Leaves `group_id` as NULL initially

4. **Assign to Groups**
   - Go to `/permission-groups`
   - Edit relevant group
   - Click "Manage Permissions"
   - Select permissions to assign

### Role Permission Assignment Flow

1. **Navigate to Role Editor**
   - Go to `/roles`
   - Click "Edit" on any role

2. **Permission Display**
   - Shows hierarchical accordion
   - Top level: App Grid, Departments, Tools, Administration
   - Second level: Accounting, CRM, HR, etc.
   - Permissions grouped under their assigned group

3. **Select Permissions**
   - Check/uncheck individual permissions
   - Use "Toggle All" for entire group
   - "Select All" / "Deselect All" for everything

4. **Save**
   - Updates `role_permissions` table
   - User permissions update immediately

## Maintenance Workflow

### Adding New Controllers/Permissions

1. Developer adds `checkPermission('new.permission')` in controller
2. Run scanner:
   ```bash
   php scripts/scan_permissions.php --live
   ```
3. Go to `/permission-groups` and assign the new permission to appropriate group
4. Done! Permission now appears in role editor under that group

### Reorganizing Permissions

1. Go to `/permission-groups`
2. Edit group or create new sub-groups
3. Reassign permissions between groups
4. Changes reflect immediately in role editor

### Cleaning Up Unused Permissions

1. Run scanner:
   ```bash
   php scripts/scan_permissions.php
   ```
2. Review "Unused Permissions" section
3. Verify these aren't used in views or planned features
4. Manually delete from database if truly unused

## Database Schema

### permission_groups Table

| Column | Type | Description |
|--------|------|-------------|
| id | INT UNSIGNED | Primary key |
| name | VARCHAR(100) | Display name |
| parent_id | INT UNSIGNED | Parent group (NULL = top level) |
| display_order | INT | Sort order within parent |
| icon | VARCHAR(50) | Bootstrap icon class |
| color | VARCHAR(20) | Bootstrap color name |
| description | TEXT | Group description |
| is_system | BOOLEAN | Protected from deletion |

### permissions Table (Updated)

| Column | Type | Description |
|--------|------|-------------|
| id | INT UNSIGNED | Primary key |
| name | VARCHAR(100) | Permission key (e.g., crm.view) |
| module | VARCHAR(50) | Module name |
| **group_id** | **INT UNSIGNED** | **→ permission_groups.id** |
| description | VARCHAR(255) | Human-readable description |

## Benefits

### Before (Problems)

❌ Hardcoded categories in `roles/edit.php`  
❌ Manual permission addition to database  
❌ No way to know if permissions are used  
❌ Flat permission list difficult to navigate  
❌ Code/database drift over time

### After (Solutions)

✅ Dynamic groups from database  
✅ Auto-discovery via scanner  
✅ Coverage reporting and sync checking  
✅ Hierarchical, organized display  
✅ Automated sync between code and DB

## Example Scenarios

### Scenario 1: New Feature Added

Developer creates `ProcessingController`:
```php
public function index() {
    $this->checkPermission('processing.view');
    // ...
}

public function create() {
    $this->checkPermission('processing.create');
    // ...
}
```

**Steps:**
1. Run: `php scripts/scan_permissions.php --live`
2. Scanner creates:
   - `processing.view` - "View Processing"
   - `processing.create` - "Create Processing"
3. Go to `/permission-groups`
4. Edit "Manufacturing" group
5. Assign both permissions to Manufacturing
6. Done! Now visible in role editor under Manufacturing

### Scenario 2: Reorganizing Structure

You want to split "Accounting" into sub-groups:

1. Go to `/permission-groups`
2. Create new groups:
   - "Accounts Payable" (parent: Accounting)
   - "Accounts Receivable" (parent: Accounting)
   - "General Ledger" (parent: Accounting)
3. Edit each sub-group
4. Reassign permissions from Accounting to appropriate sub-group
5. Role editor now shows three-level hierarchy

### Scenario 3: Auditing Permissions

Before deployment, verify all permissions are synced:

```bash
php scripts/scan_permissions.php --export
```

Review `docs/permissions_scan_YYYY-MM-DD.json`:
- Check coverage percentage (should be near 100%)
- Review unused permissions list
- Ensure all discovered permissions are in database

## Configuration

### Permission Naming Convention

Format: `module.action`

**Examples:**
- `accounting.view`
- `crm.create`
- `hr.delete`
- `manufacturing.approve`

**Actions:**
- `view` - Read access
- `create` - Create new records
- `edit` - Modify existing records
- `delete` - Delete records
- `approve` - Approval workflow
- `export` - Export data
- `manage` - Full management access

### Group Color Coding

- **Success (Green)** - Essential/recommended permissions
- **Primary (Blue)** - Standard department modules
- **Info (Cyan)** - Tools and utilities
- **Danger (Red)** - Administrative/sensitive operations
- **Warning (Yellow)** - Caution required

## Troubleshooting

### Scanner shows missing permissions but they don't exist

**Cause**: Permission used in code but not in database  
**Solution**: Run with `--live` flag to auto-create

### Permissions not appearing in role editor

**Cause**: Permission has `group_id = NULL`  
**Solution**: Assign to group via `/permission-groups/{id}/edit`

### "Ungrouped Permissions" section too large

**Cause**: Many permissions not assigned to groups  
**Solution**: Bulk assign via permission group manager

### Cannot delete permission group

**Possible causes:**
1. Group has child groups (delete children first)
2. Group is system group (`is_system = 1`)
3. Group is referenced by permissions (unassign first)

## Future Enhancements

Potential improvements for v2.1:

1. **Drag-and-drop reordering** in group manager UI
2. **Permission templates** for common roles
3. **Bulk group operations** (merge, split, move)
4. **Permission dependencies** (if has X, must have Y)
5. **Scheduled scanner** runs (cron job)
6. **Permission usage analytics** (which are most/least used)
7. **Role comparison tool** (diff between roles)
8. **Permission inheritance** in group hierarchy

## Migration Notes

### Upgrading from v1.0

1. **Backup database** before running migration
2. Run migration: `mysql -u user -p db < migrations/081_permission_groups.sql`
3. Verify groups created: `SELECT * FROM permission_groups;`
4. Check permissions mapped: `SELECT COUNT(*) FROM permissions WHERE group_id IS NOT NULL;`
5. Run scanner to verify sync: `php scripts/scan_permissions.php`
6. Test role editor at `/roles/{id}/edit`

### Unmapped Permissions

After migration, ~30 permissions will be ungrouped. Assign these via:

1. Go to `/permission-groups`
2. Identify relevant group for each permission
3. Edit group and assign permissions
4. Verify in role editor

## Support

For questions or issues:

1. Check this documentation
2. Review code comments in:
   - `scripts/scan_permissions.php`
   - `models/PermissionGroup.php`
   - `controllers/PermissionGroupController.php`
3. Check database view: `SELECT * FROM vw_permission_groups_hierarchy;`

---

**Created**: November 24, 2024  
**Author**: Development Team  
**Version**: 2.0