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

# 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

// 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. Orchestrator-Script erstellt
2. 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

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