Household Items API

Háztartási leltár

Megosztott tételek követése, automatikus utánpótlási feladatokkal

A háztartási tételek egy megosztott leltárlista, opcionálisan egy emberek csoportjához kötve, eltarthatósági idő és lejárati dátum követésével. Egy óránkénti vizsgálat automatikusan létrehoz egy utánpótlási Task-ot, amikor egy tétel elfogy vagy közel áll a kifogyáshoz.

JWT vagy felhasználói API-kulcsEltarthatósági idő követéseAutomatikus utánpótlási feladatokMegosztás emberek csoportjával

Hitelesítés és jogosultságok

• Ennek az oldalnak minden végpontja hitelesítést és a task_management csomagfunkciót igényli (lásd RequireFeature('task_management')).
• A tételek a hitelesített tulajdonoshoz vannak kötve; a groupId emellett megosztja a tételt egy emberek csoportjának tagjaival.

Végpont-referencia

Metódus	Útvonal	Cél	Kérés vagy query	Auth	Forrás
POST	/api/household-items	Háztartási tétel létrehozása.	Body: tételmezők	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
GET	/api/household-items	A hívó tulajdonában lévő tételek listázása.	Nincs	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
GET	/api/household-items/:id	Egy tétel lekérése.	Path: id	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
PATCH	/api/household-items/:id	Tétel frissítése.	Path: id, body: részleges tételmezők	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
DELETE	/api/household-items/:id	Tétel törlése.	Path: id	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
POST	/api/household-items/:id/mark-used-up	Tétel megjelölése elfogyottként, ami a következő vizsgálatnál (vagy azonnal, ha már megfelel a feltételnek) utánpótlási feladatot indít.	Path: id	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts
POST	/api/household-items/:id/consume	A mennyiség csökkentése egy megadott értékkel (alapértelmezés 1), pl. „elhasznált 2 tekercs papírtörlőt."	Path: id, body: amount (opcionális)	JWT vagy felhasználói API-kulcs	household/household-items.controller.ts

Kérésformák

Tétel payload

CreateHouseholdItemDto

• name: kötelező, max 200 karakter
• category: opcionális, max 100 karakter
• quantity: opcionális egész szám, >= 0, alapértelmezett 1
• groupId: opcionális egész szám — megosztja a tételt egy emberek csoportjával
• expiryDate: opcionális ISO dátum string (YYYY-MM-DD)
• shelfLifeDays: opcionális egész szám, 1..3650
• lowStockThreshold: opcionális egész szám, >= 0 — egy második, független utánpótlási kiváltó ok azoknál a tételeknél, amelyeket darabszám alapján követ, nem frissesség alapján (papírtörlő, elem)

Az UpdateHouseholdItemDto ugyanazt a struktúrát tartja meg, de minden mezőt opcionálissá tesz.

Fogyasztás payload

ConsumeHouseholdItemDto

• amount: opcionális egész szám, >= 1, alapértelmezett 1

Példahívások

Háztartási tétel létrehozása eltarthatósági idővel

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

Háztartási tételek listázása

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

Tétel megjelölése elfogyottként

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

Darabszám alapú tétel követése és fogyasztása

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Papírtörlő",
    "category": "Takarítás",
    "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
  }'

Válasz- és viselkedési megjegyzések

• Egy óránkénti vizsgálat (HouseholdRestockSchedulerService) létrehoz egy Restock: <név> című Task-ot minden olyan tételhez, amely isUsedUp, 3 napon belül van a expiryDate mezőjétől, 3 napon belül kimeríti a shelfLifeDays mezőt a lastRestockedAt-tól számítva, vagy amelynek quantity mezője elérte vagy az alá csökkent a lowStockThreshold értékének.
• Ha egy tételnek már van pendingRestockTaskId mezője, a vizsgálat kihagyja — egyszerre csak egy nyitott utánpótlási feladat létezik tételenként.
• A POST /api/household-items/:id/mark-used-up beállítja az isUsedUp: true értéket; nem hozza létre szinkron módon az utánpótlási feladatot — a következő óránkénti vizsgálat (vagy a mögöttes vizsgálati logika egy hívása) veszi fel.
• A POST /api/household-items/:id/consume az amount értékkel csökkenti a quantity mezőt (nullára korlátozva), és ha eléri a nullát, beállítja az isUsedUp: true értéket. A mark-used-up-hoz hasonlóan ez sem hozza létre szinkron módon az utánpótlási feladatot.
• A shelfLifeDays, az expiryDate és a lowStockThreshold mind egymástól függetlenek — egy tétel ezek bármely kombinációját használhatja, vagy egyiket sem. Ha egyik sincs beállítva, a tétel csak az isUsedUp/consume nullára csökkenésén keresztül kerül megjelölésre.

Bevált gyakorlatok

• Állítson be shelfLifeDays értéket azokhoz a tételekhez, amelyeket nagyjából rendszeres ciklusban pótol (tej, szűrők, fogyóeszközök), ahelyett hogy egy pontos expiryDate értéket kellene kézzel frissítenie.
• Állítson be lowStockThreshold értéket azokhoz a tételekhez, amelyeket darabszám alapján követ, nem frissesség alapján (papírtörlő, elem, izzó), és hívja meg a consume végpontot ahogy elhasználja őket, ahelyett hogy csak egyszerre jelölné meg elhasználtként az egész tételt.
• Osszon meg fogyóeszközöket groupId segítségével, hogy az egész háztartás — nem csak a tételt létrehozó személy — lássa, és megjelölhesse elfogyottként, vagy fogyaszthasson belőle.
• Hívja meg a mark-used-up/consume végpontot, amint egy tétel elfogyóban van, ahelyett hogy megvárná, hogy az eltarthatósági időablak magától záruljon le — így az utánpótlási feladat hamarabb létrejön.