furt/devdocs/furt_development_process.md

# Entwicklungsprozess für Furt API-Gateway

**Erstellt:** 03.06.2025  
**Letzte Aktualisierung:** 03.06.2025  
**Version:** 1.0  
**Verantwortlich:** Claude / DAW-Team  
**Dateipfad:** devdocs/development-process.md

## Zweck dieses Dokuments

Dieses Dokument definiert den verbindlichen Prozess für die Entwicklung und Änderung von Code im Rahmen des Furt API-Gateway-Projekts. Es ergänzt die allgemeinen Entwicklungsrichtlinien um API-Gateway-spezifische Patterns und Multi-Service-Koordination.

Es richtet sich an alle Projektbeteiligten, die am Gateway oder Services entwickeln.

## Verwandte Dokumente

Dieses Dokument steht im Zusammenhang mit folgenden anderen Dokumenten:

- **KONZEPT.md:** Zentrale Referenz und Konzeptdokumentation, devdocs/KONZEPT.md
- **TESTING_GUIDELINES.md:** API-Gateway-spezifische Test-Standards, devdocs/TESTING_GUIDELINES.md
- **ARCHITECTURE.md:** Detaillierte Systemarchitektur, devdocs/ARCHITECTURE.md

## Änderungshistorie

| Version | Datum | Änderungen | Autor |
|---------|-------|------------|-------|
| 1.0 | 03.06.2025 | Initiale Version für Furt API-Gateway | Claude / DAW-Team |

## 1. Grundprinzipien für API-Gateway-Entwicklung

### 1.1 Service-First-Entwicklung

Jede Entwicklungsaufgabe muss im Kontext des **Service-Ökosystems** betrachtet werden:

- **Gateway-Änderungen** betreffen potenziell alle Services
- **Service-Änderungen** können Gateway-Anpassungen erfordern
- **API-Contracts** zwischen Gateway und Services sind kritisch
- **Breaking Changes** erfordern koordinierte Rollouts

### 1.2 API-Contract-Driven Development

Bevor Code geschrieben wird, müssen **API-Contracts** definiert werden:

- **OpenAPI-Spezifikation** für neue Endpunkte
- **Service-Interface-Definition** für neue Services
- **Authentication/Authorization-Requirements** für alle APIs
- **Error-Response-Standards** konsistent halten

### 1.3 Security-First-Pattern

Sicherheit wird bei **jeder** Änderung mitgedacht:

- **API-Key-Berechtigungen** bei neuen Endpunkten definieren
- **Input-Validation** für alle eingehenden Requests
- **Rate-Limiting** für neue Services konfigurieren
- **IP-Restrictions** wo angemessen anwenden

## 2. Verbindlicher Entwicklungsprozess für Furt

### 2.1 Vorbereitung

1. **Requirements-Analyse mit Service-Impact**
   - Welche Services sind betroffen?
   - Welche Gateway-Komponenten benötigen Änderungen?
   - Sind Breaking Changes erforderlich?
   - Welche API-Contracts müssen definiert/aktualisiert werden?

2. **Explizite Anfrage nach relevanten Dateien**
   - Gateway-Dateien: `internal/gateway/`, `configs/gateway.yaml`
   - Service-Dateien: `internal/services/[service]/`, `configs/services/`
   - API-Dokumentation: `docs/api/`, OpenAPI-Specs
   - Integration-Tests: `tests/integration/`

3. **Analyse der Service-Integration-Pattern**
   - Bestehende Service-Registry-Einträge
   - Routing-Patterns und Middleware-Chain
   - Authentifizierungs-Flows
   - Health-Check-Mechanismen

### 2.2 Design und Planung

1. **API-First-Design dokumentieren**
   - OpenAPI-Spezifikation **vor** der Implementierung schreiben
   - Request/Response-Schemas definieren
   - HTTP-Status-Codes und Error-Handling spezifizieren
   - Authentication-Requirements dokumentieren

2. **Service-Integration-Strategy festlegen**
   - Wie wird der Service im Gateway registriert?
   - Welche Health-Check-URL wird verwendet?
   - Welche Timeout-Werte sind angemessen?
   - Braucht der Service Admin-UI-Integration?

