Project-Image-Uploader/FeatureRequests/FEATURE_REQUEST-telegram.md

# 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