User Stories — Epic 5: Logistik & Tracking#

Pilot/Format-Muster. Methodik: Connextra (Als/möchte/damit) + Gherkin-Akzeptanzkriterien (Gegeben/Wenn/Dann) + INVEST-Qualitätsgate. Sprache der Stories DE; Fachbegriffe/Status wie im Schema. Bezug: Modul 5 (14-logistik-tracking.md), Schema Dok 30 §7, RLS Dok 30 §13. Rollen-Codes kanonisch (UPPERCASE): ADMIN, OPERATIONS, FAHRER, BUCHHALTUNG, READONLY. IDs: US-LOG-NN (stabil). Status: Entwurf (zur Freigabe).

Personas in diesem Epic#

INVEST-Gate (für alle Stories dieses Epics geprüft): jede Story ist unabhängig schneidbar, verhandelbar, liefert Geschäftswert, schätzbar, klein genug für einen Schritt und über die Gherkin-Szenarien testbar (inkl. Negativfälle/RLS).

US-LOG-01 — Boxen aus Auftrag materialisieren#

Als OPERATIONS möchte ich aus einem angenommenen Auftrag die einzelnen Boxen mit eindeutiger UUID + QR erzeugen, damit jede Transporteinheit ab dem Lager lückenlos verfolgbar ist.

Akzeptanzkriterien

• Gegeben ein Auftrag im Status ANGENOMMEN, wenn ich „Boxen erzeugen" auslöse, dann wird je bestellter Box ein boxes-Datensatz mit eigener UUID (= QR-Inhalt), fortlaufender box_no und Status EMPTY_DELIVERED angelegt.
• Gegeben ein Auftrag, der nicht ANGENOMMEN ist, wenn ich „Boxen erzeugen" auslöse, dann wird die Aktion abgelehnt (keine Materialisierung vor Auftragsannahme).
• Gegeben bereits materialisierte Boxen eines Auftrags, wenn ich erneut auslöse, dann werden keine Duplikate erzeugt (idempotent).

Traceability: boxes (§7), Workflow §4.1.

US-LOG-02 — Transport-Etikett (QR) drucken#

Als OPERATIONS möchte ich für jede Box ein Etikett mit QR-Code (und optional GS1-128/SSCC) drucken, damit die Box physisch scanbar ist.

Akzeptanzkriterien

• Gegeben eine materialisierte Box, wenn ich das Etikett drucke, dann enthält es den QR (UUID), box_no, Auftrags-/Empfängerbezug und ist mobil-tauglich (Batch-Druck mehrerer Boxen möglich).
• Gegeben app_settings.gs1_sscc_enabled = true und eine gesetzte GCP, wenn ich drucke, dann trägt das Etikett zusätzlich den GS1-128-Barcode mit (00)-SSCC (§12).
• Gegeben GS1 ist nicht aktiv, wenn ich drucke, dann bleibt es beim QR (UUID) — kein Fehler.

Traceability: §4.1.4, §12 (SSCC).

US-LOG-03 — Box packen & wiegen (CH)#

Als OPERATIONS möchte ich Box-Typ, Inhalt und CH-Gewicht erfassen, damit Preis-, Zoll- und Nachweisdaten vollständig sind.

Akzeptanzkriterien

• Gegeben eine Box vor CONTAINER_LOADED, wenn ich box_product_id, content_note und weight_kg setze, dann werden die Werte gespeichert.
• Gegeben Produkt OTRO (Freimaß), wenn ich packe, dann sind zusätzlich length_cm/width_cm/height_cm pro Box erfassbar (für den Volumen-Tarif).
• Gegeben eine Box ab CONTAINER_LOADED, wenn ich Stammdaten ändern will, dann wird die Änderung abgelehnt (Stammdaten read-only, §11.3) — Ausnahme weight_rd_kg.

