breakpilot-pwa/backend/compliance/SPRINT3_INTEGRATION.md

# Sprint 3 Integration Guide - Service Module Registry

## Übersicht

Sprint 3 erweitert das Compliance-Modul um eine vollständige Service-Registry mit:
- 30+ dokumentierte Breakpilot Services
- Service ↔ Regulation Mappings
- Automatisches Seeding
- Validierung und Statistiken

## Dateien

### Neue/Aktualisierte Dateien

```
backend/compliance/
├── data/
│   ├── service_modules.py          (AKTUALISIERT - +4 neue Services)
│   └── README.md                    (NEU - Dokumentation)
├── services/
│   └── seeder.py                    (AKTUALISIERT - Service-Seeding)
└── scripts/
    ├── __init__.py                  (NEU)
    ├── seed_service_modules.py      (NEU - Seeding-Script)
    └── validate_service_modules.py  (NEU - Validierung)
```

## Neue Services

Folgende Services wurden zu `service_modules.py` hinzugefügt:

1. **dsms-node** (Port 5001) - IPFS Dezentralspeicher
2. **dsms-gateway** (Port 8082) - DSMS REST API
3. **mailpit** (Port 8025) - Dev Mail Server
4. **backup** - PostgreSQL Backup Service
5. **breakpilot-drive** (Port 3001) - Unity WebGL Game
6. **camunda** (Port 8089) - BPMN Workflow Engine

## Installation & Setup

### 1. Datenbank-Migration

```bash
cd backend
alembic revision --autogenerate -m "Add service module registry"
alembic upgrade head
```

### 2. Validierung der Service-Daten

```bash
python -m compliance.scripts.validate_service_modules
```

Erwartete Ausgabe:
```
=== Validating Required Fields ===
✓ All services have required fields

=== Checking Port Conflicts ===
✓ No port conflicts detected

=== Validating Regulation Mappings ===
✓ All regulation mappings are valid

=== Service Module Statistics ===
Total Services: 30+
...
```

### 3. Seeding

Nur Service-Module:
```bash
python -m compliance.scripts.seed_service_modules --mode modules
```

Vollständige Compliance-DB:
```bash
python -m compliance.scripts.seed_service_modules --mode all
```

## API-Integration

### Bestehende Endpoints erweitern

Die Service-Module sind bereits im Datenmodell integriert:

```python
# compliance/db/models.py
class ServiceModuleDB(Base):
    __tablename__ = 'compliance_service_modules'
    # ... bereits definiert

class ModuleRegulationMappingDB(Base):
    __tablename__ = 'compliance_module_regulations'
    # ... bereits definiert
```

### Neue API-Endpoints (Optional)

Füge zu `compliance/api/routes.py` hinzu:

```python
@router.get("/modules", response_model=List[ServiceModuleSchema])
async def list_service_modules(
    db: Session = Depends(get_db),
    service_type: Optional[str] = None,
    processes_pii: Optional[bool] = None,
):
    """List all service modules with optional filtering."""
    query = db.query(ServiceModuleDB)

    if service_type:
        query = query.filter(ServiceModuleDB.service_type == service_type)
    if processes_pii is not None:
        query = query.filter(ServiceModuleDB.processes_pii == processes_pii)

    return query.all()


@router.get("/modules/{module_id}", response_model=ServiceModuleDetailSchema)
async def get_service_module(
    module_id: str,
    db: Session = Depends(get_db),
):
    """Get detailed information about a service module."""
    module = db.query(ServiceModuleDB).filter(
        ServiceModuleDB.id == module_id
    ).first()

    if not module:
        raise HTTPException(status_code=404, detail="Service module not found")

    return module


@router.get("/modules/{module_id}/regulations")
async def get_module_regulations(
    module_id: str,
    db: Session = Depends(get_db),
):
    """Get all applicable regulations for a service."""
    mappings = db.query(ModuleRegulationMappingDB).filter(
        ModuleRegulationMappingDB.module_id == module_id
    ).all()

    return mappings
```

### Schemas hinzufügen

Füge zu `compliance/api/schemas.py` hinzu:

```python
from pydantic import BaseModel
from typing import List, Optional

class ServiceModuleSchema(BaseModel):
    id: str
    name: str
    display_name: str
    service_type: str
    port: Optional[int]
    processes_pii: bool
    ai_components: bool
    criticality: str

    class Config:
        from_attributes = True


class ServiceModuleDetailSchema(ServiceModuleSchema):
    description: Optional[str]
    technology_stack: List[str]
    data_categories: List[str]
    owner_team: Optional[str]
    compliance_score: Optional[float]

    class Config:
        from_attributes = True
```

## Verwendung im Code

### Python

```python
from compliance.data.service_modules import (
    BREAKPILOT_SERVICES,
    get_service_count,
    get_services_by_type,
    get_services_processing_pii,
)

# Alle KI-Services finden
ai_services = get_services_with_ai()
for service in ai_services:
    print(f"{service['name']}: {service['regulations']}")

# Services mit kritischer GDPR-Relevanz
from compliance.db.models import ServiceModuleDB, ModuleRegulationMappingDB
from classroom_engine.database import SessionLocal

db = SessionLocal()
critical_gdpr = db.query(ServiceModuleDB).join(
    ModuleRegulationMappingDB
).filter(
    ModuleRegulationMappingDB.relevance_level == "critical"
).all()
```

