From d4cbf9b6cea5857353612f14dbb21bef0df3825a Mon Sep 17 00:00:00 2001 From: root Date: Tue, 10 Feb 2026 19:47:49 +0000 Subject: [PATCH] Initial marketplace: n8n-skills + doc-converter plugins Marketplace with 2 plugins: - n8n-skills v1.0.0 (7 skills for n8n workflow automation) - doc-converter v1.0.0 (DOCX/PDF to HTML via Gemini Vision) --- .claude-plugin/marketplace.json | 18 + README.md | 21 + doc-converter/.claude-plugin/plugin.json | 8 + doc-converter/README.md | 38 + .../skills/doc-converter-expert/SKILL.md | 808 ++++++++++++ n8n-skills/.claude-plugin/plugin.json | 8 + n8n-skills/README.md | 39 + .../code-javascript/BUILTIN_FUNCTIONS.md | 764 ++++++++++++ .../skills/code-javascript/COMMON_PATTERNS.md | 1110 +++++++++++++++++ .../skills/code-javascript/DATA_ACCESS.md | 782 ++++++++++++ .../skills/code-javascript/ERROR_PATTERNS.md | 763 +++++++++++ n8n-skills/skills/code-javascript/README.md | 350 ++++++ n8n-skills/skills/code-javascript/SKILL.md | 699 +++++++++++ .../skills/code-python/COMMON_PATTERNS.md | 794 ++++++++++++ n8n-skills/skills/code-python/DATA_ACCESS.md | 702 +++++++++++ .../skills/code-python/ERROR_PATTERNS.md | 601 +++++++++ n8n-skills/skills/code-python/README.md | 386 ++++++ n8n-skills/skills/code-python/SKILL.md | 748 +++++++++++ .../skills/code-python/STANDARD_LIBRARY.md | 974 +++++++++++++++ .../expression-syntax/COMMON_MISTAKES.md | 393 ++++++ .../skills/expression-syntax/EXAMPLES.md | 483 +++++++ n8n-skills/skills/expression-syntax/README.md | 93 ++ n8n-skills/skills/expression-syntax/SKILL.md | 516 ++++++++ n8n-skills/skills/mcp-tools-expert/README.md | 99 ++ .../skills/mcp-tools-expert/SEARCH_GUIDE.md | 374 ++++++ n8n-skills/skills/mcp-tools-expert/SKILL.md | 642 ++++++++++ .../mcp-tools-expert/VALIDATION_GUIDE.md | 442 +++++++ .../skills/mcp-tools-expert/WORKFLOW_GUIDE.md | 618 +++++++++ .../skills/node-configuration/DEPENDENCIES.md | 789 ++++++++++++ .../node-configuration/OPERATION_PATTERNS.md | 913 ++++++++++++++ .../skills/node-configuration/README.md | 364 ++++++ n8n-skills/skills/node-configuration/SKILL.md | 785 ++++++++++++ .../skills/validation-expert/ERROR_CATALOG.md | 943 ++++++++++++++ .../validation-expert/FALSE_POSITIVES.md | 720 +++++++++++ n8n-skills/skills/validation-expert/README.md | 290 +++++ n8n-skills/skills/validation-expert/SKILL.md | 689 ++++++++++ n8n-skills/skills/workflow-patterns/README.md | 251 ++++ n8n-skills/skills/workflow-patterns/SKILL.md | 411 ++++++ .../workflow-patterns/ai_agent_workflow.md | 784 ++++++++++++ .../workflow-patterns/database_operations.md | 785 ++++++++++++ .../workflow-patterns/http_api_integration.md | 734 +++++++++++ .../workflow-patterns/scheduled_tasks.md | 773 ++++++++++++ .../workflow-patterns/webhook_processing.md | 545 ++++++++ 43 files changed, 23049 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 README.md create mode 100644 doc-converter/.claude-plugin/plugin.json create mode 100644 doc-converter/README.md create mode 100644 doc-converter/skills/doc-converter-expert/SKILL.md create mode 100644 n8n-skills/.claude-plugin/plugin.json create mode 100644 n8n-skills/README.md create mode 100644 n8n-skills/skills/code-javascript/BUILTIN_FUNCTIONS.md create mode 100644 n8n-skills/skills/code-javascript/COMMON_PATTERNS.md create mode 100644 n8n-skills/skills/code-javascript/DATA_ACCESS.md create mode 100644 n8n-skills/skills/code-javascript/ERROR_PATTERNS.md create mode 100644 n8n-skills/skills/code-javascript/README.md create mode 100644 n8n-skills/skills/code-javascript/SKILL.md create mode 100644 n8n-skills/skills/code-python/COMMON_PATTERNS.md create mode 100644 n8n-skills/skills/code-python/DATA_ACCESS.md create mode 100644 n8n-skills/skills/code-python/ERROR_PATTERNS.md create mode 100644 n8n-skills/skills/code-python/README.md create mode 100644 n8n-skills/skills/code-python/SKILL.md create mode 100644 n8n-skills/skills/code-python/STANDARD_LIBRARY.md create mode 100644 n8n-skills/skills/expression-syntax/COMMON_MISTAKES.md create mode 100644 n8n-skills/skills/expression-syntax/EXAMPLES.md create mode 100644 n8n-skills/skills/expression-syntax/README.md create mode 100644 n8n-skills/skills/expression-syntax/SKILL.md create mode 100644 n8n-skills/skills/mcp-tools-expert/README.md create mode 100644 n8n-skills/skills/mcp-tools-expert/SEARCH_GUIDE.md create mode 100644 n8n-skills/skills/mcp-tools-expert/SKILL.md create mode 100644 n8n-skills/skills/mcp-tools-expert/VALIDATION_GUIDE.md create mode 100644 n8n-skills/skills/mcp-tools-expert/WORKFLOW_GUIDE.md create mode 100644 n8n-skills/skills/node-configuration/DEPENDENCIES.md create mode 100644 n8n-skills/skills/node-configuration/OPERATION_PATTERNS.md create mode 100644 n8n-skills/skills/node-configuration/README.md create mode 100644 n8n-skills/skills/node-configuration/SKILL.md create mode 100644 n8n-skills/skills/validation-expert/ERROR_CATALOG.md create mode 100644 n8n-skills/skills/validation-expert/FALSE_POSITIVES.md create mode 100644 n8n-skills/skills/validation-expert/README.md create mode 100644 n8n-skills/skills/validation-expert/SKILL.md create mode 100644 n8n-skills/skills/workflow-patterns/README.md create mode 100644 n8n-skills/skills/workflow-patterns/SKILL.md create mode 100644 n8n-skills/skills/workflow-patterns/ai_agent_workflow.md create mode 100644 n8n-skills/skills/workflow-patterns/database_operations.md create mode 100644 n8n-skills/skills/workflow-patterns/http_api_integration.md create mode 100644 n8n-skills/skills/workflow-patterns/scheduled_tasks.md create mode 100644 n8n-skills/skills/workflow-patterns/webhook_processing.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..bc9739d --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,18 @@ +{ + "name": "ki-brain-plugins", + "description": "Claude Code plugins by ki-brain: n8n workflow automation and document conversion", + "plugins": [ + { + "name": "n8n-skills", + "source": "n8n-skills", + "description": "Complete n8n workflow automation skills (7 skills: Code JS/Python, Expressions, Patterns, Validation, Config, MCP Tools)", + "version": "1.0.0" + }, + { + "name": "doc-converter", + "source": "doc-converter", + "description": "Expert guidance for DOCX/PDF to HTML conversion via Gemini Vision API", + "version": "1.0.0" + } + ] +} diff --git a/README.md b/README.md new file mode 100644 index 0000000..7063101 --- /dev/null +++ b/README.md @@ -0,0 +1,21 @@ +# ki-brain Claude Code Plugins + +Plugin marketplace for Claude Code by ki-brain. + +## Available Plugins + +| Plugin | Description | Skills | +|--------|-------------|--------| +| **n8n-skills** | n8n workflow automation | 7 skills (Code JS/Python, Expressions, Patterns, Validation, Config, MCP) | +| **doc-converter** | DOCX/PDF to HTML conversion | 1 skill (Gemini Vision document analysis) | + +## Installation + +```bash +# Add marketplace +/plugin marketplace add claudecode/claude-plugins@gitea.veser.org + +# Install plugins +/plugin install n8n-skills@ki-brain-plugins +/plugin install doc-converter@ki-brain-plugins +``` diff --git a/doc-converter/.claude-plugin/plugin.json b/doc-converter/.claude-plugin/plugin.json new file mode 100644 index 0000000..50e4167 --- /dev/null +++ b/doc-converter/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "doc-converter", + "description": "Expert guidance for DOCX/PDF to HTML conversion using the doc-converter service with Gemini Vision API. Covers layout templates (Vorlagen), document type detection, and troubleshooting.", + "version": "1.0.0", + "author": { + "name": "ki-brain" + } +} diff --git a/doc-converter/README.md b/doc-converter/README.md new file mode 100644 index 0000000..4712f75 --- /dev/null +++ b/doc-converter/README.md @@ -0,0 +1,38 @@ +# Doc Converter Plugin for Claude Code + +Expert guidance for DOCX/PDF to HTML conversion using the doc-converter service with Gemini Vision API. + +## Skills Included + +| Skill | Invocation | Description | +|-------|-----------|-------------| +| **Doc Converter Expert** | `/doc-converter:doc-converter-expert` | Document conversion, layout templates (Vorlagen), troubleshooting | + +## Features + +- **Document type detection**: Standard (blue), Verfahrensanweisung/VA (pink), Other (1:1) +- **Template rules**: Color schemes, section structures, table layouts +- **Image processing**: Waifu2x upscaling, vector extraction, logo filtering +- **Post-processing**: Font normalization, hierarchical indentation, table merging +- **Jodit editor compatibility**: Inline styles, no CSS classes + +## Requirements + +- [Claude Code](https://claude.ai/code) CLI +- doc-converter service (Flask + Gemini Vision) + +## Installation + +```bash +# Via marketplace (if published) +/plugin install doc-converter + +# Or from local path +/plugin install /path/to/doc-converter +``` + +## Usage + +``` +/doc-converter:doc-converter-expert +``` diff --git a/doc-converter/skills/doc-converter-expert/SKILL.md b/doc-converter/skills/doc-converter-expert/SKILL.md new file mode 100644 index 0000000..9608e91 --- /dev/null +++ b/doc-converter/skills/doc-converter-expert/SKILL.md @@ -0,0 +1,808 @@ +--- +name: doc-converter-expert +description: Expert guidance for DOCX/PDF to HTML conversion using the doc-converter service. Use when converting documents, diagnosing conversion issues, understanding layout templates (Vorlagen), or working with the Gemini Vision API for document analysis. +--- + +# Document Converter Expert + +Expert guidance for converting DOCX/PDF documents to Jodit-compatible HTML using the doc-converter service. + +--- + +## Overview + +The doc-converter service uses Gemini Vision to analyze document images and generate HTML that matches the visual layout. Documents are classified into three types: + +| Type | Detection | Approach | +|------|-----------|----------| +| **Standard** | Blue headers (#B8CCE4), table-based sections | Follow Standard template rules - NUR Vorlagen-Farben! | +| **Verfahrensanweisung (VA)** | Rosa headers (#E6B8B7/#F2DCDB), h2-based with procedure table | Follow VA template rules - NUR Vorlagen-Farben! | +| **Other** | No template match | **1:1 EXAKT wie im Dokument** - alle Farben/Strukturen übernehmen | + +--- + +## KRITISCHE REGELN für VA und Standard + +### Erlaubte Farben - NUR DIESE! + +**Standard (Blau):** +| Element | Farbe | Hex | +|---------|-------|-----| +| Header-Zeile | Blau | #B8CCE4 | +| Nummerierungsspalte | Blau (gleich wie Header!) | #B8CCE4 | +| Datenzellen | Weiß/transparent | - | + +**Verfahrensanweisung (Rosa):** +| Element | Farbe | Hex | +|---------|-------|-----| +| Header-Zeile | Rosa | #E6B8B7 | +| Nummerierungsspalte | Rosa (IDENTISCH wie Header!) | #E6B8B7 | +| Datenzellen | Weiß/transparent | - | + +**KRITISCH: Header und Nummerierungsspalte MÜSSEN denselben Hex-Code haben!** + +**VERBOTEN bei VA/Standard Verfahrenstabellen:** +- Unterschiedliche Farben zwischen Header und Nummerierungsspalte +- Hintergrundfarbe auf normalen Datenzellen (außer Nummerierungsspalte) + +**ERLAUBT bei anderen Tabellen im Dokument (z.B. Legende):** +- Alle Farben 1:1 wie im Original: gelb, grün, rot, grau etc. + +### Dokument-Header und Titel Behandlung + +**Der Dokumenttitel MUSS im Content erscheinen!** +- Die **Hauptüberschrift** (Dokumenttitel) → wird als `