3. **Breaking-Change-Impact analysieren**
   - Betrifft die Änderung bestehende API-Contracts?
   - Sind koordinierte Service-Updates erforderlich?
   - Müssen Client-Integrationen (Hugo-Shortcodes) angepasst werden?
   - Ist eine API-Versionierung (v1 → v2) notwendig?

4. **Configuration-Strategy bestimmen**
   - Welche neuen Config-Parameter werden benötigt?
   - Sind Environment-Variable für Secrets erforderlich?
   - Wie wird die Config zwischen Gateway und Service koordiniert?

### 2.3 Implementierung

1. **Multi-Component-Development-Order**
   
   **Für neue Services:**
   ```
   1. Service-Struktur scaffolden (service-generator.sh)
   2. Service-Logik implementieren (Standalone-Mode)
   3. Gateway-Integration hinzufügen
   4. Integration-Tests schreiben
   5. Deployment-Scripts anpassen
   ```

   **Für Gateway-Änderungen:**
   ```
   1. Gateway-Kern-Logik implementieren
   2. Middleware/Auth-Anpassungen
   3. Service-Integration testen
   4. Health-Check-Aggregation
   5. Admin-Interface-Updates
   ```

   **Für API-Änderungen:**
   ```
   1. OpenAPI-Spec aktualisieren
   2. Gateway-Routing anpassen
   3. Service-Endpunkt implementieren
   4. Input-Validation hinzufügen
   5. Integration-Tests erweitern
   ```

2. **Koordinierte Entwicklung bei Service-Updates**
   - **Gateway-kompatible Änderungen zuerst** (additive APIs)
   - **Service-Tests** mit Gateway-Integration
   - **Backward-Compatibility** während Übergangsphase
   - **Coordinated Deployment** bei Breaking Changes

3. **Configuration-Management während Entwicklung**
   - **Development-Configs** in `configs/[component].dev.yaml`
   - **Environment-Variable-Mapping** dokumentieren
   - **Config-Validation** bei Service-Start implementieren
   - **Hot-Reload** für Development (wo möglich)

### 2.4 Testing-Integration

1. **Multi-Layer-Testing-Strategy**
   - **Unit-Tests:** Für Gateway- und Service-Komponenten isoliert
   - **Integration-Tests:** Gateway ↔ Service-Kommunikation
   - **API-Tests:** End-to-End API-Contract-Validation
   - **Load-Tests:** Gateway-Performance mit mehreren Services

2. **Test-Coordination-Pattern**
   ```go
   // Beispiel: Service-Integration-Test
   func TestGatewayServiceIntegration(t *testing.T) {
       // 1. Start Test-Service
       service := startTestService(t, serviceConfig)
       defer service.Close()
       
       // 2. Configure Gateway with Test-Service
       gateway := startTestGateway(t, gatewayConfigWithService(service.URL))
       defer gateway.Close()
       
       // 3. Test Gateway → Service communication
       testServiceAPIThroughGateway(t, gateway, service)
   }
   ```

3. **Breaking-Change-Test-Strategy**
   - **Backward-Compatibility-Tests** bei API-Änderungen
   - **Version-Migration-Tests** bei Breaking Changes
   - **Client-Integration-Tests** (Hugo-Shortcode-Kompatibilität)

## 3. Service-spezifische Entwicklungs-Pattern

### 3.1 Neue Service-Entwicklung

1. **Service-Scaffolding**
   ```bash
   ./scripts/service-generator.sh newsletter
   # Erstellt komplette Service-Struktur
   ```

2. **Service-Interface-Implementation**
   ```go
   // Jeder Service muss dieses Interface implementieren
   type Service interface {
       // Gateway-Integration
       HandleRequest(w http.ResponseWriter, r *http.Request)
       HealthCheck() HealthStatus
       
       // Standalone-Mode
       HandleWithAuth(w http.ResponseWriter, r *http.Request)
       
       // Lifecycle
       Start(ctx context.Context, config ServiceConfig) error
       Stop(ctx context.Context) error
       
       // Service-Metadata
       GetServiceInfo() ServiceInfo
   }
   ```

