Skip to content

Study Planner Open Items

wcorn edited this page Jul 11, 2026 · 11 revisions

Open Items / 결정 기록: Study Planner (v2.5)

이 문서는 v2 / v2.1 / v2.2 / v2.3 / v2.4 / v2.5 기획 과정에서 내린 결정과 그 이유를 보존한다. 향후 변경 시 컨텍스트 참고용.

0-D. v2.4 → v2.5: 복습 허브 (오늘 복습 → 복습) (신규)

0D.1 "오늘 복습"을 "복습" 허브로 확장 — 새 동작이 아니라 가시화

결정: 하루치 due 카드만 한 장씩 넘기던 화면을, 현황(지금/밀림/앞으로/완료) + 앞으로·완료 목록 조회 + 여러 진입점을 한 화면에 모은 복습 허브로 확장한다. 복습 로직·SM-2·평가 흐름은 그대로. 이유: 사용자가 원한 건 "복습이 어떻게 돌아가는지"를 보는 것 — 지금 뭘 하고, 뭐가 밀렸고, 뭐가 다가오고, 뭘 했나. 특히 AGAIN(다시)으로 생긴 now+10분 재복습이 세션 스냅샷 큐에 반영되지 않아 "복습 일정에 있는데 안 보인다"는 문제가 있었다. 앞당김·타이머 같은 새 메커니즘을 발명하는 대신 이미 있는 데이터를 펼쳐 보여주는 방향으로 결정. 영향: 조회 API 3종 추가(요약 집계 / 앞으로 / 완료). FE 화면 재구성. 스키마·복습 로직 변경 없음.

0D.2 조회 ↔ 진입 통합 (상태 배지·자료 행이 필터이자 진입점)

결정: 좌 레일의 상태 배지(지금 할 것/밀림/앞으로/오늘 완료)와 자료 행을 누르면 그 조건으로 목록이 걸러지며, 시작 시 그 스코프로 세션에 진입한다. 별도 필터 UI와 별도 진입 버튼을 겹쳐 두지 않는다. 이유: 주 행동(복습 시작)을 절대 잃지 않으면서 현황·조회를 그 위에 얹기 위함. "밀린 것만 몰아보기"·"이 자료만 복습"이 자연스러운 한 동작이 된다.

0D.3 세션 스코프(전체/밀림/자료별)는 클라이언트 필터 — 세션 BE 무변경

결정: "전체 복습 시작 / 밀린 것만 / 자료별" 진입은 기존 GET /reviews/today(지금 due 세트)를 받아 클라이언트에서 필터해 세션을 돈다. 세션용 새 엔드포인트/파라미터를 만들지 않는다. 이유: 밀림·자료별은 모두 due-now 세트의 부분집합이다(밀림 = due 중 예정일이 과거, 자료별 = due 중 그 자료). 세트가 작아 클라 필터로 충분하고, 세션 BE·평가·burying 로직을 건드리지 않아 안전하다.

0D.4 요약 수치·자료별 집계는 서버 집계 (목록 길이 아님)

결정: 상단 요약(지금 N / 밀림 X / 앞으로 M / 오늘 완료 K)과 자료별 due/밀림/다음 라벨은 서버 집계 값으로 내려준다. 무한 스크롤로 로드되는 목록 슬라이스 길이와 무관한 총계. 이유: 목록은 페이지네이션돼 일부만 로드되므로 길이로 총계를 셀 수 없다. "복습이 어떻게 돌아가는지"의 핵심 수치라 정확해야 한다.

0D.5 앞으로·완료 목록은 커서(keyset) 기반 무한 스크롤

결정: 앞으로(upcoming)·완료(completed) 목록은 커서 페이지네이션 + 무한 스크롤. offset이 아니라 keyset((scheduled_at, id) / (completed_at, id)). 이유: 무한 스크롤 중 새 복습이 삽입돼도 순서가 밀리지 않고(offset은 중복/누락 발생), 인덱스로 효율적. 단일 사용자지만 장기 누적되는 완료 이력에 특히 유리. 대안(기각): offset/page — 구현은 단순하나 스크롤 중 삽입에 취약.

0D.6 "앞으로" = 전 PENDING(지금 due 포함), 스코프로 좁힘

