Skip to content

Study Planner Data Model

wcorn edited this page Jul 11, 2026 · 11 revisions

데이터 모델링: Study Planner (v2.5)

범위: 4개 테이블 (study_material, note, flashcard, review_schedule). 카테고리, 목표, 단원(study_unit) 등은 범위 외. v2.1: 노트를 Notion 스타일 트리(nested)로 확장. v2.2: 트리를 인라인 하위 페이지 방식으로 구현 (테이블 스키마 변경 없음, content 안 childPage 노드 추가). v2.3: 플래시카드에 카드 종류(type)를 도입 — 기존 앞/뒷면 카드(BASIC)에 더해 순서 카드(ORDERING) 신설. flashcard에 type/items(JSON) 추가, back NULL 허용. review_schedule(SM-2)은 flashcard_id만 참조하므로 복습 사이클은 카드 종류와 무관하게 그대로 재사용(변경 없음). v2.4: 양방향 카드(짝 카드) 도입 — 카드 추가 시 "양방향" 옵션을 켜면 (front→back)·(back→front) 독립 카드 2개가 서로 다른 주기로 생성된다. flashcard에 sibling_group_id(짝 공유 키) 추가. 스케줄러에 sibling burying(짝은 같은 날 안 나오게 다른 날로 분산 — 리스케줄형)을 넣어 양방향의 장점은 살리고 되뱉기(regurgitation) 문제를 없앤다. v2.5: 복습 허브("오늘 복습" → "복습") — 현황 집계 + 앞으로·완료 목록 조회를 위한 조회 API만 추가하고 복습 로직·평가는 그대로 둔다. 테이블/컬럼 변경 없음. 완료 목록을 completed_at 내림차순으로 커서 페이지네이션하기 위한 인덱스 (member_id, status, completed_at)만 추가한다(인덱스 전용 마이그레이션). 상세 결정은 Open Items §0-D.

1. ERD

┌────────┐        ┌─────────────────┐        ┌──────────────┐        ┌──────────────────┐
│ member │──1:N──▶│  study_material │──1:N──▶│  flashcard   │──1:N──▶│ review_schedule  │
└────────┘        └─────────────────┘        └──────────────┘        └──────────────────┘
                          │
                          └──1:N──▶┌────────┐
                                   │  note  │──┐
                                   └────────┘  │ self-ref (parent_id)
                                       ▲────────┘ 무제한 중첩

note는 자료에 1:N으로 속하며, 동시에 parent_id로 자기 자신을 참조하는 트리 구조다 (Notion 스타일). 루트 노트(parent_id = NULL)는 자료 직속이고, 그 아래로 무제한 중첩된다.

모든 테이블에 member_id FK가 포함된다 (멀티유저 확장 대비). note, flashcard, review_schedule은 부모를 통해 멤버를 추적하지만, 조회 성능을 위해 비정규화된 member_id 컬럼도 유지한다.

2. 테이블 정의

2.1 study_material

학습 자료 (책, 강의, 문제집 등). 노트 1개와 카드 N개를 묶는 그릇.

컬럼 타입 제약조건 설명
id BIGINT PK, AUTO_INCREMENT 기본키
member_id BIGINT FK → member, NOT NULL 소유자
title VARCHAR(200) NOT NULL 자료 제목
type VARCHAR(10) NOT NULL BOOK / LECTURE / WORKBOOK / MOOC
status VARCHAR(10) NOT NULL, DEFAULT 'ACTIVE' ACTIVE / COMPLETED
created_at DATETIME NOT NULL 생성일시
updated_at DATETIME NOT NULL 수정일시
  • 인덱스: (member_id, status) — 자료 목록 조회

v1의 description VARCHAR(500)은 노트로 대체되어 제거된다.

2.2 note

자료에 속한 학습 노트. Notion 스타일 트리(nested) 구조. 자료당 노트 N개, 노트는 다시 하위 노트를 무제한 가질 수 있다. Tiptap 블록 에디터의 JSON content를 저장.

v2.2 인라인 하위 페이지: 하위 노트는 본문에서 /페이지로 만든다. 부모 노트의 content(Tiptap JSON) 안에 자식의 noteId를 참조하는 childPage 노드가 박힌다. 단, 트리 관계의 진실은 parent_id 컬럼이고, 본문의 childPage 블록은 "본문 내 인라인 진입점"일 뿐이다. 테이블 스키마는 v2.1과 동일 (컬럼 변경 없음).