3. **Service-Registration im Gateway**
   ```yaml
   # configs/gateway.yaml
   services:
     newsletter:
       enabled: true
       path_prefix: "/v1/newsletter"
       upstream: "http://127.0.0.1:8083"
       health_check: "/health"
       timeout: 15s
       auth_required: true
       rate_limit:
         requests_per_minute: 60
   ```

### 3.2 Service-API-Design-Standards

1. **Einheitliche Request-Patterns**
   ```go
   // Standard Request-Wrapper
   type APIRequest struct {
       RequestID string                 `json:"request_id,omitempty"`
       Data      interface{}            `json:"data"`
       Meta      map[string]interface{} `json:"meta,omitempty"`
   }
   
   // Standard Response-Wrapper
   type APIResponse struct {
       Success   bool                   `json:"success"`
       Data      interface{}            `json:"data,omitempty"`
       Error     *APIError              `json:"error,omitempty"`
       Meta      map[string]interface{} `json:"meta,omitempty"`
       RequestID string                 `json:"request_id,omitempty"`
   }
   ```

2. **Konsistente Error-Handling**
   ```go
   // Standard Error-Format
   type APIError struct {
       Code    string `json:"code"`
       Message string `json:"message"`
       Details string `json:"details,omitempty"`
   }
   
   // Standard Error-Codes
   const (
       ErrInvalidInput     = "INVALID_INPUT"
       ErrUnauthorized     = "UNAUTHORIZED"
       ErrServiceUnavailable = "SERVICE_UNAVAILABLE"
       ErrRateLimitExceeded = "RATE_LIMIT_EXCEEDED"
   )
   ```

3. **Health-Check-Standards**
   ```go
   // Standard Health-Response
   type HealthStatus struct {
       Status    string            `json:"status"`
       Version   string            `json:"version"`
       Uptime    time.Duration     `json:"uptime"`
       Checks    map[string]string `json:"checks"`
       Timestamp time.Time         `json:"timestamp"`
   }
   
   // Status-Werte
   const (
       HealthStatusHealthy   = "healthy"
       HealthStatusDegraded  = "degraded"
       HealthStatusUnhealthy = "unhealthy"
   )
   ```

### 3.3 Gateway-Integration-Pattern

1. **Service-Discovery-Integration**
   ```go
   // Gateway registriert Services automatisch
   func (g *Gateway) RegisterService(name string, config ServiceConfig) error {
       service := &ServiceProxy{
           Name:        name,
           PathPrefix:  config.PathPrefix,
           Upstream:    config.Upstream,
           HealthCheck: config.HealthCheck,
           // ...
       }
       
       g.services[name] = service
       g.updateRouting()
       return nil
   }
   ```

2. **Request-Middleware-Chain**
   ```go
   // Standard Middleware-Order für alle Services
   func (g *Gateway) buildMiddlewareChain(serviceName string) []Middleware {
       return []Middleware{
           LoggingMiddleware,
           AuthenticationMiddleware,
           RateLimitingMiddleware(serviceName),
           ValidationMiddleware,
           ProxyMiddleware(serviceName),
       }
   }
   ```

## 4. Configuration-Management-Pattern

### 4.1 Hierarchische Konfiguration

```go
// Config-Loading-Reihenfolge
func LoadConfig(serviceName string) (*Config, error) {
    config := &Config{}
    
    // 1. Default-Values
    config.ApplyDefaults()
    
    // 2. Base-Config-File
    config.LoadFromFile("configs/" + serviceName + ".yaml")
    
    // 3. Environment-specific
    if env := os.Getenv("ENVIRONMENT"); env != "" {
        config.LoadFromFile("configs/" + serviceName + "." + env + ".yaml")
    }
    
    // 4. Environment-Variables
    config.LoadFromEnv()
    
    // 5. Command-Line-Flags
    config.LoadFromFlags()
    
    return config.Validate()
}
```

### 4.2 Service-Gateway-Config-Coordination

```yaml
# Gateway-Config für Service
services:
  formular2mail:
    config_sync: true
    config_endpoint: "/config"
    config_push_on_change: true

# Service erhält Config vom Gateway
```

