Codex-Leitfaden

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 für 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 Änderung prüfen, 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 müssen lauffähig bleiben, solange nichts anderes vereinbart ist.
4. Neue APIs werden kompatibel als zusätzliche Schicht eingeführt.
5. Direkte Kernel-Änderungen nur, wenn ein echter wiederverwendbarer Steckpunkt fehlt.
6. myX-Vererbung ist offizielle Erweiterungsschicht, kein Notbehelf.
7. State muss nachvollziehbar und wiederherstellbar sein.
8. Konventionen dürfen helfen, müssen 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 größeren 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 möglich:

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 geprüft 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 gehört.
3. Fachliche Sonderlogik erhalten.
4. Neue Baustein-API an Pilotstellen einführen.
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 für die neue Methodik.

8. Hooks und Events

Codex soll Erweiterbarkeit über klare Hooks herstellen, nicht über 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 müssen 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:

• nächster Schritt nach Zustand
• Benutzerentscheidung möglich
• Fehlerbehandlung möglich
• Wiederaufnahme möglich
• Abbruch und Pause möglich

Prozesse müssen für grosse Datenmengen chunkbar sein:

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

Prozesse dürfen nicht vom Browser-Leben abhängen. 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 Wiederöffnen 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 erklären können, 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 einführt, muss der Trace die konkrete Auflösung zeigen.

12. Umsetzungsreihenfolge für Codex

1. Vor Änderungen relevante Doku lesen: RAD-Konzept, Systemdoku, diese Datei, Roadmap.
2. Bestehende Klassen und Modulmuster prüfen, bevor neue Abstraktion gebaut wird.
3. Kleine kompatible API-Ergänzung bevorzugen.
4. Ein Pilotmodul oder ein klarer Use Case zuerst.
5. Trace und Doku bei neuen Bausteinen mitdenken.
6. Tests oder Syntaxchecks ausführen, soweit möglich.
7. Keine grosse Migration ohne explizite Freigabe.

13. Erste konkrete Arbeitspakete

1. dbxApi: Factory-Methoden für db(), tpl(), form(), report() entwerfen.
2. dbxForm: öffentliche Setter/Fluent-Methoden für DD, FD, TPL, Action, Data ergänzen.
3. dbxReport: öffentliche Methoden für Fields, Query, Rows, Sort, Actions ergänzen.
4. Trace-Struktur für Form/Report einführen.
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 Rücksprache 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 Auflösung ohne Trace.
• Keine Fachlogik in den Kernel schieben.
• Keine grossen Modulmigrationen ohne Pilot und Entscheidung.

15. Entscheidungsfragen vor größeren Umbauten

1. Ist das ein allgemeiner Baustein oder nur ein Fachfall?
2. Kann es über DD, FD, Template, Hook oder myX geloest werden?
3. Bleiben alte Module lauffähig?
4. Ist der neue Weg einfacher für Modulautoren?
5. Ist der Ablauf tracebar?
6. Ist State sauber gespeichert und wiederherstellbar?
7. Ist Browser-Schließen sicher?
8. Muss diese Änderung vorher besprochen werden?

16. Zielzustand

dbxapp soll am Ende für drei Gruppen funktionieren:

17. Merksatz für 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.