MABEA/ergebnisse/testphasen.md

# Testphasen – MABEA V1

Bezug: [[22_testkonzept]], [[18_version_1]], [[02_prozess_kontrolle]], [[03_fehlbestandsmanagement]], [[04_mindermengen]], [[05_rollen_rechte]], [[17_mobile_offline]], [[21_api]].

Grundprinzip: Tests werden **phasenweise** aufgebaut, parallel zur Implementierung – nicht als Block am Ende. Jede Phase hat Einstiegs- und Abnahmekriterien. Der Satelliten-Betrieb (Karte 13) ist bewusst **nicht** Teil der V1-Testphasen, sondern eigene spätere Phase S (Roadmap).

## Phase 0 – Testinfrastruktur (vor erstem Feature-Code)

**Ziel:** Gerüst steht, bevor Logik entsteht – verhindert „Tests schreiben wir später".

- pytest + pytest-asyncio + httpx (AsyncClient für FastAPI) im Projekt
- pytest-cov mit Regressions-Gate: `--cov-fail-under=50` als Startwert in `pytest.ini` (Erfahrungswert: lieber niedrig starten und hochschrauben als gar kein Gate)
- Separate **Test-Datenbank** (eigene PostgreSQL-Datenbank, Schema via Alembic-Migrationen aufgesetzt, nie gegen Dev-/Produktiv-DB)
- Test-Fixtures: frische DB pro Testklasse (Transaction-Rollback oder Drop/Create), Standard-Stammdaten-Set (1 Bereich, 2 Standorte, 3 Objekttypen, ~10 Materialien aller 3 Typen, 1 Vorlage mit Positionen, 2 Objekte, 4 Benutzer = 1 je Rolle)
- CI-Job (Gitea Actions): install → migrate → pytest → Coverage-Report; Blocker bei Rot
- **Seed-Datensatz `systemknoten`:** `objekt.zustaendiger_server_id`, `kontrolle.erzeugt_von_server_id`, `fehlbestand.erzeugt_von_server_id`, `historie.erzeugt_von_server_id` sind NOT NULL (Prompt 20) – V1 braucht daher zwingend einen Seed-Datensatz `systemknoten (typ='haupt')` VOR dem ersten Datensatz jeder Art, plus eine Konfigurations-Referenz im Backend (z. B. Umgebungsvariable/Settings-Wert `SYSTEMKNOTEN_ID`), die der Anwendungscode bei jedem Insert einsetzt. Ohne diesen Seed schlägt der allererste Insert fehl – gehört in die Migrations-/Setup-Reihenfolge von Phase 0, nicht erst bei Satelliten-Umsetzung (Phase S) relevant.

**Abnahmekriterium:** `pytest` läuft grün (auch wenn erst 1 Smoke-Test existiert), CI schlägt bei Testfehler fehl.

## Phase 1 – Domänenlogik (Unit-Tests, keine API, keine UI)

**Ziel:** Die fachlichen Leitplanken sind bewiesen, bevor irgendein Endpoint existiert. Reine Python-Tests gegen den Service-Layer (Prompt 19 Punkt 2), DB über Fixtures.

Kritischste Regeln zuerst (aus `reihenfolge.md` und Prompt 03/04):

