breakpilot-pwa/scripts/REFACTORING_STRATEGY.md

# Refactoring-Strategie für große Dateien

## Übersicht

Dieses Dokument beschreibt die Strategie für das automatisierte Refactoring
der größten Dateien im BreakPilot-Projekt mittels Qwen2.5:32B auf dem Mac Mini.

## Priorisierte Dateien

| Prio | Datei | Zeilen | Sprache | Strategie |
|------|-------|--------|---------|-----------|
| 1 | `backend/frontend/static/js/studio.js` | 9.787 | JS | In Module aufteilen |
| 2 | `website/components/admin/SystemInfoSection.tsx` | 5.690 | TSX | Subkomponenten extrahieren |
| 3 | `backend/frontend/modules/companion.py` | 5.513 | Python | Klassen extrahieren |
| 4 | `backend/classroom_api.py` | 4.467 | Python | Router aufteilen |
| 5 | `backend/frontend/school.py` | 3.732 | Python | Services extrahieren |
| 6 | `backend/frontend/components/admin_panel.py` | 3.434 | Python | Komponenten separieren |
| 7 | `backend/ai_processor.py` | 2.999 | Python | Pipeline-Module |
| 8 | `website/app/admin/rag/page.tsx` | 2.964 | TSX | Hooks/Komponenten |
| 9 | `backend/frontend/modules/alerts.py` | 2.902 | Python | Alert-Typen separieren |
| 10 | `backend/frontend/meetings.py` | 2.847 | Python | Services extrahieren |

## Detailstrategien

### 1. studio.js (9.787 Zeilen) - HÖCHSTE PRIORITÄT

**Problem:** Monolithisches Admin-Panel JavaScript

**Ziel-Struktur:**
```
backend/frontend/static/js/
├── studio/
│   ├── index.js           # Entry point, imports
│   ├── api.js             # API-Calls
│   ├── components/
│   │   ├── dashboard.js   # Dashboard-Logik
│   │   ├── documents.js   # Dokument-Verwaltung
│   │   ├── users.js       # User-Management
│   │   └── settings.js    # Einstellungen
│   ├── utils/
│   │   ├── validators.js  # Validierungsfunktionen
│   │   ├── formatters.js  # Formatierung
│   │   └── helpers.js     # Hilfsfunktionen
│   └── state.js           # State-Management
└── studio.js              # Legacy-Wrapper (für Rückwärtskompatibilität)
```

**Chunk-Aufteilung:**
- Chunk 1 (Zeilen 1-800): Initialisierung, Globals, Utils
- Chunk 2 (Zeilen 801-1600): API-Funktionen
- Chunk 3 (Zeilen 1601-2400): Dashboard-Komponenten
- Chunk 4 (Zeilen 2401-3200): Dokument-Management
- Chunk 5 (Zeilen 3201-4000): User-Management
- Chunk 6 (Zeilen 4001-4800): Einstellungen
- Chunk 7 (Zeilen 4801-5600): Event-Handler
- Chunk 8 (Zeilen 5601-6400): Render-Funktionen
- Chunk 9 (Zeilen 6401-7200): Modals/Dialoge
- Chunk 10 (Zeilen 7201-8000): Tabellen/Listen
- Chunk 11 (Zeilen 8001-8800): Formulare
- Chunk 12 (Zeilen 8801-9787): Navigation/Footer

### 2. SystemInfoSection.tsx (5.690 Zeilen)

**Problem:** Zu große React-Komponente mit vielen Subkomponenten inline

**Ziel-Struktur:**
```
website/components/admin/
├── SystemInfoSection/
│   ├── index.tsx              # Hauptkomponente
│   ├── SystemOverview.tsx     # Übersichtskarten
│   ├── ContainerStatus.tsx    # Docker-Status
│   ├── DatabaseInfo.tsx       # DB-Statistiken
│   ├── ServiceHealth.tsx      # Service-Health
│   ├── ResourceUsage.tsx      # CPU/RAM/Disk
│   ├── LogViewer.tsx          # Log-Anzeige
│   └── hooks/
│       ├── useSystemInfo.ts   # Daten-Fetching
│       └── useHealthCheck.ts  # Health-Polling
└── SystemInfoSection.tsx      # Legacy-Wrapper
```

### 3. companion.py (5.513 Zeilen)

**Problem:** Monolithischer AI-Companion-Code

**Ziel-Struktur:**
```
backend/frontend/modules/companion/
├── __init__.py
├── core.py                # CompanionCore-Klasse
├── conversation.py        # Konversations-Handler
├── memory.py              # Gedächtnis-Management
├── prompts.py             # Prompt-Templates
├── tools.py               # Tool-Integration
├── handlers/
│   ├── text.py            # Text-Handler
│   ├── image.py           # Bild-Handler
│   └── voice.py           # Voice-Handler
└── utils.py               # Hilfsfunktionen
```

