Skip to content

Routine API Spec

wcorn edited this page Jun 20, 2026 · 2 revisions

API 설계: Routine (반복 루틴 / 고정 일정)

범위: 루틴(=Google Calendar 반복 이벤트) 생성/목록/수정/삭제 프록시 + 습관 완료 체크 토글. 루틴 인스턴스 조회는 기존 통합 피드(GET /planner/calendar)에 routine 메타를 덧붙이는 방식으로 흡수한다.

상태: ✅ 구현 완료 — R0R5 (2026-06). 관련 PR: #589#597 (BE #589/#590/#591/#592/#593, FE #594/#595/#596/#597). Planner API 위에 올라가며 인증·에러·시간대 규약을 상속한다. 결정 근거는 결정 기록.

Base URL: /api

모든 API는 인증 필요 (Authorization: Bearer {accessToken}). 시간대는 X-Timezone 헤더. 응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.

1. 에러 코드

Planner 에러 코드를 재사용한다(Planner API §1).

코드 HTTP 메시지
PLN-ERR-002 400 유효하지 않은 요청입니다 (반복 규칙/scope/날짜 오류)
PLN-ERR-003 409 Google 연동이 필요합니다
PLN-ERR-004 502 Google API 호출에 실패했습니다
PLN-ERR-005 401 Google 연동이 만료되어 재연결이 필요합니다

구현에서는 별도 코드 없이 PLN-ERR-002(ROUTINE_INVALID_RULE, 400)가 반복 규칙/scope/날짜 오류를 모두 포괄한다.

2. 엔드포인트 목록

Method Path 설명
GET /api/planner/routines 루틴 시리즈 목록(관리 화면)
POST /api/planner/routines 루틴 생성(반복 이벤트)
PATCH /api/planner/routines/{eventId} 루틴 수정 (?scope=)
DELETE /api/planner/routines/{eventId} 루틴 삭제 (?scope=)
POST /api/planner/routines/{recurringEventId}/check 습관 완료 토글

조회는 통합 피드 재사용: GET /api/planner/calendar 의 events[] 항목에 routine 메타가 포함된다(§6).


3. 루틴 생성

POST /api/planner/routines
{
  "type": "habit",
  "title": "운동하기",
  "allDay": true,
  "start": "2026-06-20",
  "end": "2026-06-20",
  "recurrence": {
    "freq": "WEEKLY",
    "interval": 1,
    "byDay": ["MO", "WE", "FR"],
    "byMonthDay": null,
    "until": null
  },
  "memo": null,
  "color": null
}
필드 설명
type habit(체크형 습관) | schedule(시간 고정 일정)
allDay habit은 보통 true(종일). schedule은 false
start/end allDay면 YYYY-MM-DD(date), 아니면 YYYY-MM-DDThh:mm:ss(dateTime, X-Timezone 기준)
recurrence.freq DAILY | WEEKLY | MONTHLY
recurrence.interval N일/N주 간격(기본 1). "N일 간격"=DAILY+interval
recurrence.byDay WEEKLY일 때 요일(MO,TU,WE,TH,FR,SA,SU)
recurrence.byMonthDay MONTHLY일 때 일자(1~31)
recurrence.until 종료일 YYYY-MM-DD(포함). null=무기한
  • BE: 규칙 → RRULE 작성(아키텍처 §4), extendedProperties.private에 orinoRoutine=1,orinoRoutineType=type 태깅 → events.insert.
  • Response 201: 생성된 루틴 시리즈 요약(§5 항목 형식). 미연동 시 409 PLN-ERR-003.

4. 루틴 수정

PATCH /api/planner/routines/{eventId}?scope=all

Query: scope = all | following | instance. following/instance는 instanceDate(YYYY-MM-DD) 필수.

