Repository navigation
Study Planner API Spec
범위: 학습 자료 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}).
응답/에러 형식은 BE 에러 처리 컨벤션을 따른다.
| 코드 | HTTP | 메시지 |
|---|---|---|
| SP-ERR-001 | 404 | 존재하지 않는 리소스입니다 |
| SP-ERR-002 | 400 | 유효하지 않은 요청입니다 |
| SP-ERR-003 | 409 | 현재 상태에서 수행할 수 없는 작업입니다 |
추가 에러 코드는 구현 과정에서 필요 시 추가한다.
| 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 |
복습 평가 → 다음 복습 자동 생성 |
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 수
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
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로 조회 (탭 전환 시 호출).
PATCH /api/planner/materials/{id}
{
"title": "이펙티브 자바 3rd",
"status": "COMPLETED"
}
전송한 필드만 부분 업데이트.
DELETE /api/planner/materials/{id}
자료, 노트, 카드, 복습 일정 모두 cascade 삭제.
Response 204: No Content
자료에 속한 노트는 트리 구조다. 트리 조회는 제목/계층만 (가벼움), content는 단건 조회 시 로드.
v2.2 인라인 하위 페이지: 하위 노트는 본문에서
/페이지로 만든다. 즉 클라이언트가POST .../notes { parentId }로 자식 노트를 만든 뒤, 받은noteId를 부모 본문의childPageTiptap 노드 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": "싱글턴" } }
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.
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.
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"
}
}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" }
}DELETE /api/planner/notes/{noteId}
해당 노트와 모든 자손 노트를 cascade 삭제. 클라이언트는 삭제 전 "하위 노트 N개도 함께 삭제됩니다" 확인.
Response 204: No Content
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_atASC,idASC 타이브레이크) -
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 시점엔 발생 안 함). 카드 종류와 무관하게 동일
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개, 각text1~1000자,id(문자열) 카드 내 유일. BASIC이면 무시(NULL 저장) -
bidirectional(v2.4): 선택 boolean, 기본 false. BASIC +back존재일 때만 허용. ORDERING이면400
PATCH /api/planner/flashcards/{id}
{
"front": "수정된 지시문",
"items": [ { "id": "it_a1", "text": "..." }, ... ]
}
- 전송한 필드만 부분 업데이트.
type변경도 허용하되, 변경 시 대상 종류의 제약(6.2)을 만족해야 한다(예: BASIC→ORDERING이면items3~7개 필수). - 복습 일정은 영향 없음. 콘텐츠만 변경.
DELETE /api/planner/flashcards/{id}
연결된 모든 review_schedule도 cascade 삭제.
Response 204
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는 카드 종류를 구분하지 않는다.
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.
GET /api/planner/reviews/calendar?from=2026-04-27&to=2026-06-07
월간 캘린더 그리드에 표시할 복습 일정을 기간으로 조회. 그리드는 앞뒤 달 일부를 포함하므로 from6주 범위.to는 보통 5
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
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내림차순 등 구현 재량.
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)
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를 쓴다
| 항목 | 규칙 |
|---|---|
자료 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. 마지막 호출이 이김 (단일 사용자, 충돌 가능성 낮음) |
- 카테고리, 목표/마일스톤 CRUD
- 카드 태그/덱, sort_order 변경
- 카드 일괄 입력 (CSV, Anki
.apkg) - 카드 멀티미디어 업로드
- 노트 검색 / 풀텍스트 인덱싱
- 노트 즐겨찾기/아이콘/커버 (Notion 메타)
- 노트 ↔ 카드 인라인 연결
- 고정 일정, 루틴, 할 일 CRUD
- 자료 일시정지/재개 (
pause/resume) — 현재는 status 직접 수정으로 대체 - 자료별 복습 주기 오버라이드, 시간 할당, 일별 오버라이드
- 캘린더 (일/주/월) 조회
- 대시보드, 스트릭, 일일 회고
- 알림, 외부 캘린더 연동