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:
```go
// 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:
```bash
make migrate-up
```

### Frontend Changes

#### 1. TypeScript Types (`frontend/src/services/settings.ts`)
Added the field to the `AdminSettings` type:
```typescript
// 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:**
```typescript
// 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.)