breakpilot-compliance/docs-src/services/sdk-modules/freigabe-module.md

# Freigabe-Module (Paket 2): Import, Screening, Modules, Quellen

Dieses Paket bringt vier SDK-Module auf Produktionsreife: Document Import (CP-IMP), System Screening (CP-SCR), Service Module Registry (CP-MOD) und RAG/Quellen-Verwaltung (CP-RAG).

---

## CP-IMP — Document Import & Gap-Analyse

**URL:** `/sdk/import`
**Backend:** `backend-compliance:8002/v1/import/...` (direkt in `main.py` registriert)

### Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `POST` | `/v1/import/analyze` | Dokument hochladen, Typ erkennen, Gap-Analyse durchführen |
| `GET` | `/v1/import/documents` | Alle importierten Dokumente eines Tenants |
| `GET` | `/v1/import/gap-analysis/{document_id}` | Gap-Analyse für ein bestimmtes Dokument abrufen |

### POST /v1/import/analyze

```http
POST /v1/import/analyze
Content-Type: multipart/form-data

file: <binary>
document_type: "OTHER"   # Optional; "OTHER" → automatische Erkennung
tenant_id: "<uuid>"
```

**Response (200):**
```json
{
  "document_id": "uuid",
  "filename": "dsfa.pdf",
  "detected_type": "DSFA",
  "confidence": 0.85,
  "extracted_entities": ["DSGVO", "AI Act"],
  "recommendations": ["Risikoklassifizierung ergänzen"],
  "gap_analysis": {
    "id": "analysis-abc123",
    "total_gaps": 2,
    "critical_gaps": 1,
    "high_gaps": 1,
    "medium_gaps": 0,
    "low_gaps": 0,
    "gaps": [...],
    "recommended_packages": ["analyse", "dokumentation"]
  }
}
```

**Unterstützte Dokument-Typen:** `DSFA`, `TOM`, `VVT`, `PRIVACY_POLICY`, `AGB`, `COOKIE_POLICY`, `RISK_ASSESSMENT`, `AUDIT_REPORT`, `OTHER`

**Erkennung:** Keyword-Matching (Fallback) + optionale Klassifikation via LLM (`COMPLIANCE_LLM_MODEL`).

### GET /v1/import/gap-analysis/{document_id}

Gibt die gespeicherte Gap-Analyse für ein zuvor analysiertes Dokument zurück.

**Errors:**
- `404`: Kein Gap-Analyse-Eintrag für `document_id` im angegebenen Tenant

---

## CP-SCR — System Screening (SBOM + Vulnerability Scan)

**URL:** `/sdk/screening`
**Backend:** `backend-compliance:8002/v1/screening/...` (direkt in `main.py` registriert)

### Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `POST` | `/v1/screening/scan` | Dependency-Datei hochladen, SBOM generieren, CVE-Scan via OSV.dev |
| `GET` | `/v1/screening/{screening_id}` | Scan-Ergebnis abrufen |
| `GET` | `/v1/screening` | Alle Scans eines Tenants auflisten |

### POST /v1/screening/scan

**Unterstützte Dateiformate:** `package-lock.json`, `requirements.txt`, `yarn.lock`

```http
POST /v1/screening/scan
Content-Type: multipart/form-data

file: requirements.txt
tenant_id: "<uuid>"
```

**Response (200):**
```json
{
  "id": "uuid",
  "status": "completed",
  "sbom_format": "CycloneDX",
  "sbom_version": "1.5",
  "total_components": 47,
  "total_issues": 3,
  "critical_issues": 0,
  "high_issues": 2,
  "medium_issues": 1,
  "low_issues": 0,
  "components": [...],
  "issues": [
    {
      "id": "uuid",
      "severity": "HIGH",
      "title": "Remote Code Execution in lodash",
      "cve": "CVE-2024-0001",
      "cvss": 7.5,
      "affected_component": "lodash",
      "affected_version": "4.17.20",
      "fixed_in": "4.17.21",
      "remediation": "Upgrade lodash to 4.17.21",
      "status": "OPEN"
    }
  ]
}
```

**Errors:**
- `400`: Datei konnte nicht geparsed werden oder ist kein unterstütztes Format
- `422`: Kein File im Request

---

## CP-MOD — Service Module Registry

**URL:** `/sdk/modules`
**Backend:** `backend-compliance:8002/api/compliance/modules/...` (via `__init__.py` registriert)

### Endpoints

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/modules` | Alle Service-Module auflisten (Filter: `service_type`, `criticality`, `processes_pii`, `ai_components`) |
| `GET` | `/modules/overview` | Aggregierte Statistiken aller Module |
| `GET` | `/modules/{module_id}` | Modul-Details inkl. Regulierungen und Risiken |
| `POST` | `/modules/seed` | Module aus Stammdaten einspielen |
| `POST` | `/modules/{module_id}/activate` | Modul aktivieren |
| `POST` | `/modules/{module_id}/deactivate` | Modul deaktivieren |
| `POST` | `/modules/{module_id}/regulations` | Regulierungs-Mapping hinzufügen |

### DB-Migration

```bash
# Tabellen anlegen (Migration 031):
ssh macmini "/usr/local/bin/docker exec bp-compliance-backend \
  python3 /app/migrations/run_migration.py 031_modules.sql"
```

**Tabellen:**
- `compliance_service_modules` — Service-Modul-Registry
- `compliance_module_regulations` — Modul ↔ Regulierungs-Mappings
- `compliance_module_risks` — Modul-spezifische Risikobewertungen

### Detail-Seite

Die Detail-Seite unter `/sdk/modules/{moduleId}` zeigt:
- Modul-Header: Name, Typ-Badge, Active-Badge, Compliance-Score
- Anforderungen (Requirements)
- Kontrollen (Controls)
- Zugeordnete Regulierungen

---

## CP-RAG — Quellen & Regulierungs-Suche

**URL:** `/sdk/rag`
**Backend:** `ai-compliance-sdk:8090/...` (Proxy: `/api/sdk/v1/rag/[[...path]]`)

### Endpoints (via AI Compliance SDK)

| Methode | Pfad | Beschreibung |
|---------|------|--------------|
| `GET` | `/regulations` | Alle verfügbaren Regulierungen auflisten |
| `POST` | `/search` | Semantische Suche in Regulierungstexten |

### POST /search

```json
{
  "query": "Datenschutz-Folgenabschätzung Pflicht",
  "corpus": "bp_dsfa_corpus",
  "top_k": 5
}
```

**Response:**
```json
{
  "results": [
    {
      "id": "uuid",
      "text": "Art. 35 DSGVO – Datenschutz-Folgenabschätzung...",
      "score": 0.92,
      "metadata": {
        "source": "DSGVO",
        "article": "Art. 35"
      }
    }
  ]
}
```

**Corpora:** `bp_dsfa_corpus` (alle 16 Bundesländer + BfDI + WP248), weitere via RAG-Ingest-Script.

---

## Tests & Verifikation

```bash
# Import-Routen (inkl. API-Endpoint-Tests)
cd backend-compliance && python3 -m pytest tests/test_import_routes.py -v

# Screening-Routen (inkl. API-Endpoint-Tests)
cd backend-compliance && python3 -m pytest tests/test_screening_routes.py -v

# Module-Registry
cd backend-compliance && python3 -m pytest tests/test_module_routes.py -v
```