From 6eea814fad1d81cdc6ac35060d43ad0f372136a4 Mon Sep 17 00:00:00 2001
From: Kenzo <kenzo.signer@bookageek.ch>
Date: Tue, 9 Dec 2025 17:08:36 +0100
Subject: [PATCH] feat: Add gallery management to admin panel + system
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Features:
- Gallery upload, delete, reorder (drag & drop)
- Preview images in admin panel
- Same upload flow as events (WebP conversion via sharp)
- Complete system documentation explaining:
  - Architecture (Frontend/Backend/Volume)
  - Upload flow (Multipart → Sharp → WebP → Storage)
  - Why SQLite works on Fly.io (persistent volumes)
  - Troubleshooting guide

Admin now has full CRUD for both Events and Gallery!
---
 SYSTEM_ERKLAERUNG.md  | 220 ++++++++++++++++++++++++++++++++++++++++++
 src/pages/admin.astro | 149 ++++++++++++++++++++++++++++
 2 files changed, 369 insertions(+)
 create mode 100644 SYSTEM_ERKLAERUNG.md

diff --git a/SYSTEM_ERKLAERUNG.md b/SYSTEM_ERKLAERUNG.md
new file mode 100644
index 0000000..cb70757
--- /dev/null
+++ b/SYSTEM_ERKLAERUNG.md
@@ -0,0 +1,220 @@
+# 🎯 Gallus Pub CMS - System-Erklärung
+
+## 📐 Architektur-Überblick
+
+```
+┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
+│   Frontend      │         │   Backend CMS    │         │  Fly.io Volume  │
+│  (Astro SSG)    │◄────────┤   (Fastify API)  │◄────────┤   /app/data/    │
+│ gallus-pub.ch   │  fetch  │ cms.gallus-pub.ch│  mount  │  - SQLite DB    │
+│                 │         │                  │         │  - images/      │
+└─────────────────┘         └──────────────────┘         └─────────────────┘
+```
+
+## 🔄 Wie funktioniert der Upload-Flow?
+
+### 1. **Admin lädt Bild hoch** (admin.astro)
+```
+User wählt Bild → uploadImage() → POST /api/gallery/upload
+```
+
+### 2. **Backend verarbeitet Upload** (backend/src/routes/gallery.ts)
+```javascript
+// Line 60-134 in gallery.ts
+1. Empfange Multipart-File
+2. Validiere Mimetype (nur images/*)
+3. Lese Stream in Buffer
+4. sharp() konvertiert zu WebP:
+   - Auto-rotate (EXIF)
+   - Resize auf max 1600px
+   - WebP quality 82%
+5. Speichere in /app/data/images/gallery/
+6. Erstelle DB-Eintrag mit imageUrl
+7. Return imageUrl an Frontend
+```
+
+### 3. **Bilder werden serviert** (backend/src/index.ts)
+```javascript
+// Line 63-69
+fastifyStatic → /static/ → /app/data/
+```
+
+Beispiel:
+- Bild liegt in: `/app/data/images/gallery/miyma9zc-8he1di.webp`
+- URL ist: `/images/gallery/miyma9zc-8he1di.webp`
+- Wird serviert als: `https://cms.gallus-pub.ch/static/images/gallery/miyma9zc-8he1di.webp`
+
+### 4. **Frontend zeigt Bilder** (src/pages/index.astro)
+```javascript
+// Line 30-43
+1. Fetch von /api/gallery/public
+2. Map imageUrl: `${API_BASE}${img.imageUrl}`
+3. Result: https://cms.gallus-pub.ch/static/images/gallery/xyz.webp
+```
+
+## 💾 Warum funktioniert SQLite mit Fly.io?
+
+**Fly.io Volumes** sind persistente Speicher:
+- Gemountet als: `/app/data/`
+- Konfiguration in: `backend/fly.toml` (Line 40-42)
+- Bleibt bei Restarts/Deploys erhalten
+
+```toml
+[mounts]
+  source = "gallus_data"
+  destination = "/app/data"
+```
+
+### Was liegt wo?
+
+```
+/app/data/
+├── gallus_cms.db          # SQLite Datenbank
+├── gallus_cms.db-wal      # Write-Ahead Log
+├── gallus_cms.db-shm      # Shared Memory
+└── images/
+    ├── events/
+    │   ├── event_karaoke.webp
+    │   └── ...
+    └── gallery/
+        ├── Gallery1.webp
+        └── ...
+```
+
+## 🔒 Datenfluss im Detail
+
+### Event erstellen:
+```
+1. Admin: Bild auswählen + Formular ausfüllen
+2. uploadImage(file) → /api/gallery/upload
+   ↓
+3. Backend:
+   - Sharp konvertiert → WebP
+   - Speichert in /app/data/images/gallery/
+   - Returnt: { image: { imageUrl: "/images/gallery/xyz.webp" } }
+   ↓
+4. Admin: POST /api/events
+   Body: { title, date, description, imageUrl: "/images/gallery/xyz.webp" }
+   ↓
+5. Backend:
+   - INSERT INTO events (imageUrl = "/images/gallery/xyz.webp")
+   ↓
+6. Frontend: GET /api/events/public
+   - Fetcht Events aus DB
+   - Mapped imageUrl zu voller URL
+   - Zeigt an: <img src="https://cms.gallus-pub.ch/static/images/gallery/xyz.webp">
+```
+
+### Warum separate Uploads für Gallery?
+
+Events nutzen den Gallery-Upload, weil:
+- Beide brauchen WebP-Konvertierung
+- Beide nutzen gleichen Storage
+- Vermeidet Code-Duplikation
+- Gallery kann eigenständige Bildergalerie haben
+
+## 🎨 Admin-Panel Features
+
+### Events-Verwaltung:
+- ✅ Event erstellen (mit Bild-Upload)
+- ✅ Events auflisten
+- ✅ Events löschen
+- ✅ Reihenfolge ändern (Drag & Drop)
+- ✅ Events veröffentlichen/verstecken (isPublished)
+
+### Gallery-Verwaltung: (NEU!)
+- ✅ Bild hochladen
+- ✅ Gallery auflisten
+- ✅ Bilder löschen
+- ✅ Reihenfolge ändern (Drag & Drop)
+- ✅ Bilder veröffentlichen/verstecken (isPublished)
+
+### Publish:
+- Git-Integration (für statische Seiten-Updates)
+- Commit & Push zu Repository
+
+## 🚀 Deployment-Prozess
+
+### Was passiert beim Deploy?
+
+1. **Woodpecker CI** triggered bei Push zu `main`
+2. **Frontend Deploy** (gallus-pub):
+   - Build Astro SSG
+   - Deploy zu Fly.io
+
+3. **Backend Deploy** (gallus-cms-backend):
+   - Docker Build:
+     ```dockerfile
+     # Backend-Code kompilieren
+     npm run build → dist/
+
+     # Migrierte Bilder einpacken
+     COPY backend/data/images → /app/migration-images
+
+     # Migration-Script kopieren
+     COPY migrate-production.js → /app/
+     ```
+   - Deploy zu Fly.io
+   - **Volume bleibt erhalten** (SQLite DB + hochgeladene Bilder)
+
+4. **Nach erstem Deploy**: Migration ausführen
+   ```bash
+   fly ssh console -a gallus-cms-backend
+   node migrate-production.js
+   ```
+   - Kopiert Bilder: `/app/migration-images/` → `/app/data/images/`
+   - Befüllt DB mit Event/Gallery-Einträgen
+
+## 🔍 Troubleshooting
+
+### "Bilder werden nicht angezeigt"
+
+**Prüfe:**
+1. Backend logs: `fly logs -a gallus-cms-backend`
+2. Bild existiert: `fly ssh console -a gallus-cms-backend`
+   ```bash
+   ls -la /app/data/images/gallery/
+   ```
+3. DB-Eintrag korrekt:
+   ```bash
+   sqlite3 /app/data/gallus_cms.db
+   SELECT * FROM gallery_images;
+   ```
+4. Static-Route funktioniert:
+   ```bash
+   curl https://cms.gallus-pub.ch/static/images/gallery/xyz.webp
+   ```
+
+### "SQLite locked" Fehler
+
+- Nur ein Writer zur Zeit erlaubt
+- Bei hohem Traffic: Wechsel zu PostgreSQL empfohlen
+- Für Gallus Pub: ausreichend (wenig Writes)
+
+### "Volume voll"
+
+```bash
+fly volumes list -a gallus-cms-backend
+fly volumes extend <volume-id> -s <new-size>
+```
+
+## 📁 Wichtige Dateien
+
+| Datei | Zweck |
+|-------|-------|
+| `backend/src/routes/gallery.ts` | Gallery-Upload & CRUD |
+| `backend/src/routes/events.ts` | Events CRUD + Public API |
+| `backend/src/index.ts` | Static File Serving |
+| `backend/migrate-production.js` | Initiale Daten-Migration |
+| `src/pages/admin.astro` | Admin-Interface |
+| `src/pages/index.astro` | Frontend (fetched von API) |
+| `backend/fly.toml` | Backend Fly.io Config |
+| `fly.toml` | Frontend Fly.io Config |
+
+## 🎯 Nächste Schritte
+
+1. ✅ Gallery-Verwaltung implementiert
+2. ⏳ Migration ausführen (nach Deploy)
+3. ⏳ Testen: Bild hochladen → Frontend anzeigen
+4. 📋 Optional: Image-Editing Features
+5. 📋 Optional: Bulk-Upload für Gallery
diff --git a/src/pages/admin.astro b/src/pages/admin.astro
index 8570387..c52ceab 100644
--- a/src/pages/admin.astro
+++ b/src/pages/admin.astro
@@ -68,6 +68,28 @@ const title = 'Admin';
       </div>
     </section>
 
