Todo für Satellitenüberflüge Telegram erweitert

todo.md

@@ -31,4 +31,110 @@ Größe bei gegebener Entfernung
 scheinbarer Winkel in reale Größe und zurück
 
 Geschwindigkeit / Raumfahrt
-km/s, AE/Tag, Prozent von c
+km/s, AE/Tag, Prozent von c
+
+
+# TODO Telegram Satelliten-Abo
+- Ziel: Ein Benutzer soll für seinen Favoriten-Satelliten eine Telegram-Nachricht abonnieren können, wenn am Abend ein guter Überflug bevorsteht.
+- Definition „guter Überflug“ für die erste Version:
+  - Satellit ist sichtbar
+  - Himmel ist dunkel genug
+  - maximale Höhe ist groß genug
+  - optional später zusätzlich Helligkeit / Sichtbarkeits-Score
+
+- Grundentscheidung:
+  - Überflüge nicht bei jedem Telegram-Cron-Lauf live neu berechnen
+  - stattdessen vorberechnen, in der Datenbank zwischenspeichern und aus diesem Bestand Benachrichtigungen versenden
+  - vorhandene Tabelle `sat_pass_predictions` dafür nutzen und erweitern
+
+- Datenbank:
+  - `app_user_satellites` erweitern um:
+    - `telegram_evening_alert_enabled` `tinyint(1) not null default 0`
+    - optional später:
+      - `telegram_min_elevation` `decimal(5,2) null`
+      - `telegram_min_score` `decimal(5,2) null`
+      - `telegram_darkness_only` `tinyint(1) not null default 1`
+  - `sat_pass_predictions` erweitern um:
+    - `visibility_score` `decimal(5,2) null`
+    - `peak_magnitude` `decimal(5,2) null`
+    - `sun_altitude_deg` `decimal(5,2) null`
+    - `is_dark_enough` `tinyint(1) not null default 0`
+    - `alert_eligible` `tinyint(1) not null default 0`
+    - `alert_sent_at` `datetime null`
+    - optional `alert_message_hash` `varchar(64) null` zur Deduplizierung
+
+- UI / Benutzerseite:
+  - in `my_favorites.php` beim Favoriten-Satelliten einen Schalter ergänzen:
+    - „Telegram bei gutem Abendüberflug“
+  - nur aktivierbar, wenn:
+    - Telegram mit dem Benutzerkonto verbunden ist
+    - ein Favoritensatellit gesetzt ist
+    - ein Standard-Standort vorhanden ist
+  - optional später kleine Erklärung daneben:
+    - „Benachrichtigt nur bei dunklem Himmel und ausreichend hoher Passage“
+
+- Berechnung:
+  - neue Hilfsfunktion für Favoriten-Satelliten-Überflüge bauen
+  - Grundlage ist die bestehende Logik aus `satellitenhimmel.php`
+  - nur berechnen für:
+    - Benutzer mit `telegram_chat_id`
+    - Benutzer mit aktiviertem Satelliten-Abo
+    - den als Favorit markierten Satelliten
+    - den Standard-Standort des Benutzers
+  - Zeitfenster für die erste Version:
+    - heute Abend und die kommende Nacht
+    - optional zusätzlich schon der nächste Abend
+
+- Bewertung „gut genug“ in Version 1:
+  - `is_visible = 1`
+  - `sun_altitude_deg <= -8` oder besser `<= -10`
+  - `max_elevation >= 25°` oder `>= 30°`
+  - wenn vorhanden zusätzlich `visibility_score >= 0.55`
+  - diese Schwellwerte erstmal zentral im Code halten, noch nicht pro Benutzer konfigurierbar
+
+- Telegram-Cron:
+  - neuen Task ergänzen:
+    - `prepare_satellite_evening_alerts`
+    - berechnet und aktualisiert vorbereitete gute Überflüge
+  - empfohlenes Timing:
+    - nachmittags und am frühen Abend
+    - Beispiel: alle 30 oder 60 Minuten
+  - zweiten Task ergänzen:
+    - `send_satellite_evening_alerts`
+    - versendet nur Einträge mit `alert_eligible = 1` und `alert_sent_at is null`
+  - nach erfolgreichem Versand:
+    - `alert_sent_at = now()`
+
+- Nachrichtentext:
+  - kurz und direkt
+  - Beispiel:
+    - `ISS heute 21:43 bis 21:49 Uhr`
+    - `Maximale Höhe 62°`
+    - `Sichtbar bei dunklem Himmel`
+    - `Richtung: Westen nach Südosten`
+  - optional später mit Emoji oder Score, aber erstmal schlicht halten
+
+- Deduplizierung:
+  - pro Benutzer und Überflug nur genau eine Nachricht senden
+  - Grundlage:
+    - `user_id`
+    - `satellite_id`
+    - `aos_utc`
+  - vorhandener Unique-Key in `sat_pass_predictions` hilft bereits
+  - Versand zusätzlich über `alert_sent_at` absichern
+
+- Offene Umsetzungsreihenfolge:
+  - 1. Datenbankfelder erweitern
+  - 2. UI-Schalter in `my_favorites.php`
+  - 3. Vorberechnungslogik für Favoriten-Satelliten auslagern
+  - 4. Task `prepare_satellite_evening_alerts`
+  - 5. Task `send_satellite_evening_alerts`
+  - 6. Telegram-Nachrichtentext bauen
+  - 7. Test mit einem Benutzer und einem Favoriten-Satelliten
+
+- Wichtige Entscheidung für später:
+  - wenn das stabil läuft, kann daraus auch ein allgemeines Satelliten-Abo für mehrere Satelliten werden
+  - für die erste Version aber bewusst nur:
+    - ein Favorit
+    - ein Standort
+    - eine Abendbenachrichtigung