Skip to content

Study Planner API Spec

wcorn edited this page Apr 1, 2026 · 18 revisions

API 설계: Study Planner

Base URL: /api

모든 API는 인증 필요 (Authorization: Bearer {accessToken}).

1. 공통 응답 형식

성공

{
  "code": "요청에 성공하였습니다.",
  "data": { ... }
}

에러

{
  "code": "SP-ERR-001",
  "message": "존재하지 않는 리소스입니다."
}

2. 에러 코드

코드 HTTP 메시지
SP-ERR-001 404 존재하지 않는 리소스입니다
SP-ERR-002 400 유효하지 않은 요청입니다
SP-ERR-003 409 참조하는 데이터가 존재하여 삭제할 수 없습니다
SP-ERR-004 409 현재 상태에서 수행할 수 없는 작업입니다
SP-ERR-005 400 배분 비율 합계가 100%를 초과합니다

3. 엔드포인트 목록

3.1 카테고리

Method Path 설명
GET /api/categories 카테고리 목록
POST /api/categories 카테고리 생성
PUT /api/categories/{id} 카테고리 수정
DELETE /api/categories/{id} 카테고리 삭제

3.2 목표

Method Path 설명
GET /api/goals 목표 목록
POST /api/goals 목표 생성
GET /api/goals/{id} 목표 상세 (마일스톤, 연결된 자료/할일 포함)
PUT /api/goals/{id} 목표 수정
DELETE /api/goals/{id} 목표 삭제
PATCH /api/goals/{id}/status 목표 상태 변경
POST /api/goals/{id}/milestones 마일스톤 추가
PUT /api/goals/{goalId}/milestones/{id} 마일스톤 수정
DELETE /api/goals/{goalId}/milestones/{id} 마일스톤 삭제
PATCH /api/goals/{goalId}/milestones/{id}/complete 마일스톤 완료

3.3 고정 일정

Method Path 설명
GET /api/fixed-schedules 고정 일정 목록
POST /api/fixed-schedules 고정 일정 생성
PUT /api/fixed-schedules/{id} 고정 일정 수정
DELETE /api/fixed-schedules/{id} 고정 일정 삭제

3.4 루틴

Method Path 설명
GET /api/routines 루틴 목록
POST /api/routines 루틴 생성
GET /api/routines/{id} 루틴 상세 (스트릭 포함)
PUT /api/routines/{id} 루틴 수정
DELETE /api/routines/{id} 루틴 삭제
PATCH /api/routines/{id}/status 루틴 상태 변경
POST /api/routines/{id}/check 루틴 체크
DELETE /api/routines/{id}/check 루틴 체크 취소
POST /api/routines/{id}/exceptions 예외일 추가
DELETE /api/routines/{id}/exceptions/{exceptionId} 예외일 삭제

3.5 할 일

Method Path 설명
GET /api/todos 할 일 목록 (필터: status, priority, categoryId, hasDeadline)
POST /api/todos 할 일 생성
PUT /api/todos/{id} 할 일 수정
DELETE /api/todos/{id} 할 일 삭제
PATCH /api/todos/{id}/complete 할 일 완료

3.6 학습 자료

Method Path 설명
GET /api/materials 학습 자료 목록
POST /api/materials 학습 자료 생성
GET /api/materials/{id} 학습 자료 상세 (학습 단위, 진행률 포함)
PUT /api/materials/{id} 학습 자료 수정
DELETE /api/materials/{id} 학습 자료 삭제
PATCH /api/materials/{id}/pause 일시정지
PATCH /api/materials/{id}/resume 재개
POST /api/materials/{id}/units 학습 단위 추가
POST /api/materials/{id}/units/batch 학습 단위 일괄 등록
PUT /api/materials/{materialId}/units/{id} 학습 단위 수정
DELETE /api/materials/{materialId}/units/{id} 학습 단위 삭제
POST /api/materials/{materialId}/units/{id}/dependencies 의존성 추가
DELETE /api/materials/{materialId}/units/{unitId}/dependencies/{depId} 의존성 삭제
PUT /api/materials/{id}/allocation 배분 비율 설정
PUT /api/materials/{id}/review-config 복습 설정 오버라이드

3.7 캘린더

Method Path 설명
GET /api/calendar/daily 일간 스케줄 조회
GET /api/calendar/weekly 주간 스케줄 조회
GET /api/calendar/monthly 월간 요약 조회
PATCH /api/calendar/blocks/{blockId}/complete 블록 완료
POST /api/calendar/blocks/{blockId}/postpone 블록 미루기

3.8 복습

Method Path 설명
POST /api/reviews/{id}/feedback 복습 피드백 제출

3.9 리스케줄링

Method Path 설명
GET /api/rescheduling/options 리스케줄링 선택지 조회
POST /api/rescheduling/apply 리스케줄링 적용

