Repository navigation
Routine API Spec
범위: 루틴(=Google Calendar 반복 이벤트) 생성/목록/수정/삭제 프록시 + 습관 완료 체크 토글. 루틴 인스턴스 조회는 기존 통합 피드(
GET /planner/calendar)에routine메타를 덧붙이는 방식으로 흡수한다.상태: ✅ 구현 완료 — R0
R5 (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 에러 처리 컨벤션을 따른다.
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/날짜 오류를 모두 포괄한다.
| 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).
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.
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를 포함한다.
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 제공).
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 }.
POST /api/planner/routines/{recurringEventId}/check
{ "date": "2026-06-20", "done": true }
-
done=true→routine_checkupsert.done=false→ 행 delete. -
recurringEventId는 시리즈 안정 키(인스턴스 id 아님).date는 사용자 로컬 날짜. - 시간 고정 일정(schedule)에 호출 시 400(체크 비대상).
Response 200:
{ "code": "SUCCESS", "data": { "recurringEventId": "abc123", "date": "2026-06-20", "done": true } }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/무의미.
- 신규 보안 설정 변경 없음.
/api/planner/routines/**는 인증 필요(Planner와 동일 규칙). - 쓰기(생성/수정/삭제/체크)는 Google 미연동 시 409,
invalid_grant시 401로 재연동 유도. - 쓰기 성공 후 해당 기간
google:cal-cache:*무효화.