docs: Zeitsteuerung in README und Hilfeseite dokumentieren

README:
- Feature-Liste und Routen-Tabelle ergaenzt
  (POST /admin/<site>/update-playlist-item/<screen>)
- Neuer Abschnitt "Playlist-Eintraege" mit dem Dict-Format fuer URL- und
  Datei-Eintraege sowie dem schedule-Objekt: Felder, Beispiele und die
  Verhaltensregeln (nur Uhrzeit bei daily/weekly, days nur bei weekly,
  Fenster ueber Mitternacht gehoert zum Starttag, unlesbare Angaben
  blenden nicht aus, Aktiv-Zustand fliesst in den Playlist-Hash ein)
- Helper-Liste aktualisiert: playlist_item_enabled() gibt es nicht mehr,
  dafuer is_item_active(), _schedule_time(), _window_start_date(),
  _in_validity_range() und der Filter schedule_text()

Hilfeseite (/admin/help):
- Neuer Abschnitt "Zeitsteuerung" mit Modus-Tabelle, Beispielen und den
  Punkten, ueber die man sonst stolpert
- Playlist-Abschnitt: Edit-Button gilt jetzt fuer alle Eintragstypen,
  "Zeit"-Badge erklaert
- Priority-Abschnitt: Zeitsteuerung steht dort ebenfalls zur Verfuegung

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

README.md

@@ -25,6 +25,7 @@ Browserbasiertes Digital-Signage-System für interne Info-Screens.
 - **Admin Dashboard**: `/admin/dashboard` – Statistiken (Sites, Screens, User, Admins, Superuser) mit Sparkline-Charts + Trendanzeige, Aktivitätsverlauf
 - **Aktivitätsverlauf**: Alle Erstell-/Lösch-/Änderungsaktionen sowie Login/Logout werden in `history.json` protokolliert und im Dashboard angezeigt
 - Tab-basierte Admin-UI pro Screen: Playlist, Einstellungen, Aktionen, Digital Voice Agent, Medien, Info (Tabler Tabs)
+- **Zeitsteuerung**: Pro Playlist-Eintrag (URL *und* Datei, auch in der Priority-Playlist) ein Zeitfenster festlegen – einmalig (Datum + Uhrzeit), täglich oder wöchentlich (Uhrzeit + optionaler Gültigkeitszeitraum, wöchentlich zusätzlich mit Wochentagen). Fenster über Mitternacht werden unterstützt. Ein "Zeit"-Badge in der Playlist-Zeile zeigt die Einstellung im Tooltip
 - **Query-Parameter-Passthrough**: Per Player-URL übergebene Query-Parameter (z. B. `/player/stuttgart/lobby?customer=acme`) können pro Playlist-URL im Edit-Modal aktiviert werden – standardmäßig aus. Link-Icon in der Playlist-Zeile zeigt Status (an/aus) an.
 - Priority-Seite ebenfalls mit Tabs: Playlist und Medien
 - Dark Mode (localStorage-persistiert)
