# HVAC Trainer Role Migration Guide

**Date**: July 23, 2025  
**Issue**: Master dashboard not showing all HVAC trainers  
**Resolution**: Legacy role migration from `event_trainer` to `hvac_trainer`

---

## Problem Description

The master dashboard was only showing 4 out of 15 HVAC trainer users. Investigation revealed that 11 users had the legacy `event_trainer` role instead of the current `hvac_trainer` role.

### Root Cause
- Master dashboard code only queries for users with `hvac_trainer` and `hvac_master_trainer` roles
- 11 users had legacy `event_trainer` role from previous development
- These users were invisible to the master dashboard analytics

---

## Solution Summary

**Migration Process**: Convert all `event_trainer` users to `hvac_trainer` role

**Users Migrated**:
1. andys@genzryan.com
2. ben@tealmaker.com
3. david@hvacinstituteinc.com
4. dpetz@johnstonenjpa.com
5. eric.energy@gmail.com
6. Greg.a.kula@gmail.com
7. hhr.handc@gmail.com
8. janderson@sila.com
9. mnantel@republicsupplyco.com
10. rigobertohugo19 (info103@noreply0.com)
11. thoffmaster@hoffmastermechanical.com

---

## Migration Script

The migration was performed using `migrate-event-trainers.sh`:

```bash
#!/bin/bash
# Migration script: migrate-event-trainers.sh

# For each event_trainer user:
wp user remove-role "$username" event_trainer
wp user add-role "$username" hvac_trainer
```

### Verification Commands

```bash
# Check role counts before migration
wp user list --role=event_trainer --format=count
wp user list --role=hvac_trainer --format=count

# Perform migration
./migrate-event-trainers.sh

# Verify migration completed
wp user list --role=event_trainer --format=count  # Should be 0
wp user list --role=hvac_trainer --format=count   # Should be 14
```

---

## Results

### Before Migration
- **HVAC Trainers**: 3 users
- **Event Trainers**: 11 users (invisible to master dashboard)
- **Master Dashboard**: Showed 4 total trainers

### After Migration
- **HVAC Trainers**: 14 users ✅
- **HVAC Master Trainers**: 3 users ✅
- **Event Trainers**: 0 users ✅
- **Master Dashboard**: Shows 15 total trainers ✅

### Master Dashboard Statistics
- **Total Trainers**: 15 (increased from 4)
- **Total Events**: 16 events across all trainers
- **Complete Analytics**: All trainer data now visible
- **Legacy Cleanup**: All `event_trainer` role artifacts removed

---

## Prevention

To prevent similar issues in the future:

1. **Consistent Role Naming**: Always use `hvac_trainer` for trainer users
2. **Role Verification**: Check user roles during testing
3. **Master Dashboard Testing**: Verify all trainers appear in analytics
4. **Migration Scripts**: Keep role migration scripts for future use

---

## Testing Verification

**Master Dashboard Query Test**:
```php
$trainer_users = get_users(array(
    'role__in' => array('hvac_trainer', 'hvac_master_trainer'),
    'fields' => 'ID'
));
// Should return 15 users after migration
```

**Master Dashboard Access**:
- Login as master trainer: joe@measurequick.com
- Navigate to: `/master-trainer/dashboard/`
- Verify: 15 trainers visible in analytics
- Confirm: All trainer statistics display correctly

---

## Files Modified

1. **Migration Script**: `migrate-event-trainers.sh` (created)
2. **Verification Script**: `verify-master-dashboard-data.sh` (created)
3. **Documentation**: `CLAUDE.md` (updated with fix details)
4. **Documentation**: `README.md` (updated user counts)

---

## Deployment Notes

- **Code Changes**: No code changes required (only data migration)
- **Database Changes**: User role metadata updated
- **Cache Clearing**: Automatic via deployment script
- **Verification**: Master dashboard functionality confirmed

The migration resolved the issue completely and all HVAC trainers are now properly visible in the master dashboard analytics.