Skip to content

Study Planner API Spec

wcorn edited this page Jul 29, 2026 · 18 revisions

API 설계: Study Planner (v2.6)

범위: 학습 자료 CRUD + 노트(Notion 인라인 하위 페이지) + 플래시카드 CRUD + 복습 사이클 + 복습 캘린더. 카테고리, 목표, 알림 등은 범위 외. v2.1: 노트 단건(1:1) → 트리 CRUD. v2.2: 인라인 하위 페이지 방식 — API 엔드포인트는 v2.1 그대로, 본문 content 안 childPage 노드로 트리 표현. v2.3: 순서 카드 도입 — 엔드포인트 추가 없음. 카드 생성/수정/조회 페이로드에 type(BASIC/ORDERING)·items(JSON)를 추가하고 back을 nullable로 확장. 복습 평가(/reviews/{id}/complete)는 그대로. v2.4: 양방향 짝 카드 — 엔드포인트 추가 없음. 카드 생성 요청에 bidirectional 옵션(BASIC 전용) 추가 시 정·역방향 카드 2개를 생성해 응답한다. 카드 응답에 siblingGroupId 추가. 복습 완료 응답에 sibling burying으로 밀린 buriedReviewIds 추가. v2.6: 카드 목록 탐색 — 엔드포인트 추가 없음. GET /materials/{id}/flashcards에 검색(q)·필터(type/review)·정렬(sort)과 커서(keyset) 페이지네이션(cursor/size)을 추가하고, 응답에 totalCount·nextCursor·hasNext를 동봉한다. 커서 인코딩은 복습 목록과 공용 KeysetCursor를 쓴다. 스키마·복습 로직 변경 없음. (#992) v2.5: 복습 허브("오늘 복습" → "복습") — 조회 API 3종 추가(GET /reviews/summary 현황 집계 + GET /reviews/upcoming 앞으로 목록 + GET /reviews/completed 완료 목록). 앞으로·완료는 커서(keyset) 페이지네이션 + 무한 스크롤. 세션(카드 넘기기)은 기존 GET /reviews/today를 그대로 쓰고 스코프(전체/밀림/자료별)는 클라이언트 필터. 복습 로직·평가·스키마 변경 없음. 결정은 Open Items §0-D.

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} 카드 수정 (type/front/back/items)
DELETE /api/planner/flashcards/{id} 카드 삭제 (cascade)
GET /api/planner/reviews/today 오늘 + 밀린 복습 조회 (세션 큐)
GET /api/planner/reviews/summary (v2.5) 복습 허브 현황 집계 (지금/밀림/앞으로/오늘 완료 + 자료별)
GET /api/planner/reviews/upcoming (v2.5) 앞으로의 복습 목록 (전 PENDING, 필터 + 커서 페이징)
GET /api/planner/reviews/completed (v2.5) 완료된 복습 목록 (필터 + 커서 페이징)
GET /api/planner/reviews/calendar 기간(월) 복습 일정 조회 (캘린더)
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_at <= now 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는 단건 조회 시 로드.

v2.2 인라인 하위 페이지: 하위 노트는 본문에서 /페이지로 만든다. 즉 클라이언트가 POST .../notes { parentId }로 자식 노트를 만든 뒤, 받은 noteId를 부모 본문의 childPage Tiptap 노드 attrs에 넣어 PATCH /notes/{parentId} { content }로 저장한다. BE API 엔드포인트는 v2.1과 동일 — 본문의 childPage 노드는 BE 입장에선 그냥 content JSON의 일부다. 본문에서 childPage 블록을 지우면 클라이언트가 DELETE /notes/{childId}를 호출한다.

childPage 노드 형식 (content JSON 내부):

{ "type": "childPage", "attrs": { "noteId": 103, "title": "싱글턴" } }

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로 서버가 자동 부여
  • 인라인 흐름: 본문 /페이지로 자식 생성 시, 클라이언트는 응답의 id(noteId)를 부모 본문의 childPage 노드 attrs에 넣고 부모를 PATCH로 저장한다

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. content 안 childPage 노드 포함
  • 제목 변경: { "title": ... } → 사이드바 + 부모 본문 childPage 블록 라벨 갱신
  • 이동 (parentId 변경): API는 지원하나 v2.2 FE 1차에서는 사용 안 함 (인라인 모델에서 본문 블록 이동과 엮여 복잡 → 차기)