### Frontend (React/Next.js)

```typescript
// Fetch all service modules
const modules = await fetch('/api/compliance/modules').then(r => r.json());

// Filter AI services
const aiServices = modules.filter(m => m.ai_components);

// Get regulations for a service
const regulations = await fetch(
  `/api/compliance/modules/${moduleId}/regulations`
).then(r => r.json());
```

## Testing

### Unit Tests

Beispiel für `backend/tests/test_service_modules.py`:

```python
import pytest
from compliance.data.service_modules import (
    get_service_count,
    get_services_by_type,
    get_critical_services,
)

def test_service_count():
    """Test that we have all expected services."""
    count = get_service_count()
    assert count >= 30, "Should have at least 30 services"


def test_critical_services():
    """Test that critical services are properly marked."""
    critical = get_critical_services()
    critical_names = [s['name'] for s in critical]

    assert 'consent-service' in critical_names
    assert 'postgresql' in critical_names
    assert 'vault' in critical_names


def test_ai_services_have_regulations():
    """Test that all AI services have AI Act regulations."""
    from compliance.data.service_modules import get_services_with_ai

    ai_services = get_services_with_ai()
    for service in ai_services:
        regulation_codes = [r['code'] for r in service['regulations']]
        assert 'AIACT' in regulation_codes or 'GDPR' in regulation_codes
```

### Integration Test

```python
def test_seeder_creates_modules(db_session):
    """Test that seeder creates service modules."""
    from compliance.services.seeder import ComplianceSeeder

    seeder = ComplianceSeeder(db_session)
    result = seeder.seed_service_modules_only()

    assert result > 0

    # Verify consent-service was created
    from compliance.db.models import ServiceModuleDB
    module = db_session.query(ServiceModuleDB).filter(
        ServiceModuleDB.name == "consent-service"
    ).first()

    assert module is not None
    assert module.port == 8081
    assert module.processes_pii == True
```

## Maintenance

### Neue Services hinzufügen

1. Service zu `BREAKPILOT_SERVICES` in `service_modules.py` hinzufügen
2. Validierung ausführen: `python -m compliance.scripts.validate_service_modules`
3. Re-seeding: `python -m compliance.scripts.seed_service_modules`

### Service aktualisieren

```python
# Via API (wenn implementiert)
PATCH /api/compliance/modules/{module_id}
{
    "port": 8082,
    "technology_stack": ["Python", "FastAPI", "IPFS"]
}

# Oder via Code
from compliance.db.models import ServiceModuleDB
from classroom_engine.database import SessionLocal

db = SessionLocal()
module = db.query(ServiceModuleDB).filter(
    ServiceModuleDB.name == "dsms-gateway"
).first()

module.port = 8082
db.commit()
```

## Monitoring & Reporting

### Compliance-Score pro Service

```python
# Zukünftige Implementierung
def calculate_service_compliance_score(module_id: str) -> float:
    """
    Berechnet Compliance-Score basierend auf:
    - Anzahl erfüllter Requirements
    - Implementierungsstatus der Controls
    - Kritikalität der offenen Gaps
    """
    # TODO: Implementierung
    pass
```

### Gap-Analyse

```sql
-- Services mit offenen kritischen GDPR-Requirements
SELECT
    sm.name,
    sm.display_name,
    COUNT(r.id) as open_requirements
FROM compliance_service_modules sm
JOIN compliance_module_regulations mr ON sm.id = mr.module_id
JOIN compliance_regulations reg ON mr.regulation_id = reg.id
JOIN compliance_requirements r ON r.regulation_id = reg.id
WHERE reg.code = 'GDPR'
  AND r.implementation_status != 'implemented'
  AND r.priority = 1
GROUP BY sm.id, sm.name, sm.display_name
ORDER BY open_requirements DESC;
```

## Troubleshooting

### Import-Fehler

```bash
# Stelle sicher, dass der Python-Path korrekt ist
export PYTHONPATH="${PYTHONPATH}:/Users/benjaminadmin/Projekte/breakpilot-pwa/backend"
```

### Seeding-Fehler

```bash
# Prüfe Datenbankverbindung
python -c "from classroom_engine.database import SessionLocal; db = SessionLocal(); print('DB OK')"

# Prüfe, ob Regulations bereits geseedet sind
python -m compliance.scripts.seed_service_modules --mode all
```

### Port-Konflikte

```bash
# Validierung zeigt Port-Konflikte
python -m compliance.scripts.validate_service_modules

# Konflikte manuell in service_modules.py beheben
```

## Nächste Schritte (Sprint 4+)

- [ ] Compliance-Score Berechnung implementieren
- [ ] Automatische Gap-Analyse
- [ ] Dashboard für Service-Overview
- [ ] CI/CD Integration (Auto-Validierung)
- [ ] Service-Health-Checks integrieren
- [ ] Abhängigkeits-Graph visualisieren