# Sternwarte API – DB4js_all.php

Vereinheitlichte Backend-API für öffentliche Führungen, Sonderführungen, Mitarbeiter (BEO), Anmeldungen und Statistiken.

## Überblick
Die Datei `DB4js_all.php` bündelt ehemals mehrere Endpunkte:
- `DB4js.php` (öffentliche Führungen + Anmeldungen)
- `sofueDB.php` (Sonderführungen)
- `anmeldDB.php` (Anmeldungen alte Variante)
- `sofianmeldDB.php` (Sonderführungs-Anmeldungen)
- `statisticDB.php` (Statistiken)

Alle Aufrufe erfolgen über einen einzigen HTTP-POST (oder wenige GET) Request an die Datei mit dem Parameter `cmd`.
Antwortformat immer JSON (`Content-Type: application/json; charset=utf-8`).

## Authentifizierung (optional)
Falls die Environment-Variablen `API_USER` und `API_PASS` gesetzt sind, **muss** Basic-Auth verwendet werden.

Header Beispiel:
```
Authorization: Basic base64(API_USER:API_PASS)
```

Ohne gesetzte ENV-Variablen ist die API offen (nur interne Nutzung empfohlen).

## Allgemeines Request-Format
```http
POST /api/DB4js_all.php
Content-Type: application/json

{
  "cmd": "GET_ANMELD",
  "id": 42
}
```

Erfolgreiche Antworten: HTTP 200. Fehler: passende HTTP-Status (z.B. 400, 401, 404, 422, 500) + `{"error": "Beschreibung"}`.

## Fehlerstruktur
```json
{
  "error": "Message",
  "...optional": "Zusatzinformationen"
}
```

## Kommandoliste
| Command | Beschreibung |
|---------|--------------|
| PING | Health-Check (liefert Zeitstempel) |
| LIST_COMMANDS | Liefert alle verfügbaren Kommandos mit Beschreibung |
| GET_ANMELD | Liste öffentlicher Anmeldungen für `fid` |
| GET_ONEANMELD | Einzelne Anmeldung per `id` |
| GET_COUNTS | Anzahl Anmeldungen für `fid` |
| GET_COUNTS_DATE | Anzahl Anmeldungen für Datum `date` (YYYY-MM-DD) |
| INSERT_TLN | Neue öffentliche Anmeldung erstellen |
| UPDATE_TLN | Öffentliche Anmeldung ändern |
| DELETE_TLN | Öffentliche Anmeldung löschen |
| GET_SOFIANMELD | Sonderführungs-Anmeldungen; optional `sofue_id` |
| GET_ONESOFIANMELD | Einzelne Sonderführungs-Anmeldung per `id` |
| GET_SOFIANMELD_COUNT | Anzahl Sonderführungs-Anmeldungen pro `sofue_id` |
| INSERT_SOFIANMELD | Neue Sonderführungs-Anmeldung |
| UPDATE_SOFIANMELD | Sonderführungs-Anmeldung ändern |
| DELETE_SOFIANMELD | Sonderführungs-Anmeldung löschen |
| GET_TERMINE | Öffentliche Führungstermine, optional `includeOld` |
| GET_ONETERMIN | Termin per `id` |
| GET_FID | Führungs-ID zu Datum `datum` |
| GET_TIME | Uhrzeit zu Datum `date` + optional `typ` ("sonnen") |
| GET_BEOS | Alle BEOs; optional `onlyguides` und `what` (Spalten) |
| GET_ONEBEO | Einzelner BEO per `name` |
| GET_ONE | Sonderführung per `id` |
| GET_ONETERMIN_SOFUE | Sonderführung per `termin` (Datum) |
| GET_MANY | Gefilterte Sonderführungen (status, rows, page, termin) |
| UPDATE | Standard-Update einer Sonderführung |
| UPDATEAFTER | Nachbearbeitung (stattgefunden, besucher, remark, bezahlt, status) |
| DELETE | Sonderführung Soft-Delete |
| GET_STATISTIK_SOFUE | Monatsstatistik Sonderführungen Jahr `year` |
| GET_STATISTIK_ANMELD | Monatsstatistik öffentliche Führungen Jahr `year` |
| GET_STATISTIK_BEO | BEO-Führungsstatistik Jahr `year` |
| GET_STATISTIK_GESAMT | Gesamtstatistik Jahr `year` |
| SEND_CONFIRMATION | Einfache Text-Mail |
| SENDMAILZUSAGE | Zusage-Mail an Anfragenden |
| SENDMAIL2BEO | Mail an Mitarbeiter (BEO) |
| SENDMAIL2LISTE | Anfrage an Verteilerliste |
| PUT2KALENDER | Placeholder für Kalender-Eintrag |

## Parameter & Beispiele

### 1. Öffentliche Anmeldungen
#### GET_ANMELD
```json
{ "cmd": "GET_ANMELD", "id": 17 }
```
Antwort: Liste von Anmeldungen.

#### INSERT_TLN
Pflichtfelder: `name`, `email`, `anzahl`, `fid`
```json
{
  "cmd": "INSERT_TLN",
  "name": "Müller",
  "email": "mueller@example.com",
  "anzahl": 4,
  "fid": 17,
  "remarks": "Kommt etwas früher"
}
```
Antwort: `{ "success": true, "id": 123 }`