제약:

  • 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
  ?q=&type=all&review=all&sort=created_asc&cursor=&size=30

Query params (v2.6, #992) — 검색·필터·정렬·페이징의 SSOT는 서버다. 페이징이 걸린 목록을 FE에서 다시 거르면 이미 로드된 페이지에만 적용되어 결과가 어긋나므로, 클라이언트는 재필터링하지 않는다.

파라미터 값 기본 설명
q 문자열 — front · back · items(JSON) 부분일치. 대소문자 무관. 공백뿐이면 무시
type all | basic | order | pair all 복습 허브와 동일한 종류 축. pair = BASIC + siblingGroupId IS NOT NULL 파생, basic = 단방향 BASIC
review all | overdue | today | upcoming all PENDING 복습 시각 구간. 경계는 사용자 시간대 자정
sort created_asc | created_desc created_asc 생성순만. 복습 임박순은 지원하지 않는다 — nextReview가 PENDING의 min이라 keyset 커서로 안정 페이징이 어렵고, 그 용도는 복습 허브(/reviews/upcoming)가 자료 필터와 함께 이미 제공한다
cursor 불투명 문자열 — 이전 응답의 nextCursor를 그대로 전달
size 1~100 30 범위를 벗어나면 잘림

알 수 없는 type/review/sort 값이나 깨진 cursor는 400(SP-ERR-002).

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "flashcards": [
      {
        "id": 11,
        "materialId": 1,
        "type": "BASIC",
        "front": "정적 팩토리 메서드의 장점 4가지는?",
        "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X",
        "items": null,
        "siblingGroupId": null,
        "nextReview": {
          "id": 95,
          "scheduledAt": "2026-05-23T04:00:00",
          "intervalDays": 6,
          "easeFactor": 2.50,
          "sequence": 2
        },
        "createdAt": "2026-05-17T10:30:00"
      },
      {
        "id": 12,
        "materialId": 1,
        "type": "ORDERING",
        "front": "kubectl apply 실행 이후 순서대로 배열",
        "back": null,
        "items": [
          { "id": "it_a1", "text": "apiserver 인증/인가" },
          { "id": "it_b2", "text": "etcd 저장" },
          { "id": "it_c3", "text": "controller 감지" },
          { "id": "it_d4", "text": "scheduler 노드 선택" },
          { "id": "it_e5", "text": "kubelet 파드 생성" }
        ],
        "nextReview": {
          "id": 96, "scheduledAt": "2026-05-19T04:00:00",
          "intervalDays": 1, "easeFactor": 2.50, "sequence": 1
        },
        "createdAt": "2026-05-18T09:00:00"
      }
    ],
    "totalCount": 43,
    "nextCursor": "MjAyNi0wNS0xOFQwOTowMDowMFp8MTI",
    "hasNext": true
  }
}
  • 정렬: sort 파라미터 (기본 생성순 created_at ASC, id ASC 타이브레이크)
  • totalCount: 필터를 적용한 총 개수(페이지 길이가 아님). 목록 상단 "N장" 표시용
  • nextCursor: (created_at, id) keyset을 base64로 인코딩한 불투명 문자열. 마지막 페이지면 생략. 형식은 내부 구현 세부사항이며 FE는 그대로 되돌려준다
  • hasNext: 다음 페이지 존재 여부
  • type: BASIC | ORDERING. BASIC이면 items = null, ORDERING이면 back = null
  • items(ORDERING): 항상 정답 순서(index 0 = 1단계). 각 항목 { id, text }. FE가 복습 시 셔플해서 표시
  • siblingGroupId(v2.4): 양방향 짝이 공유하는 키. 단독 카드는 null. 같은 값이면 서로 짝 카드
  • nextReview: 가장 가까운 PENDING review (없으면 null — 모든 회차 완료된 카드는 v2 시점엔 발생 안 함). 카드 종류와 무관하게 동일

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