결정: 앞으로 탭 목록은 모든 PENDING 복습(지금 due + 오늘 남음 + 미래). 상태 배지 스코프(all/today/overdue)와 기간·자료·종류 필터로 좁힌다. 이유: "앞으로"의 총계(예: 37)가 전체 예정이라, 목록도 전체 예정을 담고 스코프로 뷰를 바꾸는 게 일관적. "지금 할 것"은 그 중 due 부분집합.

0D.7 카드 종류 표시 = 기본/순서/양방향 (양방향은 파생)

결정: 목록의 종류 칩은 기본/순서/양방향. 이때 양방향은 카드 타입이 아니라 파생이다 — ORDERING → 순서, BASIC + siblingGroupId 있음 → 양방향, 그 외 BASIC → 기본. 종류 필터도 같은 매핑. 이유: 데이터 모델상 양방향은 BASIC 2장(같은 sibling_group_id)일 뿐 별도 타입이 없다(§0C.1). 표시/필터만 파생으로 계산한다.

0D.8 완료 배지는 "오늘"만, 완료 목록은 최근 전체

결정: 요약의 "오늘 완료 K"는 DATE(completed_at) = today만 카운트. 완료 탭 목록은 최근 완료 전체(어제 이전 포함)를 무한 스크롤로 보여준다. 이유: 배지는 "오늘 얼마나 했나"의 동기부여 수치, 목록은 회고용 이력. 목적이 달라 범위를 분리.

0D.9 라우트: 허브 /planner/reviews, 세션 /planner/reviews/session

결정: 허브를 /planner/reviews, 카드 넘기기 세션을 /planner/reviews/session(스코프/자료 쿼리)로 둔다. 사이드바 라벨 "오늘 복습" → "복습". 기존 /planner/reviews/today는 허브로 리다이렉트. 이유: 화면이 "오늘"만이 아니라 과거·미래를 아우르므로 이름을 "복습"으로. 세션은 별도 라우트로 분리해 허브(조망)와 세션(집중)을 구분한다.


0-C. v2.3 → v2.4: 양방향 짝 카드 + Sibling Burying (신규)

0C.1 양방향은 "카드 추가 시 옵션" → 독립 카드 2개

결정: 카드 추가 다이얼로그(BASIC)에 "양방향" 체크박스. 켜면 (front→back)·(back→front) 독립 카드 2개를 서로 다른 주기로 생성한다. 별도 "양방향 카드 타입"을 만들지 않는다. 이유: 실제 학습에서 정의↔용어처럼 양쪽 방향을 다 연습해야 할 때가 있다. Anki의 "Basic (and reversed card)"와 같은 모델 — 한 입력에서 두 카드. 두 방향은 난이도·기억 곡선이 달라 각자 독립 SM-2 사이클을 갖는 게 자연스럽다. 새 카드 타입 대신 기존 BASIC 2개로 두면 복습 화면·SM-2를 그대로 재사용한다. 영향: flashcard에 sibling_group_id만 추가. 복습 로직은 burying(아래) 외 변경 없음.

0C.2 짝 연결 모델: sibling_group_id (그룹 키)

결정: 짝이 공유하는 sibling_group_id BIGINT NULL 컬럼. 단독 카드는 NULL. FK 없음(특정 행이 아니라 그룹을 가리킴). 이유: burying이 필요로 하는 건 "같은 짝인지" 뿐. 상호 FK(A.sibling_id=B, B.sibling_id=A)는 삽입 시 2단계 업데이트가 필요하고, 그룹 키는 한 값 공유로 끝난다. 향후 n-way(같은 개념의 여러 카드)로도 확장 가능.

0C.3 생성 후 두 카드는 독립 (편집 동기화 없음)

결정: 짝을 만든 뒤 두 카드는 완전히 독립. 한쪽 front를 고쳐도 다른 쪽 back은 안 바뀐다. sibling_group_id는 오직 burying 용도. 이유: 동기화(한쪽 편집 → 반대쪽 자동 수정)는 "어느 필드가 진실인지" 경계와 검증이 복잡해진다. 두 카드는 이미 독립 복습 대상이므로 콘텐츠도 독립이 단순하고 예측 가능. 사용자가 한쪽만 다듬고 싶을 때도 자유롭다.