### 2. Sonderführungs-Anmeldungen
#### INSERT_SOFIANMELD
```json
{
  "cmd": "INSERT_SOFIANMELD",
  "name": "Schule ABC",
  "email": "lehrer@schule.de",
  "anzahl": 22,
  "sofue_id": 55,
  "remarks": "Viele Fragen erwartet"
}
```

### 3. Termine
#### GET_TERMINE
```json
{ "cmd": "GET_TERMINE", "includeOld": "false" }
```

### 4. BEOs
#### GET_BEOS
Hinweis: In der Tabelle `beos` heißt die E-Mail-Spalte `email_1`. Aus Kompatibilitätsgründen akzeptiert die API auch `email` und liefert diese als Alias zurück.
```json
{ "cmd": "GET_BEOS", "onlyguides": "true", "what": "id,name,email" }
```
Oder explizit mit Originalspalte:
```json
{ "cmd": "GET_BEOS", "onlyguides": true, "what": "id,name,email_1" }
```

### 5. Sonderführungen
#### GET_MANY
Filterbar über Status/Termin/Pagination.
```json
{ "cmd": "GET_MANY", "status": "2", "rows": 20, "page": 1 }
```

#### UPDATE (Standard)
```json
{
  "cmd": "UPDATE",
  "id": 55,
  "mitarbeiter": "beo_k1",
  "status": 2,
  "bemerkung": "Bestätigt",
  "wtermin": "2025-12-03 19:00:00"
}
```

#### UPDATEAFTER (Nachbearbeitung)
Optional Felder: `stattgefunden`, `besucher`, `remark`, `bezahlt`, `status`, `wtermin`
```json
{
  "cmd": "UPDATEAFTER",
  "id": 55,
  "stattgefunden": 1,
  "besucher": 27,
  "remark": "Sehr interessiert",
  "bezahlt": "Kasse 50€"
}
```

### 6. Statistiken
#### Gesamtstatistik
```json
{ "cmd": "GET_STATISTIK_GESAMT", "year": 2025 }
```

### 7. Mail
#### SEND_CONFIRMATION
```json
{
  "cmd": "SEND_CONFIRMATION",
  "to": "rxf@gmx.de",
  "subject": "Test",
  "body": "Hallo Welt"
}
```

## GET Fallback / Health
Ein GET ohne `cmd` liefert einfachen Status:
```http
GET /api/DB4js_all.php
```
Antwort:
```json
{ "status": "ok", "message": "API erreichbar" }
```

## Typische Fehlerfälle
| Status | Ursache | Beispiel |
|--------|---------|---------|
| 401 | Ungültige oder fehlende Basic-Auth | `{ "error": "Unauthorized" }` |
| 422 | Fehlender `cmd` oder Pflichtfelder | `{ "error": "Command missing" }` |
| 404 | Datensatz nicht gefunden | `{ "error": "Not found" }` |
| 500 | Interner Fehler | `{ "error": "Internal error" }` |

## Sicherheit
- Alle DB-Zugriffe über PDO Prepared Statements.
- Optional Basic-Auth.
- Keine direkte Ausgabe interner Fehlermeldungen an Client.
- E-Mail-Versand minimalistisch (kein HTML-Injection-Risiko durch Plaintext).

## Migration Hinweise
| Alt-Datei | Abgedeckt durch | Hinweise |
|----------|-----------------|----------|
| DB4js.php | Commands für öffentliche Anmeldungen & Termine | Parameter unverändert nutzbar |
| sofueDB.php | Sonderführungen & Nachbearbeitung | `UPDATEAFTER` ersetzt alte updateAfter-Version |
| anmeldDB.php | Enthalten in öffentlichen Anmeldungen | Zusammengeführt |
| sofianmeldDB.php | SoFi-Anmeldungen | eigener Command-Namespace |
| statisticDB.php | Statistik-Commands | Jahr-Parameter optional |

## Beispiel: JS Fetch
```js
async function getAnmeldungen(fid) {
  const res = await fetch('/api/DB4js_all.php', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ cmd: 'GET_ANMELD', id: fid })
  });
  return res.json();
}
```

## Beispiel: curl
```bash
curl -X POST https://example.com/api/DB4js_all.php \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"PING"}'
```
Mit Basic-Auth:
```bash
curl -X POST https://example.com/api/DB4js_all.php \
  -u "$API_USER:$API_PASS" \
  -H 'Content-Type: application/json' \
  -d '{"cmd":"GET_TERMINE"}'
```

## Erweiterung neuer Commands
1. Eintrag in `Commands::MAP` hinzufügen.
2. Switch-Case im Dispatcher erweitern.
3. Validierung & Antwortformat konsistent halten.

## Known Limitations / TODO
- Kein Rate Limiting.
- Kein Pagination bei öffentlichen Anmeldungen (nur Sonderführungen umgesetzt).
- Kein zentraler Logger für Nutzungsstatistik.
- Kalender-Funktion ist Platzhalter.

## Changelog (Unified Version)
- Erstveröffentlichung: Zusammenführung aller Endpoints, PDO, Auth, Validation.

---
Bei Fragen oder für neue Features bitte erweitern oder Issue anlegen.
