From cf253c1367db07d0e9f23270fd1fb54bb3469770 Mon Sep 17 00:00:00 2001 From: Sven Date: Tue, 12 May 2026 11:51:54 +0200 Subject: [PATCH] =?UTF-8?q?codex.md=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- codex.md | 1162 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1162 insertions(+) create mode 100644 codex.md diff --git a/codex.md b/codex.md new file mode 100644 index 0000000..472d017 --- /dev/null +++ b/codex.md @@ -0,0 +1,1162 @@ +# Codex-Anweisung: WordPress-Plugin für GitLab-/Antora-basierte Knowledgebase + +## 1. Projektziel + +Entwickle ein WordPress-Plugin, das technische Produktdokumentationen aus einer GitLab-Gruppe einliest, verarbeitet und innerhalb eines WordPress-basierten Kundenportals veröffentlicht. + +Die vorhandene Dokumentationsstruktur basiert auf **AsciiDoc (`.adoc`)** und ist grundsätzlich für **Antora** ausgelegt. In GitLab existiert eine Gruppe namens `knowledgebase`. Darin liegen mehrere GitLab-Projekte, jeweils ein Projekt pro Produkt oder Modul. Innerhalb jedes Projekts existieren mehrere Branches, wobei jede Branch eine Dokumentationsversion repräsentiert. + +Das Plugin soll diese GitLab-Struktur lesen, relevante Branches erkennen, `.adoc`-Dateien importieren, in HTML rendern und als durchsuchbare, versionierte Dokumentation innerhalb von WordPress bereitstellen. + +Das Ziel ist **nicht**, Antora vollständig nachzubauen. Das Ziel ist ein WordPress-native Plugin, das die bestehende Antora-kompatible Struktur möglichst gut versteht und daraus eine konsistente Kundenportal-Dokumentation erzeugt. + +--- + +## 2. Ausgangssituation + +### 2.1 GitLab-Struktur + +GitLab enthält eine Gruppe: + +```text +knowledgebase/ +├── produkt-a/ +│ ├── Branch: v1.0.0 +│ ├── Branch: v1.1.0 +│ └── Branch: v2.0.0 +├── produkt-b/ +│ ├── Branch: v3.4.0 +│ └── Branch: v3.5.0 +└── produkt-c/ + └── Branch: v1.0.0 +``` + +Jedes Projekt enthält eine Antora-kompatible Dokumentationsstruktur, zum Beispiel: + +```text +antora.yml +modules/ +└── ROOT/ + ├── pages/ + │ ├── index.adoc + │ ├── installation.adoc + │ └── configuration.adoc + ├── images/ + │ └── screenshot.png + ├── partials/ + └── examples/ +``` + +Die genaue Struktur kann je nach Produkt variieren, soll aber an Antora angelehnt bleiben. + +### 2.2 Versionierung + +Die Versionierung erfolgt derzeit über Git-Branches. Branches, die als Dokumentationsversion gelten, beginnen üblicherweise mit `v`, zum Beispiel: + +```text +v1.0.0 +v1.2.0 +v2.0.0 +``` + +Die eigentliche Anzeigenversion kann zusätzlich aus der jeweiligen `antora.yml` gelesen werden. + +Beispiel: + +```yaml +name: produkt-a +title: Produkt A +version: 1.2.0 +nav: + - modules/ROOT/nav.adoc +``` + +Das Plugin soll Branch- und `antora.yml`-Informationen kombinieren. + +--- + +## 3. Grundanforderungen + +Das Plugin soll folgende Kernfunktionen bereitstellen: + +1. Verbindung zu GitLab über API-Token. +2. Auswahl einer GitLab-Gruppe, zum Beispiel `knowledgebase`. +3. Auslesen aller Projekte innerhalb dieser Gruppe. +4. Erkennen relevanter Dokumentationsbranches. +5. Auslesen der `antora.yml` pro Projekt und Branch. +6. Auslesen der Antora-typischen Dateistruktur. +7. Importieren und Rendern von `.adoc`-Dateien nach HTML. +8. Speichern der gerenderten Dokumentationsseiten in WordPress. +9. Abbildung von Produkten, Versionen, Navigationsstruktur und Seiten. +10. Anzeige der Dokumentation im WordPress-Frontend. +11. Suche innerhalb der importierten Dokumentation. +12. Synchronisation per manuellem Button, WP-Cron und optional Webhook. +13. Rechte-/Zugriffssteuerung passend für ein Kundenportal. + +--- + +## 4. Technische Zielarchitektur + +Das Plugin soll als eigenständiges WordPress-Plugin entwickelt werden. + +Vorgeschlagener Plugin-Name: + +```text +kb-antora-importer +``` + +Vorgeschlagene Hauptdatei: + +```text +kb-antora-importer.php +``` + +Vorgeschlagene Struktur: + +```text +kb-antora-importer/ +├── kb-antora-importer.php +├── composer.json +├── readme.md +├── uninstall.php +├── assets/ +│ ├── css/ +│ │ └── frontend.css +│ └── js/ +│ └── frontend.js +├── includes/ +│ ├── Plugin.php +│ ├── Admin/ +│ │ ├── SettingsPage.php +│ │ ├── SyncPage.php +│ │ └── StatusPage.php +│ ├── GitLab/ +│ │ ├── GitLabClient.php +│ │ ├── GitLabProject.php +│ │ └── GitLabBranch.php +│ ├── Antora/ +│ │ ├── AntoraParser.php +│ │ ├── AntoraYamlReader.php +│ │ ├── AntoraNavParser.php +│ │ └── AntoraResourceResolver.php +│ ├── AsciiDoc/ +│ │ ├── AsciiDocRenderer.php +│ │ └── ShortcodeTransformer.php +│ ├── Import/ +│ │ ├── ImportManager.php +│ │ ├── ImportJob.php +│ │ ├── ImportLogger.php +│ │ └── Checksum.php +│ ├── Repository/ +│ │ ├── ProductRepository.php +│ │ ├── VersionRepository.php +│ │ └── PageRepository.php +│ ├── Frontend/ +│ │ ├── Router.php +│ │ ├── TemplateLoader.php +│ │ ├── SearchController.php +│ │ └── BreadcrumbBuilder.php +│ └── Access/ +│ └── AccessController.php +└── templates/ + ├── documentation-index.php + ├── product.php + ├── version.php + ├── page.php + └── search.php +``` + +--- + +## 5. WordPress-Datenmodell + +Es gibt zwei mögliche Umsetzungswege. Codex soll zunächst Variante A umsetzen, sofern nichts dagegenspricht. + +### 5.1 Variante A: Custom Post Types + +Verwende Custom Post Types für die Dokumentationsseiten. + +#### Custom Post Type: `kb_doc_page` + +Repräsentiert eine gerenderte Dokumentationsseite. + +Wichtige Meta-Felder: + +```text +_kb_gitlab_project_id +_kb_gitlab_project_path +_kb_gitlab_branch +_kb_gitlab_commit_sha +_kb_antora_component +_kb_antora_component_title +_kb_antora_version +_kb_antora_module +_kb_antora_page_path +_kb_antora_source_path +_kb_page_checksum +_kb_last_imported_at +_kb_nav_order +_kb_parent_page_path +``` + +#### Taxonomie: `kb_product` + +Repräsentiert Produkt oder Modul. + +Beispiele: + +```text +Produkt A +Produkt B +STARFACE Modul X +Yeastar Integration Y +``` + +#### Taxonomie: `kb_version` + +Repräsentiert Dokumentationsversionen. + +Beispiele: + +```text +1.0.0 +1.2.0 +2.0.0 +``` + +#### Taxonomie: `kb_component` + +Optional, falls Antora-Komponenten explizit abgebildet werden sollen. + +--- + +### 5.2 Variante B: Eigene Datenbanktabellen + +Diese Variante ist für spätere Skalierung möglich, soll aber nicht initial umgesetzt werden, außer WordPress-Performance oder Datenmodellgründe erzwingen es. + +Mögliche Tabellen: + +```text +wp_kb_products +wp_kb_versions +wp_kb_pages +wp_kb_assets +wp_kb_import_logs +``` + +Für den MVP soll jedoch WordPress-nativ mit Custom Post Types gearbeitet werden. + +--- + +## 6. GitLab-Integration + +### 6.1 Konfiguration im WordPress-Backend + +Erstelle eine Admin-Seite unter: + +```text +Einstellungen → Knowledgebase +``` + +Oder als eigener Menüpunkt: + +```text +Knowledgebase +├── Übersicht +├── Synchronisation +├── Einstellungen +└── Import-Logs +``` + +Benötigte Einstellungen: + +```text +GitLab Base URL +GitLab API Token +GitLab Group Path oder Group ID +Branch Pattern, Standard: ^v\d+\.\d+\.\d+.*$ +Standard-Synchronisationsintervall +Frontend-Basis-Slug, Standard: /docs/ +Zugriffsbeschränkung aktiv/inaktiv +``` + +Beispiele: + +```text +GitLab Base URL: https://git.example.de +GitLab Group Path: knowledgebase +Branch Pattern: ^v.* +Frontend-Basis-Slug: docs +``` + +### 6.2 API-Zugriff + +Implementiere eine Klasse `GitLabClient`. + +Aufgaben: + +1. Authentifizierung per Private Token oder Bearer Token. +2. Abrufen der Gruppe. +3. Abrufen aller Projekte innerhalb der Gruppe. +4. Abrufen aller Branches pro Projekt. +5. Filtern der Branches nach Pattern. +6. Abrufen einzelner Dateien per Repository Files API. +7. Abrufen von Repository Trees. +8. Abrufen von Raw File Content. +9. Fehlerbehandlung für 401, 403, 404, 429 und 5xx. +10. Optional: einfache Rate-Limit-Behandlung. + +Der Token darf niemals im Klartext ausgegeben werden. + +Speicherung des Tokens: + +- möglichst verschlüsselt oder zumindest über WordPress Options API geschützt, +- niemals in Logs, +- niemals im Frontend, +- niemals in Fehlermeldungen. + +--- + +## 7. Antora-Kompatibilität + +Das Plugin soll zentrale Antora-Konzepte verstehen, ohne Antora vollständig nachzubauen. + +### 7.1 `antora.yml` + +Pro Projekt und Branch soll die Datei `antora.yml` gelesen werden. + +Relevante Felder: + +```yaml +name: product-name +title: Product Title +version: 1.2.0 +nav: + - modules/ROOT/nav.adoc +``` + +Verwendung: + +```text +name → interner Komponenten-/Produktname +title → Anzeigename im Frontend +version → Anzeigenversion +nav → Navigationsdateien +``` + +Falls `antora.yml` fehlt: + +- Projekt nicht hart abbrechen, +- Fehler sauber loggen, +- Projekt/Branch überspringen oder Fallback verwenden, +- Importstatus anzeigen. + +### 7.2 Module + +Unterstütze mindestens: + +```text +modules/ROOT/pages/ +modules/ROOT/images/ +modules/ROOT/partials/ +modules/ROOT/examples/ +modules/ROOT/nav.adoc +``` + +Später optional: + +```text +modules//pages/ +modules//images/ +modules//partials/ +modules//examples/ +``` + +MVP-Anforderung: + +- `ROOT`-Modul vollständig unterstützen. +- Weitere Module erkennen, aber zunächst einfach als zusätzliche Bereiche importieren. + +### 7.3 Navigation + +Antora nutzt häufig `nav.adoc`. + +Beispiel: + +```adoc +* xref:index.adoc[Einführung] +* Installation +** xref:installation.adoc[Installation] +** xref:configuration.adoc[Konfiguration] +``` + +Das Plugin soll daraus eine hierarchische Navigation erzeugen. + +Anforderungen: + +1. `xref:`-Links erkennen. +2. Titel aus eckigen Klammern lesen. +3. Verschachtelung anhand der Sternchen-Ebene erkennen. +4. Seitenreihenfolge speichern. +5. Nicht verlinkte Überschriften als Navigationsgruppen darstellen. +6. Navigation im Frontend als Sidebar ausgeben. + +--- + +## 8. AsciiDoc-Rendering + +### 8.1 Grundsatz + +`.adoc`-Dateien müssen in HTML gerendert werden. + +Mögliche Renderer: + +1. PHP-basierter AsciiDoc-Parser, falls ausreichend stabil. +2. Externer CLI-Aufruf zu Asciidoctor, falls verfügbar. +3. Container-/Service-basierter Renderer als spätere Option. + +Für den MVP soll eine robuste und realistische Lösung gewählt werden. Wenn ein vollständiger AsciiDoc-Renderer in PHP nicht zuverlässig verfügbar ist, soll das Plugin optional `asciidoctor` per CLI verwenden können. + +### 8.2 Renderer-Konfiguration + +Backend-Einstellung: + +```text +Renderer Mode: +- PHP Renderer +- Asciidoctor CLI +- External Render Service später +``` + +Wenn `asciidoctor` CLI verwendet wird: + +- Pfad konfigurierbar machen, +- Verfügbarkeit prüfen, +- Fehlermeldung im Status anzeigen, +- keine unsicheren Shell-Aufrufe, +- Eingaben escapen, +- temporäre Dateien sicher speichern und löschen. + +### 8.3 Mindestfeatures + +Folgende AsciiDoc-Features sollen unterstützt werden: + +```text +Überschriften +Absätze +Listen +Tabellen +Quellcodeblöcke +Admonitions / Hinweise +Bilder +Interne xref-Links +Externe Links +Includes / Partials, soweit lokal auflösbar +``` + +### 8.4 Link-Transformation + +Antora-/AsciiDoc-Links müssen in WordPress-URLs umgeschrieben werden. + +Beispiele: + +```adoc +xref:installation.adoc[Installation] +image::screenshot.png[Screenshot] +``` + +Soll werden zu: + +```html +Installation +Screenshot +``` + +Bei fehlendem Ziel: + +- Link markieren, +- Importwarnung loggen, +- Frontend nicht hart abbrechen. + +--- + +## 9. Assets und Bilder + +Bilder aus Antora-Strukturen müssen importiert oder proxyfähig ausgeliefert werden. + +### 9.1 Import in WordPress Media Library + +Bevorzugt für MVP: + +1. Bilder aus `modules/*/images/` erkennen. +2. In die WordPress Media Library importieren. +3. Medien-ID speichern. +4. Bildreferenzen im HTML auf WordPress-Medien-URLs umschreiben. +5. Checksums nutzen, damit Bilder nicht bei jedem Sync dupliziert werden. + +### 9.2 Unterstützte Dateitypen + +Mindestens: + +```text +.png +.jpg +.jpeg +.gif +.svg +.webp +``` + +SVG nur zulassen, wenn sicher behandelt oder explizit erlaubt. + +### 9.3 Lightbox-Kompatibilität + +Das gerenderte HTML soll optional CSS-Klassen oder Attribute erhalten, damit Bilder im Frontend mit einer Lightbox geöffnet werden können. + +Beispiel: + +```html + + ... + +``` + +Dies soll als Option steuerbar sein: + +```text +Bilder automatisch mit Lightbox verlinken: ja/nein +``` + +--- + +## 10. Frontend-Ausgabe + +Die Dokumentation soll unter einem konfigurierbaren Basis-Slug erscheinen. + +Standard: + +```text +/docs/ +``` + +URL-Struktur: + +```text +/docs/ +/docs/{product}/ +/docs/{product}/{version}/ +/docs/{product}/{version}/{page}/ +``` + +Beispiele: + +```text +/docs/starface-modul-x/ +/docs/starface-modul-x/2.1.0/ +/docs/starface-modul-x/2.1.0/installation/ +``` + +### 10.1 Frontend-Komponenten + +Jede Dokumentationsseite soll enthalten: + +1. Produktname. +2. Versionsauswahl. +3. Sidebar-Navigation. +4. Breadcrumbs. +5. Hauptinhalt. +6. Optional: Inhaltsverzeichnis der Seite. +7. Optional: Hinweis, wenn es eine neuere Version gibt. +8. Suchfeld innerhalb der Dokumentation. + +### 10.2 Shortcodes oder Blöcke + +Zusätzlich sollen Shortcodes bereitgestellt werden: + +```text +[kb_docs_index] +[kb_product_index product="produkt-a"] +[kb_search] +``` + +Optional später Gutenberg-Blöcke. + +--- + +## 11. Suche + +Für den MVP reicht eine WordPress-native Suche über den Custom Post Type `kb_doc_page`. + +Anforderungen: + +1. Suche nur innerhalb der Dokumentation. +2. Filter nach Produkt. +3. Filter nach Version. +4. Treffer mit Titel, Auszug und Produkt-/Versionskontext anzeigen. + +Später optional: + +- Relevanzranking, +- Volltextindex, +- externe Search Engine, +- Synonyme, +- Suchstatistiken. + +--- + +## 12. Synchronisation + +### 12.1 Manuelle Synchronisation + +Backend-Seite: + +```text +Knowledgebase → Synchronisation +``` + +Funktionen: + +1. Alle Projekte synchronisieren. +2. Einzelnes Projekt synchronisieren. +3. Einzelne Version/Branch synchronisieren. +4. Dry Run durchführen. +5. Import-Log anzeigen. + +### 12.2 WP-Cron + +Konfigurierbare automatische Synchronisation: + +```text +Deaktiviert +Stündlich +Täglich +Wöchentlich +``` + +### 12.3 Webhook später + +Optional soll vorbereitet werden: + +```text +/wp-json/kb-antora/v1/gitlab-webhook +``` + +Der Webhook soll später GitLab Push Events empfangen können. + +Für MVP nur vorbereiten oder als einfache Version implementieren. + +--- + +## 13. Importlogik + +### 13.1 Importablauf + +Pro Synchronisation: + +1. Einstellungen laden. +2. GitLab-Verbindung prüfen. +3. Gruppe abrufen. +4. Projekte abrufen. +5. Pro Projekt Branches abrufen. +6. Branches nach Pattern filtern. +7. Pro Branch `antora.yml` abrufen. +8. Version und Produkttitel bestimmen. +9. Repository Tree abrufen. +10. `.adoc`-Dateien unter `modules/*/pages/` finden. +11. Assets unter `modules/*/images/` finden. +12. Navigation aus `nav.adoc` lesen. +13. Assets importieren. +14. `.adoc` rendern. +15. Links und Bilder umschreiben. +16. WordPress-Posts erstellen oder aktualisieren. +17. Veraltete Seiten markieren. +18. Importlog schreiben. + +### 13.2 Update-Erkennung + +Verwende Checksums und/oder Git Commit SHA. + +Wenn sich eine Datei nicht geändert hat: + +- nicht neu rendern, +- nicht unnötig WordPress-Post aktualisieren, +- Importzeit sparen. + +### 13.3 Löschverhalten + +Wenn eine Seite in GitLab nicht mehr existiert: + +Optionen: + +```text +Als veraltet markieren +In Papierkorb verschieben +Hart löschen +Ignorieren +``` + +MVP-Standard: + +```text +Als veraltet markieren +``` + +--- + +## 14. Rechte und Kundenportal-Integration + +Das Plugin wird in einem Kundenportal verwendet. Dokumentationen dürfen je nach Portalstruktur nicht immer öffentlich sein. + +### 14.1 Zugriff + +Backend-Option: + +```text +Dokumentation öffentlich anzeigen: ja/nein +``` + +Wenn nein: + +- nur eingeloggte Benutzer dürfen Dokumentation sehen. + +Später optional: + +- Zugriff nach Produkt, +- Zugriff nach Kundengruppe, +- Zugriff nach WordPress-Rolle, +- Zugriff nach Membership-/Portal-Plugin. + +### 14.2 WordPress Capabilities + +Neue Capabilities: + +```text +manage_kb_docs +view_kb_docs +sync_kb_docs +``` + +Administratoren erhalten alle Capabilities automatisch. + +--- + +## 15. Admin-UX + +Das Backend soll technisch sauber, aber nicht überladen sein. + +### 15.1 Übersichtsseite + +Anzeigen: + +```text +GitLab-Verbindungsstatus +Anzahl Projekte +Anzahl importierte Produkte +Anzahl Versionen +Anzahl Seiten +Letzte Synchronisation +Letzter Fehler +Renderer-Status +``` + +### 15.2 Synchronisationsseite + +Anzeigen: + +```text +Button: Alles synchronisieren +Button: Dry Run +Projektliste mit Sync-Button pro Projekt +Fortschritts-/Statusanzeige +Importlogs +``` + +### 15.3 Einstellungen + +Felder: + +```text +GitLab Base URL +GitLab Token +GitLab Group Path / ID +Branch Pattern +Docs Base Slug +Renderer Mode +Asciidoctor Path +Lightbox für Bilder +Öffentlich / nur eingeloggte Benutzer +Cron-Intervall +``` + +Alle Eingaben validieren und escapen. + +--- + +## 16. REST API + +Erstelle eine kleine interne REST API für Admin-Aktionen. + +Namespace: + +```text +kb-antora/v1 +``` + +Routen: + +```text +GET /status +POST /sync +POST /sync/project +GET /search +POST /gitlab-webhook optional +``` + +Alle schreibenden Endpoints müssen Nonce- und Capability-Prüfung verwenden. + +--- + +## 17. Sicherheit + +Besondere Anforderungen: + +1. GitLab-Token niemals ausgeben. +2. Alle Admin-Aktionen mit Capability Checks absichern. +3. REST-API mit Nonces und Berechtigungen schützen. +4. Gerendertes HTML sanitizen. +5. Keine ungeprüften Shell-Befehle. +6. Temporäre Dateien sicher behandeln. +7. SVG nur nach Sanitizing oder deaktiviert. +8. Keine privaten GitLab-URLs im Frontend leaken. +9. Keine Stacktraces im Frontend. +10. Logs ohne Secrets speichern. + +--- + +## 18. Performance + +Die Dokumentation kann viele Produkte, Versionen und Seiten enthalten. Deshalb: + +1. Imports in Batches ausführen. +2. Lange Prozesse nicht direkt in einem einzelnen HTTP-Request blockieren, wenn vermeidbar. +3. Checksums verwenden. +4. Caching für Navigationsbäume. +5. Caching für Produkt-/Versionslisten. +6. WP_Query effizient halten. +7. Nur geänderte Dateien neu rendern. +8. Importlogs begrenzen oder rotieren. + +Für den MVP darf die manuelle Synchronisation zunächst sequentiell laufen, solange der Code so strukturiert ist, dass Batch-/Queue-Verarbeitung später leicht ergänzt werden kann. + +--- + +## 19. Fehlerbehandlung und Logging + +Implementiere Importlogs mit Schweregraden: + +```text +INFO +WARNING +ERROR +DEBUG optional +``` + +Zu loggende Ereignisse: + +```text +GitLab-Verbindung erfolgreich/fehlgeschlagen +Projekt gefunden +Branch gefunden +Branch übersprungen +antora.yml gefunden/fehlt/fehlerhaft +nav.adoc gefunden/fehlt/fehlerhaft +Seite importiert +Seite aktualisiert +Seite unverändert +Asset importiert +Linkziel fehlt +Rendering fehlgeschlagen +Synchronisation abgeschlossen +``` + +Logs sollen im Backend sichtbar sein. + +--- + +## 20. MVP-Umfang + +Der erste funktionsfähige Stand soll Folgendes können: + +1. Plugin installierbar und aktivierbar. +2. Admin-Einstellungen für GitLab-Zugang. +3. Verbindungstest zu GitLab. +4. Projekte einer GitLab-Gruppe abrufen. +5. Branches nach Pattern `^v.*` erkennen. +6. `antora.yml` lesen. +7. `modules/ROOT/pages/*.adoc` importieren. +8. Einfache `.adoc`-Dateien nach HTML rendern. +9. Bilder aus `modules/ROOT/images/` importieren. +10. Interne `xref:`-Links umschreiben. +11. Seiten als `kb_doc_page` speichern. +12. Frontend-Ausgabe unter `/docs/{product}/{version}/{page}/`. +13. Produktindex und Versionsauswahl anzeigen. +14. Einfache Sidebar aus `nav.adoc` erzeugen. +15. Manuelle Synchronisation im Backend. +16. Importlogs anzeigen. + +--- + +## 21. Nicht-Ziele für den MVP + +Nicht im ersten Schritt umsetzen: + +1. Vollständige Antora-Engine nachbauen. +2. Mehrsprachigkeit. +3. Komplexe Berechtigung nach Kunde/Produkt. +4. Externe Suchmaschine. +5. Live-Rendering bei jedem Seitenaufruf. +6. GitLab-Webhook mit vollständiger Eventlogik. +7. Gutenberg-Blöcke. +8. Visueller Editor für `.adoc`. +9. Merge-Request-Workflow. +10. Antora UI Bundles vollständig unterstützen. + +--- + +## 22. Coding-Standards + +Bitte nach WordPress-Standards entwickeln: + +1. PHP 8.1+ kompatibel. +2. WordPress Coding Standards berücksichtigen. +3. Namespaces verwenden. +4. Klassen sauber trennen. +5. Keine Businesslogik in Templates. +6. Keine direkten `$_POST`/`$_GET`-Zugriffe ohne Sanitizing. +7. Alle Ausgaben escapen. +8. Transients/Options API sinnvoll verwenden. +9. Composer Autoloading nutzen, falls sinnvoll. +10. Code dokumentieren, aber nicht überkommentieren. + +Namespace-Vorschlag: + +```php +Obyte\Knowledgebase\ +``` + +Oder neutral: + +```php +KbAntoraImporter\ +``` + +--- + +## 23. Akzeptanzkriterien + +Der MVP gilt als erfolgreich, wenn folgende Tests bestehen: + +### 23.1 Installation + +- Plugin lässt sich in WordPress aktivieren. +- Admin-Menü erscheint. +- Keine PHP-Warnings oder Fatal Errors. + +### 23.2 GitLab-Verbindung + +- GitLab Base URL und Token können gespeichert werden. +- Verbindungstest funktioniert. +- Gruppe `knowledgebase` kann gelesen werden. +- Projekte werden angezeigt. + +### 23.3 Import + +- Mindestens ein Projekt mit Branch `v1.0.0` wird erkannt. +- `antora.yml` wird gelesen. +- `.adoc`-Seiten werden importiert. +- Bilder werden importiert oder korrekt referenziert. +- Seiten erscheinen als `kb_doc_page`. + +### 23.4 Frontend + +- `/docs/` zeigt eine Dokumentationsübersicht. +- `/docs/{product}/` zeigt Produktversionen. +- `/docs/{product}/{version}/` zeigt die Versionsübersicht. +- `/docs/{product}/{version}/{page}/` zeigt die gerenderte Seite. +- Sidebar-Navigation funktioniert. +- Interne Links funktionieren. + +### 23.5 Sync + +- Erneuter Import dupliziert keine Seiten. +- Geänderte Seiten werden aktualisiert. +- Unveränderte Seiten bleiben unverändert. +- Fehler werden im Log sichtbar. + +--- + +## 24. Entwicklungsreihenfolge + +Bitte in dieser Reihenfolge entwickeln: + +1. Plugin-Grundstruktur und Autoloading. +2. Admin-Menü und Einstellungsseite. +3. GitLabClient mit Verbindungstest. +4. Projekt- und Branch-Erkennung. +5. `antora.yml` Reader. +6. Repository Tree Reader. +7. Importmodell für Produkte, Versionen und Seiten. +8. Custom Post Type und Taxonomien. +9. Einfacher AsciiDoc Renderer. +10. Link- und Bild-Umschreibung. +11. Frontend-Routing und Templates. +12. Navigation aus `nav.adoc`. +13. Importlogs. +14. Suche. +15. Cron/Webhook-Grundlage. +16. Sicherheits- und Performance-Review. + +--- + +## 25. Wichtige Architekturentscheidung + +Das Plugin soll Dokumentation **nicht bei jedem Seitenaufruf live aus GitLab rendern**. + +Stattdessen: + +```text +GitLab → Sync/Import → WordPress-Speicherung → Frontend-Ausgabe aus WordPress +``` + +Begründung: + +1. Bessere Performance. +2. Kein GitLab-API-Zugriff bei jedem Kundenaufruf. +3. Bessere WordPress-Suche. +4. Bessere Kontrolle über Zugriffsrechte. +5. Stabileres Kundenportal bei GitLab-Ausfällen. + +--- + +## 26. Beispiel-Frontend-Struktur + +Dokumentationsübersicht: + +```text +/docs/ + +Knowledgebase +├── Produkt A +│ ├── Version 1.0.0 +│ └── Version 1.2.0 +├── Produkt B +│ └── Version 3.5.0 +└── Produkt C + └── Version 1.0.0 +``` + +Produktseite: + +```text +/docs/produkt-a/ + +Produkt A +Verfügbare Versionen: +- 2.0.0 aktuell +- 1.2.0 +- 1.0.0 +``` + +Dokuseite: + +```text +/docs/produkt-a/2.0.0/installation/ + +[Sidebar Navigation] +Produkt A / 2.0.0 / Installation + +

