Repository navigation
Study Planner API Spec
범위: 학습 자료 CRUD + 노트(트리, Notion 스타일) + 플래시카드 CRUD + 복습 사이클. 카테고리, 목표, 캘린더, 알림 등은 범위 외. v2.1 변경: 노트 단건(1:1) → 트리 CRUD로 확장.
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} |
카드 수정 (front/back) |
| DELETE | /api/planner/flashcards/{id} |
카드 삭제 (cascade) |
| GET | /api/planner/reviews/today |
오늘 + 밀린 복습 조회 |
| 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_date <= today 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는 단건 조회 시 로드.
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로 서버가 자동 부여
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 -
제목 변경:
{ "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" }
}DELETE /api/planner/notes/{noteId}
해당 노트와 모든 자손 노트를 cascade 삭제. 클라이언트는 삭제 전 "하위 노트 N개도 함께 삭제됩니다" 확인.
Response 204: No Content
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"
}
]
}
}- 정렬: 생성순 (
idASC) -
nextReview: 가장 가까운 PENDING review (없으면null— 모든 회차 완료된 카드는 v2 시점엔 발생 안 함)
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자 (줄바꿈 허용)
PATCH /api/planner/flashcards/{id}
{
"front": "수정된 앞면",
"back": "수정된 뒷면"
}
복습 일정은 영향 없음. 콘텐츠만 변경.
DELETE /api/planner/flashcards/{id}
연결된 모든 review_schedule도 cascade 삭제.
Response 204
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 호출 없음)
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 참조).
| 항목 | 규칙 |
|---|---|
자료 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. 마지막 호출이 이김 (단일 사용자, 충돌 가능성 낮음) |
- 카테고리, 목표/마일스톤 CRUD
- 카드 태그/덱, sort_order 변경
- 카드 일괄 입력 (CSV, Anki
.apkg) - 카드 멀티미디어 업로드
- 노트 검색 / 풀텍스트 인덱싱
- 노트 즐겨찾기/아이콘/커버 (Notion 메타)
- 노트 ↔ 카드 인라인 연결
- 고정 일정, 루틴, 할 일 CRUD
- 자료 일시정지/재개 (
pause/resume) — 현재는 status 직접 수정으로 대체 - 자료별 복습 주기 오버라이드, 시간 할당, 일별 오버라이드
- 캘린더 (일/주/월) 조회
- 대시보드, 스트릭, 일일 회고
- 알림, 외부 캘린더 연동