` GANZ OBEN im `content_html` eingefügt +- Format: `

Dokumenttitel

` +- Danach folgt der restliche Content ab Sektion 1 + +**KEINE Logos oder Bilder aus dem Header-Bereich!** +- Logos (Firmenlogos, Wappen) die im Kopfbereich erscheinen: **IGNORIEREN!** +- Diese werden automatisch vom System herausgefiltert (Hash-basierte Duplikat-Erkennung) +- Referenziere NUR inhaltliche Bilder (Diagramme, Fotos) — KEINE Header-Logos! + +``` +RICHTIG: "Verfahrensanweisung Dienstplan" → als

im content_html +RICHTIG: Diagramm aus Dokument → +FALSCH: Logo-Bild extrahieren und referenzieren +FALSCH: Logo mehrfach im HTML anzeigen +``` + +### TOC (Inhaltsverzeichnis) — NIEMALS im Content! + +**ABSOLUTE REGEL: Das TOC gehört NICHT in content_html!** +- Das Inhaltsverzeichnis wird SEPARAT in `toc_html` ausgegeben +- Wenn das Originaldokument ein TOC hat: ÜBERSPRINGEN im Content! +- Der Content beginnt DIREKT mit dem Dokumenttitel (`

`) und dann Sektion 1 +- **VERBOTEN:** Klickbare Links wie "1. Zweck", "2. Geltungsbereich" im Content! + +### TOC-Sektion-1-Fix +Wenn "1. Inhaltsverzeichnis" die erste Sektion im TOC ist: +- Die Funktion `fix_toc_section_one()` korrigiert automatisch +- Fall 1: "1. Inhaltsverzeichnis" → wird ersetzt mit "1. " +- Fall 2: TOC beginnt bei "2." → "1. " wird hinzugefügt +- Die h1-Überschrift bekommt `id="sec-1"` und das "1." Präfix + +**TOC Format mit HÄNGENDEM EINZUG (h2, h3, h4):** + +⚠️ **KRITISCH: Hängender Einzug bei Zeilenumbruch!** +Bei langen Titeln die umbrechen, MUSS der Text unter dem ERSTEN WORT weitergehen, NICHT am linken Rand! + +``` +FALSCH: RICHTIG: +4.1.1 Externe Signatur Servicehaus 4.1.1 Externe Signatur Servicehaus +Sonnenhalde ← am Rand! Sonnenhalde ← unter "Externe"! +``` + +**Technik: `padding-left` + negativer `text-indent`:** +```html + +
1. Zweck der Verfahrensanweisung
+ + +
3.1. Grundlagen
+ + +
4.1.1. Externe Signatur Servicehaus Sonnenhalde
+``` + +**WICHTIG:** h3 UND h4 Überschriften MÜSSEN im TOC erscheinen! + +### Hierarchische Einrückung — GENERELLE REGEL! + +**Alles was einem übergeordneten Element untersteht, wird eingerückt!** +- Einrückung erfolgt über `margin-left` in 20px-Schritten +- Ebene 1 (h2): margin-left: 0 +- Ebene 2 (h3, Listen unter h2): margin-left: 20px +- Ebene 3 (Listen unter h3, verschachtelte Listen): margin-left: 40px +- usw. + +**Tabellen und Bilder — MIT Einrückung und Abstand:** +- **Tabellen**: margin-left entsprechend der Hierarchie-Ebene + Abstand oben/unten! + - Tabelle unter h2: `margin: 15px 0 15px 20px;` + - Tabelle unter h3: `margin: 15px 0 15px 40px;` + - **Ausnahme:** Verfahrenstabelle (Sektion 4) mit `width: 100%` hat margin-left: 0 +- **Bilder**: Eingerückt + Abstand! ALLE Bilder aus dem Original müssen erscheinen! + +### Tabellen — Einrückung statt Zentrierung + +Tabellen werden eingerückt (nicht zentriert): +```html + +``` + +**Ausnahme:** Verfahrenstabellen (Sektion 4) mit 4 Spalten: `width: 100%; margin-left: 0;` + +**h2 für Hauptsektionen (1., 2., 3.):** +```html +