Installation

+... +``` + +--- + +## 27. Beispiel für interne Linkauflösung + +Quelle: + +```adoc +Weitere Informationen findest du unter xref:configuration.adoc[Konfiguration]. +``` + +Kontext: + +```text +Produkt: produkt-a +Version: 2.0.0 +Aktuelle Seite: installation.adoc +``` + +Ziel: + +```html +Weitere Informationen findest du unter Konfiguration. +``` + +--- + +## 28. Beispiel für Bildauflösung + +Quelle: + +```adoc +image::screenshot-login.png[Login-Screenshot] +``` + +Suchpfad: + +```text +modules/ROOT/images/screenshot-login.png +``` + +Ziel: + +```html +
+ + Login-Screenshot + +
+``` + +--- + +## 29. Erwartetes Ergebnis + +Am Ende soll ein installierbares WordPress-Plugin entstehen, das vorhandene GitLab-/Antora-Dokumentationen aus der Gruppe `knowledgebase` importiert und im WordPress-Kundenportal als strukturierte, versionierte Knowledgebase veröffentlicht. + +Das Plugin soll technisch sauber, wartbar und erweiterbar sein. Der MVP soll bewusst pragmatisch bleiben, aber die Architektur muss spätere Erweiterungen erlauben, insbesondere: + +```text +kundenspezifische Berechtigungen +bessere Suche +GitLab-Webhooks +mehrere Module +mehrsprachige Dokumentation +Gutenberg-Blöcke +externen Render-Service +``` + +--- + +## 30. Zusätzliche Hinweise für Codex + +- Arbeite inkrementell. +- Nach jeder größeren Änderung soll der Code lauffähig bleiben. +- Keine Platzhalterfunktionen ohne klare TODO-Kommentare. +- Keine unnötigen Framework-Abhängigkeiten. +- WordPress-Kompatibilität priorisieren. +- Fehler lieber sichtbar loggen als still verschlucken. +- Sicherheitsrelevante Eingaben immer validieren, sanitizen und escapen. +- Plugin so entwickeln, dass es später in einem produktiven Kundenportal betrieben werden kann. +