feat: Add Telegram notification feature request and improve prod.sh Docker registry push

2025-11-29 19:28:23 +01:00 · 2025-11-29 19:28:23 +01:00 · b2386e7f11
commit b2386e7f11
parent 52125397bf
5 changed files with 481 additions and 3 deletions
--- a/FeatureRequests/FEATURE_REQUEST-telegram.md
+++ b/FeatureRequests/FEATURE_REQUEST-telegram.md
@ -0,0 +1,450 @@
+# Feature Request: Telegram Bot für Benachrichtigungen
+
+## Übersicht
+
+Integration eines Telegram Bots zur automatischen Benachrichtigung der Werkstatt-Gruppe über wichtige Events im Image Uploader System.
+
+## Ziel
+
+Werkstatt-Mitarbeiter sollen zeitnah über neue Uploads, Änderungen und bevorstehende Löschungen informiert werden, ohne ständig das Admin-Panel prüfen zu müssen.
+
+## Use Case
+
+Die Offene Werkstatt hat eine Telegram Gruppe, in der das Team kommuniziert. Der Bot wird zu dieser Gruppe hinzugefügt und sendet automatisierte Benachrichtigungen bei relevanten Events.
+
+## Funktionale Anforderungen
+
+### 1. Benachrichtigung: Neuer Upload
+
+**Trigger:** Erfolgreicher Batch-Upload über `/api/upload-batch`
+
+**Nachricht enthält:**
+- 📸 Upload-Icon
+- Name des Uploaders
+- Anzahl der hochgeladenen Bilder
+- Jahr der Gruppe
+- Titel der Gruppe
+- Workshop-Consent Status (✅ Ja / ❌ Nein)
+- Social Media Consents (Facebook, Instagram, TikTok Icons)
+- Link zum Admin-Panel (Moderation)
+
+**Beispiel:**
+```
+📸 Neuer Upload!
+
+Uploader: Max Mustermann
+Bilder: 12
+Gruppe: 2024 - Schweißkurs November
+Workshop: ✅ Ja
+Social Media: 📘 Instagram, 🎵 TikTok
+
+🔗 Zur Freigabe: https://internal.hobbyhimmel.de/moderation
+```
+
+### 2. Benachrichtigung: User-Änderungen
+
+**Trigger:** 
+- `PUT /api/manage/:token` (Consent-Änderung)
+- `DELETE /api/manage/:token/groups/:groupId` (Gruppenl löschung durch User)
+
+**Nachricht enthält:**
+- ⚙️ Änderungs-Icon
+- Art der Änderung (Consent Update / Gruppe gelöscht)
+- Betroffene Gruppe (Jahr + Titel)
+- Uploader-Name
+- Neue Consent-Werte (bei Update)
+
+**Beispiel (Consent-Änderung):**
+```
+⚙️ User-Änderung
+
+Aktion: Consent aktualisiert
+Gruppe: 2024 - Schweißkurs November
+Uploader: Max Mustermann
+
+Neu:
+Workshop: ❌ Nein (vorher: ✅)
+Social Media: 📘 Instagram (TikTok entfernt)
+
+🔗 Details: https://internal.hobbyhimmel.de/moderation
+```
+
+**Beispiel (Gruppe gelöscht):**
+```
+⚙️ User-Änderung
+
+Aktion: Gruppe gelöscht
+Gruppe: 2024 - Schweißkurs November
+Uploader: Max Mustermann
+Bilder: 12
+
+ℹ️ User hat Gruppe selbst über Management-Link gelöscht
+```
+
+### 3. Benachrichtigung: Ablauf Freigabe / Löschung in 1 Tag
+
+**Trigger:** Täglicher Cron-Job (z.B. 09:00 Uhr)
+
+**Prüfung:**
+- Alle nicht-freigegebenen Gruppen mit `created_at < NOW() - 6 days`
+- Werden in 24 Stunden durch Cleanup-Service gelöscht
+
+**Nachricht enthält:**
+- ⏰ Warnung-Icon
+- Liste aller betroffenen Gruppen
+- Countdown bis Löschung
+- Hinweis auf Freigabe-Möglichkeit
+
+**Beispiel:**
+```
+⏰ Löschung in 24 Stunden!
+
+Folgende Gruppen werden morgen automatisch gelöscht:
+
+1. 2024 - Schweißkurs November
+   Uploader: Max Mustermann
+   Bilder: 12
+   Hochgeladen: 20.11.2024
+
+2. 2024 - Holzarbeiten Workshop
+   Uploader: Anna Schmidt  
+   Bilder: 8
+   Hochgeladen: 21.11.2024
+
+💡 Jetzt freigeben oder Freigabe bleibt aus!
+🔗 Zur Moderation: https://internal.hobbyhimmel.de/moderation
+```
+
+## Technische Anforderungen
+
+### Backend-Integration
+
+**Neue Umgebungsvariablen:**
+```bash
+TELEGRAM_BOT_TOKEN=<bot-token>
+TELEGRAM_CHAT_ID=<werkstatt-gruppen-id>
+TELEGRAM_ENABLED=true
+```
+
+**Neue Service-Datei:** `backend/src/services/TelegramNotificationService.js`
+
+**Methoden:**
+- `sendUploadNotification(groupData)`
+- `sendConsentChangeNotification(oldConsents, newConsents, groupData)`
+- `sendGroupDeletedNotification(groupData)`
+- `sendDeletionWarning(groupsList)`
+
+**Integration Points:**
+- `routes/batchUpload.js` → Nach erfolgreichem Upload
+- `routes/management.js` → PUT/DELETE Endpoints
+- `services/GroupCleanupService.js` → Neue Methode für tägliche Prüfung
+
+### Telegram Bot Setup
+
+**Bot erstellen:**
+1. Mit [@BotFather](https://t.me/botfather) sprechen
+2. `/newbot` → Bot-Name: "Werkstatt Image Uploader Bot"
+3. Token speichern → `.env`
+
+**Bot zur Gruppe hinzufügen:**
+1. Bot zu Werkstatt-Gruppe einladen
+2. Chat-ID ermitteln: `https://api.telegram.org/bot<TOKEN>/getUpdates`
+3. Chat-ID speichern → `.env`
+
+**Berechtigungen:**
+- ✅ Can send messages
+- ✅ Can send photos (optional, für Vorschau-Bilder)
+- ❌ Keine Admin-Rechte nötig
+
+### Cron-Job für tägliche Prüfung
+
+**Optionen:**
+
+**A) Node-Cron (empfohlen für Development):**
+```javascript
+// backend/src/services/TelegramScheduler.js
+const cron = require('node-cron');
+
+// Jeden Tag um 09:00 Uhr
+cron.schedule('0 9 * * *', async () => {
+  await checkPendingDeletions();
+});
+```
+
+**B) System Cron (Production):**
+```bash
+# crontab -e
+0 9 * * * curl -X POST http://localhost:5000/api/admin/telegram/check-deletions
+```
+
+**Neue Route:** `POST /api/admin/telegram/check-deletions` (Admin-Auth)
+
+## Dependencies
+
+**Neue NPM Packages:**
+```json
+{
+  "node-telegram-bot-api": "^0.66.0",
+  "node-cron": "^3.0.3"
+}
+```
+
+## Konfiguration
+
+### Development (.env)
+```bash
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=-1001234567890
+TELEGRAM_ENABLED=true
+TELEGRAM_DAILY_CHECK_TIME=09:00
+```
+
+### Production
+- Gleiche Variablen in `docker/prod/backend/config/.env`
+- Cron-Job via Node-Cron oder System-Cron
+
+## Sicherheit
+
+- ✅ Bot-Token niemals committen (`.env` nur)
+- ✅ Chat-ID validieren (nur bekannte Gruppen)
+- ✅ Keine sensiblen Daten in Nachrichten (keine Email, keine vollständigen Token)
+- ✅ Rate-Limiting für Telegram API (max 30 msg/sec)
+- ✅ Error-Handling: Wenn Telegram down → Upload funktioniert trotzdem
+
+## Testing
+
+**Manuell:**
+```bash
+# Trigger Upload-Benachrichtigung
+curl -X POST http://localhost:5001/api/upload-batch \
+  -F "images=@test.jpg" \
+  -F "year=2024" \
+  -F "title=Test Upload" \
+  -F "name=Test User" \
+  -F 'consents={"workshopConsent":true,"socialMediaConsents":[]}'
+
+# Trigger Consent-Änderung
+curl -X PUT http://localhost:5001/api/manage/<TOKEN> \
+  -H "Content-Type: application/json" \
+  -d '{"workshopConsent":false,"socialMediaConsents":[]}'
+
+# Trigger tägliche Prüfung (Admin)
+curl -X POST http://localhost:5001/api/admin/telegram/check-deletions \
+  -b cookies.txt -H "X-CSRF-Token: $CSRF"
+```
+
+**Automatisiert:**
+- Unit-Tests für `TelegramNotificationService.js`
+- Mock Telegram API mit `nock`
+- Prüfe Nachrichtenformat + Escaping
+
+## Optional: Zukünftige Erweiterungen
+
+- 📊 Wöchentlicher Statistik-Report (Uploads, Freigaben, Löschungen)
+- 🖼️ Preview-Bild im Telegram (erstes Bild der Gruppe)
+- 💬 Interaktive Buttons (z.B. "Freigeben", "Ablehnen") → Webhook
+- 🔔 Admin-Befehle (`/stats`, `/pending`, `/cleanup`)
+
+## Akzeptanzkriterien
+
+- [ ] Bot sendet Nachricht bei neuem Upload
+- [ ] Bot sendet Nachricht bei Consent-Änderung  
+- [ ] Bot sendet Nachricht bei User-Löschung
+- [ ] Bot sendet tägliche Warnung für bevorstehende Löschungen (09:00 Uhr)
+- [ ] Alle Nachrichten enthalten relevante Informationen + Link
+- [ ] Telegram-Fehler brechen Upload/Änderungen nicht ab
+- [ ] ENV-Variable `TELEGRAM_ENABLED=false` deaktiviert alle Benachrichtigungen
+- [ ] README.dev.md enthält Setup-Anleitung
+
+## Aufwandsschätzung
+
+- Backend-Integration: ~4-6 Stunden
+- Cron-Job Setup: ~2 Stunden
+- Testing: ~2 Stunden
+- Dokumentation: ~1 Stunde
+
+**Gesamt: ~9-11 Stunden**
+
+## Priorität
+
+**Medium** - Verbessert Workflow, aber nicht kritisch für Kernfunktion
+
+## Release-Planung
+
+**Target Version:** `2.0.0` (Major Version)
+
+**Begründung für Major Release:**
+- Neue Infrastruktur-Abhängigkeit (Telegram Bot)
+- Neue Umgebungsvariablen erforderlich
+- Breaking Change: Optional, aber empfohlene Konfiguration
+
+## Development Workflow
+
+### 1. Feature Branch erstellen
+
+```bash
+git checkout -b feature/telegram-notifications
+```
+
+### 2. Conventional Commits verwenden
+
+**Wichtig:** Alle Commits nach [Conventional Commits](https://www.conventionalcommits.org/) formatieren!
+
+**Beispiele:**
+```bash
+git commit -m "feat: Add TelegramNotificationService"
+git commit -m "feat: Add upload notification endpoint"
+git commit -m "feat: Add daily deletion warning cron job"
+git commit -m "chore: Add node-telegram-bot-api dependency"
+git commit -m "docs: Update README with Telegram setup"
+git commit -m "test: Add TelegramNotificationService unit tests"
+git commit -m "fix: Handle Telegram API rate limiting"
+```
+
+**Commit-Typen:**
+- `feat:` - Neue Features
+- `fix:` - Bugfixes
+- `docs:` - Dokumentation
+- `test:` - Tests
+- `chore:` - Dependencies, Config
+- `refactor:` - Code-Umstrukturierung
+
+→ **Wird automatisch im CHANGELOG.md gruppiert!**
+
+### 3. Development Setup
+
+**Docker Dev Environment nutzen:**
+
+```bash
+# Container starten
+./dev.sh
+
+# .env konfigurieren (Backend)
+# docker/dev/backend/config/.env
+TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
+TELEGRAM_CHAT_ID=-1001234567890
+TELEGRAM_ENABLED=true
+TELEGRAM_DAILY_CHECK_TIME=09:00
+
+# Backend neu starten (lädt neue ENV-Variablen)
+docker compose -f docker/dev/docker-compose.yml restart backend-dev
+
+# Logs verfolgen
+docker compose -f docker/dev/docker-compose.yml logs -f backend-dev
+```
+
+**Tests ausführen:**
+```bash
+cd backend
+npm test -- tests/unit/TelegramNotificationService.test.js
+npm test -- tests/api/telegram.test.js
+```
+
+### 4. Dokumentation aktualisieren
+
+**README.md** - User-Dokumentation ergänzen:
+- [ ] Telegram-Bot Setup-Anleitung
+- [ ] Benachrichtigungs-Features beschreiben
+- [ ] ENV-Variablen dokumentieren
+
+**README.dev.md** - Development-Doku ergänzen:
+- [ ] Telegram-Bot Testing-Anleitung
+- [ ] Cron-Job Debugging
+- [ ] TelegramNotificationService API-Referenz
+- [ ] Beispiel-Curl-Commands für manuelle Trigger
+
+**Sektion in README.dev.md einfügen (z.B. nach "Cleanup-System testen"):**
+
+```markdown
+### Telegram-Benachrichtigungen testen
+
+```bash
+# Bot-Token validieren:
+curl https://api.telegram.org/bot<TOKEN>/getMe
+
+# Chat-ID ermitteln:
+curl https://api.telegram.org/bot<TOKEN>/getUpdates
+
+# Upload-Benachrichtigung testen:
+# → Einfach Upload durchführen, Telegram-Gruppe prüfen
+
+# Consent-Änderung testen:
+curl -X PUT http://localhost:5001/api/manage/<TOKEN> \
+  -H "Content-Type: application/json" \
+  -d '{"workshopConsent":false,"socialMediaConsents":[]}'
+
+# Tägliche Löschwarnung manuell triggern:
+curl -b cookies.txt -H "X-CSRF-Token: $CSRF" \
+  -X POST http://localhost:5001/api/admin/telegram/check-deletions
+```
+\`\`\`
+
+### 5. Testing Checklist
+
+- [ ] Unit-Tests für `TelegramNotificationService.js` (min. 80% Coverage)
+- [ ] Integration-Tests für alle 3 Benachrichtigungstypen
+- [ ] Manueller Test: Upload → Telegram-Nachricht kommt an
+- [ ] Manueller Test: Consent-Änderung → Telegram-Nachricht kommt an
+- [ ] Manueller Test: User-Löschung → Telegram-Nachricht kommt an
+- [ ] Manueller Test: Cron-Job (tägliche Warnung) funktioniert
+- [ ] Error-Handling: Telegram down → Upload funktioniert trotzdem
+- [ ] ENV `TELEGRAM_ENABLED=false` → Keine Nachrichten
+
+### 6. Release erstellen
+
+**Nach erfolgreicher Implementierung:**
+
+```bash
+# Alle Änderungen committen (Conventional Commits!)
+git add .
+git commit -m "feat: Complete Telegram notification system"
+
+# Feature Branch pushen
+git push origin feature/telegram-notifications
+
+# Merge in main (nach Review)
+git checkout main
+git merge feature/telegram-notifications
+
+# Major Release erstellen (2.0.0)
+npm run release:major
+
+# CHANGELOG prüfen (wurde automatisch generiert!)
+cat CHANGELOG.md
+
+# Push mit Tags
+git push --follow-tags
+
+# Docker Images bauen und pushen
+./prod.sh  # Option 3
+```
+
+**Release Notes (automatisch in CHANGELOG.md):**
+- ✨ Features: Telegram-Bot Integration (Upload, Änderungen, Lösch-Warnungen)
+- 📚 Documentation: README.md + README.dev.md Updates
+- 🧪 Tests: TelegramNotificationService Tests
+
+### 7. Deployment
+
+**Production .env updaten:**
+```bash
+# docker/prod/backend/config/.env
+TELEGRAM_BOT_TOKEN=<production-token>
+TELEGRAM_CHAT_ID=<production-chat-id>
+TELEGRAM_ENABLED=true
+```
+
+**Container neu starten:**
+```bash
+./prod.sh  # Option 4: Container neu bauen und starten
+```
+
+## Wichtige Hinweise
+
+⚠️ **Vor dem Release prüfen:**
+- README.md enthält User-Setup-Anleitung
+- README.dev.md enthält Developer-Anleitung
+- Alle Tests bestehen (`npm test`)
+- Docker Dev Setup funktioniert
+- Conventional Commits verwendet
+- CHANGELOG.md ist korrekt generiert
--- a/FeatureRequests/done/FEATURE_PLAN-FrontendPublic.md
+++ b/FeatureRequests/done/FEATURE_PLAN-FrontendPublic.md
--- a/FeatureRequests/done/FEATURE_REQUEST-FrontendPublic.md
+++ b/FeatureRequests/done/FEATURE_REQUEST-FrontendPublic.md
--- a/TODO.md
+++ b/TODO.md
@ -101,7 +101,7 @@ Neue Struktur: Datenbank in src/data/db und bilder in src/data/images
 [x] 🎨 Drag & Drop Reihenfolge ändern
 [x] 📊 Upload-Progress mit Details
 [x] 🖼️ Thumbnail-Navigation in Slideshow
-[ ] 🔄 Batch-Operations (alle entfernen, etc.)
+

 ### Future Features
 - 👤 User-Management
--- a/prod.sh
+++ b/prod.sh
@ -52,8 +52,36 @@ case $choice in
        ;;
    3)
        echo -e "${GREEN}Pushe Production Images zur Registry...${NC}"
-        docker compose -f docker/prod/docker-compose.yml push
-        echo -e "${GREEN}Production Images erfolgreich gepusht!${NC}"
+        
+        # Hole aktuelle Version aus package.json
+        VERSION=$(node -p "require('./frontend/package.json').version")
+        REGISTRY="gitea.lan.hobbyhimmel.de/hobbyhimmel"
+        echo -e "${BLUE}Aktuelle Version: ${VERSION}${NC}"
+        echo -e "${BLUE}Registry: ${REGISTRY}${NC}"
+        
+        # Baue Images mit korrekter Version
+        echo -e "${BLUE}Baue Images mit Version ${VERSION}...${NC}"
+        cd docker/prod
+        docker build -t ${REGISTRY}/image-uploader-frontend:${VERSION} -f frontend/Dockerfile ../../
+        docker build -t ${REGISTRY}/image-uploader-backend:${VERSION} -f backend/Dockerfile ../../
+        
+        # Tag als 'latest'
+        docker tag ${REGISTRY}/image-uploader-frontend:${VERSION} ${REGISTRY}/image-uploader-frontend:latest
+        docker tag ${REGISTRY}/image-uploader-backend:${VERSION} ${REGISTRY}/image-uploader-backend:latest
+        
+        # Push Images (max-concurrent-uploads=1 in Docker Desktop gesetzt)
+        echo -e "${BLUE}Pushe Frontend ${VERSION}...${NC}"
+        docker push ${REGISTRY}/image-uploader-frontend:${VERSION}
+        echo -e "${BLUE}Pushe Frontend latest...${NC}"
+        docker push ${REGISTRY}/image-uploader-frontend:latest
+        
+        echo -e "${BLUE}Pushe Backend ${VERSION}...${NC}"
+        docker push ${REGISTRY}/image-uploader-backend:${VERSION}
+        echo -e "${BLUE}Pushe Backend latest...${NC}"
+        docker push ${REGISTRY}/image-uploader-backend:latest
+        
+        cd ../..
+        echo -e "${GREEN}✓ Images v${VERSION} und latest erfolgreich gepusht!${NC}"
        ;;
    4)
        echo -e "${GREEN}Baue Container neu...${NC}"