API Routine Templates

Routines et modèles

Clonez des modèles, gérez les éléments, instanciez à la demande, et lisez l'équité

Les modèles de routine transforment une liste de contrôle récurrente en tâches réelles. Ces routes couvrent la bibliothèque de modèles, la gestion des éléments, l'instanciation manuelle (« Démarrer maintenant ») et planifiée, ainsi que l'agrégat d'équité du foyer utilisé pour repérer une rotation de corvées déséquilibrée.

JWT ou clé API utilisateurClonage de modèles systèmeStratégies de rotationAgrégat d'équité

Authentification et permissions

Toutes les routes de cette page nécessitent une authentification et la fonctionnalité de plan task_management (voir RequireFeature('task_management')).
Un modèle est visible par son propriétaire, par tout membre du groupe de personnes auquel il appartient, ou par tout le monde (en tant que modèle système en lecture seule) si isSystemTemplate vaut true.
Seul le propriétaire peut mettre à jour, supprimer ou gérer les éléments d'un modèle non système qu'il a créé — cloner un modèle système crée votre propre copie modifiable.
La modification du defaultAssigneeId d'un élément est réservée au propriétaire du modèle ou à un membre du groupe de personnes du modèle.

Référence des points de terminaison

Méthode	Chemin	Objectif	Requête ou query	Auth	Source
`POST`	`/api/routine-templates`	Créer un modèle de routine.	Corps : champs du modèle	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates`	Lister les modèles visibles par l'appelant : possédés, modèles système actifs, et modèles actifs de ses groupes de personnes.	Aucun	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/fairness`	Agrégat d'équité du foyer pour un groupe de personnes.	Query : `groupId` (requis), `windowDays` (optionnel, défaut 30, max 365)	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/:id`	Récupérer un modèle avec ses éléments.	Path : `id`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id`	Mettre à jour un modèle.	Path : `id`, corps : champs partiels du modèle	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`DELETE`	`/api/routine-templates/:id`	Supprimer un modèle.	Path : `id`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/instantiate`	« Démarrer maintenant » — créer immédiatement les tâches du jour à partir des éléments du modèle, indépendamment de sa planification de récurrence.	Path : `id`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/:id/streak`	Statistiques de série de réussites : série actuelle, plus longue série, date de la dernière instanciation entièrement terminée.	Path : `id`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/skip`	Ignorer l'occurrence du jour sans créer de tâches (par ex. « nous voyageons »). Propriétaire uniquement.	Path : `id`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/clone`	Cloner un modèle système en une copie modifiable possédée (optionnellement partagée avec un groupe).	Path : `id`, corps : `groupId` (optionnel)	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/items`	Ajouter un élément à un modèle.	Path : `id`, corps : champs de l'élément	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id/items/reorder`	Réorganiser les éléments d'un modèle.	Path : `id`, corps : `itemIds`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id/items/:itemId`	Mettre à jour un élément.	Path : `id,itemId`, corps : champs partiels de l'élément	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`
`DELETE`	`/api/routine-templates/:id/items/:itemId`	Supprimer un élément.	Path : `id,itemId`	JWT ou clé API utilisateur	`tasks/routine-templates.controller.ts`

Formes de requête

Charge utile du modèle

CreateRoutineTemplateDto

name : requis, max 200 caractères
description : optionnel, max 2000 caractères
color : optionnel, couleur hexadécimale à 6 chiffres, défaut #eab308
groupId : entier optionnel — l'appelant doit déjà être membre de ce groupe de personnes
isActive : booléen optionnel, défaut true
recurrence : RecurrencePatternDto requis — la même forme de récurrence que celle utilisée pour les événements de calendrier récurrents (type: none|daily|weekly|monthly|yearly, interval, daysOfWeek, endType, etc.)
rotationStrategy : enum optionnel fixed|round_robin|least_recently_done, défaut fixed

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

Charge utile de l'élément

CreateRoutineTemplateItemDto

title : requis, max 240 caractères
body : optionnel, max 8000 caractères
bodyFormat : optionnel, actuellement seulement markdown
color : optionnel, couleur hexadécimale à 6 chiffres
priority : enum optionnel high|medium|low
durationMinutes : entier optionnel, >= 1
place : optionnel, max 255 caractères
defaultAssigneeId : entier optionnel — doit être le propriétaire du modèle ou un membre du groupe de personnes du modèle
order : entier optionnel — par défaut la prochaine position disponible

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

Charge utile de réorganisation

ReorderRoutineTemplateItemsDto.itemIds : tableau requis d'entiers uniques, au moins un — les éléments sont réorganisés pour correspondre à la position dans le tableau ; les identifiants inconnus sont ignorés silencieusement.

Query d'équité

GetFairnessQueryDto

groupId : entier positif requis — l'appelant doit être membre
windowDays : entier optionnel, 1..365, défaut 30

Réponse de série

GET /api/routine-templates/:id/streak renvoie :

currentStreak : instanciations entièrement terminées consécutives, la plus récente en premier (0 si la dernière instanciation comportait une tâche inachevée)
longestStreak : la plus longue série d'instanciations entièrement terminées dans tout l'historique du modèle
lastCompletedDate : l'instanceDate (YYYY-MM-DD) la plus récente où tous les éléments créés ce jour-là ont été terminés, ou null
totalInstantiations : combien d'instanceDates distinctes existent dans l'historique du modèle

« Entièrement terminée » signifie que chaque tâche créée pour cette date d'instanciation a un completedAt — un seul élément inachevé rompt la série pour cette date, même si le reste a été terminé.

Stratégies de rotation

