Routinenvorlagen API

Routinen und Vorlagen

Vorlagen klonen, Einträge verwalten, bedarfsgesteuert instanziieren und Fairness auslesen

Routine-Vorlagen verwandeln eine wiederkehrende Checkliste in echte Aufgaben. Diese Routen decken die Vorlagenbibliothek, die Eintragsverwaltung, manuelle ("Start now") und geplante Instanziierung sowie das Haushalts-Fairness-Aggregat ab, mit dem sich eine ungleiche Rotation von Hausarbeiten erkennen lässt.

JWT oder Benutzer API SchlüsselKlonen von System-VorlagenRotationsstrategienFairness-Aggregat

Authentifizierung und Berechtigungen

Alle Routen auf dieser Seite erfordern Authentifizierung und das Plan-Feature task_management (siehe RequireFeature('task_management')).
Eine Vorlage ist für ihren Besitzer, für jedes Mitglied der Personengruppe, der sie angehört, oder – falls isSystemTemplate auf true steht – als schreibgeschützte System-Vorlage für jeden sichtbar.
Nur der Besitzer kann eine von ihm erstellte, nicht-systemeigene Vorlage aktualisieren, löschen oder ihre Einträge verwalten – das Klonen einer System-Vorlage erzeugt eine eigene, bearbeitbare Kopie.
Das Bearbeiten von defaultAssigneeId eines Eintrags ist dem Vorlagenbesitzer oder einem Mitglied der Personengruppe der Vorlage vorbehalten.

Endpunktreferenz

