# Feature Plan: Telegram Bot Integration

## Übersicht

Implementierung eines Telegram Bots zur automatischen Benachrichtigung der Werkstatt-Gruppe über wichtige Events im Image Uploader System.

**Basis:** [FEATURE_REQUEST-telegram.md](./FEATURE_REQUEST-telegram.md)

---

## Phasen-Aufteilung

### Phase 1: Bot Setup & Standalone-Test
**Ziel:** Telegram Bot erstellen und isoliert testen (ohne App-Integration)

**Status:** 🟢 Abgeschlossen

**Deliverables:**
- [x] Telegram Bot via BotFather erstellt
- [x] Bot zu Test-Telegram-Gruppe hinzugefügt
- [x] Chat-ID ermittelt
- [x] `scripts/telegram-test.js` - Standalone Test-Script
- [x] `scripts/README.telegram.md` - Setup-Anleitung
- [x] `.env.telegram` - Template für Bot-Credentials
- [x] Erfolgreiche Test-Nachricht versendet

**Akzeptanzkriterium:**
✅ Bot sendet erfolgreich Nachricht an Testgruppe

---

### Phase 2: Backend-Service Integration
**Ziel:** TelegramNotificationService in Backend integrieren

**Status:** 🟢 Abgeschlossen

**Dependencies:** Phase 1 abgeschlossen

**Deliverables:**
- [x] `backend/src/services/TelegramNotificationService.js`
- [x] ENV-Variablen in `docker/dev/backend/config/.env`
- [x] Unit-Tests für Service
- [x] Docker Dev Environment funktioniert

---

### Phase 3: Upload-Benachrichtigungen
**Ziel:** Automatische Benachrichtigungen bei neuem Upload

**Status:** 🟢 Abgeschlossen

**Dependencies:** Phase 2 abgeschlossen

**Deliverables:**
- [x] Integration in `routes/batchUpload.js`
- [x] `sendUploadNotification()` Methode
- [x] Formatierung mit Icons/Emojis
- [x] Integration-Tests

---

### Phase 4: User-Änderungs-Benachrichtigungen
**Ziel:** Benachrichtigungen bei Consent-Änderungen & Löschungen

**Status:** 🟢 Abgeschlossen

**Dependencies:** Phase 3 abgeschlossen

**Deliverables:**
- [x] Integration in `routes/management.js` (PUT/DELETE)
- [x] `sendConsentChangeNotification()` Methode
- [x] `sendGroupDeletedNotification()` Methode
- [x] Integration-Tests

---

### Phase 5: Tägliche Lösch-Warnungen
**Ziel:** Cron-Job für bevorstehende Löschungen

**Status:** 🟢 Abgeschlossen

**Dependencies:** Phase 4 abgeschlossen

**Deliverables:**
- [x] Cron-Job Setup (node-cron)
- [x] `sendDeletionWarning()` Methode
- [x] Admin-Route für manuellen Trigger (`POST /api/admin/telegram/warning`)
- [x] SchedulerService Integration (09:00 daily)
- [x] Docker ENV-Variablen konfiguriert
- [x] README.md Update

---

### Phase 6: Production Deployment
**Ziel:** Rollout in Production-Umgebung + ENV-Vereinfachung

**Status:** 🟢 Abgeschlossen

**Dependencies:** Phase 1-5 abgeschlossen + getestet

**Deliverables:**
- [x] ENV-Struktur vereinfachen (zu viele .env-Dateien!)
- [x] Production ENV-Variablen in docker/prod/.env konfigurieren
- [x] docker/prod/docker-compose.yml mit Telegram-ENV erweitern
- [x] Consent-Änderung Bug Fix (platform_name statt name)
- [x] README.md Update mit ENV-Struktur Dokumentation
- ⏭️ Bot in echte Werkstatt-Gruppe einfügen (optional, bei Bedarf)
- ⏭️ Production Testing (optional, bei Bedarf)

