Vorrania/docs/ROADMAP.md

Vorrania – Roadmap

Selfhostbare Lebensmittel-Lagerverwaltung. Aufbau in mehreren Schritten.

Schritt 1 – Fundament ✅

• Backend (FastAPI + PostgreSQL): Datenmodell, Auth mit Rollen (Admin/Benutzer), Chargen mit MHD, FEFO-Auslagern, Open-Food-Facts-Lookup (v0-API) mit lokalem Fallback.
• Web-UI (React/Vite): Login, Dashboard, Ein-/Auslagern, Produkte, Lagerorte, Benutzerverwaltung, Einkaufsliste.
• Deployment: Docker Compose + install.sh (Docker-/curl-Autoinstall, Secrets, erster Admin, Health-Check), README.
• Tests: pytest für FEFO, Einheiten-Umrechnung und OFF-Mengenerkennung.

Schritt 1b – Ausbau Web-UI ✅

• Design: professionelles Layout mit Seitenleiste, eigenes SVG-Icon-Set (bewusst keine Emojis), Light-/Dark-Mode, konsistente Farbcodierung (gelb = Warnfrist, rot = abgelaufen).
• Gruppen: Verwaltung, Zuordnung im Produkt, Gruppen-Mindestbestand mit Einheit, Auto-Zuordnungsvorschlag aus der OFF-Kategorie.
• Einheiten (verwaltbar): eigene Tabelle mit Art (Anzahl/Gewicht/Volumen) und Umrechnungsfaktor. Eingebaut: Stück, Gramm, Kilogramm, Milliliter, Liter. Admins können weitere anlegen (z.B. Pfund = 500 g). Gilt für Produkte und Gruppen-Mindestbestände; Bestände werden intern in der kanonischen Basiseinheit (Stück/Gramm/Milliliter) gespeichert.
• Einlagern: Drei-Wege-Barcode-Erkennung (bekannt / bei OFF gefunden → inline anlegen / unbekannt), mehrere Chargen je Vorgang mit eigenem MHD, Warnung bei bereits abgelaufenem MHD.
• Auslagern: automatisch per FEFO oder gezielte Auswahl einer Charge/MHD, auch Teilmengen.
• Chargen bearbeiten: Menge/MHD korrigieren und Chargen löschen (mit Protokollierung als Korrektur-Bewegung).
• Lagerorte: beliebig tief verschachtelbar (Schrank → Fach → Kiste → …).
• Mindestbestände: je Produkt wahlweise in der Produkteinheit oder in Packungen.
• Verlauf: Bewegungsprotokoll (wer/was/wann), Einstellungen: Ablauf-Warnfrist.
• Import / Export: CSV (eine Zeile je Charge, in Excel bearbeitbar) und JSON (vollständiges Backup inkl. Einheiten, Gruppen, Lagerorte). Der Import ist rein additiv – unbekannte Produkte/Gruppen/Lagerorte werden angelegt, Chargen ergänzt, nichts gelöscht oder überschrieben.
• Migration: schonendes Nachziehen neuer Spalten beim Start (ADD COLUMN IF NOT EXISTS), damit bestehende Installationen ihre Daten behalten.

Schritt 2 – Native iOS-App (SwiftUI) ✅

• Login (Server-URL + Passwort, Token im Keychain), „angemeldet bleiben“ abwählbar.
• Barcode-Scan (AVFoundation) mit Nahbereich-Autofokus, Licht und Tippen zum Scharfstellen.
• Einlagern-Flow: scannen → Lookup/Vorbefüllung → Menge + Einheit + MHD (mehrere Chargen).
• MHD per Texterkennung ablesbar (VisionKit); erkannte Daten werden vorgeschlagen, nie ungefragt übernommen.
• Auslagern-Flow: scannen → Menge/Einheit, FEFO oder Chargenauswahl.
• Einkaufsliste, „bald ablaufend“ und Produktliste mit Bearbeiten.
• Home-Screen-Shortcuts und URL-Schema vorrania://checkin / checkout.
• Anzeige folgt dem Datumsformat aus den Servereinstellungen.

Schritt 2b – MHD-Genauigkeit und Benennung ✅