+    <section id="sec-gallery" style="display:none">
+      <h2>Gallery verwalten</h2>
+      <div class="events-row">
+        <div class="card">
+          <h3>Neues Gallery-Bild</h3>
+          <label>Bild-Datei<input id="gal-file" type="file" accept="image/*" /></label>
+          <label>Alt-Text<input id="gal-alt" placeholder="Bildbeschreibung" /></label>
+          <button id="btn-create-gal">Bild hochladen</button>
+          <div id="gal-create-msg" class="muted"></div>
+        </div>
+        <div class="card" style="min-width:380px;">
+          <h3>Liste</h3>
+          <div class="toolbar">
+            <button id="btn-toggle-gal-reorder">Reihenfolge bearbeiten</button>
+            <button id="btn-save-gal-order" style="display:none">Reihenfolge speichern</button>
+            <span id="gal-order-msg" class="muted"></span>
+          </div>
+          <div id="gallery-list" class="grid"></div>
+        </div>
+      </div>
+    </section>
+
     <section id="sec-publish" style="display:none">
       <h2>Veröffentlichen</h2>
       <label>Commit-Message<input id="pub-msg" placeholder="Änderungen beschreiben" value="Update events" /></label>
@@ -92,9 +114,11 @@ const title = 'Admin';
           document.getElementById('auth-status').textContent = `Angemeldet als ${me.user?.giteaUsername || 'Admin'}`;
           // UI-Bereiche für eingeloggte Nutzer einblenden
           document.getElementById('sec-events').style.display = '';
+          document.getElementById('sec-gallery').style.display = '';
           document.getElementById('sec-publish').style.display = '';
           // Direkt Events laden und auf Sektion fokussieren
           await loadEvents();
+          await loadGallery();
           document.getElementById('sec-events').scrollIntoView({ behavior: 'smooth' });
         } catch (e) {
           const el = document.getElementById('auth-status');
@@ -288,6 +312,131 @@ const title = 'Admin';
         } catch(e){ msg.textContent = 'Fehler: '+e.message }
       });
 
+      // ========== Gallery Management ==========
+      let galReorderMode = false;
+      let lastGallery = [];
+
+      async function loadGallery() {
+        const listEl = document.getElementById('gallery-list');
+        listEl.innerHTML = '<div class="muted">Lade...</div>';
+        try {
+          const data = await api('/api/gallery');
+          listEl.innerHTML = '';
+          lastGallery = (data.images || []).slice();
+          let renderList = lastGallery.slice();
+
+          if (galReorderMode) {
+            renderList.sort((a,b) => (a.displayOrder??0) - (b.displayOrder??0));
+          }
+
+          renderList.forEach((img, idx) => {
+            const card = document.createElement('div');
+            card.className = 'card';
+            card.setAttribute('draggable', String(galReorderMode));
+            card.dataset.id = img.id;
+            card.dataset.displayOrder = String(img.displayOrder ?? idx);
+            card.innerHTML = `
+              <div class="row" style="justify-content:space-between;align-items:center">
+                <div><strong>${img.altText}</strong></div>
+                ${galReorderMode ? '<span class="drag-handle">⇅ Ziehen</span>' : ''}
+              </div>
+              <img src="${API_BASE}${img.imageUrl}" alt="${img.altText}" style="max-width:100%;height:auto;margin:0.5rem 0;" />
+              <div class="muted">URL: ${img.imageUrl}</div>
+              <div class="row-buttons">
+                <button data-id="${img.id}" class="btn-del-gal">Löschen</button>
+              </div>`;
+            listEl.appendChild(card);
+          });
+
+          listEl.querySelectorAll('.btn-del-gal').forEach(btn => {
+            btn.addEventListener('click', async () => {
+              const id = btn.getAttribute('data-id');
+              if (!id) return;
+              if (!confirm('Bild wirklich löschen?')) return;
+              try {
+                await api(`/api/gallery/${id}`, { method: 'DELETE' });
+                await loadGallery();
+              } catch(e){ alert('Fehler: '+e.message); }
+            })
+          })
+
+          if (galReorderMode) {
+            enableGalleryDragAndDrop(listEl);
+          }
+        } catch (e) {
+          listEl.innerHTML = '<div class="muted">Fehler beim Laden</div>';
+          console.error(e);
+        }
+      }
+
+      function enableGalleryDragAndDrop(container){
+        let draggingEl = null;
+        container.querySelectorAll('.card').forEach(card => {
+          card.addEventListener('dragstart', (e) => {
+            draggingEl = card; card.classList.add('dragging');
+            e.dataTransfer.setData('text/plain', card.dataset.id || '');
+          });
+          card.addEventListener('dragend', () => { draggingEl = null; card.classList.remove('dragging'); });
+          card.addEventListener('dragover', (e) => { e.preventDefault(); });
+          card.addEventListener('drop', (e) => {
+            e.preventDefault();
+            const target = card;
+            if (!draggingEl || draggingEl === target) return;
+            const cards = Array.from(container.querySelectorAll('.card'));
+            const draggingIdx = cards.indexOf(draggingEl);
+            const targetIdx = cards.indexOf(target);
+            if (draggingIdx < targetIdx) {
+              target.after(draggingEl);
+            } else {
+              target.before(draggingEl);
+            }
+          });
+        });
+      }
+
+      document.getElementById('btn-create-gal').addEventListener('click', async () => {
+        const file = document.getElementById('gal-file').files[0];
+        const alt = document.getElementById('gal-alt').value.trim();
+        const msg = document.getElementById('gal-create-msg');
+
+        if (!file) {
+          msg.textContent = 'Bitte wähle ein Bild aus';
+          return;
+        }
+
+        msg.textContent = 'Lade Bild hoch...';
+        try {
+          const up = await uploadImage(file, alt || 'Gallery Image');
+          msg.textContent = 'Bild hochgeladen';
+          document.getElementById('gal-file').value = '';
+          document.getElementById('gal-alt').value = '';
+          await loadGallery();
+        } catch(e){
+          msg.textContent = 'Fehler: '+e.message
+        }
+      });
+
+      document.getElementById('btn-toggle-gal-reorder').addEventListener('click', async () => {
+        galReorderMode = !galReorderMode;
+        document.getElementById('btn-save-gal-order').style.display = galReorderMode ? '' : 'none';
+        await loadGallery();
+      });
+
+      document.getElementById('btn-save-gal-order').addEventListener('click', async () => {
+        const container = document.getElementById('gallery-list');
+        const cards = Array.from(container.querySelectorAll('.card'));
+        const orders = cards.map((c, idx) => ({ id: c.dataset.id, displayOrder: idx }));
+        const msg = document.getElementById('gal-order-msg');
+        msg.textContent = 'Speichere Reihenfolge...';
+        try {
+          await api('/api/gallery/reorder', { method:'PUT', headers:{'Content-Type':'application/json'}, body: JSON.stringify({ orders }) });
+          msg.textContent = 'Reihenfolge gespeichert';
+          galReorderMode = false;
+          document.getElementById('btn-save-gal-order').style.display = 'none';
+          await loadGallery();
+        } catch(e){ msg.textContent = 'Fehler: '+e.message }
+      });
+
       refreshAuth();
     </script>
   </body>