1. Zweck

+``` + +**h3 für Untersektionen (3.1., 3.2.):** +```html +

3.1. Grundlagen

+``` + +**Absätze unter h3:** +```html +

Text

+``` + +### Listen — Einrückung je nach Hierarchie-Ebene — KRITISCH! + +## ⚠️ VERBOTEN: Listen die am linken Rand beginnen wenn sie unter h3 stehen! ⚠️ + +**Listen unter h2 (Ebene 2):** margin-left: 25px +**Listen unter h3 (Ebene 3):** margin-left: 45px — PFLICHT! + +**VISUELLES ZIEL:** Die Bullet-Points MÜSSEN weiter rechts beginnen als der erste Buchstabe der h3-Überschrift! + +**FALSCH (VERBOTEN!):** +``` +3.1. Grundlagen +• Bullet am linken Rand ← FALSCH! Keine Einrückung! +``` + +**RICHTIG:** +``` +3.1. Grundlagen + • Bullet eingerückt ← RICHTIG! Bullet beginnt weiter rechts +``` + +**HTML-CODE für VA — Liste unter h3:** +```html +

3.1. Grundlagen

+
    +
  • Betriebsmedizinliste ist eine vorgegebene...
    • +
+``` +**KRITISCH:** `margin-left: 45px` auf der `
    ` — NICHT 25px, NICHT 0! + +**Verschachtelte Listen (Listen in Listen):** zusätzliche 20px +```html +
      +
    • Hauptpunkt +
        +
      • Unterpunkt (nochmal eingerückt)
        • +
      +
      • +
    +``` + +**Hängender Einzug:** Bei Zeilenumbruch Text bündig mit erstem Wort, NICHT mit Bullet! + +### Farbige Hinweisfelder INNERHALB von Listenpunkten + +**Wenn ein gelbes/farbiges Hinweisfeld zum Text eines Listenpunkts gehört:** +- Das Feld ist TEIL des `
  • `, NICHT ein separates Element! +- Verwende `display: inline-block;` damit es NICHT volle Breite hat +- Die Originalfarbe übernehmen (gelb = #FFFF00 oder #FFF2CC, NICHT rosa!) + +```html +
  • + Text des Listenpunkts der vor dem Hinweis steht +
    + Passwort für jeden Standort: SHS-MalBm +
    +
    • +``` + +**FALSCH:** Hinweisfeld als separates `
    ` mit voller Breite außerhalb der Liste! + +### Footer-Tabelle Styling + +Die Footer-Tabelle hat **4 Spalten**, **NUR die Header-Zeile mit Hintergrundfarbe**, und verwendet **8pt** (kleiner als Content-Text): + +```html +
