From 74b179a9ceba7c1eec256834695daef62e057723 Mon Sep 17 00:00:00 2001 From: Lars Gebhardt-Kusche Date: Mon, 9 Mar 2026 01:16:38 +0100 Subject: [PATCH] update anweisungen --- PROJECT_CONTEXT.md | 96 ++++++++++++++++++++++++++++------------------ 1 file changed, 59 insertions(+), 37 deletions(-) diff --git a/PROJECT_CONTEXT.md b/PROJECT_CONTEXT.md index 5b493c9..897d95a 100644 --- a/PROJECT_CONTEXT.md +++ b/PROJECT_CONTEXT.md @@ -1,49 +1,71 @@ -Projekt-Zusammenfassung: Nexus Control Panel (Modul: KEA) -1. Projekt-Zweck & Ziel -Nexus ist ein zentrales, webbasiertes Administrations-Interface für die Verwaltung einer dynamischen IT-Infrastruktur. Das primäre Ziel ist die Abstraktion und Steuerung von Netzwerkdiensten, beginnend mit dem ISC KEA DHCP-Server. +Projekt-Zusammenfassung: Nexus Control Panel -2. Kernmodul: KEA DHCP Management -Dieses Modul dient der Verwaltung von Netzwerkgeräten und deren IP-Zuweisungen. +1) Projekt-Zweck & Ziel +Nexus ist ein zentrales, webbasiertes Admin-Interface zur Steuerung einer dynamischen IT-Infrastruktur. +Module kapseln fachliche Funktionen (z.B. KEA DHCP, Pi Control). -Datenquelle: Das Interface kommuniziert direkt mit einer PostgreSQL-Datenbank (db_nexus), in der KEA seine Leases und Hosts speichert. +2) Aktive Module (Kurzüberblick) +- KEA DHCP: Verwaltung von Hosts/Leases, Statische Reservierungen, Metadaten. +- Pi Control: Verwaltung von SSH-Hosts, Befehle/Preset, Konsole, Host-Status, Update/Upgrade-Checks. -Funktionsumfang: +3) Umgebungen & Domains +- Live: nexus.int.kusche.berlin +- Staging: staging.nexus.int.kusche.berlin -Geräte-Inventar: Auflistung aller bekannten Geräte (Hostnames, MAC-Adressen). +Container/Deploy-Layout: +- /app/live/ -> Live-Code +- /app/staging/ -> Staging-Code +- Jeweils mit eigenem /config-Unterordner: + - /app/live/config/ + - /app/staging/config/ -IP-Management: Verwaltung von statischen Reservierungen und Überwachung von dynamischen Leases. +Repo-Layout zu Configs: +- /config/live/ und /config/staging/ liegen im Repo. +- Beim Deployment werden die Dateien daraus nach /app//config kopiert. +- WICHTIG: Im laufenden Container existiert /app/config/ NICHT, sondern nur /app/live/config und /app/staging/config. -Metadaten: Speicherung zusätzlicher Informationen pro Gerät (z.B. Standort, Gerätetyp, Verantwortlicher), die über die Standard-KEA-Schema-Felder hinausgehen können. +4) Verzeichnisstruktur (Repo) +- /public/ -> Web Root (index.php, globale Assets) +- /api/ -> Backend/API-Endpunkte +- /src/ -> PHP-Kernklassen/Utilities +- /tools/ -> CLI/Worker/Jobs (z.B. tools/pi_control) +- /config/ -> Umgebungs-Configs (live/staging) +- /modules// -> Module (Pages, Assets, Bootstrap) +- /partials/structure/ -> Header/Footer/Menüs +- /partials/landingpages/ -> Komplette Seitenlayouts +- /debug/ -> Custom Logs -3. Technische Architektur (VSC Kontext) -Damit der Code Assist die Pfade korrekt generiert, ist das Standard-Server-Layout entscheidend: +5) Modul-Konzept (WICHTIG) +- Jedes Modul lebt unter /modules//. +- Pflicht-Dateien i.d.R.: + - module.json + - bootstrap.php (Schema/Setup) + - pages/*.php (UI/Endpoints) + - assets/* (modulspezifisches CSS/JS) -Domains: * nexus.int.kusche.berlin (Produktion) +Modulspezifische Assets: +- Modul-JS/CSS MUSS im Modul-Ordner liegen. +- Laden über Modul-Assets, z.B.: + - $assets->addStyle('/module/pi_control/asset?file=pi_control.css'); + - $assets->addScript('/module/pi_control/asset?file=hosts.js', 'footer', true); +- KEINE modulspezifischen Änderungen in /public/assets/*. -staging.nexus.int.kusche.berlin (Testumgebung) +6) Code-Änderungen nach Scope +- Modul-Aufgaben: nur /modules// + ggf. /tools/ ändern. +- Globale Layouts: /partials/structure und /public/assets/css/app.css. +- Konfigurationslogik: nur wenn nötig /config/ und /src/. -Dateistruktur: +7) Sicherheits-/Netzwerk-Constraints +- Zugriff im Heimnetz (192.168.178.0/24) per Nginx begrenzt. +- SSH-Hosts nur Heimnetz. -/public/: Der einzige öffentlich erreichbare Ordner (Document Root). Enthält index.php und Assets. +8) Pi Control Besonderheiten (konkret) +- Worker/Jobs unter /tools/pi_control/ +- Check-Updates & Cron nutzen die gleichen SSH-Routinen. +- Host-Karten, Befehle und Konsole sind UI im Modul. +- Update/Upgrade-Checks liefern Debug-Ausgaben, die als Tooltip oder Debugzeile angezeigt werden. -/api/: Backend-Logik und API-Endpunkte. - -/src/ und /tools/: PHP-Klassen für die KEA-Datenbankinteraktion. - -/config/: Datenbank-Zugangsdaten und Umgebungsvariablen. Die Subfolder staging/prod spielen keine technische Rolle und müssen so nicht in den Code integriert werden, denn sie werden so auch nicht synchronisiert. Beim Synchronisieren werden die beinhalteten Dateien automatisch in das Config Verzeichnis kopiert, als ob sie direkt drin liegen. - - -/partials/landingpages/: Enthält die echten Landingpages, also den kompletten Aufbau der Seite - -/partials/structure/: Enthält alle wiederverwendbaren Seiteninformationen, wie z.B. Header, Footer, Menue - -/debug/: Hier sollen custom Log-Dateien gespeichert werden. Ist dafür gedacht, dass wenn mal ein custom debug-Tool existiert, ein zentraler Ort für die Debug-Dateien existiert. - -Backend: PHP 8.2 (FPM). - -Frontend: HTML5, CSS (evtl. Tailwind/Bootstrap), JavaScript (Vanilla oder leichtgewichtig). - -4. Sicherheits-Vorgaben für den Assistenten -IP-Sperre: Der Zugriff ist strikt auf das Heimnetz (192.168.178.0/24) begrenzt (via Nginx). - -Pfadtrennung: Code-Generierung muss strikt zwischen dem Logik-Verzeichnis (außerhalb des Roots) und dem Web-Verzeichnis unterscheiden. +9) Zusammenfassung (kurz) +Nexus ist modular, mit strikter Trennung zwischen globalem Layout und modulspezifischem Code. +Staging/Live haben eigene /app//config-Strukturen; /config/ im Repo wird beim Deployment kopiert. +Modul-Assets gehören ausschließlich in den Modul-Ordner und werden dort geladen.