3.10 대시보드

Method Path 설명
GET /api/dashboard/summary 대시보드 요약
GET /api/dashboard/streaks 스트릭 정보
GET /api/dashboard/heatmap 히트맵 데이터
GET /api/dashboard/statistics 통계

3.11 일일 회고

Method Path 설명
GET /api/reflections 회고 조회
POST /api/reflections 회고 작성
PUT /api/reflections/{id} 회고 수정

3.12 설정

Method Path 설명
GET /api/preferences 설정 조회
PUT /api/preferences 설정 수정
GET /api/preferences/priority-rules 우선순위 규칙 조회
PUT /api/preferences/priority-rules 우선순위 규칙 수정

4. API 상세 (핵심 API)

GET /api/calendar/daily

일간 스케줄을 조회한다. 스케줄이 없거나 dirty 상태이면 엔진이 자동 생성한다.

Query Parameters

파라미터 타입 필수 설명
date string (YYYY-MM-DD) N 조회 날짜 (기본: 오늘)

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "date": "2026-04-02",
    "totalBlocks": 9,
    "completedBlocks": 3,
    "blocks": [
      {
        "id": 101,
        "blockType": "ROUTINE",
        "referenceId": 1,
        "title": "헬스",
        "categoryName": "건강",
        "categoryColor": "#4CAF50",
        "startTime": "07:00",
        "endTime": "08:30",
        "status": "COMPLETED"
      },
      {
        "id": 102,
        "blockType": "ROUTINE",
        "referenceId": 2,
        "title": "영어",
        "categoryName": "어학",
        "categoryColor": "#2196F3",
        "startTime": "09:00",
        "endTime": "09:30",
        "status": "COMPLETED"
      },
      {
        "id": 103,
        "blockType": "FIXED",
        "referenceId": 1,
        "title": "자료구조 수업",
        "startTime": "10:00",
        "endTime": "12:00",
        "status": "COMPLETED"
      },
      {
        "id": 104,
        "blockType": "REVIEW",
        "referenceId": 45,
        "title": "이펙티브 자바 #12 (복습 2회차)",
        "categoryName": "프로그래밍",
        "categoryColor": "#FF9800",
        "startTime": "13:00",
        "endTime": "13:30",
        "status": "SCHEDULED"
      },
      {
        "id": 105,
        "blockType": "STUDY",
        "referenceId": 15,
        "title": "이펙티브 자바 #15",
        "categoryName": "프로그래밍",
        "categoryColor": "#FF9800",
        "startTime": "13:30",
        "endTime": "14:00",
        "status": "SCHEDULED"
      }
    ],
    "warnings": [
      {
        "type": "DEADLINE_CLOSE",
        "message": "스프링 입문 데드라인까지 여유가 5일 남았습니다."
      }
    ]
  }
}

PATCH /api/calendar/blocks/{blockId}/complete

블록을 완료 처리한다. 블록 유형에 따라 후속 처리가 다르다.

Response 200 (STUDY 블록)

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "blockId": 105,
    "status": "COMPLETED",
    "effect": {
      "type": "REVIEW_CREATED",
      "message": "복습 6회가 자동 생성되었습니다.",
      "nextReviewDate": "2026-04-03"
    },
    "dailyProgress": {
      "totalBlocks": 9,
      "completedBlocks": 4
    }
  }
}

Response 200 (REVIEW 블록)

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "blockId": 104,
    "status": "COMPLETED",
    "feedbackRequired": true,
    "reviewId": 45
  }
}

복습 블록은 완료 후 피드백 제출이 필요하다.


POST /api/reviews/{id}/feedback

복습 난이도 피드백을 제출한다.

Request

{
  "difficulty": "EASY"
}
  • difficulty: EASY / NORMAL / HARD

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "reviewId": 45,
    "difficulty": "EASY",
    "nextReview": {
      "sequence": 3,
      "scheduledDate": "2026-04-08",
      "adjustedInterval": "6일 (기존 4일 → 쉬움 반영)"
    }
  }
}

POST /api/calendar/blocks/{blockId}/postpone

블록을 미룬다.

Request

{
  "strategy": "TOMORROW"
}
  • strategy: TOMORROW / THIS_WEEK

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "blockId": 105,
    "postponedTo": "2026-04-03",
    "dailyProgress": {
      "totalBlocks": 8,
      "completedBlocks": 4
    }
  }
}

GET /api/rescheduling/options