Stratégie	Résolution du responsable
`fixed`	Toujours le `defaultAssigneeId` de l'élément.
`round_robin`	Passe en revue les identifiants des membres du groupe (triés par ordre croissant), en avançant après celui qui a été désigné la dernière fois pour cet élément précis.
`least_recently_done`	Désigne la personne du groupe ayant l'historique d'attribution le plus ancien (ou inexistant) pour cet élément précis.

La rotation ne s'applique que lorsque le modèle a un groupId et que le groupe compte au moins deux membres ; sinon, le defaultAssigneeId de l'élément (ou le propriétaire du modèle) est utilisé.

Exemples d'appels

Cloner un modèle système dans un groupe de personnes

curl -X POST "$PRIMECAL_API/api/routine-templates/12/clone" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "groupId": 9
  }'

Créer une routine hebdomadaire en rotation

curl -X POST "$PRIMECAL_API/api/routine-templates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Grand nettoyage du samedi",
    "groupId": 9,
    "rotationStrategy": "round_robin",
    "recurrence": {
      "type": "weekly",
      "interval": 1,
      "daysOfWeek": ["SA"]
    }
  }'

Démarrer un modèle immédiatement

curl -X POST "$PRIMECAL_API/api/routine-templates/21/instantiate" \
  -H "Authorization: Bearer $TOKEN"

Lire la série d'une routine

curl "$PRIMECAL_API/api/routine-templates/21/streak" \
  -H "Authorization: Bearer $TOKEN"

Exemple de réponse :

{
  "currentStreak": 3,
  "longestStreak": 5,
  "lastCompletedDate": "2026-07-04",
  "totalInstantiations": 12
}

Ignorer l'occurrence du jour

curl -X POST "$PRIMECAL_API/api/routine-templates/21/skip" \
  -H "Authorization: Bearer $TOKEN"

Lire la vue d'équité du foyer

curl "$PRIMECAL_API/api/routine-templates/fairness?groupId=9&windowDays=30" \
  -H "Authorization: Bearer $TOKEN"

Exemple de réponse :

[
  { "userId": 101, "assignedCount": 2, "completedCount": 2 },
  { "userId": 102, "assignedCount": 2, "completedCount": 1 }
]

Notes de réponse et de comportement

POST /api/routine-templates/:id/instantiate crée une tâche par élément (selon order), enregistre une ligne RoutineAssignmentHistory par tâche créée, et met à jour le lastInstantiatedDate du modèle — le même marqueur d'idempotence utilisé par le planificateur nocturne, afin qu'une exécution manuelle « Démarrer maintenant » et l'exécution planifiée le même jour ne se cumulent pas.
L'instanciation est transactionnelle : soit la tâche et la ligne d'historique de chaque élément sont créées, soit aucune ne l'est.
GET /api/routine-templates renvoie les modèles possédés par l'appelant, les modèles système actifs, et les modèles actifs de tout groupe de personnes auquel l'appelant appartient — combinés et ordonnés par date de création.
Cloner un modèle système ne copie jamais les valeurs defaultAssigneeId en avant, puisque les responsables (le cas échéant) d'un modèle système n'appartiennent à personne.
GET /api/routine-templates/fairness nécessite l'appartenance au groupId et agrège les lignes routine_assignment_history jointes au completedAt de la tâche liée.
POST /api/routine-templates/:id/skip marque lastInstantiatedDate à aujourd'hui (le même marqueur d'idempotence que celui utilisé par instantiate) mais ne crée aucune tâche et ne touche pas à l'historique de rotation — la prochaine instanciation réelle reprend la rotation exactement là où elle s'était arrêtée.
GET /api/routine-templates/:id/streak calcule entièrement ses chiffres à partir des données existantes de routine_assignment_history + Task.completedAt ; elle n'ajoute aucune nouvelle table de suivi.

Bonnes pratiques

Utilisez rotationStrategy: round_robin pour les corvées où l'alternance compte plus que l'équité brute, et least_recently_done lorsque la taille du groupe ou le planning est suffisamment irrégulier pour qu'un cycle fixe semble arbitraire.
Appelez GET /api/routine-templates/fairness périodiquement (ou depuis un agent connecté en MCP) plutôt que d'essayer de déduire l'équité de l'historique des tâches vous-même — l'agrégat prend déjà en compte l'achèvement, pas seulement l'attribution.
Préférez POST /api/routine-templates/:id/instantiate à la recréation manuelle des tâches d'un modèle lorsqu'une routine doit s'exécuter en dehors de sa planification normale.
Préférez POST /api/routine-templates/:id/skip à la suppression ou à la désactivation d'un modèle lorsque vous devez simplement ignorer une seule occurrence (par ex. une semaine de vacances) — la désactivation perd la configuration de récurrence, contrairement à skip.
Affichez GET /api/routine-templates/:id/streak avec parcimonie dans les rappels ou les notifications — c'est le plus motivant juste après une réussite, pas à chaque chargement de page.

Clonez des modèles, gérez les éléments, instanciez à la demande, et lisez l'équité

Authentification et permissions​

Référence des points de terminaison​

Formes de requête​

Charge utile du modèle​

Charge utile de l'élément​

Charge utile de réorganisation​

Query d'équité​

Réponse de série​

Stratégies de rotation​

Exemples d'appels​

Cloner un modèle système dans un groupe de personnes​

Créer une routine hebdomadaire en rotation​

Démarrer un modèle immédiatement​

Lire la série d'une routine​

Ignorer l'occurrence du jour​

Lire la vue d'équité du foyer​

Notes de réponse et de comportement​

Bonnes pratiques​