Add enums for ReviewStatus, TrackMaterial, LaunchType, RideCategory, and RollerCoasterType; implement Designer and RideModel models; create migrations for ride_models and helpful_votes tables; enhance RideGalleryComponent documentation

2025-12-20 08:11:10 -05:00 · 2025-02-25 20:37:19 -05:00
parent 8951e59f49
commit 64b0e90a27
35 changed files with 3157 additions and 1 deletions
--- a/memory-bank/models/ReviewModels.md
+++ b/memory-bank/models/ReviewModels.md
@@ -0,0 +1,101 @@
+# Review System Models
+
+## Review Model
+Represents user reviews for rides in the system.
+
+### Properties
+- `id` (int) - Primary key
+- `ride_id` (int) - Foreign key to rides table
+- `user_id` (int) - Foreign key to users table
+- `rating` (int) - Rating from 1 to 5
+- `title` (string, nullable) - Optional review title
+- `content` (text) - Review content
+- `status` (enum) - ReviewStatus enum value
+- `moderated_at` (timestamp) - When review was moderated
+- `moderated_by` (int) - Foreign key to users table (moderator)
+- `helpful_votes_count` (int) - Counter cache for helpful votes
+
+### Relationships
+- `ride` - BelongsTo relationship to Ride model
+- `user` - BelongsTo relationship to User model
+- `moderator` - BelongsTo relationship to User model
+- `helpfulVotes` - HasMany relationship to HelpfulVote model
+
+### Scopes
+- `pending()` - Reviews awaiting moderation
+- `approved()` - Approved reviews
+- `rejected()` - Rejected reviews
+- `byRide()` - Filter by ride
+- `byUser()` - Filter by user
+
+### Methods
+- `approve()` - Approve the review
+- `reject()` - Reject the review
+- `moderate()` - General moderation method
+- `toggleHelpfulVote()` - Toggle helpful vote from a user
+
+## HelpfulVote Model
+Represents users marking reviews as helpful.
+
+### Properties
+- `id` (int) - Primary key
+- `review_id` (int) - Foreign key to reviews table
+- `user_id` (int) - Foreign key to users table
+- `created_at` (timestamp) - When vote was cast
+
+### Relationships
+- `review` - BelongsTo relationship to Review model
+- `user` - BelongsTo relationship to User model
+
+### Methods
+- `toggle()` - Toggle vote status
+
+## Database Considerations
+
+### Indexes
+1. Reviews Table:
+   - Primary Key: id
+   - Foreign Keys: ride_id, user_id, moderated_by
+   - Composite: [ride_id, user_id] (unique)
+   - Indexes: [ride_id, status], [user_id, created_at], status
+
+2. Helpful Votes Table:
+   - Primary Key: id
+   - Foreign Keys: review_id, user_id
+   - Composite: [review_id, user_id] (unique)
+   - Indexes: [user_id, created_at]
+
+### Constraints
+1. Reviews:
+   - One review per ride per user
+   - Rating must be between 1 and 5
+   - Status must be valid enum value
+   - Content is required
+
+2. Helpful Votes:
+   - One vote per review per user
+   - Cascading deletes with review
+
+## Usage Examples
+
+```php
+// Create a review
+$review = Review::create([
+    'ride_id' => $ride->id,
+    'user_id' => Auth::id(),
+    'rating' => 5,
+    'title' => 'Great ride!',
+    'content' => 'This was amazing...',
+]);
+
+// Toggle helpful vote
+$review->toggleHelpfulVote(Auth::id());
+
+// Moderate a review
+$review->moderate(ReviewStatus::APPROVED, Auth::id());
+
+// Get ride's approved reviews
+$reviews = $ride->reviews()->approved()->latest()->get();
+
+// Get user's helpful votes
+$votes = $user->helpfulVotes()->with('review')->get();
--- a/memory-bank/models/RideEnums.md
+++ b/memory-bank/models/RideEnums.md
@@ -0,0 +1,97 @@
+# Ride System Enums Documentation
+
+## Overview
+The Rides system uses several enum classes to maintain consistent data and provide type safety for various ride attributes. All enums follow a consistent pattern with common helper methods for values, labels, and options.
+
+## Implementation Details
+
+### 1. RideCategory
+- **Purpose**: Categorizes different types of rides
+- **Location**: `app/Enums/RideCategory.php`
+- **Values**:
+  - `SELECT` (''): Default selection prompt
+  - `ROLLER_COASTER` ('RC'): Roller coasters
+  - `DARK_RIDE` ('DR'): Dark rides
+  - `FLAT_RIDE` ('FR'): Flat rides
+  - `WATER_RIDE` ('WR'): Water rides
+  - `TRANSPORT` ('TR'): Transport rides
+  - `OTHER` ('OT'): Other ride types
+
+### 2. RideStatus
+- **Purpose**: Tracks operational status of rides
+- **Location**: `app/Enums/RideStatus.php`
+- **Values**:
+  - `SELECT` (''): Default selection prompt
+  - `OPERATING`: Currently operating
+  - `CLOSED_TEMP`: Temporarily closed
+  - `SBNO`: Standing but not operating
+  - `CLOSING`: Scheduled for closure
+  - `CLOSED_PERM`: Permanently closed
+  - `UNDER_CONSTRUCTION`: Under construction
+  - `DEMOLISHED`: Demolished
+  - `RELOCATED`: Relocated
+- **Features**:
+  - Includes post-closing status handling
+  - Helper methods for filtering post-closing statuses
+
+### 3. TrackMaterial
+- **Purpose**: Specifies roller coaster track material
+- **Location**: `app/Enums/TrackMaterial.php`
+- **Values**:
+  - `STEEL`: Steel tracks
+  - `WOOD`: Wooden tracks
+  - `HYBRID`: Hybrid construction
+
+### 4. RollerCoasterType
+- **Purpose**: Defines specific roller coaster configurations
+- **Location**: `app/Enums/RollerCoasterType.php`
+- **Values**:
+  - `SITDOWN`: Traditional sit-down coaster
+  - `INVERTED`: Inverted coaster
+  - `FLYING`: Flying coaster
+  - `STANDUP`: Stand-up coaster
+  - `WING`: Wing coaster
+  - `DIVE`: Dive coaster
+  - `FAMILY`: Family coaster
+  - `WILD_MOUSE`: Wild Mouse style
+  - `SPINNING`: Spinning coaster
+  - `FOURTH_DIMENSION`: 4th Dimension coaster
+  - `OTHER`: Other configurations
+
+### 5. LaunchType
+- **Purpose**: Specifies ride launch mechanism
+- **Location**: `app/Enums/LaunchType.php`
+- **Values**:
+  - `CHAIN`: Traditional chain lift
+  - `LSM`: Linear Synchronous Motor launch
+  - `HYDRAULIC`: Hydraulic launch system
+  - `GRAVITY`: Gravity-powered launch
+  - `OTHER`: Other launch types
+
+## Common Features
+All enum classes include:
+1. String-backed values for database storage
+2. Human-readable labels via `label()` method
+3. Helper methods:
+   - `values()`: Get all enum values
+   - `labels()`: Get all human-readable labels
+   - `options()`: Get value-label pairs for forms
+
+## Usage Notes
+1. All enums maintain exact parity with Django choices
+2. Used in models for type validation
+3. Support form select options generation
+4. Enable consistent validation rules
+5. Provide clean database values
+
+## Design Decisions
+1. Used PHP 8.1 enum feature for type safety
+2. Maintained consistent method names across all enums
+3. Added helper methods to simplify form handling
+4. Included blank/select options where needed
+5. Used string backing for database compatibility
+
+## Related Files
+- `app/Models/Ride.php` (uses RideCategory, RideStatus)
+- `app/Models/RollerCoasterStats.php` (uses TrackMaterial, RollerCoasterType, LaunchType)
+- Future Livewire components for ride forms
--- a/memory-bank/models/RideModels.md
+++ b/memory-bank/models/RideModels.md
@@ -0,0 +1,141 @@
+# Ride System Models Documentation
+
+## Overview
+The rides system is implemented through a set of interconnected Eloquent models that handle different aspects of ride management. The implementation maintains feature parity with the Django original while leveraging Laravel's conventions and features.
+
+## Model Structure
+
+### RideModel
+- **Purpose**: Templates for specific ride types/products
+- **Key Features**:
+  - Manufacturer relationship
+  - Category type from RideCategory enum
+  - Has many Rides
+  - Full name accessor for manufacturer + model name
+- **File**: `app/Models/RideModel.php`
+
+### Ride
+- **Purpose**: Individual ride installations at parks
+- **Key Features**:
+  - Complex relationships to:
+    - Park (required)
+    - ParkArea (optional)
+    - Manufacturer (optional)
+    - Designer (optional)
+    - RideModel (optional)
+    - RollerCoasterStats (optional one-to-one)
+  - Status tracking with dates
+  - Automatic slug generation
+  - Type safety through enums
+- **File**: `app/Models/Ride.php`
+
+### RollerCoasterStats
+- **Purpose**: Extended statistics for roller coaster type rides
+- **Key Features**:
+  - One-to-one relationship with Ride
+  - Physical measurements with decimal precision
+  - Track material and type enums
+  - Train configuration tracking
+  - Total seats calculation
+- **File**: `app/Models/RollerCoasterStats.php`
+
+### Designer
+- **Purpose**: Track ride designers and their work
+- **Key Features**:
+  - Basic information storage
+  - Automatic slug generation
+  - Has many relationship to rides
+- **File**: `app/Models/Designer.php`
+
+## Key Design Decisions
+
+### 1. Type Safety
+- Used PHP 8.1 enums for all constrained choices:
+  - RideCategory
+  - RideStatus
+  - TrackMaterial
+  - RollerCoasterType
+  - LaunchType
+
+### 2. Data Integrity
+- Proper foreign key constraints
+- Appropriate nullOnDelete vs cascadeOnDelete choices
+- Unique constraints where needed
+
+### 3. Automatic Features
+- Slug generation on model creation
+- Proper cast declarations for:
+  - Dates
+  - Decimals
+  - Enums
+  - Integers
+
+### 4. Optimization Choices
+- No timestamps on RollerCoasterStats (reduces overhead)
+- Appropriate indexes on foreign keys
+- Efficient relationships setup
+
+### 5. Laravel Conventions
+- Followed naming conventions
+- Used protected properties for configurations
+- Proper method return type declarations
+- Relationship method naming
+
+## Usage Examples
+
+### Creating a New Ride
+```php
+$ride = Ride::create([
+    'name' => 'Thunderbolt',
+    'park_id' => $park->id,
+    'category' => RideCategory::ROLLER_COASTER,
+    'status' => RideStatus::OPERATING,
+]);
+```
+
+### Adding Roller Coaster Stats
+```php
+$ride->coasterStats()->create([
+    'height_ft' => 120.5,
+    'track_material' => TrackMaterial::STEEL,
+    'roller_coaster_type' => RollerCoasterType::SITDOWN,
+]);
+```
+
+### Getting Ride with All Relations
+```php
+$ride = Ride::with([
+    'park',
+    'parkArea',
+    'manufacturer',
+    'designer',
+    'rideModel',
+    'coasterStats',
+])->find($id);
+```
+
+## Relationship Maps
+
+### RideModel
+- ← belongs to → Manufacturer
+- ← has many → Ride
+
+### Ride
+- ← belongs to → Park
+- ← belongs to → ParkArea
+- ← belongs to → Manufacturer
+- ← belongs to → Designer
+- ← belongs to → RideModel
+- ← has one → RollerCoasterStats
+
+### RollerCoasterStats
+- ← belongs to → Ride
+
+### Designer
+- ← has many → Ride
+
+## Future Enhancements
+1. Add review relationships
+2. Implement photo relationships
+3. Add history tracking
+4. Consider adding composite indexes for common queries
--- a/memory-bank/models/RidesSchema.md
+++ b/memory-bank/models/RidesSchema.md
@@ -0,0 +1,107 @@
+# Rides System Database Schema
+
+## Overview
+The rides system uses three primary tables to manage ride data:
+1. `ride_models` - Templates for specific ride types/models
+2. `rides` - Individual ride installations at parks
+3. `roller_coaster_stats` - Extended statistics for roller coasters
+
+## Implementation Details
+
+### Migration Files
+- `2024_02_25_194500_create_ride_models_table.php`
+- `2024_02_25_194600_create_rides_table.php`
+- `2024_02_25_194700_create_roller_coaster_stats_table.php`
+
+### RideModels Table
+- Primary key: `id`
+- Base information:
+  - `name`: string, required
+  - `description`: text, default empty
+  - `category`: string(2), using RideCategory enum
+- Relationships:
+  - `manufacturer_id`: nullable foreign key to manufacturers
+- Constraints:
+  - Unique combination of manufacturer_id and name
+  - Manufacturer can be null (for generic models)
+
+### Rides Table
+- Primary key: `id`
+- Base information:
+  - `name`: string, required
+  - `slug`: string, required
+  - `description`: text, default empty
+- Relationships:
+  - `park_id`: required foreign key to parks
+  - `park_area_id`: nullable foreign key to park_areas
+  - `manufacturer_id`: nullable foreign key to manufacturers
+  - `designer_id`: nullable foreign key to designers
+  - `ride_model_id`: nullable foreign key to ride_models
+- Status fields:
+  - `category`: string(2), RideCategory enum
+  - `status`: string(20), RideStatus enum
+  - `post_closing_status`: string(20), nullable
+  - `status_since`: date, nullable
+- Operational dates:
+  - `opening_date`: date, nullable
+  - `closing_date`: date, nullable
+- Physical characteristics:
+  - `min_height_in`: unsigned integer, nullable
+  - `max_height_in`: unsigned integer, nullable
+  - `capacity_per_hour`: unsigned integer, nullable
+  - `ride_duration_seconds`: unsigned integer, nullable
+- User interaction:
+  - `average_rating`: decimal(3,2), nullable
+- Timestamps: `created_at`, `updated_at`
+- Indexes:
+  - Unique: [park_id, slug]
+  - Regular: category, status, manufacturer_id, designer_id, ride_model_id
+
+### RollerCoasterStats Table
+- Primary key: `id`
+- Relationship:
+  - `ride_id`: unique foreign key to rides (one-to-one)
+- Physical measurements:
+  - `height_ft`: decimal(6,2), nullable
+  - `length_ft`: decimal(7,2), nullable
+  - `speed_mph`: decimal(5,2), nullable
+  - `max_drop_height_ft`: decimal(6,2), nullable
+- Track details:
+  - `inversions`: unsigned integer, default 0
+  - `ride_time_seconds`: unsigned integer, nullable
+  - `track_type`: string, default empty
+  - `track_material`: string(20), using TrackMaterial enum
+  - `roller_coaster_type`: string(20), using RollerCoasterType enum
+- Train configuration:
+  - `launch_type`: string(20), using LaunchType enum
+  - `train_style`: string, default empty
+  - `trains_count`: unsigned integer, nullable
+  - `cars_per_train`: unsigned integer, nullable
+  - `seats_per_car`: unsigned integer, nullable
+- Indexes:
+  - track_material
+  - roller_coaster_type
+  - launch_type
+
+## Design Decisions
+1. Used one-to-one relationship for roller_coaster_stats to ensure data integrity
+2. Added proper indexes for common query patterns
+3. Implemented nullable relationships where appropriate
+4. Used appropriate data types for numeric values:
+   - decimals for measurements that need precision
+   - integers for whole number counts
+5. Added proper cascading rules:
+   - rides cascade delete with park
+   - roller_coaster_stats cascade with ride
+   - other relationships set to nullOnDelete for safety
+
+## Migration Order
+The migrations are ordered to respect foreign key constraints:
+1. ride_models (depends on manufacturers)
+2. rides (depends on parks, park_areas, manufacturers, designers, ride_models)
+3. roller_coaster_stats (depends on rides)
+
+## Related Files
+- Enum classes in app/Enums/
+- Model classes (to be implemented)
+- Feature documentation in memory-bank/features/RidesManagement.md