mirror of
https://github.com/Dvorinka/ClubLogos.git
synced 2026-06-04 20:12:57 +00:00
first commit
This commit is contained in:
Tomáš Dvořák
@@ -0,0 +1,402 @@
|
||||
# 🚀 Major Update Summary
|
||||
|
||||
## What's New - Enhanced Feature Set
|
||||
|
||||
### 🎯 Critical Enhancements Completed
|
||||
|
||||
#### 1. **Separate Home & Admin Pages**
|
||||
- ✅ **Home Page** (`/`) - Public logo gallery with search
|
||||
- ✅ **Admin Page** (`/admin.html`) - Upload interface with club search
|
||||
- ✅ **Navigation** - Easy switching between pages
|
||||
- ✅ **Optimized Bundles** - Separate JS files for each page
|
||||
|
||||
#### 2. **Dual Format Support (SVG + PNG)**
|
||||
- ✅ **Upload SVG** - Automatically converted to PNG
|
||||
- ✅ **Upload PNG** - Optimized and stored
|
||||
- ✅ **Dual Storage** - Both formats kept (`logos/svg/` and `logos/png/`)
|
||||
- ✅ **Primary PNG** - PNG served by default for compatibility
|
||||
- ✅ **Format Selection** - `?format=svg` or `?format=png` query params
|
||||
- ✅ **Auto-conversion** - SVG → PNG (512x512px)
|
||||
- ✅ **Optimization** - PNG compression applied
|
||||
|
||||
#### 3. **Club Website Integration**
|
||||
- ✅ **Website Field** - Added to database and forms
|
||||
- ✅ **Browser Search** - "Search Online" button for finding club websites
|
||||
- ✅ **Google Integration** - Quick link to search for official site
|
||||
- ✅ **FAČR API** - Retrieves website from API when available
|
||||
- ✅ **Demo Data** - Demo clubs include website URLs
|
||||
|
||||
#### 4. **Required Club Name Validation**
|
||||
- ✅ **Backend Validation** - Club name required in POST request
|
||||
- ✅ **Frontend Validation** - Form won't submit without name
|
||||
- ✅ **GitHub Actions** - PR validation checks for club name
|
||||
- ✅ **Clear Warnings** - UI shows requirements prominently
|
||||
- ✅ **Auto-rejection** - Missing club name = rejected upload
|
||||
|
||||
#### 5. **GitHub Actions Logo Validation**
|
||||
- ✅ **Automated PR Checks** - Validates logo uploads
|
||||
- ✅ **UUID Validation** - Filename must be valid UUID
|
||||
- ✅ **Format Check** - Only .svg and .png allowed
|
||||
- ✅ **Metadata Check** - PR must include club name and ID
|
||||
- ✅ **Auto-comments** - Adds success/failure comments
|
||||
- ✅ **PR Template** - Dedicated template for logo uploads
|
||||
|
||||
#### 6. **List Logos Endpoint**
|
||||
- ✅ **GET /logos** - Returns all uploaded logos
|
||||
- ✅ **Full Metadata** - Name, city, type, website, formats
|
||||
- ✅ **Sorted Output** - Alphabetical by club name
|
||||
- ✅ **Gallery Support** - Powers homepage gallery
|
||||
|
||||
#### 7. **Correct FAČR API Usage**
|
||||
- ✅ **Fixed URL** - Now uses `https://facr.tdvorak.dev`
|
||||
- ✅ **Search Integration** - `/club/search?q={query}`
|
||||
- ✅ **Club Details** - `/club/{id}`
|
||||
- ✅ **Demo Fallback** - Works offline with demo data
|
||||
|
||||
---
|
||||
|
||||
## 🗄️ Database Changes
|
||||
|
||||
### Updated Schema
|
||||
```sql
|
||||
CREATE TABLE logos (
|
||||
id TEXT PRIMARY KEY,
|
||||
club_name TEXT NOT NULL, -- NOW REQUIRED ✨
|
||||
club_city TEXT,
|
||||
club_type TEXT,
|
||||
club_website TEXT, -- NEW FIELD ✨
|
||||
has_svg INTEGER DEFAULT 0, -- NEW FIELD ✨
|
||||
has_png INTEGER DEFAULT 0, -- NEW FIELD ✨
|
||||
primary_format TEXT DEFAULT 'png',-- NEW FIELD ✨
|
||||
file_size_svg INTEGER, -- NEW FIELD ✨
|
||||
file_size_png INTEGER, -- NEW FIELD ✨
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
)
|
||||
```
|
||||
|
||||
### Migration from Old Schema
|
||||
If you have existing data, the table will be automatically recreated with new fields on first run.
|
||||
|
||||
---
|
||||
|
||||
## 📁 File Structure Changes
|
||||
|
||||
### New Files Created
|
||||
```
|
||||
frontend/
|
||||
├── admin.html # NEW: Admin panel page
|
||||
├── src/
|
||||
│ ├── home.js # NEW: Home page logic
|
||||
│ └── admin.js # NEW: Admin page logic
|
||||
|
||||
backend/
|
||||
├── image_converter.go # NEW: SVG to PNG conversion
|
||||
├── handlers.go # UPDATED: New endpoints & logic
|
||||
|
||||
.github/
|
||||
├── workflows/
|
||||
│ └── validate-logo-upload.yml # NEW: GitHub Actions
|
||||
└── PULL_REQUEST_TEMPLATE/
|
||||
└── logo_upload.md # NEW: Logo upload PR template
|
||||
|
||||
docs/
|
||||
├── FEATURES.md # NEW: Complete feature list
|
||||
└── UPDATE_SUMMARY.md # NEW: This file
|
||||
```
|
||||
|
||||
### Updated Files
|
||||
- `backend/main.go` - Added logo subdirectories, list endpoint
|
||||
- `backend/go.mod` - Added image processing dependencies
|
||||
- `backend/facr_client.go` - Added Website field to Club struct
|
||||
- `frontend/vite.config.js` - Multi-page build support
|
||||
- `frontend/src/main.js` - Moved to home.js
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Setup Requirements
|
||||
|
||||
### Backend Dependencies
|
||||
```bash
|
||||
# Go modules (already configured)
|
||||
go mod tidy
|
||||
|
||||
# Optional: Image conversion tools
|
||||
# Install ONE of these for SVG → PNG conversion:
|
||||
|
||||
# Option 1: ImageMagick (recommended)
|
||||
# Windows: choco install imagemagick
|
||||
# Mac: brew install imagemagick
|
||||
# Linux: sudo apt install imagemagick
|
||||
|
||||
# Option 2: Inkscape
|
||||
# Windows: choco install inkscape
|
||||
# Mac: brew install inkscape
|
||||
# Linux: sudo apt install inkscape
|
||||
```
|
||||
|
||||
**Note:** SVG conversion is optional. If neither tool is installed, SVG files will still be stored, just not auto-converted to PNG.
|
||||
|
||||
### Frontend Dependencies
|
||||
```bash
|
||||
cd frontend
|
||||
npm install # Already configured, no new deps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 How to Use New Features
|
||||
|
||||
### 1. Browse Logos (Home Page)
|
||||
```bash
|
||||
# Start services
|
||||
docker-compose up
|
||||
|
||||
# Visit
|
||||
http://localhost:3000/
|
||||
|
||||
# Features available:
|
||||
- View all uploaded logos
|
||||
- Search/filter logos
|
||||
- Click to copy logo URL
|
||||
```
|
||||
|
||||
### 2. Upload Logos (Admin Page)
|
||||
```bash
|
||||
# Visit
|
||||
http://localhost:3000/admin.html
|
||||
|
||||
# Steps:
|
||||
1. Search for a club
|
||||
2. Click "Select" on search result
|
||||
3. Fill in club details (name is REQUIRED)
|
||||
4. Optionally search for club website
|
||||
5. Upload SVG or PNG logo
|
||||
6. Submit (both formats will be available)
|
||||
```
|
||||
|
||||
### 3. Use API with Format Selection
|
||||
```bash
|
||||
# Get logo (PNG by default)
|
||||
curl http://localhost:8080/logos/{uuid}
|
||||
|
||||
# Get specific format
|
||||
curl http://localhost:8080/logos/{uuid}?format=svg
|
||||
curl http://localhost:8080/logos/{uuid}?format=png
|
||||
|
||||
# List all logos
|
||||
curl http://localhost:8080/logos
|
||||
|
||||
# Get logo metadata
|
||||
curl http://localhost:8080/logos/{uuid}/json
|
||||
```
|
||||
|
||||
### 4. Upload via GitHub PR
|
||||
```markdown
|
||||
1. Create PR with logo file named {uuid}.svg or {uuid}.png
|
||||
2. Use PR template to provide:
|
||||
- Club Name: AC Sparta Praha
|
||||
- Club ID: 22222222-3333-4444-5555-666666666666
|
||||
3. GitHub Actions will validate
|
||||
4. Auto-approved if valid, auto-rejected if invalid
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 API Changes
|
||||
|
||||
### New Endpoints
|
||||
| Method | Endpoint | Description |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/logos` | **NEW** - List all logos |
|
||||
|
||||
### Enhanced Endpoints
|
||||
| Method | Endpoint | Changes |
|
||||
|--------|----------|---------|
|
||||
| GET | `/logos/:id` | Now supports `?format=svg` or `?format=png` |
|
||||
| GET | `/logos/:id/json` | Returns has_svg, has_png, both URLs |
|
||||
| POST | `/logos/:id` | Requires club_name, stores both formats |
|
||||
|
||||
### Response Changes
|
||||
|
||||
**GET /logos/:id/json** - New Response:
|
||||
```json
|
||||
{
|
||||
"id": "uuid",
|
||||
"club_name": "AC Sparta Praha",
|
||||
"club_city": "Praha",
|
||||
"club_type": "football",
|
||||
"club_website": "https://www.sparta.cz", // NEW
|
||||
"has_svg": true, // NEW
|
||||
"has_png": true, // NEW
|
||||
"primary_format": "png", // NEW
|
||||
"logo_url": "http://localhost:8080/logos/uuid?format=png",
|
||||
"logo_url_svg": "http://localhost:8080/logos/uuid?format=svg", // NEW
|
||||
"logo_url_png": "http://localhost:8080/logos/uuid?format=png", // NEW
|
||||
"file_size_svg": 12345, // NEW
|
||||
"file_size_png": 8192, // NEW
|
||||
"created_at": "2024-01-01T12:00:00Z",
|
||||
"updated_at": "2024-01-01T12:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
**POST /logos/:id** - New Required Field:
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/logos/{uuid} \
|
||||
-F "file=@logo.svg" \
|
||||
-F "club_name=AC Sparta Praha" \ # NOW REQUIRED
|
||||
-F "club_city=Praha" \
|
||||
-F "club_type=football" \
|
||||
-F "club_website=https://sparta.cz" # NEW FIELD
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Breaking Changes
|
||||
|
||||
### 1. **club_name is now REQUIRED**
|
||||
- **Old:** Could upload without club name
|
||||
- **New:** Upload rejected without club_name
|
||||
- **Migration:** Existing logos without names need manual update
|
||||
|
||||
### 2. **Logo file paths changed**
|
||||
- **Old:** `./logos/{uuid}.svg`
|
||||
- **New:** `./logos/svg/{uuid}.svg` and `./logos/png/{uuid}.png`
|
||||
- **Migration:** Run migration script or move files manually
|
||||
|
||||
### 3. **Database schema updated**
|
||||
- **Old:** Single file_extension and file_size columns
|
||||
- **New:** Separate columns for SVG and PNG
|
||||
- **Migration:** Database recreated on first run (backup first!)
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration Guide
|
||||
|
||||
### For Existing Installations
|
||||
|
||||
#### Step 1: Backup Data
|
||||
```bash
|
||||
# Backup database
|
||||
cp db.sqlite db.sqlite.backup
|
||||
|
||||
# Backup logos
|
||||
cp -r logos logos.backup
|
||||
```
|
||||
|
||||
#### Step 2: Update Code
|
||||
```bash
|
||||
git pull origin main
|
||||
cd backend && go mod tidy
|
||||
cd ../frontend && npm install
|
||||
```
|
||||
|
||||
#### Step 3: Migrate Files
|
||||
```bash
|
||||
# Create new structure
|
||||
mkdir -p logos/svg logos/png
|
||||
|
||||
# Move existing files (manual process)
|
||||
# SVG files to logos/svg/
|
||||
# PNG files to logos/png/
|
||||
```
|
||||
|
||||
#### Step 4: Update Database
|
||||
```bash
|
||||
# Database will auto-migrate on first run
|
||||
# Or manually run SQL migration
|
||||
```
|
||||
|
||||
#### Step 5: Restart Services
|
||||
```bash
|
||||
docker-compose down
|
||||
docker-compose up --build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 Testing New Features
|
||||
|
||||
### 1. Test SVG Upload
|
||||
```bash
|
||||
# Visit admin panel
|
||||
http://localhost:3000/admin.html
|
||||
|
||||
# Upload SVG file
|
||||
# Check: Both SVG and PNG should be created
|
||||
ls logos/svg/{uuid}.svg
|
||||
ls logos/png/{uuid}.png
|
||||
```
|
||||
|
||||
### 2. Test Format Selection
|
||||
```bash
|
||||
# Get PNG
|
||||
curl http://localhost:8080/logos/{uuid}?format=png
|
||||
|
||||
# Get SVG
|
||||
curl http://localhost:8080/logos/{uuid}?format=svg
|
||||
|
||||
# Default (PNG)
|
||||
curl http://localhost:8080/logos/{uuid}
|
||||
```
|
||||
|
||||
### 3. Test Logo List
|
||||
```bash
|
||||
curl http://localhost:8080/logos | jq
|
||||
```
|
||||
|
||||
### 4. Test GitHub Actions
|
||||
```bash
|
||||
# Create PR with logo upload
|
||||
# Check that Actions run
|
||||
# Verify validation messages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📈 Performance Impact
|
||||
|
||||
### Improvements
|
||||
- ✅ **Faster Loading** - PNG serves faster than SVG
|
||||
- ✅ **Better Caching** - Optimized PNG files
|
||||
- ✅ **Dual Format** - Clients can choose best format
|
||||
- ✅ **Code Splitting** - Separate bundles for pages
|
||||
|
||||
### Considerations
|
||||
- ⚠️ **Storage** - 2x storage (SVG + PNG)
|
||||
- ⚠️ **Upload Time** - Slightly longer (conversion)
|
||||
- ⚠️ **Dependencies** - ImageMagick/Inkscape optional
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Summary
|
||||
|
||||
### What You Get
|
||||
1. ✅ **Complete Gallery** - Beautiful homepage with all logos
|
||||
2. ✅ **Professional Admin** - Full-featured upload interface
|
||||
3. ✅ **Dual Formats** - SVG and PNG support
|
||||
4. ✅ **Website Links** - Club websites integrated
|
||||
5. ✅ **Auto-validation** - GitHub Actions protection
|
||||
6. ✅ **Better API** - More endpoints and options
|
||||
7. ✅ **Required Fields** - Data quality enforced
|
||||
|
||||
### Ready to Use
|
||||
All features are production-ready and tested. Simply run:
|
||||
```bash
|
||||
docker-compose up
|
||||
```
|
||||
|
||||
Then visit:
|
||||
- **Home:** http://localhost:3000/
|
||||
- **Admin:** http://localhost:3000/admin.html
|
||||
- **API:** http://localhost:8080/logos
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**🎊 Update Complete! All Features Enhanced! 🎊**
|
||||
|
||||
[Features](FEATURES.md) • [Quick Start](QUICKSTART.md) • [API Docs](API_EXAMPLES.md)
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user