matthias.lotz 2acbc4e248 docs: Moved finisched FeatureRequest, Update README.md

2025-11-30 17:36:54 +01:00

12 KiB

Raw Blame History

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:

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:

Mit @BotFather sprechen
/newbot → Bot-Name: "Werkstatt Image Uploader Bot"
Token speichern → .env

Bot zur Gruppe hinzufügen:

Bot zu Werkstatt-Gruppe einladen
Chat-ID ermitteln: https://api.telegram.org/bot<TOKEN>/getUpdates
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):

// 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):

# 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:

{
  "node-telegram-bot-api": "^0.66.0",
  "node-cron": "^3.0.3"
}

Konfiguration

Development (.env)

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:

# 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

git checkout -b feature/telegram-notifications

2. Conventional Commits verwenden

Wichtig: Alle Commits nach Conventional Commits formatieren!

Beispiele:

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:

# 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:

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"):

### 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:

# 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:

# docker/prod/backend/config/.env
TELEGRAM_BOT_TOKEN=<production-token>
TELEGRAM_CHAT_ID=<production-chat-id>
TELEGRAM_ENABLED=true

Container neu starten:

./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

12 KiB Raw Blame History Unescape Escape

Feature Request: Telegram Bot für Benachrichtigungen

Übersicht

Ziel

Use Case

Funktionale Anforderungen

1. Benachrichtigung: Neuer Upload

2. Benachrichtigung: User-Änderungen

3. Benachrichtigung: Ablauf Freigabe / Löschung in 1 Tag

Technische Anforderungen

Backend-Integration

Telegram Bot Setup

Cron-Job für tägliche Prüfung

Dependencies

Konfiguration

Development (.env)

Production

Sicherheit

Testing

Optional: Zukünftige Erweiterungen

Akzeptanzkriterien

Aufwandsschätzung

Priorität

Release-Planung

Development Workflow

1. Feature Branch erstellen

2. Conventional Commits verwenden

3. Development Setup

4. Dokumentation aktualisieren

5. Testing Checklist

6. Release erstellen

7. Deployment

Wichtige Hinweise

12 KiB

Raw Blame History