BASIC 카드:

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

ORDERING 카드 (front=지시문, items=정답 순서 3~7개):

POST /api/planner/materials/{materialId}/flashcards
{
  "type": "ORDERING",
  "front": "kubectl apply 실행 이후 순서대로 배열",
  "items": [
    { "id": "it_a1", "text": "apiserver 인증/인가" },
    { "id": "it_b2", "text": "etcd 저장" },
    { "id": "it_c3", "text": "controller 감지" },
    { "id": "it_d4", "text": "scheduler 노드 선택" },
    { "id": "it_e5", "text": "kubelet 파드 생성" }
  ]
}

type 생략 시 BASIC으로 간주(하위 호환).

양방향 카드 (bidirectional: true, BASIC 전용) — 정·역방향 카드 2개를 한 번에 생성:

POST /api/planner/materials/{materialId}/flashcards
{
  "type": "BASIC",
  "front": "쿠버네티스의 정의",
  "back": "컨테이너화된 애플리케이션의 배포·확장·운영을 선언적으로 자동화하는 오케스트레이션 시스템",
  "bidirectional": true
}
  • A(front→back)와 B(back→front) 두 카드를 같은 siblingGroupId로 생성한다.
  • 첫 복습 엇갈림: A는 (today+1) 04:00, B는 (today+2) 04:00 (sibling burying — Data-Model §4.6).
  • 생성 후 두 카드는 독립(편집 동기화 없음). bidirectional은 생성 시 동작일 뿐 저장 필드가 아니다.

Response 201: 생성된 flashcard(6.1의 카드 객체 형식 — type/items/siblingGroupId 포함) + firstReview(카드 종류 무관 동일). bidirectional: true면 짝 카드를 sibling에 담아 함께 반환:

{
  "code": "SUCCESS",
  "data": {
    "flashcard": { "id": 20, "type": "BASIC", "front": "쿠버네티스의 정의", "back": "...", "items": null, "siblingGroupId": 20, "createdAt": "..." },
    "firstReview": { "id": 100, "flashcardId": 20, "sequence": 1, "scheduledAt": "2026-07-07T04:00:00", "intervalDays": 1, "easeFactor": 2.50, "status": "PENDING" },
    "sibling": {
      "flashcard": { "id": 21, "type": "BASIC", "front": "컨테이너화된 ... 오케스트레이션 시스템", "back": "쿠버네티스의 정의", "items": null, "siblingGroupId": 20, "createdAt": "..." },
      "firstReview": { "id": 101, "flashcardId": 21, "sequence": 1, "scheduledAt": "2026-07-08T04:00:00", "intervalDays": 1, "easeFactor": 2.50, "status": "PENDING" }
    }
  }
}

단방향(기본)일 때 sibling은 생략(또는 null). 아래는 단방향 응답 예시.

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

제약 (위반 시 400 SP-ERR-002):

  • type: BASIC | ORDERING (생략 시 BASIC)
  • front: 필수, 1~1000자 (줄바꿈 허용) — ORDERING에선 지시문
  • back: BASIC일 때만 필수, 1~1000자. ORDERING이면 무시(NULL 저장)
  • items: ORDERING일 때만 필수 — 3~7개, 각 text 1~1000자, id(문자열) 카드 내 유일. BASIC이면 무시(NULL 저장)
  • bidirectional(v2.4): 선택 boolean, 기본 false. BASIC + back 존재일 때만 허용. ORDERING이면 400

6.3 카드 수정

