1. Auftrag

Codex soll dbxapp zu einer Borland-, Concept16- und DataFlex-inspirierten PHP-Web-RAD-Runtime weiterentwickeln. Das Ziel ist eine klare, schnelle, sichere und vorhersehbare Runtime fuer Business-Anwendungen.

Die Entwicklung folgt dem LEGO-Prinzip:

Wenige genormte Anschluesse.
Viele kombinierbare Bausteine.
Keine versteckte Magie im Kern.
Wow-Effekt im UI.
Alles tracebar.
Alles erweiterbar ohne Kernel-Hack.

Codex soll bei jeder Aenderung pruefen, ob sie dieses Ziel unterstuetzt oder dbxapp komplizierter macht.

2. Nicht verhandelbare Vorgaben

1. dbxapp bleibt PHP-Web-Runtime, keine Laravel-/React-/SPA-Neuerfindung.
2. DD, FD, Templates, Module und Client-Libs bleiben zentrale Saeulen.
3. Alte Module muessen lauffaehig bleiben, solange nichts anderes vereinbart ist.
4. Neue APIs werden kompatibel als zusaetzliche Schicht eingefuehrt.
5. Direkte Kernel-Aenderungen nur, wenn ein echter wiederverwendbarer Steckpunkt fehlt.
6. myX-Vererbung ist offizielle Erweiterungsschicht, kein Notbehelf.
7. State muss nachvollziehbar und wiederherstellbar sein.
8. Konventionen duerfen helfen, muessen aber tracebar sein.

3. Architektur-Ziel

dbxApp Runtime
  dbxApi / Services
  dbxComponent-Stecknorm
  dbxForm
  dbxReport
  dbxGrid
  dbxDialog
  dbxWindow
  dbxWorkflow
  dbxProcess
  DD / FD
  Templates
  Module
  Client Runtime
  myX Overrides

Codex soll nicht sofort eine grosse Basisklasse erzwingen. Erst wird die Stecknorm in Form und Report bewiesen. Eine echte dbxComponent-Basisklasse kommt erst, wenn die gemeinsamen Funktionen stabil verstanden sind.

4. Komponenten-Stecknorm

Alle groesseren Komponenten sollen langfristig diese Anschluesse verstehen:

id
context
dd
fd
tpl
data
state
request
actions
events / hooks
render
client
trace

Neue Methoden sollen kurz, sprechend und einheitlich sein:

->dd('kunde')
->fd('kunden|edit')
->tpl('kunden|edit')
->data($data)
->action($url)
->state('kunden.edit')
->run()

Jede neue Komponente soll allein funktionieren und in anderen Komponenten nutzbar sein.

5. Modulcode neuer Stil

Module sollen fachlich, kurz und lesbar sein.

class kunden {
    public function run() {
        return dbx()->actions($this)
            ->default('list')
            ->run();
    }

    public function list() {
        return dbx()->report('kunden')->run();
    }

    public function edit() {
        return dbx()->form('kunde')->run();
    }
}

Fortgeschrittene Anpassung bleibt moeglich:

return dbx()->report('kunden')
    ->dd('kunde')
    ->fd('kunden|rpt-kunden')
    ->rows(25)
    ->search(['name', 'email'])
    ->rowEdit()
    ->rowDelete()
    ->on('format_row', [$this, 'formatCustomerRow'])
    ->run();

Wenn Codex in einem Modul viel technischen Standardcode sieht, soll geprueft werden, ob daraus ein Kernbaustein entstehen sollte.

6. Umgang mit bestehenden Modulen

Bestehende Module sind wertvoll, weil sie echte Anforderungen zeigen. Sie sollen nicht blind umgebaut werden.

1. Ist-Muster erkennen: Routing, Form, Report, Grid, JSON, State, Aktionen, Speziallogik.
2. Standardverhalten identifizieren, das in den Kern gehoert.
3. Fachliche Sonderlogik erhalten.
4. Neue Baustein-API an Pilotstellen einfuehren.
5. Alten Code nicht entfernen, solange kein kompatibler Ersatz existiert.
6. Bei grossem Umbau lieber Modul neu nach Methodik erstellen als kosmetisch flicken.

Aktuelle Muster:

• myLKW: Routing, Sync, Tagesverschiebung, JSON, Prozesse.
• myLKW_list: Grid read/sort/save/delete/sync.
• myLKW_report: Spezialreport, Row-Formatierung, Print-Spalten.
• dbxUser_admin: Admin-Reports, Row-/Multi-Actions, Modal.
• dbxContent_edit: Form-Edit-Flow, Observer, Wait-State.

7. Form- und Report-Strategie

Form und Report sind die ersten Kernbausteine fuer die neue Methodik.

8. Hooks und Events

Codex soll Erweiterbarkeit ueber klare Hooks herstellen, nicht ueber Kopien grosser Methoden.

before_load
after_load
before_validate
after_validate
before_save
after_save
before_process
after_process
before_render
after_render
on_error
on_cancel

Report-spezifisch:

format_row
row_class
before_row
after_row
row_action
before_query
after_query

Grid-spezifisch:

