From b2386e7f113feb964d75101937798c0fd37f15d6 Mon Sep 17 00:00:00 2001 From: "matthias.lotz" Date: Sat, 29 Nov 2025 19:28:23 +0100 Subject: [PATCH] feat: Add Telegram notification feature request and improve prod.sh Docker registry push --- FeatureRequests/FEATURE_REQUEST-telegram.md | 450 ++++++++++++++++++ .../{ => done}/FEATURE_PLAN-FrontendPublic.md | 0 .../FEATURE_REQUEST-FrontendPublic.md | 0 TODO.md | 2 +- prod.sh | 32 +- 5 files changed, 481 insertions(+), 3 deletions(-) create mode 100644 FeatureRequests/FEATURE_REQUEST-telegram.md rename FeatureRequests/{ => done}/FEATURE_PLAN-FrontendPublic.md (100%) rename FeatureRequests/{ => done}/FEATURE_REQUEST-FrontendPublic.md (100%) diff --git a/FeatureRequests/FEATURE_REQUEST-telegram.md b/FeatureRequests/FEATURE_REQUEST-telegram.md new file mode 100644 index 0000000..771ae8d --- /dev/null +++ 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= +TELEGRAM_CHAT_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/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/ \ + -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/getMe + +# Chat-ID ermitteln: +curl https://api.telegram.org/bot/getUpdates + +# Upload-Benachrichtigung testen: +# → Einfach Upload durchführen, Telegram-Gruppe prüfen + +# Consent-Änderung testen: +curl -X PUT http://localhost:5001/api/manage/ \ + -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= +TELEGRAM_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 diff --git a/FeatureRequests/FEATURE_PLAN-FrontendPublic.md b/FeatureRequests/done/FEATURE_PLAN-FrontendPublic.md similarity index 100% rename from FeatureRequests/FEATURE_PLAN-FrontendPublic.md rename to FeatureRequests/done/FEATURE_PLAN-FrontendPublic.md diff --git a/FeatureRequests/FEATURE_REQUEST-FrontendPublic.md b/FeatureRequests/done/FEATURE_REQUEST-FrontendPublic.md similarity index 100% rename from FeatureRequests/FEATURE_REQUEST-FrontendPublic.md rename to FeatureRequests/done/FEATURE_REQUEST-FrontendPublic.md diff --git a/TODO.md b/TODO.md index 48563bf..e53bc57 100644 --- 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 diff --git a/prod.sh b/prod.sh index 979b56f..c821aac 100755 --- 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}"