MyClub/DOCS/ZONERAMA_GALLERY_FIX.md

# Zonerama Gallery Fix - Implementation Summary

## Problem Description

The Zonerama gallery was not displaying any photos on the admin page or frontend, despite having profile data in `zonerama_profile.json`.

### Root Cause

1. **Profile fetch** (`zonerama_profile.json`) only contained album metadata without photos (fetched with `photo_limit=0`)
2. **Album storage** (`zonerama_albums.json`) didn't exist - individual albums with photos were never fetched
3. **Flat files** (`zonerama_flat.json` and `gallery.json`) were empty because there were no albums with photos to flatten
4. **Frontend** reads from `zonerama_flat.json` → displays nothing

## Solution Implemented

### Backend Changes (`internal/services/prefetch_service.go`)

#### Modified `fetchZonerama()` function:
1. **Fetch profile** with album metadata (as before)
2. **NEW: Fetch each album individually** with photos using the Zonerama API
3. **NEW: Store albums** in `zonerama_albums.json` with all photo data
4. **NEW: Regenerate flat files** for frontend consumption

#### Added `fetchZoneramaAlbums()` helper function:
- Fetches individual albums from the profile
- Calls the Zonerama API `/zonerama-album` endpoint for each album
- Configurable photo limit per album (default: 50, env: `ZONERAMA_PHOTO_LIMIT`)
- Includes retry logic and delays between requests to avoid overwhelming the API

### Frontend Changes (`frontend/src/components/home/PhotosSection.tsx`)

Updated the photo manifest loading to use fallback paths:
1. **Primary**: `/cache/prefetch/zonerama_flat.json` (new unified location)
2. **Fallback 1**: `/cache/prefetch/zonerama/manifest.json` (legacy path)
3. **Fallback 2**: `/cache/prefetch/gallery.json` (alternative)

## Data Flow

```
1. fetchZonerama() is called (profile URL)
   ↓
2. Fetch profile → save to zonerama_profile.json (album metadata only)
   ↓
3. Parse albums from profile
   ↓
4. For each album:
   - Fetch album with photos from API
   - Collect album data with photos
   ↓
5. Save all albums → zonerama_albums.json
   ↓
6. RegenerateFlatGalleryFiles()
   - Read zonerama_albums.json
   - Flatten all photos from all albums
   - Write to zonerama_flat.json and gallery.json
   ↓
7. Frontend reads zonerama_flat.json → displays photos
```

## Configuration

### Environment Variables

- **`ZONERAMA_ALBUM_LIMIT`**: Max number of albums to fetch from profile (default: 10)
- **`ZONERAMA_PHOTO_LIMIT`**: Max photos per album (default: 50)
- **`ZONERAMA_FETCH_INTERVAL_MINUTES`**: How often to refresh (default: 1440 = daily)
- **`ENABLE_ZONERAMA_PREFETCH`**: Enable/disable Zonerama fetching (default: true)

## How to Trigger Album Fetch

### Automatic (Recommended)
The system will automatically fetch albums:
- On startup (after 15 seconds)
- Daily (configurable interval)

### Manual Trigger

#### Option 1: Admin Panel
1. Go to Admin → Settings → Sociální sítě
2. Ensure Zonerama URL is configured
3. Go to Admin → Galerie (or trigger via prefetch)
4. Click "Spustit stažení" button

#### Option 2: API Call
```bash
POST /api/v1/admin/prefetch/trigger
Authorization: Bearer <admin-token>
```

#### Option 3: Direct Service Call (for testing)
```bash
# Trigger Zonerama refresh directly
curl "http://localhost:8080/api/v1/admin/prefetch/trigger" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"
```

## Files Generated

After successful fetch, you should have:

1. **`cache/prefetch/zonerama_profile.json`**
   - Profile metadata with album list (no photos inside albums)
   - Source of truth for which albums exist

2. **`cache/prefetch/zonerama_albums.json`** ← NEW
   - Array of albums, each with full photo data
   - This is the main storage for album+photo data

3. **`cache/prefetch/zonerama_flat.json`** ← NEW (regenerated)
   - Flattened list of all photos from all albums
   - Used by admin page and frontend

4. **`cache/prefetch/gallery.json`** ← NEW (regenerated)
   - Same content as zonerama_flat.json (for compatibility)

5. **`cache/prefetch/zonerama_flat.json.hdr`** ← NEW
   - Metadata (fetched_at, source link)

## Verification

### Check if albums were fetched:
```bash
# Should show albums with photos
cat cache/prefetch/zonerama_albums.json | jq '.[0].photos | length'

# Should show flattened photos
cat cache/prefetch/zonerama_flat.json | jq 'length'
```

### Check admin page:
1. Go to `/admin/zonerama`
2. Should display photo count and photos in grid
3. "Počet fotek" should be > 0

### Check frontend:
1. Go to homepage
2. "Fotogalerie" section should show 6 photos

## Troubleshooting

### No photos showing after fetch

1. **Check Zonerama URL is configured**:
   ```bash
   cat cache/prefetch/settings.json | jq '.zonerama_url'
   ```

2. **Check profile was fetched**:
   ```bash
   cat cache/prefetch/zonerama_profile.json | jq '.albums | length'
   ```

3. **Check albums were fetched**:
   ```bash
   ls -lh cache/prefetch/zonerama_albums.json
   cat cache/prefetch/zonerama_albums.json | jq 'length'
   ```

4. **Check flat files were generated**:
   ```bash
   cat cache/prefetch/zonerama_flat.json | jq 'length'
   ```

5. **Check logs for errors**:
   ```bash
   # Look for "[prefetch] Zonerama" messages
   grep "Zonerama" logs/app.log
   ```

### API Rate Limiting

The implementation includes:
- 500ms delay between album fetches
- Exponential backoff on profile fetch (3 retries)
- Configurable limits via environment variables

If you hit rate limits, you can:
- Reduce `ZONERAMA_ALBUM_LIMIT` (fetch fewer albums)
- Reduce `ZONERAMA_PHOTO_LIMIT` (fewer photos per album)
- Increase `ZONERAMA_FETCH_INTERVAL_MINUTES` (fetch less frequently)

## API Endpoints

### Public
- `GET /api/v1/gallery/albums` - Get all albums
- `GET /api/v1/gallery/albums/:id` - Get single album with photos

### Admin
- `GET /api/v1/admin/gallery/profile` - Get Zonerama profile metadata
- `POST /api/v1/admin/gallery/albums/fetch` - Fetch single album by URL
- `DELETE /api/v1/admin/gallery/albums/:id` - Delete album from collection
- `POST /api/v1/admin/prefetch/trigger` - Trigger full prefetch (includes Zonerama)

## Admin Features

### Fetch Individual Albums
Admins can manually add albums:

```bash
POST /api/v1/admin/gallery/albums/fetch
{
  "link": "https://eu.zonerama.com/FKKofolaKrnov/Album/13939668",
  "photo_limit": 50
}
```

This allows:
- Adding new albums not in the profile
- Re-fetching specific albums with updated photos
- Fetching with custom photo limits

### Album Management
- View all fetched albums: `GET /api/v1/gallery/albums`
- Delete unwanted albums: `DELETE /api/v1/admin/gallery/albums/:id`
- Albums are automatically included in flat files after add/delete

## Notes

- Albums are fetched with photos inline (not downloaded to disk)
- Photos are served via proxy to avoid CORS issues
- The system maintains both profile metadata and full album data
- Flat files are regenerated automatically after any album operation
- Frontend has fallback logic for backward compatibility