breakpilot-lehrer/.claude/rules/vocab-worksheet.md

# Vokabel-Arbeitsblatt Generator - Entwicklerdokumentation

**Status:** Produktiv
**Letzte Aktualisierung:** 2026-02-08
**URL:** https://macmini/vocab-worksheet

---

## Uebersicht

Der Vokabel-Arbeitsblatt Generator ermoeglicht Lehrern:
- Schulbuchseiten (PDF/Bild) zu scannen
- Vokabeln automatisch per OCR zu extrahieren
- Druckfertige Arbeitsblaetter in verschiedenen Formaten zu generieren

---

## Architektur

```
Browser (studio-v2)        klausur-service (Port 8086)        PostgreSQL
       │                            │                             │
       │  POST /upload-pdf-info     │                             │
       │  POST /process-single-page │                             │
       │  POST /generate            │                             │
       │  POST /generate-nru        │  ──── vocab_sessions ──────▶│
       │  GET /worksheets/{id}/pdf  │  ──── vocab_entries ───────▶│
       │                            │  ──── vocab_worksheets ────▶│
       └────────────────────────────┘                             │
```

---

## Arbeitsblatt-Formate

### Standard-Format

Klassisches Arbeitsblatt mit waehlbaren Uebungstypen:
- **Englisch → Deutsch**: Englische Woerter uebersetzen
- **Deutsch → Englisch**: Deutsche Woerter uebersetzen
- **Abschreibuebung**: Woerter mehrfach schreiben
- **Lueckensaetze**: Saetze mit Luecken ausfuellen

### NRU-Format (Neu: 2026-02-08)

Spezielles Format fuer strukturiertes Vokabellernen:

**Seite 1 (pro gescannter Seite): Vokabeltabelle**
| Englisch | Deutsch | Korrektur |
|----------|---------|-----------|
| word     | (leer)  | (leer)    |

- Kind schreibt deutsche Uebersetzung
- Eltern korrigieren, Kind schreibt ggf. korrigierte Version

**Seite 2 (pro gescannter Seite): Lernsaetze**
| Deutscher Satz                    |
|-----------------------------------|
| (2 leere Zeilen fuer EN-Uebersetzung) |

- Deutscher Satz vorgegeben
- Kind schreibt englische Uebersetzung

**Automatische Trennung:**
- Einzelwoerter/Phrasen → Vokabeltabelle
- Saetze (enden mit `.!?` oder > 50 Zeichen) → Lernsaetze

---

## API-Endpoints

### Standard-Format
```
POST /api/v1/vocab/sessions/{session_id}/generate
Body: {
  "worksheet_types": ["en_to_de", "de_to_en", "copy", "gap_fill"],
  "title": "Vokabeln Unit 3",
  "include_solutions": true,
  "line_height": "normal" | "large" | "extra-large"
}
Response: { "id": "worksheet-uuid", ... }
```

### NRU-Format
```
POST /api/v1/vocab/sessions/{session_id}/generate-nru
Body: {
  "title": "Vokabeltest",
  "include_solutions": true,
  "specific_pages": [1, 2]  // optional, 1-indexed
}
Response: {
  "worksheet_id": "uuid",
  "statistics": {
    "total_entries": 96,
    "vocabulary_count": 75,
    "sentence_count": 21,
    "source_pages": [1, 2, 3],
    "worksheet_pages": 6
  },
  "download_url": "/api/v1/vocab/worksheets/{id}/pdf",
  "solution_url": "/api/v1/vocab/worksheets/{id}/solution"
}
```

### PDF-Download
```
GET /api/v1/vocab/worksheets/{worksheet_id}/pdf
GET /api/v1/vocab/worksheets/{worksheet_id}/solution
```

---

## Dateien

### Backend (klausur-service)

