Skip to content

Study Planner API Spec

wcorn edited this page May 31, 2026 · 18 revisions

API 설계: Study Planner (v2.1)

범위: 학습 자료 CRUD + 노트(트리, Notion 스타일) + 플래시카드 CRUD + 복습 사이클. 카테고리, 목표, 캘린더, 알림 등은 범위 외. v2.1 변경: 노트 단건(1:1) → 트리 CRUD로 확장.

Base URL: /api

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

1. 공통 응답 형식

응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.

2. 에러 코드

코드 HTTP 메시지
SP-ERR-001 404 존재하지 않는 리소스입니다
SP-ERR-002 400 유효하지 않은 요청입니다
SP-ERR-003 409 현재 상태에서 수행할 수 없는 작업입니다

추가 에러 코드는 구현 과정에서 필요 시 추가한다.

3. 엔드포인트 목록

Method Path 설명
GET /api/planner/materials 학습 자료 목록
POST /api/planner/materials 학습 자료 생성
GET /api/planner/materials/{id} 학습 자료 상세 (카드 수 + 오늘 복습 수)
PATCH /api/planner/materials/{id} 학습 자료 수정
DELETE /api/planner/materials/{id} 학습 자료 삭제 (cascade)
GET /api/planner/materials/{id}/notes 노트 트리 조회 (제목+계층만)
POST /api/planner/materials/{id}/notes 노트 생성 (parent 지정)
GET /api/planner/notes/{noteId} 노트 단건 조회 (content 포함)
PATCH /api/planner/notes/{noteId} 노트 수정 (title / content / parent / sort_order)
DELETE /api/planner/notes/{noteId} 노트 삭제 (서브트리 cascade)
GET /api/planner/materials/{id}/flashcards 카드 목록
POST /api/planner/materials/{id}/flashcards 카드 생성 + 첫 복습 자동 생성
PATCH /api/planner/flashcards/{id} 카드 수정 (front/back)
DELETE /api/planner/flashcards/{id} 카드 삭제 (cascade)
GET /api/planner/reviews/today 오늘 + 밀린 복습 조회
POST /api/planner/reviews/{id}/complete 복습 평가 → 다음 복습 자동 생성

4. 학습 자료

4.1 자료 목록

GET /api/planner/materials?status=ACTIVE

Query: status (선택, ACTIVE/COMPLETED)

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "materials": [
      {
        "id": 1,
        "title": "이펙티브 자바",
        "type": "BOOK",
        "status": "ACTIVE",
        "flashcardCount": 24,
        "dueReviewCount": 3,
        "createdAt": "2026-05-17T10:00:00",
        "updatedAt": "2026-05-17T12:30:00"
      }
    ]
  }
}
  • flashcardCount: 자료의 전체 카드 수
  • dueReviewCount: scheduled_date <= today AND status = PENDING 인 review 수

4.2 자료 생성

POST /api/planner/materials
{
  "title": "이펙티브 자바",
  "type": "BOOK"
}

자료는 빈 노트 트리로 시작한다 (노트 자동 생성 없음). 사용자가 이후 [+ 노트]로 추가.

Response 201:

{
  "code": "SUCCESS",
  "data": {
    "id": 1,
    "title": "이펙티브 자바",
    "type": "BOOK",
    "status": "ACTIVE",
    "flashcardCount": 0,
    "dueReviewCount": 0,
    "createdAt": "2026-05-17T10:00:00",
    "updatedAt": "2026-05-17T10:00:00"
  }
}

제약:

  • title: 필수, 1~200자
  • type: 필수, BOOK/LECTURE/WORKBOOK/MOOC

4.3 자료 상세

GET /api/planner/materials/{id}

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "id": 1,
    "title": "이펙티브 자바",
    "type": "BOOK",
    "status": "ACTIVE",
    "flashcardCount": 24,
    "dueReviewCount": 3,
    "createdAt": "2026-05-17T10:00:00",
    "updatedAt": "2026-05-17T12:30:00"
  }
}

노트 트리와 카드는 별도 API로 조회 (탭 전환 시 호출).

4.4 자료 수정

PATCH /api/planner/materials/{id}
{
  "title": "이펙티브 자바 3rd",
  "status": "COMPLETED"
}

전송한 필드만 부분 업데이트.

4.5 자료 삭제

DELETE /api/planner/materials/{id}

자료, 노트, 카드, 복습 일정 모두 cascade 삭제.

Response 204: No Content


5. 노트 (Notion 스타일 트리)

자료에 속한 노트는 트리 구조다. 트리 조회는 제목/계층만 (가벼움), content는 단건 조회 시 로드.

5.1 노트 트리 조회

GET /api/planner/materials/{materialId}/notes