• MHD wahlweise nur mit Monat und Jahr. Gespeichert wird weiterhin ein echtes Datum (Monatsletzter), damit FEFO unverändert arbeitet; die Genauigkeit steht getrennt an Charge und Produkt. Export/Import bleiben verlustfrei.
• Kategorien als eigene Ebene neben den Gruppen. Zuvor wurden beide Begriffe vermischt – aus der Open-Food-Facts-Kategorie wurde sogar eine Gruppe geraten. Jetzt getrennt: Die Gruppe zählt Bestände mehrerer Marken zusammen (Mindestbestand, EAN-Codes), die Kategorie ordnet nur die Artikelliste und ist verschachtelbar (Süßwaren → Schokolade). Mitgelieferte Startliste, Vorschlag aus der OFF-Einordnung, Filter in App und Web.
• EAN-Codes an der Gruppe werden automatisch gepflegt: Beim Zuordnen eines Artikels landet sein Code dort, beim Gruppenwechsel wandert er mit, beim Löschen verschwindet er. Vorher blieb die Codeliste einer Gruppe leer, obwohl Artikel darin lagen.
• Eigenes Logo und Favicon je Installation (Einstellungen → Darstellung).

Schritt 2c – Modulare Startseite mit Auswertungen ✅

• Raster statt fester Seite: Die Übersicht besteht aus Karten, die sich ziehen, in der Größe ändern und einrasten lassen (react-grid-layout, 12 Spalten). „Anordnen" schaltet das frei, gespeichert wird ausdrücklich.
• Pro Benutzer eigene Anordnung (dashboard_layouts, user_id = NULL ist die Admin-Vorgabe). Admins speichern eine Vorgabe für alle und können sie über dashboard_enforced auch verbindlich setzen; Benutzer setzen jederzeit auf die Vorgabe zurück.
• 15 Karten im Verzeichnis web/src/dashboard/cards.jsx: Schnellzugriff, Status, zwei Kennzahlen, Bald ablaufend, Abgelaufen, Einkaufsliste, letzte Bewegungen sowie sechs Auswertungen. Eine neue Karte ist ein Eintrag mehr.
• Diagramme als eigene SVG-Komponenten (kein Diagramm-Paket): Ring, gestapelte Balken, Linie mit Fadenkreuz. Zustandsfarben (ok/bald/abgelaufen) sind Statusangaben aus den Tokens und stehen nie ohne Beschriftung; Kategorien nutzen eine geprüfte Farbreihe in fester Ordnung, ab sieben Kategorien wird zu „Andere" gebündelt. Hell und Dunkel haben eigene Stufen.
• Alle Mengen in Artikeleinheiten (Gläser, Packungen, Stück). Gramm und Stück lassen sich nicht addieren – Gebinde schon. Der Helfer dafür liegt jetzt einmal zentral in backend/app/services/conversion.py::article_unit.
• Verlauf wird aus den Bewegungen rückwärts vom heutigen Bestand rekonstruiert. Bekannte Ungenauigkeit: Die Umrechnung nutzt die heutige Packungsgröße; wird sie später geändert, verschiebt sich auch die Historie.

Schritt 2e – Verleih von Einzelstücken (Backend ✅, Oberfläche offen)

