Skip to content

Study Planner Architecture

wcorn edited this page Aug 2, 2026 · 16 revisions

시스템 아키텍처: Study Planner (v2.5)

범위: 학습 자료 + 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종) 추가이며 복습 로직·평가·스키마는 그대로.

0. v2.5 복습 허브 조회 흐름 (읽기 전용)

복습 허브는 새 동작을 만들지 않고 기존 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).

1. 전체 구조

┌──────────────────┐      ┌──────────────────────────────┐      ┌─────────┐
│    Frontend      │      │          Backend             │      │  MySQL  │
│  (React + Tiptap)│─────▶│       (Spring Boot API)       │─────▶│         │
│                  │◀─────│                              │◀─────│         │
└──────────────────┘      │  ┌────────────────────────┐  │      └─────────┘
                          │  │  ReviewSchedulerService │  │
                          │  │  (SM-2 알고리즘)         │  │      ┌─────────┐
                          │  └────────────────────────┘  │─────▶│  Redis   │
                          └──────────────────────────────┘      │ (인증만)  │
                                                                 └─────────┘

인증 모듈과 동일한 인프라(MySQL, Redis, K8s)를 공유한다.

배치 서비스 없음. SM-2는 평가 시점에 동기 계산.

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회, 멱등)

3. 도메인 모델

3.1 학습 자료 (study_material)

자료는 책/강의/문제집/MOOC 등 학습의 단위.

  • 노트와 1:N (트리): 자료 안에 노트를 Notion 스타일 트리로 자유롭게 추가. 자료 생성 시 노트는 0개 (빈 트리). 자료 삭제 시 전체 노트 cascade
  • 카드와 1:N: 자료 안에 카드를 자유롭게 추가. 자료 삭제 시 카드도 cascade

3.2 노트 (note) — Notion 스타일 인라인 하위 페이지

자료에서 학습한 내용을 자유 형식으로 정리. 본문을 쓰다가 그 자리에서 하위 노트를 만들어 본문에 인라인으로 박는 Notion 방식. 노트는 무제한 중첩된다.

  • 트리 구조: parent_id self-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 중복 방지 위해 복제 차단) — 차기
  • 노트와 카드는 분리 — 인라인 카드 블록은 별개 차기 작업

3.3 플래시카드 (flashcard)

자료 안에서 사용자가 직접 만든 복습 카드.

  • 앞면/뒷면 plain text (각 1000자)
  • 생성 시점에 첫 review_schedule 1건 자동 생성 (sequence=1, scheduled_at=today+1, ease=2.50)
  • 노트와 분리 — 노트 ↔ 카드 매핑은 사용자가 수동으로 (현재 v2 범위)

3.4 복습 일정 (review_schedule)

카드별 SM-2 상태 + 회차별 기록.

  • 카드와 1:N. 카드 하나당 PENDING 1건 + COMPLETED N건 누적
  • 회차(sequence)별로 timestamp/rating/interval 보존 (FSRS 마이그레이션용)

4. 복습 시스템 (SM-2)

4.1 카드 생성 → 첫 복습

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

4.2 SM-2 알고리즘

입력 평가 → 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 원본 정의를 따른다.

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

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과 동일).

학습일 (study day) — 하루의 경계는 04:00 (#1003)

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에 만든 카드의 첫 복습과, 그 시간대에 채점해서 생긴 다음 일정이 대상이다

4.4 놓친 복습 / due 판정

별도 OVERDUE 상태를 두지 않는다. scheduled_at <= now AND status = PENDING 을 동적으로 "오늘 할 복습"으로 표시.

  • 오늘 복습 화면 = 위 조건의 모든 review_schedule (지연 일수 라벨 표시)
  • 뒤늦게 완료해도 정상 흐름과 동일하게 처리

5. FSRS 마이그레이션 호환성 (v∞)

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건 이상.

6. 프론트엔드 구조

폴더 구조는 FE 코드 아키텍처를 따른다. v2 feature 모듈:

features/
├── material/    # 학습 자료 CRUD (목록, 상세)
├── note/        # 노트 트리 사이드바 + Tiptap 에디터 + 자동 저장 훅
├── flashcard/   # 카드 목록 + 추가/편집 다이얼로그
├── review/      # 오늘 복습 (앞면 → 답 공개 → 4지선다)
└── calendar/    # 복습 캘린더 (월간 그리드 + 날짜 상세 패널)

6.1 노트 인라인 하위 페이지 + Tiptap 통합

Tiptap childPage 커스텀 노드 (핵심)

  • atom(또는 leaf) 노드. attrs: { noteId, title } (title은 표시용 캐시, 진실은 note 레코드)
  • NodeView로 렌더: 📄 아이콘 + 제목 라벨, 클릭 시 자식 노트로 라우팅
  • /페이지 슬래시 커맨드(또는 툴바 버튼)로 삽입:
    1. POST /materials/{id}/notes { parentId: 현재노트, title: "제목 없음" } → noteId 수신
    2. editor.commands.insertChildPage({ noteId, title }) → 본문에 블록 삽입
    3. 본문 변경 → 자동 저장(아래)으로 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)
  • 자동 저장: useDebouncedCallback 2초 debounce 후 PATCH
  • 제목: 에디터 상단 별도 입력(title). 변경 시 PATCH /notes/{id} { title } → ① 사이드바 라벨 ② 부모 본문의 childPage 블록 라벨 갱신
  • 저장 상태 표시: 우상단 저장됨 · 12:34 / 저장 중... / 저장 실패 (재시도)