컬럼 타입 제약조건 설명
id BIGINT PK, AUTO_INCREMENT 기본키
member_id BIGINT FK → member, NOT NULL 소유자 (비정규화)
material_id BIGINT FK → study_material, NOT NULL, ON DELETE CASCADE 소속 자료
parent_id BIGINT FK → note(self), NULL, ON DELETE CASCADE 부모 노트. NULL이면 자료 직속(루트 레벨)
title VARCHAR(200) NOT NULL, DEFAULT '제목 없음' 트리에 표시할 노트 제목
content JSON NOT NULL Tiptap JSON content. 기본값 빈 doc {"type":"doc","content":[]}
sort_order INT NOT NULL, DEFAULT 0 같은 부모 안에서의 표시 순서
created_at DATETIME NOT NULL 생성일시
updated_at DATETIME NOT NULL 마지막 자동 저장 시각
  • 트리 구조: parent_id self-reference. NULL = 루트 노트(자료 직속), 값이 있으면 해당 노트의 자식. 깊이 무제한
  • 인덱스: (material_id, parent_id, sort_order) — 트리 조회 (부모별 자식 정렬)
  • ON DELETE CASCADE (parent_id): 부모 노트 삭제 시 자손 노트 전부 삭제 (서브트리 삭제)
  • ON DELETE CASCADE (material_id): 자료 삭제 시 전체 노트 삭제
  • 저장 형식: MySQL JSON 타입 사용 → Spring JsonNode / String으로 다루기 용이
  • title은 트리 사이드바 표시용. 빈 노트는 "제목 없음"으로 표시

v2 → v2.1 변경: 기존 material_id UNIQUE(1자료=1노트)를 제거하고 parent_id/title/sort_order를 추가하여 트리화. 자료 생성 시 자동 노트 생성은 더 이상 하지 않는다 (빈 트리로 시작).

2.3 flashcard

플래시카드. v2.3부터 카드 종류(type)를 가진다 — BASIC(앞/뒷면) / ORDERING(순서 카드).

컬럼 타입 제약조건 설명
id BIGINT PK, AUTO_INCREMENT 기본키
member_id BIGINT FK → member, NOT NULL 소유자 (비정규화)
material_id BIGINT FK → study_material, NOT NULL, ON DELETE CASCADE 소속 자료
type VARCHAR(10) NOT NULL, DEFAULT 'BASIC' (v2.3 신규) BASIC / ORDERING
front VARCHAR(1000) NOT NULL 카드 앞면. BASIC=질문, ORDERING=지시문(prompt). 줄바꿈 허용
back VARCHAR(1000) NULL 카드 뒷면(답). BASIC만 사용. ORDERING은 NULL. (v2.3: NOT NULL → NULL 완화)
items JSON NULL (v2.3 신규) ORDERING 항목 배열. 항상 정답 순서로 저장(index 0 = 1단계). BASIC은 NULL
sibling_group_id BIGINT NULL (v2.4 신규) 양방향 짝이 공유하는 그룹 키. 단독 카드는 NULL. 짝의 두 카드는 같은 값
created_at DATETIME NOT NULL 생성일시
updated_at DATETIME NOT NULL 수정일시
  • 인덱스: (material_id, id) — 카드 목록 조회 (생성순, 안정 정렬)
  • 인덱스: (sibling_group_id) — (v2.4) 짝 카드 조회 (burying 시 형제 탐색)
  • v2에는 sort_order, tag, deck, cloze 등 도입하지 않음

양방향 짝 카드 (sibling_group_id, v2.4)

  • BASIC 카드만 대상. ORDERING은 역방향 개념이 없어 제외.
  • 카드 추가 시 "양방향" 옵션을 켜면 두 행을 만든다: A(front→back), B(back→front). 둘은 같은 sibling_group_id를 갖는다(값은 첫 카드 id 등 짝 내 공유되는 임의 키).
  • 생성 후 두 카드는 완전히 독립 — 편집/삭제/복습 사이클이 서로 무관하다(편집 동기화 없음). sibling_group_id는 오직 burying(형제 분산) 용도로만 쓰인다.
  • 한쪽을 삭제하면 다른 쪽은 단독 카드로 남는다(sibling_group_id는 그대로 둬도 무방 — 형제가 없으면 burying이 발동하지 않음).

items JSON 형식 (ORDERING 전용)