+ + + + + + + + + + + + +
+

Freigabe

+ 		+

Bearbeiter

+ 		+

Änderungsstand

+ 		+

Datum

+
+

QM

+ 		+

Name

+ 		+

1.0

+ 		+

01.01.2025

+
+``` + +**WICHTIG:** 4 Spalten: Freigabe, Bearbeiter, Änderungsstand, Datum. **KEINE "Seite"-Spalte!** +**Beachte:** Datenzellen haben KEINE Hintergrundfarbe, nur die Header-Zeile! + +### Tabellen durch Bilder unterbrochen — Header wiederholen! + +**Wenn eine Tabelle durch ein Bild unterbrochen wird, MUSS die Header-Zeile nach dem Bild wiederholt werden!** + +```html + + + + + + + + + + + + + + + + + + +
AufgabeVerantwortungMittel
1Schritt 1aMATelefon
1bSchritt 1bBL-
+ + +
Vorsorgekartei
+ + + + + + + + + + + + + + +
AufgabeVerantwortungMittel
2Schritt 2aMAFormular
+``` + +**WICHTIG:** Nach jedem unterbrechenden Bild beginnt eine NEUE Tabelle mit vollständiger Header-Zeile! + +### Nummerierungsspalte = Header-Farbe + +**PFLICHT:** Die Nummerierungsspalte (1, 2, 3...) MUSS EXAKT die gleiche Hintergrundfarbe haben wie die Header-Zeile der Tabelle! + +```html + + + Aufgabe + ... + + + 1 + Beschreibung (KEIN Hintergrund!) + ... + + + + + 3. Durchführung + ... + + + 1 + Beschreibung (KEIN Hintergrund!) + ... + +``` + +--- + +## Layout-Vorgaben für Dokumente MIT TOC (Abweichungen von 1:1) + +Dokumente die ein Inhaltsverzeichnis haben (Standard/VA) bekommen folgende Anpassungen, die von einer 1:1-Darstellung des Originals abweichen: + +### 1. TOC wird NEU generiert (nicht aus dem Original) +- Original-TOC (Punktreihen, Seitenzahlen) wird komplett verworfen +- Phase 2a extrahiert TOC-Einträge als JSON, `generate_toc_from_entries()` erzeugt festes Template +- Format: `
` mit `` +- **Seitenzahlen und Punktreihen werden entfernt** + +### 2. TOC-Seiten und Titelseite werden im Content übersprungen +- Alle Pre-Content-Seiten (Titel, TOC) werden NICHT an Gemini zur Content-Konvertierung gesendet +- Content beginnt bei `first_content_page` (aus Phase 1) + +### 3. "1. Inhaltsverzeichnis" → Dokumenttitel +- `fix_toc_section_one()` ersetzt "1. Inhaltsverzeichnis" mit "1. " +- Oder fügt "1. " hinzu wenn TOC bei "2." beginnt + +### 4. Dokumenttitel wird als h1 nachträglich eingefügt +- h1 mit 16pt (normal) oder h2 mit 12pt (wenn Sektion 1 = Inhaltsverzeichnis) +- Untertitel von Seite 1 als `

