MyClub/DOCS/FINISHED_MATCHES_DISPLAY_FEATURE.md

Finished Matches Display Feature

Overview

Implemented a feature to display recent finished matches with scores on the homepage for a configurable number of days (default: 2 days). This ensures that visitors can see match results for a period of time before the next upcoming match is displayed.

Implementation Details

Backend Changes

1. Database Model (internal/models/models.go)

Added new field to the Settings struct:

// Homepage matches display configuration
FinishedMatchDisplayDays int `gorm:"default:2" json:"finished_match_display_days"` // Number of days to show finished matches with scores on homepage

2. Database Migration

Created migration files:

• database/migrations/000025_add_finished_match_display_days.up.sql
• database/migrations/000025_add_finished_match_display_days.down.sql

To apply the migration, run:

make migrate-up

Frontend Changes

1. TypeScript Types (frontend/src/services/settings.ts)

Added the field to the AdminSettings type:

// Homepage matches display configuration
finished_match_display_days?: number; // Number of days to show finished matches with scores on homepage

2. Homepage Logic (frontend/src/pages/HomePage.tsx)

Updated the match filtering logic to:

• Load the finished_match_display_days setting (defaults to 2 days)
• Filter for recent finished matches that:
  • Have a score available
  • Occurred within the configured number of days
  • Are in the past
• Display the most recent finished match with score before the next upcoming match
• Show the score prominently in the "Next Match" section when displaying a finished match

Key Logic:

// Get recent finished matches with scores (within display days)
const recentFinished = allMatches
  .filter((m) => 
    matchTime < now && 
    matchTime >= cutoffTime &&
    m.score // Only show if there's a score
  )
  .sort((a, b) => b.time - a.time); // Most recent first

// Show recent finished match first if exists, then upcoming matches
const chosen = recentFinished.length > 0 ? [...recentFinished.slice(0, 1), ...upcoming] : upcoming;

Display Logic: When a finished match is shown in the "Next Match" section:

• Shows the final score instead of countdown
• Displays "Skončeno" (Finished) instead of "Začátek zápasu" (Match start)
• Maintains the same layout with team logos and names

3. Admin UI (frontend/src/pages/admin/SettingsAdminPage.tsx)

Added configuration field in the General Settings tab:

• Label: "Počet dní zobrazení dokončených zápasů"
• Type: Number input (0-30 days)
• Default: 2 days
• Helper Text: Explains that this controls how long finished matches with scores are displayed on the homepage

Usage

For Administrators

1. Go to Admin Panel → Settings → General (Nastavení)
2. Scroll to "Zobrazení zápasů" section
3. Set the desired number of days (0-30) to show finished matches
4. Click "Uložit nastavení" to save

Behavior

• If set to 0: Finished matches are never shown; only upcoming matches are displayed
• If set to 2 (default): A finished match with a score will be shown for 2 days after it finishes, then switches to the next upcoming match
• If set to 7: Results are shown for a full week before switching

Technical Details

Match Selection Priority

1. Recent finished match with score (within configured days) - shown first
2. Next upcoming match - shown if no recent finished match or after the display period expires
3. Fallback to first available match - if neither of above are available

Score Display Requirements

A match must have:

• A valid score field (e.g., "2:1", "0:0")
• A match time in the past
• A match time within the configured display window

Cache & Performance

• The setting is cached with other settings in /cache/prefetch/settings.json
• Frontend reads the setting once on page load
• Changes take effect after saving settings and refreshing the homepage

Files Modified

Backend

• internal/models/models.go - Added field to Settings model
• database/migrations/000025_add_finished_match_display_days.up.sql - Migration up
• database/migrations/000025_add_finished_match_display_days.down.sql - Migration down

Frontend

• frontend/src/services/settings.ts - Added TypeScript type
• frontend/src/pages/HomePage.tsx - Implemented match filtering logic
• frontend/src/pages/admin/SettingsAdminPage.tsx - Added admin UI configuration

Testing

Manual Testing Steps

1. Ensure a match has finished with a score in the FACR data
2. Set finished_match_display_days to a value like 7 days
3. Verify the finished match appears in the "Next Match" section with the score
4. Verify it shows "Skončeno" instead of countdown
5. Set the value to 0 days
6. Verify only upcoming matches are shown
7. Test with multiple competitions using the carousel arrows

Future Enhancements

• Add option to show multiple finished matches (currently only shows the most recent one)
• Add visual distinction for finished vs upcoming matches in the matches slider
• Option to hide finished matches without scores
• Configurable display format for finished matches (e.g., "Final", "FT", etc.)