[
  { "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 파드 생성" }
]
  • 배열 순서 = 정답 순서. 정답을 별도 필드로 저장하지 않는다 — 순서 자체에 정답이 인코딩됨. 화면에 보여줄 때만 셔플한다.
  • 각 항목은 { id, text }. id는 드래그 재정렬 시 각 항목을 추적할 안정 키(문자열, 카드 내 유일). text를 키로 쓰면 중복·재배열 시 꼬이므로 반드시 별도 id를 둔다.
  • id 생성 주체는 FE — 항목 생성 시 FE가 부여(예: nanoid). BE는 저장 시 구조/유일성만 검증한다.
  • 저장 형식: MySQL JSON 타입 (note.content와 동일 패턴 — @Column(columnDefinition = "JSON") String).
  • 제약(서버 검증, 위반 시 400 SP-ERR-002):
    • type = ORDERING: items 3~7개, 각 text 1~1000자, id 카드 내 유일, back은 무시(NULL 저장)
    • type = BASIC: back 필수(1~1000자), items는 무시(NULL 저장)

2.4 review_schedule

카드별 복습 일정. SM-2 알고리즘으로 1건씩 순차 생성.

컬럼 타입 제약조건 설명
id BIGINT PK, AUTO_INCREMENT 기본키
member_id BIGINT FK → member, NOT NULL 소유자 (비정규화)
flashcard_id BIGINT FK → flashcard, NOT NULL, ON DELETE CASCADE 학습 카드
sequence INT NOT NULL 회차 (1, 2, 3, ...)
scheduled_at DATETIME(6) NOT NULL 예정 일시. due = scheduled_at <= now
interval_days INT NOT NULL 이번 회차의 간격 (일). 당일 재복습(AGAIN)도 SM-2 base 유지를 위해 1로 기록
ease_factor DECIMAL(4,2) NOT NULL, DEFAULT 2.50 E-Factor (SM-2). 최소 1.30
status VARCHAR(10) NOT NULL, DEFAULT 'PENDING' PENDING / COMPLETED
rating VARCHAR(10) NULL 평가 (AGAIN/HARD/GOOD/EASY). 완료 시 기록
elapsed_days INT NULL 실제 경과 일수 = completed - scheduled (FSRS 트레이닝용)
completed_at DATETIME NULL 완료 일시
created_at DATETIME NOT NULL 생성일시
updated_at DATETIME NOT NULL 수정일시
  • 인덱스: (member_id, scheduled_at, status) — 오늘 복습 / 앞으로 목록 조회 (scheduled_at <= now AND PENDING, 그리고 전 PENDING을 scheduled_at 순으로 커서 페이징)
  • 인덱스: (flashcard_id, sequence) — 카드별 복습 이력
  • 인덱스 (member_id, status, completed_at) — (v2.5) 완료 목록을 completed_at DESC로 커서 페이지네이션 (Open Items §0D.5)
  • 캘린더/오늘 목록은 DATE(scheduled_at) 기준으로 날짜 그룹핑한다 (화면은 날짜 단위 유지)

3. 상태 전이

3.1 study_material.status

ACTIVE ──→ COMPLETED  (사용자가 수동으로 변경)

v2에서도 자동 전이는 두지 않는다. 사용자가 명시적으로 완료/보관 버튼을 누를 때만.

3.2 note (트리 연산)

  • 생성: parent_id(없으면 루트), title, 빈 content. sort_order는 같은 부모 내 max+1
  • 이동: parent_id 변경 (다른 노트의 자식으로). 자기 자신/자손을 부모로 지정 불가 (사이클 방지 — 서버 검증)
  • 정렬: 같은 부모 안에서 sort_order 재배치
  • 삭제: 서브트리 cascade (자손 노트 전부 삭제). 삭제 전 클라이언트에서 "하위 노트 N개도 함께 삭제" 확인
  • 자료 생성 시 노트 자동 생성 안 함 → 빈 트리로 시작

3.3 flashcard

  • 생성 시 첫 review_schedule 1건 자동 생성 (sequence=1, interval=1, ease=2.50, scheduled_at=(today+1) 04:00, status=PENDING)
  • 카드 자체에는 상태 없음 (PENDING/COMPLETED는 review_schedule에 있음)

3.4 review_schedule.status

PENDING ──→ COMPLETED  (사용자 평가 시)
  • COMPLETED 시 SM-2 계산으로 다음 회차 review_schedule 1건 생성

4. SM-2 파라미터 + datetime 하이브리드 스케줄링

간격 계산은 SM-2(일 단위), due 시각 산정은 Anki식 하이브리드를 따른다.

