API Household Items

Inventaire du foyer

Suivez les articles partagés et laissez PrimeCal créer des tâches de réapprovisionnement automatiquement

Les articles du foyer forment une liste d'inventaire partagée, optionnellement scindée par groupe de personnes, avec suivi de la durée de conservation et de l'expiration. Une analyse horaire crée automatiquement une Task de réapprovisionnement lorsqu'un article est épuisé ou proche de l'être.

JWT ou clé API utilisateurSuivi de durée de conservationTâches de réapprovisionnement automatiquesPartage par groupe de personnes

Authentification et permissions

• Toutes les routes de cette page nécessitent une authentification et la fonctionnalité de plan task_management (voir RequireFeature('task_management')).
• Les articles sont scindés par le propriétaire authentifié ; groupId partage en plus un article avec les membres d'un groupe de personnes.

Référence des points de terminaison

Méthode	Chemin	Objectif	Requête ou query	Auth
POST	/api/household-items	Créer un article du foyer.	Corps : champs de l'article	JWT ou clé API utilisateur
GET	/api/household-items	Lister les articles possédés par l'appelant.	Aucun	JWT ou clé API utilisateur
GET	/api/household-items/:id	Récupérer un article.	Path : id	JWT ou clé API utilisateur
PATCH	/api/household-items/:id	Mettre à jour un article.	Path : id, corps : champs partiels de l'article	JWT ou clé API utilisateur
DELETE	/api/household-items/:id	Supprimer un article.	Path : id	JWT ou clé API utilisateur
POST	/api/household-items/:id/mark-used-up	Marquer un article comme épuisé, ce qui déclenche une tâche de réapprovisionnement lors de la prochaine analyse (ou immédiatement, si l'article est déjà éligible).	Path : id	JWT ou clé API utilisateur
POST	/api/household-items/:id/consume	Réduire la quantité d'un montant (par défaut 1), par ex. « utilisé 2 rouleaux d'essuie-tout ».	Path : id, corps : amount (optionnel)	JWT ou clé API utilisateur

Formes de requête

Charge utile de l'article

CreateHouseholdItemDto

• name : requis, max 200 caractères
• category : optionnel, max 100 caractères
• quantity : entier optionnel, >= 0, défaut 1
• groupId : entier optionnel — partage l'article avec un groupe de personnes
• expiryDate : chaîne de date ISO optionnelle (YYYY-MM-DD)
• shelfLifeDays : entier optionnel, 1..3650
• lowStockThreshold : entier optionnel, >= 0 — un second déclencheur de réapprovisionnement indépendant pour les articles suivis par quantité plutôt que par fraîcheur (essuie-tout, piles)

UpdateHouseholdItemDto conserve la même structure mais rend tous les champs optionnels.

Charge utile de consommation

ConsumeHouseholdItemDto

• amount : entier optionnel, >= 1, défaut 1

Exemples d'appels

Créer un article du foyer avec une durée de conservation

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

Lister les articles du foyer

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

Marquer un article comme épuisé

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

Suivre un article compté par quantité et le consommer

curl -X POST "$PRIMECAL_API/api/household-items" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Essuie-tout",
    "category": "Ménage",
    "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
  }'

Notes de réponse et de comportement

• Une analyse horaire (HouseholdRestockSchedulerService) crée une Task intitulée Restock: <nom> pour tout article qui est isUsedUp, à moins de 3 jours de son expiryDate, à moins de 3 jours d'épuiser shelfLifeDays mesuré depuis lastRestockedAt, ou dont la quantity est descendue à son lowStockThreshold ou en dessous.
• Une fois qu'un article a un pendingRestockTaskId, l'analyse l'ignore — une seule tâche de réapprovisionnement ouverte existe par article à la fois.
• POST /api/household-items/:id/mark-used-up définit isUsedUp: true ; il ne crée pas la tâche de réapprovisionnement de manière synchrone — la prochaine analyse horaire (ou un appel à la logique d'analyse sous-jacente) la prend en charge.
• POST /api/household-items/:id/consume décrémente quantity de amount (plafonné à zéro) et définit isUsedUp: true si elle atteint zéro. Comme mark-used-up, il ne crée jamais la tâche de réapprovisionnement de manière synchrone.
• shelfLifeDays, expiryDate et lowStockThreshold sont tous indépendants — un article peut utiliser n'importe quelle combinaison, ou aucune. Si aucun n'est défini, l'article n'est signalé que via isUsedUp/consume atteignant zéro.

Bonnes pratiques

• Définissez shelfLifeDays pour les articles que vous réapprovisionnez selon un cycle approximatif (lait, filtres, consommables) plutôt que de suivre une expiryDate exacte que vous devriez mettre à jour manuellement.
• Définissez lowStockThreshold pour les articles que vous suivez par quantité plutôt que par fraîcheur (essuie-tout, piles, ampoules) et appelez consume au fur et à mesure que vous les utilisez, plutôt que de toujours marquer l'article entier comme épuisé d'un coup.
• Partagez les consommables avec un groupId afin que tout le foyer — pas seulement la personne qui a créé l'article — le voie et puisse le marquer comme épuisé ou en consommer une partie.
• Appelez mark-used-up/consume dès qu'un article commence à manquer plutôt que d'attendre que la fenêtre de conservation se ferme d'elle-même ; la tâche de réapprovisionnement est créée plus tôt.