DataEngine Dashboard

# Bedienungsanleitung Drive DataEngine ## 1. Zweck Drive DataEngine ist eine Symfony-basierte Kontrollschicht fuer den bestehenden Legacy-ETL-Bestand. Die Plattform stellt aktuell bereit: - Dashboard unter `https://dataengine.domgan.de` - oeffentlich lesbare Bedienungsanleitung unter `https://dataengine.domgan.de/manual` - tenant-isolierte Run-Historie in PostgreSQL mit RLS - CLI-Commands fuer Katalog, Verbindungsprofile, Run-Planung und Ausfuehrung - kontrollierte Legacy-Ausfuehrung ueber die interne Bridge - erste native Symfony-Runtime fuer Legacy-Datenbankprofile auf MySQL-Basis - erste native MySQL-Datapool-Schreiboperationen fuer Betrieb und Migration ## 2. Aktueller Architekturstand ### 2.1 Komponenten - `dashboard` Symfony-Weboberflaeche und Symfony-CLI - `legacy-bridge` startet bestehende Legacy-Runner kontrolliert per HTTP - `postgres` speichert Tenants, Runs und synchronisierte Connection-Metadaten - `traefik` bindet `dataengine.domgan.de` von aussen an ### 2.2 Legacy vs. native Runtime Aktueller Stand: - Pipelines und Engines werden nativ in Symfony erkannt und vorvalidiert. - Die eigentliche fachliche Ausfuehrung laeuft weiterhin ueber die Legacy-Bridge. - Legacy-Datenbankprofile koennen in Symfony bereits nativ bewertet werden. - Fuer MySQL-Profile existieren read-only Runtime-Probes, Datapool-Inspektion sowie erste Write-Operationen. - ODBC-Profile bleiben vorerst im Legacy-Pfad. ## 3. Zugriff ### 3.1 Web - URL: `https://dataengine.domgan.de` - aktueller Status: oeffentlich erreichbar ueber Traefik - Handbuch: `https://dataengine.domgan.de/manual` ### 3.2 Server - Deployment-Ziel: `ortho-live` - Projektpfad auf dem Server: `/opt/containers/drive-dataengine` - Compose-Datei: `/opt/containers/drive-dataengine/compose.yaml` ## 4. Mandantenmodell Die Multi-Tenant-Isolation gilt derzeit fuer die Kontrollschicht: - `tenants` - `execution_runs` - `connection_profiles` Die Isolation erfolgt ueber PostgreSQL Row Level Security und den gesetzten Tenant-Kontext in Symfony. ## 5. Dashboard bedienen ### 5.1 Startseite Die Startseite zeigt: - Anzahl erkannter Pipelines und Engines - Tenant-Kontext - erkannte Legacy-Verbindungsprofile - native Datenbank-Runtime-Abdeckung - native Datapool-Write-Abdeckung - letzte tenant-isolierte Ausfuehrungen - alle gefundenen Pipelines - alle gefundenen Engines pro Runner-Typ ### 5.5 Bedienungsanleitung im Dashboard Unter `https://dataengine.domgan.de/manual` wird immer die aktuelle Datei `docs/bedienungsanleitung.md` aus dem ausgelieferten Stand angezeigt. Damit gilt: - Jede Aenderung an Bedienung, Commands oder Betrieb muss die Markdown-Datei aktualisieren. - Nach jedem Deployment ist die Live-Anleitung automatisch synchron mit dem Container-Stand. ### 5.2 Pipeline ausfuehren Im Pipeline-Bereich: 1. Pipeline-Karte waehlen 2. `Pipeline ausfuehren` klicken 3. Das System legt einen Run in PostgreSQL an 4. Der Run wird asynchron ueber die Legacy-Bridge abgearbeitet 5. Im Run-Detail ist der native Preflight sichtbar ### 5.3 Engine ausfuehren Im Engine-Bereich: 1. Engine-Karte waehlen 2. `Engine ausfuehren` klicken 3. Der Run wird in PostgreSQL protokolliert 4. Die Ausfuehrung bleibt bis zur Portierung im Legacy-Pfad ### 5.4 Run-Detail lesen Im Run-Detail werden angezeigt: - Run-Status - Runner-Typ und Name - Trigger-Quelle - Start-/Endzeit - Exit-Code - stdout/stderr - nativer Ausfuehrungsplan mit Schritten, Connections und Validierungsfehlern ## 6. Wichtige CLI-Commands Alle Commands laufen im Dashboard-Container. Beispiel: ```bash ssh ortho-live 'cd /opt/containers/drive-dataengine && docker compose -f compose.yaml exec -T dashboard php /srv/app/symfony/bin/console <command>' ``` ### 6.1 Katalog und Planung - `app:etl:list` listet alle erkannten Pipelines und Engines - `app:etl:plan <runner-type> <name>` erzeugt den nativen Ausfuehrungsplan Beispiel: ```bash php /srv/app/symfony/bin/console app:etl:plan pipeline pipeline_update_articles_wandmontage ``` ### 6.2 Ausfuehrung - `app:etl:run-pipeline <name> [--tenant=default] [--async]` - `app:etl:run-engine <runner-type> <name> [--tenant=default] [--async]` - `app:execution:run <run-id> [--tenant=default]` interner Worker-Command ### 6.3 Verbindungsprofile - `app:etl:list-connections` zeigt erkannte Legacy-Verbindungsprofile - `app:legacy:sync-connections --tenant=default` synchronisiert redigierte Metadaten tenant-sicher nach PostgreSQL ### 6.4 Native Datenbank-Runtime - `app:etl:list-database-runtime` zeigt, welche Legacy-Datenbankprofile in Symfony nativ nutzbar sind - `app:etl:test-database-connection <profile>` fuehrt einen read-only Verbindungsprobe-Lauf fuer ein MySQL-Profil aus - `app:etl:list-datapools <profile>` listet Datapools eines nativen MySQL-Profils read-only auf - `app:etl:inspect-datapool <profile> <table> [--with-count] [--show-create-sql]` zeigt Spaltenstruktur eines Datapools und optional Zeilenzahl bzw. `SHOW CREATE TABLE` ### 6.5 Native Datapool-Write-Operationen - `app:etl:drop-datapool <profile> <table>` fuehrt `DROP TABLE IF EXISTS` kontrolliert fuer ein natives MySQL-Profil aus - `app:etl:truncate-datapool <profile> <table>` fuehrt `TRUNCATE TABLE` kontrolliert fuer ein natives MySQL-Profil aus - `app:etl:create-datapool-definition <profile> <table> <definition-file> [--drop-existing]` erzeugt einen Datapool aus einer YAML- oder JSON-Blueprint-Datei Beispiele: ```bash php /srv/app/symfony/bin/console app:etl:drop-datapool importEngine temp_articles php /srv/app/symfony/bin/console app:etl:truncate-datapool importEngine temp_articles php /srv/app/symfony/bin/console app:etl:create-datapool-definition importEngine temp_articles /srv/app/docs/examples/datapool-definition.example.yaml --drop-existing ``` Blueprint-Format: - `columns` Pflichtfeld, Mapping aus Spaltenname auf MySQL-Spaltendefinition - `primary_key` optionale Liste von Spalten fuer den Primary Key - `indices` optionale Liste von Indexdefinitionen, einzelne Werte duerfen auch `firma,ordernumber` enthalten - `engine` optional, Standard `INNODB` - `charset` optional, Standard `latin1` - `add_filter_reason` optional, fuegt die Spalte `filter_reason MEDIUMTEXT` hinzu, falls sie noch fehlt Ein lauffaehiges Beispiel liegt unter: - `docs/examples/datapool-definition.example.yaml` Beispiele: ```bash php /srv/app/symfony/bin/console app:etl:list-database-runtime php /srv/app/symfony/bin/console app:etl:test-database-connection domgan php /srv/app/symfony/bin/console app:etl:list-datapools importEngine php /srv/app/symfony/bin/console app:etl:inspect-datapool importEngine articles --with-count --show-create-sql ``` ## 7. Deployment und Betrieb ### 7.1 Compose-Stack starten oder aktualisieren ```bash ssh ortho-live 'cd /opt/containers/drive-dataengine && docker compose -f compose.yaml build dashboard && docker compose -f compose.yaml up -d dashboard' ``` ### 7.2 Stack-Status pruefen ```bash ssh ortho-live 'cd /opt/containers/drive-dataengine && docker compose -f compose.yaml ps' ``` ### 7.3 Oeffentliche Erreichbarkeit pruefen ```bash curl -sS -I https://dataengine.domgan.de ``` ### 7.4 Datenbankschema anwenden Wenn sich `docker/postgres/init/001-rls.sql` geaendert hat und der Container bereits initialisiert wurde: ```bash ssh ortho-live 'cd /opt/containers/drive-dataengine && docker compose -f compose.yaml exec -T postgres psql -U dataengine -d dataengine -f /docker-entrypoint-initdb.d/001-rls.sql' ``` ### 7.5 Repo-Guardrail lokal pruefen Vor Pushes oder Releases kann die Doku-Synchronitaet lokal geprueft werden: ```bash cd /opt/containers/drive-dataengine ./scripts/check-doc-sync.sh HEAD^ HEAD ``` ## 8. Dokumentationsstandard Diese Anleitung ist die operative Fuehrungsdokumentation fuer den aktuellen Stand. Pflicht bei jeder Aenderung: 1. `README.md` aktualisieren, wenn Einstieg oder Architektur betroffen sind. 2. Diese Bedienungsanleitung aktualisieren, wenn Bedienung, Commands, Deployment oder Grenzen betroffen sind. 3. `docs/replatforming-plan.md` aktualisieren, wenn sich Zielbild oder Migrationsgrenze verschiebt. Details stehen in `CONTRIBUTING.md`. ## 9. GitHub und Versionierung Der GitHub-Stand wird ohne produktive Secrets versioniert. Nicht versioniert werden: - `.env` - SSH-Schluessel - Cloud-Service-Account-Dateien - Legacy-Connection-Profile mit Live-Credentials Fuer diese Dateien bleibt der Server die Quelle. Neue Umgebungen muessen die Secrets separat erhalten. Das Repository erzwingt auf GitHub ueber `scripts/check-doc-sync.sh` und `.github/workflows/repository-guardrails.yml`, dass Code- und BetriebsAenderungen nicht ohne aktualisierte Dokumentation gemerged werden. Privates Repository: - `https://github.com/dominikgantenberg/drive-dataengine` ## 10. Bekannte Grenzen - Die fachliche Engine-Ausfuehrung laeuft noch ueber die Legacy-Bridge. - ODBC-Profile sind noch nicht nativ in Symfony nutzbar. - Read-only Datenbank-Probes haengen von der Netzwerkerreichbarkeit des Zielsystems vom Host `ortho-live` ab. - Native Datapool-Write-Operationen decken aktuell nur MySQL und nur die ersten Struktur-Operationen ab. - Der lokale Mount des Projektpfads kann instabil sein; im Stoerungsfall wird ueber `ssh/scp` gearbeitet.