# 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 drei Statistik-Kacheln zeigen:
- **Karten** — Anzahl eingelegter virtueller Smartcards
- **Slots belegt** — Belegte von 4 verfügbaren Slots
- **SOAP Requests** — Anzahl verarbeiteter SOAP-Anfragen in dieser Sitzung

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

### Test-Aktionen

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

### SOAP-Log

Chronologische Liste aller SOAP-Requests mit:
- **Uhrzeit** — Wann der Request verarbeitet wurde
- **Operation** — Name der SOAP-Operation (z.B. ReadVSD, GetCards)
- **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.

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