Repository navigation
Study Planner Architecture
범위: 학습 자료 + Tiptap 노트(Notion 인라인 하위 페이지) + 플래시카드(1:N) + SM-2 카드별 복습 사이클 + 복습 허브 + 복습 캘린더. 자동 스케줄링, 배치 서비스는 범위 외. 변경 이력: v2.1 노트 단건 → 트리. v2.2 트리를 Notion 인라인 하위 페이지 방식으로 구현 (본문
/페이지로 하위 노트 생성, content 안 childPage 블록). BE(parent_id 트리 + note CRUD)는 v2.1 그대로, FE만 인라인 모델로. v2.3 순서 카드(type/items), v2.4 양방향 짝 카드(sibling_group_id+ burying). v2.5 복습 허브 — "오늘 복습"을 현황 집계 + 앞으로·완료 목록 조회로 확장. 조회 전용(요약 집계 + 커서 페이지네이션 2종) 추가이며 복습 로직·평가·스키마는 그대로.
복습 허브는 새 동작을 만들지 않고 기존 review_schedule을 읽어 보여주는 층이다(Open Items §0-D).
-
ReviewQueryService에 조회 3종 추가 — 현황 집계(summary) + 앞으로 목록(upcoming) + 완료 목록(completed). 평가/스케줄링(ReviewCompletionService, SM-2)은 무변경. -
집계(
summary):count(...)로 지금 due / 밀림 / 전 PENDING / 오늘 완료를 세고, 자료별 due·밀림·다음 라벨을 묶어 반환. 목록 길이가 아닌 총계라 별도 count 쿼리로 계산. -
목록(
upcoming/completed): 커서(keyset) 페이지네이션. 앞으로 = 전 PENDING을(scheduled_at, id)오름차순, 완료 = COMPLETED를(completed_at, id)내림차순. 필터(자료·기간·종류·평가)는 WHERE 조건으로. 인덱스는 Data-Model §2.4/§6.5 참조. -
세션 진입: 허브의 "전체/밀림/자료별 시작"은 기존
GET /reviews/today(지금 due)를 받아 FE가 스코프/자료를 필터해 세션 큐를 구성한다(세션 BE·burying 무변경, §0D.3).
┌──────────────────┐ ┌──────────────────────────────┐ ┌─────────┐
│ Frontend │ │ Backend │ │ MySQL │
│ (React + Tiptap)│─────▶│ (Spring Boot API) │─────▶│ │
│ │◀─────│ │◀─────│ │
└──────────────────┘ │ ┌────────────────────────┐ │ └─────────┘
│ │ ReviewSchedulerService │ │
│ │ (SM-2 알고리즘) │ │ ┌─────────┐
│ └────────────────────────┘ │─────▶│ Redis │
└──────────────────────────────┘ │ (인증만) │
└─────────┘
인증 모듈과 동일한 인프라(MySQL, Redis, K8s)를 공유한다.
배치 서비스 없음. SM-2는 평가 시점에 동기 계산.
멀티모듈 구조는 BE 코드 아키텍처를 따른다.
be/
├── orino-app-api/ # API 서버
├── orino-domain-rdb/ # 공유 도메인 (엔티티, 리포지토리)
├── orino-domain-redis/ # 인증 토큰
├── orino-core-web/ # 공통 웹 설정
└── orino-common/ # 공유 유틸
orino-domain-rdb (ds.project.orino.domain.planner/):
planner/
├── material/ # study_material
├── note/ # note
├── flashcard/ # flashcard
└── review/ # review_schedule
orino-app-api (ds.project.orino.planner/):
planner/
├── material/ # controller, service, dto (자료 CRUD)
├── note/ # controller, service, dto (노트 트리 CRUD + 이동/정렬)
├── flashcard/ # controller, service, dto (카드 CRUD)
└── review/ # controller, service, dto (오늘 복습, 평가)
├── sm2/ # 간격·ease 계산 (Anki SM-2 스케줄러 이식, 도메인 서비스)
└── backfill/ # 간격 규칙 변경 시 기존 PENDING 일정 재계산 (기동 시 1회, 멱등)
자료는 책/강의/문제집/MOOC 등 학습의 단위.
- 노트와 1:N (트리): 자료 안에 노트를 Notion 스타일 트리로 자유롭게 추가. 자료 생성 시 노트는 0개 (빈 트리). 자료 삭제 시 전체 노트 cascade
- 카드와 1:N: 자료 안에 카드를 자유롭게 추가. 자료 삭제 시 카드도 cascade
자료에서 학습한 내용을 자유 형식으로 정리. 본문을 쓰다가 그 자리에서 하위 노트를 만들어 본문에 인라인으로 박는 Notion 방식. 노트는 무제한 중첩된다.
-
트리 구조:
parent_idself-reference가 트리 관계의 진실(source of truth). 루트 노트(parent_id=NULL)는 자료 직속 -
본문 내 인라인 하위 페이지: 본문
content(Tiptap JSON) 안에childPage커스텀 노드가 박힌다. 이 노드는 자식 노트의noteId를 참조한다 - 즉 한 노트는 두 모습으로 존재: ① 부모 본문 안의
childPage블록 ② 자기만의title+content+ 자식들 -
제목 + 본문:
title(블록 라벨 + 사이드바 표시) +content(Tiptap JSON, childPage 노드 포함) -
생성 흐름: 본문에서
/페이지→ 자식note생성(parentId= 현재 노트) → 응답의noteId를childPage블록 attrs에 기록 → 본문 계속 작성 -
진입:
childPage블록 클릭 → 자식 노트로 라우팅 -
자동 저장: 본문 입력 → FE 2초 debounce →
PATCH /notes/{noteId} { content }(childPage 노드 포함한 JSON 그대로 저장) -
삭제: 본문에서
childPage블록 삭제 → 자식 노트 삭제(DELETE /notes/{id}, 서브트리 cascade). 확인 다이얼로그 -
사이드바 트리:
parent_id로 구성한 네비게이션 뷰 (생성은 본문/페이지로, 사이드바는 루트 노트 [+]만) - 1차 제외: 트리 이동(부모 변경), childPage 블록 복붙(noteId 중복 방지 위해 복제 차단) — 차기
- 노트와 카드는 분리 — 인라인 카드 블록은 별개 차기 작업
자료 안에서 사용자가 직접 만든 복습 카드.
- 앞면/뒷면 plain text (각 1000자)
- 생성 시점에 첫
review_schedule1건 자동 생성 (sequence=1, scheduled_at=today+1, ease=2.50) - 노트와 분리 — 노트 ↔ 카드 매핑은 사용자가 수동으로 (현재 v2 범위)
카드별 SM-2 상태 + 회차별 기록.
- 카드와 1:N. 카드 하나당 PENDING 1건 + COMPLETED N건 누적
- 회차(sequence)별로 timestamp/rating/interval 보존 (FSRS 마이그레이션용)
POST /api/planner/materials/{materialId}/flashcards
│
▼
flashcard 1건 생성 (front, back)
│
▼
첫 review_schedule 자동 생성:
- flashcard_id = card.id
- sequence = 1
- scheduled_at = (today+1) 04:00
- interval_days = 1
- ease_factor = 2.50
- status = PENDING
입력 평가 → SM-2 q-score 매핑:
| 평가 | q | 의미 |
|---|---|---|
| AGAIN | 0 | 다시 (실패) |
| HARD | 3 | 어려움 |
| GOOD | 4 | 보통 (정답) |
| EASY | 5 | 쉬움 |
다음 간격 계산:
if q < 3 (AGAIN):
next_interval = 1
new_ease = max(prev_ease - 0.20, 1.30)
else:
if sequence == 1: next_interval = 1
elif sequence == 2: next_interval = 6
else: next_interval = round(prev_interval * prev_ease)
new_ease = prev_ease + (0.1 - (5 - q) * (0.08 + (5 - q) * 0.02))
new_ease = max(new_ease, 1.30)
첫 회차 next_interval = 1, 둘째 회차 = 6은 SM-2 원본 정의를 따른다.
POST /api/planner/reviews/{id}/complete body: { rating }
│
▼
현재 review_schedule 업데이트:
- status = COMPLETED
- rating = AGAIN | HARD | GOOD | EASY
- completed_at = now()
- elapsed_days = today - DATE(scheduled_at) (FSRS 트레이닝용)
│
▼
SM-2로 다음 interval, ease 계산
│
▼
새 review_schedule 생성:
- flashcard_id = 기존과 동일
- sequence = prev_sequence + 1
- scheduled_at = computeScheduledAt(rating, next_interval, now)
AGAIN → now + 10분 (분 단위 당일 재복습)
HARD/GOOD/EASY → (학습일(now) + next_interval) 04:00 (일 단위, 롤오버)
- interval_days = next_interval
- ease_factor = new_ease
- status = PENDING
놓친 복습이 뒤늦게 완료되어도 다음 복습이 과거에 잡히지 않도록 학습일/now 기준으로 계산. 다중일 due는 복습 시각과 무관하게 해당 날짜 04:00(Anki "next day starts at" = 4AM과 동일).
due 시각이 04:00 롤오버인데 "지금이 며칠인가"만 자정 기준이면 두 경계가 어긋난다. 새벽 1시에 공부한 게 다음 날 몫이 되어 첫 복습이 하루 밀리고, 실제로는 30시간 넘게 지나서야 다시 보게 된다.
그래서 모든 "오늘" 판정을 학습일로 통일했다. 타임스탬프 T의 학습일은 (T − 4h)의 날짜다.
| 학습일 | |
|---|---|
| 6/10 00:00 ~ 03:59 | 6/9 (아직 어젯밤) |
| 6/10 04:00 ~ 23:59 | 6/10 |
- 단일 출처는
orino-common의StudyDay— BE 전체(복습·카드)가 이걸 쓴다. FE도 같은 규칙(features/review/studyDay.ts)으로 오늘/어제/내일 라벨과 캘린더 분류를 맞춘다 - 적용 지점: 다음 복습 날짜, 첫 복습 날짜, 밀린 일수(
elapsed_days), 짝 카드 미루기, 오늘 복습·허브 현황, 오늘 완료 수·밀림 경계, 카드 목록의 복습 창(overdue/today/upcoming) -
날짜 매핑은 그대로 — 04:00 정각인 기존
scheduled_at은 경계를 바꿔도 같은 날짜로 매핑된다(D 04:00 − 4h = D 00:00→ D) - 다만 옛 규칙이 이미 하루 늦게 잡아둔 일정은 백필로 당긴다(
ReviewScheduleBackfillService) — 자정~04:00에 만든 카드의 첫 복습과, 그 시간대에 채점해서 생긴 다음 일정이 대상이다
별도 OVERDUE 상태를 두지 않는다. scheduled_at <= now AND status = PENDING 을 동적으로 "오늘 할 복습"으로 표시.
- 오늘 복습 화면 = 위 조건의 모든 review_schedule (지연 일수 라벨 표시)
- 뒤늦게 완료해도 정상 흐름과 동일하게 처리
v2 데이터 모델은 향후 FSRS로 마이그레이션할 때 그대로 사용 가능하도록 설계.
| 필드 | 용도 |
|---|---|
rating (AGAIN/HARD/GOOD/EASY) |
FSRS 4단계 평가와 동일 |
interval_days |
회차별 간격 기록 |
ease_factor |
SM-2 시절 기록 (FSRS에서는 미사용이나 보존) |
elapsed_days |
scheduled_at 대비 실제 경과일 (FSRS 트레이닝 입력) |
scheduled_at, completed_at
|
회차별 timestamp |
마이그레이션 트리거: 누적 리뷰 1,000건 이상.
폴더 구조는 FE 코드 아키텍처를 따른다. v2 feature 모듈:
features/
├── material/ # 학습 자료 CRUD (목록, 상세)
├── note/ # 노트 트리 사이드바 + Tiptap 에디터 + 자동 저장 훅
├── flashcard/ # 카드 목록 + 추가/편집 다이얼로그
├── review/ # 오늘 복습 (앞면 → 답 공개 → 4지선다)
└── calendar/ # 복습 캘린더 (월간 그리드 + 날짜 상세 패널)
Tiptap childPage 커스텀 노드 (핵심)
- atom(또는 leaf) 노드. attrs:
{ noteId, title }(title은 표시용 캐시, 진실은 note 레코드) - NodeView로 렌더: 📄 아이콘 + 제목 라벨, 클릭 시 자식 노트로 라우팅
-
/페이지슬래시 커맨드(또는 툴바 버튼)로 삽입:-
POST /materials/{id}/notes { parentId: 현재노트, title: "제목 없음" }→noteId수신 -
editor.commands.insertChildPage({ noteId, title })→ 본문에 블록 삽입 - 본문 변경 → 자동 저장(아래)으로 content에 영속
-
- 블록 삭제 감지: 에디터에서 childPage 노드가 사라지면 해당
noteId로DELETE /notes/{noteId}(확인 후). 트랜잭션 비교(이전 content의 childPage noteId 집합 − 현재 집합)로 삭제분 검출 - 복붙 차단: childPage 노드는 복제 시 같은 noteId 중복 → 1차는 paste/duplicate에서 제거하거나 무시 (차기에 "복제 시 새 노트 생성")
Tiptap 에디터 (본문)
- 패키지:
@tiptap/react,@tiptap/starter-kit,@tiptap/extension-task-list,@tiptap/extension-task-item,@tiptap/extension-placeholder+ 자체ChildPage노드 - 시작 익스텐션: heading, paragraph, bullet/ordered list, blockquote, code, codeBlock, horizontalRule, task-list, childPage
- 저장 형식:
editor.getJSON()(childPage 노드 포함)을PATCH /notes/{id} { content }로 전송 - 노트 전환 시 content 교체 (
editor.commands.setContent) - 자동 저장:
useDebouncedCallback2초 debounce 후 PATCH - 제목: 에디터 상단 별도 입력(title). 변경 시
PATCH /notes/{id} { title }→ ① 사이드바 라벨 ② 부모 본문의 childPage 블록 라벨 갱신 - 저장 상태 표시: 우상단
저장됨 · 12:34/저장 중.../저장 실패 (재시도)
사이드바 트리 (네비게이션 뷰)
-
GET /materials/{id}/notes로 트리 로드 (parent_id기준 구성) - 중첩 렌더링: 펼침/접힘, 들여쓰기. 노트 클릭 → 해당 노트로 진입
- 생성은 본문
/페이지로. 사이드바는 루트 노트 [+ 새 노트] 만 제공 - 본문에서 childPage 추가/삭제/제목변경 시 트리도 갱신 (note 트리 invalidate)
자료 상세 [노트 탭]
1. GET /api/planner/materials/{id}/notes → 사이드바 트리 (parent_id 기준)
2. 활성 노트 GET /notes/{noteId} → 본문 Tiptap 로드 (childPage 노드 포함)
3. 본문 입력 → 2초 debounce → PATCH /notes/{noteId} { content }
4. 본문에서 /페이지 → POST /materials/{id}/notes { parentId } → childPage 블록 삽입
5. childPage 블록 클릭 → 자식 노트로 진입 (2번부터 반복)
6. childPage 블록 삭제 → 확인 → DELETE /notes/{childId} (서브트리)
7. 제목 입력 → PATCH /notes/{noteId} { title } → 트리 + 부모 블록 라벨 갱신
8. 사이드바 [+ 새 노트] → POST /materials/{id}/notes { parentId: null }
자료 상세 [카드 탭]
1. GET /api/planner/materials/{id}/flashcards
2. 카드 목록 렌더링 (앞/뒤 + 다음 복습일)
3. [+ 카드 추가] → 다이얼로그 → POST → 카드 + 첫 review 응답
4. 카드 [편집] → 다이얼로그 → PATCH
5. 카드 [삭제] → 확인 → DELETE (cascade)
오늘 복습
1. GET /api/planner/reviews/today
2. 카드 1장씩 표시 (앞면 + 답 적는 칸)
3. 답을 적는다 (화면 전용 — 서버로 보내지 않는다)
4. [답 보기] or ⌘/Ctrl+Enter → 뒷면 공개(내 답과 나란히) + 4지선다 버튼 활성화
5. [Again/Hard/Good/Easy] or 1/2/3/4 → POST /reviews/{id}/complete { rating }
6. 응답 → 토스트 + 다음 카드로 (적은 답은 여기서 사라진다)
복습 캘린더
1. GET /api/planner/reviews/calendar?from=<그리드 첫날>&to=<그리드 마지막날>
2. FE에서 날짜별 그룹핑 + 상태 분류(밀림/오늘/예정/완료, today 기준)
3. 월간 그리드 렌더링 (각 칸에 상태별 색 점/막대)
4. 날짜 클릭 → 하단/우측 패널에 그날 복습 목록 (상태별 그룹)
5. [오늘 복습 하러가기] → /planner/reviews/today
6. 이전/다음 달 → 새 범위로 1번 재호출
각 페이지에서 데이터가 없을 때 빈 상태 메시지만 표시 (온보딩 가이드 없음).
Client Backend
│ │
│ POST /api/planner/materials │
│ { title, type } │
│──────────────────────────────▶│
│ │ study_material 생성
│ │ (노트 자동 생성 없음)
│ │
│ { material } │
│◀──────────────────────────────│
Client Backend
│ (입력 이벤트, 2초 debounce) │
│ │
│ PATCH /api/planner/notes │
│ /{noteId} │
│ { content: TiptapJSON } │
│──────────────────────────────▶│
│ │ note 업데이트 (idempotent)
│ │
│ { updatedAt } │
│◀──────────────────────────────│
│ UI: "저장됨 · 12:34" │
Client Backend
│ │
│ POST /api/planner/materials │
│ /{materialId}/flashcards │
│ { front, back } │
│──────────────────────────────▶│
│ │ flashcard 생성
│ │ 첫 review_schedule 생성
│ │ (sequence=1, interval=1, ease=2.50)
│ │
│ { flashcard, firstReview } │
│◀──────────────────────────────│
Client Backend
│ │
│ POST /api/planner/reviews │
│ /{id}/complete │
│ { rating: "GOOD" } │
│──────────────────────────────▶│
│ │ 현재 review COMPLETED
│ │ SM-2로 다음 interval/ease 계산
│ │ 다음 review 생성
│ │
│ { completed, nextReview } │
│◀──────────────────────────────│
| 결정 | 선택 | 이유 |
|---|---|---|
| 복습 알고리즘 | SM-2 (Anki 4단계) | 검증된 표준, FSRS와 입력 포맷 동일 |
| 카드 단위 | 자료별 카드 (덱/태그 없음) | v2 단순화. 자료가 곧 덱 |
| 노트 ↔ 카드 | 분리 (동일 자료 안에서만 그룹화) | 구현 단순. 인라인 카드 블록은 차기 |
| 노트 에디터 | Tiptap (블록 에디터) | React 친화 OSS. JSON 저장, 확장 용이 |
| 노트 저장 형식 | JSON (Tiptap content) | 구조화된 블록. 향후 검색/변환 용이 |
| 노트 ↔ 자료 | 1:N 트리 (parent_id self-ref) | Notion 스타일 중첩. 자료당 노트 여러 개 + 무제한 중첩 |
| 노트 하위 생성 방식 | 본문 /페이지 인라인 (Notion 방식) |
글 쓰다가 그 자리에서 하위 노트 생성 + 본문에 childPage 블록. 사이드바 버튼 X |
| childPage 블록 | Tiptap 커스텀 노드 (attrs: noteId, title) | 본문 안에 자식 노트 참조. 클릭 시 진입 |
| 본문 ↔ 노트 동기화 | 블록 삽입=note 생성, 블록 삭제=note 삭제 | content 변경분 비교(childPage noteId diff)로 검출 |
| 트리 진실(source) |
parent_id (DB). 본문 블록은 인라인 진입점 |
사이드바 트리는 parent_id로 구성 |
| 노트 트리 깊이 | 무제한 | parent_id self-reference. 단일 사용자라 깊이 폭주 우려 낮음 |
| 자료 생성 시 노트 | 자동 생성 안 함 (빈 트리) | 빈 상태에서 사용자가 [+ 새 노트] 또는 본문 작성 시작 |
| childPage 복붙/이동 | 1차 미지원 (복제 차단, 부모변경 제외) | noteId 중복·본문↔트리 동기화 복잡. 차기 |
| 노트 저장 방식 | PATCH content idempotent + 2초 debounce | 자동 저장. 충돌 가능성 낮음 (단일 유저) |
| 첫 복습 생성 시점 | 카드 생성 시 자동 1건 | SM-2는 평가 결과로 다음 간격 결정 → 미리 여러 개 못 생성 |
| OVERDUE 상태 | 별도 컬럼 없이 동적 판단 | scheduled_at <= now AND status=PENDING |
| 놓침 정책 | 단순 누적 표시 (지연 라벨) | 즉시보충/리셋/스킵 분기 제거. 완료 시 다음 복습은 today 기준 |
| 배치 서비스 | 도입 안 함 | 평가 시점 동기 계산으로 충분 |
| Redis 용도 | 인증 토큰만 | 단일 사용자, 캐싱 불필요 |
| member_id | 전 테이블에 포함 | 멀티유저 확장 대비 |
- 차기: 카테고리, 목표 도입
- 노트 강화: 즐겨찾기/아이콘/커버, 노트 검색, 노트 ↔ 카드 인라인 연결 (Tiptap 커스텀 노드)
- 그 후: 태그/덱, 카드 일괄 입력(CSV/Anki 임포트), 카드 멀티미디어
- 장기: 자동 스케줄링, 캘린더, 고정 일정/루틴/할일, 배치 서비스 부활
- v∞: FSRS 마이그레이션 (누적 리뷰 1,000건 시점)