Referenzdokumente

Diese Seiten sind Spiegelungen der Markdown-Dokumente aus dem Verzeichnis docs/ im Repository. Sie werden bei jedem npm run dev und npm run build frisch nach dev-docs/reference/ kopiert – siehe Wie die Spiegelung funktioniert.

Diese Dokumente sind auf Englisch

Alle neu geschriebenen Seiten dieser Site (Einstieg, Architektur, Erweitern) sind auf Deutsch. Die gespiegelten Referenzdokumente bleiben in ihrer Originalsprache Englisch, weil sie unverändert aus dem Repository übernommen werden. Änderungen gehören immer in die Quelldatei unter docs/, nie in die Kopie unter dev-docs/reference/.

Kern

Dokument	Inhalt
Architektur	Plugin-Identität, die vier tragenden Architektur-Entscheidungen (eigene Tabellen, Relationen auf Anwendungsebene, REST statt admin-ajax.php, optionale Module), Boot-Flow und die Tabelle aller Kern-Services mit ihrer Verantwortung.
Datenbank-Schema	Schema-Version 1: alle Tabellen mit Präfix {wpdb->prefix}ad_form_, Spalten, Indizes, Charset/Collation und das Migrationsvorgehen über den Migrator.
Formular-Schema	Aufbau der JSON-Definition in ad_form_forms.definition: settings, fields, layout, steps, actions, conditions, styles – inklusive der Regeln für stabile Feld-IDs und der gemeinsamen settings-Schlüssel.
REST API	Alle Endpunkte im Namespace ad-form/v1: Formulare, Felder-Katalog, Actions-Katalog, Bedingungen, Berechnungen, öffentlicher Submit und Einträge – mit Methoden, Parametern, Capabilities und Fehlercodes.

Oberflächen

