Routine Templates API

Rutinok és sablonok

Sablonok klónozása, elemek kezelése, igény szerinti példányosítás, méltányosság olvasása

A rutinsablonok egy ismétlődő ellenőrzőlistát valódi feladatokká alakítanak. Ezek a végpontok lefedik a sablonkönyvtárat, az elemkezelést, a manuális („Start now") és ütemezett példányosítást, valamint a háztartási méltányossági összesítést, amely az egyenetlen házimunka-rotáció felismerésére szolgál.

JWT vagy felhasználói API-kulcsRendszersablon klónozásRotációs stratégiákMéltányossági összesítés

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')).
• Egy sablont a tulajdonosa, az emberek csoportjának bármely tagja (amelyhez tartozik), vagy — ha isSystemTemplate igaz — bárki láthat, mint csak olvasható rendszersablont.
• Csak a tulajdonos frissítheti, törölheti, vagy kezelheti egy általa létrehozott nem rendszersablon elemeit — egy rendszersablon klónozása létrehozza a saját szerkeszthető másolatát.
• Egy elem defaultAssigneeId mezőjének szerkesztése a sablon tulajdonosára vagy a sablon emberek csoportjának egy tagjára korlátozódik.

Végpont-referencia

Metódus	Útvonal	Cél	Kérés vagy query	Auth	Forrás
POST	/api/routine-templates	Rutinsablon létrehozása.	Body: sablonmezők	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
GET	/api/routine-templates	A hívó számára látható sablonok listázása: saját, aktív rendszersablonok, és az emberek csoportjainak aktív sablonjai.	Nincs	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
GET	/api/routine-templates/fairness	Háztartási méltányossági összesítés egy emberek csoportjához.	Query: groupId (kötelező), windowDays (opcionális, alapértelmezett 30, max 365)	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
GET	/api/routine-templates/:id	Egy sablon lekérése az elemeivel.	Path: id	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
PATCH	/api/routine-templates/:id	Sablon frissítése.	Path: id, body: részleges sablonmezők	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
DELETE	/api/routine-templates/:id	Sablon törlése.	Path: id	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
POST	/api/routine-templates/:id/instantiate	„Start now" — a mai feladatok azonnali létrehozása a sablon elemeiből, függetlenül az ismétlődési ütemezéstől.	Path: id	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
GET	/api/routine-templates/:id/streak	Teljesítési sorozat statisztikák: aktuális sorozat, leghosszabb sorozat, utolsó teljesen befejezett példányosítás dátuma.	Path: id	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
POST	/api/routine-templates/:id/skip	A mai előfordulás kihagyása feladatok létrehozása nélkül (pl. „utazunk"). Csak a tulajdonos.	Path: id	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
POST	/api/routine-templates/:id/clone	Rendszersablon klónozása saját (opcionálisan csoporttal megosztott) szerkeszthető másolattá.	Path: id, body: groupId (opcionális)	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
POST	/api/routine-templates/:id/items	Elem hozzáadása egy sablonhoz.	Path: id, body: elemmezők	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
PATCH	/api/routine-templates/:id/items/reorder	Egy sablon elemeinek átrendezése.	Path: id, body: itemIds	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
PATCH	/api/routine-templates/:id/items/:itemId	Egy elem frissítése.	Path: id,itemId, body: részleges elemmezők	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts
DELETE	/api/routine-templates/:id/items/:itemId	Egy elem eltávolítása.	Path: id,itemId	JWT vagy felhasználói API-kulcs	tasks/routine-templates.controller.ts

Kérésformák

Sablon payload

CreateRoutineTemplateDto

• name: kötelező, max 200 karakter
• description: opcionális, max 2000 karakter
• color: opcionális 6 jegyű hexa szín, alapértelmezett #eab308
• groupId: opcionális egész szám — a hívónak már tagnak kell lennie ebben az emberek csoportjában
• isActive: opcionális logikai érték, alapértelmezett true
• recurrence: kötelező RecurrencePatternDto — ugyanaz az ismétlődési forma, amelyet az ismétlődő naptáreseményeknél is használnak (type: none|daily|weekly|monthly|yearly, interval, daysOfWeek, endType stb.)
• rotationStrategy: opcionális enum fixed|round_robin|least_recently_done, alapértelmezett fixed

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

Elem payload

CreateRoutineTemplateItemDto

• title: kötelező, max 240 karakter
• body: opcionális, max 8000 karakter
• bodyFormat: opcionális, jelenleg csak markdown
• color: opcionális 6 jegyű hexa szín
• priority: opcionális enum high|medium|low
• durationMinutes: opcionális egész szám, >= 1
• place: opcionális, max 255 karakter
• defaultAssigneeId: opcionális egész szám — a sablon tulajdonosának vagy a sablon emberek csoportja egy tagjának kell lennie
• order: opcionális egész szám — alapértelmezetten a következő elérhető pozíció

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

Átrendezés payload

ReorderRoutineTemplateItemsDto.itemIds: kötelező, egyedi egész számokból álló tömb, legalább egy elemmel — az elemek a tömbbeli pozíciónak megfelelően rendeződnek át; az ismeretlen azonosítókat csendben kihagyja a rendszer.

Méltányossági query

GetFairnessQueryDto

• groupId: kötelező pozitív egész szám — a hívónak tagnak kell lennie
• windowDays: opcionális egész szám, 1..365, alapértelmezett 30

Sorozat válasz

A GET /api/routine-templates/:id/streak a következőket adja vissza:

• currentStreak: egymást követő, teljesen befejezett példányosítások, a legutóbbival kezdve (0, ha az utolsó példányosításban volt bármilyen befejezetlen feladat)
• longestStreak: a sablon teljes előzményében a leghosszabb, teljesen befejezett példányosítási sorozat
• lastCompletedDate: a legutóbbi instanceDate (YYYY-MM-DD), amelyen az adott napon létrehozott összes elem befejeződött, vagy null
• totalInstantiations: hány különböző instanceDate létezik a sablon előzményében

A „teljesen befejezett" azt jelenti, hogy az adott példányosítási dátumhoz létrehozott minden feladatnak van completedAt mezője — egyetlen befejezetlen elem is megszakítja az adott dátum sorozatát, még akkor is, ha a többi elkészült.

Rotációs stratégiák

Stratégia	Megbízott kiválasztása
fixed	Mindig az elem defaultAssigneeId mezője.
round_robin	Végigmegy a csoport tagjainak azonosítóin (növekvő sorrendben), és a legutóbb ennél a konkrét elemnél kiosztott személy után a következőre lép.
least_recently_done	Annak a csoporttagnak adja ki, akinek a legrégebbi (vagy nem létező) kiosztási előzménye van ennél a konkrét elemnél.

A rotáció csak akkor érvényesül, ha a sablonnak van groupId mezője, és a csoportnak legalább két tagja van; egyébként az elem defaultAssigneeId mezőjét (vagy a sablon tulajdonosát) használja a rendszer.

Példahívások

Rendszersablon klónozása egy emberek csoportjába

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

Heti rotációs rutin létrehozása

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

Sablon azonnali indítása

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

Egy rutin sorozatának lekérése

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

Példa válasz:

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

A mai előfordulás kihagyása

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

A háztartási méltányossági nézet olvasása

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

Példa válasz:

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

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

• A POST /api/routine-templates/:id/instantiate elemenként egy feladatot hoz létre (az order szerint), elemenként egy RoutineAssignmentHistory sort rögzít, és frissíti a sablon lastInstantiatedDate mezőjét — ugyanazt az idempotencia-jelölőt, amelyet az éjszakai ütemező is használ, így egy manuális „Start now" futtatás és az aznapi ütemezett futtatás nem duplázódik.
• A példányosítás tranzakciós: vagy minden elem feladata és előzménysora létrejön, vagy egyik sem.
• A GET /api/routine-templates a hívó tulajdonában lévő sablonokat, az aktív rendszersablonokat, és a hívó bármely emberek csoportjának aktív sablonjait adja vissza — összesítve, létrehozási idő szerint rendezve.
• Egy rendszersablon klónozása soha nem viszi át a defaultAssigneeId értékeket, mivel egy rendszersablon megbízottjai (ha vannak) senkihez sem tartoznak.
• A GET /api/routine-templates/fairness a groupId tagságát igényli, és a routine_assignment_history sorokat összesíti a kapcsolódó feladat completedAt mezőjéhez kapcsolva.
• A POST /api/routine-templates/:id/skip a mai napra állítja a lastInstantiatedDate mezőt (ugyanazt az idempotencia-jelölőt, amelyet az instantiate is használ), de nem hoz létre feladatokat, és nem nyúl a rotációs előzményekhez — a következő valódi példányosítás pontosan onnan folytatja a rotációt, ahol abbamaradt.
• A GET /api/routine-templates/:id/streak a számait teljes egészében a meglévő routine_assignment_history + Task.completedAt adatokból vezeti le; nem ad hozzá új nyomkövető táblát.

Bevált gyakorlatok

• Használja a rotationStrategy: round_robin beállítást olyan házimunkáknál, ahol a sorrendiség fontosabb, mint a nyers méltányosság, és a least_recently_done beállítást, ha a csoport mérete vagy ütemezése elég szabálytalan ahhoz, hogy egy fix ciklus önkényesnek tűnjön.
• Hívja meg rendszeresen a GET /api/routine-templates/fairness végpontot (vagy egy MCP-kapcsolt ügynökből), ahelyett, hogy saját maga próbálná kikövetkeztetni a méltányosságot a feladatelőzményekből — az összesítés már figyelembe veszi a teljesítést, nem csak a kiosztást.
• Részesítse előnyben a POST /api/routine-templates/:id/instantiate végpontot a sablon feladatainak kézi újralétrehozásával szemben, ha egy rutinnak a normál ütemezésén kívül kell lefutnia.
• Részesítse előnyben a POST /api/routine-templates/:id/skip végpontot a sablon törlésével vagy deaktiválásával szemben, ha csak egyetlen előfordulást kell kihagynia (pl. egy ünnepi hét) — a deaktiválás elveszti az ismétlődési konfigurációt, a skip nem.
• A GET /api/routine-templates/:id/streak végpontot csak mértékkel jelenítse meg emlékeztetőkben vagy értesítésekben — közvetlenül egy teljesítés után a legmotiválóbb, nem minden oldalbetöltéskor.