` darunter +- **Kein Logo, keine Farben, keine Rahmen** — nur einfacher Text + +### 5. Schriftgrößen auf 11pt normalisiert +- `normalize_font_sizes()` erzwingt bei TOC-Dokumenten 11pt für Fließtext (p, li, span, div) +- Tabellen-Elemente (td, th) und Überschriften (h1-h6) bleiben unverändert +- h1=16pt, h2=12pt, h3/h4=11pt, p/li=11pt, footer=8pt + +### 6. Footer als festes 4-Spalten-Template +- **Immer 4 Spalten:** Freigabe | Bearbeiter | Änderungsstand | Datum +- Seitenzahlen-Spalte wird **immer entfernt** (auch wenn Original 5 Spalten hat) +- Font-Size: 8pt, border: none +- Header-Zeile: Hintergrundfarbe je nach Typ (#E6B8B7 für VA, #B8CCE4 für Standard) + +### 7. Dokumenttyp-Farben erzwungen +- **Standard:** Tabellen-Header #B8CCE4 (blau), **VA:** #E6B8B7 (rosa) +- Datenzellen **kein** Hintergrund +- Auch bei leicht abweichenden Original-Farben wird die Vorlagenfarbe erzwungen + +### 8. Hierarchische Einrückung (hängende Einzüge) +``` +h2: margin-left:0, padding-left:10pt, text-indent:-10pt +h3: margin-left:10pt, padding-left:12pt, text-indent:-12pt +h4: margin-left:22pt, padding-left:14pt, text-indent:-14pt +Content nach h2: margin-left:10pt +Content nach h3: margin-left:22pt +Content nach h4: margin-left:36pt +``` + +### 9. Content-Normalisierung (immer aktiv) +- Excessive Margins (>30pt, ≥5%) entfernt +- `text-align: justify` → entfernt +- Bold `

