Merge branch 'catch-em-all-rework'

Author: TLTimeplex

CATCH.md

@@ -1,11 +1,13 @@
 # Fursuit Catch-Em-All Game System Documentation
 
 ## System Overview
+
 The Catch-Em-All system is a **mobile-first gamified web app** for furry conventions. Fursuiters wear badges with unique 5-character codes, and attendees can "catch" them by entering these codes into the game, similar to a scavenger hunt with rarity levels, achievements, and leaderboards.
 
 ## New Architecture (2025 Redesign)
 
 ### Domain-Driven Design Structure
+
 ```
 app/Domain/CatchEmAll/
 ├── Controllers/GameController.php      # Main game logic
@@ -22,69 +24,78 @@ app/Domain/CatchEmAll/
 ```
 
 ### Database Tables
-- `user_catches` - Individual catches with **points_earned** field
-- `user_achievements` - Achievement progress and completion tracking
-- `user_catch_logs` - All catch attempts (includes anti-cheat detection)
-- `fursuits` - Fursuit records with `catch_em_all` boolean flag
-- `events` - Events with `catch_em_all_enabled` flag
+
+-   `user_achievements` - Achievement progress and completion tracking
+-   `user_catch_logs` - All catch attempts (includes anti-cheat detection)
+-   `fursuits` - Fursuit records with `catch_em_all` boolean flag
+-   `events` - Events with `catch_em_all_enabled` flag
 
 ### Game Features
-- **Rarity System**: Species are categorized as Common (1pt) → Uncommon (2pts) → Rare (5pts) → Epic (10pts) → Legendary (25pts)
-- **Achievement System**: 10 different achievements including Legendary Master, Speed Demon, Social Butterfly
-- **Mobile App Interface**: Bottom navigation with YouTube-style tab layout, Lucide icons, no emojis
-- **Tab-Based Navigation**: Leaderboard, Achievements, **Catch!** (center), Collection, Profile
-- **Real-time Progress**: Live stats, collection tracking, and leaderboard updates
-- **Anti-Cheat**: Automated detection of suspicious behavior patterns
+
+-   **Rarity System**: Species are categorized as Common (1pt) → Uncommon (2pts) → Rare (5pts) → Epic (10pts) → Legendary (25pts)
+-   **Achievement System**: 10 different achievements including Legendary Master, Speed Demon, Social Butterfly
+-   **Mobile App Interface**: Bottom navigation with YouTube-style tab layout, Lucide icons, no emojis
+-   **Tab-Based Navigation**: Leaderboard, Achievements, **Catch!** (center), Collection, Profile
+-   **Real-time Progress**: Live stats, collection tracking, and leaderboard updates
+-   **Anti-Cheat**: Automated detection of suspicious behavior patterns
 
 ### Routes (`/fcea/`)
-- `GET /` - Main game interface (`fcea.game`)
-- `POST /catch` - Submit catch code (`fcea.catch`)
-- `GET /collection` - Detailed collection view (`fcea.collection`)
-- `GET /achievements` - Achievement progress (`fcea.achievements`)
+
+-   `GET /` - Main game interface (`fcea.game`)
+-   `POST /catch` - Submit catch code (`fcea.catch`)
+-   `GET /collection` - Detailed collection view (`fcea.collection`)
+-   `GET /achievements` - Achievement progress (`fcea.achievements`)
 
 ### UI/UX Design (2025 Mobile-First Redesign)
 
 **Mobile App Navigation**:
-- **Bottom Tab Bar**: Fixed navigation like YouTube/Instagram with 5 tabs
-- **Central Catch Button**: Prominent, elevated with gradient background
-- **Lucide Icons**: Professional icon set instead of emojis
-- **Tab States**: Active tabs show colored background and icons
+
+-   **Bottom Tab Bar**: Fixed navigation like YouTube/Instagram with 5 tabs
+-   **Central Catch Button**: Prominent, elevated with gradient background
+-   **Lucide Icons**: Professional icon set instead of emojis
+-   **Tab States**: Active tabs show colored background and icons
 
 **Visual Design**:
-- **Clean Header**: App icon, title, and settings in top bar
-- **Card-Based Layout**: Each section in clean white cards with subtle shadows
-- **Gradient Accents**: Blue-to-purple gradients for primary actions
-- **Responsive Stats**: Visual progress bars, circular icons, grid layouts
-- **Touch-Friendly**: Large buttons, adequate spacing, tap feedback
+
+-   **Clean Header**: App icon, title, and settings in top bar
+-   **Card-Based Layout**: Each section in clean white cards with subtle shadows
+-   **Gradient Accents**: Blue-to-purple gradients for primary actions
+-   **Responsive Stats**: Visual progress bars, circular icons, grid layouts
+-   **Touch-Friendly**: Large buttons, adequate spacing, tap feedback
 
 **Content Organization**:
-- **Catch Tab**: Stats overview, code input, event filter (default active)
-- **Leaderboard Tab**: Top players with rank icons and points
-- **Achievements Tab**: Progress tracking with completion states
-- **Collection Tab**: Species collection with rarity indicators
-- **Profile Tab**: Future user profile section (placeholder)
+
+-   **Catch Tab**: Stats overview, code input, event filter (default active)
+-   **Leaderboard Tab**: Top players with rank icons and points
+-   **Achievements Tab**: Progress tracking with completion states
+-   **Collection Tab**: Species collection with rarity indicators
+-   **Profile Tab**: Future user profile section (placeholder)
 
 ## Recent Optimizations (Completed)
 
 ### 1. ✅ Fixed Event Selection Logic
-- **Solution**: Simplified logic to always default to current event (EF29)
-- **Location**: `DashboardController::index()` lines 36-43
-- **Impact**: Users now see current event leaderboard by default
+
+-   **Solution**: Simplified logic to always default to current event (EF29)
+-   **Location**: `DashboardController::index()` lines 36-43
+-   **Impact**: Users now see current event leaderboard by default
 
 ### 2. ✅ Added Scheduled Ranking Updates
-- **Solution**: Created `RefreshFceaRankingsCommand` with scheduled execution
-- **Location**: `routes/console.php` - runs every 15 minutes during convention hours
-- **Impact**: Rankings stay fresh without requiring user actions
+
+-   **Solution**: Created `RefreshFceaRankingsCommand` with scheduled execution
+-   **Location**: `routes/console.php` - runs every 15 minutes during convention hours
+-   **Impact**: Rankings stay fresh without requiring user actions
 
 ### 3. ✅ Improved Performance & Caching
-- **Solution**: Optimized cache keys, increased TTL, specific cache clearing
-- **Location**: `DashboardController` cache methods
-- **Impact**: Faster dashboard loads, reduced database queries
+
+-   **Solution**: Optimized cache keys, increased TTL, specific cache clearing
+-   **Location**: `DashboardController` cache methods
+-   **Impact**: Faster dashboard loads, reduced database queries
 
 ### 4. Current Architecture Limitations
-- **Issue**: Separate user/fursuit ranking systems sharing same table
-- **Location**: `UserCatchRanking` model and `DashboardController::refresh*` methods
-- **Future**: Consider splitting into separate models for better maintainability
+
+-   **Issue**: Separate user/fursuit ranking systems sharing same table
+-   **Location**: `UserCatchRanking` model and `DashboardController::refresh*` methods
+-   **Future**: Consider splitting into separate models for better maintainability
 
 ## Key Files and Their Purpose
 
