breakpilot-lehrer/klausur-service/docs/Worksheet-Editor-Architecture.md

# Visual Worksheet Editor - Architecture Documentation

**Version:** 1.0
**Datum:** 2026-01-23
**Status:** Implementiert

## 1. Übersicht

Der Visual Worksheet Editor ist ein Canvas-basierter Editor für die Erstellung und Bearbeitung von Arbeitsblättern. Er ermöglicht Lehrern, eingescannte Arbeitsblätter originalgetreu zu rekonstruieren oder neue Arbeitsblätter visuell zu gestalten.

### 1.1 Hauptfunktionen

- **Canvas-basiertes Editieren** mit Fabric.js
- **Freie Positionierung** von Text, Bildern und Formen
- **Typografie-Steuerung** (Schriftarten, Größen, Stile)
- **Bilder & Grafiken** hochladen und einfügen
- **KI-generierte Bilder** via Ollama/Stable Diffusion
- **PDF/Bild-Export** für Druck und digitale Nutzung
- **Mehrseitige Dokumente** mit Seitennavigation

### 1.2 Technologie-Stack

| Komponente | Technologie | Lizenz |
|------------|-------------|--------|
| Canvas-Bibliothek | Fabric.js 6.x | MIT |
| PDF-Export | pdf-lib 1.17.x | MIT |
| Frontend | Next.js / React | MIT |
| Backend API | FastAPI | MIT |
| KI-Bilder | Ollama + Stable Diffusion | Apache 2.0 / MIT |

## 2. Architektur

```
┌──────────────────────────────────────────────────────────────────────┐
│                    Frontend (studio-v2 / Next.js)                     │
│  /studio-v2/app/worksheet-editor/page.tsx                            │
│                                                                        │
│  ┌─────────────┐  ┌────────────────────────────┐  ┌────────────────┐ │
│  │  Toolbar    │  │     Fabric.js Canvas       │  │  Properties    │ │
│  │  (Links)    │  │     (Mitte - 60%)          │  │  Panel         │ │
│  │             │  │                            │  │  (Rechts)      │ │
│  │ - Select    │  │  ┌──────────────────────┐  │  │                │ │
│  │ - Text      │  │  │                      │  │  │ - Schriftart   │ │
│  │ - Formen    │  │  │    A4 Arbeitsfläche  │  │  │ - Größe        │ │
│  │ - Bilder    │  │  │    mit Grid          │  │  │ - Farbe        │ │
│  │ - KI-Bild   │  │  │                      │  │  │ - Position     │ │
│  │ - Tabelle   │  │  └──────────────────────┘  │  │ - Ebene        │ │
│  └─────────────┘  └────────────────────────────┘  └────────────────┘ │
│                                                                        │
│  ┌────────────────────────────────────────────────────────────────┐   │
│  │  Seiten-Navigation | Zoom | Grid | Export PDF                   │   │
│  └────────────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                 klausur-service (FastAPI - Port 8086)                 │
│  POST /api/v1/worksheet/ai-image     → Bild via Ollama generieren    │
│  POST /api/v1/worksheet/save         → Worksheet speichern           │
│  GET  /api/v1/worksheet/{id}         → Worksheet laden               │
│  POST /api/v1/worksheet/export-pdf   → PDF generieren                │
└──────────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────────┐
│                    Ollama (Port 11434)                                │
│  Model: stable-diffusion oder kompatibles Text-to-Image Modell       │
│  Text-to-Image für KI-generierte Grafiken                            │
└──────────────────────────────────────────────────────────────────────┘
```

## 3. Dateistruktur

### 3.1 Frontend (studio-v2)

```
/studio-v2/
├── app/
│   └── worksheet-editor/
│       ├── page.tsx                    # Haupt-Editor-Seite
│       └── types.ts                    # TypeScript Interfaces
│
├── components/
│   └── worksheet-editor/
│       ├── index.ts                    # Exports
│       ├── FabricCanvas.tsx            # Fabric.js Canvas Wrapper
│       ├── EditorToolbar.tsx           # Werkzeugleiste (links)
│       ├── PropertiesPanel.tsx         # Eigenschaften-Panel (rechts)
│       ├── AIImageGenerator.tsx        # KI-Bild Generator Modal
│       ├── CanvasControls.tsx          # Zoom, Grid, Seiten
│       ├── ExportPanel.tsx             # PDF/Bild Export
│       └── PageNavigator.tsx           # Mehrseitige Dokumente
│
├── lib/
│   └── worksheet-editor/
│       ├── index.ts                    # Exports
│       └── WorksheetContext.tsx        # State Management
```

