Skip to content

Data Import

wcorn edited this page Jul 11, 2026 · 2 revisions

데이터 Import (v1: 엑셀 → 노트·메모 표)

외부 데이터를 orino의 노트·메모 에디터로 가져오는 확장형 임포터. 여러 데이터 소스를 지원하되, 각 소스는 플러그인처럼 붙고 공통 출력(정규화된 2D 표) → 공통 삽입 파이프라인을 탄다. v1은 Excel(.xlsx) 파일이며, 에디터에 표(Tiptap Table)로 삽입한다.

핵심 결정 요약 (상세는 아래 §5):

  • 대상 = 노트·메모 에디터에 Tiptap 표로 삽입 (자료 노트 + /memo 공용 — NoteEditor 공유)
  • 입력 = .xlsx 파일 업로드 + 클라이언트 파싱(SheetJS) → BE 변경 없음
  • 표 렌더 = Tiptap Table 확장을 공유 NoteEditor에 추가 (양쪽 반영)
  • 값만 가져옴(서식·수식·차트 무시), 행/열 상한 + 노트 1MB 제한 준수

1. 왜 (문제)

학습 자료나 정리 표가 이미 엑셀에 있는데, orino 노트에 옮기려면 손으로 다시 치거나 어색하게 붙여야 한다. "엑셀을 그대로 표로 넣기"를 한 번에 해결하고, 이후 CSV·Google Sheets 등 다른 소스도 같은 흐름으로 확장한다.

2. 범위

구분 v1 (첫 슬라이스) 차기
소스 Excel .xlsx 파일 업로드 CSV, 붙여넣기(TSV/HTML), Google Sheets(서버 OAuth), Notion
대상 노트·메모 에디터에 표 삽입 표 → 플래시카드 변환(별개 기능), 독립 데이터셋
파싱 클라이언트(SheetJS) API 인증 필요한 소스는 서버 파싱
내용 셀 값(텍스트) 만 서식·수식·병합·이미지

3. 화면 흐름 (v1)

에디터(자료 노트 / 메모) 본문에서 시작한다. NoteEditor 공유이므로 두 화면에 동일하게 노출된다.

[노트/메모 에디터 툴바]  … [B] [I] [•] [☑] [📄페이지] [⤵ Import]   ← Import 버튼(또는 /import 슬래시)
                                                        │ 클릭
                                                        ▼
┌──────────────────────── 데이터 가져오기 ────────────────────────┐
│  소스   [ ● Excel(.xlsx) ]  [ CSV (곧) ]  [ Sheets (곧) ]        │ ← 소스 선택(비활성=곧)
│  ────────────────────────────────────────────────────────────  │
│  ┌ 파일을 끌어다 놓거나 [파일 선택] ┐   study_terms.xlsx  ✕      │ ← 드래그/선택
│  └───────────────────────────────┘                             │
│  시트   [ Sheet1 ▾ ]         ☑ 첫 행을 머리글로                  │ ← 다중 시트면 선택
│  ────────────────────────────────────────────────────────────  │
│  미리보기 (상위 5행 · 총 42행 × 3열)                             │
│  ┌────────┬──────────────┬──────┐                              │
│  │ 용어    │ 정의          │ 비고 │                              │
│  ├────────┼──────────────┼──────┤                              │
│  │ Pod     │ 최소 배포 단위 │ ...  │                              │
│  │ …      │ …            │ …   │                              │
│  └────────┴──────────────┴──────┘                              │
│                                        [취소]  [ 표로 가져오기 ] │
└────────────────────────────────────────────────────────────────┘
        │ [표로 가져오기]
        ▼
  커서 위치에 Tiptap 표 노드 삽입 → 기존 자동 저장(PATCH)로 저장

단계:

  1. 툴바 [Import] (또는 슬래시 /import) → 다이얼로그
  2. 소스 = Excel(.xlsx) 선택(기본). 그 외 소스는 "곧" 비활성
  3. .xlsx 파일 드래그/선택 → 클라이언트 파싱(SheetJS: FileReader → workbook)
  4. 시트 2개 이상이면 시트 선택 드롭다운
  5. 옵션: 첫 행을 머리글로(toggle). 켜면 표 헤더 행으로
  6. 미리보기(상위 N행 + 총 R행 × C열 표기, 상한 초과 시 경고)
  7. [표로 가져오기] → 에디터 커서 위치에 Tiptap 표 삽입. 다이얼로그 닫힘
  8. 표는 노트 content의 일부 → 기존 PATCH /notes/{id} 자동 저장으로 저장 (신규 API 없음)

빈/에러 상태:

  • 빈 시트: "이 시트에는 데이터가 없어요"
  • 파싱 실패/비-xlsx: "엑셀(.xlsx) 파일만 가져올 수 있어요"
  • 상한 초과: "표가 커서 상위 {N}행 / {M}열만 가져와요" (또는 잘라서 가져오기 확인)