` mit Sektionsnummern → h2/h3/h4 +- Serif-Fonts → Arial, Font-Family auf alle Elemente +- Gebrochene Absätze zusammengeführt +- Em-Dash-Listen → disc bullets +- Seitenübergreifende Tabellen zusammengeführt +- `text-align: left` auf alle Elemente + +--- + +## Andere Dokumente: 1:1 Konvertierung + +Bei Dokumenten die NICHT VA oder Standard sind: + +**ALLES muss 1:1 wie im Original aussehen:** +- Alle Hintergrundfarben exakt übernehmen (auch wenn nicht rosa/blau) +- Alle Rahmenlinien wie im Original +- Tabellenstrukturen exakt nachbilden +- Bilder und Grafiken einbinden +- Keine Vorlagen-Regeln anwenden! + +``` +Dokument hat grüne Header? → Grüne Header im HTML +Dokument hat graue Zellen? → Graue Zellen im HTML +Dokument hat keine Linien? → border: none im HTML +``` + +--- + +## Document Type Detection + +### Standard Document +**Detection criteria:** +- Blue header backgrounds (#B8CCE4 or similar cool blue tones) +- Each section is a separate `` with header row +- Content is in table cells, not free-flowing + +### Verfahrensanweisung (VA) +**Detection criteria:** +- Rosa/salmon header backgrounds (#F2DCDB, #E6B8B7 or similar warm tones) +- Free-flowing `

` headings (not in tables) +- Only one procedure table (Section 4: Verfahrensablauf) + +### Other Documents +**Detection criteria:** +- No blue or rosa template colors +- No numbered section structure (1. 2. 3.) +- Any other document format + +--- + +## Template Rules: Standard (Blue) + +### Section Structure +Each section is a **separate `

`**: + +```html +
+ + + + + + +
+

1. Ziel

+
+

Dieser Standard regelt...

+
+``` + +### Steps Table (Durchführung) — MIT SPALTENBREITEN! +4-column table with colspan on header. + +**Standard-Spaltenbreiten:** Nr=5%, Beschreibung=45%, Verantwortung=25%, Mittel=25% (Header colspan=50%) + +```html + + + + + + + + + + + + +
+

3. Durchführung/Ablauf

+ 		+

Verantwortung

+ 		+

Mittel

+
+

1

+ 		+

Schritt 1

+ 		+

MA

+ 		+

Arbeitsmittel, Kommunikation

+
+``` + +--- + +## Template Rules: Verfahrensanweisung (Rosa) + +### Section Structure +Sections use free-flowing `

` headings (KEINE Tabellen!): + +```html +

1. Zweck der Verfahrensanweisung

+

Mit dieser Verfahrensanweisung werden die Zuständigkeiten...

+``` + +### Procedure Table (Verfahrensablauf) — MIT SPALTENBREITEN! +Only the procedure table (Section 4) uses table format. + +**VA-Spaltenbreiten:** Nr=5%, Aufgabe=45%, Verantwortung=25%, Mittel=25% (Header colspan=50%) + +```html +

4. Beschreibung des Verfahrensablaufs

+ + + + + + + + + + + + +
+

Aufgabe

+ 		+

Verantwortung

+ 		+

Mittel

+
+

1

+ 		+

Task description

+ 		+

MA

+ 		+

Telefon

+
+``` +**KRITISCH:** Nr-Spalte hat GLEICHE Farbe wie Header (#E6B8B7), NICHT #F2DCDB! + +### Abbreviations Table (OHNE Rahmenlinien, ZENTRIERT!) +VA/Standard Abkürzungstabellen haben KEINE sichtbaren Rahmenlinien und sind ZENTRIERT: + +**KRITISCH: KEINE `width: 100%`! Zentrieren mit `margin: 10px auto;`!** + +```html +

3.3. Abkürzungen:

