Haushaltsartikel API

Haushaltsinventar

Gemeinsame Gegenstände verfolgen und PrimeCal automatisch Nachschub-Aufgaben anlegen lassen

Haushaltsartikel bilden eine gemeinsam genutzte Inventarliste, optional einer Personengruppe zugeordnet, mit Haltbarkeits- und Ablaufverfolgung. Ein stündlicher Scan erstellt automatisch eine Nachschub-Task, sobald ein Gegenstand aufgebraucht ist oder bald ausgeht.

JWT oder Benutzer API SchlüsselHaltbarkeitsverfolgungAutomatische Nachschub-AufgabenFreigabe für Personengruppen

Authentifizierung und Berechtigungen

• Alle Routen auf dieser Seite erfordern Authentifizierung und das Plan-Feature task_management (siehe RequireFeature('task_management')).
• Gegenstände sind auf den authentifizierten Besitzer beschränkt; groupId teilt einen Gegenstand zusätzlich mit den Mitgliedern einer Personengruppe.

Endpunktreferenz

Methode	Pfad	Zweck	Anfrage oder Abfrage	Auth
POST	/api/household-items	Erstellen Sie einen Haushaltsartikel.	Körper: Artikelfelder	JWT oder Benutzer API Schlüssel
GET	/api/household-items	Listet die vom Aufrufer besessenen Artikel auf.	Keine	JWT oder Benutzer API Schlüssel
GET	/api/household-items/:id	Holen Sie sich einen Artikel.	Pfad: id	JWT oder Benutzer API Schlüssel
PATCH	/api/household-items/:id	Aktualisieren Sie einen Artikel.	Pfad: id, Text: Teil-Artikelfelder	JWT oder Benutzer API Schlüssel
DELETE	/api/household-items/:id	Löschen Sie einen Artikel.	Pfad: id	JWT oder Benutzer API Schlüssel
POST	/api/household-items/:id/mark-used-up	Markiert einen Artikel als aufgebraucht, wodurch beim nächsten Scan (oder sofort, falls bereits zutreffend) eine Nachschub-Aufgabe angelegt wird.	Pfad: id	JWT oder Benutzer API Schlüssel
POST	/api/household-items/:id/consume	Verringert die Menge um einen Betrag (Standard 1), z. B. „2 Rollen Papierhandtücher verbraucht“.	Pfad: id, Text: amount (optional)	JWT oder Benutzer API Schlüssel

Anfrageformen

Artikelnutzlast

CreateHouseholdItemDto

• name: erforderlich, maximal 200 Zeichen
• category: optional, maximal 100 Zeichen
• quantity: optionale Ganzzahl, >= 0, Standard 1
• groupId: optionale Ganzzahl – teilt den Artikel mit einer Personengruppe
• expiryDate: optionale ISO-Datumszeichenfolge (YYYY-MM-DD)
• shelfLifeDays: optionale Ganzzahl, 1..3650
• lowStockThreshold: optionale Ganzzahl, >= 0 – ein zweiter, unabhängiger Nachschub-Auslöser für Artikel, die nach Stückzahl statt nach Frische verfolgt werden (Papierhandtücher, Batterien)

UpdateHouseholdItemDto behält dieselbe Struktur bei, macht jedoch alle Felder optional.

Verbrauchs-Nutzlast

ConsumeHouseholdItemDto

• amount: optionale Ganzzahl, >= 1, Standard 1

Beispielanrufe

Einen Haushaltsartikel mit Haltbarkeit erstellen

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Milk",
    "category": "Dairy",
    "groupId": 9,
    "shelfLifeDays": 7
  }'

Haushaltsartikel auflisten

curl "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN"

Einen Artikel als aufgebraucht markieren

curl -X POST "$PRIMECAL_API/api/household-items/14/mark-used-up" \
  -H "Authorization: Bearer $TOKEN"

Einen mengenbasierten Artikel verfolgen und verbrauchen

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Paper towels",
    "category": "Cleaning",
    "quantity": 6,
    "lowStockThreshold": 2
  }'

curl -X POST "$PRIMECAL_API/api/household-items/22/consume" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2
  }'

Hinweise zu Reaktion und Verhalten

• Ein stündlicher Scan (HouseholdRestockSchedulerService) erstellt eine Task mit dem Titel Restock: <name> für jeden Artikel, der isUsedUp ist, sich innerhalb von 3 Tagen vor expiryDate befindet, innerhalb von 3 Tagen davor liegt, shelfLifeDays ab lastRestockedAt zu erschöpfen, oder dessen quantity auf den lowStockThreshold oder darunter gefallen ist.
• Sobald ein Artikel eine pendingRestockTaskId besitzt, überspringt der Scan ihn – pro Artikel existiert immer nur eine offene Nachschub-Aufgabe.
• POST /api/household-items/:id/mark-used-up setzt isUsedUp: true; die Nachschub-Aufgabe wird dadurch nicht synchron erstellt – der nächste stündliche Scan (oder ein Aufruf der zugrunde liegenden Scan-Logik) greift dies auf.
• POST /api/household-items/:id/consume verringert quantity um amount (auf null begrenzt) und setzt isUsedUp: true, sobald der Wert null erreicht. Wie bei mark-used-up wird die Nachschub-Aufgabe dabei nie synchron erstellt.
• shelfLifeDays, expiryDate und lowStockThreshold sind alle unabhängig voneinander – ein Artikel kann eine beliebige Kombination oder keines davon verwenden. Ist nichts davon gesetzt, wird der Artikel nur markiert, wenn isUsedUp/consume null erreicht.

Best Practices

• Setzen Sie shelfLifeDays für Artikel, die Sie in einem groben Zyklus nachfüllen (Milch, Filter, Verbrauchsmaterial), statt ein exaktes expiryDate zu verfolgen, das Sie von Hand aktualisieren müssten.
• Setzen Sie lowStockThreshold für Artikel, die Sie nach Stückzahl statt nach Frische verfolgen (Papierhandtücher, Batterien, Glühbirnen), und rufen Sie consume bei jeder Verwendung auf, statt den ganzen Artikel immer nur auf einmal als aufgebraucht zu markieren.
• Teilen Sie Verbrauchsartikel mit einer groupId, damit der gesamte Haushalt – nicht nur die Person, die den Artikel angelegt hat – ihn sieht und als aufgebraucht markieren oder davon verbrauchen kann.
• Rufen Sie mark-used-up/consume auf, sobald ein Artikel zur Neige geht, statt darauf zu warten, dass sich das Haltbarkeitsfenster von selbst schließt – so wird die Nachschub-Aufgabe schneller angelegt.