upskill-event-manager/docs/role-implementation-plan.md

# HVAC Trainer Role Implementation Plan

## Overview
This document outlines the plan for implementing the `hvac_trainer` role in the HVAC Community Events plugin, ensuring proper integration with WordPress core and The Events Calendar plugin suite.

## Requirements Analysis

The `hvac_trainer` role needs to:
1. Allow trainers to manage their own events using The Events Calendar
2. Restrict access to WordPress admin areas
3. Provide custom capabilities for HVAC-specific features
4. Integrate with The Events Calendar's event management capabilities

## Implementation Architecture

```mermaid
classDiagram
    class HVAC_Community_Events {
        +activate()
        +deactivate()
        +init()
    }
    
    class HVAC_Roles {
        +create_trainer_role()
        +remove_trainer_role()
        +get_trainer_capabilities()
        +check_trainer_capability(capability)
    }
    
    class HVAC_Registration {
        +create_trainer_account(data)
    }
    
    HVAC_Community_Events --> HVAC_Roles : includes/initializes
    HVAC_Registration --> HVAC_Roles : uses capabilities
```

## Detailed Implementation Steps

### 1. Create Role Management Class
We will create a new file `class-hvac-roles.php` with the following functionality:

```php
class HVAC_Roles {
    /**
     * Create the hvac_trainer role
     */
    public function create_trainer_role() {
        // Check if role already exists
        if (get_role('hvac_trainer')) {
            return;
        }
        
        // Add the role with basic capabilities
        add_role(
            'hvac_trainer',
            __('HVAC Trainer', 'hvac-community-events'),
            $this->get_trainer_capabilities()
        );
    }
    
    /**
     * Remove the hvac_trainer role
     */
    public function remove_trainer_role() {
        remove_role('hvac_trainer');
    }
    
    /**
     * Get all capabilities for the hvac_trainer role
     */
    public function get_trainer_capabilities() {
        // Default capabilities
        $caps = array(
            'read' => true,
            'upload_files' => true,
            
            // Custom HVAC capabilities
            'manage_hvac_events' => true,
            'edit_hvac_profile' => true,
            'view_hvac_dashboard' => true,
            'manage_attendees' => true,
            'email_attendees' => true,
            
            // Events Calendar capabilities
            'publish_tribe_events' => true,
            'edit_tribe_events' => true,
            'delete_tribe_events' => true,
            'edit_published_tribe_events' => true,
            'delete_published_tribe_events' => true,
            'read_private_tribe_events' => true,
        );
        
        // Restrict access to admin areas
        $admin_caps = array(
            'manage_options', 
            'moderate_comments',
            'manage_categories',
            'manage_links',
            'edit_others_posts',
            'edit_pages',
            'edit_others_pages',
            'edit_published_pages',
            'publish_pages',
            'delete_pages',
            'delete_others_pages',
            'delete_published_pages',
            'delete_others_posts',
            'import',
            'export',
            'edit_theme_options',
        );
        
        foreach ($admin_caps as $cap) {
            $caps[$cap] = false;
        }
        
        return $caps;
    }
    
    /**
     * Check if current user has a specific HVAC trainer capability
     */
    public function check_trainer_capability($capability) {
        return current_user_can($capability);
    }
}
```

### 2. Update Main Plugin Class
We will modify `class-hvac-community-events.php` to:
- Include the new roles class
- Create the role during plugin activation
- Remove the role during plugin deactivation

```php
private function includes() {
    require_once HVAC_CE_PLUGIN_DIR . 'includes/class-hvac-roles.php';
    require_once HVAC_CE_PLUGIN_DIR . 'includes/class-hvac-registration.php';
}

public function activate() {
    // Create the hvac_trainer role
    $roles = new HVAC_Roles();
    $roles->create_trainer_role();
}

public function deactivate() {
    // Remove the hvac_trainer role
    $roles = new HVAC_Roles();
    $roles->remove_trainer_role();
}
```

### 3. Integration with Registration System
The registration system already assigns the 'hvac_trainer' role in the `create_trainer_account()` method, so no changes are needed there.

### 4. Admin Redirect for Trainers
To prevent trainers from accessing the WordPress admin area, we'll add a redirect:

```php
public function init() {
    // Prevent trainers from accessing wp-admin
    add_action('admin_init', array($this, 'redirect_trainers_from_admin'));
}

public function redirect_trainers_from_admin() {
    if (current_user_can('view_hvac_dashboard') && !current_user_can('manage_options')) {
        wp_redirect(home_url('/hvac-trainer-dashboard/'));
        exit;
    }
}
```

### 5. Testing the Implementation
To ensure the role works correctly, we'll:
1. Test role creation during plugin activation
2. Test trainer registration and role assignment
3. Verify trainer permissions with The Events Calendar
4. Test admin area restrictions
5. Test event creation, editing, and deletion capabilities

## Considerations and Potential Issues

1. **Plugin Dependencies**: The role's capabilities depend on The Events Calendar plugin. We should check if the plugin is active before adding its capabilities.

2. **Role Migration**: If the capabilities change in a future update, we'll need a mechanism to update existing roles.

3. **Role Conflict**: If a user already has the WordPress administrator role, adding the trainer role could cause confusion.

4. **Backward Compatibility**: Ensure compatibility with existing registered trainers if the role didn't previously exist.

## Implementation Timeline

1. Create `class-hvac-roles.php` - 1 hour
2. Update main plugin class - 30 minutes
3. Add admin redirect - 30 minutes
4. Testing and debugging - 2 hours

Total estimated time: 4 hours