dbxapp Arbeitsanweisung fuer Codex

Diese Datei beschreibt, wie Codex an dbxapp arbeiten soll. Sie ist als Arbeitsanweisung fuer neue Sitzungen gedacht.

Grundrichtung

dbxapp wird als Borland-inspirierte PHP-Web-RAD-Runtime weiterentwickelt. dbxapp soll nicht Laravel, WordPress oder React-SPA nachbauen, sondern eine eigene komponentenorientierte Anwendungsumgebung bleiben.

Module sollen Anwendungen aus klaren DBX-Komponenten zusammensetzen. Die Komplexitaet gehoert in Systemklassen und Runtime, nicht in jedes Modul.

Application Runtime
 -> Module
 -> Komponenten
    -> Forms
    -> Reports
    -> Grids
    -> Dialoge / OpenWin
    -> Editor
 -> DD/FD Metadaten
 -> Templates
 -> Client-Libs
 -> State / Remember
 -> Services ueber dbx()

Qualitaetsziel

Gold ist Ziel, Diamant wird angestrebt. Funktioniert-irgendwie reicht nicht. Verantwortlichkeiten muessen stimmen, Namen muessen klar sein, und die Verwendung in Modulen muss einfach bleiben.

Wichtige Architekturregeln

• HTML gehoert in Templates, nicht in PHP-Code.
• Module bleiben duenn und gut lesbar.
• Komplexitaet gehoert in Systemklassen.
• DD/FD sind Metadaten und Designer-Schicht.
• Templates erzeugen die visuelle Struktur.
• dbxReport rendert Reports, ist aber nicht fest an DB gebunden.
• dbxDB ist fuer DB-Daten und DB-Aktionen verantwortlich.
• dbxForm ist fuer Formulare, Feldwerte und Zustand verantwortlich.
• dbxApi / dbx() ist die zentrale, klare System-API.
• Callbacks dienen der einfachen Individualisierung ohne globales Event-System.
• Eigene Klassen wie myReport extends dbxReport bleiben moeglich.
• Keine inkompatiblen Konzeptaenderungen ohne Ruecksprache.

Namen und API

Namen muessen sprechend, kurz genug und eindeutig sein. Kryptische Namen sind zu vermeiden.

Bevorzugt:

dbx()->get_modul_var('record_count')
dbx()->set_modul_var('record_count', $count)
dbx()->get_remember_var(...)
dbx()->set_remember_var(...)
dbx()->get_system_obj('dbxReport')

Nicht bevorzugt:

dbx()->mod(...)
dbx()->rem(...)
dbx()->sys(...)

Module

Module sollen nach dem Prinzip write less, get more gebaut werden. Der einfache Standardfall soll mit wenig Code funktionieren. Bei Bedarf muss trotzdem eine saubere Erweiterung moeglich sein.

$oReport = dbx()->get_system_obj('dbxReport');
$oReport->init('report-sessions');
$oReport->_dd = 'dbxSession';

Danach sollen moeglichst viele Dinge automatisch aus DD/FD, Templates, Report-State und Systemkonventionen laufen.

Reports und Forms

• Reports und Forms sind zustandsfaehige Komponenten.
• Sie kennen nach Moeglichkeit ihre DD/FD.
• Sie speichern und restaurieren ihren Zustand.
• Reload/F5 soll den Zustand erhalten.
• Feldwerte kommen aus Formular, Request oder Remember-State.
• Pagination, Auswahl, Filter und Buttons sollen einheitlich funktionieren.
• Datumswerte bleiben intern DB-konform und werden in der Anzeige usergerecht formatiert.

Datumsformatierung in Reports soll zentral passieren:

• _rpt_format[$field] hat Vorrang.
• Danach gilt $field['convert'] aus DD/FD.
• Danach gilt $field['type'] aus DD/FD.

$field['type']='date';
$field['type']='datetime';
$field['convert']='date';
$field['convert']='date_time';

Deutsche Anzeige:

2026-05-01              -> 01.05.2026
2026-05-01 16:12:26     -> 01.05.2026 16:12:26
2026-05-01 16:12:26.439 -> 01.05.2026 16:12:26.439

Callbacks

Callbacks sollen optional und einfach sein. Kein globales Event-System, keine Listener-Registrierung, keine Prioritaeten, keine Fremdmodule.

Ein DBX-Objekt ruft optionale Methoden auf dem aktuellen Modul-Objekt auf, wenn sie existieren. Fehlen sie, passiert nichts.

private function report_sessions_body($oObj, $content) {
    return $content;
}

private function report_sessions_next_record($oObj, $record) {
    return $record;
}

Der erste Parameter ist immer das aufrufende DBX-Objekt. Der zweite Parameter ist der zu filternde Wert. Die Rueckgabe ersetzt den zweiten Parameter.

Datenquelle und Verantwortung

Deshalb duerfen DB-Aktionen nicht in dbxReport liegen. Beispiel: Tabelle leeren gehoert zu dbxDB, nicht zu dbxReport.

$ok = $db->delete_tab($dd);

dbxReport darf dafuer einen Button oder Platzhalter rendern, aber nicht selbst die DB-Tabelle leeren.

Templates

• HTML wird ueber Templates erzeugt.
• PHP-Code soll keine langen HTML-Fragmente zusammenbauen.
• Ausnahmen nur bei sehr kleinen, klar begruendeten Sonderfaellen.
• Bootstrap-Klassen sollen genutzt werden, wenn es fuer Standard-UI passt.
• Komponentenbezogenes Styling liegt in passenden CSS-Dateien.

Arbeitsweise fuer Codex

1. Vor Aenderungen die betroffenen Dateien lesen.
2. Bestehende DBX-Konventionen beachten.
3. Kleine, gezielte Patches machen.
4. Keine grossen Refactorings ohne Ruecksprache.
5. Keine inkompatiblen Konzeptaenderungen ohne Ruecksprache.
6. Nach Aenderungen PHP-Lint ausfuehren.
7. Wenn sinnvoll, HTTP-Smoke-Test fuer betroffene Route ausfuehren.
8. Alte Altlasten duerfen entfernt werden, wenn das neue Konzept sauberer ist.

Aktueller Fokus

Die modernisierten Admin-Reports sind:

• Sessions
• Missing
• SysMsg
• Trace

Diese Reports dienen als Referenz fuer neue einheitliche DBX-Report-Struktur.