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

# 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 ⭐ **CURRENT**
**Ziel:** Telegram Bot erstellen und isoliert testen (ohne App-Integration)

**Status:** 🟡 In Planung

**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

**Dependencies:** Phase 1 abgeschlossen

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

---

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

**Dependencies:** Phase 2 abgeschlossen

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

---

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

**Dependencies:** Phase 3 abgeschlossen

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

---

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

**Dependencies:** Phase 4 abgeschlossen

**Deliverables:**
- [ ] Cron-Job Setup (node-cron)
- [ ] `sendDeletionWarning()` Methode
- [ ] Admin-Route für manuellen Trigger
- [ ] Dokumentation

---

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

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

**Deliverables:**
- [ ] Production ENV-Variablen
- [ ] Docker Prod Environment konfiguriert
- [ ] Bot in echte Werkstatt-Gruppe eingefügt
- [ ] Monitoring/Logging
- [ ] README.md Update

---

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

- [ ] Node.js Version >= 18.x
- [ ] Telegram App installiert (Windows 11)
- [ ] Bot via BotFather erstellt
- [ ] Bot-Token gespeichert in `.env.telegram`
- [ ] Test-Gruppe erstellt
- [ ] Bot zur Gruppe hinzugefügt
- [ ] Chat-ID ermittelt
- [ ] Chat-ID gespeichert in `.env.telegram`
- [ ] `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-29

| Phase | Status | Datum |
|-------|--------|-------|
| Phase 1 | 🟡 In Planung | 2025-11-29 |
| Phase 2 | ⚪ Ausstehend | - |
| Phase 3 | ⚪ Ausstehend | - |
| Phase 4 | ⚪ Ausstehend | - |
| Phase 5 | ⚪ Ausstehend | - |
| Phase 6 | ⚪ Ausstehend | - |

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