| # | Test | Herkunft |
|---|------|----------|
| U1 | Fehlbestand entsteht automatisch bei Ist < Soll | Prompt 02.3 |
| U2 | Mindermengen-Genehmigung ändert NIEMALS Ist-Menge und setzt Fehlbestand NIEMALS auf erledigt | Leitplanke, Prompt 04.1 |
| U3 | Fehlbestand → erledigt AUSSCHLIESSLICH wenn Ist = Soll (nie manuell) | Prompt 03.3 |
| U4 | Sofort-Nachfüllung in Kontrolle: Fehlbestand entsteht + wird erledigt, 2 Historieneinträge | Karte 07 |
| U5 | Teilnachfüllung: Status `nachgefuellt_teilweise`, Fehlmenge reduziert, zählt weiter als offen | Prompt 03/12 |
| U6 | Genehmigung läuft bei nächster Kontrolle des Objekts automatisch ab | Karte 08, Prompt 04.4 |
| U7 | Genehmigung + Behebung vor nächster Kontrolle → beides gemeinsam beendet | Prompt 04.4 |
| U8 | Soll-Auflösung: Override auf Objektposition schlägt Vorlagenwert; Vorlagenänderung wirkt nur auf Positionen ohne Override | Prompt 10 |
| U9 | Duplizieren: Struktur/Soll ja, Ist/SN/Chargen/Fehlbestände/Historie nein, neuer Code | Prompt 09 |
| U10 | Vorlagenänderung erzeugt neue Version, alte Version bleibt lesbar (Snapshot-Historie) | Prompt 08 |
| U11 | Kontrolle abschließen mit unbestätigten Positionen → Fehler | Prompt 16.1 |
| U12 | Abgebrochene Kontrolle: keine Ist-Übernahme, kein Fehlbestand, Objekt bleibt unkontrolliert | Prompt 16.6 |
| U13 | Überbestand (Ist > Soll): protokolliert, aber KEIN Fehlbestand | Prompt 02.4 |
| U14 | Historie ist append-only: jeder fachliche Schritt erzeugt Eintrag mit wer/wann/alt→neu | Prompt 13 |

**Einstiegskriterium:** Phase 0 fertig.
**Abnahmekriterium:** U1–U14 grün, Coverage Service-Layer ≥ 80 % (Domänenlogik ist der sicherheitskritische Kern).

## Phase 2 – API-Integrationstests (HTTP gegen Test-DB)

**Ziel:** Jeder Endpoint aus Prompt 21 verhält sich spezifikationsgemäß, inkl. Rollenmatrix und Fehlerfälle.

- **Auth:** Login ok/falsch (401), Token abgelaufen, `auth/me` liefert korrekte Rollen
- **Rollenmatrix (Prompt 05):** parametrisierter Test – jede Rolle × jede kritische Aktion → erwarteter Status (200er/403). Das ist EIN Test mit Tabelle, deckt Matrix vollständig ab
- **Fehlerfälle aus Prompt 21.9:** Genehmigung ohne Begründung → 422; Genehmigung durch Mitarbeiter → 403; Abschluss mit offenen Positionen → 409 + Liste; Code-Duplikat beim Anlegen/Duplizieren → 409
- **Idempotenz PUT Kontrollposition:** derselbe PUT zweimal gesendet → identischer Endzustand, kein doppelter Fehlbestand (Vorbereitung Prompt 17)
- **Zuständigkeitsfilter (Karte 04):** Verantwortlicher sieht nur Fehlbestände seines Bereichs, Administration alles
- **Objekt-Sperre (Prompt 02.8):** Kontrolle auf Objekt A aktiv → zweiter Benutzer bekommt „wird kontrolliert von …", Übernahme erzeugt Historieneintrag; parallele Kontrollen auf Objekt B bleiben möglich
- **Admin-API (7a):** Benutzer/Zuständigkeiten/Kontrollverantwortung anlegen, ändern, löschen

**Einstiegskriterium:** Phase 1 grün.
**Abnahmekriterium:** alle Endpunkte aus Prompt 21 durch Tests abgedeckt, Gesamt-Coverage ≥ 50 % (Gate greift).

## Phase 3 – Prozess-Szenarien (E2E über API, komplette fachliche Ketten)

**Ziel:** Die 17 Testfälle aus [[22_testkonzept]] als durchspielbare Szenarien – hier wird bewiesen, dass die Einzelteile zusammenwirken.

- S1–S17 = exakt die Testfälle 1–17 aus Prompt 22 (Normalfall, Fehlbestand, Sofort-Nachfüllung, Nachfüllung später, Teilnachfüllung, Dauer-offen, Genehmigung, Ablauf Genehmigung ×2, Ablaufdatum, Duplizieren, Override, Vorlagenänderung mit Override, Rollenmatrix, Historie-Kette, Kurzzeit-Netzausfall, Abbruch)
- Besonderheit S15 (Historie-Kette): komplette Kette aus Prompt 13.3 durchlaufen und Reihenfolge + Referenzen aller Historieneinträge prüfen
- Besonderheit S16 (Netzausfall): clientseitig simuliert – PUT zweimal absetzen bzw. verzögert, Server-Verhalten muss identisch sein