| Datei | Beschreibung |
|-------|--------------|
| `vocab_worksheet_api.py` | Haupt-API Router mit allen Endpoints |
| `nru_worksheet_generator.py` | NRU-Format HTML/PDF Generator |
| `vocab_session_store.py` | PostgreSQL Datenbankoperationen |
| `hybrid_vocab_extractor.py` | OCR-Extraktion (PaddleOCR + LLM) |
| `tesseract_vocab_extractor.py` | Tesseract OCR Fallback |

### Frontend (studio-v2)

| Datei | Beschreibung |
|-------|--------------|
| `app/vocab-worksheet/page.tsx` | Haupt-UI mit Template-Auswahl |

---

## Datenbank-Schema

```sql
-- Sessions
CREATE TABLE vocab_sessions (
  id UUID PRIMARY KEY,
  name VARCHAR(255),
  status VARCHAR(50),
  vocabulary_count INT,
  source_language VARCHAR(10),
  target_language VARCHAR(10),
  created_at TIMESTAMP
);

-- Vokabeln
CREATE TABLE vocab_entries (
  id UUID PRIMARY KEY,
  session_id UUID REFERENCES vocab_sessions(id),
  english TEXT,
  german TEXT,
  example_sentence TEXT,
  source_page INT,
  source_row INT,
  source_column INT
);

-- Generierte Arbeitsblaetter
CREATE TABLE vocab_worksheets (
  id UUID PRIMARY KEY,
  session_id UUID REFERENCES vocab_sessions(id),
  worksheet_types JSONB,
  pdf_path VARCHAR(500),
  solution_path VARCHAR(500),
  generated_at TIMESTAMP
);
```

---

## Deployment

```bash
# 1. Backend synchronisieren
rsync -avz klausur-service/backend/ macmini:.../klausur-service/backend/

# 2. Frontend synchronisieren
rsync -avz studio-v2/app/vocab-worksheet/ macmini:.../studio-v2/app/vocab-worksheet/

# 3. Container neu bauen
ssh macmini "docker compose build --no-cache klausur-service studio-v2"

# 4. Container starten
ssh macmini "docker compose up -d klausur-service studio-v2"
```

---

## Frontend Refactoring (2026-04-12)

`page.tsx` wurde von 2337 Zeilen in 14 Dateien aufgeteilt:

```
studio-v2/app/vocab-worksheet/
├── page.tsx                 # 198 Zeilen — Orchestrator
├── types.ts                 # Interfaces, VocabWorksheetHook
├── constants.ts             # API-Base, Formats, Defaults
├── useVocabWorksheet.ts     # 843 Zeilen — Custom Hook (alle State + Logik)
└── components/
    ├── UploadScreen.tsx      # Session-Liste + Dokument-Auswahl
    ├── PageSelection.tsx     # PDF-Seitenauswahl
    ├── VocabularyTab.tsx     # Vokabel-Tabelle + IPA/Silben
    ├── WorksheetTab.tsx      # Format-Auswahl + Konfiguration
    ├── ExportTab.tsx         # PDF-Download
    ├── OcrSettingsPanel.tsx   # OCR-Filter Einstellungen
    ├── FullscreenPreview.tsx  # Vollbild-Vorschau Modal
    ├── QRCodeModal.tsx        # QR-Upload Modal
    └── OcrComparisonModal.tsx # OCR-Vergleich Modal
```

---

## Erweiterung: Neue Formate hinzufuegen

1. **Backend**: Neuen Generator in `klausur-service/backend/` erstellen
2. **API**: Neuen Endpoint in `vocab_worksheet_api.py` hinzufuegen
3. **Frontend**: Format zu `worksheetFormats` Array in `constants.ts` hinzufuegen
4. **Doku**: Diese Datei aktualisieren

---

## Aenderungshistorie

| Datum | Aenderung |
|-------|-----------|
| 2026-02-08 | NRU-Format und Template-Auswahl hinzugefuegt |
| 2026-02-07 | Initiale Implementierung mit Standard-Format |