Methode	Pfad	Zweck	Anfrage oder Abfrage	Auth	Quelle
`POST`	`/api/routine-templates`	Erstellen Sie eine Routine-Vorlage.	Körper: Vorlagenfelder	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates`	Listet die für den Aufrufer sichtbaren Vorlagen auf: eigene, aktive System-Vorlagen und aktive Vorlagen aus seinen Personengruppen.	Keine	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/fairness`	Haushalts-Fairness-Aggregat für eine Personengruppe.	Abfrage: `groupId` (erforderlich), `windowDays` (optional, Standard 30, max. 365)	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/:id`	Holen Sie sich eine Vorlage samt ihrer Einträge.	Pfad: `id`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id`	Aktualisieren Sie eine Vorlage.	Pfad: `id`, Text: Teil-Vorlagenfelder	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`DELETE`	`/api/routine-templates/:id`	Löschen Sie eine Vorlage.	Pfad: `id`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/instantiate`	„Start now“ – erstellt sofort die heutigen Aufgaben aus den Einträgen der Vorlage, unabhängig von ihrem Wiederholungsplan.	Pfad: `id`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`GET`	`/api/routine-templates/:id/streak`	Statistik zur Erledigungs-Serie: aktuelle Serie, längste Serie, Datum der letzten vollständig abgeschlossenen Instanziierung.	Pfad: `id`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/skip`	Überspringt den heutigen Durchlauf, ohne Aufgaben zu erstellen (z. B. „wir sind auf Reisen“). Nur der Besitzer.	Pfad: `id`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/clone`	Klonen Sie eine System-Vorlage in eine eigene (optional gruppengeteilte) bearbeitbare Kopie.	Pfad: `id`, Text: `groupId` (optional)	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`POST`	`/api/routine-templates/:id/items`	Fügen Sie einer Vorlage einen Eintrag hinzu.	Pfad: `id`, Text: Eintragsfelder	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id/items/reorder`	Ordnen Sie die Einträge einer Vorlage neu an.	Pfad: `id`, Text: `itemIds`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`PATCH`	`/api/routine-templates/:id/items/:itemId`	Aktualisieren Sie einen Eintrag.	Pfad: `id,itemId`, Text: Teil-Eintragsfelder	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`
`DELETE`	`/api/routine-templates/:id/items/:itemId`	Entfernen Sie einen Eintrag.	Pfad: `id,itemId`	JWT oder Benutzer API Schlüssel	`tasks/routine-templates.controller.ts`

Anfrageformen

Vorlagennutzlast

CreateRoutineTemplateDto

name: erforderlich, maximal 200 Zeichen
description: optional, maximal 2000 Zeichen
color: optionale 6-stellige Hexadezimalfarbe, Standard #eab308
groupId: optionale Ganzzahl – der Aufrufer muss bereits Mitglied dieser Personengruppe sein
isActive: optionaler boolescher Wert, Standard true
recurrence: erforderliches RecurrencePatternDto – dieselbe Wiederholungsstruktur wie bei wiederkehrenden Kalenderereignissen (type: none|daily|weekly|monthly|yearly, interval, daysOfWeek, endType usw.)
rotationStrategy: optionale Aufzählung fixed|round_robin|least_recently_done, Standard fixed

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

Eintragsnutzlast

CreateRoutineTemplateItemDto

title: erforderlich, maximal 240 Zeichen
body: optional, maximal 8000 Zeichen
bodyFormat: optional, derzeit nur markdown
color: optionale 6-stellige Hexadezimalfarbe
priority: optionale Aufzählung high|medium|low
durationMinutes: optionale Ganzzahl, >= 1
place: optional, maximal 255 Zeichen
defaultAssigneeId: optionale Ganzzahl – muss der Vorlagenbesitzer oder ein Mitglied der Personengruppe der Vorlage sein
order: optionale Ganzzahl – Standard ist die nächste verfügbare Position

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

Nutzlast für die Neuanordnung

ReorderRoutineTemplateItemsDto.itemIds: erforderliches Array eindeutiger Ganzzahlen, mindestens eine – Einträge werden entsprechend der Array-Position neu angeordnet; unbekannte IDs werden stillschweigend übersprungen.

Fairness-Abfrage

GetFairnessQueryDto

groupId: erforderliche positive Ganzzahl – der Aufrufer muss Mitglied sein
windowDays: optionale Ganzzahl, 1..365, Standard 30

Serien-Antwort

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

currentStreak: aufeinanderfolgende, vollständig abgeschlossene Instanziierungen, neueste zuerst (0, falls die letzte Instanziierung eine unerledigte Aufgabe enthielt)
longestStreak: die längste Folge vollständig abgeschlossener Instanziierungen in der gesamten Historie der Vorlage
lastCompletedDate: das aktuellste instanceDate (YYYY-MM-DD), an dem jeder an diesem Tag erstellte Eintrag abgeschlossen wurde, oder null
totalInstantiations: wie viele unterschiedliche instanceDate-Werte in der Historie der Vorlage existieren

„Vollständig abgeschlossen“ bedeutet, dass jede für dieses Instanziierungsdatum erstellte Aufgabe ein completedAt hat – ein einziger unerledigter Eintrag beendet die Serie für dieses Datum, selbst wenn der Rest fertig war.

Rotationsstrategien

Strategie	Auflösung der Zuweisung
`fixed`	Immer `defaultAssigneeId` des Eintrags.
`round_robin`	Durchläuft die Mitglieds-IDs der Gruppe (aufsteigend sortiert) der Reihe nach und rückt an der Person vorbei, die diesen bestimmten Eintrag beim letzten Durchlauf zugewiesen bekam.
`least_recently_done`	Weist der Person in der Gruppe zu, die für diesen bestimmten Eintrag den ältesten (oder gar keinen) Zuweisungsverlauf hat.

Rotation gilt nur, wenn die Vorlage eine groupId hat und die Gruppe mindestens zwei Mitglieder umfasst; andernfalls wird defaultAssigneeId des Eintrags (oder der Vorlagenbesitzer) verwendet.

Beispielanrufe

Eine System-Vorlage in eine Personengruppe klonen

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

Eine wöchentlich rotierende Routine erstellen

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

Eine Vorlage sofort starten

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

Die Serie einer Routine auslesen

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

Beispielantwort:

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

Den heutigen Durchlauf überspringen

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

Die Haushalts-Fairness-Ansicht auslesen

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

Beispielantwort:

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

Hinweise zu Reaktion und Verhalten

POST /api/routine-templates/:id/instantiate erstellt eine Aufgabe pro Eintrag (in der Reihenfolge order), zeichnet pro erstellter Aufgabe eine RoutineAssignmentHistory-Zeile auf und aktualisiert das lastInstantiatedDate der Vorlage – dieselbe Idempotenzmarkierung, die auch der nächtliche Scheduler verwendet, sodass ein manueller „Start now“-Lauf und der geplante Lauf am selben Tag sich nicht verdoppeln.
Die Instanziierung ist transaktional: Entweder werden die Aufgabe und die Verlaufszeile jedes Eintrags erstellt, oder keine.
GET /api/routine-templates liefert vom Aufrufer besessene Vorlagen, aktive System-Vorlagen und aktive Vorlagen aus jeder Personengruppe, der der Aufrufer angehört – kombiniert und nach Erstellungszeit sortiert.
Beim Klonen einer System-Vorlage werden defaultAssigneeId-Werte nie übernommen, da die Zuweisungen (falls vorhanden) einer System-Vorlage niemandem gehören.
GET /api/routine-templates/fairness erfordert die Mitgliedschaft in groupId und aggregiert routine_assignment_history-Zeilen, verknüpft mit dem completedAt der zugehörigen Aufgabe.
POST /api/routine-templates/:id/skip setzt lastInstantiatedDate auf heute (dieselbe Idempotenzmarkierung, die auch instantiate verwendet), erstellt aber keine Aufgaben und rührt den Rotationsverlauf nicht an – die nächste echte Instanziierung setzt die Rotation genau dort fort, wo sie aufgehört hat.
GET /api/routine-templates/:id/streak leitet seine Werte vollständig aus den bereits vorhandenen Daten von routine_assignment_history + Task.completedAt ab; es wird keine neue Tracking-Tabelle hinzugefügt.

Best Practices

Verwenden Sie rotationStrategy: round_robin für Hausarbeiten, bei denen das Abwechseln wichtiger ist als reine Fairness, und least_recently_done, wenn Gruppengröße oder Zeitplan unregelmäßig genug sind, dass ein fester Zyklus willkürlich wirken würde.
Rufen Sie GET /api/routine-templates/fairness regelmäßig ab (oder über einen MCP-verbundenen Agenten), statt Fairness selbst aus dem Aufgabenverlauf abzuleiten – das Aggregat berücksichtigt bereits die Erledigung, nicht nur die Zuweisung.
Bevorzugen Sie POST /api/routine-templates/:id/instantiate gegenüber dem manuellen Neuanlegen der Aufgaben einer Vorlage, wenn eine Routine außerhalb ihres normalen Zeitplans laufen muss.
Bevorzugen Sie POST /api/routine-templates/:id/skip gegenüber dem Löschen oder Deaktivieren einer Vorlage, wenn Sie nur einen einzelnen Durchlauf überspringen müssen (z. B. eine Ferienwoche) – Deaktivieren verwirft die Wiederholungskonfiguration, Skip nicht.
Zeigen Sie GET /api/routine-templates/:id/streak sparsam in Erinnerungen oder Benachrichtigungen an – am motivierendsten wirkt es direkt nach einer Erledigung, nicht bei jedem Seitenaufruf.

Vorlagen klonen, Einträge verwalten, bedarfsgesteuert instanziieren und Fairness auslesen

Authentifizierung und Berechtigungen​

Endpunktreferenz​

Anfrageformen​

Vorlagennutzlast​

Eintragsnutzlast​

Nutzlast für die Neuanordnung​

Fairness-Abfrage​

Serien-Antwort​

Rotationsstrategien​

Beispielanrufe​

Eine System-Vorlage in eine Personengruppe klonen​

Eine wöchentlich rotierende Routine erstellen​

Eine Vorlage sofort starten​

Die Serie einer Routine auslesen​

Den heutigen Durchlauf überspringen​

Die Haushalts-Fairness-Ansicht auslesen​

Hinweise zu Reaktion und Verhalten​

Best Practices​