# Manual Flight Time Override System - Implementation Guide

## Overview
This system allows administrators to manually override the automatically calculated flight start times for events. The system maintains backward compatibility and only affects the display when manual overrides are set.

## Files Created

### 1. Database Schema
- **`test-flight-times-schema.sql`** - SQL to create the EventFlightTimes table

### 2. Core System Files
- **`test-flight-time-manager.php`** - Main class for managing flight times
- **`test-event-participants.php`** - Test version of participants page with editing interface
- **`test-event-table.php`** - Test version of participants table using manual times
- **`test-event-start-sheet.php`** - Test version of start sheet using manual times
- **`test-event-scorecard.php`** - Test version of scorecard using manual times

## Installation Steps

### Step 1: Create Database Table
Run the SQL in `test-flight-times-schema.sql`:
```sql
CREATE TABLE IF NOT EXISTS `EventFlightTimes` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `EventId` int(11) NOT NULL,
  `flight` int(11) NOT NULL,
  `tee` int(11) NOT NULL DEFAULT 1,
  `manualStartTime` time NOT NULL,
  `isManualOverride` tinyint(1) NOT NULL DEFAULT 1,
  `createdAt` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP,
  `updatedAt` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `unique_event_flight_tee` (`EventId`, `flight`, `tee`),
  KEY `idx_event_flight` (`EventId`, `flight`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
```

### Step 2: Test the System
1. Navigate to `test-event-participants.php?EventId=YOUR_EVENT_ID`
2. You'll see a test banner indicating this is the test version
3. As an admin, you'll see flight time management controls
4. Test editing flight times and see the changes reflected

### Step 3: Verify Integration
- Check `test-event-start-sheet.php` to see manual times in start sheets
- Check `test-event-scorecard.php` to see manual times in scorecards
- Verify that manual overrides are clearly marked

## How It Works

### 1. Flight Time Manager Class
The `FlightTimeManager` class provides these key methods:
- `getFlightTime($flight, $tee)` - Gets time (manual override if exists, otherwise calculated)
- `setManualFlightTime($flight, $tee, $time)` - Sets a manual override
- `removeManualOverride($flight, $tee)` - Removes manual override
- `getAllManualOverrides()` - Gets all manual overrides for an event

### 2. Time Calculation Logic
The system maintains the existing calculation logic:
- **Pairs Events**: Groups flights in pairs (1&2, 3&4, etc.) with 9-minute intervals
- **Sequential Events**: 9-minute intervals between flights
- **Shotgun Starts**: All flights use the same start time
- **Dual Tee Events**: Tee 10 flights use secondary start time

### 3. Manual Override Priority
1. Check for manual override in `EventFlightTimes` table
2. If manual override exists, use that time
3. If no manual override, calculate using existing logic
4. Display appropriate indicators (MANUAL vs CALCULATED)

## User Interface

### Admin Controls
- **Time Input Fields**: Allow editing of individual flight times
- **Update Button**: Saves manual override
- **Revert Button**: Removes manual override (returns to calculated)
- **Visual Indicators**: Green boxes for manual overrides, yellow for calculated

### Display Indicators
- **Badges**: "MANUAL OVERRIDE" (green) vs "CALCULATED" (yellow)
- **Color Coding**: Green borders for manual, yellow for calculated
- **Summary Section**: Lists all manual overrides at bottom of pages

## Testing Checklist

### ✅ Basic Functionality
- [ ] Can set manual flight time override
- [ ] Can remove manual override (revert to calculated)
- [ ] Manual times display correctly in participants table
- [ ] Manual times display correctly in start sheet
- [ ] Manual times display correctly in scorecard
- [ ] Visual indicators work correctly

### ✅ Edge Cases
- [ ] Works with Pairs events
- [ ] Works with Shotgun starts
- [ ] Works with dual tee events
- [ ] Handles missing flight data gracefully
- [ ] Database constraints prevent duplicate entries

### ✅ Integration
- [ ] Doesn't break existing functionality
- [ ] Production files remain unchanged
- [ ] Admin-only access works correctly
- [ ] Time format validation works

## Production Implementation

### Phase 1: Database Setup
1. Run the SQL schema on production database
2. Test with a single event first

### Phase 2: Core Integration
1. Copy `test-flight-time-manager.php` to production
2. Update `event-table.php` to use FlightTimeManager
3. Update `event-start-sheet.php` to use FlightTimeManager
4. Update `event-scorecard.php` to use FlightTimeManager

### Phase 3: User Interface
1. Add flight time editing controls to `event-participants.php`
2. Add visual indicators throughout the system
3. Test thoroughly with real events

### Phase 4: Cleanup
1. Remove test files
2. Update documentation
3. Train administrators on new functionality

## Code Integration Examples

### In event-table.php
Replace the flight time calculation section with:
```php
include "flight-time-manager.php";
$flightTimeManager = new FlightTimeManager($conn, $EventId);

// Replace existing flight time calculation with:
$flightTime = $flightTimeManager->getFlightTime($flight, $tee);
$isManualOverride = $flightTimeManager->getManualFlightTime($flight, $tee) !== null;
```

### In event-start-sheet.php
Replace the flight time calculation section with:
```php
include "flight-time-manager.php";
$flightTimeManager = new FlightTimeManager($conn, $EventId);

// Replace existing flight time calculation with:
$flightTimes[$flight] = $flightTimeManager->getFlightTime($flight, $flightTee);
```

## Security Considerations

- Manual overrides are admin-only (checked via `$isAdmin`)
- All database operations use prepared statements
- Input validation on time format
- No direct database access from frontend

## Performance Considerations

- Database queries are optimized with proper indexes
- Flight time calculations are cached per request
- Minimal impact on existing performance

## Troubleshooting

### Common Issues
1. **Times not updating**: Check database connection and admin privileges
2. **Visual indicators not showing**: Verify CSS classes are applied correctly
3. **Database errors**: Check table exists and has proper permissions

### Debug Mode
Add this to any test file to see debug information:
```php
// Debug mode - remove in production
if (isset($_GET['debug'])) {
    echo "<pre>";
    print_r($flightTimeManager->getAllFlightTimes());
    echo "</pre>";
}
```

## Support

For issues or questions:
1. Check the test files first to verify functionality
2. Compare test vs production behavior
3. Check database logs for any errors
4. Verify admin privileges are working correctly