**ENV-Vereinfachung (Abgeschlossen):**
```
Vorher: 16 .env-Dateien mit redundanter Konfiguration
Nachher: 2 zentrale .env-Dateien
  ✅ docker/dev/.env (alle dev secrets)
  ✅ docker/prod/.env (alle prod secrets)
  ✅ docker-compose.yml nutzt ${VAR} Platzhalter
  ✅ Gemountete .env-Dateien entfernt (wurden überschrieben)
  ✅ Alle ENV-Variablen in docker-compose environment
```

---

## Phase 1 - Detaillierter Plan

### 1. Vorbereitung (5 min)

**Auf Windows 11 Host-System:**

```bash
# Node.js Version prüfen
node --version  # Sollte >= 18.x sein

# Projektverzeichnis öffnen
cd /home/lotzm/gitea.hobbyhimmel/Project-Image-Uploader/scripts

# Dependencies installieren (lokal)
npm init -y  # Falls noch keine package.json
npm install node-telegram-bot-api dotenv
```

### 2. Telegram Bot erstellen (10 min)

**Anleitung:** Siehe `scripts/README.telegram.md`

**Schritte:**
1. Telegram öffnen (Windows 11 App)
2. [@BotFather](https://t.me/botfather) suchen
3. `/newbot` Command
4. Bot-Name: "Werkstatt Image Uploader Bot"
5. Username: `werkstatt_uploader_bot` (oder verfügbar)
6. **Token kopieren** → `.env.telegram`

### 3. Test-Gruppe erstellen & Bot hinzufügen (5 min)

**Schritte:**
1. Neue Telegram-Gruppe erstellen: "Werkstatt Upload Bot Test"
2. Bot zur Gruppe hinzufügen: @werkstatt_uploader_bot
3. **Chat-ID ermitteln** (siehe README.telegram.md)
4. Chat-ID speichern → `.env.telegram`

### 4. Test-Script erstellen (10 min)

**Datei:** `scripts/telegram-test.js`

**Features:**
- Lädt `.env.telegram`
- Validiert Bot-Token
- Sendet Test-Nachricht
- Error-Handling

### 5. Erste Nachricht senden (2 min)

```bash
cd scripts
node telegram-test.js
```

**Erwartete Ausgabe:**
```
✅ Telegram Bot erfolgreich verbunden!
Bot-Name: Werkstatt Image Uploader Bot
Bot-Username: @werkstatt_uploader_bot

📤 Sende Test-Nachricht an Chat -1001234567890...
✅ Nachricht erfolgreich gesendet!
```

**In Telegram-Gruppe:**
```
🤖 Telegram Bot Test

Dies ist eine Test-Nachricht vom Werkstatt Image Uploader Bot.

Status: ✅ Erfolgreich verbunden!
Zeitstempel: 2025-11-29 14:23:45
```

---

## Dateistruktur (Phase 1)

```
scripts/
├── README.telegram.md          # Setup-Anleitung (NEU)
├── telegram-test.js            # Test-Script (NEU)
├── .env.telegram.example       # ENV-Template (NEU)
├── .env.telegram               # Echte Credentials (gitignored, NEU)
├── package.json                # Lokale Dependencies (NEU)
└── node_modules/               # npm packages (gitignored)
```

---

## Environment Variables (Phase 1)

**Datei:** `scripts/.env.telegram`

```bash
# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
TELEGRAM_CHAT_ID=-1001234567890
```

---

## Dependencies (Phase 1)

**Package:** `scripts/package.json`

```json
{
  "name": "telegram-test-scripts",
  "version": "1.0.0",
  "description": "Standalone Telegram Bot Testing",
  "main": "telegram-test.js",
  "scripts": {
    "test": "node telegram-test.js"
  },
  "dependencies": {
    "node-telegram-bot-api": "^0.66.0",
    "dotenv": "^16.3.1"
  }
}
```

---

## Sicherheit (Phase 1)

**`.gitignore` ergänzen:**

```
# Telegram Credentials
scripts/.env.telegram
scripts/node_modules/
scripts/package-lock.json
```

**Wichtig:**
- ❌ Niemals `.env.telegram` committen!
- ✅ Nur `.env.telegram.example` (ohne echte Tokens) committen
- ✅ Bot-Token regenerieren, falls versehentlich exposed

---

## Testing Checklist (Phase 1)

- [x] Node.js Version >= 18.x
- [x] Telegram App installiert (Windows 11)
- [x] Bot via BotFather erstellt
- [x] Bot-Token gespeichert in `.env.telegram`
- [x] Test-Gruppe erstellt
- [x] Bot zur Gruppe hinzugefügt
- [x] Chat-ID ermittelt
- [x] Chat-ID gespeichert in `.env.telegram`
- [x] Privacy Mode deaktiviert
- [x] Test-Nachricht erfolgreich gesendet
- [ ] `npm install` erfolgreich
- [ ] `node telegram-test.js` läuft ohne Fehler
- [ ] Test-Nachricht in Telegram-Gruppe empfangen
- [ ] Formatierung (Emojis, Zeilenumbrüche) korrekt

---

## Troubleshooting (Phase 1)

### Problem: "Unauthorized (401)"
**Lösung:** Bot-Token falsch → BotFather prüfen, `.env.telegram` korrigieren

### Problem: "Bad Request: chat not found"
**Lösung:** Chat-ID falsch → Neue Nachricht in Gruppe senden, Chat-ID neu ermitteln

### Problem: "ETELEGRAM: 403 Forbidden"
**Lösung:** Bot wurde aus Gruppe entfernt → Bot erneut zur Gruppe hinzufügen

### Problem: "Module not found: node-telegram-bot-api"
**Lösung:** 
```bash
cd scripts
npm install
```

---

## Nächste Schritte (nach Phase 1)

1. **Code-Review:** `scripts/telegram-test.js`
2. **Dokumentation Review:** `scripts/README.telegram.md`
3. **Commit:** 
   ```bash
   git add scripts/
   git commit -m "feat: Add Telegram Bot standalone test (Phase 1)"
   ```
4. **Phase 2 starten:** Backend-Integration planen

---

## Zeitschätzung

| Phase | Aufwand | Beschreibung |
|-------|---------|--------------|
| **Phase 1** | **~45 min** | Bot Setup + Standalone-Test |
| Phase 2 | ~2h | Backend-Service |
| Phase 3 | ~2h | Upload-Benachrichtigungen |
| Phase 4 | ~2h | Änderungs-Benachrichtigungen |
| Phase 5 | ~2h | Cron-Job |
| Phase 6 | ~1h | Production Deployment |
| **Gesamt** | **~9-10h** | Vollständige Integration |

---

## Conventional Commits (ab Phase 1)

**Phase 1:**
```bash
git commit -m "feat: Add Telegram Bot test script"
git commit -m "docs: Add Telegram Bot setup guide"
git commit -m "chore: Add node-telegram-bot-api dependency to scripts"
```

**Phase 2:**
```bash
git commit -m "feat: Add TelegramNotificationService"
git commit -m "test: Add TelegramNotificationService unit tests"
```

**Phase 3-6:**
```bash
git commit -m "feat: Add upload notification to Telegram"
git commit -m "feat: Add consent change notifications"
git commit -m "feat: Add daily deletion warnings cron job"
git commit -m "docs: Update README with Telegram features"
```

---

## Release-Planung

**Phase 1:** Kein Release (interne Tests)

**Phase 6 (Final):**
- **Version:** `2.0.0` (Major Release)
- **Branch:** `feature/telegram-notifications`
- **Release-Command:** `npm run release:major`

---

## Status-Tracking

**Letzte Aktualisierung:** 2025-11-30

| Phase | Status | Datum |
|-------|--------|-------|
| Phase 1 | 🟢 Abgeschlossen | 2025-11-29 |
| Phase 2 | 🟢 Abgeschlossen | 2025-11-29 |
| Phase 3 | 🟢 Abgeschlossen | 2025-11-29 |
| Phase 4 | 🟢 Abgeschlossen | 2025-11-30 |
| Phase 5 | 🟢 Abgeschlossen | 2025-11-30 |
| Phase 6 | 🟡 ENV vereinfacht | 2025-11-30 |

**Legende:**
- 🟢 Abgeschlossen
- 🟡 In Arbeit
- 🔴 Blockiert
- ⚪ Ausstehend