# Dokumenten-Import: Anleitung

Diese Anleitung beschreibt, wie Dokumente und Vorgaben mittels des `import-document` Management Commands in die VorgabenUI importiert werden können.

## Übersicht

Der `import-document` Command ermöglicht es, strukturierte Textdateien zu importieren, die Dokumente mit Einleitung, Geltungsbereich und Vorgaben enthalten. Das Format ist speziell für die einfache Erfassung und Pflege von IT-Sicherheitsstandards konzipiert.

## Grundlegende Verwendung

### Minimaler Aufruf

```bash
python manage.py import-document <dateipfad> \
  --nummer <dokumentnummer> \
  --name "<dokumentname>" \
  --dokumententyp "<typ>"
```

### Beispiel

```bash
python manage.py import-document Documentation/import\ formats/r009.txt \
  --nummer "R0009" \
  --name "Serversysteme" \
  --dokumententyp "Standard IT-Sicherheit"
```

## Parameter

### Pflichtparameter

| Parameter | Beschreibung | Beispiel |
|-----------|--------------|----------|
| `file_path` | Pfad zur Importdatei | `Documentation/import formats/r009.txt` |
| `--nummer` | Dokumentnummer (eindeutig) | `R0009`, `R0066` |
| `--name` | Dokumentname | `"Logging"`, `"Serversysteme"` |
| `--dokumententyp` | Dokumententyp (muss bereits existieren) | `"Standard IT-Sicherheit"` |

### Optionale Parameter

| Parameter | Beschreibung | Verwendung |
|-----------|--------------|------------|
| `--gueltigkeit_von` | Startdatum der Gültigkeit | `--gueltigkeit_von 2024-01-01` |
| `--gueltigkeit_bis` | Enddatum der Gültigkeit | `--gueltigkeit_bis 2025-12-31` |
| `--dry-run` | Testlauf ohne Datenbankänderungen | `--dry-run` |
| `--verbose` | Ausführliche Ausgabe (mit `--dry-run`) | `--dry-run --verbose` |
| `--purge` | Löscht bestehende Einleitung/Geltungsbereich/Vorgaben vor Import | `--purge` |

### Dry-Run Modus

Der Dry-Run Modus ist zum Testen gedacht:

```bash
python manage.py import-document r009.txt \
  --nummer "R0009" \
  --name "Serversysteme" \
  --dokumententyp "Standard IT-Sicherheit" \
  --dry-run --verbose
```

Dies zeigt an, was importiert würde, ohne die Datenbank zu ändern.

### Purge Modus

**Achtung:** Der Purge-Modus löscht alle bestehenden Vorgaben des Dokuments!

```bash
python manage.py import-document r009.txt \
  --nummer "R0009" \
  --name "Serversysteme" \
  --dokumententyp "Standard IT-Sicherheit" \
  --purge
```

Mit `--dry-run --purge` kann zuerst geprüft werden, was gelöscht würde.

## Dateiformat

### Grundstruktur

Die Importdatei ist eine Textdatei (UTF-8 kodiert) mit speziellen Trennzeichen `>>>` am Zeilenanfang.

### Aufbau

```
>>>Einleitung
>>>text
[Einleitungstext]

>>>Geltungsbereich
>>>text
[Geltungsbereichstext]

>>>Vorgabe [Thema]
>>>Nummer [nummer]
>>>Titel
[Titel der Vorgabe]
>>>Kurztext
>>>Text
[Kurztext-Inhalt]
>>>Langtext
>>>Text
[Langtext-Inhalt]
>>>Stichworte
[Stichwort1, Stichwort2, ...]
>>>Checkliste
[Frage 1]
[Frage 2]
```

### Abschnitt-Trenner

Jeder Abschnitt beginnt mit `>>>` gefolgt vom Abschnittstyp:

- `>>>Einleitung` - Startet den Einleitungsbereich
- `>>>Geltungsbereich` - Startet den Geltungsbereichsbereich
- `>>>Vorgabe [Thema]` - Startet eine neue Vorgabe mit angegebenem Thema

### Abschnitttypen für Textinhalte

Nach `>>>Einleitung`, `>>>Geltungsbereich`, `>>>Kurztext` oder `>>>Langtext` folgt ein Abschnitttyp:

| Typ | Verwendung | Beispiel |
|-----|------------|----------|
| `>>>text` oder `>>>Text` | Normaler Fliesstext | `>>>text` |
| `>>>liste geordnet` oder `>>>Liste geordnet` | Nummerierte Liste | `>>>Liste geordnet` |
| `>>>liste ungeordnet` oder `>>>Liste ungeordnet` | Aufzählungsliste | `>>>liste ungeordnet` |

