Init: RoggioApp Architecture, Prisma Schema, API MVP

2026-04-26 19:42:42 +02:00
commit 193b29e8a9
5256 changed files with 1446953 additions and 0 deletions
@@ -0,0 +1,52 @@
+# RoggioApp - Inventar & Zustand (Soll vs. Ist)
+
+## Das Problem
+Inventar (Löffel, Gasflaschen) ist nicht statisch. Es verbraucht sich, geht kaputt oder verschwindet. Wir müssen nicht nur wissen, *was* da sein sollte, sondern *wie viel* davon tatsächlich da ist, um Aktionen (Nachbestellen) zu triggern.
+
+## Sevs Ansatz: Soll- vs. Ist-Anzahl
+Beispiele: 
+*   Küche: Löffel (Soll: 10, Ist: 5)
+*   Butanlager: 5kg Flaschen (Soll: 10, Ist: 7)
+
+## Claras architektonische Einordnung im Unit-Graphen
+Wir können Inventar nicht einfach als dumme Text-Strings in ein Array (`inventory: ["Löffel"]`) packen, wenn wir Soll/Ist-Zahlen erfassen wollen. Wir müssen dem Inventar eine kleine Struktur geben.
+
+Da wir JSONB (`traits`) verwenden, ist das ein Kinderspiel und erfordert **keine** Änderung am Prisma-Schema!
+
+### Lösung A: Inventar als strukturiertes Objekt im Raum-Trait
+Anstatt eines einfachen Arrays speichern wir ein Array aus Objekten im JSONB der Unit (z.B. der Küche oder dem Butanlager).
+
+*Trait für die Unit "Butanlager":*
+```json
+{
+  "type": "storage_room",
+  "inventory_state": [
+    {
+      "item_id": "item_butan_5kg", 
+      "name": "5kg Butangas", 
+      "target_qty": 10, 
+      "actual_qty": 7,
+      "alert_threshold": 3
+    }
+  ]
+}
+```
+*Vorteil:* Sehr schnell abfragbar.
+*Nachteil:* Die Endreinigungskräfte müssten theoretisch die Unit "Butanlager" bearbeiten, um die Zahl anzupassen.
+
+### Lösung B: Inventar als eigene Sub-Units (Der reinrassige Graph-Weg)
+Anstatt die Gabeln als Text in die Küche zu schreiben, machen wir aus "Bestand: Löffel" eine eigene Unit, die als Child *unter* der Küche hängt.
+
+*Unit "Löffel-Bestand" (Parent: Küche):*
+```json
+{
+  "type": "inventory_item",
+  "name": "Kaffeelöffel",
+  "target_qty": 10,
+  "actual_qty": 5
+}
+```
+*Vorteil:* Absolut sauber. Wenn eine Putzkraft nach der Reinigung einen "Schwund" meldet, erstellt das System ein `Event` ("Inventar-Korrektur") und verknüpft es direkt mit der Unit "Löffel-Bestand". Die Historie bleibt erhalten (Wer hat wann gemeldet, dass 5 Löffel fehlen?).
+
+## Die Konsequenz für Aufgaben (Events)
+Wenn `actual_qty` kleiner wird als ein definierter Schwellenwert (z.B. bei Gasflaschen), feuert unser System automatisch ein neues `Event` vom Typ `TASK_BUY` (Einkaufen). Dieses Event taucht dann in Nextcloud auf der Einkaufsliste auf.