Intern · Version 1.0 · 01.11.2025

HBW Importer Mini – Spezifikation

Diese Spezifikation beschreibt das Verhalten des HBW Importer Mini (MU-Plugin), der im Ordner
wp-content/updates_ki_html/ abgelegte Dateien einliest und anhand des HBW-Headers WordPress-Seiten erstellt oder aktualisiert. Kanonisch ist das Feld permalink.

1 · Geltungsbereich & Ziel

Scope: Einlesen von .html (primär) und optional .md aus wp-content/updates_ki_html/.
Ziel: Update bestehender Seiten (Match via permalink) oder Erzeugung neuer Seiten.
Kein Build: .css, .js u. ä. werden nicht geparst (nur via Batch hochgeladen).

2 · Trigger & Ordnerstruktur

Ein Importlauf startet, sobald sich in wp-content/updates_ki_html/ mindestens eine Datei mit Endung .flag befindet (z. B. run.flag). Nach dem Lauf werden alle Flag-Dateien gelöscht.

wp-content/updates_ki_html/ – Eingang für HTML/MD + Flag
wp-content/updates_ki_html/processed/ – erfolgreich verarbeitete Eingaben
wp-content/updates_ki_html/error/ – nicht verarbeitbare Eingaben
wp-content/updates_ki_html/logs/ – Laufprotokolle hbw-importer-mini-YYYYMMDD_HHMMSS.log

3 · HBW-Header (kanonisch)

Jede Eingabedatei enthält am Anfang einen Kommentarblock mit JSON (UTF-8, ohne BOM):

<!-- HBW
{
  "title": "Seitentitel",
  "permalink": "/grundlagen/was-ist-bewusstsein/",
  "file": "was-ist-bewusstsein_v3.7.1.html",
  "post_type": "page",
  "status": "publish",
  "version": "3.7.1",
  "date": "2025-11-01 10:42:00",
  "parent": "/grundlagen/",
  "author": "Clara"
}
-->

title (string, empfohlen) – Seitentitel; bei Update optional.
permalink (string, erforderlich) – kanonischer Seitenpfad (beginnend mit /).
file (string, empfohlen) – Quell-Dateiname, erscheint in der Updates-Tabelle.
post_type (string, default page).
status (string, default publish): publish|draft|private…
version (string, empfohlen) – HBW-Version; steigt nur um +0.01, +0.1 oder +1.
date (string, empfohlen) – YYYY-MM-DD oder YYYY-MM-DD HH:MM:SS.
parent (string, optional) – Permalink der Elternseite; leer oder "/" ⇒ kein Parent.
author (string, optional) – WP-Login (z. B. Clara).

Deprecated: path (Altname für permalink) wird erkannt, ist aber obsolet und sollte nicht mehr verwendet werden.

4 · Matching, Erzeugen & Aktualisieren

Seitenauflösung: Bestehende Seite wird via permalink gesucht. Treffer ⇒ Update, sonst ⇒ Create.
Slug bei Create: Letztes Segment des permalink (z. B. was-ist-bewusstsein).
Parent: Wird gesetzt, wenn parent auf eine existierende Seite zeigt; sonst bleibt Parent leer (keine Hilfsseiten werden erzeugt).
Autor: Wird gesetzt, wenn author existiert; andernfalls Standardautor.

5 · Skip-Logik & Versionierung

Identisch-Skip: Bei Update: Wenn version unverändert und MD5(Content) unverändert ⇒ skip-identical.
Mindest-Inkrement: Versionen steigen nur in Schritten +0.01, +0.1 oder +1 (nie senken).
Metas: Importer pflegt hbw_version und hbw_hash pro Seite.

6 · Updates-Seite

Nach jedem Lauf wird oben in /intern/updates/ ein neuer Block eingefügt (keine Vermischung mit alten Blöcken). Die Tabelle enthält klickbare Permalinks.

<h3>Import-Lauf am 2025-11-01 22:32:00</h3>
<p class="muted">importer=v0.4.3; created=1, updated=3, skip-identical=2, skip-older=0, errors=0, flush=no</p>
<table class="hbw-updates">…</table>
<hr />

7 · Fehlerbehandlung & Logging

Kein HBW-Header oder fehlender permalink ⇒ Datei nach error/; Logeintrag mit Fehlercode.
WP-Fehler (z. B. ungültiger Parent) ⇒ Datei nach error/ mit Fehlermeldung.
Erfolg ⇒ Datei nach processed/.
Logs in …/logs/ enthalten Zeitstempel und Aktionen je Datei.

8 · Encoding & Format

UTF-8 ohne BOM für alle Quell-HTML/MD.
Genau ein HBW-Headerblock direkt am Anfang der Datei.

9 · Beispiele

9.1 · Gültiger Minimal-Header

<!-- HBW
{ "permalink": "/praxis/aufmerksamkeit-weite/", "version": "1.2" }
-->

9.2 · Voller Header (empfohlen)

<!-- HBW
{
  "title": "Was ist Bewusstsein?",
  "permalink": "/grundlagen/was-ist-bewusstsein/",
  "file": "was-ist-bewusstsein_v3.8.html",
  "post_type": "page",
  "status": "publish",
  "version": "3.8",
  "date": "2025-11-01 10:42:00",
  "parent": "/grundlagen/",
  "author": "Clara"
}
-->

9.3 · Fehlerhaft (wird nach `error/` verschoben)

<!-- HBW
{ "title": "Ohne Permalink" }
-->

10 · Changelog (Importer)

v0.4.3 – Toleriert path als Alias (obsolet), blockweises Updates-Append, verbesserte Logs.
v0.4.2 – Stabilität, Skip-Logik (Version+MD5), Permalink-Fix in Tabelle.

11 · Test-Checkliste

Datei mit gültigem HBW-Header in updates_ki_html/ ablegen, Flag run.flag daneben.
Nach Lauf: Datei in processed/ oder error/, Log prüfen.
/intern/updates/ zeigt neuen Block oben; Permalinks anklickbar.
Parent korrekt (falls gesetzt), Version hochgezählt, Autor gesetzt (falls vorhanden).

Rückfragen & Erweiterungen: siehe HBW-Architektur und Anweisungsdatei.