# Dokumentation: mpc_obscode_api.bas

## Zweck

`mpc_obscode_api.bas` laedt Observatory-Code-Daten des Minor Planet Center (MPC), speichert sie lokal und erzeugt optional eine direkt in FreeBASIC einbindbare `.bi`-Datei.

Die wichtigsten Arbeitsregeln dazu sind:

- konservativ arbeiten
- keine Architekturentscheidung ohne Rueckfrage
- nur die konkret genannte Funktion oder den konkret genannten Bereich aendern
- die TSV-Feldreihenfolge nicht aendern
- das MPC-Codeformat bleibt `[0-9A-Z][0-9][0-9]`
- die `.bi`-Datei enthaelt nur die Type-Definition und kurze Kopierhinweise, kein statisches Datenarray und keine Ladefunktion
- Dateiausgaben, UI-Texte und Beschriftungen immer auf Englisch schreiben
- Datenwerte niemals uebersetzen oder inhaltlich umdeuten
- die Sprache im Chat bleibt Deutsch
- Tabellen in Ausgaben mit links ausgerichteter Titelzeile und links ausgerichteter erster Spalte verwenden
- Textspalten links, Zahlenspalten rechts ausrichten
- Zahlen nach Moeglichkeit am Dezimalpunkt ausrichten
- Tabellen nur so breit wie noetig rendern, nicht automatisch auf volle Seitenbreite strecken
- Texte duerfen umbrechen, aber eine umgebrochene Spalte soll nicht unter 4 sichtbaren Zeichen fallen
- Jede Tabellenkopf-Zeile braucht einen erklaerenden Hover und am Tabellenende eine ausfuehrliche Spaltenliste
- Alle Tabellen muessen sortierbar sein; wenn eine `Count`-Spalte vorhanden ist, ist die Startreihenfolge `Count` absteigend
- Jede Tabelle ist vor der Ausgabe auf korrekte Sortierung zu pruefen

Das Programm kann:

- einen einzelnen Observatory-Code pruefen
- eine lokale Datenbasis synchronisieren
- neue und geaenderte Codes erkennen
- Snapshot- und Include-Dateien erzeugen
- Logs schreiben und versionieren
- temporaere Dateien beim Start bereinigen
- bei Tastendruck waehrend des Syncs kontrolliert abbrechen

## Dateien

| Datei | Zweck |
|---|---|
| `mpc_obscode_snapshot.tsv` | lokale Datenbasis im TSV-Format |
| `mpc_obscode_snapshot_data.bi` | FreeBASIC-Include mit Type und Kopierhinweisen, ohne statisches Datenarray und ohne Ladefunktion |
| `mpc_obscode_sync.log` | aktuelles Log |
| `mpc_obscode_sync.log.1` bis `.10` | rotierte Logversionen |
| `*.tmp` | temporaere Dateien beim atomischen Schreiben |
| `*.bak` | Backups bei `--deleteall --backup-delete` |

## Wichtige Aufrufe

### Hilfe anzeigen

```bat
mpc_obscode_api.exe --help
```

### Einzelnen Code pruefen

```bat
mpc_obscode_api.exe --check=X09
```

Alternativ:

```bat
mpc_obscode_api.exe X09
```

### Synchronisation starten

```bat
mpc_obscode_api.exe --sync
```

### Synchronisation mit maximalem Alter

```bat
mpc_obscode_api.exe --sync --max-age-days=91
```

Bedeutung: Jeder Code wird spaetestens nach 91 Tagen erneut geprueft.

### Sync simulieren

```bat
mpc_obscode_api.exe --sync --dry-run
```

Laedt und prueft, schreibt aber die Datenbasis am Ende nicht.

### Anzahl API-Abfragen begrenzen

```bat
mpc_obscode_api.exe --sync --limit=50
```

### Statistik anzeigen

```bat
mpc_obscode_api.exe --stats
```

### Datenbasis loeschen

```bat
mpc_obscode_api.exe --deleteall
```

Das Programm fragt zur Sicherheit nach `YES`.

### Datenbasis sichern statt loeschen

```bat
mpc_obscode_api.exe --deleteall --backup-delete
```

Dann werden vorhandene Dateien nach `.bak` umbenannt.

## Synchronisationslogik

1. MPC-ObsCode-Liste wird geladen.
2. Lokale Snapshot-Datei wird gelesen.
3. Neue Codes werden sofort per API abgefragt.
4. Alte Codes werden ab `--max-age-days=N` erneut geprueft.
5. Codes mit frueherem Fehler werden nach 7 Tagen priorisiert erneut geprueft.
6. Optional werden weitere Kandidaten zufaellig ausgewaehlt.
7. Am Ende werden TSV und BI atomisch geschrieben.

## Atomisches Schreiben

Das Programm schreibt zuerst in:

- `mpc_obscode_snapshot.tsv.tmp`
- `mpc_obscode_snapshot_data.bi.tmp`

Danach wird die alte Datei ersetzt. Dadurch wird eine halb geschriebene Datenbasis vermieden.

Beim naechsten Programmstart werden liegengebliebene `.tmp`-Dateien geloescht und im Log vermerkt.

## Tastendruck-Abbruch

Waehrend `--sync` prueft das Programm regelmaessig auf Tastendruck.

Bei Tastendruck fragt es:

1. Ob der Sync abgebrochen werden soll.
2. Ob der aktuelle Zwischenstand vorher geschrieben werden soll.

## Logging

Vor jedem Sync wird das Log rotiert:

- `mpc_obscode_sync.log` wird zu `.1`
- `.1` wird zu `.2`
- ...
- `.10` wird geloescht

Das aktuelle Log enthaelt unter anderem:

- `SYNC_START`
- `SYNC_END`
- `NEW`
- `CHANGED`
- `ERROR`
- `MISSING`
- `RECOVERY`

Am Sync-Ende werden Anzahl gepruefter, geaenderter und fehlerhafter Codes sowie Dauer in Sekunden protokolliert.

## Hinweise

Das Programm verwendet `curl`. `curl.exe` muss im Suchpfad liegen oder unter Windows verfuegbar sein.

Die Datei ist bewusst ASCII-kompatibel kommentiert, damit FBide keine UTF-8-Umlaute falsch anzeigt.

## Pruefregel fuer Aenderungen

- `fbc` nur ausfuehren, wenn sich eine `.bas`-Datei geaendert hat.
- Python nur ausfuehren, wenn sich eine `.py`-Datei geaendert hat.
- Beide Pruefungen bleiben als Regel erhalten und ergaenzen die bestehenden Ablaufinfos.