**Einstiegskriterium:** Phase 2 grün.
**Abnahmekriterium:** S1–S17 grün, zweimal reproduzierbar (kein Flaky).

## Phase 4 – Frontend/PWA-Tests

**Ziel:** Die Einsatzumfeld-Anforderungen (Prompt 11, 17) sind bewiesen.

- **Kurzzeit-Netzausfall:** Eingabe wird lokal gepuffert, nach Reconnect automatisch übertragen, Abschluss blockiert solange ungesendete Positionen existieren (Prompt 17.3) – Browser-Test mit Netzwerk-Throttling/Offline-Toggle (Playwright)
- **Responsivität:** Kernscreens (Screen 1–6) auf PC + Tablet + Smartphone-Viewport bedienbar, Touch-Ziele groß genug
- **Fortschrittsanzeige + Gerätewechsel:** Kontrolle auf Gerät 1 begonnen, auf Gerät 2 fortgesetzt (login-/objektgebunden, Karte 06)
- **Statusfarben/Markierungen:** genehmigte Mindermenge, individuelle Abweichung, Ablaufdatum-Warnung sichtbar unterscheidbar
- **Manuelle Explorations-Session:** 2–3 Praktiker aus dem Rettungsdienst klicken ohne Anleitung durch eine Kontrolle – Beobachtung dokumentieren (UX-Fallen)

**Einstiegskriterium:** Phase 3 grün, PWA bedienbar auf Test-Deployment.
**Abnahmekriterium:** Netzausfall-Test grün, keine kritischen UX-Befunde offen.

## Phase 5 – Pilotphase mit Echtdaten (organisatorisch, kein Code-Test)

**Ziel:** Realitätsabgleich, bevor Papier abgeschaltet wird.