@@ -194,6 +195,7 @@ Server läuft auf `http://localhost:5005` (gunicorn mit 4 Workern, non-root User
 | `POST /admin/<site>/add-url/<screen>` | URL zur Playlist hinzufügen |
 | `POST /admin/<site>/delete/<screen>/<filename>` | Datei löschen |
 | `POST /admin/<site>/playlist/<screen>` | Playlist-Reihenfolge speichern (JSON) |
+| `POST /admin/<site>/update-playlist-item/<screen>` | Einzelnen Playlist-Eintrag ändern: URL, Zoom, Passthrough, Zeitsteuerung (JSON) |
 | `POST /admin/<site>/delete-screen/<screen>` | Screen + Medien löschen |
 | `GET /admin/<site>/add-screen?name=<name>` | Neuen Screen anlegen |
 | `GET /add-site?name=<name>` | Neuen Standort anlegen |
@@ -404,7 +406,7 @@ OPENAI_API_KEY=sk-...
 
 | Feld | Typ | Beschreibung |
 |------|-----|-------------|
-| `playlist` | Array | Playlist-Einträge (Strings oder Dicts mit `url`/`zoom`) |
+| `playlist` | Array | Playlist-Einträge (Strings oder Dicts, siehe [Playlist-Einträge](#playlist-eintraege)) |
 | `interval` | int | Anzeige-Intervall in Sekunden |
 | `show_images` | bool | Bilder anzeigen |
 | `show_videos` | bool | Videos anzeigen |
@@ -422,6 +424,64 @@ OPENAI_API_KEY=sk-...
 | `voice_agent_target` | string | `"overlay"` (iframe) oder `"redirect"` |
 | `voice_agent_position` | string | Position des Buttons: `top-left`, `top-center`, `top-right`, `middle-left`, `middle-center`, `middle-right`, `bottom-left`, `bottom-center`, `bottom-right` |
 
+<a id="playlist-eintraege"></a>
+## Playlist-Einträge
+
+Ein Eintrag ist entweder ein String (Dateiname oder URL, Altbestand) oder ein Dict:
+
+```jsonc
+// URL-Eintrag
+{
+  "url": "https://example.com",
+  "zoom": 1.0,                    // Zoom-Faktor im Player
+  "enabled": true,                // Checkbox in der Playlist
+  "passthrough_params": false,    // Query-Parameter der Player-URL durchreichen
+  "schedule": { ... }             // optional, siehe unten
+}
+
+// Datei-Eintrag
+{
+  "name": "bild.jpg",
+  "enabled": true,
+  "schedule": { ... }             // optional
+}
+```
+
+### Zeitsteuerung (`schedule`)
+
+Optional pro Eintrag. Ohne `schedule` läuft der Eintrag immer (sofern `enabled`).
+
+| Feld | Typ | Beschreibung |
+|------|-----|-------------|
+| `mode` | string | `"once"`, `"daily"` oder `"weekly"` |
+| `start` / `end` | string | Bei `once` voller Zeitstempel (`"2026-09-10T08:00"`), bei `daily`/`weekly` nur die Uhrzeit (`"08:00"`) |
+| `days` | Array | Nur bei `weekly`: Wochentage als Strings, `"0"` = Montag … `"6"` = Sonntag |
+| `valid_from` | string | Optional, nur bei `daily`/`weekly`: Datum (`"2026-09-10"`), ab dem das Fenster gilt – inklusiv |
+| `valid_until` | string | Optional, nur bei `daily`/`weekly`: Datum, bis zu dem das Fenster gilt – inklusiv |
+
+```jsonc
+// Täglich 08:00–12:00, nur vom 10.09. bis 20.09.2026
+{ "mode": "daily", "start": "08:00", "end": "12:00",
+  "valid_from": "2026-09-10", "valid_until": "2026-09-20" }
+
+// Mo/Mi/Fr von 09:00 bis 17:00, unbefristet
+{ "mode": "weekly", "start": "09:00", "end": "17:00", "days": ["0", "2", "4"] }
+
+// Einmalig, durchgehend über mehrere Tage
+{ "mode": "once", "start": "2026-09-10T08:00", "end": "2026-09-20T12:00" }
+```
+
+**Verhaltensregeln:**
+
+- Bei `daily` und `weekly` zählt **nur die Uhrzeit** von `start`/`end`. Ein Gültigkeitszeitraum wird über `valid_from`/`valid_until` gesetzt, nicht über den Datumsanteil.
+- Bei `daily` sind **alle Wochentage** gemeint; `days` wird in diesem Modus nicht ausgewertet.
+- Ist `start` > `end`, läuft das Fenster **über Mitternacht** (z. B. `22:00`–`02:00`). Ein solches Fenster gehört zum Wochentag bzw. Gültigkeitstag seines **Starts**: „Mi 22:00–02:00" läuft Mittwochabend bis Donnerstagfrüh.
+- Unlesbare oder unvollständige Zeitangaben blenden den Eintrag **nicht** aus – ein Konfigurationsfehler soll nicht dazu führen, dass stillschweigend nichts mehr läuft.
+- `_schedule_time()` liest neben `"08:00"` auch volle ISO-Zeitstempel, damit Einträge aus älteren Versionen unverändert weiterlaufen.
+- Der Aktiv-Zustand fliesst in `/playlist/<site>/<screen>/hash` ein, damit der Player beim Öffnen und Schliessen eines Zeitfensters von selbst neu lädt.
+
+---
+
 ## Helper-Funktionen (`app.py`)
 
 - `load_config()` / `save_config()` – JSON lesen/schreiben
@@ -430,7 +490,11 @@ OPENAI_API_KEY=sk-...
 - `is_url(item)` – prüft ob Item eine URL ist
 - `normalize_url(item)` – normalisiert URL-Item zu `{"url", "zoom"}`
 - `playlist_item_name(item)` – Name aus String oder Dict extrahieren
-- `playlist_item_enabled(item)` – Enabled-Status prüfen
+- `is_item_active(item)` – prüft `enabled` **und** die Zeitsteuerung
+- `_schedule_time(value)` – Uhrzeit aus `"HH:MM"` oder vollem ISO-Zeitstempel lesen
+- `_window_start_date(now, start, end)` – Kalendertag, an dem das laufende Zeitfenster begann (`None` = ausserhalb)
+- `_in_validity_range(schedule, day)` – optionalen Gültigkeitszeitraum prüfen
+- `schedule_text(schedule)` – Jinja-Filter: Klartext einer Zeitsteuerung für Tooltips
 - `load_priority_files()` – Priority-Playlist + Dateien laden
 - `prio_redirect(site)` – Redirect-Pfad zur Priority-Seite
 - `get_background_url(site)` – URL zum benutzerdefinierten Hintergrundbild oder `None`

templates/help.html

@@ -51,6 +51,7 @@
               <a class="nav-link py-1 px-2 small" href="#help-standort"><i class="ti ti-building-community me-1"></i>Standort</a>
               <a class="nav-link py-1 px-2 small" href="#help-screen"><i class="ti ti-devices me-1"></i>Screen</a>
               <a class="nav-link py-1 px-2 small" href="#help-playlist"><i class="ti ti-list me-1"></i>Playlist</a>
+              <a class="nav-link py-1 px-2 small" href="#help-zeitsteuerung"><i class="ti ti-clock me-1"></i>Zeitsteuerung</a>
               <a class="nav-link py-1 px-2 small" href="#help-priority"><i class="ti ti-player-play me-1"></i>Priority</a>
               <a class="nav-link py-1 px-2 small" href="#help-actions"><i class="ti ti-external-link me-1"></i>Action Button</a>
               <a class="nav-link py-1 px-2 small" href="#help-voice"><i class="ti ti-robot me-1"></i>Voice Agent</a>
@@ -105,12 +106,67 @@
           <li><strong>Sortieren:</strong> Per Drag & Drop die Reihenfolge der Playlist-Einträge ändern (Ziehgriff links).</li>
           <li><strong>Deaktivieren:</strong> Mit der Checkbox einzelne Einträge temporär ausblenden.</li>
           <li><strong>Löschen:</strong> Über den roten Papierkorb-Button.</li>
+          <li><strong>Bearbeiten:</strong> Der <em>Edit</em>-Button öffnet einen Dialog. Bei URLs lassen sich dort Adresse, Zoom, Query-Parameter-Passthrough und Zeitsteuerung ändern; bei Bildern, Videos und HTML-Seiten die Zeitsteuerung.</li>
+          <li><strong>Zeitsteuerung:</strong> Einträge können nur zu bestimmten Zeiten laufen – siehe <a href="#help-zeitsteuerung">Zeitsteuerung</a>. Ein Badge <span class="badge bg-info text-white">Zeit</span> in der Playlist-Zeile zeigt an, dass ein Eintrag zeitgesteuert ist; der Tooltip nennt die Einstellung im Klartext.</li>
           <li><strong>Query-Parameter-Passthrough:</strong> Per URL-Edit-Button (Stift-Icon) im Playlist-Eintrag kann pro URL gesteuert werden, ob Query-Parameter von der Player-URL an die Playlist-URL übergeben werden. Standardmäßig <strong>aus</strong> – Checkbox "Query-Parameter an diese URL übergeben" aktivieren wenn gewünscht. Ein Link-Icon in der Playlist-Zeile zeigt den Status: <i class="ti ti-link"></i> = an, <i class="ti ti-link-off"></i> = aus.</li>
         </ul>
         <p class="text-muted small mb-0"><i class="ti ti-info-circle me-1"></i>Änderungen an der Playlist werden automatisch gespeichert. Der Player lädt die Seite automatisch neu (via Hash-Prüfung).</p>
       </div>
     </div>
 
+    <div class="card mb-3">
+      <div class="card-header"><h3 class="card-title" id="help-zeitsteuerung"><i class="ti ti-clock me-1"></i>Zeitsteuerung</h3></div>
+      <div class="card-body">
+        <p>Jeder Playlist-Eintrag – URL, Bild, Video oder HTML-Seite – kann nur zu bestimmten Zeiten laufen. Das gilt für die Playlist eines Screens genauso wie für die Priority-Playlist.</p>
+
+        <p><strong>Einstellen:</strong> beim Anlegen im Tab "Medien" unter <em>Zeitsteuerung</em>, oder nachträglich über den <em>Edit</em>-Button des Eintrags. Häkchen bei "Zeitgesteuerte Wiedergabe" setzen und einen Modus wählen:</p>
+
+        <table class="table table-sm">
+          <thead>
+            <tr><th style="width:110px">Modus</th><th>Bedeutung</th><th>Felder</th></tr>
+          </thead>
+          <tbody>
+            <tr>
+              <td><strong>Einmalig</strong></td>
+              <td>Läuft einmal in einem zusammenhängenden Zeitraum – auch über mehrere Tage am Stück.</td>
+              <td>Start und Ende jeweils mit Datum <em>und</em> Uhrzeit</td>
+            </tr>
+            <tr>
+              <td><strong>Täglich</strong></td>
+              <td>Läuft jeden Tag im selben Zeitfenster.</td>
+              <td>Von / Bis als Uhrzeit, optional "Gültig von / bis"</td>
+            </tr>
+            <tr>
+              <td><strong>Wöchentlich</strong></td>
+              <td>Wie täglich, aber nur an den angehakten Wochentagen.</td>
+              <td>Von / Bis als Uhrzeit, Wochentage, optional "Gültig von / bis"</td>
+            </tr>
+          </tbody>
+        </table>
+
+        <p><strong>Gültig von / bis</strong> ist optional und begrenzt, an welchen <em>Tagen</em> das Zeitfenster überhaupt greift. Beide Grenzen lassen sich einzeln setzen und zählen den genannten Tag mit. Ohne Angabe läuft die Wiedergabe unbefristet.</p>
+
+        <p class="mb-1"><strong>Beispiele:</strong></p>
+        <ul>
+          <li>Täglich, 08:00 bis 12:00, ohne Gültigkeitszeitraum → jeden Vormittag, unbefristet.</li>
+          <li>Täglich, 08:00 bis 12:00, gültig vom 10.09. bis 20.09. → nur an diesen elf Tagen.</li>
+          <li>Wöchentlich, 09:00 bis 17:00, Mo/Mi/Fr → nur an diesen drei Tagen während der Bürozeit.</li>
+          <li>Täglich, 22:00 bis 02:00 → abends bis in die Nacht hinein, über Mitternacht hinweg.</li>
+        </ul>
+
+        <p class="mb-1"><strong>Gut zu wissen:</strong></p>
+        <ul>
+          <li>Bei "Täglich" und "Wöchentlich" zählt nur die <em>Uhrzeit</em> – ein Datum wird ausschliesslich unter "Gültig von / bis" angegeben.</li>
+          <li>Bei "Täglich" gilt automatisch jeder Wochentag; die Auswahl der Wochentage erscheint deshalb nur bei "Wöchentlich".</li>
+          <li>Ein Fenster über Mitternacht gehört zum Tag seines <em>Starts</em>: "Mi 22:00–02:00" läuft Mittwochabend bis Donnerstagfrüh.</li>
+          <li>Die Checkbox links im Playlist-Eintrag wirkt weiterhin unabhängig davon – ein deaktivierter Eintrag läuft auch innerhalb seines Zeitfensters nicht.</li>
+          <li>Der Player merkt von selbst, wenn ein Zeitfenster beginnt oder endet, und lädt neu. Ein manueller Eingriff am Screen ist nicht nötig.</li>
+        </ul>
+
+        <p class="text-muted small mb-0"><i class="ti ti-info-circle me-1"></i>Es gilt die Uhrzeit des Servers, nicht die des Players.</p>
+      </div>
+    </div>
+
     <div class="card mb-3">
       <div class="card-header"><h3 class="card-title" id="help-priority"><i class="ti ti-player-play me-1"></i>Priority-Playlist</h3></div>
       <div class="card-body">
@@ -119,6 +175,7 @@
           <li>Aufruf über <code>/admin/&lt;standort&gt;/priority</code></li>
           <li>Globale Medien und URLs verwalten, ebenfalls per Drag & Drop</li>
           <li>Priority muss in der Konfiguration aktiviert sein (<code>config.json → priority.enabled</code>)</li>
+          <li>Die <a href="#help-zeitsteuerung">Zeitsteuerung</a> steht hier genauso zur Verfügung wie in den Screen-Playlists</li>
         </ul>
       </div>
     </div>