Naptár API

Naptárak és naptárcsoportok

Naptárak létrehozása, csoportokba rendezése és a megosztás kezelése

A PrimeCal felosztja a naptárkezelést /api/calendars és között /api/calendar-groups. Ez az oldal mindkét útvonalcsaládot egyben tartja, így a a teljes naptárkezelési munkafolyamat egy helyen van dokumentálva.

JWT vagy felhasználói API kulcsSaját és megosztott naptárakCsoportálnevek a /calendars/groups alattMegosztási engedélyek

Hitelesítés és engedélyek

• Ezen az oldalon minden végpont hitelesítést igényel.
• A tulajdonjog vagy a megosztási engedélyek a szolgáltatási rétegben érvényesülnek.
• A megosztási műveletek read, write és admin engedélyszinteket használnak.
• A naptártörlés lágy törlés.
• A csoporttörlés nem törli a csoporton belüli naptárakat.

Végpont referencia

Naptárak

módszer	Útvonal	Cél	Kérjen vagy érdeklődjön	Auth
POST	/api/calendars	Hozzon létre egy naptárt.	Törzs: name,description,color,icon,visibility,groupId,rank	JWT vagy felhasználói API kulcs
GET	/api/calendars	Saját és megosztott naptárak listázása.	Egyik sem	JWT vagy felhasználói API kulcs
GET	/api/calendars/:id	Vegyél egy naptárat.	Elérési út: id	JWT vagy felhasználói API kulcs
PATCH	/api/calendars/:id	Naptár frissítése.	Elérési út: id, törzs: részleges naptármezők	JWT vagy felhasználói API kulcs
DELETE	/api/calendars/:id	Naptár finom törlése.	Elérési út: id	JWT vagy felhasználói API kulcs
POST	/api/calendars/:id/share	Naptár megosztása a felhasználókkal.	Elérési út: id, törzs: userIds,permission	JWT vagy felhasználói API kulcs
DELETE	/api/calendars/:id/share	Naptár megosztásának megszüntetése a felhasználókkal.	Elérési út: id, törzs: userIds	JWT vagy felhasználói API kulcs
GET	/api/calendars/:id/shared-users	Sorolja fel azokat a felhasználókat, akikkel a naptár meg van osztva.	Elérési út: id	JWT vagy felhasználói API kulcs
GET	/api/calendars/groups	Alias ​​a naptárcsoportok listázásához.	Egyik sem	JWT vagy felhasználói API kulcs
POST	/api/calendars/groups	Alias ​​naptárcsoport létrehozásához.	Törzs: name,isVisible	JWT vagy felhasználói API kulcs

Naptár csoportok

módszer	Útvonal	Cél	Kérjen vagy érdeklődjön	Auth
POST	/api/calendar-groups	Hozzon létre egy csoportot.	Törzs: name,isVisible	JWT vagy felhasználói API kulcs
GET	/api/calendar-groups	Csoportok listázása elérhető naptárral.	Egyik sem	JWT vagy felhasználói API kulcs
PATCH	/api/calendar-groups/:id	Csoport átnevezése vagy láthatóság váltása.	Elérési út: id, törzs: name,isVisible	JWT vagy felhasználói API kulcs
DELETE	/api/calendar-groups/:id	Csoport törlése a naptárak törlése nélkül.	Elérési út: id	JWT vagy felhasználói API kulcs
POST	/api/calendar-groups/:id/calendars	Naptárak hozzárendelése egy csoporthoz.	Elérési út: id, törzs: calendarIds	JWT vagy felhasználói API kulcs
POST	/api/calendar-groups/:id/calendars/unassign	Naptárak eltávolítása egy csoportból.	Elérési út: id, törzs: calendarIds	JWT vagy felhasználói API kulcs
POST	/api/calendar-groups/:id/share	Az összes naptár megosztása egy csoportban.	Elérési út: id, törzs: userIds,permission	JWT vagy felhasználói API kulcs
DELETE	/api/calendar-groups/:id/share	Egy csoportban lévő összes naptár megosztásának megszüntetése a felhasználókkal.	Elérési út: id, törzs: userIds	JWT vagy felhasználói API kulcs

Kérjen alakzatokat

Naptár DTO-k

CreateCalendarDto és UpdateCalendarDto

• name: kötelező a létrehozásnál, karakterlánc
• description: opcionális karakterlánc
• color: opcionális karakterlánc, az entitás szintjén az alapértelmezett #3b82f6
• icon: opcionális karakterlánc
• visibility: opcionális enum private|shared|public
• groupId: opcionális szám vagy null
• rank: opcionális szám, az entitás szintjén az alapértelmezett 0

Megjegyzések:

• name hossza: 200
• description hossza: 500
• color hossza: 7
• icon hossza: 10

DTO-k megosztása

• ShareCalendarDto.userIds: szükséges számtömb
• ShareCalendarDto.permission: kötelező enum read|write|admin
• UnshareCalendarUsersDto.userIds: szükséges egyedi egész tömb, maximum 100 elem, minimum 1

Csoport DTO-k

CreateCalendarGroupDto és UpdateCalendarGroupDto

• name: létrehozáskor kötelező, minimum 2 karakter
• isVisible: opcionális logikai érték
• AssignCalendarsToGroupDto.calendarIds: szükséges számtömb
• ShareCalendarGroupDto.userIds: szükséges számtömb
• ShareCalendarGroupDto.permission: kötelező enum read|write|admin

Példahívások

Hozzon létre egy naptárt

curl -X POST "$PRIMECAL_API/api/calendars" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Family",
    "description": "Shared household planning",
    "color": "#14b8a6",
    "visibility": "private",
    "rank": 10
  }'

Hozzon létre egy csoportot és rendeljen hozzá naptárakat

curl -X POST "$PRIMECAL_API/api/calendar-groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Late Family",
    "isVisible": true
  }'

curl -X POST "$PRIMECAL_API/api/calendar-groups/3/calendars" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarIds": [5, 7]
  }'

Naptár megosztása

curl -X POST "$PRIMECAL_API/api/calendars/5/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userIds": [42],
    "permission": "write"
  }'

Válasz és viselkedés megjegyzések

• A naptári válaszok csoport metaadatokat és megosztott felhasználói összefoglalókat tartalmazhatnak.
• A GET /api/calendars a naptár munkaterület fő rendszerindítási útvonala.
• A /api/calendars/groups kompatibilitási álnévként létezik; a kanonikus csoportvezérlő a /api/calendar-groups címen található.
• A rank befolyásolja a sorrendet és a prioritási viselkedést a naptárorientált nézetekben.
• A isTasksCalendar és a isReservationCalendar léteznek entitás szinten, de nem közvetlenül az itt dokumentált DTO-k létrehozása/frissítése révén kezelik őket.

Legjobb gyakorlatok

• A GET /api/calendars és a GET /api/calendar-groups együtt használja a bal oldali naptárfa felépítéséhez.
• Csak akkor részesítse előnyben a csoportos megosztást, ha az a szándék, hogy több naptárt ugyanazon engedélymodell szerint igazítson.
• Kezelje a DELETE /api/calendars/:id-t lágy törlésként, és frissítse a helyi állapotot a mutáció után.
• Használja a User API GET /api/users?search=... alkalmazást, hogy segítse a megosztási párbeszédpanelek kiválasztását.
• Tartsa a visibility és az engedélyek megosztását fogalmilag elkülönítve az ügyfelekben: a láthatóság a naptár megjelenési modellje, míg a megosztás konkrét hozzáférést biztosít a felhasználóknak.