From db68c84d45cb683485f3f64efcdafa91a42a4d42 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jesko=20Ansch=C3=BCtz?= <jesko@linuxmuster.net>
Date: Fri, 27 Mar 2026 20:25:50 +0100
Subject: [PATCH] =?UTF-8?q?docs:=20API-ENDPOINTS=20+=20SCHEMA=20f=C3=BCr?=
 =?UTF-8?q?=20Override=20und=20Wochenend-Sperre?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 docs/API-ENDPOINTS.md | 87 +++++++++++++++++++++++++++++++++++++++++++
 docs/SCHEMA.md        | 30 +++++++++++++++
 2 files changed, 117 insertions(+)

diff --git a/docs/API-ENDPOINTS.md b/docs/API-ENDPOINTS.md
index 7a2b244..ac66752 100644
--- a/docs/API-ENDPOINTS.md
+++ b/docs/API-ENDPOINTS.md
@@ -587,6 +587,93 @@ Der Scheduler prüft jede Minute, ob die aktuelle Uhrzeit mit `power_on_time` od
 
 ---
 
+### Globaler Override
+
+| Methode | Pfad | Auth | Beschreibung |
+|---------|------|------|--------------|
+| GET | `/api/v1/global-override` | authUser | Aktiven Override abrufen (204 wenn keiner aktiv) |
+| POST | `/api/v1/global-override` | authUser | Override setzen + sofort MQTT an alle Screens |
+| DELETE | `/api/v1/global-override` | authUser | Override aufheben |
+
+**GET /api/v1/global-override**
+
+Ruft den aktuell aktiven globalen Override ab.
+
+**Response:** `200 OK` (wenn aktiv)
+```json
+{"type":"off","until":"2026-04-05T18:00:00+02:00","set_at":"2026-03-27T15:30:00+02:00"}
+```
+
+**Response:** `204 No Content` (wenn kein Override aktiv)
+
+---
+
+**POST /api/v1/global-override**
+
+Setzt einen globalen Override und sendet sofort MQTT-Befehle an alle Screens.
+
+**Request-Body:**
+```json
+{"type":"off","until":"2026-04-05T18:00:00+02:00"}
+```
+
+**Response:** `200 OK`
+```json
+{"type":"off","until":"2026-04-05T18:00:00+02:00","set_at":"2026-03-27T15:30:00+02:00"}
+```
+
+**Fehler:**
+- `400 Bad Request` — `type` nicht "on"/"off", oder ungültiges Zeitformat
+- `500 Internal Server Error` — DB-Fehler
+
+---
+
+**DELETE /api/v1/global-override**
+
+Hebt den aktuellen globalen Override auf.
+
+**Response:** `204 No Content`
+
+**Fehler:**
+- `500 Internal Server Error` — DB-Fehler
+
+---
+
+### Per-Screen Override
+
+| Methode | Pfad | Auth | Beschreibung |
+|---------|------|------|--------------|
+| POST | `/api/v1/screens/{screenSlug}/override` | authScreen | Per-Screen "Einschalten bis" setzen oder löschen |
+
+**POST /api/v1/screens/{screenSlug}/override**
+
+Setzt oder löscht den per-Screen "Einschalten bis"-Override. Mit diesem Override bleibt ein Monitor bis zu
+dem angegebenen Zeitpunkt eingeschaltet, selbst wenn der globale Schedule "aus" vorsieht.
+
+**Auth:** Erforderlich. Screen-Zugriff erforderlich.
+
+**Path-Parameter:**
+- `screenSlug` — Slug des Screens
+
+**Request-Body:**
+```json
+{"on_until":"2026-04-05T18:00:00+02:00"}
+```
+
+Um den Override zu löschen, `on_until` auf `null` setzen:
+```json
+{"on_until":null}
+```
+
+**Response:** `204 No Content`
+
+**Fehler:**
+- `400 Bad Request` — Ungültiges Zeitformat oder ungültiges JSON
+- `404 Not Found` — Screen nicht vorhanden
+- `500 Internal Server Error` — DB-Fehler
+
+---
+
 ## Message Wall
 
 ### POST /api/v1/tools/message-wall/resolve
diff --git a/docs/SCHEMA.md b/docs/SCHEMA.md
index 51944f0..c512fbf 100644
--- a/docs/SCHEMA.md
+++ b/docs/SCHEMA.md
@@ -523,6 +523,36 @@ Regeln:
 - `schedule_enabled = false` bedeutet: Zeitplan vorhanden, aber deaktiviert
 - Leere Zeitfelder bedeuten: kein Einschalt- bzw. kein Ausschaltbefehl
 
+Neue Spalte in `screen_schedules` (Migration `006`):
+- `override_on_until timestamptz` — Einschalten-Override: Monitor bleibt bis zu diesem Zeitpunkt eingeschaltet (null = kein Override)
+
+### `global_override` (Migration 006)
+
+Zweck:
+
+- Speichert den globalen Display-Override (maximal eine Zeile)
+
+Spalten:
+
+```sql
+id        INT         PRIMARY KEY DEFAULT 1
+type      TEXT        NOT NULL         -- "on" oder "off"
+until     TIMESTAMPTZ NOT NULL         -- Override aktiv bis zu diesem Zeitpunkt
+set_at    TIMESTAMPTZ NOT NULL DEFAULT now()  -- Wann der Override gesetzt wurde
+```
+
+Constraint:
+```sql
+CHECK (id = 1)
+```
+
+Regeln:
+
+- Die Tabelle enthaelt maximal eine Zeile (id = 1)
+- `type` bestimmt den globalen Zielzustand (alle Screens)
+- `until` gibt an, wann der Override automatisch aufgehoben wird
+- Der Scheduler prueft jede Minute, ob der Override noch aktiv ist (aktuell <= until)
+
 ### `screen_snapshots`
 
 Zweck: