Repository navigation
Study Planner Data Model
범위: 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) 추가,backNULL 허용.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.
┌────────┐ ┌─────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ 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 컬럼도 유지한다.
학습 자료 (책, 강의, 문제집 등). 노트 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)은 노트로 대체되어 제거된다.
자료에 속한 학습 노트. 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_idself-reference. NULL = 루트 노트(자료 직속), 값이 있으면 해당 노트의 자식. 깊이 무제한 - 인덱스:
(material_id, parent_id, sort_order)— 트리 조회 (부모별 자식 정렬) -
ON DELETE CASCADE(parent_id): 부모 노트 삭제 시 자손 노트 전부 삭제 (서브트리 삭제) -
ON DELETE CASCADE(material_id): 자료 삭제 시 전체 노트 삭제 - 저장 형식: MySQL
JSON타입 사용 → SpringJsonNode/String으로 다루기 용이 -
title은 트리 사이드바 표시용. 빈 노트는 "제목 없음"으로 표시
v2 → v2.1 변경: 기존
material_id UNIQUE(1자료=1노트)를 제거하고parent_id/title/sort_order를 추가하여 트리화. 자료 생성 시 자동 노트 생성은 더 이상 하지 않는다 (빈 트리로 시작).
플래시카드. 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등 도입하지 않음
- BASIC 카드만 대상. ORDERING은 역방향 개념이 없어 제외.
- 카드 추가 시 "양방향" 옵션을 켜면 두 행을 만든다:
A(front→back),B(back→front). 둘은 같은sibling_group_id를 갖는다(값은 첫 카드 id 등 짝 내 공유되는 임의 키). -
생성 후 두 카드는 완전히 독립 — 편집/삭제/복습 사이클이 서로 무관하다(편집 동기화 없음).
sibling_group_id는 오직 burying(형제 분산) 용도로만 쓰인다. - 한쪽을 삭제하면 다른 쪽은 단독 카드로 남는다(
sibling_group_id는 그대로 둬도 무방 — 형제가 없으면 burying이 발동하지 않음).
[
{ "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:items3~7개, 각text1~1000자,id카드 내 유일,back은 무시(NULL 저장) -
type = BASIC:back필수(1~1000자),items는 무시(NULL 저장)
-
카드별 복습 일정. 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_atDESC로 커서 페이지네이션 (Open Items §0D.5) - 캘린더/오늘 목록은
DATE(scheduled_at)기준으로 날짜 그룹핑한다 (화면은 날짜 단위 유지)
ACTIVE ──→ COMPLETED (사용자가 수동으로 변경)
v2에서도 자동 전이는 두지 않는다. 사용자가 명시적으로 완료/보관 버튼을 누를 때만.
-
생성:
parent_id(없으면 루트),title, 빈content.sort_order는 같은 부모 내 max+1 -
이동:
parent_id변경 (다른 노트의 자식으로). 자기 자신/자손을 부모로 지정 불가 (사이클 방지 — 서버 검증) -
정렬: 같은 부모 안에서
sort_order재배치 - 삭제: 서브트리 cascade (자손 노트 전부 삭제). 삭제 전 클라이언트에서 "하위 노트 N개도 함께 삭제" 확인
- 자료 생성 시 노트 자동 생성 안 함 → 빈 트리로 시작
- 생성 시 첫
review_schedule1건 자동 생성 (sequence=1, interval=1, ease=2.50, scheduled_at=(today+1) 04:00, status=PENDING) - 카드 자체에는 상태 없음 (PENDING/COMPLETED는
review_schedule에 있음)
PENDING ──→ COMPLETED (사용자 평가 시)
- COMPLETED 시 SM-2 계산으로 다음 회차
review_schedule1건 생성
간격 계산은 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) |
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)뿐이라 거기에만 분 단위를 적용한다.
짝 카드(같은 sibling_group_id)가 같은 날 함께 나오지 않도록 스케줄러가 분산한다. 목적: 양방향 학습의 장점(양쪽 다 연습)은 살리고, "방금 본 답을 곧바로 되뱉는" 문제를 없앤다.
두 지점에서 발동한다 (리스케줄형 — scheduled_at을 실제로 이동):
-
생성 시 첫 복습 엇갈림
-
A(front→back)첫 복습 =(today+1) 04:00(기존 규칙) -
B(back→front)첫 복습 =(today+2) 04:00(+1일 추가 오프셋) -
interval_days는 둘 다 SM-2 base(1)로 기록.scheduled_at만 하루 밀어 분리한다.
-
-
복습 완료 시 형제 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가 정상 계산된다.
- 카드 A의 복습을 완료(
왜 리스케줄형인가: orino의 오늘 복습·캘린더·due 카운트는 전부
scheduled_at단일 진실 위에 있다. 숨김필터형(scheduled_at은 그대로 두고 오늘 큐에서만 숨김)은 "캘린더엔 오늘인데 큐엔 없음" 불일치를 낳는다. 리스케줄형은scheduled_at을 실제로 옮겨 모든 화면이 일관된다.한계(의도된 단순화): 미래 시점의 충돌을 선제적으로 피하지는 않는다(형제의 다음 회차가 우연히 같은 날 잡히는 경우). 그 날이 오면 "완료 시 bury"가 런타임에 다시 분산하므로 장기적으로도 겹치지 않는다. Anki의 bury와 동일한 접근.
다음 항목은 테이블/컬럼 수준에서 도입하지 않는다. 차기 이후 도입 시 마이그레이션으로 추가:
-
학습 단위(
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) — 배치 서비스 없음
DB 마이그레이션 가이드에 따라 Liquibase changeset으로 관리한다.
- v1 changeset의
study_unit,review_schedule(v1) drop -
study_material에서 v1description컬럼 drop - v2 신규 changeset으로
note(1:1),flashcard,review_schedule(flashcard_id 기반) 생성 -
001-create-member(인증 모듈)는 유지
note 테이블을 트리 구조로 확장하는 ALTER 마이그레이션:
-
note에서material_idUNIQUE 제약 제거 (1자료=1노트 해제) - 컬럼 추가:
-
parent_id BIGINT NULL+ FK self-ref(ON DELETE CASCADE) title VARCHAR(200) NOT NULL DEFAULT '제목 없음'sort_order INT NOT NULL DEFAULT 0
-
- 인덱스 추가:
(material_id, parent_id, sort_order) - 기존 노트(자료당 1개)는
parent_id = NULL(루트),title = '제목 없음',sort_order = 0으로 자연 유지 — 데이터 손실 없음
기존 데이터가 적고 구조가 단순해 ALTER로 무손실 전환 가능. drop 불필요.
향후 카테고리·목표·태그 등은 신규 마이그레이션으로 점진 도입.
flashcard에 카드 종류를 도입하는 ALTER 마이그레이션. 신규 changeset 033-add-flashcard-type-items.yaml (현재 마지막이 032-create-monthly-goal).
- 컬럼 추가:
type VARCHAR(10) NOT NULL DEFAULT 'BASIC'-
items JSON NULL(columnDefinition = "JSON"—note.content패턴)
-
back제약 완화:NOT NULL → NULL(ORDERING은 back 미사용) - 기존 카드는 전부
type = 'BASIC'(DEFAULT),items = NULL,back유지 — 데이터 손실 없음
back을 NULL 허용으로 바꾸면 기존 BASIC 카드는 값이 그대로라 영향 없다. BASIC의back필수는 애플리케이션 레이어(Bean Validation) 에서 강제한다(DB 컬럼은 NULL 허용).review_schedule은 변경 없음 —flashcard_id만 참조하므로 순서 카드도 기존 첫 복습 자동 생성·SM-2 사이클을 그대로 탄다.- Liquibase 관례(
columnExists/tableExists가드, authorwcorn)는 DB 마이그레이션을 따른다.
flashcard에 짝 그룹 키를 더하는 ALTER 마이그레이션. 신규 changeset 034-add-flashcard-sibling-group.yaml (v2.3의 033 다음).
- 컬럼 추가:
sibling_group_id BIGINT NULL - 인덱스 추가:
(sibling_group_id)— burying 시 형제 탐색 - 기존 카드는 전부
sibling_group_id = NULL(단독) — 데이터 손실 없음
review_schedule은 변경 없음. burying은 기존scheduled_at을 이동하는 것뿐이라 스키마 변경이 필요 없다.sibling_group_id에 FK를 걸지 않는다(그룹 키일 뿐 특정 행을 가리키지 않음). 무결성은 애플리케이션에서 관리.
테이블/컬럼 변경 없음. 복습 허브는 전부 조회(집계·목록)라 스키마를 바꾸지 않는다. 완료 목록 커서 페이지네이션(completed_at DESC)만 인덱스가 필요하다. 신규 changeset 035-add-review-schedule-completed-index.yaml (v2.4의 034 다음):
- 인덱스 추가:
(member_id, status, completed_at)— 완료 목록 조회 (status = COMPLETED AND member_id = ?→completed_atDESC keyset)
- 요약 집계(지금/밀림/앞으로/오늘 완료)와 앞으로 목록은 기존 인덱스
(member_id, scheduled_at, status)로 커버된다.- 컬럼 추가/변경/삭제가 없어 데이터 손실·기존 기능 영향 없음. Liquibase 관례(
indexExists가드, authorwcorn)는 DB 마이그레이션을 따른다.