Add models, enums, and services for user roles, theme preferences, slug history, and ID generation

2025-12-22 16:51:11 -05:00 · 2025-02-23 19:50:40 -05:00
parent 32aea21e48
commit 7e5d15eb46
55 changed files with 6462 additions and 4 deletions
--- a/memory-bank/features/AreaStatistics.md
+++ b/memory-bank/features/AreaStatistics.md
@@ -0,0 +1,216 @@
+# 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