연속 미완료 시 리스케줄링 선택지를 조회한다.

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "missedDays": 3,
    "missedItems": 12,
    "options": [
      {
        "strategy": "POSTPONE",
        "label": "뒤로 밀기",
        "description": "전체 일정 3일 후퇴",
        "deadlineFeasible": true,
        "newEstimatedCompletion": "2026-07-04"
      },
      {
        "strategy": "COMPRESS",
        "label": "압축",
        "description": "남은 기간에 밀린 양 분산",
        "dailyIncreasePercent": 20,
        "deadlineFeasible": true,
        "newEstimatedCompletion": "2026-07-01"
      },
      {
        "strategy": "KEEP_DEADLINE",
        "label": "데드라인 고정",
        "description": "하루 학습량 증가로 기존 일정 유지",
        "dailyIncreasePercent": 35,
        "deadlineFeasible": false,
        "warning": "하루 가용시간 대비 학습량이 과다합니다"
      }
    ]
  }
}

POST /api/rescheduling/apply

리스케줄링 전략을 적용한다.

Request

{
  "strategy": "COMPRESS"
}

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "strategy": "COMPRESS",
    "affectedDays": 87,
    "newDailyStudyMinutes": 144
  }
}

POST /api/materials

학습 자료를 생성한다.

Request

{
  "title": "이펙티브 자바",
  "type": "BOOK",
  "categoryId": 1,
  "goalId": 1,
  "deadline": "2026-07-01",
  "deadlineMode": "DEADLINE",
  "units": [
    { "title": "아이템 1 - 생성자 대신 정적 팩터리 메서드", "estimatedMinutes": 30 },
    { "title": "아이템 2 - 생성자에 매개변수가 많다면 빌더를 고려하라", "estimatedMinutes": 30 }
  ]
}

Response 201

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "id": 1,
    "title": "이펙티브 자바",
    "type": "BOOK",
    "totalUnits": 2,
    "completedUnits": 0,
    "deadlineMode": "DEADLINE",
    "deadline": "2026-07-01",
    "dailyRequired": 1,
    "estimatedCompletion": "2026-06-28"
  }
}

GET /api/dashboard/summary

대시보드 요약을 조회한다.

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "goals": [
      {
        "id": 1,
        "title": "백엔드 취업 준비",
        "progressPercent": 32,
        "paceStatus": "ON_TRACK"
      }
    ],
    "thisWeek": {
      "studyMinutes": 860,
      "reviewCompletionRate": 85
    },
    "streaks": {
      "overall": { "currentCount": 23, "longestCount": 30 },
      "routines": [
        { "routineId": 1, "title": "헬스", "currentCount": 15 },
        { "routineId": 2, "title": "영어", "currentCount": 23 }
      ]
    },
    "todayProgress": {
      "totalBlocks": 9,
      "completedBlocks": 4
    }
  }
}

GET /api/dashboard/heatmap

연간 히트맵 데이터를 조회한다.

Query Parameters

파라미터 타입 필수 설명
year int N 연도 (기본: 올해)

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "year": 2026,
    "days": [
      { "date": "2026-01-01", "achievementRate": 0 },
      { "date": "2026-01-02", "achievementRate": 80 },
      { "date": "2026-01-03", "achievementRate": 100 }
    ]
  }
}

GET /api/dashboard/statistics

기간별 통계를 조회한다.

Query Parameters

파라미터 타입 필수 설명
period string N DAILY / WEEKLY / MONTHLY (기본: WEEKLY)
startDate string N 시작일
endDate string N 종료일

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": {
    "period": "WEEKLY",
    "totalStudyMinutes": 860,
    "totalReviewMinutes": 240,
    "reviewCompletionRate": 85,
    "categoryBreakdown": [
      { "categoryId": 1, "name": "프로그래밍", "color": "#FF9800", "minutes": 680, "percent": 62 },
      { "categoryId": 2, "name": "알고리즘", "color": "#9C27B0", "minutes": 420, "percent": 38 }
    ]
  }
}

PUT /api/preferences

사용자 설정을 수정한다.

Request

{
  "wakeTime": "07:00",
  "sleepTime": "24:00",
  "studyTimePreference": "MORNING",
  "focusMinutes": 50,
  "breakMinutes": 10,
  "restDays": ["SUN"],
  "skipHolidays": false,
  "defaultReviewIntervals": [1, 2, 3, 7, 15, 30],
  "defaultMissedPolicy": "IMMEDIATE",
  "streakFreezePerMonth": 2
}

Response 200

{
  "code": "요청에 성공하였습니다.",
  "data": { ... }
}

5. Phase별 API 범위

Phase API
1 categories, goals, fixed-schedules, routines (기본), todos, materials, calendar/daily, preferences
2 reviews/feedback, calendar/weekly, calendar/monthly, rescheduling, calendar/blocks/postpone
3 dashboard (summary, streaks, heatmap, statistics), reflections
4 Google Calendar 연동 API, 학습 자료 OCR/URL 파싱 API, 알림 API

Clone this wiki locally