+ + + + + + + +
+

MA

+ 		+

Mitarbeiter

+ 		+

DP

+ 		+

Dienstplan

+
+``` + +--- + +## Tabellen MIT vs. OHNE Rahmenlinien + +**Tabelle MIT sichtbaren Rahmenlinien:** +```html + +
+``` + +**Tabelle OHNE sichtbare Rahmenlinien:** +```html + +
+``` + +--- + +## Font-Größen und Normalisierung + +### Einheiten: Immer pt (nicht px!) + +Alle Größenangaben in **pt** (Points), nicht px: + +| Element | Größe | +|---------|-------| +| h1 (Dokumenttitel) | 14pt bold | +| h2 (Hauptsektionen) | 12pt bold | +| h3 (Untersektionen) | 11pt bold | +| **Fließtext (p, li)** | **11pt** | +| Tabellenzellen (td) | 11pt | +| **Footer-Tabelle** | **8pt** | + +### Post-Processing: `normalize_font_sizes()` + +Automatische Normalisierung nach der Gemini-Konvertierung: + +- **Dokumente mit TOC** → Fließtext wird auf `11pt` normalisiert (Vorlagen-Standard) +- **Dokumente ohne TOC** → Erste verwendete Font-Größe wird als Baseline genommen + +**Unberührt bleiben:** +- Tabellen (``, ``) — behalten ihre eigene Größe +- Headings (`

`-`

