homelab-brain/fuenfvoracht/STATE.md

# STATE: FünfVorAcht
**Stand: 26.02.2026**

---

## Projektübersicht

**Zweck:** KI-gestützter Telegram-Kanal-Poster für die tägliche Reihe "Fünf vor Acht"
**Posting-Zeit:** 19:55 Uhr (Europe/Berlin) — pro Artikel individuell konfigurierbar
**Kanal:** Privater Kanal (`-1001285446620`)
**Status:** ✅ Produktiv seit 24.02.2026

---

## Aktiver Zustand

### Container-Landschaft

| CT | Dienst | Status | Tailscale |
|----|--------|--------|-----------|
| 112 | FünfVorAcht (Bot + Dashboard) | ✅ Läuft | 100.73.171.62 |

---

## Architektur

### Stack (CT 112 auf pve-hetzner)
- **Sprache:** Python 3.11
- **Bot-Framework:** python-telegram-bot
- **KI:** OpenRouter API (GPT-4o-mini, konfigurierbar)
- **Scheduler:** APScheduler (jede Minute für Posting, alle 5 Min für Notify-Check)
- **DB:** SQLite mit WAL-Modus
- **Dashboard:** Flask + Tailwind CSS (self-hosted, kein CDN)
- **Deployment:** Docker Compose (2 Container: bot + web)
- **Logging:** JSON-Lines nach `/logs/fuenfvoracht.log`

### Workflow

```
Redakteur gibt Quelle/Thema ein
        ↓
KI generiert Artikel (OpenRouter)
        ↓
Redigieren im Dashboard + Telegram-Vorschau
        ↓
Einplanen: Datum + 15-Min-Zeitslot + Bot-Benachrichtigungszeit
        ↓
Scheduler schickt Review an alle Redakteure (notify_at)
        ↓
[✅ Freigeben] [✏️ Bearbeiten]
        ↓
APScheduler postet automatisch zum Zeitslot
        ↓
Bestätigung + Markenzeichen automatisch angehängt
```

---

## Pfade & Konfiguration

| Was | Pfad |
|-----|------|
| App-Verzeichnis | /opt/fuenfvoracht/ |
| Docker Compose | /opt/fuenfvoracht/docker-compose.yml |
| Datenbank | /opt/fuenfvoracht/data/fuenfvoracht.db |
| Logs (JSON) | /opt/fuenfvoracht/logs/fuenfvoracht.log |
| Prompts | In SQLite DB (Tabelle: prompts) |
| Tailwind CSS | Im Docker-Image gebaut (/app/static/tailwind.min.css) |

---

## Datenbank-Schema

### Tabellen

| Tabelle | Zweck |
|---------|-------|
| articles | Artikel-Queue mit `date + post_time` als Unique-Key |
| article_versions | Alle Versionen bei Neu-Generierung |
| post_history | Posting-Log mit Channel-Message-IDs |
| prompts | KI-Prompt-Bibliothek (editierbar) |
| sources_favorites | Gespeicherte Quellen-Favoriten |
| tags | Themen-Kategorien |
| article_tags | Artikel ↔ Tags (n:m) |
| channels | Kanal-Konfiguration (Zeit, Timezone) |
| locations | Aufenthaltsorte mit Reminder-Zeiten |
| settings | Schlüssel-Wert-Paare (z.B. user_location_id) |
| reviewers | Redakteure (chat_id, name, active) |

### Article-Status-Lifecycle
```
draft → scheduled → sent_to_bot → approved → posted
      ↘ rejected
      ↘ skipped
      ↘ pending_review
```

### Zeitslot-System
- `UNIQUE(date, post_time)` — Konflikte technisch ausgeschlossen
- `post_time` im 15-Minuten-Raster (06:00, 06:15, … 23:45)
- `notify_at` — UTC-Timestamp wann der Review-Bot benachrichtigt
- `scheduled_at` — wann der Artikel eingeplant wurde

---

## Telegram-Setup

| Was | Wert |
|-----|------|
| Review-Bot Token | 8799990587:AAEoQuohGdoJ2WudoOHs_j5Ns3iwft6OlFc |
| Review-Bot Name | @Diendemleben_bot |
| Kanal-ID | -1001285446620 |
| Redakteur 1 | Chat-ID 674951792 |
| Redakteur 2 | Chat-ID 1329146910 |

---

## Dashboard-Features

- **Studio:** Artikel generieren, redigieren, Telegram-Vorschau in Echtzeit
- **Einplan-Panel:** Datum + 15-Min-Zeitslot + Bot-Benachrichtigungszeit
- **Redaktionsplan:** Nächste 7 Tage, mehrere Slots pro Tag, Umplanen + Löschen direkt im Board
- **Monatskalender:** Status-Dots pro Tag
- **Prompt-Editor:** Bearbeiten + Test mit Telegram-Preview
- **History:** Alle Posts der letzten 30 Tage
- **Quellen-Favoriten:** Häufig genutzte Quellen
- **Redakteure-Verwaltung:** Hinzufügen/Entfernen per Chat-ID
- **Aufenthaltsort-Schalter:** Reminder-Zeiten automatisch auf MEZ umgerechnet
- **Anleitung (/hilfe):** 6 Aufgabenbereiche mit Klickpfaden

---

## Bot-Features

| Feature | Details |
|---------|---------|
| `/start` | Übersicht & Befehle (alle Redakteure) |
| `/heute` | Alle Slots des heutigen Tages |
| `/queue` | Nächste 3 Tage mit Slots |
| `/skip` | Hauptslot heute überspringen |
| Inline-Review | ✅ Freigeben / ✏️ Bearbeiten |
| Morgen-Briefing | 10:00 MEZ: Tagesplan + Ausblick 3 Tage |
| Nachmittags-Reminder | 18:00 MEZ: Warnung wenn nicht freigegeben |
| Fehler-Alarm | Sofort bei Posting-Fehler: Ursache + Dashboard-Link |
| Willkommensnachricht | Automatisch bei neuem Redakteur |

---

## Markenzeichen (automatisch)

Wird unter **jeden** Beitrag angehängt (Duplikat-Schutz aktiv):
```
Wir schützen die Zukunft unserer Kinder und das Leben❤️

Pax et Lux Terranaut01 https://t.me/DieneDemLeben

Unterstützt die Menschen, die für Uns einstehen❗️
```

---

## Logging

Strukturiertes JSON-Logging nach `/logs/fuenfvoracht.log`:
```json
{"ts": "2026-02-26T14:46:19Z", "level": "INFO", "event": "article_posted", "date": "2026-02-26", "post_time": "19:55", ...}
```

Events: `article_generated`, `article_saved`, `article_scheduled`, `article_sent_to_bot`, `article_approved`, `article_posted`, `article_skipped`, `posting_failed`, `reviewer_added`, `reviewer_removed`, `slot_conflict`, `bot_started`, `morning_briefing_sent`

---

## Routing

- Dashboard: `https://fuenfvoracht.orbitalo.net` (Cloudflare Tunnel)
- Lokal: `http://100.73.171.62:8080`
- Login: Holgerhh / ddlhh
- Kein öffentlicher Zugriff außer via Cloudflare Tunnel

---

## Offene Punkte / TODOs

- [ ] 15-Min-Einplan-Panel in Dashboard-UI integrieren (API vorhanden)
- [ ] Board: Umplanen/Löschen Buttons in index.html
- [ ] Redakteure-Verwaltung in settings.html
- [ ] Kanal-ID in Settings-UI editierbar
- [ ] Media-Einbettung im Editor (Video/Link Drag & Drop)
- [ ] Letzter-Post Zeitstempel im Dashboard anzeigen