- Testdaten aus den **echten Excel-Listen** (Handball Rucksack.xlsx, Rettungsrucksack.xlsx, Rucksack PAX SEG.xlsx im Repo) als initiale Vorlagen/Materialstamm importieren (Mapping siehe Abschnitt „Excel-Import-Mapping" unten)
- 1–2 Wochen **Parallelbetrieb**: Kontrolle digital UND Papier wie bisher, danach Abgleich (findet das System alles, was Papier fand?)
- Dedizierte Übungskontrollen mit vorher verabredeten Abweichungen („versteckte Fehlmenge") – prüft, ob Mitarbeiter den digitalen Weg korrekt durchlaufen
- E-Mail-Benachrichtigung (Karte 05) mit realem Mailserver verifizieren
- Feedback-Runde → kleinteilige UI-Nachjustierung

**Einstiegskriterium:** Phase 4 grün, Echtdaten importiert, Test-Deployment erreichbar.
**Abnahmekriterium (Go/No-Go für V1):** Parallelbetrieb ohne fachliche Diskrepanz, keine Datenverluste, Akzeptanz bei Pilotnutzern vorhanden.

## Excel-Import-Mapping (Detail zu Phase 5)

Grundlage: die drei bestehenden Listen im Repo (`Handball Rucksack.xlsx`, `Rettungsrucksack.xlsx`, `Rucksack PAX SEG.xlsx`), Struktur laut Ausgangsanalyse (Prompt 01): Fach-Überschriftzeile, darunter Zeilen mit Artikel/Menge/Artikelnummer, teils Seriennummer-Spalte.

### Mapping-Tabelle

| Excel-Spalte/Struktur | Ziel im Datenmodell (Prompt 06/20) | Hinweis |
|---|---|---|
| Datei selbst (z. B. „Handball Rucksack") | `objekttyp.name` + `beladungsvorlage.name` (z. B. „Rucksack Handball Standard") | Ein Import-Lauf pro Datei erzeugt einen Objekttyp + eine Vorlage Version 1 |
| Fach-Überschriftzeile (z. B. „Fach 1") | `vorlagenposition.fach` | Freitext übernehmen wie in Excel geschrieben, keine Normalisierung nötig |
| Artikel-Spalte | `material.name` (neu anlegen, falls Name noch nicht im Materialstamm existiert) | Abgleich über den Namen - die drei Listen haben **keine** echte Artikelnummer-Spalte (Korrektur, siehe unten), Tippfehler-Risiko bleibt manuelle Review-Pflicht |
| Menge-Spalte | `vorlagenposition.sollmenge` | Numerisch parsen, Fehleinträge (z. B. „ca. 5") vor Import manuell bereinigen |
| Spalte D (Excel-Zellformat: Datum) | Materialtyp-Erkennung: plausibles Ablaufdatum (Jahr ~2015-2039) in dieser Zeile → `material.materialtyp = 'ablauf_charge'` | Korrektur: ursprünglich fälschlich als Artikelnummer gemappt, siehe „Bekannte Lücken" unten. Datum selbst wird NICHT gespeichert (gehört auf `objektposition`, nicht auf die Vorlage - Ablaufdatum ist pro physischem Exemplar, nicht pro Soll-Position) |
| Seriennummer-Spalte (falls vorhanden) | Materialtyp-Erkennung: Vorhandensein einer SN-Spalte bei dieser Zeile → `material.materialtyp = 'geraet_sn'` (hat Vorrang vor Ablaufdatum-Erkennung) | |
| Einheit | nicht in Excel vorhanden | Beim Import Standardwert „Stück" setzen, danach manuell korrigieren wo nötig (z. B. „Paar", „Packung") |
| Kategorie/Bereich | nicht in Excel vorhanden | Einmalig vor Import anlegen: 1 Bereich „Rettungsdienst/KatS", grobe Kategorie „Rucksäcke" für alle drei Objekttypen |

### Ablauf des Imports (Vorschlag, Umsetzung Phase 5)

1. Bereich + Kategorie einmalig anlegen (Administration, manuell oder Skript).
2. Je Excel-Datei: Objekttyp + Beladungsvorlage Version 1 anlegen.
3. Zeilen einlesen (stdlib `zipfile`/`xml.etree.ElementTree` wie bei der Erstanalyse, siehe Prompt 01 – kein `openpyxl` nötig): Fach, Artikel, Menge, Ablaufdatum-Hinweis (Spalte D), optionale SN-Spalte.
4. Je Zeile: Material anhand des Namens suchen oder neu anlegen, dann Vorlagenposition mit Sollmenge und Fach erzeugen.
5. Konkrete Objekte (z. B. „Rucksack Handball 12", „Rucksack Handball 17") werden NICHT aus Excel importiert (Excel enthält nur die Soll-Struktur, keine konkreten Instanzen) – Administration legt sie danach manuell an, je mit Code (Karte 10) und Vorlagen-Referenz.
6. Erste Kontrolle je neu angelegtem Objekt erfasst den tatsächlichen Ist-Bestand (Objekte starten „nicht kontrolliert", analog Duplizieren-Regel Prompt 09) – dies IST der Übergang vom Papier- zum Digitalbetrieb (Prompt 23).

### Bekannte Lücken, vor Import zu klären
- Einheiten pro Material sind in den Excel-Listen nicht erfasst – vor Import Liste durchgehen und einmalig ergänzen (einmaliger manueller Aufwand, keine Systemfrage).
- Import-Skript selbst ist Code (Prompt-19-Deployment-Regel gilt: bei Umsetzung nur Skript-Datei erzeugen, Ausführung gegen Test-DB erst auf Zielsystem/Test-Deployment, nicht lokal).
- **Korrektur (nach echtem Import-Lauf, vom Nutzer anhand "Kompresse 10x10 / 5 / Apr 29" bemerkt):** Spalte D wurde ursprünglich fälschlich als Artikelnummer gemappt. Vollständige Prüfung aller drei Listen zeigt: D ist bei den meisten Zeilen ein echtes Excel-Datum (z. B. 47209 → 2029-04-01, angezeigt „Apr 29") - ein Ablaufdatum-Hinweis, keine Artikelnummer. Es gibt in den drei Listen **keine** Artikelnummer-Spalte; Material-Abgleich läuft daher über den Namen. Ausnahmen in den Rohdaten: der Wert 12754 (→ 1934-12-01) wiederholt sich identisch bei mehreren unterschiedlichen Artikeln und ist offensichtlich kein echtes Datum, sondern ein Platzhalter/Fehlwert; vereinzelt steht in Spalte D auch Freitext („Jahr 2023", „MTK 23"). Das Importskript (`backend/scripts/import_excel.py`) akzeptiert daher nur Werte in einem plausiblen Jahresfenster (~2015-2039) als Ablaufdatum-Hinweis und nutzt sie ausschließlich zur `materialtyp`-Klassifikation (`ablauf_charge`) - das konkrete Datum selbst wird nicht gespeichert (gehört auf `objektposition`, nicht auf die Vorlage).
- Bereits mit der alten (falschen) Logik importierte Test-Daten auf dem Zielsystem enthalten fehlerhafte `material.artikelnummer`-Werte (die eigentlich Datums-Rohwerte waren) und teils falschen `materialtyp` (`standard` statt `ablauf_charge`) - Bereinigung/Neu-Import auf dem Testsystem nötig, siehe Projekt-Historie.
- Gleiches Material kommt in einer Liste teils in mehreren Fächern vor (z. B. Verbandsmaterial in mehreren Taschen) - da `vorlagenposition` nur eine Zeile pro Material+Vorlage zulässt (Prompt 20-Schema), führt das Importskript solche Duplikate zusammen (Mengen addiert, Fächer als Liste), erste Erkenntnis erst beim echten Import-Lauf gegen den Zielserver, nicht vorher erkannt.

## Regeln übergreifend

- **Kein Feature ohne Test:** jeder Endpoint/jede Domänenregel wird erst mit Test gemerged (CI-Gate).
- **Leitplanke-Doppelschutz:** U2/U3 (Mindermenge ≠ erledigt) laufen zusätzlich als Phase-3-Szenario (S7) – bei Bruch dieser Regel sofortiger Release-Blocker.
- **Coverage-Hochschraubung:** nach V1-Release Gate schrittweise 50 → 60 → 70 % erhöhen.
- **Testdaten niemals Produktivdaten:** Pilotphase läuft auf Test-Deployment, echte Inbetriebnahme erst nach Go/No-Go.

## Phase S – Satelliten-Betrieb (spätere Erweiterung, NICHT V1)

Roadmap-Phase, erst nach stabiler V1. Eigener Testplan nötig, mindestens:

- **PoC mit zwei lokalen PostgreSQL-Instanzen** (Docker oder zwei Datenbanken): Objekt auslagern → Kontrolle + Fehlbestand + Nachfüllung + Genehmigung am „Satelliten" → zurücksyncen → Hauptserver-Stand vollständig und ohne Duplikate
- Sync-Fälle 1–3 aus Prompt 20.10 einzeln beweisen (Insert neue Zeilen, Upsert Objektpositionen, Upsert Fehlbestand/Genehmigung)
- Bestückungsregel testen: Objekt mit offenem Fehlbestand auslagern → am Satelliten nachfüllen → zurücksyncen → genau EIN Fehlbestand, erledigt
- Schreibzugriff am Hauptserver auf ausgelagertes Objekt → muss abgelehnt werden
- Offene Punkte aus Karte 13 vorher entscheiden: Pre-Sync-Check laufender Kontrollen, DB-Trigger für `zuletzt_geaendert_am`, Bestückungs-Details

## Referenzen
Bezug: [[22_testkonzept]], [[18_version_1]], [[01_anforderungsanalyse]], [[09_duplizieren]], [[23_papieraloesung]], [[13_satelliten_server]]