breakpilot-pwa/.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

-- 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

# 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"

---

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 page.tsx 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