### 4. classroom_api.py (4.467 Zeilen)

**Problem:** Zu viele Endpoints in einer Datei

**Ziel-Struktur:**
```
backend/api/
├── classroom/
│   ├── __init__.py        # Router-Sammlung
│   ├── courses.py         # Kurs-Endpoints
│   ├── students.py        # Schüler-Endpoints
│   ├── teachers.py        # Lehrer-Endpoints
│   ├── assignments.py     # Aufgaben-Endpoints
│   ├── grades.py          # Noten-Endpoints
│   └── materials.py       # Material-Endpoints
└── classroom_api.py       # Legacy-Wrapper
```

## Refactoring-Regeln für Qwen

### Allgemeine Regeln

1. **Keine Breaking Changes**
   - Alle öffentlichen APIs beibehalten
   - Legacy-Wrapper für Rückwärtskompatibilität

2. **Imports beibehalten**
   - Relative Imports für neue Module
   - Absolute Imports nur bei externen Dependencies

3. **Type Hints hinzufügen**
   - Python: Type Hints für alle Parameter/Returns
   - TypeScript: Explizite Types statt `any`

4. **Dokumentation**
   - Docstrings für alle Klassen/Funktionen
   - JSDoc für JavaScript-Funktionen

### Python-spezifisch

```python
# VORHER (schlecht)
def process(data):
    # 500 Zeilen Code...
    pass

# NACHHER (gut)
def process(data: Dict[str, Any]) -> ProcessResult:
    """
    Verarbeitet die eingehenden Daten.

    Args:
        data: Dictionary mit Eingabedaten

    Returns:
        ProcessResult mit Verarbeitungsergebnis
    """
    validated = _validate_input(data)
    transformed = _transform_data(validated)
    return _create_result(transformed)
```

### JavaScript/TypeScript-spezifisch

```typescript
// VORHER (schlecht)
function handleClick(e) {
    // 200 Zeilen Code...
}

// NACHHER (gut)
interface ClickHandlerResult {
    success: boolean;
    data?: unknown;
    error?: string;
}

/**
 * Behandelt Click-Events auf dem Dashboard
 * @param event - Das Click-Event
 * @returns Ergebnis der Verarbeitung
 */
function handleDashboardClick(event: MouseEvent): ClickHandlerResult {
    const validatedEvent = validateClickEvent(event);
    const result = processClickAction(validatedEvent);
    return formatResult(result);
}
```

## Ausführungsplan

### Phase 1: Vorbereitung
1. [x] Orchestrator-Script erstellt
2. [x] Strategie-Dokument erstellt
3. [ ] Qwen2.5:32B Download abwarten
4. [ ] Ollama-API-Verbindung testen

### Phase 2: Refactoring (Reihenfolge)
1. [ ] `classroom_api.py` (kleiner, gut testbar)
2. [ ] `ai_processor.py` (wichtig für KI-Features)
3. [ ] `companion.py` (großer Impact)
4. [ ] `SystemInfoSection.tsx` (Frontend-Test)
5. [ ] `studio.js` (größte Datei, zuletzt)

### Phase 3: Validierung
1. [ ] Tests ausführen nach jedem Refactoring
2. [ ] Manuelle Code-Review durch Claude
3. [ ] Integration in Hauptbranch

## Kommandos

```bash
# Status prüfen
python scripts/qwen_refactor_orchestrator.py --status

# Ollama-Verbindung testen
python scripts/qwen_refactor_orchestrator.py --check-ollama

# Einzelne Datei refaktorieren
python scripts/qwen_refactor_orchestrator.py --file backend/classroom_api.py

# Alle großen Dateien refaktorieren
python scripts/qwen_refactor_orchestrator.py --all-large-files

# Tests für refaktorierte Datei
python scripts/qwen_refactor_orchestrator.py --run-tests backend/classroom_api.py
```

## Risiken und Mitigationen

| Risiko | Mitigation |
|--------|------------|
| Qwen-Kontext zu klein für Chunks | Chunk-Größe auf 800 Zeilen begrenzt |
| Breaking Changes | Legacy-Wrapper für alle Dateien |
| Tests schlagen fehl | Rollback auf Original möglich |
| Qwen-Halluzinationen | Claude-Review vor Integration |
| Netzwerk-Probleme | Retry-Logik im Orchestrator |

## Erfolgsmetriken

- [ ] Alle 10 Dateien unter 1000 Zeilen
- [ ] 100% Test-Coverage erhalten
- [ ] Keine Breaking Changes
- [ ] Verbesserte Code-Dokumentation
- [ ] Kürzere Build-Zeiten (durch besseres Tree-Shaking)