platz/doc/dateiformate.md

# Dateiformate

Referenz fuer die Eingabe- und Ausgabedateien eines `platz`-Laufs, mit Beispielen aus
`work/test1/` und `work/test2/`.

Alle vier Dateien liegen unter dem mit `--indir <dir>` angegebenen Verzeichnis (z.B.
`work/test1/` oder `work/test2/`) unter festen Namen: `tische.ini`, `bestellung.json` als
Eingabe, `TischePersonen.txt` und `PersonenTische.csv` als Ausgabe. Beispielaufruf:

```bash
bin/platz.sh --indir work/test1
```

## Tischaufstellung: `tische.ini`

Ein INI-File mit einer Sektion pro Tisch. Sektionsname ist die Tisch-Id.

| Schluessel      | Bedeutung                                              |
|-----------------|---------------------------------------------------------|
| `Nummer`        | Anzeigenummer des Tisches                              |
| `Hof`           | Hof/Bereich, in dem der Tisch steht                    |
| `Plaetze`       | Anzahl der Sitzplaetze am Tisch                        |
| `Nachbarliste`  | Python-Liste der Ids benachbarter Tische               |
| `Koordinaten`   | `(x,y)`-Tupel fuer die Position des Tisches             |

Beispiel aus `work/test2/tische.ini` (eine Reihe von fuenf Tischen, jeder mit seinen
direkten Nachbarn verkettet):

```ini
[1]
Nummer=1
Hof=1
Plaetze=3
Nachbarliste=[2]
Koordinaten=(1,1)

[2]
Nummer=2
Hof=1
Plaetze=5
Nachbarliste=[1,3]
Koordinaten=(2,1)

[3]
Nummer=3
Hof=1
Plaetze=3
Nachbarliste=[2,4]
Koordinaten=(3,1)

[4]
Nummer=4
Hof=1
Plaetze=4
Nachbarliste=[3,5]
Koordinaten=(4,1)

[5]
Nummer=5
Hof=1
Plaetze=4
Nachbarliste=[4]
Koordinaten=(5,1)
```

Werte wie `Nachbarliste` und `Koordinaten` werden mit `eval()` geladen (siehe
`Tische.laden()` in `libs/Strukturdaten.py`) — es steht also echter Python-Ausdruckscode im
File, keine reine INI-Syntax.

## Gaesteliste: `bestellung.json`

Ein JSON-Objekt mit dem Schluessel `"gruppen"`, einer Liste von Gruppen-Objekten. Jede
Gruppe enthaelt:

- `"personen"`: Liste von Personen-Objekten mit `"vorname"`, `"nachname"` und optionalem
  `"titel"` (Pflicht: Vor- und Nachname)
- optional `"name"`: Anzeigename der Gruppe (z.B. `"Familie Huber"`); nur fuer Ausgabe und
  Web-Anzeige, nicht fuer die Optimierung relevant
- optional `"anzahl"`: N, um **jede** Person der Gruppe zu einer Sammelbuchung von N
  (gleichnamigen) Buchungen zu vervielfaeltigen — praktisch fuer anonyme Kontingente
- optional `"tisch"`: Tisch-Id, um die Gruppe als VIP-Gruppe fest an diesen Tisch zu binden
  (sie wird dann **nicht** vom GA platziert)

Geladen wird das File von `JSONConfig` in `libs/Strukturdaten.py` (Nachfolger des frueheren
`XMLConfig`; das alte `bestellung.xml`-Format wurde vollstaendig durch JSON abgeloest).
Die Datei sollte UTF-8 sein; ein evtl. vorhandenes BOM (Excel) wird geschluckt.

Minimalbeispiel mit Sammelbuchungen, aus `work/test1/bestellung.json`:

```json
{
  "gruppen": [
    {
      "anzahl": 10,
      "personen": [
        { "vorname": "A", "nachname": "AA", "titel": "Dipl. Ing." }
      ]
    },
    {
      "anzahl": 4,
      "personen": [
        { "vorname": "B", "nachname": "BB", "titel": "Prof." }
      ]
    },
    {
      "anzahl": 5,
      "personen": [
        { "vorname": "C", "nachname": "CC", "titel": "Dr." }
      ]
    }
  ]
}
```

Umfangreicheres Beispiel mit benannten Gruppen und einer VIP-Gruppe, aus
`work/test2/bestellung.json`:

```json
{
  "gruppen": [
    {
      "name": "einfache Gruppe aus drei Personen mit festem Wunsch fuer einen Tisch",
      "tisch": 1,
      "personen": [
        { "vorname": "Michael", "nachname": "Stangl", "titel": "Dipl. Ing." },
        { "vorname": "Magnus", "nachname": "Mueller", "titel": "Professor" },
        { "vorname": "Bernd Robert", "nachname": "Hoehn", "titel": "Professor" }
      ]
    },
    {
      "name": "einfache Gruppe aus zwei Personen",
      "personen": [
        { "vorname": "Heinz", "nachname": "Bruegge" },
        { "vorname": "Hubert", "nachname": "K" }
      ]
    },
    {
      "name": "Gruppe aus drei anonymen Personen",
      "anzahl": 3,
      "personen": [
        { "vorname": "Bestelli", "nachname": "Bloedkopf" }
      ]
    }
  ]
}
```

Die erste Gruppe hier ist per `"tisch": 1` fest an Tisch 1 gebunden (VIP-Gruppe); die letzte
Gruppe erzeugt ueber `"anzahl": 3` drei gleichnamige "Bestelli Bloedkopf" Buchungen.

> Fuer den Web-Weg (Meilenstein 1) gibt es zusaetzlich einen CSV-Import (`libs/CSVConfig.py`,
> Spalten `Vorname;Nachname;Titel;Gruppe;Tisch;Anzahl`) — inhaltlich aequivalent, nur
> flach statt verschachtelt.

## Ausgabe: `TischePersonen.txt`

Eine Sektion pro Tisch (`[Tischid]`), darunter eine Zeile pro Sitzplatz:

```
[1]
Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 1
Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 2
Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 3
Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 4
Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 5

[2]
Dipl. Ing. A AA = Hof 1, Tisch 2, Nummer 1
...
```

Format je Zeile: `Titel Vorname Nachname = Hof <Hof>, Tisch <Nummer>, Nummer <Platznummer>`.

## Ausgabe: `PersonenTische.csv`

Dieselben Sitzplatzdaten, aber eine Zeile pro Person statt pro Tisch, alphabetisch nach
Nachname sortiert:

```
AA, A, Dipl. Ing. = Hof 1, Tisch 1, Nummer 2
AA, A, Dipl. Ing. = Hof 1, Tisch 1, Nummer 3
...
BB, B, Prof. = Hof 1, Tisch 3, Nummer 2
...
CC, C, Dr. = Hof 1, Tisch 4, Nummer 2
...
```

Format je Zeile: `Nachname, Vorname, Titel = Hof <Hof>, Tisch <Nummer>, Nummer <Platznummer>`.

## Zyklus- und Strafenkonfiguration

Siehe `cfg/zyklus.cfg` und `cfg/strafen.cfg` sowie die Beschreibung in `CLAUDE.md` /
`README.md` fuer das Format der GA-Ablaufsteuerung (`Abfolge`/`Anzahl`) und der
Strafpunkte-Tabelle.