matthias.lotz
6b603112de
- Docker Structure: Neue ENV-Verwaltung erklärt (2 zentrale .env Dateien) - Environment Variables: Vollständige Tabelle mit allen Variablen - Telegram-Konfiguration dokumentiert - Phase 6 als abgeschlossen markiert in FEATURE_PLAN-telegram.md
386 lines
9.5 KiB
Markdown
386 lines
9.5 KiB
Markdown
# 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
|