0C.4 Burying: 리스케줄형 (scheduled_at 이동), 숨김필터형 기각

결정: 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 기반 화면들과 어긋남.

0C.5 되뱉기(regurgitation) 문제 해결이 목적

결정: burying의 목적은 명확히 "같은 날 짝이 함께 나오지 않게". 이유: 짝을 그냥 만들면 첫 복습이 둘 다 (today+1)로 겹친다. "쿠버네티스→정의"를 본 직후 "정의→쿠버네티스"가 나오면 방금 본 답을 그대로 뱉는 셈 → EASY로 눌러 ease가 부풀고 학습 효과가 왜곡. 다른 날로 분산하면 양방향의 장점(양쪽 연습)은 살리고 되뱉기는 사라진다.

0C.6 미래 충돌은 런타임 bury로 (선제 회피 안 함)

결정: 형제의 다음 회차가 우연히 같은 날 잡히는 미래 충돌을 선제적으로 피하지 않는다. 그 날이 오면 "완료 시 bury"가 다시 분산한다. 이유: 선제 회피는 SM-2 간격 계산과 얽혀 복잡. Anki도 런타임 bury만 한다. 매 복습마다 재분산되므로 장기적으로도 겹치지 않는다.

0C.7 ORDERING 카드는 대상 아님

결정: 양방향은 BASIC 전용. ORDERING(순서 카드)은 역방향 개념이 없어 bidirectional 옵션을 노출하지 않고, 요청 시 400. 이유: 순서 카드는 "정답 순서 맞히기"라 앞↔뒤 뒤집기가 성립하지 않는다.

0C.8 기존 단독 카드에 역방향 추가 (차기, 선택)

결정: 이미 만든 단독 카드에서 "역방향 카드 만들기" 액션은 차기 선택 항목. v2.4 1차 범위는 "카드 추가 시 양방향 옵션"에 집중. 이유: 사용자가 명시적으로 원한 건 추가 시 옵션. 기존 카드 역방향화도 유용하지만 같은 생성·burying 로직을 재사용하므로 나중에 얇게 얹을 수 있다. 1차 범위를 좁게 유지.


0-B. v2.2 → v2.3: 순서 카드 (Ordering Card) (신규)

0B.1 기존 flashcard에 type을 더해 카드 종류 확장

결정: 별도 테이블/도메인을 새로 만들지 않고, flashcard에 type(BASIC/ORDERING) 컬럼을 더해 순서 카드를 신설. 이유: 순서 카드도 결국 "복습 대상 카드"다. review_schedule이 flashcard_id만 참조하므로, 같은 테이블에 두면 복습 사이클(첫 복습 자동 생성 + SM-2)을 코드 변경 0으로 상속한다. 새 테이블은 복습 연동을 다시 짜야 해 과설계. 영향: flashcard에 type/items 추가 + back NULL 완화. 복습 BE 로직 변경 없음.

0B.2 정답을 별도 필드로 저장하지 않는다 — items가 곧 정답 순서

결정: items 배열을 항상 정답 순서(index 0 = 1단계)로 저장. 정답 순서를 담는 별도 컬럼을 두지 않는다. 화면에 보여줄 때만 셔플. 이유: 정답을 이중 저장하면 두 진실(items 순서 vs 정답 필드)이 어긋날 수 있다. 순서 자체에 정답을 인코딩하면 데이터가 단일 진실로 단순해진다.

0B.3 각 항목에 안정 id 부여 (FE 생성)

결정: 각 항목은 { id, text }. id는 문자열, 카드 내 유일. FE가 항목 생성 시 부여(nanoid 등), BE는 구조/유일성만 검증. 이유: 드래그로 순서가 바뀌어도 각 항목을 추적할 안정 키가 필요. text를 키로 쓰면 중복 텍스트나 재배열 시 React 키가 꼬인다. 생성 주체를 FE로 둔 건, id의 용도가 런타임 드래그 추적이고 편집 라운드트립에서 클라이언트가 항목 정체성을 관리하기 때문.

0B.4 지시문(prompt)은 기존 front 재사용

