mirror of
https://github.com/Dvorinka/MyClubServer.git
synced 2026-06-04 02:32:57 +00:00
upload
This commit is contained in:
Tomáš Dvořák
@@ -0,0 +1,223 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user