before_read
after_read
before_save
after_save
before_delete
after_delete
sync
json_response

Hooks muessen dokumentiert, vorhersehbar und mit Trace sichtbar sein.

9. Workflow- und Process-Arbeit

Codex soll Workflow und Process sauber trennen:

Workflow = fachlicher Ablauf
Process  = technische Ausfuehrung
Step     = einzelner Schritt
State    = gespeicherter Zustand

Workflows sind smart, nicht starr:

• naechster Schritt nach Zustand
• Benutzerentscheidung moeglich
• Fehlerbehandlung moeglich
• Wiederaufnahme moeglich
• Abbruch und Pause moeglich

Prozesse muessen fuer grosse Datenmengen chunkbar sein:

State laden
Pause/Cancel pruefen
Chunk verarbeiten
Fortschritt speichern
Status ausgeben

Prozesse duerfen nicht vom Browser-Leben abhaengen. Der Browser steuert und zeigt nur an.

10. Persistenter State

Codex soll State als Kernanforderung behandeln, nicht als Nebenprodukt.

State-Ebenen:

sys      = Laufkontext des aktuellen Requests
mod      = aktive Modulinstanz
remember = laenger gueltiger Benutzer-/UI-State
session  = strukturierter Session-State
process  = persistenter Langlauf-State

Prozess-State muss mindestens enthalten:

process_id
status
current_step
cursor
processed_count
total_count
payload
result
last_error
pause_requested
cancel_requested
updated_at

Beim Wiederoeffnen von dbxapp muss klar erkennbar sein, welche Arbeit offen ist und wo fortgesetzt werden kann.

11. Trace-Pflicht

Keine Magie im Kern. Jede Komponente soll erklaeren koennen, was sie tut:

component: report users
class: dbxReport / myReport / module custom class
module: dbxUser_admin
dd: dbxUser
fd: dbxUser_admin|rpt-users
tpl: dbxUser_admin|report-users
state: dbxUser_admin.report.users
actions: row_edit,row_delete,multi_delete
hooks: format_row,before_query
client: report.js/grid.js

Wenn Codex Konventionen einfuehrt, muss der Trace die konkrete Aufloesung zeigen.

12. Umsetzungsreihenfolge fuer Codex

1. Vor Aenderungen relevante Doku lesen: RAD-Konzept, Systemdoku, diese Datei, Roadmap.
2. Bestehende Klassen und Modulmuster pruefen, bevor neue Abstraktion gebaut wird.
3. Kleine kompatible API-Ergaenzung bevorzugen.
4. Ein Pilotmodul oder ein klarer Use Case zuerst.
5. Trace und Doku bei neuen Bausteinen mitdenken.
6. Tests oder Syntaxchecks ausfuehren, soweit moeglich.
7. Keine grosse Migration ohne explizite Freigabe.

13. Erste konkrete Arbeitspakete

1. dbxApi: Factory-Methoden fuer db(), tpl(), form(), report() entwerfen.
2. dbxForm: oeffentliche Setter/Fluent-Methoden fuer DD, FD, TPL, Action, Data ergaenzen.
3. dbxReport: oeffentliche Methoden fuer Fields, Query, Rows, Sort, Actions ergaenzen.
4. Trace-Struktur fuer Form/Report einfuehren.
5. dbxAdmin Session-Liste als Report-Pilot vorbereiten.
6. dbxUser_admin Gruppen-Form als Form-Pilot vorbereiten.
7. myLKW_list als Grid-Pilot analysieren und neue Grid-Anforderungen ableiten.
8. dbxProcess-DD/Tabelle konzipieren, aber erst nach Ruecksprache implementieren.

14. Was Codex vermeiden soll

• Kein kompletter Rewrite.
• Kein neues externes Framework als Kernersatz.
• Keine Entfernung alter API-Wege ohne Freigabe.
• Keine statischen, unflexiblen Workflows.
• Keine versteckte automatische Aufloesung ohne Trace.
• Keine Fachlogik in den Kernel schieben.
• Keine grossen Modulmigrationen ohne Pilot und Entscheidung.

15. Entscheidungsfragen vor groesseren Umbauten

1. Ist das ein allgemeiner Baustein oder nur ein Fachfall?
2. Kann es ueber DD, FD, Template, Hook oder myX geloest werden?
3. Bleiben alte Module lauffaehig?
4. Ist der neue Weg einfacher fuer Modulautoren?
5. Ist der Ablauf tracebar?
6. Ist State sauber gespeichert und wiederherstellbar?
7. Ist Browser-Schliessen sicher?
8. Muss diese Aenderung vorher besprochen werden?

16. Zielzustand

dbxapp soll am Ende fuer drei Gruppen funktionieren:

17. Merksatz fuer Codex

dbxapp ist kein Puzzle und kein Zauberkasten.
dbxapp ist eine klare LEGO-RAD-Runtime.

Der Kern setzt die Stecknorm.
DD, FD und Templates beschreiben die Anwendung.
Komponenten fuehren vorhersehbar aus.
Hooks und myX machen alles erweiterbar.
State macht Arbeit wiederherstellbar.
Das UI darf glaenzen.