**Hinweis:** Gross-/Kleinschreibung und Bindestriche (`liste-ungeordnet`) werden normalisiert.

## Beispiele

### Beispiel 1: Einfaches Dokument mit einer Vorgabe

```
>>>Einleitung
>>>text
Dieser Standard definiert Anforderungen für XYZ.

>>>Geltungsbereich
>>>text
Dieser Standard gilt für alle Systeme im BIT.

>>>Vorgabe Technik
>>>Nummer 1
>>>Titel
Verschlüsselung verwenden
>>>Kurztext
>>>Text
Alle Verbindungen müssen verschlüsselt sein.
>>>Langtext
>>>Text
Die Verschlüsselung muss mindestens TLS 1.2 verwenden.
Es sind folgende Cipher Suites erlaubt:
>>>Liste ungeordnet
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
>>>Stichworte
Verschlüsselung, TLS, Kryptographie
>>>Checkliste
TLS 1.2 oder höher ist konfiguriert
Schwache Cipher Suites sind deaktiviert
```

### Beispiel 2: Mehrere Vorgaben mit gleichem Thema

```
>>>Vorgabe Organisation
>>>Nummer 1
>>>Titel
CMDB-Erfassung
>>>Kurztext
>>>Text
Alle Assets müssen in der CMDB erfasst sein.
>>>Langtext
>>>Text
Jedes Asset muss dokumentiert werden...

>>>Vorgabe Organisation
>>>Nummer 2
>>>Titel
Verantwortlichkeiten
>>>Kurztext
>>>Text
Verantwortlichkeiten müssen definiert sein.
>>>Langtext
>>>Text
Für jedes System muss ein Verantwortlicher...
```

### Beispiel 3: Verschiedene Themen

```
>>>Vorgabe Technik
>>>Nummer 1
>>>Titel
Firewall-Konfiguration
>>>Kurztext
>>>Text
Lokale Firewall muss aktiviert sein.
>>>Langtext
>>>Text
Details zur Firewall-Konfiguration...

>>>Vorgabe Organisation
>>>Nummer 1
>>>Titel
Dokumentation
>>>Kurztext
>>>Text
Konfiguration muss dokumentiert sein.
>>>Langtext
>>>Text
Die Firewall-Regeln müssen...

>>>Vorgabe Informationen
>>>Nummer 1
>>>Titel
Datenklassifizierung
>>>Kurztext
>>>Text
Daten müssen klassifiziert werden.
>>>Langtext
>>>Text
Klassifizierungsstufen sind...
```

### Beispiel 4: Mehrere Textabschnitte

```
>>>Vorgabe Technik
>>>Nummer 1
>>>Titel
Komplexe Anforderung
>>>Kurztext
>>>Text
Erste Zusammenfassung.
>>>Langtext
>>>Text
Erster Absatz mit Details.
>>>Text
Zweiter Absatz mit weiteren Informationen.
>>>Liste ungeordnet
Punkt 1
Punkt 2
Punkt 3
>>>Text
Abschliessender Text nach der Liste.
```

## Vorgaben-Struktur

### Vorgabe-Header

```
>>>Vorgabe [Thema]
```

Das Thema muss in der Datenbank bereits als `Thema`-Objekt existieren. Die bestehenden Themen sind - wie in den bestehenden Standards - aus dem IT-Grundschutz übernommen:
- Organisation
- Technik
- Informationen
- Systeme
- Anwendungen
- Zonen

### Vorgabe-Felder

#### Nummer (Pflicht)

```
>>>Nummer 1
```

oder inline:

Die Nummer wird als Integer gespeichert. Sie ist nicht eindeutig innerhalb eines Dokuments und Themas. Wenn mehrere Vorgaben im selben Thema mit der selben Nummer vorkommen, darf sich der Geltungszeitraum der Vorgaben nicht überschneiden (wird beim Import geprüft).

#### Titel (Pflicht)

```
>>>Titel
Titel der Vorgabe
```

oder inline:

```
>>>Titel: Titel der Vorgabe
```

#### Kurztext (Optional)

```
>>>Kurztext
>>>Text
Kurze Zusammenfassung der Vorgabe.
```

#### Langtext (Optional)

```
>>>Langtext
>>>Text
Ausführliche Beschreibung der Vorgabe.
>>>Liste ungeordnet
Punkt 1
Punkt 2
```

#### Stichworte (Optional)

Komma-getrennte Liste:

```
>>>Stichworte
Firewall, Netzwerk, Sicherheit
```