파라미터 값 설명
초기 ease_factor 2.50 신규 카드의 첫 복습
최소 ease_factor 1.30 SM-2 표준 하한
1차 복습 interval 1일 sequence=1
2차 복습 interval 6일 sequence=2, q ≥ 3
이후 interval round(prev_interval × ease) sequence ≥ 3, q ≥ 3
AGAIN 시 interval 1일 q < 3 (다음 성공의 base 유지용. 실제 due는 분 단위)
AGAIN 시 ease 변화 -0.20 최소 1.30으로 클램프
롤오버 시각 04:00 다중일 복습 due 시각. scheduled_at = (today+interval) 04:00 → 그 날 하루 종일 due
AGAIN 재복습 now + 10분 틀림 시 당일 분 단위 재복습 (Anki learning step)

due 시각 산정 (ReviewSchedule.computeScheduledAt)

AGAIN              → scheduled_at = now + 10분        (분 단위, 당일 재복습)
HARD/GOOD/EASY     → scheduled_at = (today + interval_days) 04:00   (일 단위, 롤오버)
  • 복습한 시각과 무관하게 다중일 due는 항상 해당 날짜 04:00 (Anki의 "next day starts at" = 4AM과 동일). "오후 1시에 했으면 6일 후 오후 1시"가 아니라 6일 후 날짜의 04:00.
  • 시각 정밀도가 의미 있는 곳은 당일 짧은 재복습(AGAIN)뿐이라 거기에만 분 단위를 적용한다.

4.6 Sibling Burying (양방향 짝 분산, v2.4)

짝 카드(같은 sibling_group_id)가 같은 날 함께 나오지 않도록 스케줄러가 분산한다. 목적: 양방향 학습의 장점(양쪽 다 연습)은 살리고, "방금 본 답을 곧바로 되뱉는" 문제를 없앤다.

두 지점에서 발동한다 (리스케줄형 — scheduled_at을 실제로 이동):

  1. 생성 시 첫 복습 엇갈림

    • A(front→back) 첫 복습 = (today+1) 04:00 (기존 규칙)
    • B(back→front) 첫 복습 = (today+2) 04:00 (+1일 추가 오프셋)
    • interval_days는 둘 다 SM-2 base(1)로 기록. scheduled_at만 하루 밀어 분리한다.
  2. 복습 완료 시 형제 bury

    • 카드 A의 복습을 완료(POST /reviews/{id}/complete)할 때, 현재 due 상태(scheduled_at <= now AND PENDING)인 형제의 review를 찾아 scheduled_at을 다음날 04:00으로 민다.
    • 즉 "오늘 A를 했으면, 오늘 같이 due이던 B는 내일로." 완료 응답에 밀린 형제 review id(buriedReviewIds)를 실어 FE가 현재 세션 큐에서 즉시 제거한다.
    • SM-2 간격은 건드리지 않는다 — due 날짜만 하루 지연. 형제 자신이 실제 평가될 때 SM-2가 정상 계산된다.

왜 리스케줄형인가: orino의 오늘 복습·캘린더·due 카운트는 전부 scheduled_at 단일 진실 위에 있다. 숨김필터형(scheduled_at은 그대로 두고 오늘 큐에서만 숨김)은 "캘린더엔 오늘인데 큐엔 없음" 불일치를 낳는다. 리스케줄형은 scheduled_at을 실제로 옮겨 모든 화면이 일관된다.

한계(의도된 단순화): 미래 시점의 충돌을 선제적으로 피하지는 않는다(형제의 다음 회차가 우연히 같은 날 잡히는 경우). 그 날이 오면 "완료 시 bury"가 런타임에 다시 분산하므로 장기적으로도 겹치지 않는다. Anki의 bury와 동일한 접근.

5. v2에서 도입하지 않은 항목

다음 항목은 테이블/컬럼 수준에서 도입하지 않는다. 차기 이후 도입 시 마이그레이션으로 추가:

  • 학습 단위(study_unit) — v1에 있었으나 v2에서 폐기. 카드가 학습 단위
  • 카테고리 (category)
  • 목표/마일스톤 (goal, milestone)
  • 카드 태그, 덱, sort_order
  • 카드 멀티미디어 (이미지/오디오)
  • 카드 클로즈(빈칸) 타입
  • 노트 ↔ 카드 인라인 연결 (Tiptap 커스텀 노드) — 노트와 카드는 여전히 분리
  • 노트 즐겨찾기/아이콘/커버 (Notion 메타) — 트리 + 제목만
  • 고정 일정 (fixed_schedule)
  • 루틴 (routine, routine_check, routine_exception)
  • 할 일 (todo)
  • 자료 추가 정보: category_id, goal_id, deadline, deadline_mode
  • 사용자 선호 (user_preference, priority_rule)
  • 일간 스케줄 (daily_schedule, schedule_block)
  • 시간 할당 (material_allocation, material_daily_override)
  • 복습 설정 오버라이드 (review_config)
  • 동기부여 (streak, daily_reflection)
  • 분산 락 (shedlock) — 배치 서비스 없음

