Vorlagen-Authoring (Reference-Copy-Muster)

Überblick

Das Reference-Copy-Muster ist der empfohlene Weg, pixel-perfekte Vorlagen zu erstellen, die das Corporate Design des Kunden exakt reproduzieren. Im Gegensatz zum reinen DocBuilder-Skript-Ansatz beginnt das Reference-Copy-Muster mit einer originalen Referenzdatei des Kunden und injiziert Daten über OOXML-Post-Prozessoren.

Wann welches Muster verwenden?

Muster	Wann verwenden	Beispiel
DocBuilder-Skript	Einfache Layouts, keine Corporate-Design-Vorgaben	Generische Basis-Vorlagen
Reference-Copy	Pixel-perfekte Reproduktion bestehender Dokumente	Kunden-Vorlagen mit Logo, Kopfzeile, Footer
docxtemplater	DOCX mit einfachen Platzhaltern	`{{name}}` in Word-Dokumenten

Reference-Copy-Workflow

Referenzdatei vom Kunden einholen

Fordern Sie eine original .docx/.xlsx/.pptx-Datei vom Kunden an. Diese Datei ist die visuelle Referenz - jedes generierte Dokument muss exakt so aussehen.
Tokenisierung (Platzhalter einfügen)

Ersetzen Sie ausfüllbare Texte in der Referenzdatei durch Token-Platzhalter wie {{TITLE}}, {{NAME}}, {{DATE}}. Verwenden Sie für DOCX FORMTEXT-Felder oder einfache {{TOKEN}}-Platzhalter.
Terminal-Fenster
```
# Tokenisierungs-Skript ausführen
npx tsx scripts/tokenize-worms-reference-docx.ts <input.docx> <output.docx>
```

registry.json mit Post-Prozessoren konfigurieren

Deklarieren Sie die Post-Prozessoren in der Vorlagen-Registry:

{
  "templates": {
    "my_template": {
      "versions": {
        "v2.0": {
          "refDocxPath": "my_template/v2.0/reference.docx",
          "postProcessors": ["copyDOCXVisualAssets", "injectDOCXText"]
        }
      }
    }
  }
}

Schema.json erstellen

Definieren Sie die Felder, die der Benutzer ausfüllt:

{
  "type": "object",
  "properties": {
    "title": { "type": "string", "description": "Dokumenttitel" },
    "date": { "type": "string", "format": "date" }
  },
  "required": ["title"]
}

Fixture zum Testen erstellen

{
  "title": "Test-Titel",
  "date": "2026-08-03",
  "_postProcessorArgs": {
    "injectDOCXText": {
      "TITLE": "Test-Titel",
      "DATE": "03.08.2026"
    }
  }
}

Post-Prozessor-Referenz

DOCX

Post-Prozessor	Zweck	Parameter
`copyDOCXVisualAssets`	Kopiert Theme, Header, Footer, Logos, Schriftarten aus der Referenz	`refDocxPath`
`injectDOCXText`	Injiziert Text in `{{TOKEN}}`-Platzhalter	Token-Map im Fixture
`injectDOCXCheckboxes`	Setzt SDT-Checkbox-Status aus Fixture-Booleans	Token-Map mit `true`/`false`

XLSX

Post-Prozessor	Zweck	Parameter
`copyXLSXVisualAssets`	Kopiert Formatierung, Blätter, Spaltenbreiten aus der Referenz	`refXlsxPath`
`injectXLSXText`	Injiziert Text in sharedStrings und Inline-Cells	Token-Map im Fixture

PPTX

Post-Prozessor	Zweck	Parameter
`copyPPTXVisualAssets`	Kopiert Theme, Master-Layouts, Medien aus der Referenz	`refPptxPath`
`injectPPTXSlideText`	Injiziert Text in Folien-Platzhalter	Slot-Map pro Folie
`removePPTXSlides`	Entfernt Folien basierend auf Daten (variable Folienanzahl)	Liste zu entfernender Folien-Indizes

Token-Konventionen

Token-Format	Verwendung
`{{TOKEN_NAME}}`	DOCX/XLSX Text-Platzhalter
`TITLE`, `SUBTITLE`, `SLIDE_TITLE`	PPTX Folien-Titel
`CONTENT`, `BULLET_1..3`	PPTX Folien-Inhalt
`CARD_TITLE_1..4`, `CONTENT_1..4`	PPTX Karten-Layouts

Visualisierung validieren

Vergleichen Sie generierte Dokumente mit der Originalreferenz:

# Visuelle Überprüfung generieren
npx tsx scripts/generate-worms-visual-review.ts

# Vergleichen Sie die Ausgabe mit raw/worms/templates/

Die Tests FR-F1 (33 Struktur-Paritäts-Tests) und FR-F2 (3 E2E-Tests mit 0 Token-Resten) validieren strukturelle Parität automatisch.