결정: 순서 카드의 지시문("kubectl apply 이후 순서대로 배열")은 별도 prompt 컬럼 없이 기존 front에 저장. 이유: "기존 카드에 type만 더한다"는 최소 변경 원칙. front는 이미 BASIC의 "질문"이라 ORDERING의 "지시문"과 의미가 자연스럽게 겹친다. 컬럼/매핑 분기를 줄인다. 대안(기각): 별도 prompt 컬럼 신설 — nullable 컬럼과 매핑 분기만 늘고 이득이 없어 기각.

0B.5 항목 개수: 최소 3 ~ 최대 7

결정: ORDERING의 items는 3~7개. FE·BE 양쪽에서 검증. 이유: 2개 이하는 순서 맞히기의 의미가 옅고(사실상 이지선다), 8개 이상은 드래그 인지 부하가 급증. 3~7은 한 화면에서 다루기 좋은 범위(밀러의 7±2와도 부합).

0B.6 자동 채점 없음 — 색 표시는 "비교 보조", 점수·정답률 계산·표시 안 함

결정: 정답 공개 시 사용자 배열의 각 위치가 정답과 맞는지 색(초록/빨강)으로만 표시. 점수·정답률은 계산도 표시도 하지 않는다. 평가는 사용자가 4등급(다시/어려움/좋음/쉬움) 버튼으로 스스로 내린다. 이유: 이 도메인의 복습은 자기평가 기반 SRS다. 앱이 점수를 매기면 SM-2의 자기평가 모델과 충돌한다. 색은 "내가 맞았나?"를 눈으로 빠르게 확인하게 돕는 시각화일 뿐, 판단은 사용자 몫으로 남긴다. 이 경계를 지키는 게 설계의 핵심.

0B.7 평가 등급: 기존 4등급 유지 (3등급 아님)

결정: 순서 카드도 기존 복습과 동일하게 AGAIN/HARD/GOOD/EASY 4등급. 3등급(다시/어려움/쉬움) 안은 기각. 이유: 복습 시스템 전체가 4등급 SM-2 위에 있다. 순서 카드만 3등급이면 POST /reviews/{id}/complete(Rating enum)·미리보기·SM-2 계산과 불일치한다. 4등급이면 기존 API·화면을 그대로 재사용.

0B.8 셔플: 마운트 1회 + 정답 회피

결정: 복습 화면에서 마운트 시 딱 1회 셔플(Fisher–Yates). 셔플 결과가 우연히 정답과 같으면 재셔플. 항목 1개면 스킵(최소 3개라 사실상 항상 셔플). 이유: 매 렌더마다 섞이면 사용자가 배열하던 게 튄다. 정답과 같은 채로 시작하면 카드가 무의미해진다.

0B.9 드래그: @dnd-kit sortable + 핸들 분리 + 8px 임계값 + revealed 잠금

결정: @dnd-kit(core/sortable/utilities) 도입. 드래그 핸들(≡)만 잡기, arrayMove로 재정렬, PointerSensor 8px 이동 임계값, revealed 상태에선 드래그 이벤트 무시. 이유: @dnd-kit은 키보드·스크린리더 접근성이 기본 내장. 항목 전체를 드래그 대상으로 두면 텍스트 선택/스크롤과 충돌해 핸들을 분리. 8px 임계값은 탭을 드래그로 오인하는 것을 막는다(모바일 특히). 정답 공개 후엔 재배열을 잠근다. 현재 저장소에 드래그 라이브러리가 없어 신규 의존성으로 추가.


0-A. v2.1 → v2.2: 노트 인라인 하위 페이지 (신규)

0A.1 트리 구현을 Notion 인라인 방식으로

결정: v2.1의 "사이드바 트리 + [+ 하위 노트] 버튼" 대신, 본문에서 /페이지로 하위 노트를 만들어 본문 content 안에 childPage 블록으로 박는 Notion 인라인 방식으로 구현. 이유: 사용자가 원한 건 "글 쓰다가 그 자리에서 하위 노트 만들고 이어쓰기"였음. 사이드바 버튼 방식은 글쓰기 흐름이 끊김. 인라인이 진짜 Notion UX. 영향: BE는 v2.1 그대로 (parent_id 트리 + note CRUD). FE만 Tiptap childPage 커스텀 노드 + 본문↔노트 동기화로 재작성. 테이블/마이그레이션 변경 없음.

0A.2 트리 진실(source of truth): parent_id

