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

---

Phasen-Aufteilung

Phase 1: Bot Setup & Standalone-Test

Ziel: Telegram Bot erstellen und isoliert testen (ohne App-Integration)

Status: 🟢 Abgeschlossen

Deliverables:

• Telegram Bot via BotFather erstellt
• Bot zu Test-Telegram-Gruppe hinzugefügt
• Chat-ID ermittelt
• scripts/telegram-test.js - Standalone Test-Script
• scripts/README.telegram.md - Setup-Anleitung
• .env.telegram - Template für Bot-Credentials
• 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:

• 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

Status: 🟢 Abgeschlossen

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

Status: 🟢 Abgeschlossen

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

Status: 🟢 Abgeschlossen

Dependencies: Phase 4 abgeschlossen

Deliverables:

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

---

Phase 6: Production Deployment

Ziel: Rollout in Production-Umgebung + ENV-Vereinfachung

Status: 🟢 Abgeschlossen

Dependencies: Phase 1-5 abgeschlossen + getestet

Deliverables:

• ENV-Struktur vereinfachen (zu viele .env-Dateien!)
• Production ENV-Variablen in docker/prod/.env konfigurieren
• docker/prod/docker-compose.yml mit Telegram-ENV erweitern
• Consent-Änderung Bug Fix (platform_name statt name)
• 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:

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

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

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

---

Dependencies (Phase 1)

Package: scripts/package.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
• Privacy Mode deaktiviert
• 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:

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:

   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:

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:

git commit -m "feat: Add TelegramNotificationService"
git commit -m "test: Add TelegramNotificationService unit tests"

Phase 3-6:

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