### 3.2 Backend (klausur-service)

```
/klausur-service/backend/
├── worksheet_editor_api.py             # API Endpoints
└── main.py                             # Router-Registrierung
```

## 4. API Endpoints

### 4.1 KI-Bild generieren

```http
POST /api/v1/worksheet/ai-image
Content-Type: application/json

{
  "prompt": "Ein freundlicher Cartoon-Hund der ein Buch liest",
  "style": "cartoon",
  "width": 512,
  "height": 512
}
```

**Response:**
```json
{
  "image_base64": "data:image/png;base64,...",
  "prompt_used": "...",
  "error": null
}
```

**Styles:**
- `realistic` - Fotorealistisch
- `cartoon` - Cartoon/Comic
- `sketch` - Handgezeichnete Skizze
- `clipart` - Einfache Clipart-Grafiken
- `educational` - Bildungs-Illustrationen

### 4.2 Worksheet speichern

```http
POST /api/v1/worksheet/save
Content-Type: application/json

{
  "id": "optional-existing-id",
  "title": "Englisch Vokabeln Unit 3",
  "pages": [
    { "id": "page_1", "index": 0, "canvasJSON": "{...}" }
  ],
  "pageFormat": {
    "width": 210,
    "height": 297,
    "orientation": "portrait"
  }
}
```

### 4.3 Worksheet laden

```http
GET /api/v1/worksheet/{id}
```

### 4.4 PDF exportieren

```http
POST /api/v1/worksheet/{id}/export-pdf
```

**Response:** PDF-Datei als Download

### 4.5 Worksheets auflisten

```http
GET /api/v1/worksheet/list/all
```

## 5. Komponenten

### 5.1 FabricCanvas

Die Kernkomponente für den Canvas-Bereich:

- **A4-Format**: 794 x 1123 Pixel (96 DPI)
- **Grid-Overlay**: Optionales Raster mit Snap-Funktion
- **Zoom/Pan**: Mausrad und Controls
- **Selection**: Einzel- und Mehrfachauswahl
- **Keyboard Shortcuts**: Del, Ctrl+C/V/Z/D

### 5.2 EditorToolbar

Werkzeuge für die Bearbeitung:

| Icon | Tool | Beschreibung |
|------|------|--------------|
| 🖱️ | Select | Elemente auswählen/verschieben |
| T | Text | Text hinzufügen (IText) |
| ▭ | Rechteck | Rechteck zeichnen |
| ○ | Kreis | Kreis/Ellipse zeichnen |
| ― | Linie | Linie zeichnen |
| → | Pfeil | Pfeil zeichnen |
| 🖼️ | Bild | Bild hochladen |
| ✨ | KI-Bild | Bild mit KI generieren |
| ⊞ | Tabelle | Tabelle einfügen |

### 5.3 PropertiesPanel

Eigenschaften-Editor für ausgewählte Objekte:

**Text-Eigenschaften:**
- Schriftart (Arial, Times, Georgia, OpenDyslexic, Schulschrift)
- Schriftgröße (8-120pt)
- Schriftstil (Normal, Fett, Kursiv)
- Zeilenhöhe, Zeichenabstand
- Textausrichtung
- Textfarbe

**Form-Eigenschaften:**
- Füllfarbe
- Rahmenfarbe und -stärke
- Eckenradius

**Allgemein:**
- Deckkraft
- Löschen-Button

### 5.4 WorksheetContext

React Context für globalen State:

```typescript
interface WorksheetContextType {
  canvas: Canvas | null
  document: WorksheetDocument | null
  activeTool: EditorTool
  selectedObjects: FabricObject[]
  zoom: number
  showGrid: boolean
  snapToGrid: boolean
  currentPageIndex: number
  canUndo: boolean
  canRedo: boolean
  isDirty: boolean
  // ... Methoden
}
```

