claude-plugins/doc-converter/skills/doc-converter-expert/SKILL.md

---
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 `<h1>` GANZ OBEN im `content_html` eingefügt
- Format: `<h1 style="font-size: 14pt; font-weight: bold; margin: 0 0 10px 0; font-family: Arial, sans-serif; text-align: center;">Dokumenttitel</h1>`
- 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 <h1> im content_html
RICHTIG:  Diagramm aus Dokument → <img src="content_1.png">
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 (`<h1>`) und dann Sektion 1
- **VERBOTEN:** Klickbare Links wie "1. Zweck", "2. Geltungsbereich" im Content!

### Pipeline-Architektur (3-Phasen-Hybrid)

```
PDF → pdftoppm → Seitenbilder
  Phase 1: recognize_document_structure() (Gemini, 3 Content-Seiten)
    → header_bottom_pct, footer_top_pct (Crop-Koordinaten)
  crop_page_images() → gecroppte Seitenbilder (Header/Footer entfernt)
  Phase 2a: TOC + Footer generieren
  Phase 2b: Content pro Seite (gecroppte Bilder, KEINE Header/Footer-Referenz)
  Post-Processing: normalize_content_structure() → normalize_font_sizes()
```

### 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. <Dokumenttitel>"
- Fall 2: TOC beginnt bei "2." → "1. <Dokumenttitel>" 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
<!-- Level 1: h2 (1., 2., 3.) -->
<div class="toc-entry toc-level-1" style="line-height: 1.5; padding-left: 20px; text-indent: -20px;"><a href="#sec-1">1. Zweck der Verfahrensanweisung</a></div>

<!-- Level 2: h3 (3.1., 4.2.) - zusätzlich margin-left: 15px -->
<div class="toc-entry toc-level-2" style="line-height: 1.5; margin-left: 15px; padding-left: 32px; text-indent: -32px;"><a href="#sec-3-1">3.1. Grundlagen</a></div>

<!-- Level 3: h4 (4.1.1., 4.3.2.) - zusätzlich margin-left: 30px -->
<div class="toc-entry toc-level-3" style="line-height: 1.5; margin-left: 30px; padding-left: 44px; text-indent: -44px;"><a href="#sec-4-1-1">4.1.1. Externe Signatur Servicehaus Sonnenhalde</a></div>
```

**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
<table border="1" style="border-collapse: collapse; margin: 15px 0 15px 20px; font-family: Arial, sans-serif; font-size: 11pt;">
```

**Ausnahme:** Verfahrenstabellen (Sektion 4) mit 4 Spalten: `width: 100%; margin-left: 0;`

**h2 für Hauptsektionen (1., 2., 3.):**
```html
<h2 id="sec-1" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">1. Zweck</h2>
```

**h3 für Untersektionen (3.1., 3.2.):**
```html
<h3 id="sec-3.1" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.1. Grundlagen</h3>
```

**Absätze unter h3:**
```html
<p style="margin: 0 0 5px 20px; line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Text</p>
```

### 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
<h3 id="sec-3.1" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.1. Grundlagen</h3>
<ul style="list-style-type: disc; margin: 5px 0 5px 45px; padding-left: 0;">
  <li style="line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Betriebsmedizinliste ist eine vorgegebene...</li>
</ul>
```
**KRITISCH:** `margin-left: 45px` auf der `<ul>` — NICHT 25px, NICHT 0!

**Verschachtelte Listen (Listen in Listen):** zusätzliche 20px
```html
<ul style="...margin-left: 25px...">
  <li>Hauptpunkt
    <ul style="...margin-left: 20px...">
      <li>Unterpunkt (nochmal eingerückt)</li>
    </ul>
  </li>
</ul>
```

**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 `<li>`, NICHT ein separates Element!
- Verwende `display: inline-block;` damit es NICHT volle Breite hat
- Die Originalfarbe übernehmen (gelb = #FFFF00 oder #FFF2CC, NICHT rosa!)

```html
<li style="...">
  Text des Listenpunkts der vor dem Hinweis steht
  <div style="background-color: #FFFF00; padding: 5px; margin-top: 5px; display: inline-block;">
    Passwort für jeden Standort: SHS-MalBm
  </div>
</li>
```

**FALSCH:** Hinweisfeld als separates `<div>` 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
<table style="width: 100%; border-collapse: collapse; border: none; font-family: Arial, sans-serif; font-size: 8pt;">
  <tr>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Freigabe</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Bearbeiter</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Änderungsstand</p>
    </td>
    <td style="width: 25%; background-color: #E6B8B7; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Datum</p>
    </td>
  </tr>
  <tr>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">QM</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">Name</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">1.0</p>
    </td>
    <td style="width: 25%; padding: 4px; vertical-align: top; border: none;">
      <p style="margin: 0; line-height: 1.5; font-size: 8pt;">01.01.2025</p>
    </td>
  </tr>
</table>
```