PATCH /api/planner/flashcards/{id}
{
  "front": "수정된 지시문",
  "items": [ { "id": "it_a1", "text": "..." }, ... ]
}
  • 전송한 필드만 부분 업데이트. type 변경도 허용하되, 변경 시 대상 종류의 제약(6.2)을 만족해야 한다(예: BASIC→ORDERING이면 items 3~7개 필수).
  • 복습 일정은 영향 없음. 콘텐츠만 변경.

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_at <= now AND status = PENDING. 정렬: scheduled_at ASC, id ASC.

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "today": "2026-05-17",
    "reviews": [
      {
        "id": 95,
        "scheduledAt": "2026-05-15T04:00:00",
        "delayDays": 2,
        "sequence": 2,
        "intervalDays": 6,
        "easeFactor": 2.50,
        "flashcard": {
          "id": 11,
          "type": "BASIC",
          "front": "정적 팩토리 메서드의 장점 4가지는?",
          "back": "이름을 가질 수 있다 / 인스턴스 통제 / 반환 타입 다형성 / 매번 새 인스턴스 X",
          "items": null,
          "siblingGroupId": null,
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        },
        "preview": {
          "again": 1,
          "hard": 4,
          "good": 6,
          "easy": 8
        }
      }
    ]
  }
}
  • delayDays: today - DATE(scheduled_at) (0이면 정확히 오늘)
  • preview: 각 평가 시 다음 복습까지의 일수. 클라이언트가 버튼 위에 미리보기 표시
  • 응답에는 back도 포함되어 클라이언트에서 답 공개 시 즉시 표시 (추가 API 호출 없음)
  • ORDERING 카드도 같은 큐에 섞여 온다(type: "ORDERING", items 포함, back: null). 클라이언트가 items를 셔플해 배열 UI로 표시하고, 사용자가 순서를 맞춘 뒤 동일한 4등급 평가로 7.2를 호출한다. 평가 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,
      "scheduledAt": "2026-05-23T04:00:00",
      "intervalDays": 6,
      "easeFactor": 2.50,
      "status": "PENDING"
    },
    "buriedReviewIds": [131]
  }
}
  • 다음 due 시각: AGAIN은 now + 10분(분 단위 당일 재복습), 그 외는 (today + intervalDays) 04:00(롤오버). 산정식은 Data-Model §4, 놓친 복습 정책은 Architecture §4.4 참조.
  • buriedReviewIds(v2.4): 이번 완료로 sibling burying이 발동해 다음날로 밀린 형제 review id 배열. 짝 카드가 없거나 형제가 오늘 due가 아니면 빈 배열. FE는 이 id들을 현재 세션 복습 큐에서 제거한다(오늘 안 나오게). 상세는 Data-Model §4.6.

7.3 복습 캘린더 조회

GET /api/planner/reviews/calendar?from=2026-04-27&to=2026-06-07

월간 캘린더 그리드에 표시할 복습 일정을 기간으로 조회. 그리드는 앞뒤 달 일부를 포함하므로 fromto는 보통 56주 범위.

Query:

  • from, to: 조회 범위 (날짜, inclusive). 둘 다 필수
  • 조건: member_id = me AND scheduled_at 가 [from 00:00, to 23:59:59] 구간 (status 무관 — PENDING + COMPLETED 모두)

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "today": "2026-05-16",
    "items": [
      {
        "id": 95,
        "scheduledAt": "2026-05-16T04:00:00",
        "status": "PENDING",
        "sequence": 2,
        "flashcard": {
          "id": 11,
          "front": "정적 팩토리 메서드의 장점 4가지는?",
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        }
      },
      {
        "id": 80,
        "scheduledAt": "2026-05-14T04:00:00",
        "status": "COMPLETED",
        "rating": "GOOD",
        "sequence": 1,
        "flashcard": {
          "id": 9,
          "front": "...",
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        }
      }
    ]
  }
}

클라이언트 처리 (상태 분류는 FE에서 DATE(scheduledAt)와 today 비교로 계산):

  • status = COMPLETED → 완료 (회색/체크)

  • status = PENDING:

    • DATE(scheduledAt) < today → 밀림 (빨강)
    • DATE(scheduledAt) = today → 오늘 (primary)
    • DATE(scheduledAt) > today → 예정 (중립)
  • 모든 항목은 DATE(scheduledAt) 칸에 배치 (완료 항목도 원래 예정일 칸에)

  • 날짜별 그룹핑/카운트는 FE에서 계산 (단일 사용자, 월 데이터 적음)

  • 정렬: scheduledAt ASC, id ASC

7.4 복습 허브 현황 집계 (v2.5)

GET /api/planner/reviews/summary