Traceability: boxes.weight_kg/*_cm (§7), Sperr-Invariante §11.3.

US-LOG-04 — Status per QR-Scan fortschreiben#

Als OPERATIONS/FAHRER möchte ich den Box-Status per QR-Scan setzen, damit der Tracking-Verlauf in Echtzeit und revisionssicher entsteht.

Akzeptanzkriterien

• Gegeben eine Box, wenn ich einen gültigen Vorwärts-Schritt scanne, dann schreibt fn_record_tracking_event() atomar ein tracking_events-Event (Actor + Zeitstempel) und aktualisiert boxes.current_status.
• Gegeben ein Rückwärts-/Sprung-Schritt, wenn ich scanne, dann wird er abgelehnt — außer mit allow_out_of_order + Begründung (nur ADMIN/OPERATIONS).
• Gegeben ein Offline-Scan, der doppelt synchronisiert wird (gleiche client_event_id), dann entsteht kein Duplikat und kein Fehler (idempotent).

Traceability: tracking_events, fn_record_tracking_event (§4.2). (Deckt Audit-Härtung data-08 ab.)

US-LOG-05 — Massen-Statuswechsel#

Als OPERATIONS möchte ich mehrere Boxen gleichzeitig auf einen Status setzen, damit ich Sammelvorgänge (z.B. „ins CH-Lager") effizient erfasse — ohne Audit-/Benachrichtigungslücke.

Akzeptanzkriterien

• Gegeben eine Auswahl Boxen, wenn ich einen Bulk-Statuswechsel auslöse, dann erzeugt fn_bulk_track() pro Box ein reguläres tracking_events-Event — mit denselben Folgen wie der Einzelscan (Audit + Notification-Matrix + Reihenfolge-Validierung).
• Gegeben einzelne Boxen, die den Schritt nicht erlauben, wenn der Bulk läuft, dann werden nur diese übersprungen und in einem Sammel-Fehlerbericht ausgewiesen (kein stilles Überspringen).

Traceability: §11.2 (BR-16).

US-LOG-06 — Box in Container verladen#

Als OPERATIONS möchte ich Boxen einem See-Container zuordnen, damit die Verschiffung gebündelt und nachverfolgbar ist.

Akzeptanzkriterien

• Gegeben Boxen im CH-Lager, wenn ich sie einem Container zuweise, dann wird boxes.container_id gesetzt und ein Bulk-Event CONTAINER_LOADED geschrieben.
• Gegeben eine verladene Box, wenn danach jemand Box-Stammdaten ändern will, dann sind diese read-only (Korrektur nur via Rückwärts-Event, US-LOG-14).
• Gegeben ein Container mit Kapazitätsgrenze, wenn die Auslastung überschritten würde, dann erscheint eine Warnung.

Traceability: containers, boxes.container_id (§7), §11.3.

US-LOG-07 — Verschiffung & DR-Zoll#

Als OPERATIONS möchte ich den Container-Lebenszyklus bis zur Zollabfertigung in der DR abbilden, damit alle Beteiligten den Phasenstatus sehen.

Akzeptanzkriterien

• Gegeben ein beladener Container, wenn ich ihn als verschifft markiere (BL-Nr. erfasst), dann wechseln die Boxen über SHIPPED → IN_TRANSIT und containers.bl_number ist gesetzt.
• Gegeben Ankunft + Zollfreigabe, wenn ich „verzollt" setze, dann wechseln die Boxen auf DR_CUSTOMS und containers.cleared_at ist gesetzt.

Traceability: containers (§7), Status-Modell §3.1.

US-LOG-08 — RD-Nachwiegung#

Als OPERATIONS (DR-Seite) möchte ich das in der DR nachgewogene Gewicht erfassen, damit Zoll/Nachweis die Gewichtsdifferenz CH↔RD belegen können.

Akzeptanzkriterien

• Gegeben eine Box ab DR_CUSTOMS, wenn ich weight_rd_kg erfasse, dann wird es gespeichert — auch wenn die übrigen Stammdaten gesperrt sind.
• Gegeben weight_rd_kg, dann fließt es nicht in die Preisberechnung ein (nur Doku/Zoll).

Traceability: boxes.weight_rd_kg (§7), §11.2.

US-LOG-09 — Zustellung mit Liefernachweis#

Als FAHRER möchte ich die Zustellung mit Foto, GPS und Empfänger-Unterschrift quittieren, damit ein belastbarer Liefernachweis existiert.

Akzeptanzkriterien

• Gegeben eine Box in der Zustellung, wenn ich DELIVERED erfasse, dann werden Foto (doc_class='delivery_proof'), GPS und Name des Unterzeichners (tracking_events.signer_name) + Unterschrift (doc_class='signature') gespeichert.
• Gegeben fehlendes Pflicht-Element (Foto/Unterschrift — je nach Entscheid E11), wenn ich abschließen will, dann weist das System darauf hin.
• Gegeben DELIVERED, dann wird die Status-Benachrichtigung gemäß Matrix ausgelöst (US-LOG-15).

Traceability: §10.3, tracking_events.signer_name, storage_objects (§6.3). (Deckt Audit-Befund sec/G6 ab.)

US-LOG-10 — Fahrer disponieren#

Als OPERATIONS möchte ich einer Sendung Abhol-, Transport- und Zustell-Fahrer zuweisen, damit Verantwortlichkeit und Fahrer-Sicht klar sind.

Akzeptanzkriterien

• Gegeben eine Sendung, wenn ich Fahrer wähle, dann werden shipments.pickup_driver_id / transport_driver_id / delivery_driver_id gesetzt (Autocomplete, max. 10 Treffer, Rolle FAHRER).
• Gegeben kein zugewiesener Fahrer, dann bleibt das Feld leer (= nicht zugewiesen), kein Pflichtfeld.

Traceability: shipments.*_driver_id (§7), §11.4.

US-LOG-11 — Fahrer sieht nur eigene Sendungen (RLS-Negativfall)#

Als FAHRER möchte ich ausschließlich die mir zugewiesenen Sendungen sehen und bewegen können, damit Mandanten-/Datentrennung gewahrt ist.

Akzeptanzkriterien

• Gegeben ich bin als FAHRER eingeloggt, wenn ich die Sendungsliste öffne, dann sehe ich nur Sendungen, bei denen ich pickup/transport/delivery-Fahrer bin.
• Gegeben eine fremde Box, wenn ich versuche, ein Tracking-Event dafür zu schreiben, dann wird es abgelehnt (RLS with check + Funktions-Guard).
• Gegeben READONLY/Treuhänder, wenn er Boxen liest, dann sieht er sie maskiert und kann nichts schreiben.

Traceability: Dok 30 §13 (Fussnote 12, BR-05). (Deckt Audit-P1 sec-02 direkt ab.)

US-LOG-12 — Status-Übersicht mit Zählung#

Als OPERATIONS möchte ich je Tracking-Schritt sehen, wie viele Boxen dort stehen, damit ich Engpässe sofort erkenne.

Akzeptanzkriterien

• Gegeben das Logistik-Board, wenn ich es öffne, dann zeigt jede Status-Kachel die Box-Anzahl (v_tracking_status_counts) und ist als Filter klickbar.
• Gegeben der Status DELIVERED, dann erscheint er gemäß Entscheid (E: bewusst 0 oder echt gezählt — zu bestätigen).

Traceability: v_tracking_status_counts (§11.6).

US-LOG-13 — Aduana-Manifest exportieren#

Als OPERATIONS möchte ich je Container ein Zoll-Manifest (Excel/PDF) erzeugen, damit die DR-Verzollung möglich ist.

Akzeptanzkriterien

• Gegeben ein Container, wenn ich „Aduana-Manifest" exportiere, dann enthält es je Box: Empfänger-Cédula + Dokumenttyp, Absender-Dokumenttyp, content_note, weight_rd_kg, bl_number — als Excel-Download (Standard) und PDF.
• Gegeben fehlende Pflichtangaben (z.B. Cédula), wenn ich exportiere, dann werden die betroffenen Boxen markiert.

Traceability: §10.1/§11.8, containers.bl_number, contacts.id_doc_type, recipients.id_doc_type.

US-LOG-14 — Storno & Box-Korrektur#

Als ADMIN möchte ich eine Box nach dem Verladen korrigieren oder eine Sendung stornieren können, damit Fehler revisionssicher behebbar sind.

Akzeptanzkriterien

• Gegeben eine gesperrte (verladene) Box mit Fehler, wenn ich ein Rückwärts-Event mit Begründung auslöse, dann verlässt die Box den Container (container_id=null, Status fällt zurück) und Stammdaten werden wieder editierbar.
• Gegeben eine Sendung, wenn ich storniere, dann wird sie als CANCELLED markiert (kein hartes Löschen) und der Vorgang im Audit protokolliert.

Traceability: §7 (Storno), §11.3, audit_log (§6.1).

US-LOG-15 — Empfänger verfolgt seine Box (kein Login)#

Als Empfänger in der DR möchte ich den Status meiner Box ohne Login verfolgen, damit ich weiß, wann sie ankommt.

Akzeptanzkriterien

• Gegeben ein QR-/Tracking-Link (/b/<uuid>), wenn ich ihn öffne, dann sehe ich den aktuellen Schritt + Verlauf in meiner Sprache — ohne sensible interne Daten.
• Gegeben ein relevanter Statuswechsel (z.B. DELIVERED), wenn er eintritt, dann erhalte ich eine WhatsApp-Benachrichtigung gemäß Matrix (Sprache aus recipients.preferred_lang).
• Gegeben ein relevanter Statuswechsel, dann erhalten beide Parteien (CH-Absender + Empfänger-DR) die Nachricht — immer, auch bei offener Rechnung (Entscheid #16/#17, kein Zahlungs-Gate).

Traceability: §4.1.4 (öffentliche QR-URL), Notification-Matrix §11.1.

Schätzung & Priorität (Vorschlag — vom Team final zu bestätigen)#

Größe = grobe Aufwands-Indikation (S/M/L), nicht Story Points. Priorität nach MoSCoW (Must/Should/Could). Beides ist ein Vorschlag zur Release-Planung — die verbindliche Schätzung/Priorisierung macht das Team im Backlog.

Abdeckung & offene Punkte (dieses Epic)#

• 15 Stories decken den Box-Lebenszyklus end-to-end ab (materialisieren → packen/wiegen → tracken → verladen → verschiffen/verzollen → nachwiegen → zustellen + Nachweis → Empfänger-Sicht) plus Querschnitt (Disposition, RLS, Übersicht, Reports, Storno).
• Audit-Verzahnung: US-LOG-04 (Idempotenz, data-08), US-LOG-09 (Unterschrift, G6), US-LOG-11 (Fahrer-RLS, sec-02) — die Akzeptanzkriterien encodieren die Audit-Härtungen als testbare Szenarien.
• Entscheid-abhängig: US-LOG-09 (Unterschrift Pflicht? E11), US-LOG-12 (DELIVERED-Zählung). ✅ Status-Set E3 entschieden (2026-06-28): DR_DEPOT ist Schritt 9, DELIVERED Schritt 10.
• Nächster Schritt: Format-Freigabe → Fan-out auf die übrigen 7 Epics (CRM, WhatsApp/OCR, Produkte/Preise, Offerten, Finanzen, Affiliate, Plattform) im selben Muster + INVEST-Red-Team-Pass.