Cog Integration DE

Cog-Integration

🌐 English · Deutsch

Jeder Red-Cog kann Inhalte zum Dashboard beisteuern – Widgets, Panels, Listen und (optional) vollständige Seiten – indem er einige Methoden dekoriert. Die Integration ist opt-in und entkoppelt: Ein Cog funktioniert auch ohne installiertes Dashboard (die Decorators werden zu No-ops) und kann gleichzeitig neben AAA3As Dashboard laufen. Diese Seite fokussiert, wie diese Beiträge in der Web-UI erscheinen; die vollständige Anleitung der Python-Seite liegt im Cogs-Repo.

➡️ Anleitung zur Dashboard-Integration (Cogs-Wiki)

Der Drop-in und die Decorators

Ein Cog integriert sich, indem er einen kleinen pdc_dashboard.py-Drop-in kopiert (oder aus pdc_webdashboard.integration importiert) und Methoden dekoriert. Vier Beitragstypen existieren:

Decorator	Beitrag	Wird gerendert als
@dashboard_widget	Schreibgeschützte Daten-Kachel	KPI-/Listen-/Linien-Chart-/Status-/Markdown-Karte, optional auto-aktualisierend.
@dashboard_panel	Ein deklaratives Formular	Formular (Switches, Text, Kanal-/Rollen-Picker) mit Speichern-Button.
@dashboard_list	Eine verwaltbare Sammlung	Tabelle zum Ansehen, Hinzufügen, Bearbeiten und Löschen.
@dashboard_page	Eine vollständige eigene Ansicht (optional)	Komponentenbaum-Seite für Fälle, die mehr als ein Panel brauchen.

Jeder Beitrag deklariert eine permission-Stufe (authenticated … bot_owner); das Gateway erzwingt sie serverseitig, bevor der Handler überhaupt läuft. Siehe Authentifizierung.

Deklarative Schemas (kein rohes HTML)

Beiträge liefern deklarative Daten, nie HTML:

• WidgetData – strukturierter Widget-Inhalt: kpi, list, status, markdown oder ein chart (Liniendiagramm via WidgetData.chart(series, labels=…)).
• PanelSchema + Field – ein als Felder (switch, text, textarea, channel, role, …) beschriebenes Formular mit Werten und Validierung. Das Absenden ruft den on_submit-Handler des Cogs auf, der ein SubmitResult zurückgibt.
• Listen liefern Zeilen plus Spalten-Metadaten; Bearbeiten/Löschen mappen auf die Handler des Cogs.

Da die Web-App immer nur deklarative Schemas erhält, gibt es keine XSS-Fläche – das Frontend rendert vertrauenswürdige Komponenten, kein vom Cog geliefertes Markup. Das wird beidseitig erzwungen.

Lokalisierung (i18n)

Ein Cog kann seine Dashboard-Texte in Deutsch und Englisch ausliefern, und sie folgen dem Sprach-Umschalter in der Web-UI (dem DE/EN-Schalter oben rechts). Drei kleine Drop-in-Helfer decken die Flächen ab:

Helfer	Lokalisiert	Folgt
L("Deutsch", "English")	Decorator-Namen/Beschreibungen (Tab-Titel).	Der Web-UI-Sprache.
tr(ctx, …)	Text, der aus einem Handler zurückkommt (PanelSchema-Beschreibung, SubmitResult-Nachricht, Widget-Text), über ctx.locale.	Der Web-UI-Sprache.
tr_lang(lang, …)	Die Discord-Ausgabe des Cogs.	Einer Pro-Gilde-Einstellung, die der Cog speichert, nicht der Website-Sprache.

Schaltet ein Nutzer den Umschalter um, lädt das Frontend die Modul-Texte live neu, sodass Tab-Titel und Panel-Text sofort aktualisiert werden. Feld-Labels bleiben Englisch – eine Quelle der Wahrheit – sodass nur Namen/Beschreibungen und die Discord-Ausgabe übersetzt werden.

Die ausführliche Referenz (Helfer-Signaturen, die Pro-Gilde-Einstellung language, vollständiger Code) liegt in der Cogs-Repo-Anleitung:

➡️ Anleitung zur Dashboard-Integration (Cogs-Wiki)

Das „ein Modul mit Tabs"-Modell

Statt jedem Cog eine isolierte Seite zu geben (das AAA3A-Modell), bündelt dieses Dashboard die Beiträge eines einzelnen Cogs in einem Modul mit Tabs. Ein Cog, der etwa ein Stats-Widget, ein Konfig-Panel und eine verwaltbare Liste bereitstellt, erscheint als ein kohärentes Modul – Ansehen, Konfigurieren und Verwalten am selben Ort, eingehängt dort, wo der Cog es wünscht (z. B. in den Gilden-Einstellungen oder als globales Owner-Panel unter Cog-Verwaltung).

Wie es den Browser erreicht

1. Beim Laden registriert der Cog seine dekorierten Methoden bei pdc_webdashboard (oder das Dashboard erkennt sie automatisch).
2. Das Gateway sammelt jeden Beitrag in seiner Registry.
3. Der BFF ruft manifest.get auf, das die Beiträge zurückgibt, die der aktuelle Nutzer sehen darf, gefiltert nach Berechtigungsstufe.
4. Zum Rendern ruft das Frontend die beitragsspezifischen Methoden auf: widget.data, panel.schema / panel.submit, list.rows / list.edit / list.delete, page.schema.

Cog (dekoriert) ──registrieren──▶ pdc_webdashboard-Registry
BFF ──manifest.get──▶ Gateway ──nach Berechtigung gefiltert──▶ Beiträge
BFF ──widget.data / panel.schema / list.rows──▶ Gateway ──▶ Cog-Handler

Kompatibilität

• Funktioniert ohne das Dashboard. Keine harte Abhängigkeit – ist pdc_webdashboard nicht geladen, tun die Decorators nichts und der Cog läuft normal.
• Koexistiert mit AAA3A. Marker-Attribute und Klassennamen unterscheiden sich, beide Dashboards können denselben Cog ohne Konflikt scannen; keines schaltet das andere ab.

Für die Python-Implementierung – die Drop-in-Datei, vollständige Decorator-Signaturen, PanelSchema/Field-Referenz und den Registrierungs-Lifecycle – folge der oben verlinkten Cogs-Repo-Anleitung.

Verwandte Seiten

• Dashboard-Integration (Cogs-Wiki) – die Python-Seite
• Architektur – wo Beiträge im BFF sitzen
• API & Gateway – die manifest.*-, widget.*-, panel.*-, list.*-Methoden
• Web-UI – wie Module Nutzern erscheinen