---
name: sma-radar
description: "Use when working on the VPS SMA/Social-Media-Radar system."
---

# SMA / Social-Media-Radar (VPS)

Class-level guidance für alle Aufträge rund um `/opt/struktur/social-media-radar/` 
(Radar) und `/opt/struktur/social-media-agent/` (Legacy-Cockpit, Port 8652).

## Architektur-Überblick

```
Intakes (rss, weather, multi_intake=YouTube+FB)
  → signal_db.insert_signal()   Dedup-Kette:
      1. URL-Hash  2. Title-Hash  3. external_id (AA-045)  4. Jaccard-Kanonisierung
  → content_briefing.run()      füllt briefing_* NUR für director_action='pruefen'
  → caption_gate.can_generate_caption()   blockiert bei fehlendem Briefing
  → visual_render.render_by_id()          Semaphore in app.py begrenzt parallele Jobs
Cron: 30 7 * * * /opt/struktur/social-media-radar/run_radar.sh
DB:  /var/lib/sma-data/signals.db (Pfad via sma_database.SIGNALS_DB_PATH)
```

## Pitfalls (alle praktisch verifiziert)

1. **Alles per sudo.** Radar-/Agent-Dateien und DB gehören root bzw. sind 750/660.
   Patch-Skripte als Datei nach /tmp schreiben und mit `sudo python3 <datei>` laufen
   lassen; große inline-Heredocs mit sudo werden teils vom Approval-Layer blockiert.
2. **Briefing-Lücke:** Neue Signale ohne passendes `director_action` bekommen kein
   Briefing → Caption-Gate meldet „briefing_winkel und briefing_nutzen beide leer".
   Fix-Muster: Nachbefüllung via `compute_briefing()` je Signal (siehe references).
3. **Parallele Bildformate:** Das Cockpit fordert 1x1+4x5 parallel an
   (`Promise.all`). `_PACKAGE_RENDER_SLOTS` in agent/app.py muss ≥ 2 sein,
   sonst garantierte 429 „Eine Bilderzeugung läuft bereits." Nach App-Änderung:
   py_compile + `sudo systemctl restart social-media-agent`.
4. **YouTube-Thumbnails:** direkt `https://i.ytimg.com/vi/<ID>/hqdefault.jpg`
   ableiten (HEAD-Check), nicht crawlen. YouTube-Suche ohne API-Key über
   Suchseiten-Parsing (`"videoRenderer":{...}` Regex); Channel-RSS
   `feeds/videos.xml?channel_id=` liefert 404 für ungültige Kanäle — überspringen.
5. **Facebook loginfrei:** Bing-RSS (`format=rss`) funktioniert, liefert aber kaum
   tiefe Post-URLs; DDG/Mojeek/Qwant/Startpage sind von diesem VPS aus geblockt
   (anomaly/Captcha). FB-Filter gegen `/login|register|l.facebook|m.me`.
6. **Bildpipeline wiederverwenden:** Legacy `/api/img?u=` Proxy mit MD5-Cache
   (`static/img_cache/`) funktioniert; Frontend blendet kaputte Bilder per
   `onerror` aus → typabhängiges Fallback greift automatisch.
7. **Tests am Live-System:** Repro über HTTP (`/api/caption/<sid>`,
   `/api/visual/<sid>?fmt=`) statt nur DB — erst so sieht man Gate/Lock-Effekte.
   Parallele Requests mit ThreadPoolExecutor simulieren.
8. **published_at-Normalisierung für 2-Tage-Filter:** Alle Signale im radar.db
   haben die Spalte `published_at` (via AA-045-Schema-Migration), aber alle Werte
   sind leer, obwohl die Spalte existiert. Relativ-formatierte Datumsangaben aus
   Quellen ("vor 2 Tagen", "vor 6 Monaten", "vor 1 Jahr") müssen in gültiges
   ISO-8601 konvertiert werden, damit der 2-Tage-Filter (CANONICAL_WINDOW_HOURS=48)
   Signale innerhalb von 48h erkennt. Ohne `published_at` werden alle Signale als
   "ältest" behandelt und vom 2-Tage-Filter ausgeschlossen.
9. **Positive reale Testbasis:** Für den AA-045-F7-P3A-Test einen aktuellen Signal-Inhalt
   aus dem produktiven Radar verwenden, dessen Veröffentlichungsdatum innerhalb der
   letzten 48 Stunden liegt. Priorität: YouTube > RSS > Web/Blog > Branchen-Watch.
   Das Signal muss ein gültiges ISO-8601 `published_at` haben und im Cockpit unter
   `/api/signals?days=2` sichtbar sein.
10. **Datumformat-Quantifizierung:** Nach erfolgreichem Import alle `published_at`-Formate
    quantifizieren: NULL/leer, gültiges ISO-8601, relative deutsche Angabe
    ("vor X Tagen"/"vor X Monaten"/"vor X Jahren"), sonstiges ungültiges Format.
    Nur echte ISO-8601-Werte zählen für den 48h-Cutoff, relative Formate müssen
    erst normalisiert werden.

## Referenzen

- `references/architecture-and-fixes.md` — Pfade, DB-Felder, konkrete Fix-Rezepte
  (Briefing-Nachbefüllung, Semaphore-Patch, Thumbnail-Anreicherung) aus AA-044/045/F1/F2.
- `references/published_at-normalization.md` — Konvertierung relativer Datumsformate
  in ISO-8601 für den 2-Tage-Filter, inkl. Mustervorlagen für "vor 2 Tagen",
  "vor 6 Monaten", "vor 1 Jahr".