asdasd

NEXUS_SYSTEM.md

@@ -0,0 +1,119 @@
+Projektkontext: Nexus-System
+
+1) Projekt-Zweck und Ziel
+- Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur.
+- Module kapseln fachliche Funktionen, das Nexus-System stellt das globale Grundgerüst bereit.
+- Das generelle Nexus-System wird unabhängig von den bestehenden Fachmodulen weiterentwickelt.
+
+2) Umgebungen und Domains
+- Live: `nexus.kusche.berlin`
+- Staging: `staging.nexus.kusche.berlin`
+
+Container- und Deploy-Layout:
+- `/app/live/` -> Live-Code
+- `/app/staging/` -> Staging-Code
+- jeweils mit eigenem `config`-Unterordner:
+  - `/app/live/config/`
+  - `/app/staging/config/`
+
+Repo-Layout zu Configs:
+- `/config/live/` und `/config/staging/` liegen im Repo
+- beim Deployment werden die Dateien daraus nach `/app/<env>/config` kopiert
+- wichtig: im laufenden Container existiert `/app/config/` nicht, sondern nur `/app/live/config` und `/app/staging/config`
+
+3) Verzeichnisstruktur
+- `/public/` -> Web Root mit globalen Assets
+- `/api/` -> Backend- und API-Endpunkte
+- `/src/` -> PHP-Kernklassen und Utilities
+- `/tools/` -> CLI, Worker und Jobs
+- `/config/` -> Umgebungs-Configs
+- `/modules/<modul>/` -> klassische Nexus-Module
+- `/partials/structure/` -> Header, Footer, Menüs
+- `/partials/landingpages/` -> komplette Seitenlayouts
+- `/debug/` -> Custom Logs
+
+4) Code-Änderungen nach Scope
+- globale Layouts: `/partials/structure/` und `/public/assets/css/app.css`
+- Konfigurationslogik: nur wenn nötig `/config/` und `/src/`
+- Modul-Aufgaben: nur `/modules/<modul>/` und gegebenenfalls `/tools/<modul>`
+
+5) UI-Naming und Seitenaufbau
+- `Seitenheader-Box`: oberste globale Header-Box mit Seitentitel, Login und Farbschema
+- `Submenü-Box`: Box direkt unter der Seitenheader-Box für modul- oder seitenbezogene Aktionen
+- `Submenü-Aktionen`: rechtsbündige Zusatzbuttons innerhalb der Submenü-Box, z.B. `Setup` oder `Nexus Übersicht`
+- `Bereichs-Box`: größere Inhaltsbox für einen zusammenhängenden Seitenbereich
+- `Karten-Box`: kleinere Karte auf derselben Ebene wie Bereichs-Boxen, meist in Grids
+
+Zentrale CSS-Klassen:
+- `main-header-box`
+- `submenu-box`
+- `module-submenu-actions`
+- `section-box`
+- `card-box`
+
+Globale Struktur:
+- zuerst Seitenheader-Box
+- danach Submenü-Box
+- danach Bereichs-Boxen und/oder Karten-Boxen je nach Seite
+
+Layout-Regeln:
+- vertikale Abstände zwischen `main-header-box`, `submenu-box` und den ersten Folge-Boxen müssen aus der globalen Shell kommen
+- maßgeblich sind `module-page-bg` und `module-page-stack` in `public/assets/css/app.css`
+- Top-Level-Wrapper wie Grids, Kartencontainer oder Modul-Listen dürfen keinen zusätzlichen `margin-top` oder Sonder-Gap erzeugen, der den Abstand nach dem Submenü verändert
+- bei Layout-Reviews ist explizit zu prüfen, ob `Main-Header -> Submenü -> erste Section/Card` optisch denselben Rhythmus hat wie auf Referenzseiten
+- die Optik der Submenü-Aktionsbuttons kommt ausschließlich aus dem globalen CSS
+
+Beispielstruktur:
+- Börsenchecker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Bereichs-Box
+- FX-Rates: Seitenheader-Box, Submenü-Box, danach Bereichs-Boxen
+- Mining-Checker: Seitenheader-Box, Submenü-Box, Bereichs-Box, Karten-Boxen, Karten-Boxen, Bereichs-Box
+- Modulverwaltung: Seitenheader-Box, Submenü-Box, danach Karten-Boxen
+
+6) Nexus-Kerngerüst
+- Der aktuelle Ausbauschritt betrifft das generelle Nexus-System, nicht die bestehenden Fachmodule.
+- Bestehende Module sind funktional und strukturell zunächst ausgenommen und dürfen durch Arbeiten am Kerngerüst nicht beeinträchtigt werden.
+- Neue Kernfunktionen müssen parallel zum bestehenden Modulsystem eingeführt werden.
+- Zielbild ist ein Nexus-Grundsystem mit flexiblen Benutzer-Dashboards, Integrationen und datengetriebenen Seitenmodulen.
+
+Produktprinzip:
+- Nexus ist nicht nur Modul-Launcher, sondern ein persönliches und gruppenfähiges Dashboard-System.
+- Benutzer sollen eigene Dashboards anlegen, anordnen und konfigurieren können.
+- Inhalte auf Dashboards sollen aus drei Quellen kommen können:
+  - interne Nexus-Funktionen
+  - externe Integrationen
+  - einfache Seitenmodule ohne eigene Modul-Implementierung
+
+Abgrenzung zu bestehenden Modulen:
+- das Verzeichnis `/modules/<modul>/` bleibt das Zuhause klassischer Nexus-Module
+- das Dashboard-System ist ein zusätzliches globales Kernsystem
+- neue Kernfunktionen müssen ohne Umbau bestehender Module lauffähig sein
+
+7) Globale Zeitzonen-Logik
+- globale Nexus-Einstellungen liegen unter `/settings`
+- dort werden zentral gepflegt:
+  - `Anzeige-Zeitzone`
+  - `Standard-Zeitzone für Crons`
+
+Regeln:
+- ohne Custom bei der Anzeige-Zeitzone wird die System-Zeitzone verwendet
+- die aktive Anzeige-Zeitzone soll angezeigt werden
+- die Standard-Zeitzone für Crons ist der globale Default für Modul-Crons
+- Module dürfen diese Zeitzone im Setup übersteuern
+- einzelne Cron-Einträge dürfen sie ebenfalls übersteuern
+
+UTC-Speicherregel:
+- Zeitwerte sollen projektweit intern immer in `UTC` gespeichert werden
+- Anzeige-Zeitzonen dienen nur der Darstellung für Benutzer
+- Cron-Zeitzonen dienen nur der lokalen Auswertung von Zeitplänen und Fälligkeiten
+- beim Einlesen lokaler Eingaben muss vor dem Speichern nach `UTC` normalisiert werden
+- beim Anzeigen gespeicherter Werte muss von `UTC` in die jeweils wirksame Anzeige-Zeitzone umgerechnet werden
+
+8) Globales Debug-System
+- das Debug-Popup ist eine globale Infrastruktur aus dem zentralen Layout
+- die Aktivierung bleibt pro Modul über `debug_enabled` im Modul-Setup steuerbar
+- das Debug-Symbol darf nur sichtbar sein, wenn für das aktuelle Modul Debug aktiv ist
+- Module sollen keine eigene separate Debug-Oberfläche bauen, wenn der globale Debug-Stream genutzt werden kann
+
+9) Sicherheits- und Netzwerk-Constraints
+- Zugriff im Heimnetz `192.168.178.0/24` per Nginx begrenzt
+- SSH-Hosts nur Heimnetz