6. 마이그레이션 전략

DB 마이그레이션 가이드에 따라 Liquibase changeset으로 관리한다.

6.1 v1 → v2 (완료됨)

  1. v1 changeset의 study_unit, review_schedule(v1) drop
  2. study_material에서 v1 description 컬럼 drop
  3. v2 신규 changeset으로 note(1:1), flashcard, review_schedule(flashcard_id 기반) 생성
  4. 001-create-member(인증 모듈)는 유지

6.2 v2 → v2.1 노트 트리화 (신규)

note 테이블을 트리 구조로 확장하는 ALTER 마이그레이션:

  1. note에서 material_id UNIQUE 제약 제거 (1자료=1노트 해제)
  2. 컬럼 추가:
    • parent_id BIGINT NULL + FK self-ref(ON DELETE CASCADE)
    • title VARCHAR(200) NOT NULL DEFAULT '제목 없음'
    • sort_order INT NOT NULL DEFAULT 0
  3. 인덱스 추가: (material_id, parent_id, sort_order)
  4. 기존 노트(자료당 1개)는 parent_id = NULL(루트), title = '제목 없음', sort_order = 0으로 자연 유지 — 데이터 손실 없음

기존 데이터가 적고 구조가 단순해 ALTER로 무손실 전환 가능. drop 불필요.

향후 카테고리·목표·태그 등은 신규 마이그레이션으로 점진 도입.

6.3 v2.2 → v2.3 순서 카드 (신규)

flashcard에 카드 종류를 도입하는 ALTER 마이그레이션. 신규 changeset 033-add-flashcard-type-items.yaml (현재 마지막이 032-create-monthly-goal).

  1. 컬럼 추가:
    • type VARCHAR(10) NOT NULL DEFAULT 'BASIC'
    • items JSON NULL (columnDefinition = "JSON" — note.content 패턴)
  2. back 제약 완화: NOT NULL → NULL (ORDERING은 back 미사용)
  3. 기존 카드는 전부 type = 'BASIC'(DEFAULT), items = NULL, back 유지 — 데이터 손실 없음
  • back을 NULL 허용으로 바꾸면 기존 BASIC 카드는 값이 그대로라 영향 없다. BASIC의 back 필수는 애플리케이션 레이어(Bean Validation) 에서 강제한다(DB 컬럼은 NULL 허용).
  • review_schedule은 변경 없음 — flashcard_id만 참조하므로 순서 카드도 기존 첫 복습 자동 생성·SM-2 사이클을 그대로 탄다.
  • Liquibase 관례(columnExists/tableExists 가드, author wcorn)는 DB 마이그레이션을 따른다.

6.4 v2.3 → v2.4 양방향 짝 카드 (신규)

flashcard에 짝 그룹 키를 더하는 ALTER 마이그레이션. 신규 changeset 034-add-flashcard-sibling-group.yaml (v2.3의 033 다음).

  1. 컬럼 추가: sibling_group_id BIGINT NULL
  2. 인덱스 추가: (sibling_group_id) — burying 시 형제 탐색
  3. 기존 카드는 전부 sibling_group_id = NULL(단독) — 데이터 손실 없음
  • review_schedule은 변경 없음. burying은 기존 scheduled_at을 이동하는 것뿐이라 스키마 변경이 필요 없다.
  • sibling_group_id에 FK를 걸지 않는다(그룹 키일 뿐 특정 행을 가리키지 않음). 무결성은 애플리케이션에서 관리.

6.5 v2.4 → v2.5 복습 허브 (신규)

테이블/컬럼 변경 없음. 복습 허브는 전부 조회(집계·목록)라 스키마를 바꾸지 않는다. 완료 목록 커서 페이지네이션(completed_at DESC)만 인덱스가 필요하다. 신규 changeset 035-add-review-schedule-completed-index.yaml (v2.4의 034 다음):

  1. 인덱스 추가: (member_id, status, completed_at) — 완료 목록 조회 (status = COMPLETED AND member_id = ? → completed_at DESC keyset)
  • 요약 집계(지금/밀림/앞으로/오늘 완료)와 앞으로 목록은 기존 인덱스 (member_id, scheduled_at, status)로 커버된다.
  • 컬럼 추가/변경/삭제가 없어 데이터 손실·기존 기능 영향 없음. Liquibase 관례(indexExists 가드, author wcorn)는 DB 마이그레이션을 따른다.

Clone this wiki locally