Repository navigation
Planner API Spec
범위: Google OAuth 연동, 통합 캘린더 피드(일정+할일+복습), 일정 양방향 CRUD(프록시), Google Tasks CRUD(프록시). 일정/할 일은 BE가 Google API를 프록시한다(FE는 Google 토큰을 보지 않는다). 결정 근거는 결정 기록.
Base URL: /api
OAuth 콜백을 제외한 모든 API는 인증 필요 (Authorization: Bearer {accessToken}). 시간대는 X-Timezone 헤더 사용. 응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.
| 코드 | HTTP | 메시지 |
|---|---|---|
| PLN-ERR-001 | 404 | 존재하지 않는 리소스입니다 |
| PLN-ERR-002 | 400 | 유효하지 않은 요청입니다 |
| PLN-ERR-003 | 409 | Google 연동이 필요합니다 |
| PLN-ERR-004 | 502 | Google API 호출에 실패했습니다 |
| PLN-ERR-005 | 401 | Google 연동이 만료되어 재연결이 필요합니다 (invalid_grant) |
추가 에러 코드는 구현 중 필요 시 보강.
| Method | Path | 설명 |
|---|---|---|
| GET | /api/integrations/google/oauth/url |
인증 URL 발급 (state 생성) |
| GET | /api/integrations/google/oauth/callback |
OAuth 콜백 (permitAll, 302 리다이렉트) |
| GET | /api/integrations/google/status |
연동 상태 조회 |
| POST | /api/integrations/google/disconnect |
연동 해제 (revoke + 삭제) |
| GET | /api/planner/calendar |
통합 피드(일정+할일+복습) |
| POST | /api/planner/calendar/events |
일정 생성 (Google) |
| PATCH | /api/planner/calendar/events/{eventId} |
일정 수정 (Google) |
| DELETE | /api/planner/calendar/events/{eventId} |
일정 삭제 (Google) |
| GET | /api/planner/tasks |
할 일 목록 (Google Tasks) |
| POST | /api/planner/tasks |
할 일 생성 |
| PATCH | /api/planner/tasks/{taskId} |
할 일 수정/완료 토글 |
| DELETE | /api/planner/tasks/{taskId} |
할 일 삭제 |
기존 유지: /api/planner/reviews/calendar, /reviews/today, /reviews/{id}/complete (복습 단독 조회·평가).
GET /api/integrations/google/oauth/url
Response 200:
{ "code": "SUCCESS", "data": { "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth?..." } }- BE가
state(memberId 바인딩) 생성·Redis 저장. scope=calendar+tasks,access_type=offline,prompt=consent.
GET /api/integrations/google/oauth/callback?code={code}&state={state}
- state 검증 → code→token 교환 → refresh DB 저장, access Redis 캐시, primary calendar/task list 조회.
-
302 redirect →
{FE}/integrations?google=connected(실패 시?google=error).
GET /api/integrations/google/status
Response 200:
{ "code": "SUCCESS", "data": {
"connected": true, "googleEmail": "me@gmail.com",
"scopes": ["...calendar", "...tasks"], "connectedAt": "2026-06-15T10:00:00" } }- 미연동:
connected:false, 나머지 null.
POST /api/integrations/google/disconnect
Response 200: { "code": "SUCCESS", "data": null } — Google revoke + DB row 삭제 + Redis 정리.
GET /api/planner/calendar?from=2026-06-01&to=2026-06-30&view=month
Query: from,to (LocalDate, 최대 ~100일), view(month|week|day, 선택·표시 힌트).
Response 200:
{ "code": "SUCCESS", "data": {
"from": "2026-06-01", "to": "2026-06-30",
"googleConnected": true,
"partial": false,
"errors": [],
"events": [
{ "id": "g-evt-abc", "title": "치과 예약", "allDay": false,
"start": "2026-06-10T14:00:00", "end": "2026-06-10T15:00:00",
"location": null, "recurring": true, "source": "google" }
],
"tasks": [
{ "id": "g-task-1", "title": "리포트 제출", "due": "2026-06-12",
"completed": false, "source": "google" }
],
"reviews": [
{ "id": 1001, "scheduledAt": "2026-06-11T04:00:00", "status": "PENDING",
"materialTitle": "이펙티브 자바", "front": "...", "readOnly": true, "source": "review" }
]
} }- 시간 값은
X-Timezone기준으로 정규화. 반복 일정은singleEvents=true로 펼쳐진 인스턴스(recurring:true). - 미연동:
googleConnected:false,events/tasks빈 배열,reviews는 정상. - 부분 실패:
partial:true,errors:[{ "source": "google-events", "message": "..." }].
POST /api/planner/calendar/events
{ "title": "치과 예약", "allDay": false,
"start": "2026-06-10T14:00:00", "end": "2026-06-10T15:00:00",
"location": null, "description": null }
Response 201: 생성된 event(피드 event 형식). 미연동 시 409 PLN-ERR-003.
PATCH /api/planner/calendar/events/{eventId}
{ "title": "치과 예약(변경)", "start": "...", "end": "..." }
Response 200: 수정된 event. 없는 id면 404 PLN-ERR-001.
- 반복 일정 편집은 1차에서 단일 인스턴스 patch 우선. "이 일정 이후 전체" 등은 차기(결정 기록).
DELETE /api/planner/calendar/events/{eventId}
Response 200: { "code": "SUCCESS", "data": null }.
쓰기 성공 후 BE는 해당 기간 캐시(
google:cal-cache:*)를 무효화한다.
GET /api/planner/tasks?showCompleted=true
Response 200: { "tasks": [ { "id", "title", "due", "completed", "notes" } ] }.
POST /api/planner/tasks
{ "title": "리포트 제출", "due": "2026-06-12", "notes": null }
Response 201: 생성된 task. 미연동 시 409 PLN-ERR-003.
PATCH /api/planner/tasks/{taskId}
{ "completed": true } // 또는 title/due/notes 수정
Response 200: 수정된 task.
DELETE /api/planner/tasks/{taskId}
Response 200: { "code": "SUCCESS", "data": null }.
-
/api/integrations/google/oauth/callback은 permitAll (브라우저 top-level redirect라 JWT 헤더 없음). - 나머지
/api/integrations/google/**,/calendar/**,/tasks/**는 인증 필요. - Google 호출 실패는 502(PLN-ERR-004),
invalid_grant는 401(PLN-ERR-005)로 매핑해 FE가 재연동 유도.