**Hinweis:** Stichworte werden automatisch in der Datenbank angelegt, falls sie noch nicht existieren.

#### Checkliste (Optional)

```
>>>Checkliste
Ist die Firewall aktiviert?
Sind alle unnötigen Ports geschlossen?
Wurde die Konfiguration dokumentiert?
```

Jede Zeile wird als separate Checklistenfrage gespeichert.

## Tipps und Best Practices

### 1. Dry-Run vor Import

Immer zuerst einen Dry-Run durchführen:

```bash
python manage.py import-document datei.txt \
  --nummer "R0XXX" \
  --name "Test" \
  --dokumententyp "Standard IT-Sicherheit" \
  --dry-run --verbose
```

### 2. Themen vorab erstellen

Sicherstellen, dass alle verwendeten Themen in der Datenbank existieren:

```python
python manage.py shell
>>> from dokumente.models import Thema
>>> Thema.objects.get_or_create(name="Organisation")
>>> Thema.objects.get_or_create(name="Technik")
>>> Thema.objects.get_or_create(name="Informationen")
```

### 3. Dokumententyp vorab erstellen

Der Dokumententyp muss existieren:

```python
python manage.py shell
>>> from dokumente.models import Dokumententyp
>>> Dokumententyp.objects.get_or_create(
...     name="Standard IT-Sicherheit",
...     defaults={"verantwortliche_ve": "SR-SUR-SEC"}
... )
```

### 4. Abschnitttypen prüfen

Folgende Abschnitttypen müssen in der Datenbank existieren:
- `text`
- `liste geordnet`
- `liste ungeordnet`
- `code`
- `diagramm`

Prüfen in der Autorenumgebung unter "Abschnitttypen".

### 5. UTF-8 Kodierung

Sicherstellen, dass die Importdatei UTF-8 kodiert ist, besonders bei Umlauten (ä, ö, ü) und Sonderzeichen.

### 6. Versionierung mit Purge

Beim Re-Import mit `--purge`:

```bash
# 1. Backup erstellen
python manage.py dumpdata dokumente.Dokument dokumente.Vorgabe > backup.json

# 2. Import mit Purge
python manage.py import-document datei.txt \
  --nummer "R0009" \
  --name "Serversysteme" \
  --dokumententyp "Standard IT-Sicherheit" \
  --purge
```

### 7. Mehrzeilige Inhalte

Mehrzeiliger Text wird automatisch erkannt:

```
>>>Langtext
>>>Text
Dies ist Zeile 1.
Dies ist Zeile 2.

Dies ist ein neuer Absatz.
```

### 8. Leerzeilen

Leerzeilen innerhalb eines Abschnitts werden beibehalten. Eine Leerzeile nach einem `>>>`-Trenner wird ignoriert.

## Fehlerbehebung

### "Dokumententyp does not exist"

Der angegebene Dokumententyp existiert nicht in der Datenbank.

**Lösung:** Dokumententyp aus dem IT-Grundschutz verwenden, nötigenfalls hinzufügen in der Autorenumgebung oder per Shell.

### "Thema not found, skipping Vorgabe"

Das in der Vorgabe verwendete Thema existiert nicht.

**Lösung:** Thema in der Autorenumgebung erstellen oder Importdatei anpassen.

### "AbschnittTyp not found"

Ein verwendeter Abschnitttyp existiert nicht.

**Lösung:**
- Schreibweise prüfen (Gross-/Kleinschreibung und "-"/" " wird normalisiert)
- Wenn nötig Abschnitttyp in der Autorenumgebung erstellen (Achtung! Ausgabeformat muss im Code definiert werden)
- Standardtypen: `text`, `liste geordnet`, `liste ungeordnet`, `tabelle`, `code`

### Vorgabe wird nicht importiert

Prüfen:
- Ist `>>>Nummer` gesetzt?
- Ist `>>>Titel` gesetzt?
- Existiert das Thema?

`--dry-run --verbose` für detaillierte Informationen.

## Weitere Informationen

### Beispieldateien

Beispieldateien:
- `Documentation/import formats/r009.txt`
- `Documentation/import formats/r0126.txt`

### Export-Format

Der Export verwendet JSON statt Textformat. Für JSON-Export siehe:

```bash
python manage.py export_json --output dokumente.json
```

Oder über die Web-Oberfläche: `/dokumente/R0066/?format=json`

### Verwandte Commands

- `export_json` - Exportiert Dokumente als JSON
- `sanity_check_vorgaben` - Prüft Vorgaben auf Konflikte
- `clear_diagram_cache` - Löscht Diagramm-Cache