결정: 트리 관계의 진실은 DB parent_id. 본문의 childPage 블록은 "본문 내 인라인 진입점". 사이드바 트리는 parent_id로 구성. 이유: content JSON만으로 트리를 재구성하면 조회/집계가 어려움. parent_id가 정규화된 진실이면 사이드바·삭제·복습 등 모든 곳에서 일관.

0A.3 본문 ↔ 노트 동기화

결정: childPage 블록 삽입 = POST notes(자식 생성), 블록 삭제 = DELETE notes(서브트리). content 변경분 비교(이전/현재 childPage noteId 집합 diff)로 삭제 검출. 이유: 블록과 노트 레코드를 1:1로 유지해야 트리·사이드바가 본문과 어긋나지 않음.

0A.4 1차 제외: 복붙 · 이동

결정: childPage 블록 복붙(복제)과 본문 간 이동(부모 변경)은 v2.2 1차에서 제외. 복제는 차단/무시. 이유: 복붙 시 noteId 중복, 이동 시 본문↔트리 동기화가 까다로움. 1차는 "생성·진입·삭제"만. 잘못 두면 삭제 후 재생성.


0. v2 → v2.1: 노트 트리화

참고: 0.1의 "2-pane 트리 + 사이드바 버튼 생성" UX는 v2.2(§0-A)에서 인라인 방식으로 대체됨. 데이터 모델(parent_id 트리)은 유지.

0.1 노트를 Notion 스타일 트리로

결정: 자료당 노트를 1:1 단건에서 1:N 트리(parent_id self-ref, 무제한 중첩) 로 확장. 이유: 사용자가 책의 장(章)/절(節)처럼 학습 내용을 중첩 구조로 정리하고 싶어함. 단일 노트로는 긴 자료를 담기 어렵고 탐색도 불편. 영향: note에 parent_id/title/sort_order 추가, material_id UNIQUE 제거. 노트 API가 단건 GET/PUT → 트리 CRUD로 확장.

0.2 카드는 자료 직속 유지

결정: 노트가 트리가 되어도 카드는 노트가 아닌 자료에 그대로 붙인다. 이유: 복습은 자료 전체 단위로 모으는 게 자연스럽고, 노트↔카드 매핑 UI 복잡도 회피. "어느 노트에서 나온 카드인지" 연결은 차기.

0.3 자료 생성 시 노트 자동 생성 폐지

결정: v2에서 하던 "자료 생성 시 빈 노트 1건 자동 생성"을 제거. 빈 트리로 시작. 이유: 트리 모델에선 빈 상태에서 [+ 노트]로 시작하는 게 자연스럽고, "제목 없음" 노트가 강제로 생기는 어색함 제거.

0.4 노트 이동 사이클 방지

결정: parentId 변경 시 자기 자신/자손을 부모로 지정하면 서버가 거부 (400). 이유: 트리 무결성. 사이클 발생 시 조회/삭제가 깨짐.

0.5 마이그레이션: ALTER 무손실

결정: v2 → v2.1은 drop 없이 ALTER로 컬럼 추가 + UNIQUE 제거. 기존 노트는 루트로 자연 편입. 이유: 데이터 손실 없이 전환 가능. v1→v2와 달리 구조가 호환됨.


1. v1 → v2 구조 전환

1.1 학습 단위(unit) 폐기

결정: v1의 study_unit (챕터/회차) 개념을 완전 제거. 이유: 단위에 콘텐츠가 없어 "뭘 복습해야 할지"가 외부 자료에 있었음. 노트+카드 모델에서는 카드 자체가 학습/복습 단위. 영향: study_unit 테이블 drop. review_schedule.study_unit_id → flashcard_id.

1.2 노트 ↔ 카드 분리

결정: 노트와 카드는 같은 자료에 속하되, 직접 매핑은 안 함. (Tiptap 인라인 카드 블록 X) 이유: 구현 단순, 책임 분리 명확. 한 흐름으로 합치는 건 차기 작업. 비교: Anki도 노트와 카드가 분리되어 있음. 대안 (검토): 노트 내 인라인 card 블록 (Tiptap 커스텀 노드). 차기 검토.

1.3 마이그레이션 없이 전면 롤백