{
  "title": "운동하기(아침)",
  "allDay": true,
  "start": "2026-06-20",
  "end": "2026-06-20",
  "recurrence": { "freq": "WEEKLY", "byDay": ["MO","WE","FR"], "until": "2026-12-31" }
}
scope 동작
all 마스터 이벤트 patch (전체 시리즈)
instance {eventId}를 인스턴스 id로 해석 → 해당 날짜만 예외 patch
following 마스터 UNTIL=instanceDate 전날로 끊고, instanceDate부터 새 반복 이벤트 insert(태그 복사)
  • Response 200: 수정된 시리즈 요약. 없는 id면 404, 규칙/scope 오류 400.
  • following은 새 recurringEventId가 생기므로 응답에 신규 id를 포함한다.

5. 루틴 시리즈 목록 (관리)

GET /api/planner/routines
  • BE: events.list?privateExtendedProperty=orinoRoutine=1&showDeleted=false&singleEvents=false → 마스터 시리즈만 반환(인스턴스 펼침 안 함).

Response 200:

{ "code": "SUCCESS", "data": { "routines": [
  {
    "recurringEventId": "abc123",
    "type": "habit",
    "title": "운동하기",
    "allDay": true,
    "start": "2026-06-20",
    "recurrence": { "freq": "WEEKLY", "interval": 1, "byDay": ["MO","WE","FR"], "byMonthDay": null, "until": null },
    "recurrenceText": "매주 월·수·금",
    "color": null
  },
  {
    "recurringEventId": "def456",
    "type": "schedule",
    "title": "팀 회의",
    "allDay": false,
    "start": "2026-06-17T10:00:00",
    "end": "2026-06-17T11:00:00",
    "recurrence": { "freq": "WEEKLY", "interval": 1, "byDay": ["TU"], "until": "2026-12-31" },
    "recurrenceText": "매주 화 · ~2026-12-31",
    "color": null
  }
] } }
  • recurrence는 Google RRULE을 역파싱한 결과. recurrenceText는 표시용 한글 요약(BE 또는 FE 생성 — 1차 BE 제공).

6. 루틴 삭제

DELETE /api/planner/routines/{eventId}?scope=all

Query: scope = all | following | instance (+ instanceDate).

scope 동작
all 마스터 delete + routine_check 시리즈 전체 행 삭제
following 마스터 UNTIL=instanceDate 전날 patch + instance_date >= instanceDate 체크 행 삭제
instance 인스턴스 status=cancelled patch + 해당 날짜 체크 행 삭제

Response 200: { "code": "SUCCESS", "data": null }.


7. 습관 완료 토글

POST /api/planner/routines/{recurringEventId}/check
{ "date": "2026-06-20", "done": true }
  • done=true → routine_check upsert. done=false → 행 delete.
  • recurringEventId는 시리즈 안정 키(인스턴스 id 아님). date는 사용자 로컬 날짜.
  • 시간 고정 일정(schedule)에 호출 시 400(체크 비대상).

Response 200:

{ "code": "SUCCESS", "data": { "recurringEventId": "abc123", "date": "2026-06-20", "done": true } }

8. 통합 피드의 routine 메타 (조회)

GET /api/planner/calendar 응답의 events[] 각 항목에 필드 추가:

{
  "id": "abc123_20260620",
  "title": "운동하기",
  "allDay": true,
  "start": "2026-06-20",
  "end": "2026-06-20",
  "recurring": true,
  "source": "google",
  "routine": { "type": "habit", "recurringEventId": "abc123", "done": true }
}
  • 루틴 아닌 일반 이벤트는 routine: null.
  • type=habit이면 done이 채워진다(routine_check 조인). type=schedule이면 done은 항상 false/무의미.

9. 보안 / Security 설정

  • 신규 보안 설정 변경 없음. /api/planner/routines/** 는 인증 필요(Planner와 동일 규칙).
  • 쓰기(생성/수정/삭제/체크)는 Google 미연동 시 409, invalid_grant 시 401로 재연동 유도.
  • 쓰기 성공 후 해당 기간 google:cal-cache:* 무효화.

Clone this wiki locally