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

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

2. Validierung der Service-Daten

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:

python -m compliance.scripts.seed_service_modules --mode modules

Vollständige Compliance-DB:

python -m compliance.scripts.seed_service_modules --mode all

API-Integration

Bestehende Endpoints erweitern

Die Service-Module sind bereits im Datenmodell integriert:

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

@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:

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

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)

// 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:

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

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

# 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

# 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

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

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

Seeding-Fehler

# 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

# 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