# Vokabel-Arbeitsblatt Generator - Entwicklerhandbuch **Version:** 1.0.0 **Datum:** 2026-01-23 --- ## 1. Schnellstart ### 1.1 Lokale Entwicklung ```bash # Backend starten (klausur-service) cd /Users/benjaminadmin/Projekte/breakpilot-pwa/klausur-service/backend source venv/bin/activate uvicorn main:app --host 0.0.0.0 --port 8086 --reload # Frontend starten (studio-v2) cd /Users/benjaminadmin/Projekte/breakpilot-pwa/studio-v2 npm run dev ``` ### 1.2 URLs | Umgebung | Frontend | Backend API | |----------|----------|-------------| | Lokal | http://localhost:3001/vocab-worksheet | http://localhost:8086/api/v1/vocab/ | | Mac Mini | http://macmini:3001/vocab-worksheet | http://macmini:8086/api/v1/vocab/ | --- ## 2. Projektstruktur ``` breakpilot-pwa/ ├── klausur-service/ │ ├── backend/ │ │ ├── main.py # FastAPI App (inkl. Vocab-Router) │ │ ├── vocab_worksheet_api.py # Vocab-Worksheet Endpoints │ │ ├── hybrid_vocab_extractor.py # PaddleOCR + LLM Pipeline │ │ └── tests/ │ │ └── test_vocab_worksheet.py # Unit Tests │ └── docs/ │ ├── Vocab-Worksheet-Architecture.md │ └── Vocab-Worksheet-Developer-Guide.md │ └── studio-v2/ └── app/ └── vocab-worksheet/ └── page.tsx # Frontend (React/Next.js) ``` --- ## 3. Backend API ### 3.1 Endpoints-Uebersicht ``` POST /api/v1/vocab/sessions # Session erstellen GET /api/v1/vocab/sessions # Sessions auflisten GET /api/v1/vocab/sessions/{id} # Session abrufen DELETE /api/v1/vocab/sessions/{id} # Session loeschen POST /api/v1/vocab/sessions/{id}/upload # Bild/PDF hochladen POST /api/v1/vocab/sessions/{id}/upload-pdf-info # PDF-Info abrufen GET /api/v1/vocab/sessions/{id}/pdf-thumbnail/{p} # Seiten-Thumbnail POST /api/v1/vocab/sessions/{id}/process-single-page/{p} # Seite verarbeiten GET /api/v1/vocab/sessions/{id}/vocabulary # Vokabeln abrufen PUT /api/v1/vocab/sessions/{id}/vocabulary # Vokabeln aktualisieren POST /api/v1/vocab/sessions/{id}/generate # Arbeitsblatt generieren GET /api/v1/vocab/worksheets/{id}/pdf # PDF herunterladen GET /api/v1/vocab/worksheets/{id}/solution # Loesungs-PDF ``` ### 3.2 Session erstellen ```bash curl -X POST http://localhost:8086/api/v1/vocab/sessions \ -H "Content-Type: application/json" \ -d '{ "name": "Englisch Klasse 7 - Unit 3", "description": "Vokabeln aus Green Line", "source_language": "en", "target_language": "de" }' ``` **Response:** ```json { "id": "15dce1f4-f587-4b80-8c3d-62b20e7b845c", "name": "Englisch Klasse 7 - Unit 3", "status": "pending", "vocabulary_count": 0, "created_at": "2026-01-23T10:00:00Z" } ``` ### 3.3 Bild hochladen ```bash curl -X POST http://localhost:8086/api/v1/vocab/sessions/{session_id}/upload \ -F "file=@vokabeln.png" ``` ### 3.4 PDF verarbeiten ```bash # 1. PDF hochladen und Info abrufen curl -X POST http://localhost:8086/api/v1/vocab/sessions/{id}/upload-pdf-info \ -F "file=@schulbuch.pdf" # Response: {"session_id": "...", "page_count": 5} # 2. Einzelne Seiten verarbeiten (empfohlen) curl -X POST http://localhost:8086/api/v1/vocab/sessions/{id}/process-single-page/0 curl -X POST http://localhost:8086/api/v1/vocab/sessions/{id}/process-single-page/1 ``` ### 3.5 Vokabeln aktualisieren ```bash curl -X PUT http://localhost:8086/api/v1/vocab/sessions/{id}/vocabulary \ -H "Content-Type: application/json" \ -d '{ "vocabulary": [ { "id": "uuid-1", "english": "achieve", "german": "erreichen", "example_sentence": "She achieved her goals." } ] }' ``` ### 3.6 Arbeitsblatt generieren ```bash curl -X POST http://localhost:8086/api/v1/vocab/sessions/{id}/generate \ -H "Content-Type: application/json" \ -d '{ "worksheet_types": ["en_to_de", "de_to_en"], "include_solutions": true, "line_height": "large" }' ``` --- ## 4. Frontend-Entwicklung ### 4.1 Komponenten-Struktur Die gesamte UI ist in einer Datei (`page.tsx`) organisiert: ```typescript // Hauptkomponente export default function VocabWorksheetPage() { const [activeTab, setActiveTab] = useState('upload') const [sessions, setSessions] = useState([]) const [currentSession, setCurrentSession] = useState(null) const [vocabulary, setVocabulary] = useState([]) // ... } // Tabs type TabType = 'upload' | 'pages' | 'vocabulary' | 'worksheet' | 'export' ``` ### 4.2 API-Aufrufe ```typescript // API Base URL automatisch ermitteln const getApiBase = () => { if (typeof window === 'undefined') return 'http://localhost:8086' const host = window.location.hostname return `http://${host}:8086` } // Session erstellen const createSession = async (name: string) => { const response = await fetch(`${getApiBase()}/api/v1/vocab/sessions`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ name }) }) return response.json() } ``` ### 4.3 Styling Tailwind CSS mit Dark/Light Theme: ```typescript // Theme-aware Klassen className="bg-white dark:bg-gray-800 text-gray-900 dark:text-white" // Gradient-Buttons className="bg-gradient-to-r from-purple-600 to-blue-600 hover:from-purple-700 hover:to-blue-700" ``` --- ## 5. Vokabel-Extraktion ### 5.1 Vision LLM Modus (Standard) ```python # vocab_worksheet_api.py OLLAMA_URL = os.getenv("OLLAMA_URL", "http://host.docker.internal:11434") VISION_MODEL = os.getenv("OLLAMA_VISION_MODEL", "qwen2.5vl:32b") async def extract_vocabulary_from_image(image_data: bytes, filename: str): # Base64-kodiertes Bild an Ollama senden image_base64 = base64.b64encode(image_data).decode("utf-8") payload = { "model": VISION_MODEL, "messages": [{ "role": "user", "content": VOCAB_EXTRACTION_PROMPT, "images": [image_base64] }], "stream": False } response = await client.post(f"{OLLAMA_URL}/api/chat", json=payload) # Parse JSON response... ``` ### 5.2 Hybrid OCR + LLM Modus (Optional) ```python # hybrid_vocab_extractor.py async def extract_vocabulary_hybrid(image_bytes: bytes, page_number: int): # 1. PaddleOCR fuer Text-Erkennung regions, raw_text = run_paddle_ocr(image_bytes) # 2. Text fuer LLM formatieren formatted_text = format_ocr_for_llm(regions) # 3. LLM strukturiert die Daten vocabulary = await structure_vocabulary_with_llm(formatted_text) return vocabulary, confidence, error ``` ### 5.3 Prompt Engineering Der Extraktions-Prompt ist auf Deutsch fuer bessere Ergebnisse: ```python VOCAB_EXTRACTION_PROMPT = """Analysiere dieses Bild einer Vokabelliste aus einem Schulbuch. AUFGABE: Extrahiere alle Vokabeleintraege in folgendem JSON-Format: { "vocabulary": [ { "english": "to improve", "german": "verbessern", "example": "I want to improve my English." } ] } REGELN: 1. Erkenne das typische 3-Spalten-Layout: Englisch | Deutsch | Beispielsatz 2. Behalte die exakte Schreibweise bei 3. Bei fehlenden Beispielsaetzen: "example": null 4. Ignoriere Seitenzahlen, Ueberschriften 5. Gib NUR valides JSON zurueck """ ``` --- ## 6. Tests ### 6.1 Tests ausfuehren ```bash cd /Users/benjaminadmin/Projekte/breakpilot-pwa/klausur-service/backend source venv/bin/activate # Alle Tests pytest tests/test_vocab_worksheet.py -v # Mit Coverage pytest tests/test_vocab_worksheet.py --cov=vocab_worksheet_api --cov-report=html # Einzelne Testklasse pytest tests/test_vocab_worksheet.py::TestSessionCRUD -v ``` ### 6.2 Test-Kategorien | Klasse | Beschreibung | |--------|--------------| | `TestSessionCRUD` | Session erstellen, lesen, loeschen | | `TestVocabulary` | Vokabeln abrufen, aktualisieren | | `TestWorksheetGeneration` | Arbeitsblatt-Generierung | | `TestJSONParsing` | LLM-Response parsing | | `TestFileUpload` | Bild/PDF-Upload | | `TestSessionStatus` | Status-Workflow | | `TestEdgeCases` | Randfaelle | --- ## 7. Deployment ### 7.1 Docker Build ```bash # Klausur-Service neu bauen docker compose build klausur-service # Studio-v2 neu bauen docker compose build studio-v2 ``` ### 7.2 Sync zum Mac Mini ```bash # Source-Files synchronisieren rsync -avz --exclude 'node_modules' --exclude '.next' --exclude '__pycache__' \ /Users/benjaminadmin/Projekte/breakpilot-pwa/ \ macmini:/Users/benjaminadmin/Projekte/breakpilot-pwa/ # Container neu starten ssh macmini "cd /Users/benjaminadmin/Projekte/breakpilot-pwa && docker compose up -d" ``` --- ## 8. Troubleshooting ### 8.1 Haeufige Probleme | Problem | Loesung | |---------|---------| | Ollama nicht erreichbar | `docker exec -it ollama ollama list` pruefen | | PDF-Konvertierung schlaegt fehl | PyMuPDF installiert? `pip install PyMuPDF` | | Vision LLM Timeout | Timeout auf 300s erhoehen | | Leere Vokabel-Liste | Bild-Qualitaet pruefen, anderen LLM-Modus testen | ### 8.2 Logs pruefen ```bash # Backend-Logs docker logs klausur-service -f --tail 100 # Ollama-Logs docker logs ollama -f --tail 100 ``` ### 8.3 Debug-Modus ```python # In vocab_worksheet_api.py import logging logging.basicConfig(level=logging.DEBUG) logger = logging.getLogger(__name__) # Zeigt detaillierte OCR/LLM-Ausgaben ``` --- ## 9. Erweiterung ### 9.1 Neue Sprache hinzufuegen 1. `source_language` und `target_language` in Session-Model erweitern 2. Prompt anpassen fuer neue Sprachkombination 3. Frontend-Dropdown erweitern ### 9.2 Neuer Arbeitsblatt-Typ 1. `WorksheetType` Enum erweitern: ```python class WorksheetType(str, Enum): # ... CROSSWORD = "crossword" # Neu ``` 2. `generate_worksheet_html()` erweitern 3. Frontend-Checkbox hinzufuegen ### 9.3 Datenbank-Persistenz Aktuell: In-Memory (`_sessions` Dict) Fuer Produktion PostgreSQL hinzufuegen: ```python # models.py class VocabSession(Base): __tablename__ = "vocab_sessions" id = Column(UUID, primary_key=True) name = Column(String) status = Column(String) vocabulary = Column(JSON) # ... ``` --- ## 10. API-Referenz Vollstaendige OpenAPI-Dokumentation verfuegbar unter: - **Swagger UI:** http://macmini:8086/docs - **ReDoc:** http://macmini:8086/redoc Filter nach Tag `Vocabulary Worksheets` fuer alle Vocab-Endpoints.