# Online-Upgrade Backend (time.ca-game.de)

## Ziel
Dieses Backend speichert den kompletten App-Datenstand online und liefert Monatsreports.
Intern wird hybrid gearbeitet:
- Snapshot-JSON als Vollbackup
- zusaetzlich normalisierte SQL-Tabellen fuer Website/Reporting

## Verzeichnis auf dem Webserver
Empfohlen:

`https://time.ca-game.de/api`

Lege die Dateien aus `backend/api/` per FTP in diesen Ordner.

Fuer das Web-Dashboard zusaetzlich:

`https://time.ca-game.de/web`

Lege die Dateien aus `backend/web/` per FTP in diesen Ordner.

## 1) MySQL vorbereiten
1. Datenbank und Benutzer anlegen.
2. `backend/schema.sql` importieren.
3. In `backend/api/db.php` die Zugangsdaten setzen:
   - `DB_HOST`
   - `DB_PORT`
   - `DB_NAME`
   - `DB_USER`
   - `DB_PASS`

### Bestehende Installationen
Wenn die alten Tabellen schon existieren, nur die neuen Tabellen nachziehen:

- `backend/migrations/2026_03_16_relational_tables.sql`
- `backend/migrations/2026_03_17_shift_templates.sql`
- `backend/migrations/2026_03_18_contract_phases.sql`

## 2) API-Dateien deployen
Diese Dateien muessen im Zielordner liegen:
- `db.php`
- `bootstrap.php`
- `register.php`
- `login.php`
- `change_password.php`
- `push_snapshot.php`
- `pull_snapshot.php`
- `month_report.php`
- `month_days.php`
- `.htaccess`

Zusaetzlich fuer die Website (`/web`):
- `.htaccess`
- `login.php`
- `register.php`
- `logout.php`
- `index.php`
- `export_csv.php`
- `assets/style.css`
- `lib/init.php`
- `lib/data.php`
- `lib/.htaccess`

## 3) App konfigurieren
In der App unter:

`Settings -> Online-Upgrade / Cloud Sync`

API-URL setzen auf:

`https://time.ca-game.de/api`

Dann registrieren oder einloggen, anschliessend:
- `In Cloud sichern` (Upload)
- `Cloud-Stand laden` (Download)
- `Report aus Cloud laden` (Monatsauswertung)

Wichtig fuer Website-Daten:
- Nach dem Deploy einmal in der App `In Cloud sichern` ausfuehren.
- Dadurch werden die relationalen Tabellen befuellt/aktualisiert.

## Endpunkte
- `POST /api/register.php`
- `POST /api/login.php`
- `POST /api/change_password.php` (Bearer-Token, aktuelles + neues Passwort)
- `POST /api/push_snapshot.php` (Bearer-Token)
- `GET /api/pull_snapshot.php` (Bearer-Token)
- `GET /api/month_report.php?year=YYYY&month=MM` (Bearer-Token)
- `GET /api/month_days.php?year=YYYY&month=MM` (Bearer-Token, tageweise Daten fuer Web-UI)

## Web-Dashboard
- URL: `https://time.ca-game.de/web/login.php`
- Login mit demselben Benutzerkonto (`users`), das auch fuer die App verwendet wird.
- Inhalte:
  - Monats-KPIs (Soll/Ist/Delta, Carry Over, Zeitkonto)
  - Spezialtage (Urlaub/Krank/Feiertag/Frei/Unbezahlt)
  - Tagesliste inkl. Plan/Stempel/Pausen/Saldo
  - Direkte Bearbeitung einzelner Tage aus der Tagesliste
  - Schichtvorlagen fuer schnelle Planerfassung
  - Planungsbasis im Web editierbar (Wochenziel/Solltage/Urlaub/Frei-Logik)
  - Jahresverlauf (Delta pro Monat)
  - CSV-Export pro Monat

## Synchronisation Web <-> App
- Aenderungen im Web werden in den relationalen Tabellen gespeichert.
- Beim Web-Speichern wird der Jahres-Carry-Over (Monatskette) neu berechnet.
- Danach wird der Nutzer-Snapshot automatisch neu aus den relationalen Daten aufgebaut.
- Ergebnis: `Cloud-Stand laden` in der App liefert die im Web korrigierte Version.
- Monate ohne Plan/Stempel-Daten werden in der Jahreskette als neutral (Delta 0) behandelt.

## Wichtiger Auth-Hinweis (Apache)
Damit PHP den Authorization-Header erhaelt, muss `.htaccess` im API-Ordner liegen.
Zusaetzlich akzeptiert die API als Fallback `X-Authorization: Bearer <token>`.

## Welche Daten werden online gespeichert?
- App-Settings (Pausenregeln/Compliance/Urlaubsanspruch)
- Vertragsphasen mit Stichtag (`gueltig_ab`, Wochenziel, Solltage)
- Plan-Tage inkl. Spezialtage (`Arbeit`, `Urlaub`, `Krank`, `Feiertag`, `Frei`, `Unbezahlt`)
- Stempelungen inkl. Kommen/Gehen/Pausensegmente/Override
- Monats-Saldovortraege (Zeitkonto-Basis)
- Relevante Nutzer-Prefs (Monatsreport-Spalten/Ask-on-open, Notification-Enabled)

Damit sind Soll-/Ist-Berechnungsgrundlagen, Zeitkonto und Spezialtage vollstaendig enthalten
und sowohl als Snapshot als auch relational auswertbar.