자료의 모든 노트를 트리(중첩 배열) 로 반환한다. content는 제외 (제목/메타만).

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "notes": [
      {
        "id": 101,
        "title": "1장 객체 생성",
        "parentId": null,
        "sortOrder": 0,
        "children": [
          { "id": 102, "title": "정적 팩토리 메서드", "parentId": 101, "sortOrder": 0, "children": [] },
          { "id": 103, "title": "싱글턴", "parentId": 101, "sortOrder": 1, "children": [] }
        ]
      },
      {
        "id": 110,
        "title": "2장 객체 파괴",
        "parentId": null,
        "sortOrder": 1,
        "children": []
      }
    ]
  }
}

서버는 flat 목록을 조회한 뒤 트리로 조립해 반환한다 (단일 사용자, 노트 수 적음). 또는 flat 배열을 반환하고 FE에서 조립해도 됨 — 구현 시 택1.

5.2 노트 단건 조회 (content 포함)

GET /api/planner/notes/{noteId}

트리에서 노트를 클릭했을 때 호출. 해당 노트의 본문 content 로드.

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "id": 102,
    "materialId": 1,
    "parentId": 101,
    "title": "정적 팩토리 메서드",
    "sortOrder": 0,
    "content": {
      "type": "doc",
      "content": [
        { "type": "paragraph", "content": [{ "type": "text", "text": "이름을 가질 수 있다 ..." }] }
      ]
    },
    "updatedAt": "2026-05-17T12:30:00"
  }
}

존재하지 않으면 404 SP-ERR-001.

5.3 노트 생성

POST /api/planner/materials/{materialId}/notes
{
  "parentId": 101,
  "title": "싱글턴"
}
  • parentId: null이면 루트 노트, 값이 있으면 해당 노트의 자식
  • title: 선택. 미전송 시 "제목 없음"
  • content: 빈 doc으로 초기화
  • sortOrder: 같은 부모 내 max + 1로 서버가 자동 부여

Response 201:

{
  "code": "SUCCESS",
  "data": {
    "id": 103,
    "materialId": 1,
    "parentId": 101,
    "title": "싱글턴",
    "sortOrder": 1,
    "content": { "type": "doc", "content": [] },
    "updatedAt": "2026-05-17T12:35:00"
  }
}

5.4 노트 수정 (title / content / 이동 / 정렬)

PATCH /api/planner/notes/{noteId}
{
  "title": "싱글턴 패턴",
  "content": { "type": "doc", "content": [...] },
  "parentId": 110,
  "sortOrder": 0
}

전송한 필드만 부분 업데이트. 용도별로 나눠 호출 가능:

  • 자동 저장 (본문 입력): { "content": ... } — FE 2초 debounce
  • 제목 변경: { "title": ... }
  • 이동 (드래그 앤 드롭): { "parentId": ..., "sortOrder": ... }

제약:

  • content: Tiptap doc JSON, 직렬화 크기 1MB 이하. 초과 시 400 SP-ERR-002
  • title: 1~200자
  • parentId: 자기 자신 또는 자손으로 이동 불가 (사이클 방지). 위반 시 400 SP-ERR-002
  • 다른 자료의 노트를 부모로 지정 불가 (400 SP-ERR-002)

Response 200:

{
  "code": "SUCCESS",
  "data": { "id": 103, "title": "싱글턴 패턴", "parentId": 110, "sortOrder": 0, "updatedAt": "2026-05-17T12:40:00" }
}

5.5 노트 삭제 (서브트리)

DELETE /api/planner/notes/{noteId}

해당 노트와 모든 자손 노트를 cascade 삭제. 클라이언트는 삭제 전 "하위 노트 N개도 함께 삭제됩니다" 확인.

Response 204: No Content


6. 플래시카드

6.1 카드 목록

GET /api/planner/materials/{materialId}/flashcards

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "flashcards": [
      {
        "id": 11,
        "materialId": 1,
        "front": "정적 팩토리 메서드의 장점 4가지는?",
        "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X",
        "nextReview": {
          "id": 95,
          "scheduledDate": "2026-05-23",
          "intervalDays": 6,
          "easeFactor": 2.50,
          "sequence": 2
        },
        "createdAt": "2026-05-17T10:30:00"
      }
    ]
  }
}
  • 정렬: 생성순 (id ASC)
  • nextReview: 가장 가까운 PENDING review (없으면 null — 모든 회차 완료된 카드는 v2 시점엔 발생 안 함)

6.2 카드 생성 → 첫 복습 자동 생성

POST /api/planner/materials/{materialId}/flashcards
{
  "front": "정적 팩토리 메서드의 장점 4가지는?",
  "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X"
}

Response 201:

{
  "code": "SUCCESS",
  "data": {
    "flashcard": {
      "id": 11,
      "materialId": 1,
      "front": "정적 팩토리 메서드의 장점 4가지는?",
      "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X",
      "createdAt": "2026-05-17T10:30:00"
    },
    "firstReview": {
      "id": 90,
      "flashcardId": 11,
      "sequence": 1,
      "scheduledDate": "2026-05-18",
      "intervalDays": 1,
      "easeFactor": 2.50,
      "status": "PENDING"
    }
  }
}

제약:

  • front: 필수, 1~1000자 (줄바꿈 허용)
  • back: 필수, 1~1000자 (줄바꿈 허용)

6.3 카드 수정

PATCH /api/planner/flashcards/{id}
{
  "front": "수정된 앞면",
  "back": "수정된 뒷면"
}

복습 일정은 영향 없음. 콘텐츠만 변경.

6.4 카드 삭제

DELETE /api/planner/flashcards/{id}

연결된 모든 review_schedule도 cascade 삭제.

Response 204


7. 복습

7.1 오늘 복습 조회

GET /api/planner/reviews/today

조건: member_id = me AND scheduled_date <= today AND status = PENDING. 정렬: scheduled_date ASC, id ASC.

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "today": "2026-05-17",
    "reviews": [
      {
        "id": 95,
        "scheduledDate": "2026-05-15",
        "delayDays": 2,
        "sequence": 2,
        "intervalDays": 6,
        "easeFactor": 2.50,
        "flashcard": {
          "id": 11,
          "front": "정적 팩토리 메서드의 장점 4가지는?",
          "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X",
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        },
        "preview": {
          "again": 1,
          "hard": 4,
          "good": 6,
          "easy": 8
        }
      }
    ]
  }
}
  • delayDays: today - scheduled_date (0이면 정확히 오늘)
  • preview: 각 평가 시 다음 복습까지의 일수. 클라이언트가 버튼 위에 미리보기 표시
  • 응답에는 back도 포함되어 클라이언트에서 답 공개 시 즉시 표시 (추가 API 호출 없음)

7.2 복습 평가 → 다음 복습 생성

POST /api/planner/reviews/{id}/complete
{
  "rating": "GOOD"
}

Body: rating ∈ AGAIN | HARD | GOOD | EASY

이미 COMPLETED 복습에 호출하면 409 SP-ERR-003.

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "completed": {
      "id": 95,
      "status": "COMPLETED",
      "rating": "GOOD",
      "elapsedDays": 2,
      "completedAt": "2026-05-17T22:00:00"
    },
    "nextReview": {
      "id": 102,
      "flashcardId": 11,
      "sequence": 3,
      "scheduledDate": "2026-05-23",
      "intervalDays": 6,
      "easeFactor": 2.50,
      "status": "PENDING"
    }
  }
}

scheduledDate = today + intervalDays (놓친 복습 정책 Architecture §4.4 참조).


8. 검증 규칙

항목 규칙
자료 title 1~200자, 비어있지 않음
자료 type BOOK / LECTURE / WORKBOOK / MOOC
노트 title 1~200자. 미전송 시 "제목 없음"
노트 content Tiptap doc JSON, 직렬화 크기 1MB 이하
노트 parentId 자기 자신/자손으로 이동 불가 (사이클 방지). 같은 자료 내 노트만
노트 삭제 서브트리 cascade (자손 전부 삭제)
카드 front / back 각 1~1000자, 비어있지 않음. 줄바꿈 허용
rating 4값 중 하나만
자료/카드 삭제 소프트 삭제 안 함. 물리 삭제 + cascade
동시성 복습 평가는 멱등성 보장: 이미 COMPLETED 면 409 SP-ERR-003
노트 저장 PATCH content idempotent. 마지막 호출이 이김 (단일 사용자, 충돌 가능성 낮음)

9. v2에 없는 API (차기 이후)

  • 카테고리, 목표/마일스톤 CRUD
  • 카드 태그/덱, sort_order 변경
  • 카드 일괄 입력 (CSV, Anki .apkg)
  • 카드 멀티미디어 업로드
  • 노트 검색 / 풀텍스트 인덱싱
  • 노트 즐겨찾기/아이콘/커버 (Notion 메타)
  • 노트 ↔ 카드 인라인 연결
  • 고정 일정, 루틴, 할 일 CRUD
  • 자료 일시정지/재개 (pause/resume) — 현재는 status 직접 수정으로 대체
  • 자료별 복습 주기 오버라이드, 시간 할당, 일별 오버라이드
  • 캘린더 (일/주/월) 조회
  • 대시보드, 스트릭, 일일 회고
  • 알림, 외부 캘린더 연동

Clone this wiki locally