복습 허브 좌 레일의 요약 수치와 자료별 현황. 모두 서버 집계 값(무한 스크롤 목록 슬라이스 길이와 무관한 총계 — Open Items §0D.4).

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "today": "2026-07-11",
    "counts": {
      "now": 18,
      "overdue": 5,
      "upcoming": 37,
      "doneToday": 9
    },
    "estimatedMinutes": 12,
    "materials": [
      { "id": 1, "name": "이펙티브 자바",   "due": 6, "overdue": 2, "nextLabel": "지금" },
      { "id": 2, "name": "알고리즘 문제풀이", "due": 5, "overdue": 3, "nextLabel": "지금" },
      { "id": 5, "name": "SQL 튜닝",         "due": 0, "overdue": 0, "nextLabel": "내일 07/12" }
    ]
  }
}
  • counts.now: PENDING AND scheduled_at <= now (지금 할 것). 전체 복습 시작 대상 = 이 수.
  • counts.overdue: PENDING AND DATE(scheduled_at) < today (밀림). now의 부분집합.
  • counts.upcoming: PENDING 전체 (지금 due + 오늘 남음 + 미래). 앞으로 탭 총계.
  • counts.doneToday: COMPLETED AND DATE(completed_at) = today (오늘 완료). 완료 목록은 최근 전체지만 이 수치는 오늘만 (§0D.8).
  • estimatedMinutes: now 카드 수 기반 예상 소요(대략치, 카드당 상수). FE "약 N분" 표기.
  • materials[]: 자료별 오늘 due 수(due) · 밀림 수(overdue) · 다음 복습 라벨(nextLabel). 행 클릭 시 그 자료로 세션 진입(due 0이면 no-op). 정렬은 due 내림차순 등 구현 재량.

7.5 앞으로의 복습 목록 (v2.5)

GET /api/planner/reviews/upcoming?scope=all&materialId=1&when=all&type=all&cursor=&size=20

앞으로 탭 목록. 모든 PENDING 복습(지금 due 포함)을 scheduled_at 오름차순으로 커서 페이지네이션(§0D.5·0D.6).

Query (모두 선택):

  • scope: all(기본) | today(지금+오늘) | overdue(밀림만) — 상태 배지가 설정
  • materialId: 자료 필터
  • when: all(기본) | today | 3d | 7d — 기간 필터(Select). scope와 교집합 적용
  • type: all(기본) | basic | order | pair — 카드 종류. pair는 파생: basic=BASIC AND siblingGroupId IS NULL, order=ORDERING, pair=BASIC AND siblingGroupId IS NOT NULL (§0D.7)
  • cursor: 이전 응답의 nextCursor. 미전송 시 첫 페이지
  • size: 기본 20, 최대 50

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "today": "2026-07-11",
    "items": [
      {
        "id": 501,
        "scheduledAt": "2026-07-11T02:10:00",
        "whenKind": "now",
        "overdue": true,
        "cardType": "PAIR",
        "flashcard": {
          "id": 11,
          "type": "BASIC",
          "front": "빌더 패턴을 선택하는 기준은?",
          "siblingGroupId": 20,
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        }
      },
      {
        "id": 502,
        "scheduledAt": "2026-07-11T09:40:00",
        "whenKind": "now",
        "overdue": false,
        "cardType": "PAIR",
        "flashcard": {
          "id": 12, "type": "BASIC", "front": "정적 팩터리 메서드 vs 생성자",
          "siblingGroupId": 20,
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        }
      },
      {
        "id": 510,
        "scheduledAt": "2026-07-12T04:00:00",
        "whenKind": "future",
        "overdue": false,
        "cardType": "ORDERING",
        "flashcard": {
          "id": 40, "type": "ORDERING", "front": "TCP 3-way handshake의 순서",
          "siblingGroupId": null,
          "material": { "id": 4, "title": "컴퓨터 네트워크", "type": "BOOK" }
        }
      }
    ],
    "nextCursor": "eyJzIjoiMjAyNi0wNy0xMlQwNDowMDowMCIsImlkIjo1MTB9",
    "hasNext": true
  }
}
  • 정렬: scheduled_at ASC, id ASC. 커서는 (scheduled_at, id) keyset을 base64 인코딩한 불투명 문자열
  • whenKind: now(due 또는 임박한 재복습 — FE가 primary 강조) | today(오늘 남음) | future(내일 이후). 임계값은 구현 세부
  • overdue: DATE(scheduled_at) < today → FE "밀림" pill
  • cardType: 표시용 파생 — BASIC(기본) | ORDERING(순서) | PAIR(양방향). FE 종류 칩
  • whenLabel(지금/10분 후/오늘 20:30/내일 07/12)은 FE가 scheduledAt과 현재 시각으로 포맷한다(서버는 scheduledAt + whenKind만 제공). back/items는 목록엔 불필요해 미포함(세션 진입 시 /today로 로드)
  • nextCursor가 null이면 마지막 페이지(hasNext: false)