### 4.3 Secrets-Management

```go
// Secrets werden nie in Config-Files gespeichert
type ServiceConfig struct {
    // Public config
    Port     string `yaml:"port"`
    LogLevel string `yaml:"log_level"`
    
    // Secrets via Environment
    APIKey     string `env:"SERVICE_API_KEY"`
    DBPassword string `env:"DB_PASSWORD"`
}
```

## 5. Security-First-Development-Pattern

### 5.1 Authentication-Integration

```go
// Jeder Service-Endpunkt bekommt Auth-Context
type AuthContext struct {
    APIKey      string
    Permissions []string
    ClientIP    string
    UserAgent   string
    RequestID   string
}

func (s *Service) HandleRequest(w http.ResponseWriter, r *http.Request) {
    // Auth-Context wird vom Gateway gesetzt
    authCtx := r.Context().Value("auth").(*AuthContext)
    
    // Service-spezifische Permission-Checks
    if !authCtx.HasPermission("service:" + s.name + ":write") {
        http.Error(w, "Forbidden", http.StatusForbidden)
        return
    }
    
    // ... Service-Logik
}
```

### 5.2 Input-Validation-Standards

```go
// Standard Validation-Middleware
func ValidationMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 1. Content-Type validation
        if !isValidContentType(r.Header.Get("Content-Type")) {
            http.Error(w, "Invalid Content-Type", http.StatusBadRequest)
            return
        }
        
        // 2. Content-Length limits
        if r.ContentLength > MaxRequestSize {
            http.Error(w, "Request too large", http.StatusRequestEntityTooLarge)
            return
        }
        
        // 3. Request-Body validation (service-specific)
        if err := validateRequestBody(r); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        
        next.ServeHTTP(w, r)
    })
}
```

### 5.3 Rate-Limiting-Strategy

```go
// Service-spezifische Rate-Limits
type RateLimitConfig struct {
    RequestsPerMinute int           `yaml:"requests_per_minute"`
    BurstSize         int           `yaml:"burst_size"`
    PerAPIKey         bool          `yaml:"per_api_key"`
    PerIP             bool          `yaml:"per_ip"`
    Whitelist         []string      `yaml:"whitelist"`
}

// Gateway-Level Rate-Limiting
func (g *Gateway) GetRateLimit(serviceName, apiKey, clientIP string) *RateLimit {
    config := g.getRateLimitConfig(serviceName)
    key := buildRateLimitKey(config, apiKey, clientIP)
    return g.rateLimiter.GetLimit(key)
}
```

## 6. Breaking-Change-Management

### 6.1 API-Versionierung-Strategy

```go
// URL-basierte Versionierung
// /v1/mail/send  → formular2mail v1
// /v2/mail/send  → formular2mail v2

// Gateway-Routing für mehrere Versionen
services:
  formular2mail-v1:
    path_prefix: "/v1/mail"
    upstream: "http://127.0.0.1:8081"
  formular2mail-v2:
    path_prefix: "/v2/mail"  
    upstream: "http://127.0.0.1:8084"
```

### 6.2 Backward-Compatibility-Pattern

```go
// Service unterstützt mehrere API-Versionen
func (s *FormularService) HandleRequest(w http.ResponseWriter, r *http.Request) {
    version := extractAPIVersion(r.URL.Path) // v1, v2
    
    switch version {
    case "v1":
        s.handleV1Request(w, r)
    case "v2":  
        s.handleV2Request(w, r)
    default:
        s.handleLatestRequest(w, r)
    }
}
```

### 6.3 Migration-Pattern

```go
// Coordinated Service-Migration
type MigrationPlan struct {
    FromVersion string
    ToVersion   string
    Steps       []MigrationStep
}

type MigrationStep struct {
    Name        string
    Component   string // "gateway" | "service"
    Action      string // "deploy" | "config" | "test"
    Rollback    func() error
}
```

## 7. Checkliste für API-Gateway-Entwicklung

### 7.1 Vor Implementierungsbeginn