Dokument	Inhalt
Visueller Builder	Die React-Anwendung auf dem Formular-Bearbeitungsscreen (#ad-form-builder): Aufbau aus Palette, Canvas, Inspector und Toolbar, Autosave, Undo/Redo und das Zusammenspiel mit dem Inspector-Schema aus der Field-API.
Frontend-Renderer	Shortcode [ad_form], erzeugtes Markup und CSS-Klassen, AJAX- und Classic-POST-Submit, Honeypot, Nonces sowie das bedingte Laden von form.css und form.js.
Entries / Inbox	Die Admin-Screens für gespeicherte Übermittlungen: Liste, Detailansicht, Statuswechsel (gelesen, Spam, Papierkorb, markiert), Suche und Bulk-Aktionen.
Gutenberg-Block	Der dynamische Block ad-form/form: Registrierung, Attribute, Editor-Verhalten (Picker statt Live-Formular) und die Frontend-Ausgabe über den Shortcode-Pfad.
Elementor-Widget	Das Widget ad-form ab Elementor 3.5: Registrierung, Editor-Platzhalter über content_template und die gemeinsame Frontend-Ausgabe mit FormRenderer.

Formular-Logik

Dokument	Inhalt
Submit-Actions	Aufbau von definition.actions, die eingebaute Email-Action mit ihren Einstellungen, der vollständige Merge-Tag-Katalog und das Verhalten bei Fehlern und übersprungenen Actions.
Bedingte Logik	Struktur einer Bedingungsgruppe (enabled, effect, logic, rules), alle Operatoren und die doppelte Auswertung in PHP und im Browser mit identischem Ergebnis.
Berechnungen	Der Formel-Parser: rekursiv absteigender Evaluator ohne eval(), erlaubte Syntax und Operatoren, Rundung über decimals sowie die Regel, dass übermittelte Rechenwerte serverseitig immer neu berechnet werden.
Multi-Step-Formulare	Wann ein Formular geblättert wird (ab zwei Einträgen in definition.steps), Markup und Navigation, Verhalten ohne JavaScript und warum es genau einen Submit am Ende gibt.

Erweiterung

Dokument	Inhalt
Hooks & Filter (Original)	Die knappe tabellarische Originalfassung aller Hooks, dazu die Liste der Plugin-Capabilities und der für Add-ons gedachten PHP-Interfaces. Die ausführliche Fassung mit Signaturen steht unter Hook-Referenz.

Licensing

Der ausgelieferte Stand des Lizenz- und Entitlement-Systems.

Dokument	Inhalt
Licensing – Überblick	Der Einstieg: die fünf Grundregeln, die strikte Trennung von Plugin-Lizenz und Formular-Zahlungen, der Objektgraph, der Lebenszyklus aus Aktivierung, Validierung und Deaktivierung, die beiden getrennten Uhren und alle neun Zustände.
Entitlements & Feature Gating	Wie entschieden wird, ob ein Feature benutzt werden darf: Auflösung aus Free-Baseline plus signierter Liste, die vollständige API, die Enforcement-Ebenen und warum es bewusst keinen Filter gibt, der Entitlements überschreiben kann.
License API – Vertrag	Der Wire-Vertrag zu api.andredingfelder.com/v1: exakte Request-Felder, Payload-Mitglieder, beide akzeptierten Signaturformate samt Kanonisierungsregeln, Schlüsselrotation und die Fehlercodes mit ihrer Wirkung.
Downgrade-Policy	Was bei Planwechsel, Ablauf oder Widerruf passiert. Kernaussage: es wird nie etwas gelöscht. Dazu die vier Schalter pro Kategorie, das diff-basierte Speicher-Gate und warum bestehende Formulare im Frontend weiterlaufen, Zahlungen aber nicht.
Installationen & Staging	Installation-Identität, warum URLs nie lokal verglichen werden, die Umgebungssignale und ihre Grenzen, die Multisite-Policy und die vollständige Liste der übertragenen Felder.
Licensing-Sicherheit	Die Trust Boundary und eine offene Aussage darüber, was das Verfahren nicht leisten kann. Dazu Secret-Handling, Fail-Closed-Verhalten, DoS-Betrachtung und die verbleibenden Restrisiken.

Feature-Matrix

Dokument	Inhalt
Feature-Matrix	Das Feature-Register. Die Plan-Spalten sind ausschließlich Marketing-Voreinstellungen – maßgeblich zur Laufzeit ist immer die signierte Entitlement-Liste der API.
Feature-Matrix – offene Punkte	Die noch offenen Plan-Zuordnungen, jeweils mit R markiert. Der technische Schlüssel existiert bereits; offen ist nur die Marketing-Zuordnung.
Feature-Enforcement-Audit	Wo jedes bezahlte Feature tatsächlich gestoppt wird, getrennt nach heute durchsetzbar und nur reserviert – inklusive sechs offen benannter Lücken.

Architecture Decision Records

Kurze Entscheidungsprotokolle: Kontext, Entscheidung, Konsequenzen und die verworfenen Alternativen mit Begründung.

ADR	Thema
0001	Warum die Plattform-API autoritativ ist und das Plugin niemals selbst Stripe kontaktiert oder Preise kennt.
0002	Ed25519-signierte Payloads, Verify-on-Read und warum der Public-Key-Registry weder per Filter noch per Konstante konfigurierbar ist.
0003	Die beiden getrennten Uhren: Offline-Grace bei Transportfehlern gegenüber der Business-Grace, die es nicht gibt.
0004	Entitlement-Keys statt Plan-Vergleichen, und warum es keinen Escape-Hatch gibt.
0005	Nichts wird gelöscht, Enforcement pro Phase, diff-basiertes Speicher-Gate.
0006	UUID v4 plus servergestelltes Credential, und warum Klon-Erkennung nicht lokal passiert.
0007	Per-Site-Scope in Multisite, im Einklang mit dem restlichen Plugin.

Phase 0 – Audit

Historische Dokumente aus der Vorbereitungsphase. Sie beschreiben den Stand vor der Implementierung und den damaligen Plan.

Dokument	Inhalt
Architektur-Audit	Read-only-Bestandsaufnahme der Codebasis vor der ersten Zeile Lizenzierungscode: Verzeichnisse, Services, REST-Routen mit Capabilities, Assets, Erweiterungspunkte und 15 Risiken.
Licensing-Integrationsplan	Was gebaut werden sollte, an welchen Stellen es andockt und welche Entscheidungen durch das Audit bereits feststanden.

Wie die Spiegelung funktioniert

Die Quelldokumente unter docs/ werden nicht verschoben und nicht verändert. Das Script dev-docs/scripts/sync-docs.mjs läuft als Pre-Step der npm-Skripte dev und build:

{
  "scripts": {
    "sync": "node scripts/sync-docs.mjs",
    "dev": "npm run sync && vitepress dev",
    "build": "npm run sync && vitepress build"
  }
}

Dabei passiert pro Datei:

1. dev-docs/reference/ wird geleert und neu angelegt – Umbenennungen und Löschungen in docs/ schlagen also sauber durch.
2. Aus der ersten #-Überschrift wird der Titel abgeleitet und als Frontmatter ergänzt (title, dazu editLink: false und outline: [2, 3]). Der Fließtext bleibt unverändert.
3. Relative Links zwischen den Dokumenten werden umgeschrieben. [STEPS.md](STEPS.md) und [Feature-Matrix](docs/FEATURE_MATRIX.md) zeigen danach beide auf die gespiegelte Datei im selben Verzeichnis.
4. Ein relativer Link auf etwas, das nicht gespiegelt wurde – etwa auf eine Quelldatei unter src/ –, verliert den Link und bleibt als Inline-Code stehen. Das Script protokolliert jeden solchen Fall, damit tote Links den Build nicht abbrechen und trotzdem sichtbar bleiben.

Externe Links (http:, https:, mailto:), reine Anker (#…) und Bilder bleiben unberührt.

Weil dev-docs/reference/ generiert ist, steht es in der .gitignore des Repositories. Die Sidebar-Gruppen werden in dev-docs/.vitepress/reference-nav.ts gepflegt und gegen das Dateisystem abgeglichen: Ein neues Dokument in docs/ erscheint automatisch unter „Weitere", auch wenn es dort noch nicht eingruppiert wurde.