thrillwiki_laravel/memory-bank/features/AreaStatistics.md

# Area Statistics System

## Overview
The Area Statistics system provides comprehensive tracking and management of various metrics for park areas, including ride counts, visitor statistics, and historical data. This system enables data-driven insights and performance monitoring at both the area and park level.

## Database Structure

### Park Areas Table Statistics Fields
```sql
ALTER TABLE park_areas ADD (
    -- Ride statistics
    ride_count integer DEFAULT 0,
    coaster_count integer DEFAULT 0,
    flat_ride_count integer DEFAULT 0,
    water_ride_count integer DEFAULT 0,
    
    -- Visitor statistics
    daily_capacity integer NULL,
    peak_wait_time integer NULL,
    average_rating decimal(3,2) NULL,
    
    -- Historical data
    total_rides_operated integer DEFAULT 0,
    retired_rides_count integer DEFAULT 0,
    last_new_ride_added date NULL,
    
    -- Indexes
    INDEX idx_rides (park_id, ride_count),
    INDEX idx_coasters (park_id, coaster_count),
    INDEX idx_rating (park_id, average_rating)
);
```

## Components

### 1. HasAreaStatistics Trait
Located in `app/Traits/HasAreaStatistics.php`

Purpose:
- Provides statistics management functionality
- Handles calculations and formatting
- Manages data updates
- Tracks historical metrics

Features:
1. Ride Statistics
   - Total ride count
   - Type distribution
   - Coaster percentage
   - Historical tracking

2. Visitor Metrics
   - Daily capacity
   - Peak wait times
   - Average ratings
   - Formatted displays

3. Historical Data
   - Total rides operated
   - Retirement tracking
   - Last addition date
   - Retirement rate

## Implementation Details

### Ride Count Management
```php
public function updateRideCounts(array $counts): void
{
    $this->update([
        'ride_count' => $counts['total'] ?? 0,
        'coaster_count' => $counts['coasters'] ?? 0,
        'flat_ride_count' => $counts['flat_rides'] ?? 0,
        'water_ride_count' => $counts['water_rides'] ?? 0,
    ]);
}
```

### Visitor Statistics
```php
public function updateVisitorStats(
    int $dailyCapacity,
    int $peakWaitTime,
    float $rating
): void
{
    $this->update([
        'daily_capacity' => $dailyCapacity,
        'peak_wait_time' => $peakWaitTime,
        'average_rating' => round($rating, 2),
    ]);
}
```

### Historical Tracking
```php
public function recordNewRide(): void
{
    $this->increment('total_rides_operated');
    $this->update(['last_new_ride_added' => now()]);
}

public function recordRetirement(): void
{
    $this->increment('retired_rides_count');
}
```

## Display Features

### 1. Rating Display
- Star-based visualization (★★★☆☆)
- Numerical rating with one decimal
- "Not rated" fallback

### 2. Capacity Display
- Formatted numbers with commas
- "riders/day" unit
- Unknown capacity handling

### 3. Wait Time Display
- Minutes format
- Peak time indication
- Unknown time handling

## Data Analysis

### 1. Distribution Analysis
```php
public function getRideDistributionAttribute(): array
{
    return [
        'coasters' => $this->coaster_count ?? 0,
        'flat_rides' => $this->flat_ride_count ?? 0,
        'water_rides' => $this->water_ride_count ?? 0,
    ];
}
```

### 2. Historical Analysis
```php
public function getHistoricalStatsAttribute(): array
{
    return [
        'total_operated' => $this->total_rides_operated,
        'retired_count' => $this->retired_rides_count,
        'last_addition' => $this->last_new_ride_added?->format('M Y'),
        'retirement_rate' => $this->getRetirementRate(),
    ];
}
```

## Performance Optimization

### 1. Database Indexes
- Compound indexes for common queries
- Efficient sorting support
- Quick statistical lookups

### 2. Caching Strategy
- [ ] Implement statistics caching
- [ ] Add cache invalidation rules
- [ ] Set up cache warming

## Future Enhancements
1. [ ] Add seasonal statistics
2. [ ] Implement trend analysis
3. [ ] Add capacity forecasting
4. [ ] Create statistical reports
5. [ ] Add comparison tools
6. [ ] Implement benchmarking
7. [ ] Add historical graphs
8. [ ] Create export functionality

## Integration Points
1. Park Model
   - Area statistics rollup
   - Park-wide metrics
   - Comparative analysis

2. Rides System
   - Automatic count updates
   - Type classification
   - Capacity calculation

3. Visitor System
   - Wait time tracking
   - Rating collection
   - Capacity monitoring

## Security Considerations
1. Data Validation
   - Range checks
   - Type validation
   - Update authorization

2. Access Control
   - Statistics visibility
   - Update permissions
   - Export restrictions

## Testing Strategy
1. Unit Tests
   - [ ] Calculation accuracy
   - [ ] Format handling
   - [ ] Edge cases

2. Integration Tests
   - [ ] Update operations
   - [ ] Rollup functionality
   - [ ] Cache invalidation

3. Performance Tests
   - [ ] Large dataset handling
   - [ ] Update efficiency
   - [ ] Query optimization