From 18b633afa3be8d38008b2a394262353af3d02451 Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Wed, 17 Jun 2026 18:31:47 +0200 Subject: [PATCH] =?UTF-8?q?Brettspiel=20News=20Logo=20in=20Header=20+=20Pr?= =?UTF-8?q?ojekt-Briefing=20f=C3=BCr=20Wolfi?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Logo (993x217) als Base64 in public_frontend() und public_detail() - Ersetzt đŸŽČ BSN Community Text-Logo durch Brettspiel News Bild-Logo - PROJEKT-BRIEFING.md: VollstĂ€ndige Projektdokumentation fĂŒr AGB/Datenschutz - Architektur, DatenflĂŒsse, DSGVO-Relevanz, Feature-Stand --- PROJEKT-BRIEFING.md | 290 ++++++++++++++++++++++++++++++++++++++++++++ app.py | 3 +- 2 files changed, 291 insertions(+), 2 deletions(-) create mode 100644 PROJEKT-BRIEFING.md diff --git a/PROJEKT-BRIEFING.md b/PROJEKT-BRIEFING.md new file mode 100644 index 0000000..85e08ad --- /dev/null +++ b/PROJEKT-BRIEFING.md @@ -0,0 +1,290 @@ +# BSN-Chatsystem — Projekt-Briefing + +> **Stand:** 17. Juni 2026 +> **Betreiber:** Daniel Krause, brettspiel-news.de +> **Zweck dieses Dokuments:** VollstĂ€ndige Übersicht fĂŒr die Erstellung von AGB, DatenschutzerklĂ€rung und rechtlichen Dokumenten durch Wolfi. + +--- + +## 1. ProjektĂŒberblick + +Das **BSN-Chatsystem** („BSN Community — Stimmen aus der Szene“) ist ein **Multi-Channel-Intake-System** fĂŒr die Brettspiel-Community. Besucher können ĂŒber verschiedene KanĂ€le (WhatsApp, Web-Formular) Texte, Fotos, Videos und Sprachnachrichten einreichen — rund um Brettspiele, insbesondere zur SPIEL Essen. + +Die Redaktion (brettspiel-news.de) sichtet die Einreichungen, reichert sie mit KI-UnterstĂŒtzung an (Zusammenfassung, Hallen-Erkennung, Spieltitel-Erkennung) und veröffentlicht ausgewĂ€hlte BeitrĂ€ge auf einer öffentlichen Frontend-Seite. + +ZusĂ€tzlich gibt es einen **KI-Chat-Assistenten**, der Besucherfragen auf Basis der veröffentlichten Inhalte beantwortet. + +**URLs:** +- Öffentliches Frontend: `https://chat.datenhimmel.work/` +- Admin-Dashboard: `https://chat.datenhimmel.work/admin` +- WhatsApp-Kontakt: +1 (555) 238-5591 (Meta-Testnummer) + +--- + +## 2. Architektur + +``` +WhatsApp ──→ Meta Cloud API ──→ cloudflared Tunnel ──→ Flask :5002 ──→ SQLite +Web-Formular ─────────────────────────────────────────────┘ + │ + ┌──────┮──────┐ + │ Admin │ /admin + │ Frontend │ / + │ Detail │ /beitrag/ + │ Chat-API │ /api/chat + │ Submit-API │ /api/submit + └─────────────┘ +``` + +### Technologie-Stack + +| Komponente | Technologie | +|---|---| +| Webserver | Flask (Python), Port 5002 | +| Datenbank | SQLite (`bsn_intake.db`) | +| Tunnel | cloudflared (token-basiert, permanent) | +| KI-Modelle | DeepSeek V4 Flash (Zusammenfassung), faster-whisper (Transkription) | +| TTS | Piper TTS (de_DE-thorsten-medium) fĂŒr WhatsApp-Sprachnachrichten | +| Frontend | Vanilla HTML/CSS/JS, Masonry-Layout, iOS-26-Design | +| Hosting | 4-Kern AMD EPYC, 8 GB RAM, 250 GB Disk, Linux | + +--- + +## 3. KanĂ€le & Funktionen + +### 3.1 WhatsApp-Intake + +- **Webhook:** Meta Cloud API → `POST /whatsapp/webhook` +- **UnterstĂŒtzte Formate:** Text, Bilder, Sprachnachrichten, Videos +- **Auto-Reply:** + - **Neuer Nutzer (erster Kontakt):** AusfĂŒhrliche Willkommensnachricht mit ErklĂ€rung, DSGVO-Hinweis, TTS-Sprachnachricht (Piper Thorsten) + - **Bestehender Nutzer (neuer Thread):** Kurze Dankesnachricht + - **Thread-Fortsetzung (innerhalb 5 Min.):** Keine Antwort, Nachricht wird an bestehenden Thread angehĂ€ngt +- **Transkription:** Sprachnachrichten und Videos werden automatisch mit faster-whisper transkribiert +- **KI-Anreicherung:** Nach Transkription automatische Zusammenfassung + Hallen/Stand-Erkennung via DeepSeek V4 Flash +- **Medien-Download:** Bilder, Audio, Video werden von Meta-Servern heruntergeladen und lokal gespeichert + +### 3.2 Web-Submit-Formular + +- **Zugang:** Floating „+“-Button auf dem öffentlichen Frontend +- **Eingabefelder:** + - Name (optional, Vorname/Spitzname) + - Nachricht (optional, max. 5.000 Zeichen) + - Medien-Upload: Foto (Kamera), Video (Kamera), Audio (Mikrofon), Galerie + - Halle/Stand (optional) + - Spieltitel (optional) +- **Capture-Buttons:** Mobile-First — direkter Kamera-/Mikrofon-Zugriff ohne Galerie-Umweg +- **BestĂ€tigung:** Nach erfolgreicher Einreichung wird eine **Referenz-ID** angezeigt, die fĂŒr spĂ€tere LöschantrĂ€ge notiert werden soll +- **KI-Anreicherung:** Automatische LLM-Zusammenfassung + Hallen-Erkennung im Hintergrund +- **Speicherung:** `channel='web'`, `status='new'` + +### 3.3 Admin-Dashboard (`/admin`) + +- **Zugang:** Aktuell ungeschĂŒtzt (lokal); auf dem Server ĂŒber den cloudflared-Tunnel erreichbar +- **Funktionen:** + - Tabellarische Übersicht aller Einreichungen + - Filterung nach Status (Neu, Publiziert, Markiert) per Pill-Buttons + - Detailansicht pro Einreichung (`/submission/`): + - Absender, Typ, Inhalt, Status, Kategorie + - Medien-Vorschau (Bilder, Videos, Audio) + - **Per-Media-Veröffentlichungs-Checkboxen** (Toggle-Switches) + - **Inline-Editing:** Spieltitel, Zusammenfassung, Halle, Veröffentlichungsname + - **LLM-Zusammenfassung-Button** (KI-generierte 2–3-Satz-Zusammenfassung) + - **Veröffentlichen-Button** (Status: `new` → `published`) + - **Veröffentlichung-zurĂŒcknehmen-Button** (Status: `published` → `new`) + - **Erledigt-Button** (Status: `new` → `done`) + - **Löschen-Button** (mit BestĂ€tigungsdialog, löscht Medien + DB-Eintrag hart) + - iOS-26-Design: Dark/Light-Theme, Glass-Header, Pill-Buttons, Mobile-Bottom-Bar + - Auto-Refresh alle 30 Sekunden + - Theme-Toggle (🌓) mit localStorage-Persistenz + +### 3.4 Öffentliches Frontend (`/`) + +- **Design:** SPIEL Essen inspiriert, gelber Hintergrund (#FCE812), Masonry-Layout +- **Anzeige:** Nur veröffentlichte BeitrĂ€ge (`status='published'`, `deleted_at IS NULL`) +- **Karten:** + - Bild/Video-Karten: Medien-Vorschau mit Frosted-Glass-Timestamp + - Text-Karten: Kompakt, 4-Zeilen-Preview + - Badges: 📍 Halle, đŸš« AUSVERKAUFT +- **Filter:** Dropdown-Filter fĂŒr Halle (H1–H7) und Kategorie +- **Detailseite:** `/beitrag/` — vollstĂ€ndiger Beitrag mit Medien, Metadaten, Beitrags-ID (fĂŒr DSGVO-LöschantrĂ€ge) +- **Floating Buttons:** + - 💬 Chat-Bubble (BSN Assistant) + - ➕ Submit-Button (Einreich-Formular) + +### 3.5 Chat-Assistant (`/api/chat`) + +- **Typ:** Read-Only — beantwortet Fragen nur auf Basis veröffentlichter BeitrĂ€ge +- **Modell:** DeepSeek V4 Flash +- **Kontext:** Bis zu 60 aktuellste veröffentlichte BeitrĂ€ge +- **Sicherheit:** + - Kein Zugriff auf Rohdaten + - Antwortet nur aus dem Kontext + - Ehrlichkeits-Prompt: „Dazu habe ich leider keine Informationen“ bei Unbekanntem +- **Frontend:** Chat-Overlay mit Nachrichten-Bubbles, TTS-Button (Web Speech API, Deutsch), Typing-Indikator + +--- + +## 4. Datenverarbeitung + +### 4.1 Gespeicherte Daten pro Einreichung (`submissions`-Tabelle) + +| Feld | Beschreibung | Personenbezug | +|---|---|---| +| `id` | Fortlaufende Nummer | Nein | +| `channel` | Kanal (`whatsapp`, `web`) | Nein | +| `sender_id` | WhatsApp-Nummer oder `web_` | **Ja** (Telefonnummer bei WhatsApp) | +| `sender_name` | WhatsApp-Profilname (automatisch) | **Ja** | +| `type` | `text`, `image`, `audio`, `video`, `document` | Nein | +| `content` | Nachrichtentext / Transkription | **Ja** (Inhalt) | +| `media_path` | Pfade zu gespeicherten Mediendateien | **Ja** (Bilder, Audio, Video) | +| `media_publish_flags` | Pro-Medium 0/1 (welche Medien öffentlich) | Nein | +| `status` | `new`, `done`, `published`, `flagged`, `gdpr_deleted` | Nein | +| `category` | KI-klassifizierte Kategorie | Nein | +| `summary` | KI-generierte Zusammenfassung | Nein | +| `publish_name` | Name zur Veröffentlichung (nur mit Einwilligung) | **Ja** | +| `halle` | Extrahierte Hallen/Stand-Info | Nein | +| `spiel_titel` | Extrahierter Spieltitel | Nein | +| `published_at` | Veröffentlichungszeitpunkt | Nein | +| `deleted_at` | Soft-Delete-Zeitpunkt | Nein | +| `created_at` | Erstellungszeitpunkt | Nein | + +### 4.2 Einwilligung (Consent) + +- **WhatsApp:** Der erste Kontakt erhĂ€lt eine Nachricht, die erklĂ€rt, dass das Nennen des Vornamens die Einwilligung zur Namensnennung als Quelle darstellt. Ohne Name = „anonyme Quelle“. +- **Web-Formular:** Name ist optional. Wird ein Name angegeben, gilt dies als Einwilligung zur Nennung. +- **Keine Checkbox:** Die Einwilligung erfolgt konkludent durch die freiwillige Angabe des Namens. + +### 4.3 DSGVO-Löschung + +- **WhatsApp:** Nutzer sendet „Meine Daten löschen“ → Alle Einreichungen + Medien dieser Nummer werden sofort gelöscht. Ein anonymer DSGVO-Vermerk bleibt. +- **Web:** Nutzer notiert die bei Einreichung angezeigte **Referenz-ID**. Löschung aktuell nur durch Kontaktaufnahme mit der Redaktion (zukĂŒnftig: Selbstbedienungs-Löschformular). +- **Admin:** BeitrĂ€ge können im Admin-Dashboard hart gelöscht werden (Medien + DB-Eintrag). + +### 4.4 Speicherdauer + +- Unveröffentlichte Einreichungen: Bis zur manuellen Löschung oder DSGVO-Anfrage +- Veröffentlichte BeitrĂ€ge: Bis zur ZurĂŒcknahme oder Löschung +- DSGVO-Vermerke: Dauerhaft (Dokumentationspflicht) +- **Keine automatische Löschroutine** aktuell implementiert + +### 4.5 Medien + +- Gespeichert unter `./media/` auf dem Server +- WhatsApp: `whatsapp_.` +- Web: `web_.` +- Werden bei DSGVO-Löschung oder Admin-Löschung von der Platte entfernt + +--- + +## 5. Datenschutzrechtliche Relevanz + +### 5.1 Personenbezogene Daten (Art. 4 DSGVO) + +| Datenkategorie | Vorhanden | Quelle | +|---|---|---| +| Telefonnummer | ✅ | WhatsApp-Sender | +| Name (Vorname/Spitzname) | ✅ | WhatsApp-Profil + Nutzereingabe | +| Bildaufnahmen | ✅ | WhatsApp/Web-Upload (kann Personen zeigen) | +| Videoaufnahmen | ✅ | WhatsApp/Web-Upload (kann Personen zeigen) | +| Sprachaufnahmen | ✅ | WhatsApp/Web-Upload | +| Inhaltsdaten | ✅ | Nutzertexte | +| Standortdaten | ❌ | Nicht erfasst | + +### 5.2 Erforderliche Dokumente + +1. **DatenschutzerklĂ€rung** — fĂŒr das öffentliche Frontend (`/`) +2. **AGB / Nutzungsbedingungen** — fĂŒr die Nutzung des Einreich-Formulars und Chat-Assistenten +3. **Impressum** — mit Kontaktdaten des Verantwortlichen +4. **Cookie-Hinweis** — aktuell: nur localStorage fĂŒr Theme (Dark/Light), kein Tracking + +### 5.3 Navigation (Vorschlag) + +``` +/ +├── Startseite (Community-Feed) +├── Impressum +├── Datenschutz +├── AGB / Nutzungsbedingungen +└── Fußzeile (Footer) + ├── brettspiel-news.de + ├── Impressum + ├── Datenschutz + └── AGB +``` + +--- + +## 6. Technische Details + +### 6.1 Server + +- **Host:** 4-Kern AMD EPYC, 8 GB RAM, 250 GB Disk +- **OS:** Linux (Debian) +- **Prozess:** Flask lĂ€uft als Hintergrundprozess mit Keepalive-Thread (gegen InaktivitĂ€ts-Timeout) +- **Start:** `cd ~/workspace/bsn-chatbot && source .env && /home/hermes/venv/bin/python app.py` +- **Port:** 5002 (localhost only) +- **Tunnel:** cloudflared token-basiert → `chat.datenhimmel.work` + +### 6.2 Meta / WhatsApp + +- **App:** Brettspiel-News.de (App-ID: `1864231860438511`) +- **Token:** Permanent System User Token (lĂ€uft nie ab) +- **Phone Number ID:** `1152708791258718` +- **Test-Nummer:** `16315551181` (Meta-Testnummer) + +### 6.3 KI-Dienste + +- **DeepSeek V4 Flash:** via `https://ui.datenhimmel.work/api/chat/completions` (API-Key in `~/.hermes/config.yaml`) +- **faster-whisper:** Lokal unter `/home/hermes/.hermes/venvs/speech/`, Modell `base` +- **Piper TTS:** Lokal unter `~/.local/bin/piper`, Stimme `de_DE-thorsten-medium` + +--- + +## 7. Aktueller Feature-Stand + +| Feature | Status | +|---|---| +| WhatsApp Webhook (Text, Bild, Audio, Video) | ✅ Produktiv | +| WhatsApp Auto-Reply (Onboarding + Thread) | ✅ Produktiv | +| WhatsApp TTS-Onboarding (Thorsten) | ✅ Produktiv | +| Sprachnachrichten-Transkription | ✅ Produktiv | +| Video-Transkription | ✅ Produktiv | +| Auto-LLM-Zusammenfassung + Hallen-Erkennung | ✅ Produktiv | +| Web-Submit-Formular mit Capture-Buttons | ✅ Produktiv | +| Referenz-ID mit Kopier-Button nach Web-Submit | ✅ Produktiv | +| DSGVO-Löschung per WhatsApp („Meine Daten löschen“) | ✅ Produktiv | +| Admin-Dashboard mit iOS-26-Design | ✅ Produktiv | +| Admin-Detailview mit Medien-Toggles | ✅ Produktiv | +| Admin-Unpublish (Veröffentlichung zurĂŒcknehmen) | ✅ Produktiv | +| Admin-LLM-Zusammenfassung-Button | ✅ Produktiv | +| Admin-Delete mit BestĂ€tigungsdialog | ✅ Produktiv | +| Admin-Theme-Toggle (Dark/Light) | ✅ Produktiv | +| Öffentliches Frontend (Masonry-Layout) | ✅ Produktiv | +| Frontend-Filter (Halle + Kategorie) | ✅ Produktiv | +| Beitrags-Detailseite mit ID-Footer | ✅ Produktiv | +| Chat-Assistant (Read-Only, RAG) | ✅ Produktiv | +| DSGVO-Löschung per Web-ID | ⏳ In Planung | +| AGB / Datenschutz / Impressum | ❌ Fehlt | +| Cookie-Consent-Banner | ❌ Nicht nötig (kein Tracking) | +| Zugangsschutz fĂŒr /admin | ❌ Fehlt | +| Automatische Löschroutine | ❌ Fehlt | + +--- + +## 8. Datei-Übersicht (Projektverzeichnis) + +``` +~/workspace/bsn-chatbot/ +├── app.py # Flask-Hauptanwendung (2.700+ Zeilen) +├── bsn_intake.db # SQLite-Datenbank +├── .env # Secrets (Meta-Token etc., nicht in Git) +├── .env.bak # Backup (nicht in Git) +├── .gitignore # SchĂŒtzt Secrets, DB, Medien vor Commit +├── media/ # Hochgeladene Mediendateien (nicht in Git) +└── bsn-chatbot/SKILL.md # Entwickler-Dokumentation (Skill) +``` + +--- + +*Erstellt von Basti (Hermes Agent) am 17.06.2026 fĂŒr Daniel Krause / brettspiel-news.de* diff --git a/app.py b/app.py index 5b46d96..aee09b3 100644 --- a/app.py +++ b/app.py @@ -2672,8 +2672,7 @@ def public_detail(sub_id: int):