7.6 완료된 복습 목록 (v2.5)

GET /api/planner/reviews/completed?materialId=1&grade=GOOD&cursor=&size=20

완료 탭 목록. 최근 완료 전체(어제 이전 포함)를 completed_at 내림차순으로 커서 페이지네이션(§0D.8).

Query (모두 선택):

  • materialId: 자료 필터
  • grade: AGAIN | HARD | GOOD | EASY — 평가 등급 필터
  • cursor: 이전 응답의 nextCursor. 미전송 시 첫 페이지
  • size: 기본 20, 최대 50

Response 200:

{
  "code": "SUCCESS",
  "data": {
    "items": [
      {
        "id": 480,
        "completedAt": "2026-07-11T09:12:00",
        "rating": "GOOD",
        "sequence": 3,
        "cardType": "BASIC",
        "flashcard": {
          "id": 9, "type": "BASIC", "front": "제네릭 와일드카드 ? extends T의 의미",
          "siblingGroupId": null,
          "material": { "id": 1, "title": "이펙티브 자바", "type": "BOOK" }
        }
      },
      {
        "id": 465,
        "completedAt": "2026-07-10T22:10:00",
        "rating": "HARD",
        "sequence": 2,
        "cardType": "BASIC",
        "flashcard": {
          "id": 33, "type": "BASIC", "front": "커버링 인덱스란 무엇인가",
          "siblingGroupId": null,
          "material": { "id": 5, "title": "SQL 튜닝", "type": "BOOK" }
        }
      }
    ],
    "nextCursor": "eyJjIjoiMjAyNi0wNy0xMFQyMjoxMDowMCIsImlkIjo0NjV9",
    "hasNext": true
  }
}
  • 정렬: completed_at DESC, id DESC. 커서는 (completed_at, id) keyset. 인덱스 (member_id, status, completed_at) 사용 (Data-Model §6.5)
  • rating → FE Badge variant: AGAIN → destructive(다시), HARD → warning(어려움), GOOD → success(양호), EASY → info(쉬움)
  • completedAt 시각 라벨(오늘 09:12 / 어제 22:10)은 FE 포맷
  • 오늘 완료 배지 수치는 이 목록 길이가 아니라 GET /reviews/summary의 counts.doneToday를 쓴다

8. 검증 규칙

항목 규칙
자료 title 1~200자, 비어있지 않음
자료 type BOOK / LECTURE / WORKBOOK / MOOC
노트 title 1~200자. 미전송 시 "제목 없음"
노트 content Tiptap doc JSON, 직렬화 크기 1MB 이하
노트 parentId 자기 자신/자손으로 이동 불가 (사이클 방지). 같은 자료 내 노트만
노트 삭제 서브트리 cascade (자손 전부 삭제)
카드 type BASIC / ORDERING (생략 시 BASIC)
카드 front 1~1000자, 비어있지 않음. 줄바꿈 허용 (ORDERING=지시문)
카드 back BASIC만 필수, 1~1000자. ORDERING이면 NULL 저장
카드 items ORDERING만 필수 — 3~7개, 각 text 1~1000자, id(문자열) 카드 내 유일. 배열 순서=정답 순서
카드 bidirectional 선택 boolean(기본 false). BASIC + back 존재일 때만 허용. true면 정·역방향 카드 2개 생성
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