Repository navigation
Study Planner Open Items
이 문서는 v2 / v2.1 / v2.2 / v2.3 / v2.4 / v2.5 기획 과정에서 내린 결정과 그 이유를 보존한다. 향후 변경 시 컨텍스트 참고용.
결정: 하루치 due 카드만 한 장씩 넘기던 화면을, 현황(지금/밀림/앞으로/완료) + 앞으로·완료 목록 조회 + 여러 진입점을 한 화면에 모은 복습 허브로 확장한다. 복습 로직·SM-2·평가 흐름은 그대로.
이유: 사용자가 원한 건 "복습이 어떻게 돌아가는지"를 보는 것 — 지금 뭘 하고, 뭐가 밀렸고, 뭐가 다가오고, 뭘 했나. 특히 AGAIN(다시)으로 생긴 now+10분 재복습이 세션 스냅샷 큐에 반영되지 않아 "복습 일정에 있는데 안 보인다"는 문제가 있었다. 앞당김·타이머 같은 새 메커니즘을 발명하는 대신 이미 있는 데이터를 펼쳐 보여주는 방향으로 결정.
영향: 조회 API 3종 추가(요약 집계 / 앞으로 / 완료). FE 화면 재구성. 스키마·복습 로직 변경 없음.
결정: 좌 레일의 상태 배지(지금 할 것/밀림/앞으로/오늘 완료)와 자료 행을 누르면 그 조건으로 목록이 걸러지며, 시작 시 그 스코프로 세션에 진입한다. 별도 필터 UI와 별도 진입 버튼을 겹쳐 두지 않는다. 이유: 주 행동(복습 시작)을 절대 잃지 않으면서 현황·조회를 그 위에 얹기 위함. "밀린 것만 몰아보기"·"이 자료만 복습"이 자연스러운 한 동작이 된다.
결정: "전체 복습 시작 / 밀린 것만 / 자료별" 진입은 기존 GET /reviews/today(지금 due 세트)를 받아 클라이언트에서 필터해 세션을 돈다. 세션용 새 엔드포인트/파라미터를 만들지 않는다.
이유: 밀림·자료별은 모두 due-now 세트의 부분집합이다(밀림 = due 중 예정일이 과거, 자료별 = due 중 그 자료). 세트가 작아 클라 필터로 충분하고, 세션 BE·평가·burying 로직을 건드리지 않아 안전하다.
결정: 상단 요약(지금 N / 밀림 X / 앞으로 M / 오늘 완료 K)과 자료별 due/밀림/다음 라벨은 서버 집계 값으로 내려준다. 무한 스크롤로 로드되는 목록 슬라이스 길이와 무관한 총계. 이유: 목록은 페이지네이션돼 일부만 로드되므로 길이로 총계를 셀 수 없다. "복습이 어떻게 돌아가는지"의 핵심 수치라 정확해야 한다.
결정: 앞으로(upcoming)·완료(completed) 목록은 커서 페이지네이션 + 무한 스크롤. offset이 아니라 keyset((scheduled_at, id) / (completed_at, id)).
이유: 무한 스크롤 중 새 복습이 삽입돼도 순서가 밀리지 않고(offset은 중복/누락 발생), 인덱스로 효율적. 단일 사용자지만 장기 누적되는 완료 이력에 특히 유리.
대안(기각): offset/page — 구현은 단순하나 스크롤 중 삽입에 취약.
결정: 앞으로 탭 목록은 모든 PENDING 복습(지금 due + 오늘 남음 + 미래). 상태 배지 스코프(all/today/overdue)와 기간·자료·종류 필터로 좁힌다. 이유: "앞으로"의 총계(예: 37)가 전체 예정이라, 목록도 전체 예정을 담고 스코프로 뷰를 바꾸는 게 일관적. "지금 할 것"은 그 중 due 부분집합.
결정: 목록의 종류 칩은 기본/순서/양방향. 이때 양방향은 카드 타입이 아니라 파생이다 — ORDERING → 순서, BASIC + siblingGroupId 있음 → 양방향, 그 외 BASIC → 기본. 종류 필터도 같은 매핑.
이유: 데이터 모델상 양방향은 BASIC 2장(같은 sibling_group_id)일 뿐 별도 타입이 없다(§0C.1). 표시/필터만 파생으로 계산한다.
결정: 요약의 "오늘 완료 K"는 DATE(completed_at) = today만 카운트. 완료 탭 목록은 최근 완료 전체(어제 이전 포함)를 무한 스크롤로 보여준다.
이유: 배지는 "오늘 얼마나 했나"의 동기부여 수치, 목록은 회고용 이력. 목적이 달라 범위를 분리.
결정: 허브를 /planner/reviews, 카드 넘기기 세션을 /planner/reviews/session(스코프/자료 쿼리)로 둔다. 사이드바 라벨 "오늘 복습" → "복습". 기존 /planner/reviews/today는 허브로 리다이렉트.
이유: 화면이 "오늘"만이 아니라 과거·미래를 아우르므로 이름을 "복습"으로. 세션은 별도 라우트로 분리해 허브(조망)와 세션(집중)을 구분한다.
결정: 카드 추가 다이얼로그(BASIC)에 "양방향" 체크박스. 켜면 (front→back)·(back→front) 독립 카드 2개를 서로 다른 주기로 생성한다. 별도 "양방향 카드 타입"을 만들지 않는다.
이유: 실제 학습에서 정의↔용어처럼 양쪽 방향을 다 연습해야 할 때가 있다. Anki의 "Basic (and reversed card)"와 같은 모델 — 한 입력에서 두 카드. 두 방향은 난이도·기억 곡선이 달라 각자 독립 SM-2 사이클을 갖는 게 자연스럽다. 새 카드 타입 대신 기존 BASIC 2개로 두면 복습 화면·SM-2를 그대로 재사용한다.
영향: flashcard에 sibling_group_id만 추가. 복습 로직은 burying(아래) 외 변경 없음.
결정: 짝이 공유하는 sibling_group_id BIGINT NULL 컬럼. 단독 카드는 NULL. FK 없음(특정 행이 아니라 그룹을 가리킴).
이유: burying이 필요로 하는 건 "같은 짝인지" 뿐. 상호 FK(A.sibling_id=B, B.sibling_id=A)는 삽입 시 2단계 업데이트가 필요하고, 그룹 키는 한 값 공유로 끝난다. 향후 n-way(같은 개념의 여러 카드)로도 확장 가능.
결정: 짝을 만든 뒤 두 카드는 완전히 독립. 한쪽 front를 고쳐도 다른 쪽 back은 안 바뀐다. sibling_group_id는 오직 burying 용도.
이유: 동기화(한쪽 편집 → 반대쪽 자동 수정)는 "어느 필드가 진실인지" 경계와 검증이 복잡해진다. 두 카드는 이미 독립 복습 대상이므로 콘텐츠도 독립이 단순하고 예측 가능. 사용자가 한쪽만 다듬고 싶을 때도 자유롭다.
결정: sibling burying을 scheduled_at을 실제로 옮기는 리스케줄형으로 구현. (a) 생성 시 첫 복습 엇갈림(A: today+1, B: today+2), (b) 복습 완료 시 오늘 due인 형제를 다음날로 밀어냄. 완료 응답에 buriedReviewIds 반환.
이유: orino의 오늘 복습·캘린더·due 카운트가 전부 scheduled_at 단일 진실 위에 있다. 숨김필터형(scheduled_at은 그대로, 오늘 큐에서만 숨김)은 "캘린더엔 오늘인데 큐엔 없음" 불일치를 만든다. 리스케줄형은 모든 화면이 일관된다. SM-2 간격은 건드리지 않고 due 날짜만 하루 지연하므로 알고리즘 영향 없음.
대안(기각): 숨김필터형(Anki 고전) — 구현은 가볍지만 orino의 scheduled_at 기반 화면들과 어긋남.
결정: burying의 목적은 명확히 "같은 날 짝이 함께 나오지 않게".
이유: 짝을 그냥 만들면 첫 복습이 둘 다 (today+1)로 겹친다. "쿠버네티스→정의"를 본 직후 "정의→쿠버네티스"가 나오면 방금 본 답을 그대로 뱉는 셈 → EASY로 눌러 ease가 부풀고 학습 효과가 왜곡. 다른 날로 분산하면 양방향의 장점(양쪽 연습)은 살리고 되뱉기는 사라진다.
결정: 형제의 다음 회차가 우연히 같은 날 잡히는 미래 충돌을 선제적으로 피하지 않는다. 그 날이 오면 "완료 시 bury"가 다시 분산한다. 이유: 선제 회피는 SM-2 간격 계산과 얽혀 복잡. Anki도 런타임 bury만 한다. 매 복습마다 재분산되므로 장기적으로도 겹치지 않는다.
결정: 양방향은 BASIC 전용. ORDERING(순서 카드)은 역방향 개념이 없어 bidirectional 옵션을 노출하지 않고, 요청 시 400.
이유: 순서 카드는 "정답 순서 맞히기"라 앞↔뒤 뒤집기가 성립하지 않는다.
결정: 이미 만든 단독 카드에서 "역방향 카드 만들기" 액션은 차기 선택 항목. v2.4 1차 범위는 "카드 추가 시 양방향 옵션"에 집중. 이유: 사용자가 명시적으로 원한 건 추가 시 옵션. 기존 카드 역방향화도 유용하지만 같은 생성·burying 로직을 재사용하므로 나중에 얇게 얹을 수 있다. 1차 범위를 좁게 유지.
결정: 별도 테이블/도메인을 새로 만들지 않고, flashcard에 type(BASIC/ORDERING) 컬럼을 더해 순서 카드를 신설.
이유: 순서 카드도 결국 "복습 대상 카드"다. review_schedule이 flashcard_id만 참조하므로, 같은 테이블에 두면 복습 사이클(첫 복습 자동 생성 + SM-2)을 코드 변경 0으로 상속한다. 새 테이블은 복습 연동을 다시 짜야 해 과설계.
영향: flashcard에 type/items 추가 + back NULL 완화. 복습 BE 로직 변경 없음.
결정: items 배열을 항상 정답 순서(index 0 = 1단계)로 저장. 정답 순서를 담는 별도 컬럼을 두지 않는다. 화면에 보여줄 때만 셔플.
이유: 정답을 이중 저장하면 두 진실(items 순서 vs 정답 필드)이 어긋날 수 있다. 순서 자체에 정답을 인코딩하면 데이터가 단일 진실로 단순해진다.
결정: 각 항목은 { id, text }. id는 문자열, 카드 내 유일. FE가 항목 생성 시 부여(nanoid 등), BE는 구조/유일성만 검증.
이유: 드래그로 순서가 바뀌어도 각 항목을 추적할 안정 키가 필요. text를 키로 쓰면 중복 텍스트나 재배열 시 React 키가 꼬인다. 생성 주체를 FE로 둔 건, id의 용도가 런타임 드래그 추적이고 편집 라운드트립에서 클라이언트가 항목 정체성을 관리하기 때문.
결정: 순서 카드의 지시문("kubectl apply 이후 순서대로 배열")은 별도 prompt 컬럼 없이 기존 front에 저장.
이유: "기존 카드에 type만 더한다"는 최소 변경 원칙. front는 이미 BASIC의 "질문"이라 ORDERING의 "지시문"과 의미가 자연스럽게 겹친다. 컬럼/매핑 분기를 줄인다.
대안(기각): 별도 prompt 컬럼 신설 — nullable 컬럼과 매핑 분기만 늘고 이득이 없어 기각.
결정: ORDERING의 items는 3~7개. FE·BE 양쪽에서 검증.
이유: 2개 이하는 순서 맞히기의 의미가 옅고(사실상 이지선다), 8개 이상은 드래그 인지 부하가 급증. 3~7은 한 화면에서 다루기 좋은 범위(밀러의 7±2와도 부합).
결정: 정답 공개 시 사용자 배열의 각 위치가 정답과 맞는지 색(초록/빨강)으로만 표시. 점수·정답률은 계산도 표시도 하지 않는다. 평가는 사용자가 4등급(다시/어려움/좋음/쉬움) 버튼으로 스스로 내린다. 이유: 이 도메인의 복습은 자기평가 기반 SRS다. 앱이 점수를 매기면 SM-2의 자기평가 모델과 충돌한다. 색은 "내가 맞았나?"를 눈으로 빠르게 확인하게 돕는 시각화일 뿐, 판단은 사용자 몫으로 남긴다. 이 경계를 지키는 게 설계의 핵심.
결정: 순서 카드도 기존 복습과 동일하게 AGAIN/HARD/GOOD/EASY 4등급. 3등급(다시/어려움/쉬움) 안은 기각.
이유: 복습 시스템 전체가 4등급 SM-2 위에 있다. 순서 카드만 3등급이면 POST /reviews/{id}/complete(Rating enum)·미리보기·SM-2 계산과 불일치한다. 4등급이면 기존 API·화면을 그대로 재사용.
결정: 복습 화면에서 마운트 시 딱 1회 셔플(Fisher–Yates). 셔플 결과가 우연히 정답과 같으면 재셔플. 항목 1개면 스킵(최소 3개라 사실상 항상 셔플). 이유: 매 렌더마다 섞이면 사용자가 배열하던 게 튄다. 정답과 같은 채로 시작하면 카드가 무의미해진다.
결정: @dnd-kit(core/sortable/utilities) 도입. 드래그 핸들(≡)만 잡기, arrayMove로 재정렬, PointerSensor 8px 이동 임계값, revealed 상태에선 드래그 이벤트 무시.
이유: @dnd-kit은 키보드·스크린리더 접근성이 기본 내장. 항목 전체를 드래그 대상으로 두면 텍스트 선택/스크롤과 충돌해 핸들을 분리. 8px 임계값은 탭을 드래그로 오인하는 것을 막는다(모바일 특히). 정답 공개 후엔 재배열을 잠근다. 현재 저장소에 드래그 라이브러리가 없어 신규 의존성으로 추가.
결정: v2.1의 "사이드바 트리 + [+ 하위 노트] 버튼" 대신, 본문에서 /페이지로 하위 노트를 만들어 본문 content 안에 childPage 블록으로 박는 Notion 인라인 방식으로 구현.
이유: 사용자가 원한 건 "글 쓰다가 그 자리에서 하위 노트 만들고 이어쓰기"였음. 사이드바 버튼 방식은 글쓰기 흐름이 끊김. 인라인이 진짜 Notion UX.
영향: BE는 v2.1 그대로 (parent_id 트리 + note CRUD). FE만 Tiptap childPage 커스텀 노드 + 본문↔노트 동기화로 재작성. 테이블/마이그레이션 변경 없음.
결정: 트리 관계의 진실은 DB parent_id. 본문의 childPage 블록은 "본문 내 인라인 진입점". 사이드바 트리는 parent_id로 구성.
이유: content JSON만으로 트리를 재구성하면 조회/집계가 어려움. parent_id가 정규화된 진실이면 사이드바·삭제·복습 등 모든 곳에서 일관.
결정: childPage 블록 삽입 = POST notes(자식 생성), 블록 삭제 = DELETE notes(서브트리). content 변경분 비교(이전/현재 childPage noteId 집합 diff)로 삭제 검출.
이유: 블록과 노트 레코드를 1:1로 유지해야 트리·사이드바가 본문과 어긋나지 않음.
결정: childPage 블록 복붙(복제)과 본문 간 이동(부모 변경)은 v2.2 1차에서 제외. 복제는 차단/무시. 이유: 복붙 시 noteId 중복, 이동 시 본문↔트리 동기화가 까다로움. 1차는 "생성·진입·삭제"만. 잘못 두면 삭제 후 재생성.
참고: 0.1의 "2-pane 트리 + 사이드바 버튼 생성" UX는 v2.2(§0-A)에서 인라인 방식으로 대체됨. 데이터 모델(parent_id 트리)은 유지.
결정: 자료당 노트를 1:1 단건에서 1:N 트리(parent_id self-ref, 무제한 중첩) 로 확장.
이유: 사용자가 책의 장(章)/절(節)처럼 학습 내용을 중첩 구조로 정리하고 싶어함. 단일 노트로는 긴 자료를 담기 어렵고 탐색도 불편.
영향: note에 parent_id/title/sort_order 추가, material_id UNIQUE 제거. 노트 API가 단건 GET/PUT → 트리 CRUD로 확장.
결정: 노트가 트리가 되어도 카드는 노트가 아닌 자료에 그대로 붙인다. 이유: 복습은 자료 전체 단위로 모으는 게 자연스럽고, 노트↔카드 매핑 UI 복잡도 회피. "어느 노트에서 나온 카드인지" 연결은 차기.
결정: v2에서 하던 "자료 생성 시 빈 노트 1건 자동 생성"을 제거. 빈 트리로 시작. 이유: 트리 모델에선 빈 상태에서 [+ 노트]로 시작하는 게 자연스럽고, "제목 없음" 노트가 강제로 생기는 어색함 제거.
결정: parentId 변경 시 자기 자신/자손을 부모로 지정하면 서버가 거부 (400).
이유: 트리 무결성. 사이클 발생 시 조회/삭제가 깨짐.
결정: v2 → v2.1은 drop 없이 ALTER로 컬럼 추가 + UNIQUE 제거. 기존 노트는 루트로 자연 편입. 이유: 데이터 손실 없이 전환 가능. v1→v2와 달리 구조가 호환됨.
결정: v1의 study_unit (챕터/회차) 개념을 완전 제거.
이유: 단위에 콘텐츠가 없어 "뭘 복습해야 할지"가 외부 자료에 있었음. 노트+카드 모델에서는 카드 자체가 학습/복습 단위.
영향: study_unit 테이블 drop. review_schedule.study_unit_id → flashcard_id.
결정: 노트와 카드는 같은 자료에 속하되, 직접 매핑은 안 함. (Tiptap 인라인 카드 블록 X) 이유: 구현 단순, 책임 분리 명확. 한 흐름으로 합치는 건 차기 작업. 비교: Anki도 노트와 카드가 분리되어 있음. 대안 (검토): 노트 내 인라인 card 블록 (Tiptap 커스텀 노드). 차기 검토.
결정: v1 데이터 점진 마이그레이션 없이 drop & recreate. 이유: v1 출시 직후라 데이터 적음. 점진 마이그레이션 복잡도 > 재입력 비용.
결정: Tiptap (블록 에디터) 채택. 마크다운/리치텍스트 대신. 이유: React 친화 OSS, JSON 저장으로 향후 검색/변환 용이, Notion 스타일 UX. 시작 익스텐션: StarterKit + TaskList + TaskItem. 슬래시 메뉴는 차기.
결정: 자료당 노트 N개, Notion 스타일 트리 (무제한 중첩). 자료 생성 시 노트 0개. 이유: 중첩 정리 + 탐색. (v2의 1:1 단건 결정은 §0.1에서 트리로 대체됨) 히스토리: v2에서는 "자료당 노트 1개 + 자동 생성"이었으나, 사용자 요구로 v2.1에서 트리화.
결정: 자동 저장, PATCH /notes/:id로 해당 노트 content 덮어쓰기.
이유: 단일 사용자라 동시 편집 충돌 가능성 낮음. 단순 구현.
대안 (검토): 블록 단위 patch / OT/CRDT. 협업 모듈 도입 시 검토.
결정: 직렬화된 JSON 크기 1MB 이하.
이유: 단일 자료 노트로 충분. 초과 시 자료 분리 유도.
서버 검증: 초과 시 400 SP-ERR-002.
결정: front, back 각 VARCHAR(1000), 줄바꿈 허용 plain text.
이유: v2 단순화. 마크다운/리치텍스트/멀티미디어는 차기.
결정: 카드 생성 시점에 review_schedule 1건 자동 생성 (sequence=1, today+1, ease=2.50).
이유: SM-2 표준. 평가 결과로 다음 간격이 결정되므로 1건만 미리 생성.
결정: (material_id, id ASC) 고정. sort_order 컬럼 없음.
이유: v2 단순화. 카드 재정렬 UI 부담 제거. 차기에 sort_order 도입.
결정: 카드의 material_id는 변경 불가.
이유: 단순화. 잘못 만들었으면 삭제 후 재생성.
결정: SM-2 + Anki 4단계 평가 (AGAIN=0, HARD=3, GOOD=4, EASY=5). 이유: 검증된 표준, FSRS와 입력 포맷 동일하여 마이그레이션 용이.
결정: 별도 OVERDUE 상태 컬럼 없음. scheduled_at <= now AND status = PENDING을 동적 조회.
이유: 상태 전이 단순. 배치 잡 불필요.
결정: 뒤늦게 평가해도 다음 복습은 today + new_interval. 즉시보충/리셋/스킵 분기 없음.
이유: 단순. 과거 누적이 미래 일정을 어지럽히지 않음.
결정: 초기 ease=2.50, 최소 ease=1.30, 1회차=1일, 2회차=6일. 이유: SM-2 원본 정의 그대로. 사용자 커스터마이징은 차기.
결정: 캘린더에 PENDING + COMPLETED 복습을 모두 표시. 이유: 지난 한 달 회고(완료 이력) + 앞으로 계획(예정)을 한 화면에서. 투두메이트의 "지난 한 달 뭘 했는지" 회고 가치.
결정: 날짜 칸 색을 복습 상태로 구분 — 🔴밀림 / 🟣오늘 / ⚪예정 / ✅완료. study_material에 color 컬럼 추가 안 함.
이유: 복습 캘린더의 핵심은 "지금 뭘 해야 하나(밀림/오늘)". 자료별 색은 카테고리 도입 시 함께. 지금 색 컬럼 추가하면 자료 CRUD/마이그레이션 변경 필요 → 범위 절약.
대안 (검토): 자료별 color (투두메이트 카테고리 색). 카테고리 모듈과 함께 차기.
결정: 모든 항목(완료 포함)을 scheduled_at(예정일) 칸에 배치. completed_at이 아님.
이유: "복습 일정" 캘린더이므로 예정일 기준이 일관적. 밀려서 늦게 완료한 것도 원래 예정일 칸에 ✅로 표시.
결정: 캘린더에서 직접 평가하지 않음. 날짜 클릭 → 그날 목록 + [오늘 복습 하러가기]. 이유: 평가 흐름(앞→답→4지선다)은 오늘 복습 화면에 집중. 캘린더는 조망 전용으로 단순.
결정: API는 기간 내 복습 항목 리스트를 반환, 날짜별 그룹핑/상태분류/카운트는 FE 계산. 이유: 단일 사용자 + 월 데이터 적음. 서버 집계 쿼리 불필요. 상태 분류는 today 기준이라 클라이언트 계산이 자연스러움.
결정: 모든 테이블에 member_id 컬럼 유지.
이유: 멀티유저 확장 대비. 단일 인덱스로 사용자별 조회 가능.
결정: 자료 삭제 시 노트/카드/복습 모두 cascade. 이유: 단순. 소프트 삭제 안 함.
결정: JSON 컬럼 (MySQL 8.0+).
이유: 인덱싱은 불필요, 직렬화/역직렬화 편의. LONGTEXT 대신 JSON 검증.
결정: 자료 상세에 2개 탭. 기본 노트 탭. 이유: 학습 → 노트, 복습 → 카드. 화면 분리로 컨텍스트 명확.
결정: 한 화면에 카드 1장. Space → 답 공개 → 1/2/3/4 평가. 이유: Anki 표준 UX. 집중도 ↑.
결정: Space (답 공개), 1/2/3/4 (평가) 단축키 구현. 이유: 빠른 복습 흐름. 데스크탑 사용자 핵심 경험.
결정: 평가 버튼 위에 각 평가 시 다음 간격(일수) 표시. 이유: Anki 표준. 사용자가 선택 시 결과를 예측 가능.
| 코드 | HTTP | 설명 |
|---|---|---|
| SP-ERR-001 | 404 | 존재하지 않는 리소스 |
| SP-ERR-002 | 400 | 유효하지 않은 요청 (검증 실패, 노트 크기 초과) |
| SP-ERR-003 | 409 | 멱등성 충돌 (이미 COMPLETED 복습 평가 시도) |
- 카테고리 / 목표
- 카드 태그 / 덱
- 카드 멀티미디어 / 클로즈
- 카드 일괄 입력 (CSV / Anki 임포트)
- 노트 ↔ 카드 인라인 연결
- 노트 풀텍스트 검색
- 알림 / 푸시
- 통계 / 스트릭 / 히트맵
- 자동 스케줄링 / 캘린더
- 다중 사용자 / 공유
- PWA / 오프라인
-
Tiptap 슬래시 메뉴(
/) 도입 시점 — v2에는 툴바 + 마크다운 단축키만. 사용 빈도 보고 결정. - 카드 추가 다이얼로그에서 노트 부분 인용 — 사용자가 노트 일부를 카드로 옮길 때 복붙 외 UX. 현 v2는 복붙만.
- 자료 status 전이 자동화 — 현재 수동만. v2 사용 중 자동 전이 룰 필요성 발견 시 도입.