# TI-Gateway — Benutzerhandbuch

> **⚠️ Dieses Tool ist ein Prototyp und darf NICHT produktiv eingesetzt werden!**
> Alle Daten sind Demo-Daten. Keine echten Versichertendaten, keine gültigen Zertifikate, keine echten Rezepte.

## Was ist das TI-Gateway?

Das TI-Gateway simuliert einen gematik-Konnektor auf deinem lokalen Rechner. Damit kannst du testen, wie Software mit der Telematikinfrastruktur (TI) kommuniziert — ohne echten Konnektor, ohne echte Smartcards, ohne VPN in die TI.

Das Gateway stellt eine SOAP-Schnittstelle bereit (wie ein echter Konnektor) und emuliert virtuelle Smartcards (eGK und SMC-B). Seit Version 0.2.0 enthält es auch eine vollständige **ePA 2.0-Simulation** (Elektronische Patientenakte) mit Dokumentenverwaltung, Berechtigungsprofilen und Medikationsplan. Alles läuft lokal und ist über ein Web-Dashboard steuerbar.

**Typische Anwendungsfälle:**
- SOAP-Schnittstellen eines PVS/KIS gegen den Konnektor testen
- Verstehen, wie ReadVSD, GetCards und andere Konnektor-Operationen funktionieren
- ePA 2.0-Zugriffe simulieren und Berechtigungskonzepte kennenlernen
- Demo-Umgebung für Schulungen aufbauen

## Systemvoraussetzungen

| Komponente | Minimum |
|------------|---------|
| Python | 3.10 oder neuer |
| Betriebssystem | Windows 10/11, Linux, macOS |
| Docker | Optional — nur für den IdP-Server |
| Browser | Aktueller Chrome, Firefox oder Edge |
| Freie Ports | 8500 (HTTP), 4742 (SICCT) |

## Installation

### 1. Python prüfen

Öffne PowerShell und prüfe die Python-Version:

```powershell
python --version
```