`) — behalten ihre eigene Größe +- Bold-Tags (``) — oft Überschriften, behalten ihre Größe + +--- + +## Color Reference + +### VA/Standard - NUR diese Farben! + +| Dokument-Typ | Header | Nummerierungsspalte | Datenzellen | +|--------------|--------|---------------------|-------------| +| Standard | #B8CCE4 (blau) | #B8CCE4 (blau) | transparent | +| VA | #E6B8B7 (rosa dunkel) | #F2DCDB (rosa hell) | transparent | + +### Farbunterscheidung + +| Warm (Rosa/Lachs) | Cool (Blue) | +|-------------------|-------------| +| #F2DCDB | #B8CCE4 | +| #E6B8B7 | #D9E2F3 | +| #D99594 | - | + +--- + +## Bild-Verarbeitung + +### Waifu2x Upscaling +Alle extrahierten Bilder werden automatisch mit waifu2x-converter-cpp hochskaliert: +- **Skalierung:** 2x (doppelte Auflösung) +- **Noise Level:** 2 (mittlere Rauschunterdrückung) +- **Anzeige:** Bilder werden im HTML mit Originalgrößen-Attributen angezeigt (`width`/`height`) + +```python +# Upscaling läuft automatisch nach Bildextraktion +image_orig_dimensions = upscale_images_in_dir(full_output, scale=2, noise=2) +``` + +### Bild-Benennungsschema +Format: `content_X_Y.png` wobei: +- **X** = Seitennummer (1-basiert) +- **Y** = Fortlaufende Position im Dokument + +**Beispiele:** +- `content_1_1.png` = Seite 1, Position 1 (oft Logo - Vorsicht!) +- `content_2_2.png` = Seite 2, Position 2 +- `content_6_5.png` = Seite 6, Position 5 + +**Duplikate (Bilder auf mehreren Seiten):** +- Wenn ein Bild auf mehreren Seiten vorkommt → `content_Y.png` (ohne Seite) + +### Ganzseitige Bilder (Gescannte Dokumente) +Wenn eine Seite >90% von einem Bild bedeckt ist: +- **Erkennung:** `coverage_w > 0.90 AND coverage_h > 0.90` +- **Verhalten:** Seite wird NICHT an Gemini gesendet +- **Ausgabe:** Direktes `` Tag im HTML + +```html + +
+ Seite 1 +
+``` + +**Vorteile:** +- Keine API-Kosten für gescannte Seiten +- Schnellere Verarbeitung +- Originalqualität erhalten +- Kein OCR-Fehlerrisiko + +### Logo-Filterung +Automatische Erkennung und Ausfilterung von Logos: + +| Kriterium | Beschreibung | +|-----------|--------------| +| Header-Bereich | Top 12% der Seite (kleine Bilder) | +| Logo-artig | Top 20%, Höhe <60px, Ratio >2.0 | +| Logo-Dimensionen | Höhe <50px, Ratio >2.5 | +| Zu flach | Ratio >5.0 | +| Hash-Duplikate | Gleiches Bild auf mehreren Seiten | + +**Ausnahme:** Große Bilder (>200x150) werden NIE als Logo gefiltert! + +### Vektorgrafik-Extraktion +PyMuPDF `get_images()` extrahiert nur Rasterbilder. Für Vektorgrafiken: + +**Erkennung:** +- Seite hat >10 drawings +- Keine Rasterbilder auf der Seite extrahiert + +**Verarbeitung:** +1. Gruppiere drawings nach Y-Position (±50px = gleiche Gruppe) +2. Rendere jede Gruppe als separates Bild mit `zoom=1.0` +3. Validiere mit Gemini ob es echte Grafik ist (nicht nur Text/Linien) + +```python +drawings = page.get_drawings() +if len(drawings) >= 10 and page_num not in pages_with_images: + # Rendere Vektorgrafik-Gruppen +``` + +--- + +## API Endpoints + +### POST /convert +Main conversion endpoint. + +```json +{ + "input": "tmp/upload_xxx/document.docx", + "output_dir": "tmp/upload_xxx", + "template_mode": "auto" +} +``` + +**template_mode Options:** + +| Mode | Beschreibung | +|------|-------------| +| `"auto"` | **(Default)** Automatische Erkennung. Wendet Standard/VA Vorlagen-Regeln an wenn erkannt. | +| `"standard"` | Erzwingt Standard-Vorlage (blaue Header #B8CCE4). | +| `"va"` | Erzwingt Verfahrensanweisung-Vorlage (rosa Header #E6B8B7). | +| `"exact"` | **1:1 Konvertierung** — KEINE Vorlagen-Anpassung! Alle Farben/Strukturen exakt wie im Original. | + +**Wann welcher Modus?** +- `auto`: Standard für normale Dokumente die einer Vorlage folgen +- `standard`/`va`: Erzwingen wenn das Dokument einer Vorlage folgen SOLL aber nicht erkannt wird +- `exact`: Für **Import/Re-Check** wenn das Dokument EXAKT wie das Original aussehen soll + +**Response:** +```json +{ + "success": true, + "template_mode": "exact", + "files": { "content": "content.html", "toc": "toc.html", ... } +} +``` + +### POST /analyze-html +Quality analysis of generated HTML. + +### GET /health +Service health check. + +--- + +## Troubleshooting + +### Issue: Falsche Farben verwendet +**Ursache:** VA/Standard Template nicht erkannt oder falsche Farben generiert. +**Lösung:** Prüfen ob Dokument rosa (VA) oder blau (Standard) Header hat. Nur Vorlagen-Farben verwenden! + +### Issue: Alle Datenzellen haben Hintergrundfarbe +**Ursache:** Farbregeln nicht befolgt. +**Lösung:** NUR Header-Zeile und Nummerierungsspalte bekommen Hintergrundfarbe! + +### Issue: Logo/Bilder aus Header extrahiert +**Ursache:** Header-Behandlung falsch. +**Lösung:** Aus Header NUR Dokumenttitel extrahieren, KEINE Bilder! + +### Issue: Abkürzungstabelle hat Rahmenlinien +**Ursache:** Tabellentyp nicht erkannt. +**Lösung:** Abkürzungstabellen: `border="0"` und `border: none;` + +### Issue: Footer-Datenzellen haben Hintergrundfarbe +**Ursache:** Footer-Styling falsch. +**Lösung:** Footer-Tabelle: NUR Header-Zeile mit Hintergrundfarbe! + +### Issue: Bilder werden nicht angezeigt (broken image icon) +**Ursache:** HTML referenziert `content_N.png` mit relativem Pfad. +**Lösung:** Der doc-converter bettet Bilder automatisch als base64 Data-URI ein: +```html +... +``` +Wenn Bilder trotzdem fehlen: Prüfen ob `extract_pdf_images()` die Bilder korrekt extrahiert. + +### Issue: h3-Überschriften fehlen im TOC +**Ursache:** TOC enthält nur h2-Level. +**Lösung:** Alle h3 (3.1, 3.2, 3.3 etc.) müssen im TOC erscheinen mit `margin-left: 20px;` + +### Issue: Gescannte Seiten werden konvertiert +**Ursache:** Fullpage-Image-Erkennung nicht aktiv. +**Lösung:** Prüfen ob `fullpage_image_pages` korrekt zurückgegeben wird. Bilder >90% coverage sollten als ganzseitig erkannt werden. + +### Issue: Bilder haben unterschiedliche Qualität +**Ursache:** Verschiedene Extraktionsmethoden. +**Lösung:** Alle Bilder werden jetzt einheitlich mit `zoom=1.0` gerendert und dann mit waifu2x 2x hochskaliert. + +### Issue: Kleine Icons/Elemente auf gescannten Seiten +**Ursache:** Zusätzliche kleine Bilder auf einer fullpage-Seite werden auch angezeigt. +**Lösung:** Das ist erwartetes Verhalten. Das große ganzseitige Bild und eventuelle kleine Elemente werden beide angezeigt. + +--- + +## Jodit Editor Compatibility + +**REQUIRED for Jodit:** +- All styles as inline `style="..."` attributes +- No `