@@ -118,13 +129,14 @@ database/
 ```
 
 ## Configuration
-- `FURSUIT_CATCH_CODE_LENGTH=5` - Length of catch codes
-- `FURSUIT_CATCH_ATTEMPTS_PER_MINUTE=20` - Rate limiting
+
+-   `FURSUIT_CATCH_CODE_LENGTH=5` - Length of catch codes
+-   `FURSUIT_CATCH_ATTEMPTS_PER_MINUTE=20` - Rate limiting
 
 ## Optimization Opportunities
 
 1. **Simplify Event Logic**: Always show current event data unless explicitly filtered
 2. **Add Scheduled Jobs**: Periodic ranking updates via console scheduling
 3. **Improve Caching**: Better cache keys and longer TTLs for stable data
 4. **Optimize Queries**: Reduce N+1 queries and complex joins
-5. **Separate Ranking Models**: Split user/fursuit rankings into separate tables
+5. **Separate Ranking Models**: Split user/fursuit rankings into separate tables

app/Domain/CatchEmAll/Achievements/Archivist.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Domain\CatchEmAll\Achievements;
+
+use App\Domain\CatchEmAll\Interface\Achievement;
+use App\Domain\CatchEmAll\Models\AchievementUpdateContext;
+
+class Archivist implements Achievement
+{
+    public function getId(): string
+    {
+        return 'archivist';
+    }
+
+    public function getTile(): string
+    {
+        return 'Archivist';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Your dedication is clear.';
+    }
+
+    public function getIcon(): string
+    {
+        return '📚';
+    }
+
+    public function getMaxProgress(): int
+    {
+        return 100;
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function isOptional(): bool
+    {
+        return false;
+    }
+
+    public function isHidden(): bool
+    {
+        return false;
+    }
+
+    public function updateAchievementProgress(AchievementUpdateContext $context): int
+    {
+        // Only trigger on actual catches, not special codes
+        if (!$context->hasCatch()) {
+            return -1; // Ignore this update
+        }
+
+        // Return current progress based on user's total catches
+        $currentProgress = min($context->userTotalCatches, $this->getMaxProgress());
+
+        return $currentProgress;
+    }
+}

app/Domain/CatchEmAll/Achievements/BugBountyHunter.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace App\Domain\CatchEmAll\Achievements;
+
+use App\Domain\CatchEmAll\Enums\SpecialCodeType;
+use App\Domain\CatchEmAll\Interface\SpecialAchievement;
+use App\Domain\CatchEmAll\Models\AchievementUpdateContext;
+
+class BugBountyHunter implements SpecialAchievement
+{
+
+    public function getId(): string
+    {
+        return 'bug_bounty_hunter';
+    }
+
+
+    public function getTile(): string
+    {
+        return 'Bug Bounty Hunter';
+    }
+
+
+    public function getDescription(): string
+    {
+        return 'Thanks for the QA! Your contribution is noted.';
+    }
+
+
+    public function getIcon(): string
+    {
+        return '🐛';
+    }
+
+
+    public function getMaxProgress(): int
+    {
+        return 1;
+    }
+
+
+    public function isSecret(): bool
+    {
+        return true;
+    }
+
+
+    public function isOptional(): bool
+    {
+        return true;
+    }
+
+
+    public function isHidden(): bool
+    {
+        return false;
+    }
+
+
+    public function updateAchievementProgress(AchievementUpdateContext $context): int
+    {
+        // This achievement can only be triggered by special code, not by catches
+        if (!$context->isSpecialCodeTrigger() || $context->specialCodeType !== SpecialCodeType::BUG_BOUNTY) {
+            return -1; // Ignore this update
+        }
+
+        // Return completion progress - achievement granting is handled by AchievementService
+        return $this->getMaxProgress(); // Return 1 (completed)
+    }
+
+
+    public function getSpecialCode(): SpecialCodeType
+    {
+        return SpecialCodeType::BUG_BOUNTY;
+    }
+}

app/Domain/CatchEmAll/Achievements/Collector.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Domain\CatchEmAll\Achievements;
+
+use App\Domain\CatchEmAll\Interface\Achievement;
+use App\Domain\CatchEmAll\Models\AchievementUpdateContext;
+
+class Collector implements Achievement
+{
+    public function getId(): string
+    {
+        return 'collector';
+    }
+
+    public function getTile(): string
+    {
+        return 'Collector';
+    }
+
+    public function getDescription(): string
+    {
+        return 'You are an aspiring collector.';
+    }
+
+    public function getIcon(): string
+    {
+        return '📦';
+    }
+
+    public function getMaxProgress(): int
+    {
+        return 10;
+    }
+
+    public function isSecret(): bool
+    {
+        return false;
+    }
+
+    public function isOptional(): bool
+    {
+        return false;
+    }
+
+    public function isHidden(): bool
+    {
+        return false;
+    }
+
+    public function updateAchievementProgress(AchievementUpdateContext $context): int
+    {
+        // Only trigger on actual catches, not special codes
+        if (!$context->hasCatch()) {
+            return -1; // Ignore this update
+        }
+
+        // Return current progress based on user's total catches
+        $currentProgress = min($context->userTotalCatches, $this->getMaxProgress());
+
+        return $currentProgress;
+    }
+}