• Eigene Tabelle item_loans statt eines Lagerort-Werts „verliehen". Der Lagerort am Stück bleibt stehen und sagt weiter, wohin es nach der Rückgabe zurückgehört; ein Lagerort-Wert hätte diese Information vernichtet. Je Vorgang: Entleiher (Freitext), Grund (Freitext, optional), Verleihdatum, erwartetes Rückgabedatum (optional – „kurz mal mitgenommen" soll nicht an einem Datumszwang scheitern) und das Konto, das herausgegeben hat.
• Zurückgegebene Verleihe bleiben stehen (returned_on gesetzt) – damit ist die Tabelle gleichzeitig die Verleih-Historie je Stück. Ein Teilindex auf die offenen Vorgänge sichert ab, dass ein Stück nicht zweimal gleichzeitig verliehen ist.
• Verliehen heißt nicht im Bestand. Ein verliehenes Stück zählt nirgends mehr mit – weder am Lagerort noch im Gesamtbestand. Entschieden wird das an einer Stelle (services/loans.py::nicht_verliehen), die alle fünf Zählungen benutzen. „Was liegt hier?" behauptet damit nicht länger, das Stück liege im Regal. Folge: Fällt es unter den Mindestbestand, erscheint der Artikel auf der Einkaufsliste – gewollt, aber gut zu wissen.
• Verleihen darf jeder angemeldete Benutzer (es ist eine Buchung wie Ein- und Auslagern, keine Stammdatenänderung) und wird mit dem Konto protokolliert. Nur das Löschen eines Vorgangs bleibt Admins vorbehalten, weil es Historie vernichtet.
• Bewusst keine Movement-Bewegung je Verleih: Der Verlauf rechnet den Bestand rückwärts aus vorzeichenbehafteten Bewegungen – ein Abgang ohne Gegenbuchung würde diese Kurve verfälschen.
• Web-Oberfläche: Verleihen und Zurücknehmen in der Einzelstück-Tabelle eines Artikels und in der Liste aller Einzelstücke (Spalten „Verliehen an" und „Zurück bis", filter- und sortierbar), zwei Dashboard-Karten („Verliehen", „Überfällige Verleihe") und der Verleih-Verlauf je Stück. Überfällig ist rot, demnächst fällig gelb – dieselben Zustandsfarben wie beim MHD.
• Nach dem Scannen direkt verleihen: Das Ziel eines Einzelstück-QR bzw. NFC-Tags (/i/<uid>) leitete vorher nur zum Artikel weiter. Jetzt zeigt es, was man in der Hand hält, und bietet Verleihen bzw. Zurücknehmen an der Stelle an – Gegenstück zur Lagerort-Seite (/l/<code>).
• iOS-App: Verleih-Abschnitt im Einzelstück mit Herausgeben und Zurücknehmen, Verleih-Verlauf, Zustand in der Einzelstück-Liste und ein Filter Verliehen / Überfällig / Im Haus. Weil alle Scan-Wege (QR über Nachschlagen, NFC-Tag, vorrania://i/<UID>) in derselben Ansicht enden, ist „scannen und verleihen" damit überall möglich, ohne einen eigenen Weg dafür.
• Rückgabe-Erinnerung in der App, auf dem Weg der Ablauf-Meldungen: lokale Benachrichtigung, geplant aus GET /loans?due_in=…. Einstellbar je Server: „X vorher", am Rückgabetag, und täglich weiter, solange etwas überfällig ist. Echtes Push (APNs) fehlt weiterhin, siehe Schritt 3.
• Eine Meldung je Meldetag und Server statt einer je Meldungsart. Vorher gab es an einem Tag getrennte Mitteilungen für „bald ablaufend" und „abgelaufen"; mit dem Verleih wären es vier geworden. Der Grund ist nicht nur weniger Lärm: iOS erlaubt 64 geplante Mitteilungen je App, und ein Platz je Tag statt je Art ist die Voraussetzung dafür, dass der volle Planungshorizont hineinpasst.
• Horizont auf 30 Tage (vorher 60). Er ist die Zusage, wie lange die App ungeöffnet bleiben darf, ohne dass Erinnerungen ausfallen – der BGAppRefreshTask ist keine Garantie, iOS führt ihn nur aus, wenn es will. Ein längerer Horizont hätte nur spätere Tage eingeplant und dafür die nächsten verdrängt. Preis: Eine MHD-Regel mit mehr als 30 Tagen Vorlauf greift erst, wenn das Datum in dieses Fenster rückt.

Schritt 3 – Weitere Ideen – offen

• Ablauf-Push-Benachrichtigungen via APNs (setzt die App voraus).
• Einkaufsliste verfeinern: Abhaken dauerhaft speichern, manuelle Einträge, Mengenvorschläge in Packungen.
• Statistik/Auswertung über den Bewegungsverlauf (Verbrauch pro Zeitraum).
• Lagerort beim Auslagern berücksichtigen bzw. pro Charge wählbar beim Einlagern.
• Produktbilder lokal cachen (aktuell direkt von Open Food Facts geladen).
• Alembic-Migrationen statt create_all + Startup-ALTER, sobald das Schema stabil ist.