**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
<table border="1" style="...">
  <tr>
    <th colspan="2" style="...background-color: #E6B8B7;">Aufgabe</th>
    <th style="...background-color: #E6B8B7;">Verantwortung</th>
    <th style="...background-color: #E6B8B7;">Mittel</th>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">1</td>
    <td>Schritt 1a</td>
    <td>MA</td>
    <td>Telefon</td>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">1b</td>
    <td>Schritt 1b</td>
    <td>BL</td>
    <td>-</td>
  </tr>
</table>

<!-- BILD unterbricht die Tabelle - MIT Einrückung und Abstand! -->
<div style="text-align: center; margin: 15px 0 15px 20px;"><img src="content_1.png" alt="Vorsorgekartei" style="max-width: 100%;"></div>

<!-- NEUE Tabelle mit WIEDERHOLTER Header-Zeile! -->
<table border="1" style="...">
  <tr>
    <th colspan="2" style="...background-color: #E6B8B7;">Aufgabe</th>
    <th style="...background-color: #E6B8B7;">Verantwortung</th>
    <th style="...background-color: #E6B8B7;">Mittel</th>
  </tr>
  <tr>
    <td style="...background-color: #F2DCDB;">2</td>
    <td>Schritt 2a</td>
    <td>MA</td>
    <td>Formular</td>
  </tr>
</table>
```

**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
<!-- VA: Rosa Header → Rosa Nummerierung -->
<tr>
  <th style="...background-color: #E6B8B7;">Aufgabe</th>
  ...
</tr>
<tr>
  <td style="...background-color: #F2DCDB; text-align: center;">1</td>
  <td style="...">Beschreibung (KEIN Hintergrund!)</td>
  ...
</tr>

<!-- Standard: Blau Header → Blau Nummerierung -->
<tr>
  <th style="...background-color: #B8CCE4;">3. Durchführung</th>
  ...
</tr>
<tr>
  <td style="...background-color: #B8CCE4; text-align: center;">1</td>
  <td style="...">Beschreibung (KEIN Hintergrund!)</td>
  ...
</tr>
```

---

## 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: `<div class="toc-entry toc-level-N">` mit `<a href="#sec-N">`
- **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. <Dokumenttitel>"
- Oder fügt "1. <Dokumenttitel>" 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 `<p>` 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 `<p>` 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 `<table>` 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 `<h2>` 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 `<table>`**:

```html
<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt;">
  <tr>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 12pt; font-weight: bold; text-align: left;">
      <p style="margin: 0; line-height: 1.5;">1. Ziel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Dieser Standard regelt...</p>
    </td>
  </tr>
</table>
```

### 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
<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt; margin-top: 10px;">
  <tr>
    <th colspan="2" style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 12pt; font-weight: bold; text-align: left; width: 50%;">
      <p style="margin: 0; line-height: 1.5;">3. Durchführung/Ablauf</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 11pt; font-weight: bold; text-align: left; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Verantwortung</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; font-size: 11pt; font-weight: bold; text-align: left; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Mittel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #B8CCE4; text-align: center; width: 5%;">
      <p style="margin: 0; line-height: 1.5;">1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; width: 45%;">
      <p style="margin: 0; line-height: 1.5;">Schritt 1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Arbeitsmittel, Kommunikation</p>
    </td>
  </tr>