사이드바 트리 (네비게이션 뷰)

  • GET /materials/{id}/notes로 트리 로드 (parent_id 기준 구성)
  • 중첩 렌더링: 펼침/접힘, 들여쓰기. 노트 클릭 → 해당 노트로 진입
  • 생성은 본문 /페이지로. 사이드바는 루트 노트 [+ 새 노트] 만 제공
  • 본문에서 childPage 추가/삭제/제목변경 시 트리도 갱신 (note 트리 invalidate)

6.2 화면 렌더링 흐름

자료 상세 [노트 탭]

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번 재호출

6.3 빈 상태

각 페이지에서 데이터가 없을 때 빈 상태 메시지만 표시 (온보딩 가이드 없음).

7. 주요 API 흐름

7.1 자료 생성 (빈 트리)

Client                         Backend
  │                               │
  │  POST /api/planner/materials  │
  │  { title, type }              │
  │──────────────────────────────▶│
  │                               │  study_material 생성
  │                               │  (노트 자동 생성 없음)
  │                               │
  │  { material }                 │
  │◀──────────────────────────────│

7.2 노트 자동 저장

Client                         Backend
  │ (입력 이벤트, 2초 debounce)   │
  │                               │
  │  PATCH /api/planner/notes     │
  │  /{noteId}                    │
  │  { content: TiptapJSON }      │
  │──────────────────────────────▶│
  │                               │  note 업데이트 (idempotent)
  │                               │
  │  { updatedAt }                │
  │◀──────────────────────────────│
  │  UI: "저장됨 · 12:34"          │

7.3 카드 생성 → 첫 복습

Client                         Backend
  │                               │
  │  POST /api/planner/materials  │
  │  /{materialId}/flashcards     │
  │  { front, back }              │
  │──────────────────────────────▶│
  │                               │  flashcard 생성
  │                               │  첫 review_schedule 생성
  │                               │  (sequence=1, interval=1, ease=2.50)
  │                               │
  │  { flashcard, firstReview }   │
  │◀──────────────────────────────│

7.4 복습 평가

Client                         Backend
  │                               │
  │  POST /api/planner/reviews    │
  │  /{id}/complete                │
  │  { rating: "GOOD" }           │
  │──────────────────────────────▶│
  │                               │  현재 review COMPLETED
  │                               │  SM-2로 다음 interval/ease 계산
  │                               │  다음 review 생성
  │                               │
  │  { completed, nextReview }    │
  │◀──────────────────────────────│

8. 기술 결정사항

결정 선택 이유
복습 알고리즘 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 전 테이블에 포함 멀티유저 확장 대비

9. 향후 확장

  • 차기: 카테고리, 목표 도입
  • 노트 강화: 즐겨찾기/아이콘/커버, 노트 검색, 노트 ↔ 카드 인라인 연결 (Tiptap 커스텀 노드)
  • 그 후: 태그/덱, 카드 일괄 입력(CSV/Anki 임포트), 카드 멀티미디어
  • 장기: 자동 스케줄링, 캘린더, 고정 일정/루틴/할일, 배치 서비스 부활
  • v∞: FSRS 마이그레이션 (누적 리뷰 1,000건 시점)

Clone this wiki locally