4. 기술 설계 (v1)

4.1 클라이언트 파싱 (BE 무변경)

  • 파일 업로드 엔드포인트·저장 없이 브라우저에서 파싱한다. .xlsx를 FileReader로 읽어 SheetJS(xlsx)로 workbook → 시트 → 2D 배열(sheet_to_json/sheet_to_aoa).
  • 결과 표는 노트 content JSON(Tiptap)에 table 노드로 들어가 기존 노트 저장 경로를 그대로 탄다. 그래서 BE·스키마 변경이 전혀 없다.
  • 서버 파싱은 API 인증이 필요한 소스(Google Sheets/Notion)를 붙일 때 도입한다(차기). Excel 파일은 클라이언트로 충분.

4.2 Tiptap Table 확장 (공유 에디터에 추가)

  • 현재 NoteEditor는 StarterKit + TaskList + TaskItem + Placeholder + ChildPage. 여기에 @tiptap/extension-table(Table / TableRow / TableHeader / TableCell) 를 추가한다(신규 의존성).
  • 공유 features/note/NoteEditor에 넣으므로 Study Planner 노트 + Memo 양쪽에 자동 반영된다.
  • 스키마에 table 노드가 등록되면 기존/신규 content가 표를 담을 수 있다. 표 편집(행·열 추가/삭제)은 Tiptap Table 기본 커맨드 사용(차기 툴바 노출 검토).

4.3 정규화 & 상한

  • 정규화 출력 = { headers?: string[], rows: string[][] } (모든 셀 문자열). 임포터 공통 인터페이스.
  • 값만: 수식은 계산된 값, 서식/색/병합/차트/이미지는 버림. 병합 셀은 좌상단 값만.
  • 상한(과대 표·1MB 노트 제한 대비): 최대 열 ~30, 최대 행 ~200 (조정 가능). 초과 시 잘라서 + 경고. 삽입 전 직렬화 크기 추정해 1MB 근접 시 차단.

4.4 임포터 레지스트리 (확장 지점)

Importer = {
  id: 'xlsx' | 'csv' | 'gsheets' | ...,
  label, accept,               // UI 표시/파일 필터
  parse(input): NormalizedTable // → { headers?, rows }
}
  • 소스별 parse만 다르고, 이후 미리보기 → Tiptap 표 삽입은 공통. v1은 xlsx 하나만 등록, 나머지는 "곧".

5. 결정 기록

  • 대상 = 노트·메모 표(플래시카드/독립 데이터셋 아님): 요청("엑셀을 표로 넣는다")의 직역이자, 에디터 Tiptap에 자연히 얹힌다. 표 → 카드 변환은 별개 기능으로 분리(차기).
  • 입력 = .xlsx 파일 업로드 + 클라 파싱: 붙여넣기(TSV/HTML)보다 파일이 다중 시트·재사용에 낫고, 클라 파싱이면 BE 무변경으로 첫 슬라이스가 작다. 붙여넣기·CSV는 같은 파이프라인에 얇게 얹을 차기 소스.
  • 공유 에디터에 Table 추가: 노트와 메모가 NoteEditor를 공유하므로 한 번에 양쪽. 개별 구현/분기 회피.
  • 일회성 삽입(동기화 아님): 엑셀↔노트 양방향 동기화는 진실 경계가 복잡해 제외. 가져온 뒤 표는 일반 노트 콘텐츠로 독립 편집.

6. Non-Goals (v1)

  • 서식/색/수식/차트/이미지 가져오기 (값만)
  • 엑셀 ↔ 노트 양방향 동기화 / 재-import 갱신 (일회성 삽입만)
  • 대용량(수천 행+) — v1은 상한으로 컷, 대용량 편집 표는 데이터 그리드 블록으로 분리(Epic #768)
  • 표 → 플래시카드 대량 생성 (별개 기능)
  • Google Sheets / Notion (차기 소스)
  • 서버 업로드·파일 저장 (클라 파싱이라 불필요, 붙여넣기 미지원 — 파일만)

7. 로드맵 (여러 데이터 소스)

  1. v1 — Excel .xlsx 파일 → 노트·메모 표 (본 문서)
  2. v2 — CSV .csv 파일 : 같은 레지스트리에 parse만 추가 (붙여넣기 미지원, 파일 소스만)
  3. 대용량 — 데이터 그리드 블록 : 10MB 초과 표를 별도 dataset + 가상화 편집 그리드로(Epic #768)
  4. v3 — Google Sheets (서버 OAuth로 시트 읽기 — 서버 파싱 도입)
  5. 이후 — Notion 등 · 표 → 플래시카드 변환 파이프라인

Clone this wiki locally