Skip to content

Planner API Spec

wcorn edited this page Jul 24, 2026 · 2 revisions

API 설계: Planner (Google Calendar 연동)

범위: Google OAuth 연동, 통합 캘린더 피드(일정+할일+복습), 일정 양방향 CRUD(프록시), Google Tasks CRUD(프록시). 일정/할 일은 BE가 Google API를 프록시한다(FE는 Google 토큰을 보지 않는다). 결정 근거는 결정 기록.

Base URL: /api

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

1. 에러 코드

코드 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)

추가 에러 코드는 구현 중 필요 시 보강.

2. 엔드포인트 목록

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 (복습 단독 조회·평가).


3. OAuth 연동

3.1 인증 URL 발급

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.

3.2 콜백 (permitAll)

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).

3.3 연동 상태

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.

3.4 연동 해제

POST /api/integrations/google/disconnect

Response 200: { "code": "SUCCESS", "data": null } — Google revoke + DB row 삭제 + Redis 정리.


4. 통합 캘린더 피드

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": "..." }].

5. 일정 양방향 CRUD (Google 프록시)

5.1 생성

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.

5.2 수정

PATCH /api/planner/calendar/events/{eventId}
{ "title": "치과 예약(변경)", "start": "...", "end": "..." }

Response 200: 수정된 event. 없는 id면 404 PLN-ERR-001.

  • 반복 일정 편집은 1차에서 단일 인스턴스 patch 우선. "이 일정 이후 전체" 등은 차기(결정 기록).

5.3 삭제

DELETE /api/planner/calendar/events/{eventId}

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

쓰기 성공 후 BE는 해당 기간 캐시(google:cal-cache:*)를 무효화한다.


6. 할 일 (Google Tasks 프록시)

6.1 목록

GET /api/planner/tasks?showCompleted=true

Response 200: { "tasks": [ { "id", "title", "due", "completed", "notes" } ] }.

6.2 생성

POST /api/planner/tasks
{ "title": "리포트 제출", "due": "2026-06-12", "notes": null }

Response 201: 생성된 task. 미연동 시 409 PLN-ERR-003.

6.3 수정 / 완료 토글

PATCH /api/planner/tasks/{taskId}
{ "completed": true }          // 또는 title/due/notes 수정

Response 200: 수정된 task.

6.4 삭제

DELETE /api/planner/tasks/{taskId}

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


7. 보안 / Security 설정 변경

  • /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가 재연동 유도.

Clone this wiki locally