# 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) 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.

---

## Zwei unabhängige Status-Dimensionen

Eine Bestellung hat **keinen einzelnen Status**, sondern mehrere Felder, die unabhängig voneinander wirken:

```mermaid
flowchart TB
    subgraph orderLevel [Bestellung]
        opStatus["status"]
    end
    subgraph lineLevel [Position]
        backorder["backorder_status"]
        processed["is_processed"]
    end
    backorder --> processed
```

- **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 Anzeige-Label** (z. B. „Offen" oder „Teilweise bearbeitet"). 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 |
| **Bearbeitet** | Alle Positionen bearbeitet | Bestellung abgeschlossen |
| **Teilweise bearbeitet** | Mindestens eine, nicht alle Positionen bearbeitet | Bestellung in Arbeit |
| **Offen** | Sonst | Noch keine Position bearbeitet |

Auf der Detailseite ist ggf. sichtbar: Zeitpunkt der internen Weiterleitung (`admin_notified_at`).

### 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` |
| **Teilweise bearbeitet** | `status = partial` |
| **Bearbeitet** | `status = processed` |
| **Storniert** | `status = cancelled` |
| **Nachbestellung** | Summe aller Positionen in `to_be_backordered` oder `ordered` (inkl. manueller Nachbestellungen) |

#### „Letzte offene Bestellungen" (max. 5)

Eine Bestellung erscheint hier nur, wenn:

1. Das Anzeige-Label **Offen** oder **Teilweise bearbeitet** ist (nicht Bearbeitet, nicht Storniert), **und**
2. Mindestens **eine Position** existiert, die **nicht** bearbeitet ist (unabhängig vom Nachbestell-Status).

Spalte **Nachbestellung:** Zusammenfassung der Nachbestell-Status aller **offenen** Positionen (`-`, ein Status-Badge, oder **Gemischt**).

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 (auch mit Nachbestell-Status).

Spalte **Nachbestellung:** pro Zeile **Nachzubestellen**, **Wartet auf Lieferung** oder `-`.

Sortierung: **älteste zuerst** (FIFO-Arbeitsliste).

Bulk-Aktionen für Nachbestellungen (als bestellt markieren, Lieferung eingetroffen) bleiben auf **Nachbestellungen**; das Dashboard dient der Übersicht und dem Sprung zur Bestelldetailseite.

---

### Bestellliste (`admin/orders.php`)

Filter und Suchfeld (Bestellnummer):

| Filter | Was angezeigt wird |
| --- | --- |
| **Alle** | Alle Bestellungen |
| **Offen** | `status = open` |
| **Teilweise bearbeitet** | `status = partial` |
| **Bearbeitet** | `status = processed` |
| **Storniert** | `status = cancelled` |

Die Status-Spalte zeigt das **Anzeige-Label** aus dem operativen Bestellstatus.

---

### 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 |
| **Als Nachbestellung markieren / aufheben** | Bestellung nicht storniert; nur Wechsel zwischen *(leer)* und **Nachzubestellen** — **nicht** von **Wartet auf Lieferung** |
| **Bestellung stornieren** | Nicht storniert; nicht vollständig Bearbeitet; löscht auf allen Positionen Nachbestell-Status und zugehörige Zeitstempel |
| **Stornierung aufheben** | Bestellung storniert |

Zusätzliches Badge **„Nachbestellung"**, wenn mindestens eine Position einen Nachbestell-Status hat (nicht bei stornierten Bestellungen, sofern beim Stornieren zurückgesetzt).

**Bearbeitet + Nachbestellung:** Eine Position kann als **bearbeitet** markiert sein und gleichzeitig einen Nachbestell-Status behalten (z. B. Retoure deckt die Bestellung ab, während die Nachbestellung auf Lieferantenware wartet). „Als bearbeitet markieren" löscht den Nachbestell-Status **nicht**. Umgekehrt: **Nachzubestellen** kann nicht auf bereits bearbeitete Positionen gesetzt werden.

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** stornierte Bestellungen.

Positionen werden nach **Produkt und Größe** gruppiert. Spalten **Nachzubestellen** und **Wartet auf Lieferung** werden getrennt gezählt.

#### Bulk-Aktionen (FIFO — älteste zuerst)

Kandidaten und Anzeige-Reihenfolge nutzen dieselbe Sortierung nach `sort_at` (u. a. `backordered_at` / `ordered_at`, sonst Bestelldatum).

| 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 |
| --- | --- | --- | --- | --- | --- | --- |
| **Offen** | 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 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. Manuelle Nachbestellung (ohne Kundenbestellung)

1. **Nachbestellungen** → Formular „Manuelle Nachbestellung".
2. Produkt, Größe, Anzahl wählen.
3. Weiter wie Workflow 2 (bestellt → geliefert).

### 4. 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`):

- **Empfängeradresse für interne Bestellmails**
- **PDF an interne Bestell-E-Mails anhängen**

---

## Bekannte Unstimmigkeiten

Die folgenden Punkte sind **keine Bedienanleitung**, sondern dokumentierte bewusste Einschränkungen.

1. **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.

---

## Querverweise

- [ORDER_PROCESS.md](ORDER_PROCESS.md) — Gesamtprozess von Bestellung bis Abarbeitung, 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)