updating docs

docs/ADMIN_BUSINESS_LOGIC.md

@@ -0,0 +1,330 @@
+# Admin Business Logic — Leitfaden für Operatoren
+
+Dieses Dokument beschreibt die **Geschäftslogik der Bestellverwaltung** im Admin-Bereich. Es richtet sich an Operatoren, die Bestellungen im Alltag bearbeiten: Welche Status es gibt, was sie bedeuten, wo Bestellungen und Positionen angezeigt werden, und welche Aktionen wo möglich sind.
+
+Technische Details zum Kundenprozess (Checkout, E-Mail-Bestätigung) stehen in [ORDER_PROCESS.md](ORDER_PROCESS.md). Login und Admin-Konten: [ADMIN_SYSTEM.md](ADMIN_SYSTEM.md).
+
+---
+
+## Admin-Seiten im Überblick
+
+Vier Seiten sind für die Bestellbearbeitung relevant:
+
+| Seite | Datei | Rolle für Operatoren |
+| --- | --- | --- |
+| Dashboard | `admin/index.php` | Tagesübersicht, offene Arbeit, Statistik |
+| Bestellliste | `admin/orders.php` | Suchen, filtern, alle Bestellungen finden |
+| Bestelldetail | `admin/order.php` | Positionen bearbeiten, stornieren |
+| Nachbestellungen | `admin/backorders.php` | Externe Bestellung und Lieferung verwalten |
+
+Weitere Admin-Seiten (Produkte, Kategorien, Organisationen, FAQ, Einstellungen, Admins) haben **keinen Bezug** zu Bestellstatus oder -anzeige.
+
+---
+
+## Drei unabhängige Status-Dimensionen
+
+Eine Bestellung hat **keinen einzelnen Status**, sondern mehrere Felder, die unabhängig voneinander wirken:
+
+```mermaid
+flowchart TB
+    subgraph orderLevel [Bestellung]
+        confStatus["confirmation_status"]
+        opStatus["status"]
+    end
+    subgraph lineLevel [Position]
+        backorder["backorder_status"]
+        processed["is_processed"]
+    end
+    confStatus --> opStatus
+    backorder --> processed
+```
+
+- **Bestellung — Bestätigung** (`confirmation_status`): Hat der Kunde die E-Mail bestätigt? Blockiert Bearbeitung, solange unbestätigt oder abgelaufen.
+- **Bestellung — Bearbeitung** (`status`): Wie weit ist die Abarbeitung insgesamt? Wird automatisch aus den Positionen berechnet (`open`, `partial`, `processed`) oder manuell gesetzt (`cancelled`).
+- **Position — Nachbestellung** (`backorder_status`): Liegt der Artikel auf Lager oder muss extern nachbestellt werden?
+- **Position — Bearbeitet** (`is_processed`): Wurde diese Position ausgegeben/abarbeitet?
+
+In Tabellen und Listen erscheint **ein kombiniertes Anzeige-Label** (z. B. „Unbestätigt" oder „Offen"). Die Nachbestellung wird auf Positionsebene geführt und erscheint zusätzlich als Badge „Nachbestellung" auf der Detailseite, wenn mindestens eine Position einen Nachbestell-Status hat.
+
+---
+
+## Bestellstatus — was Operatoren sehen
+
+### Anzeige-Label in Listen und Dashboard
+
+Das sichtbare Label folgt einer **festen Priorität**. Höhere Priorität überschreibt niedrigere:
+
+| Anzeige-Label | Bedingung | Bedeutung für Operatoren |
+| --- | --- | --- |
+| **Storniert** | Bestellung storniert | Bestellung ist ungültig; nur „Stornierung aufheben" möglich |
+| **Unbestätigt** | E-Mail-Bestätigung ausstehend | Kunde hat noch nicht bestätigt; **keine Bearbeitung** möglich |
+| **Bestätigung abgelaufen** | Bestätigungsfrist abgelaufen | Kunde hat nicht rechtzeitig bestätigt; **keine Bearbeitung** möglich |
+| **Bearbeitet** | Alle Positionen bearbeitet | Bestellung abgeschlossen |
+| **Teilweise bearbeitet** | Mindestens eine, nicht alle Positionen bearbeitet | Bestellung in Arbeit |
+| **Offen** | Sonst | Noch keine Position bearbeitet |
+
+**Wichtig:** Die internen Werte `not_required` (Bestätigung nicht nötig) und `confirmed` (Kunde hat bestätigt) erscheinen **nie als eigenes Label**. Sobald keine Blockade durch Unbestätigt/Abgelaufen besteht, sehen Operatoren den operativen Status: Offen, Teilweise bearbeitet oder Bearbeitet.
+
+### Interne Bestätigungsstatus (Referenz)
+
+| Wert | Wann gesetzt | Operator-Relevanz |
+| --- | --- | --- |
+| `not_required` | Bestätigung in Einstellungen deaktiviert | Bestellung sofort bearbeitbar |
+| `pending` | Bestätigung aktiviert, Kunde hat noch nicht bestätigt | Label „Unbestätigt"; Bearbeitung gesperrt |
+| `confirmed` | Kunde hat per Link bestätigt | Bearbeitung freigegeben |
+| `expired` | Frist (`confirmation_expires_at`) überschritten | Label „Bestätigung abgelaufen"; Bearbeitung gesperrt |
+
+Auf der Detailseite sind ggf. sichtbar: Bestätigungsfrist (bei Unbestätigt), Bestätigungszeitpunkt, Zeitpunkt der internen Weiterleitung.
+
+### Interner Bearbeitungsstatus der Bestellung
+
+| Wert | Bedeutung | Wie gesetzt |
+| --- | --- | --- |
+| `open` | Keine Position bearbeitet | Automatisch |
+| `partial` | Einige Positionen bearbeitet | Automatisch |
+| `processed` | Alle Positionen bearbeitet | Automatisch |
+| `cancelled` | Bestellung storniert | Manuell durch Operator |
+
+Stornierte Bestellungen werden **nicht** automatisch aus Positionen neu berechnet. Nach „Stornierung aufheben" wird der Status wieder aus den Positionen abgeleitet.
+
+---
+
+## Positionsstatus — Bearbeitung und Nachbestellung
+
+### Bearbeitet (`is_processed`)
+
+- Pro Position auf der **Bestelldetail**-Seite umschaltbar: „Als bearbeitet markieren" / „Als offen markieren".
+- Steuert den Bestellstatus automatisch: keine Position bearbeitet → Offen; alle → Bearbeitet; dazwischen → Teilweise bearbeitet.
+
+### Nachbestellung (`backorder_status`)
+
+| Wert | Anzeige-Label | Bedeutung |
+| --- | --- | --- |
+| *(leer)* | — | Normale offene Position (Lager/Abgabe) |
+| `to_be_backordered` | Nachzubestellen | Position muss extern nachbestellt werden |
+| `ordered` | Wartet auf Lieferung | Extern bestellt, Lieferung steht aus |
+
+**Manuelle Nachbestellungen** (`data/manual_backorders.json`): Gleicher Ablauf wie bei Bestellpositionen, aber **ohne Kundenbestellung** — nur auf der Seite Nachbestellungen sichtbar und verwaltbar.
+
+---
+
+## Wo erscheint was?
+
+### Dashboard (`admin/index.php`)
+
+#### Statistik-Karten
+
+| Karte | Was gezählt wird |
+| --- | --- |
+| **Offen** | Bestellungen mit operativem Status `open`, **ohne** Unbestätigt; **inkl.** abgelaufener Bestätigungen (siehe Bekannte Unstimmigkeiten) |
+| **Teilweise bearbeitet** | `status = partial`, ohne Unbestätigt |
+| **Bearbeitet** | `status = processed`, ohne Unbestätigt |
+| **Storniert** | `status = cancelled` |
+| **Nachbestellung** | Summe aller Positionen in `to_be_backordered` oder `ordered` (inkl. manueller Nachbestellungen) |
+
+**Unbestätigte Bestellungen** (`pending`) werden in **keiner** Statistik-Karte gezählt.
+
+#### „Letzte offene Bestellungen" (max. 5)
+
+Eine Bestellung erscheint hier nur, wenn:
+
+1. Das Anzeige-Label **Offen** oder **Teilweise bearbeitet** ist (nicht Unbestätigt, nicht Abgelaufen, nicht Bearbeitet, nicht Storniert), **und**
+2. Mindestens **eine Position** existiert, die **nicht** bearbeitet ist **und** **keinen** Nachbestell-Status hat.
+
+Sortierung: neueste zuerst.
+
+#### „Offene Positionen"
+
+Eine Position erscheint hier nur, wenn:
+
+1. Die zugehörige Bestellung das Label **Offen** oder **Teilweise bearbeitet** hat, **und**
+2. Die Position **nicht** bearbeitet ist **und** **keinen** Nachbestell-Status hat.
+
+Sortierung: **älteste zuerst** (FIFO-Arbeitsliste).
+
+**Operator-Hinweis:** Positionen mit Nachbestell-Status (**Nachzubestellen** oder **Wartet auf Lieferung**) erscheinen **nirgends** auf dem Dashboard. Diese werden ausschließlich unter **Nachbestellungen** verwaltet.
+
+---
+
+### Bestellliste (`admin/orders.php`)
+
+Filter und Suchfeld (Bestellnummer):
+
+| Filter | Was angezeigt wird |
+| --- | --- |
+| **Alle** | Alle Bestellungen (inkl. Unbestätigt) |
+| **Unbestätigt** | `confirmation_status = pending` |
+| **Bestätigung abgelaufen** | `confirmation_status = expired` |
+| **Offen** | Nicht Unbestätigt **und** `status = open` |
+| **Teilweise bearbeitet** | `status = partial` |
+| **Bearbeitet** | `status = processed` |
+| **Storniert** | `status = cancelled` |
+
+Die Status-Spalte zeigt das **kombinierte Anzeige-Label** (Bestätigung hat Vorrang vor operativem Status).
+
+**Hinweis zum Filter „Offen":** Enthält auch Bestellungen mit abgelaufener Bestätigung, solange der operative Status `open` ist (siehe Bekannte Unstimmigkeiten).
+
+---
+
+### Bestelldetail (`admin/order.php`)
+
+Jede Bestellung ist immer über die Bestellliste oder Dashboard-Links erreichbar — unabhängig vom Status.
+
+| Aktion | Wann sichtbar / erlaubt |
+| --- | --- |
+| **Als bearbeitet / offen markieren** | Bestellung nicht storniert; nicht Unbestätigt; nicht Abgelaufen |
+| **Als Nachbestellung markieren / aufheben** | Wie oben; nur Wechsel zwischen *(leer)* und **Nachzubestellen** — **nicht** von **Wartet auf Lieferung** |
+| **Bestellung stornieren** | Nicht storniert; nicht vollständig Bearbeitet |
+| **Stornierung aufheben** | Bestellung storniert |
+
+Zusätzliches Badge **„Nachbestellung"**, wenn mindestens eine Position einen Nachbestell-Status hat.
+
+Positionen im Status **Wartet auf Lieferung** (`ordered`): Kein Nachbestell-Toggle auf der Detailseite — Weiterbearbeitung nur über **Nachbestellungen** („Lieferung eingetroffen").
+
+---
+
+### Nachbestellungen (`admin/backorders.php`)
+
+#### Was erscheint in der Liste?
+
+- Alle **manuellen** Nachbestell-Einträge mit Status Nachzubestellen oder Wartet auf Lieferung.
+- Bestellpositionen mit Nachbestell-Status, **ausgenommen** Bestellungen die:
+  - storniert sind, oder
+  - Unbestätigt sind, oder
+  - abgelaufene Bestätigung haben.
+
+Positionen werden nach **Produkt und Größe** gruppiert. Spalten **Nachzubestellen** und **Wartet auf Lieferung** werden getrennt gezählt.
+
+#### Bulk-Aktionen (FIFO — älteste zuerst)
+
+| Aktion | Wirkung |
+| --- | --- |
+| **Als bestellt markieren** | Verschiebt N Positionen von **Nachzubestellen** → **Wartet auf Lieferung** |
+| **Lieferung eingetroffen** | Setzt N Positionen von **Wartet auf Lieferung** → *(leer)*; Position bleibt offen zur normalen Abarbeitung auf der Detailseite |
+
+Manuelle Nachbestellungen können über ein Formular auf derselben Seite hinzugefügt werden.
+
+---
+
+## Sichtbarkeits-Matrix
+
+Übersicht: Wo erscheint ein Zustand?
+
+| Zustand / Bedingung | Dashboard-Statistik | Letzte offene Bestellungen | Offene Positionen | Bestellliste-Filter | Bestelldetail | Nachbestellungen |
+| --- | --- | --- | --- | --- | --- | --- |
+| **Unbestätigt** (`pending`) | — (nicht gezählt) | — | — | Unbestätigt, Alle | Ja (nur Ansehen) | — |
+| **Bestätigung abgelaufen** (`expired`) | Zählt als **Offen** | — | — | Abgelaufen, **auch Offen** | Ja (nur Ansehen) | — |
+| **Offen** (bestätigt/nicht nötig) | Offen | Ja*, wenn offene Positionen ohne NB | Ja*, pro Position | Offen, Alle | Ja, bearbeitbar | Ja, wenn NB markiert |
+| **Teilweise bearbeitet** | Teilweise | Ja*, wenn offene Positionen ohne NB | Ja*, pro Position | Teilweise, Alle | Ja, bearbeitbar | Ja, wenn NB markiert |
+| **Bearbeitet** | Bearbeitet | — | — | Bearbeitet, Alle | Ja (nur Ansehen) | Ja, wenn NB markiert |
+| **Storniert** | Storniert | — | — | Storniert, Alle | Ja (Stornierung aufheben) | — |
+| Position **Nachzubestellen** | In NB-Statistik | Position ausgeblendet | Position ausgeblendet | Bestellung in Liste | Toggle auf Detail | Ja |
+| Position **Wartet auf Lieferung** | In NB-Statistik | Position ausgeblendet | Position ausgeblendet | Bestellung in Liste | Kein Toggle auf Detail | Ja |
+| Nur NB-Positionen, Bestellung operativ **Offen** | Offen | — (keine qualif. Position) | — | Alle, Offen | Ja | Ja |
+| Manuelle Nachbestellung | In NB-Statistik | — | — | — | — | Ja |
+
+*NB = Nachbestell-Status. „Ja*" = nur wenn mindestens eine unverarbeitete Position **ohne** Nachbestell-Status existiert.
+
+---
+
+## Typische Operator-Workflows
+
+### 1. Neue bestätigte Bestellung abarbeiten
+
+1. **Dashboard** → „Offene Positionen" oder „Letzte offene Bestellungen" prüfen.
+2. **Details** öffnen.
+3. Pro Position **„Als bearbeitet markieren"**, sobald ausgegeben.
+4. Wenn alle Positionen bearbeitet: Status wechselt automatisch zu **Bearbeitet**.
+
+### 2. Artikel nicht auf Lager (Nachbestellung)
+
+1. **Bestelldetail** → Position **„Als Nachbestellung markieren"** (Status: Nachzubestellen).
+2. Position verschwindet aus Dashboard-Listen.
+3. **Nachbestellungen** → gruppiert nach Produkt/Größe → **„Als bestellt markieren"** (extern bestellt).
+4. Nach Lieferung: **„Lieferung eingetroffen"** → Position wieder normal offen.
+5. Zurück auf **Bestelldetail** → **„Als bearbeitet markieren"**.
+
+```mermaid
+stateDiagram-v2
+    direction LR
+    state backorder {
+        none --> toBeBackordered: Detail markieren
+        toBeBackordered --> ordered: Nachbestellungen bestellt
+        ordered --> none: Lieferung eingetroffen
+        toBeBackordered --> none: Detail aufheben
+    }
+```
+
+### 3. Unbestätigte Bestellung
+
+1. **Bestellliste** → Filter **Unbestätigt**.
+2. Abwarten, bis Kunde bestätigt, oder Frist abläuft.
+3. Nach Bestätigung: normal auf Dashboard sichtbar.
+4. Nach Ablauf: Label **Bestätigung abgelaufen** — keine Bearbeitung möglich.
+
+### 4. Manuelle Nachbestellung (ohne Kundenbestellung)
+
+1. **Nachbestellungen** → Formular „Manuelle Nachbestellung".
+2. Produkt, Größe, Anzahl wählen.
+3. Weiter wie Workflow 2 (bestellt → geliefert).
+
+### 5. Bestellung stornieren
+
+1. **Bestelldetail** → **„Bestellung stornieren"** (nicht möglich bei Status Bearbeitet).
+2. Optional Stornogrund angeben.
+3. Stornierte Bestellungen: Filter **Storniert** in der Bestellliste; **Stornierung aufheben** auf der Detailseite.
+
+---
+
+## Einstellungen mit Einfluss auf neue Bestellungen
+
+Unter **Einstellungen** (`admin/settings.php`):
+
+- **E-Mail-Bestätigung erforderlich**: Neue Bestellungen starten als **Unbestätigt** statt sofort bearbeitbar.
+- **Bestätigungsfrist (Tage)**: Nach Ablauf → **Bestätigung abgelaufen**.
+
+Diese Einstellungen betreffen nur **neu eingehende** Bestellungen, nicht bereits gespeicherte.
+
+---
+
+## Bekannte Unstimmigkeiten
+
+Die folgenden Punkte sind **keine Bedienanleitung**, sondern dokumentierte Abweichungen in der Anzeige-Logik. Sie können später im Code behoben werden.
+
+1. **`expirePendingOrders()` speichert Ablauf ggf. nicht dauerhaft**  
+   In `includes/functions.php`: Der Vergleich `$updated !== $order` ist bei Arrays per Referenz immer falsch. Abgelaufene Bestätigungen werden beim Lesen berechnet, `orders.json` kann aber weiterhin `pending` enthalten, bis eine andere Speicherung erfolgt.
+
+2. **Dashboard-Zähler „Offen" inkl. abgelaufener Bestätigungen**  
+   Abgelaufene Bestellungen erhöhen die Karte **Offen**, zeigen in Listen aber **Bestätigung abgelaufen** — die Zahl kann irreführend sein.
+
+3. **Filter „Offen" in der Bestellliste inkl. abgelaufener Bestätigungen**  
+   Der Filter schließt nur `pending` aus, nicht `expired`. Abgelaufene Bestellungen mit operativem Status `open` erscheinen unter **Offen** und **Bestätigung abgelaufen**.
+
+4. **Kein Dashboard-Zähler für Unbestätigt**  
+   Unbestätigte Bestellungen fehlen in allen Statistik-Karten; sie sind nur über Bestellliste → Filter **Unbestätigt** oder **Alle** auffindbar.
+
+5. **Bestellung nur mit Nachbestellpositionen**  
+   Operativer Status kann **Offen** bleiben (0 Positionen bearbeitet), aber alle Positionen haben Nachbestell-Status → Bestellung erscheint **nicht** in Dashboard-Tabellen, nur in **Alle** und **Nachbestellungen**.
+
+6. **Status „Wartet auf Lieferung" nicht auf Detailseite änderbar**  
+   Bewusste Trennung: Weiterführung nur über **Nachbestellungen**. Operatoren, die nur die Detailseite nutzen, finden keinen Button dafür.
+
+7. **Stornierte Bestellungen können Nachbestell-Flags in den Daten behalten**  
+   In der Nachbestellungen-Ansicht ausgeblendet, in den Rohdaten ggf. noch vorhanden.
+
+8. **Position bearbeitbar trotz Nachbestell-Flag**  
+   „Als bearbeitet markieren" löscht den Nachbestell-Status nicht automatisch. Umgekehrt blockiert ein gesetzter Nachbestell-Status auf bereits bearbeiteten Positionen keine erneute Markierung als offen/bearbeitet.
+
+9. **FIFO-Sortierung bei Bulk-Aktionen inkonsistent**  
+   Anzeige in Nachbestellungen sortiert u. a. nach `sort_at` (Bestell-/Bestellzeitpunkt). Bulk-Updates sortieren Kandidaten nur nach `created_at` — Reihenfolge kann bei „Wartet auf Lieferung" abweichen.
+
+10. **`MANUAL_BACKORDERS_FILE` fehlt in `config.sample.php`**  
+    Manuelle Nachbestellungen setzen die Konstante voraus; fehlt sie in der produktiven `config.php`, kann die Nachbestellungen-Seite fehlschlagen.
+
+---
+
+## Querverweise
+
+- [ORDER_PROCESS.md](ORDER_PROCESS.md) — Gesamtprozess von Bestellung bis Abarbeitung, E-Mail-Bestätigung, technische Abläufe
+- [ADMIN_SYSTEM.md](ADMIN_SYSTEM.md) — Admin-Login und Kontenverwaltung
+- [CONFIG_REFERENCE.md](CONFIG_REFERENCE.md) — Konfigurationsoptionen (sofern relevant für Betrieb)

docs/ORDER_PROCESS.md

@@ -93,7 +93,7 @@ Jede Bestellposition kann optional folgende Felder haben:
 
 In `admin/backorders.php` werden Positionen nach Produkt und Größe gruppiert. Die Spalten **Nachzubestellen** und **Wartet auf Lieferung** werden getrennt gezählt, damit neu markierte Artikel nicht mit bereits bestellten vermischt werden.
 
-Nachbestellte Positionen erscheinen weiterhin in **Offene Positionen** auf dem Dashboard, zusätzlich mit einem Nachbestell-Badge.
+Positionen mit Nachbestell-Status (**Nachzubestellen** oder **Wartet auf Lieferung**) erscheinen nicht in **Offene Positionen** auf dem Dashboard; sie werden über **Nachbestellungen** verwaltet.
 
 ## Abweichungen zum Standard-Webshop