- [ ] **Service-Impact analysiert:** Welche Services sind betroffen?
- [ ] **API-Contract definiert:** OpenAPI-Spec erstellt/aktualisiert?
- [ ] **Gateway-Integration geplant:** Routing, Auth, Rate-Limiting?
- [ ] **Config-Strategy festgelegt:** Neue Parameter dokumentiert?
- [ ] **Breaking-Change-Assessment:** Versionierung erforderlich?
- [ ] **Security-Requirements:** Auth, Validation, Rate-Limiting?
- [ ] **Test-Strategy:** Unit, Integration, API-Tests geplant?

### 7.2 Während der Implementierung

- [ ] **Service-Interface-Compliance:** Standard-Interface implementiert?
- [ ] **Error-Handling-Consistency:** Standard-Error-Format verwendet?
- [ ] **Health-Check-Integration:** Standardisierte Health-Endpoint?
- [ ] **Logging-Standards:** Strukturierte Logs mit Request-IDs?
- [ ] **Config-Validation:** Startup-Config-Checks implementiert?
- [ ] **Auth-Integration:** Gateway-Auth-Context respektiert?
- [ ] **Documentation-Update:** API-Docs und Service-Docs aktualisiert?

### 7.3 Nach Implementierungsabschluss

- [ ] **Integration-Tests:** Gateway ↔ Service-Tests bestehen?
- [ ] **API-Contract-Tests:** OpenAPI-Compliance validiert?
- [ ] **Performance-Tests:** Load-Tests mit Gateway durchgeführt?
- [ ] **Security-Tests:** Auth, Input-Validation, Rate-Limiting getestet?
- [ ] **Deployment-Scripts:** Service-Deployment automatisiert?
- [ ] **Monitoring-Integration:** Health-Checks und Metriken?
- [ ] **Documentation-Complete:** Service-Integration dokumentiert?

## 8. Troubleshooting-Pattern

### 8.1 Service-Integration-Debugging

```go
// Standard Debug-Endpoints für Services
func (s *Service) RegisterDebugEndpoints() {
    http.HandleFunc("/debug/config", s.debugConfig)
    http.HandleFunc("/debug/health-detail", s.debugHealthDetail)  
    http.HandleFunc("/debug/metrics", s.debugMetrics)
    http.HandleFunc("/debug/auth", s.debugAuth)
}

// Gateway Debug-Endpoints
func (g *Gateway) RegisterDebugEndpoints() {
    http.HandleFunc("/debug/services", g.debugServices)
    http.HandleFunc("/debug/routing", g.debugRouting)
    http.HandleFunc("/debug/auth-keys", g.debugAuthKeys)
}
```

### 8.2 Request-Tracing

```go
// Request-ID-Propagation durch alle Services
func (g *Gateway) addRequestID(r *http.Request) *http.Request {
    requestID := r.Header.Get("X-Request-ID")
    if requestID == "" {
        requestID = generateRequestID()
    }
    
    // Für Service-Weiterleitung
    r.Header.Set("X-Request-ID", requestID)
    
    // Für Logging
    ctx := context.WithValue(r.Context(), "request_id", requestID)
    return r.WithContext(ctx)
}
```

## 9. Zusammenfassung: API-Gateway-Entwicklungs-Goldene-Regeln

1. **API-Contract-First:** OpenAPI-Spec vor Code-Implementation
2. **Service-Integration-Aware:** Jede Änderung auf Service-Impact prüfen
3. **Security-by-Default:** Auth, Validation, Rate-Limiting bei jedem Endpunkt
4. **Configuration-Hierarchie:** Defaults → Environment → Service-specific
5. **Multi-Layer-Testing:** Unit → Integration → API → E2E
6. **Breaking-Change-Coordination:** Versionierung und Migration planen
7. **Health-Check-Integration:** Jeder Service braucht standardisierten Health-Endpoint
8. **Request-Tracing:** Request-IDs durch gesamte Pipeline propagieren

---

**Wichtiger Hinweis:** Diese Entwicklungs-Pattern sind spezifisch für das Furt API-Gateway-System optimiert und sollten bei jeder Entwicklungsaufgabe konsultiert werden, um konsistente und gut integrierte Services zu gewährleisten.