결정: v1 데이터 점진 마이그레이션 없이 drop & recreate. 이유: v1 출시 직후라 데이터 적음. 점진 마이그레이션 복잡도 > 재입력 비용.

2. 노트

2.1 에디터: Tiptap

결정: Tiptap (블록 에디터) 채택. 마크다운/리치텍스트 대신. 이유: React 친화 OSS, JSON 저장으로 향후 검색/변환 용이, Notion 스타일 UX. 시작 익스텐션: StarterKit + TaskList + TaskItem. 슬래시 메뉴는 차기.

2.2 노트와 자료의 관계: 1:N 트리 (v2.1 갱신)

결정: 자료당 노트 N개, Notion 스타일 트리 (무제한 중첩). 자료 생성 시 노트 0개. 이유: 중첩 정리 + 탐색. (v2의 1:1 단건 결정은 §0.1에서 트리로 대체됨) 히스토리: v2에서는 "자료당 노트 1개 + 자동 생성"이었으나, 사용자 요구로 v2.1에서 트리화.

2.3 저장 방식: PATCH content idempotent + 2초 debounce

결정: 자동 저장, PATCH /notes/:id로 해당 노트 content 덮어쓰기. 이유: 단일 사용자라 동시 편집 충돌 가능성 낮음. 단순 구현. 대안 (검토): 블록 단위 patch / OT/CRDT. 협업 모듈 도입 시 검토.

2.4 노트 크기 제한: 1MB

결정: 직렬화된 JSON 크기 1MB 이하. 이유: 단일 자료 노트로 충분. 초과 시 자료 분리 유도. 서버 검증: 초과 시 400 SP-ERR-002.

3. 플래시카드

3.1 카드 구조: 앞/뒷면 plain text

결정: front, back 각 VARCHAR(1000), 줄바꿈 허용 plain text. 이유: v2 단순화. 마크다운/리치텍스트/멀티미디어는 차기.

3.2 카드 생성 시 첫 복습 자동 생성

결정: 카드 생성 시점에 review_schedule 1건 자동 생성 (sequence=1, today+1, ease=2.50). 이유: SM-2 표준. 평가 결과로 다음 간격이 결정되므로 1건만 미리 생성.

3.3 카드 정렬: 생성순

결정: (material_id, id ASC) 고정. sort_order 컬럼 없음. 이유: v2 단순화. 카드 재정렬 UI 부담 제거. 차기에 sort_order 도입.

3.4 카드 자료 간 이동 없음

결정: 카드의 material_id는 변경 불가. 이유: 단순화. 잘못 만들었으면 삭제 후 재생성.

4. 복습 (SM-2)

4.1 알고리즘: SM-2

결정: SM-2 + Anki 4단계 평가 (AGAIN=0, HARD=3, GOOD=4, EASY=5). 이유: 검증된 표준, FSRS와 입력 포맷 동일하여 마이그레이션 용이.

4.2 OVERDUE 동적 처리

결정: 별도 OVERDUE 상태 컬럼 없음. scheduled_at <= now AND status = PENDING을 동적 조회. 이유: 상태 전이 단순. 배치 잡 불필요.

4.3 놓침 정책: today 기준 재계산

결정: 뒤늦게 평가해도 다음 복습은 today + new_interval. 즉시보충/리셋/스킵 분기 없음. 이유: 단순. 과거 누적이 미래 일정을 어지럽히지 않음.

4.4 SM-2 파라미터: 표준값 고정

결정: 초기 ease=2.50, 최소 ease=1.30, 1회차=1일, 2회차=6일. 이유: SM-2 원본 정의 그대로. 사용자 커스터마이징은 차기.

4.5 복습 캘린더 (투두메이트 스타일)

4.5.1 표시 대상: 예정 + 완료 모두

결정: 캘린더에 PENDING + COMPLETED 복습을 모두 표시. 이유: 지난 한 달 회고(완료 이력) + 앞으로 계획(예정)을 한 화면에서. 투두메이트의 "지난 한 달 뭘 했는지" 회고 가치.

4.5.2 색상 기준: 상태별 (자료 color 미도입)