</table>
```

---

## Template Rules: Verfahrensanweisung (Rosa)

### Section Structure
Sections use free-flowing `<h2>` headings (KEINE Tabellen!):

```html
<h2 id="sec-1" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">1. Zweck der Verfahrensanweisung</h2>
<p style="margin: 0 0 5px 0; line-height: 1.5; font-family: Arial, sans-serif; font-size: 11pt;">Mit dieser Verfahrensanweisung werden die Zuständigkeiten...</p>
```

### 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
<h2 id="sec-4" style="font-size: 12pt; font-weight: bold; margin: 10px 0 5px 0; font-family: Arial, sans-serif;">4. Beschreibung des Verfahrensablaufs</h2>
<table border="1" style="border-collapse: collapse; width: 100%; font-family: Arial, sans-serif; font-size: 11pt; margin-top: 10px;">
  <tr>
    <th colspan="2" style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 50%;">
      <p style="margin: 0; line-height: 1.5;">Aufgabe</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Verantwortung</p>
    </th>
    <th style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; width: 25%;">
      <p style="margin: 0; line-height: 1.5;">Mittel</p>
    </th>
  </tr>
  <tr>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; background-color: #E6B8B7; text-align: center; width: 5%;">
      <p style="margin: 0; line-height: 1.5;">1</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top; width: 45%;">
      <p style="margin: 0; line-height: 1.5;">Task description</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Telefon</p>
    </td>
  </tr>
</table>
```
**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
<h3 id="sec-3.3" style="font-size: 11pt; font-weight: bold; margin: 10px 0 5px 20px; font-family: Arial, sans-serif;">3.3. Abkürzungen:</h3>
<table border="0" style="border-collapse: collapse; margin: 10px auto; font-family: Arial, sans-serif; font-size: 11pt;">
  <tr>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">MA</p>
    </td>
    <td style="border: none; padding: 4px 30px 4px 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Mitarbeiter</p>
    </td>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">DP</p>
    </td>
    <td style="border: none; padding: 4px; vertical-align: top;">
      <p style="margin: 0; line-height: 1.5;">Dienstplan</p>
    </td>
  </tr>
</table>
```

---

## Tabellen MIT vs. OHNE Rahmenlinien

**Tabelle MIT sichtbaren Rahmenlinien:**
```html
<table border="1" style="border-collapse: collapse; ...">
  <td style="border: 1px solid #000; padding: 4px; vertical-align: top;">
```

**Tabelle OHNE sichtbare Rahmenlinien:**
```html
<table border="0" style="border-collapse: collapse; ...">
  <td style="border: none; padding: 4px; vertical-align: top;">
```

---

## 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 (`<td>`, `<th>`) — behalten ihre eigene Größe
- Headings (`<h1>`-`<h6>`) — behalten ihre eigene Größe
- Bold-Tags (`<strong>`) — 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 | - |

---

## Seitenbild-Cropping (Header/Footer-Entfernung)

### Gemini-basierte Crop-Erkennung (Phase 1)
Phase 1 sendet Pre-Content + **3 Content-Seiten** an Gemini. Der RECOGNITION_PROMPT instruiert:
- "Vergleiche die Seiten. Alles was sich auf mind. 2 Seiten am oberen/unteren Rand wiederholt = Header/Footer"
- Seitenzahlen zählen auch dazu (Position gleich, nur Zahl ändert sich)
- `header_bottom_percent` und `footer_top_percent` sind **physische Crop-Grenzen**
- Beispiel: Footer-Trennlinie bei 88%, Text 89-91%, Balken 91-92% → `footer_top_percent = 87.5`

### crop_page_images() — Physisches Cropping
Nach Phase 1 werden ALLE Seitenbilder physisch gecroppt:
```python
crop_page_images(page_images, header_bottom_pct, footer_top_pct, margin_px=5)
```
- Header/Footer werden abgeschnitten bevor Gemini die Bilder in Phase 2b sieht
- Gemini kann NICHT durch Header/Footer verwirrt werden
- Prompts enthalten KEINE "IGNORIEREN!"-Sektionen mehr
- Stattdessen: "Die Seitenbilder zeigen NUR den Content-Bereich. Konvertiere ALLES."
- Original-Bilder bleiben für visuelle Verifikation erhalten

### Vorteile des Croppings
1. **Keine Header/Footer-Artefakte möglich** (Gemini sieht sie nie)
2. **Kürzere Prompts** (keine "KOPFZEILE IGNORIEREN" Sektionen)
3. **Keine Header/Footer-Referenzbilder** → weniger Tokens → günstiger
4. **Tabellenfortsetzung einfacher** (Content reicht bis unterer Rand = Tabelle geht weiter)
5. **Weniger Post-Processing** nötig

---

## 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 `<img>` Tag im HTML

```html
<!-- Seite 1: Ganzseitiges Bild (gescanntes Dokument) -->
<div style="margin: 20px 0; page-break-inside: avoid;">
  <img src="content_1_1.png" alt="Seite 1" style="max-width: 100%; height: auto;" width="596" height="842">
</div>
```

**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
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." alt="...">
```
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 `<style>` tags
- No `<colgroup>` or `<col>` tags
- No `<thead>` or `<tbody>` tags
- Text in table cells wrapped in `<p>` tags
- Every `<td>` and `<th>` needs `vertical-align: top;`

**FORBIDDEN:**
- CSS classes (no `class="..."`)
- External stylesheets
- Empty separator rows
- Columns with `width: 0%`