Erwartet: `Python 3.10.x` oder höher. Falls nicht installiert: [python.org/downloads](https://www.python.org/downloads/)

### 2. Abhängigkeiten installieren

Wechsle in den Projektordner und installiere die Pakete:

```powershell
cd C:\Users\andre\Projekt\TI-Gateway; pip install -r requirements.txt
```

### 3. Gateway starten

```powershell
python main.py
```

Der Browser öffnet automatisch `http://localhost:8500`. Falls Port 8500 belegt ist, wechselt das Gateway auf 8501 — die Konsole zeigt den tatsächlichen Port.

### 4. Optional: IdP-Server starten

Falls Docker installiert ist:

```powershell
docker compose up -d
```

Das startet den gematik Referenz-IdP-Server auf Port 8571. Ohne Docker bleibt der IdP-Status im Dashboard rot — das ist normal und kein Fehler.

## Dashboard-Übersicht

Nach dem Start siehst du das Dashboard im Browser. Es besteht aus folgenden Bereichen:

### Header und Status-Badges

Oben rechts zeigt **Live** (grüner Punkt) an, dass die SSE-Verbindung zum Server steht. Falls **Getrennt** (roter Punkt) erscheint, lädt die Seite automatisch nach.

Die Statistik-Kacheln zeigen:
- **Karten** — Anzahl eingelegter virtueller Smartcards
- **Slots belegt** — Belegte von 4 verfügbaren Slots
- **Konnektor-Requests** — Anzahl verarbeiteter SOAP-Anfragen in dieser Sitzung
- **TI-2.0-Requests** — Anzahl der Zero-Trust-Anfragen (ZETA, PoPP, VSDM 2.0)

Direkt unter dem Header liegt die **Migrations-Zeitleiste** mit den echten gematik-Stichtagen: RSA-Abschaltung (seit 29.06.2026), PoPP Stufe 1 (seit 30.06.2026), VSDM-2.0-Pilotierung (ab 01.09.2026) und der vollständige TI-2.0-Umbau bis 2029.

### Karten-Slots

Vier Slots für virtuelle Smartcards. Beim Start sind automatisch eingelegt:

| Slot | Karte | Details |
|------|-------|---------|
| 1 | eGK (Max Mustermann) | KVNR: X110501499, IKK classic |
| 2 | SMC-B (IKK Kliniken) | Telematik-ID: 3-SMC-B-Testkarte-... |
| 3 | Leer | — |
| 4 | Leer | — |

Jede Karte zeigt:
- **Kartentyp** — eGK (cyan) oder SMC-B (lila)
- **Name** — Versicherter bzw. Institution
- **KVNR / Telematik-ID** — Identifikationsnummer
- **ICCSN** — Kartennummer (wie aufgedruckt)
- **PIN-Status** — Ob die PIN verifiziert wurde

### Dienste-Status

Fünf Dienste mit Ampel-Anzeige:

| Dienst | Bedeutung wenn grün | Bedeutung wenn rot |
|--------|--------------------|--------------------|
| SOAP-Konnektor | Lokaler SOAP-Handler läuft | Server nicht gestartet |
| SICCT-Terminal | TCP-Server auf Port 4742 aktiv | Port blockiert |
| IdP-Server | Docker-Container erreichbar | Docker nicht gestartet |
| Titus VSDM | gematik-Referenzumgebung erreichbar | Kein Zugang (normal!) |
| ePA 2.0 | Demo-Modus aktiv (immer grün) | — |

**Wichtig:** IdP und Titus sind im Normalfall rot. Das ist erwartetes Verhalten, solange kein Docker läuft bzw. kein Zugang zur gematik-Infrastruktur besteht. Die ePA 2.0 läuft immer im Demo-Modus und ist daher immer grün.

### TI 2.0 — Zero Trust (neue Welt)

Der grüne Bereich zeigt den neuen TI-2.0-Ablauf als vier Schritte, die beim Durchspielen aufleuchten:

1. **ZETA-Registrierung** — Das Primärsystem meldet sich am Policy Decision Point (PDP) an. Die Attestation (Selbstauskunft über die Gerätesicherheit) bestimmt das Device Security Rating.
2. **Access Token** — Der PDP stellt ein OAuth2-Token aus (300 Sekunden gültig, an den Client gebunden).
3. **PoPP-Token** — Der Anwesenheitsnachweis: entweder über die gesteckte eGK oder kartenlos über die GesundheitsID. Ersetzt den alten Prüfungsnachweis.
4. **VSDM 2.0** — Die Stammdaten kommen als FHIR-Bundle direkt vom Fachdienst der Kasse — nicht mehr von der Karte! Dazu gibt es eine Prüfziffer für die Abrechnung.

| Button | Was passiert |
|--------|-------------|
| **Kompletter Ablauf (eGK gesteckt)** | Spielt alle vier Schritte automatisch durch, mit eGK als Anwesenheitsnachweis. |
| **Kompletter Ablauf (GesundheitsID)** | Wie oben, aber kartenlos über die GesundheitsID — so funktioniert Telemedizin in der TI 2.0. |
| **1-4 einzeln** | Jeden Schritt manuell auslösen, um den Ablauf nachzuvollziehen. |
| **Zero-Trust-Demo: Zugriff verweigert** | Registriert ein unsicheres Gerät („Altes Windows-7-PVS") — der PDP lehnt das Token ab, weil das Device Security Rating nicht reicht. Genau das ist Zero Trust. |

Das Ergebnis (Token-Claims, FHIR-Bundle, Prüfziffer) erscheint im Panel unter den Buttons.

**Probier das mal:** Entferne die eGK aus Slot 1 und starte den kompletten Ablauf mit „eGK gesteckt" — der PoPP-Dienst verweigert den Nachweis. Mit „GesundheitsID" klappt es trotzdem, weil dieser Weg keine Karte braucht.

### Test-Aktionen (Konnektor-Welt, Legacy)

Buttons zum Auslösen von Test-Requests:

| Button | Was passiert |
|--------|-------------|
| **eGK lesen (ReadVSD)** | Simuliert einen ReadVSD-SOAP-Request. Liest Versichertenstammdaten der eGK in Slot 1. |
| **Karten auflisten (GetCards)** | Simuliert GetCards. Listet alle gesteckten Karten als SOAP-Response auf. |
| **SMC-B Auth** | Simuliert ExternalAuthenticate mit der SMC-B. Gibt ein Demo-Token zurück. |
| **Titus: VSDM** | Sendet einen echten VSDM-Request an die Titus-Umgebung (benötigt Netzwerkzugang). |
| **IdP: Challenge** | Holt eine Authentication-Challenge vom IdP-Server (benötigt Docker). |
| **eRezept erstellen** | Erstellt ein Demo-E-Rezept (Mock-Daten). |
| **eRezepte auflisten** | Listet Demo-E-Rezepte auf (Mock-Daten). |

**ePA 2.0 — Elektronische Patientenakte:**

| Button | Was passiert |
|--------|-------------|
| **ePA: Aktenstatus** | Zeigt den Status der elektronischen Patientenakte (Version, Dokumentanzahl, Größe). |
| **ePA: Dokumente laden** | Ruft alle Dokumente aus der ePA ab. Die SMC-B wird zur Berechtigungsprüfung verwendet — nicht alle Institutionen sehen alle Dokumente. |
| **ePA: Dokument hochladen** | Lädt ein Demo-Dokument in die ePA hoch. Bleibt bis zum Neustart des Gateways gespeichert. |
| **ePA: Berechtigungen** | Zeigt die Berechtigungsprofile: Welche Institution darf welche Dokumentenkategorien sehen, mit Gültigkeitszeitraum. |
| **ePA: Medikationsplan** | Ruft den Medikationsplan ab mit PZN, Dosierung, Verordner und Grund. |

### Ereignis-Log

Chronologische Liste aller Requests mit:
- **Uhrzeit** — Wann der Request verarbeitet wurde
- **Protokoll** — SOAP (Konnektor-Welt, cyan) oder TI 2.0 (Zero Trust, grün)
- **Operation** — Name der Operation (z.B. ReadVSD, ZETA:Token, PoPP:IssueToken)
- **Status** — OK (grün) oder ERROR (rot)
- **Detail** — Zusätzliche Info oder Fehlermeldung

Der Log zeigt die letzten 50 Einträge und aktualisiert sich in Echtzeit.

## Eigene Karten erstellen

Du kannst eigene Testkarten erstellen, indem du eine JSON-Datei im Ordner `cards/` anlegst. Der Dateiname muss auf `_demo.json` enden.

### eGK erstellen

Erstelle z.B. `cards/erika_demo.json`:

```json
{
  "card_type": "eGK",
  "generation": "2+",
  "iccsn": "80276883110000000099",
  "pin": "123456",
  "versicherter": {
    "vorname": "Erika",
    "nachname": "Musterfrau",
    "geburtsdatum": "1990-07-20",
    "geschlecht": "W",
    "strasse": "Beispielweg 7",
    "plz": "10115",
    "ort": "Berlin",
    "land": "D"
  },
  "versicherung": {
    "kvnr": "X110501500",
    "versicherten_id": "X110501500",
    "kostentraeger": "109519005",
    "kostentraeger_name": "IKK classic",
    "kostentraeger_laendercode": "D",
    "versicherungsschutz_beginn": "2021-01-01",
    "versicherungsschutz_ende": "2099-12-31",
    "versichertenart": "1",
    "besondere_personengruppe": "00",
    "dmp_kennzeichen": "00",
    "wop": "38"
  }
}
```

### SMC-B erstellen

Erstelle z.B. `cards/praxis_demo.json`:

```json
{
  "card_type": "SMC-B",
  "iccsn": "80276883120000000099",
  "pin": "654321",
  "institution": {
    "name": "Praxis Dr. Beispiel",
    "telematik_id": "3-SMC-B-Testkarte-000000099",
    "institution_typ": "Arztpraxis",
    "betriebsstaetten_nr": "987654321"
  },
  "zertifikate": {
    "auth": {
      "algorithm": "ECC",
      "not_before": "2024-01-01T00:00:00",
      "not_after": "2029-12-31T23:59:59",
      "issuer": "gematik GmbH NOT-VALID (Demo)"
    }
  }
}
```

**Wichtig:** Die `iccsn` muss eindeutig sein. Beim nächsten Start wird die Karte automatisch geladen. Neue eGK-Dateien landen in Slot 1, SMC-B in Slot 2 (überschreibt die vorherige Karte in dem Slot). Karten lassen sich auch über die REST-API in beliebige Slots einlegen.

## SOAP-Schnittstelle testen

### Mit PowerShell (Invoke-WebRequest)

**ReadVSD — eGK-Daten lesen:**

```powershell
$body = @"
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <ReadVSD_Request xmlns="http://ws.gematik.de/conn/vsds/VSDService/v5.2">
      <Context>
        <MandantId>Mandant1</MandantId>
        <ClientSystemId>CS1</ClientSystemId>
        <WorkplaceId>WP1</WorkplaceId>
      </Context>
    </ReadVSD_Request>
  </soap:Body>
</soap:Envelope>
"@

Invoke-WebRequest -Uri "http://localhost:8500/soap" -Method POST -ContentType "application/soap+xml; charset=utf-8" -Body $body | Select-Object -ExpandProperty Content
```

**GetCards — Alle Karten auflisten:**

```powershell
$body = @"
<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <GetCards_Request xmlns="http://ws.gematik.de/conn/CardService/v8.1">
      <Context><MandantId>Mandant1</MandantId></Context>
    </GetCards_Request>
  </soap:Body>
</soap:Envelope>
"@

Invoke-WebRequest -Uri "http://localhost:8500/soap" -Method POST -ContentType "application/soap+xml; charset=utf-8" -Body $body | Select-Object -ExpandProperty Content
```

### Mit curl (Git Bash / Linux)

```bash
curl -X POST http://localhost:8500/api/test/read-vsd
curl -X POST http://localhost:8500/api/test/get-cards
curl http://localhost:8500/api/status | python -m json.tool
```

## Häufige Fragen (FAQ)

### Warum sind IdP und Titus im Dashboard rot?

Das ist normal. Der IdP-Server läuft nur, wenn Docker gestartet ist (`docker compose up -d`). Titus ist die gematik-Referenzumgebung und nur mit speziellem Netzwerkzugang erreichbar. Für lokale Tests brauchst du beides nicht — die SOAP-Schnittstelle und Karten-Emulation funktionieren unabhängig davon.

### Was ist der Unterschied zwischen Konnektor-Welt und TI 2.0?

In der alten Welt liest der Konnektor die Versichertenstammdaten direkt von der eGK (die Karte ist der Datenspeicher). In der TI 2.0 beweist die Karte nur noch, dass der Patient da war (PoPP-Token), und die Daten kommen aktuell und direkt vom Fachdienst der Krankenkasse (VSDM 2.0, FHIR). Dazu kommt Zero Trust: Statt einmal per VPN „drin" zu sein, wird jeder einzelne Zugriff vom ZETA Guard geprüft. Die gematik stellt die echte TI bis 2029 komplett darauf um — das Dashboard zeigt beide Welten parallel, genau wie der echte Übergangsbetrieb.

### Kann ich das produktiv nutzen?

**Nein.** Das Gateway ist ein Prototyp zu Lern- und Testzwecken. Es emuliert keine echte Kryptografie, hat keine TLS-Verschlüsselung und verwendet Demo-Daten. Für den Produktivbetrieb brauchst du einen zugelassenen gematik-Konnektor.

### Was ist SICCT?

SICCT (Secure Interoperable ChipCard Terminal) ist das Protokoll, über das Kartenterminals mit dem Konnektor kommunizieren. Das Gateway emuliert ein solches Terminal auf TCP-Port 4742. Damit kann Software, die direkt mit Kartenterminals spricht, gegen den Prototypen getestet werden.

### Wie verbinde ich ein echtes Kartenterminal?

Das Gateway unterstützt keine echten Kartenterminals. Es emuliert selbst ein virtuelles Terminal. Für echte Terminals brauchst du einen zugelassenen Konnektor.

### Was ist die PIN der Demo-Karten?

Die Standard-PIN für alle Demo-Karten ist `123456`. Du kannst sie in den JSON-Dateien unter `cards/` ändern.

### Was ist die ePA 2.0 im TI-Gateway?

Die ePA 2.0 (Elektronische Patientenakte) ist seit Version 0.2.0 im TI-Gateway enthalten. Sie simuliert eine vollständige Aktenumgebung mit:

- **6 Demo-Dokumenten** — Arztbriefe, Laborbefunde, Medikationsplan, Impfausweis, psychiatrische Stellungnahme
- **Feingranulare Zugriffskontrolle** — Nicht jede Institution sieht alle Dokumente. Die Praxis Weber sieht z.B. nur Psychiatrie-Dokumente.
- **Medikationsplan** — 3 Medikamente mit PZN, Dosierung und Verordner
- **Berechtigungsprofile** — 3 Institutionen mit unterschiedlichen Zugriffsrechten und Gültigkeitszeiträumen

Die ePA läuft komplett lokal im Demo-Modus — kein externer Dienst nötig. Hochgeladene Dokumente bleiben bis zum Neustart des Gateways gespeichert.

### Kann ich mehrere eGK gleichzeitig einlegen?

Ja, über die REST-API. Es stehen 4 Slots zur Verfügung. Die SOAP-Operationen wie ReadVSD verwenden allerdings immer die erste gefundene eGK.

```powershell
# Karte in Slot 3 einlegen
Invoke-WebRequest -Uri "http://localhost:8500/api/cards/3/insert" -Method POST -ContentType "application/json" -Body (Get-Content cards/egk_demo.json -Raw)
```

## Troubleshooting

### Port 8500 ist belegt

Das Gateway erkennt das automatisch und wechselt auf Port 8501. In der Konsole steht:

```
Port 8500 belegt — versuche 8501
```

Falls auch 8501 belegt ist, beende den anderen Prozess:

```powershell
# Prüfen welcher Prozess den Port belegt
netstat -ano | findstr :8500
# Prozess beenden (PID aus der letzten Spalte)
taskkill /PID <PID> /F
```

### Python nicht gefunden

Stelle sicher, dass Python im PATH ist:

```powershell
# Python-Pfad prüfen
where python
```

Falls nicht gefunden: Python neu installieren und dabei **"Add Python to PATH"** aktivieren.

### pip install schlägt fehl

Versuche es mit dem `--user` Flag:

```powershell
pip install --user -r requirements.txt
```

Oder nutze ein Virtual Environment:

```powershell
python -m venv .venv; .\.venv\Scripts\Activate.ps1; pip install -r requirements.txt
```

### SICCT-Port 4742 blockiert

Falls ein anderer Dienst Port 4742 belegt, startet der SICCT-Server nicht. In der Konsole erscheint:

```
SICCT-Server konnte nicht starten: [Errno 10048] ...
```

Lösung: Den blockierenden Prozess beenden oder den Port in `config.json` ändern (`sicct_port`).

### Docker-Fehler beim IdP-Server

```powershell
# Docker-Status prüfen
docker info

# Container-Logs ansehen
docker compose logs idp-server

# Neustart
docker compose down; docker compose up -d
```

### Dashboard zeigt "Getrennt"

Die SSE-Verbindung ist unterbrochen. Mögliche Ursachen:
- Der Python-Server wurde beendet → Neu starten mit `python main.py`
- Browser-Tab war lange inaktiv → Seite neu laden (F5)