## 6. Datenmodelle

### 6.1 WorksheetDocument

```typescript
interface WorksheetDocument {
  id: string
  title: string
  description?: string
  pages: WorksheetPage[]
  pageFormat: PageFormat
  createdAt: string
  updatedAt: string
}
```

### 6.2 WorksheetPage

```typescript
interface WorksheetPage {
  id: string
  index: number
  canvasJSON: string  // Serialisierter Fabric.js Canvas
  thumbnail?: string
}
```

### 6.3 PageFormat

```typescript
interface PageFormat {
  width: number   // in mm (Standard: 210)
  height: number  // in mm (Standard: 297)
  orientation: 'portrait' | 'landscape'
  margins: { top, right, bottom, left: number }
}
```

## 7. Features

### 7.1 Undo/Redo

- History-Stack mit max. 50 Einträgen
- Automatische Speicherung bei jeder Änderung
- Keyboard: Ctrl+Z (Undo), Ctrl+Y (Redo)

### 7.2 Grid & Snap

- Konfigurierbares Raster (5mm, 10mm, 15mm, 20mm)
- Snap-to-Grid beim Verschieben
- Ein-/Ausblendbar

### 7.3 Export

- **PDF**: Mehrseitig, A4-Format
- **PNG**: Hochauflösend (2x Multiplier)
- **JPG**: Mit Qualitätseinstellung

### 7.4 Speicherung

- **Backend**: REST API mit JSON-Persistierung
- **Fallback**: localStorage bei Offline-Betrieb

## 8. KI-Bildgenerierung

### 8.1 Ollama Integration

Der Editor nutzt Ollama für die KI-Bildgenerierung:

```python
OLLAMA_URL = "http://host.docker.internal:11434"
```

### 8.2 Placeholder-System

Falls Ollama nicht verfügbar ist, wird ein Placeholder-Bild generiert:
- Farbcodiert nach Stil
- Prompt-Text als Beschreibung
- "KI-Bild (Platzhalter)"-Badge

### 8.3 Stil-Prompts

Jeder Stil fügt automatisch Modifikatoren zum Prompt hinzu:

```python
STYLE_PROMPTS = {
    "realistic": "photorealistic, high detail",
    "cartoon": "cartoon style, colorful, child-friendly",
    "sketch": "pencil sketch, hand-drawn",
    "clipart": "clipart style, flat design",
    "educational": "educational illustration, textbook style"
}
```

## 9. Glassmorphism Design

Der Editor folgt dem Glassmorphism-Design des Studio v2:

```typescript
// Dark Theme
'backdrop-blur-xl bg-white/10 border border-white/20'

// Light Theme
'backdrop-blur-xl bg-white/70 border border-black/10 shadow-xl'
```

## 10. Internationalisierung

Unterstützte Sprachen:
- 🇩🇪 Deutsch
- 🇬🇧 English
- 🇹🇷 Türkçe
- 🇸🇦 العربية (RTL)
- 🇷🇺 Русский
- 🇺🇦 Українська
- 🇵🇱 Polski

Translation Key: `nav_worksheet_editor`

## 11. Sicherheit

### 11.1 Bild-Upload

- Nur Bildformate (image/*)
- Client-seitige Validierung
- Base64-Konvertierung

### 11.2 CORS

Aktiviert für lokale Entwicklung und Docker-Umgebung.

## 12. Deployment

### 12.1 Frontend

```bash
cd studio-v2
npm install
npm run dev  # Port 3001
```

### 12.2 Backend

Der klausur-service läuft auf Port 8086:

```bash
cd klausur-service/backend
python main.py
```

### 12.3 Docker

Der Service ist Teil des docker-compose.yml.

## 13. Zukünftige Erweiterungen

- [ ] Tabellen-Tool mit Zellbearbeitung
- [ ] Vorlagen-Bibliothek
- [ ] Kollaboratives Editieren
- [ ] Drag & Drop aus Dokumentenbibliothek
- [ ] Integration mit Vocab-Worksheet