Refactoring: Konsolidierung und Vereinfachung der Utils-Struktur

Problemanalyse

Die aktuelle src/utils/-Struktur ist über die Zeit organisch gewachsen und weist mehrere architektonische Probleme auf:

1. WFS-Authentication: Fragmentierte Konfiguration

  • wfs-auth.ts: Hauptimplementierung mit hardcoded Credentials
  • wfs-config.ts: Server-side Config (wenig genutzt)
  • test-wfs-auth.ts: Test-Utilities vermischt mit Produktionscode
  • Problem: Mehrfache Config-Quellen

2. Event-System: Überlappende Verantwortlichkeiten

  • events.ts: Generisches Event-Handling mit Retry-Mechanismus
  • kommunen-click-handler.ts: Spezifische Click-Handler-Logik
  • Problem: Doppelte Event-Dispatcher, unterschiedliche Patterns

3. State Management: Verteilte Zuständigkeiten

  • map-state.ts: Zentrale Map-State-Verwaltung
  • tab-persistence.ts: Isolierte Tab-State-Logik
  • feature-selection.ts: Feature-spezifischer State
  • Problem: State-Logik über mehrere Module verteilt

4. Handler-Klassen: Inkonsistente Patterns

  • CategoryHandler: Klassen-basiert
  • FeatureSelectionHandler: Klassen-basiert
  • KommunenClickHandler: Klassen-basiert
  • Utils-Funktionen: Funktional
  • Problem: Gemischte Paradigmen, keine einheitliche API

Ziel-Architektur

src/
├── services/           # External Service Integrations
│   ├── wfs/
│   │   ├── client.ts          # WFS Client (auth, requests)
│   │   ├── config.ts          # Environment-based config
│   │   └── types.ts           # WFS-specific types
│   └── osm/
│       └── client.ts          # Future: OSM integration
├── stores/             # State Management  
│   ├── map-store.ts           # Consolidated map state
│   ├── ui-store.ts            # UI state (tabs, selections)
│   └── feature-store.ts       # Feature selections
├── handlers/           # Event & Interaction Handlers
│   ├── map-handlers.ts        # Map interactions consolidated
│   ├── ui-handlers.ts         # UI interactions
│   └── sync-handlers.ts       # Data synchronization
├── utils/              # Pure Utilities
│   ├── crs.ts                 # CRS transformations (unchanged)
│   ├── validation.ts          # Data validation utilities
│   └── dom.ts                 # DOM helpers
├── types/              # TypeScript Definitions
│   ├── map.ts
│   ├── api.ts
│   └── ui.ts
└── constants/          # App Constants
    ├── projections.ts
    └── endpoints.ts

Refactoring-Plan

Phase 1: Service-Layer (Woche 1-2)

Ziele

  • WFS-Client konsolidieren und Credentials sicher verwalten
  • Einheitliche Service-API etablieren
  • Tests von Produktionscode trennen

Änderungen

  • Erstelle src/services/wfs/client.ts mit sauberer API
  • Migriere Credentials zu Environment-Variablen
  • Verschiebe Tests nach src/tests/services/

Phase 2: State Management (Woche 3)

Ziele

  • Zentralisierte State-Verwaltung
  • Konsistente State-Updates
  • Simplified Subscription-Pattern

Änderungen

  • Konsolidiere State-Manager zu src/stores/
  • Implementiere einheitliches Store-Pattern
  • Reduziere setState/getState-Komplexität

Phase 3: Handler Consolidation (Woche 4)

Ziele

  • Einheitliche Handler-APIs
  • Reduzierte Event-Komplexität
  • Verbesserte Error-Handling

Änderungen

  • Konsolidiere Handler-Klassen
  • Vereinfache Event-Dispatching
  • Einheitliche Cleanup-Patterns

Phase 4: Testing & Documentation (Woche 5)

Ziele

  • Vollständige Test-Coverage
  • API-Dokumentation
  • Migration Guide

Lieferables

  • Unit-Tests für alle Services/Stores
  • JSDoc-Dokumentation
  • Upgrade-Guide für Team

API-Vereinfachung (Beispiele)

Vorher:

// Fragmentiert über mehrere Files
const wfsClient = new WFSAuthClient(/* complex config */);
const mapState = new MapStateManager(/* more config */);
const eventHandler = new KommunenClickHandler();

// Komplexe Event-Chain
dispatchThrottledEvent("kommunen:focus", detail);
window.addEventListener("kommunen:focus", handler);

Nachher:

// Einfache, einheitliche APIs
import { wfs } from '@/services/wfs';
import { mapStore, uiStore } from '@/stores';

// Direkte Service-Calls
const features = await wfs.getFeatures('containers', { category: 'friedhoefe' });

// Reactive State
mapStore.focusKommune({ slug: 'koeln', center: [6.9, 50.9] });
uiStore.setActiveTab('kategorien');

Migration Strategy

  1. Feature-Flags: Alte und neue APIs parallel laufen lassen
  2. Schrittweise Migration: Ein Modul nach dem anderen
  3. Backward Compatibility: Wrapper für bestehende APIs
  4. Team-Koordination: Tägliche Sync-Calls während Refactoring

Erfolgskriterien

  • Performance: Reduzierte Bundle-Size um mindestens 10%
  • Maintainability: Reduzierung der zyklomatischen Komplexität
  • Security: Keine hardcoded Credentials im Code
  • DX: Verbesserte TypeScript-Unterstützung
  • Testing: >80% Test-Coverage für neue Module

Risiken & Mitigation

Risiko Impact Mitigation
Breaking Changes Hoch Feature-Flags + schrittweise Migration
Team-Blockierung Mittel Tägliche Abstimmung + Pair-Programming
Scope Creep Mittel Strikter Phase-Plan + Review-Gates

Technische Notizen

Branch-Strategy: feature/team-de1/utils-refactoring

Review-Requirements:

  • Mindestens 2 Reviewer pro Phase
  • Zwingend Code-Owner Review bei Core-Utils
  • Performance-Benchmarks vor/nach Refactoring

Dependencies:

  • Keine neuen External Dependencies
  • Mögliche interne Reorganisation von Astro-Content-Collections

/cc @team-de1 @PeterKoenig

Aufwand: ~5 Wochen (1 FTE)
Priorität: Hoch
Labels: refactoring, architecture, technical-debt, feature/team-de1

Edited by Peter König