결정: 날짜 칸 색을 복습 상태로 구분 — 🔴밀림 / 🟣오늘 / ⚪예정 / ✅완료. study_material에 color 컬럼 추가 안 함. 이유: 복습 캘린더의 핵심은 "지금 뭘 해야 하나(밀림/오늘)". 자료별 색은 카테고리 도입 시 함께. 지금 색 컬럼 추가하면 자료 CRUD/마이그레이션 변경 필요 → 범위 절약. 대안 (검토): 자료별 color (투두메이트 카테고리 색). 카테고리 모듈과 함께 차기.

4.5.3 배치 기준: scheduled_at

결정: 모든 항목(완료 포함)을 scheduled_at(예정일) 칸에 배치. completed_at이 아님. 이유: "복습 일정" 캘린더이므로 예정일 기준이 일관적. 밀려서 늦게 완료한 것도 원래 예정일 칸에 ✅로 표시.

4.5.4 보기 전용

결정: 캘린더에서 직접 평가하지 않음. 날짜 클릭 → 그날 목록 + [오늘 복습 하러가기]. 이유: 평가 흐름(앞→답→4지선다)은 오늘 복습 화면에 집중. 캘린더는 조망 전용으로 단순.

4.5.5 집계는 FE에서

결정: API는 기간 내 복습 항목 리스트를 반환, 날짜별 그룹핑/상태분류/카운트는 FE 계산. 이유: 단일 사용자 + 월 데이터 적음. 서버 집계 쿼리 불필요. 상태 분류는 today 기준이라 클라이언트 계산이 자연스러움.

5. 데이터/스키마

5.1 member_id 비정규화

결정: 모든 테이블에 member_id 컬럼 유지. 이유: 멀티유저 확장 대비. 단일 인덱스로 사용자별 조회 가능.

5.2 ON DELETE CASCADE

결정: 자료 삭제 시 노트/카드/복습 모두 cascade. 이유: 단순. 소프트 삭제 안 함.

5.3 노트 content 타입: MySQL JSON

결정: JSON 컬럼 (MySQL 8.0+). 이유: 인덱싱은 불필요, 직렬화/역직렬화 편의. LONGTEXT 대신 JSON 검증.

6. UI

6.1 자료 상세: 노트 탭 / 카드 탭

결정: 자료 상세에 2개 탭. 기본 노트 탭. 이유: 학습 → 노트, 복습 → 카드. 화면 분리로 컨텍스트 명확.

6.2 오늘 복습: 카드 1장씩

결정: 한 화면에 카드 1장. Space → 답 공개 → 1/2/3/4 평가. 이유: Anki 표준 UX. 집중도 ↑.

6.3 키보드 단축키 필수

결정: Space (답 공개), 1/2/3/4 (평가) 단축키 구현. 이유: 빠른 복습 흐름. 데스크탑 사용자 핵심 경험.

6.4 미리보기 (preview) 표시

결정: 평가 버튼 위에 각 평가 시 다음 간격(일수) 표시. 이유: Anki 표준. 사용자가 선택 시 결과를 예측 가능.

7. 에러 코드

코드 HTTP 설명
SP-ERR-001 404 존재하지 않는 리소스
SP-ERR-002 400 유효하지 않은 요청 (검증 실패, 노트 크기 초과)
SP-ERR-003 409 멱등성 충돌 (이미 COMPLETED 복습 평가 시도)

8. 의식적으로 안 한 것 (Non-Goals for v2)

  • 카테고리 / 목표
  • 카드 태그 / 덱
  • 카드 멀티미디어 / 클로즈
  • 카드 일괄 입력 (CSV / Anki 임포트)
  • 노트 ↔ 카드 인라인 연결
  • 노트 풀텍스트 검색
  • 알림 / 푸시
  • 통계 / 스트릭 / 히트맵
  • 자동 스케줄링 / 캘린더
  • 다중 사용자 / 공유
  • PWA / 오프라인

9. 미해결 / 차후 결정

  • Tiptap 슬래시 메뉴(/) 도입 시점 — v2에는 툴바 + 마크다운 단축키만. 사용 빈도 보고 결정.
  • 카드 추가 다이얼로그에서 노트 부분 인용 — 사용자가 노트 일부를 카드로 옮길 때 복붙 외 UX. 현 v2는 복붙만.
  • 자료 status 전이 자동화 — 현재 수동만. v2 사용 중 자동 전이 룰 필요성 발견 시 도입.

Clone this wiki locally