Skip to content

Data Grid Block

wcorn edited this page Aug 31, 2026 · 12 revisions

데이터 그리드 블록 (대용량 편집 표)

범위: 데이터 Import의 후속. 10MB 초과(수만~수십만 셀) 표를 노트에 인라인으로, 편집 가능하게, 성능 유지로 다루기 위한 구조. 노트 content엔 경량 참조 노드만 담고, 표 데이터는 별도 dataset 리소스에 저장한다. FE는 Tiptap NodeView 안에서 가상화 편집 그리드(TanStack Table + Virtual)로 렌더한다.

상태: 구현 완료 (Epic #768). 모든 표가 dataset 그리드다 — native Tiptap 표(TableKit)는 #789에서 제거되어 크기 임계치 분기는 폐기됐다(#787에서 툴바·Import 진입점을 dataset으로 전환).

열 조작 4종(rename #792 · add #793 · delete #794 · reorder #795)과 수식 지원 설계(Epic #799)는 §10·§12 참고.

1. 왜 (문제)

Data-Import v1은 엑셀·CSV를 native Tiptap 표로 삽입한다. 이 방식의 한계:

  • 성능: ProseMirror/Tiptap 표는 상태 업데이트마다 재렌더 → 수천 셀부터 입력이 버벅인다(prosemirror-tables엔 가상화 없음).
  • 저장/전송: 표가 노트 content(단일 JSON 문서) 안에 통째로 들어가 매번 통째 저장·로드된다.
  • 한계: 실용상 수 MB. 그래서 v1은 행/열 상한으로 컷했다.

native 표 커맨드로는 "인라인 편집 + 대용량"을 동시에 못 한다(물리적 한계). 업계 정석(Notion DB 블록, 가상화 데이터 그리드)은 대용량 표 데이터를 문서에서 분리하고 가상화 렌더한다.

2. 접근 — 데이터 그리드 블록

노트 content (작게 유지)                 별도 저장소
┌───────────────────────────┐          ┌──────────────────────────┐
│ doc                       │          │ dataset (메타)           │
│  ├ paragraph …            │   ref    │  columns, row_count      │
│  ├ datasetTable{datasetId}├─────────▶│                          │
│  └ paragraph …            │          │ dataset_row × N          │
└───────────────────────────┘          │  row_index, cells(JSON)  │
        │ NodeView                      └──────────────────────────┘
        ▼                                  ▲ page fetch / patch
  ┌─────────────────────────┐              │
  │ TanStack Table + Virtual│──────────────┘
  │  보이는 행만 DOM        │
  │  셀 편집·복붙·행/열 조작 │
  └─────────────────────────┘
  • 노트 content엔 datasetTable { datasetId } leaf 노드 하나 → content는 항상 작다(1MB 문제 없음).
  • 표 데이터는 dataset/dataset_row에 저장. 그리드가 보이는 페이지만 지연 로드하고, 편집은 행 단위 patch로 저장한다(노트 통째 저장 X).

핵심 결정 (상세 §10):

  • 그리드: TanStack Table + TanStack Virtual (편집·복붙 UI는 자체 구현 — DOM 완전 제어)
  • 저장 모델: dataset_row(행-JSON) — 페이지 조회·행 patch에 단순
  • Import: 크기 임계치 분기 → 폐기. native 표를 제거하고 dataset으로 단일화했다(#787·#789)
  • 파싱: 클라이언트 재사용(SheetJS) — 파싱 결과를 dataset에 벌크 업로드

3. 데이터 모델

member (1) ──< (N) dataset (1) ──< (N) dataset_row
                    │                      └ row_index · cells(JSON 문자열 배열)
                    └ columns(JSON) · row_count

dataset

컬럼 타입 설명
id BIGINT PK
member_id BIGINT FK, NOT NULL 소유자(비정규화)
columns JSON, NOT NULL 열 메타 [{ "key": "c0", "label": "과목", "width?": 240, "align?": "right" }, …]. width(px)·align(left/center/right)은 nullable — 없으면 기본 폭·기본 정렬(left). 값 없는 필드는 직렬화에서 빠져 마이그레이션 없이 확장된다(#830 width · #828 align)
row_count INT, NOT NULL 행 수(비정규화, 조회 최적화)
next_column_seq INT, NOT NULL 열 key 발급 카운터. 지운 key를 재발급하면 행에 남은 옛 값이 새 열에 되살아나므로 한 방향으로만 올린다 (#798)
created_at / updated_at DATETIME(6)

dataset_row

컬럼 타입 설명
id BIGINT PK
dataset_id BIGINT FK, NOT NULL, ON DELETE CASCADE
row_index INT, NOT NULL 정렬 키(0-base)
cells JSON, NOT NULL 열 key 기반 맵 {"c0":"네트워크","c1":"92"} (#797)
height INT 표시 높이(px). NULL이면 기본 높이(36). 열 너비가 columns_json의 열 속성이듯, 행 속성은 여기(#839). 값 있는 행만 sparse
  • 인덱스: (dataset_id, row_index) UNIQUE — 페이지 조회(offset/limit = row_index 범위)·정렬.
  • 한 행 = DB 한 행. 10만 행 = 10만 로우.
  • cells는 key 맵이고 API는 위치 배열이다(#797). DatasetService가 경계에서 columns 순서로 투영·역투영한다. 덕분에 열 추가·삭제·순서변경이 columns 갱신만으로 끝나고 행을 안 건드린다(O(1)). 클라이언트는 여전히 직사각형 표만 다룬다.
  • cells엔 값이 담긴다. 수식은 별도 sparse 테이블(dataset_formula)에 두어 이 읽기 경로를 그대로 유지한다 — 설계는 Epic #799, §12 참고.
  • id는 행의 안정적 식별자다(#801). row_index는 삽입·삭제 때 밀리지만 id는 안 바뀐다 — 수식의 행 참조가 묶이는 대상.
  • 행 삽입/삭제 시 재인덱싱 이슈: 임의 위치 삽입은 뒤 행 row_index 시프트가 O(n). v1은 append·말단 편집 중심이라 허용, 대규모 임의 삽입은 gap/fractional index(sort_order 패턴)로 최적화 — [결정 기록 §10].
  • 스키마 변경은 Liquibase changeset(신규 2 테이블).

dataset_cell_style (셀 서식 — 배경색·정렬·세로정렬)

컬럼 타입 설명
id BIGINT PK
dataset_id BIGINT FK, NOT NULL, ON DELETE CASCADE
row_id BIGINT FK, NOT NULL, ON DELETE CASCADE 행 정체성은 row_index가 아니라 id — 행이 밀려도 서식이 따라다닌다
col_key VARCHAR(64), NOT NULL 셀 주소 = (row_id, col_key)
bg VARCHAR(32) 배경색 토큰명(red/orange/yellow/green/blue/purple — hex 아님). 없으면 NULL
align VARCHAR(16) 가로 정렬 left/center/right. 없으면 NULL(열 기본 정렬을 따른다)
valign VARCHAR(16) 세로 정렬 top/middle/bottom. 없으면 NULL(기본=위). 세로 병합된 큰 셀에서 유용(#890)
  • 값이 아니라 서식만 담는다(#828). 값은 dataset_row.cells에 그대로 남아 읽기 경로가 안 바뀐다 — 수식(dataset_formula)과 같은 sparse 전략. bg·align·valign 모두 NULL이면 이 행 자체가 없다(서식 없는 셀).
  • 배경색은 토큰명 저장, 렌더는 var(--cell-bg-<토큰>). 라이트/다크 토큰을 따로 둬 다크모드 대비가 자동 해결된다(자유 hex라면 어두운 테마에서 글자를 삼키는 문제를 따로 보정해야 한다).
  • 정렬은 2단(#828 D2): 열 기본은 columns[].align, 셀 단위 override는 여기 align. 셀 > 열 > 기본(left) 순으로 이긴다.
  • 세로 정렬(#890): valign은 셀 서식에만 있다(열 기본 없음). 렌더는 기본(top)일 때 기존 truncate 블록 그대로(말줄임 유지)이고, 가운데/아래일 때만 세로 flex(justify-*)로 전환한다 — DOM·말줄임 회귀 없이 세로 병합 셀에서 값 위치를 잡는다.
  • 삭제 정리: 행·데이터셋 삭제는 FK cascade로 함께 사라진다. 열 삭제는 col_key가 FK가 아니라 cascade가 없어 styleService.invalidateColumn으로 즉시 지운다(수식의 invalidateColumn과 같은 처리).

4. API 스펙 (/api/datasets)

모두 소유자(member) 스코프. 응답은 공통 ApiResponse 래핑.

메서드·경로 요청 응답 용도
POST /datasets { columns: [{key,label,width?,align?}] } { id, columns, rowCount:0 } 빈 dataset 생성. width·align은 생성 시에도 검증(우회 방지)
POST /datasets/{id}/rows:bulk { rows: string[][], startIndex? } { rowCount } Import 벌크 삽입(청크)
GET /datasets/{id} — { id, columns, rowCount } 메타(그리드 초기화)
GET /datasets/{id}/rows?offset&limit — { rows:[{id,rowIndex,cells,formulas,styles}], offset, limit } 가상화 페이지. formulas·styles는 있는 셀만 담긴 sparse 맵(열key→…)
PATCH /datasets/{id}/rows/{rowIndex} { cells } { id, rowIndex, cells, formulas, styles } 셀/행 편집
POST /datasets/{id}/rows { atIndex?, cells } { rowIndex } 행 추가
DELETE /datasets/{id}/rows/{rowIndex} — 204 행 삭제
PUT /datasets/{id}/rows/{rowIndex}/cells/{colKey}/style { bg?, align? } { id, rowIndex, cells, formulas, styles } 셀 서식(배경색·정렬) 통째 교체. 빈 요청({})이면 그 셀 서식 삭제(#828)
POST /datasets/{id}/columns { label?, atIndex? } { columns } 열 추가 — key·기본 이름은 서버가 발급(#798·#804). atIndex를 주면 그 위치에 삽입(#838), 없으면 끝에
PATCH /datasets/{id}/columns/{key} { label } { columns } 열 이름 변경(#792). 중복이면 409
DELETE /datasets/{id}/columns/{key} — { columns } 열 삭제(#794). 마지막 열은 400
PATCH /datasets/{id}/columns/order { keys: string[] } { columns } 열 순서 변경(#795). 전체 순서, 집합이 다르면 400
GET /datasets/{id}/row-heights — { heights: [{rowIndex,height}] } 기본이 아닌 행 높이 전체(#839). 세로 병합 오버레이의 누적 높이용, dataset 단위 sparse
PATCH /datasets/{id}/rows/{rowIndex}/height { height } { heights } 행 높이(#839). 24–600px, 범위 밖 400. 갱신된 전체 반환
DELETE /datasets/{id}/rows/{rowIndex}/height — { heights } 행 높이 초기화(기본 36)
PATCH /datasets/{id}/columns/{key}/width { width } { columns } 열 너비(#830). 60–800px, 범위 밖 400
DELETE /datasets/{id}/columns/{key}/width — { columns } 열 너비 초기화(기본 폭)
PATCH /datasets/{id}/columns/{key}/align { align } { columns } 열 기본 정렬(#828). left/center/right, 그 외 400
DELETE /datasets/{id}/columns/{key}/align — { columns } 열 정렬 초기화(기본 left)
  • 페이지 크기: 기본 limit 100, 최대 500. 벌크 청크: 요청당 최대 ~2,000행 권장.
  • 인가: getOwnedDataset(memberId, id) — 타인 404.

5. FE 설계

5.1 Tiptap 노드 datasetTable

  • atom block leaf 노드, attrs: { datasetId }. content엔 이 노드만(데이터 없음).
  • ReactNodeView로 그리드 렌더. 블록 선택·삭제는 ProseMirror(블록 통째). 삭제 감지 시 dataset 정리(childPage 삭제 감지 패턴 재사용).

5.2 그리드 (TanStack Table + Virtual)

  • TanStack Table: 헤드리스 테이블 로직(열/셀 모델). TanStack Virtual: 행 가상화(보이는 행 + 버퍼만 DOM).
  • 지연 로드: 가상화 스크롤 위치 → 필요한 row_index 범위를 GET /rows?offset&limit로 페이지 fetch + 캐시(react-query 무한/윈도우). 미로드 행은 스켈레톤.
  • 편집(자체 구현): 셀 클릭 → inline input/contentEditable, 확정 시 해당 행 PATCH(디바운스). 복사/붙여넣기 = clipboard 이벤트 → 대상 셀 범위 채우고 영향 행 배치 patch. 행/열 추가·삭제 = 툴바 → API.
  • 열 헤더: dataset columns.

가로 넘침 — 행 폭은 "보이는 폭"이 아니라 표 전체 폭 (#996)

행·세로병합 오버레이·열 선택 핸들 바는 모두 w-full로 폭을 잡는다. 그런데 가로 스크롤 컨테이너(.overflow-x-auto) 안의 블록 요소는 폭이 auto라 보이는 폭(clientWidth)까지만 차지한다. 셀은 gridTemplateColumns대로 그 밖까지 넘쳐 그려지지만, 가로줄은 셀이 아니라 행의 border-b 라서 행 폭에서 끊긴다 → 오른쪽으로 스크롤하면 줄이 사라진다.

본문 컨테이너에 열 최소 폭 합계를 min-width로 준다(지정 폭 열은 그 값, 유연폭 열은 FLEX_COLUMN_MIN_WIDTH). 그러면 그 위의 w-full 요소가 모두 표 전체 폭으로 늘어난다. 컨테이너가 그보다 넓으면 min-width가 안 걸려 1fr 스트레치가 그대로 산다. 열 요약줄(border-t)도 같은 값을 쓴다.

width: max-content로는 안 된다 — 행이 position: absolute(가상화)라 절대 위치 자식은 intrinsic 폭에 기여하지 않는다. 그래서 열 정의에서 폭을 직접 계산한다.

포인터별 상호작용 (마우스 vs 터치, #994)

단일 셀을 선택하면 그 셀 위에 빈 <input>을 미리 띄운다 — 선택 직후 글자를 치면 곧바로 덮어쓰기가 되고 한글 IME 조합이 끊기지 않게 하는 장치다. 그런데 터치에선 이 입력창이 포커스되는 순간 가상 키보드가 뜬다. 표를 잡으려는 첫 터치가 곧 셀 선택이라, 열이 넘치는 표를 좌우로 스크롤할 수 없었다.

pointerdown의 e.pointerType으로 갈라 처리한다.

마우스·펜 터치
1번째 선택 + 활성 입력창(타이핑 대기) 선택만 — 입력창 없음 → 키보드 안 뜸, 스크롤 가능
같은 셀 다시 (변화 없음) 편집 진입 — 이때만 키보드
편집 더블클릭 같은 셀 재탭
드래그 범위 선택 범위 선택 안 함 — 스크롤에 양보
  • 더블탭을 쓰지 않는 이유: 브라우저 확대 제스처와 겹쳐 모바일에서 신뢰할 수 없다. "선택된 셀 재탭"은 Excel·Sheets 모바일과 같은 관례다.
  • 터치 드래그를 범위 선택으로 잡지 않는 이유: 같은 제스처를 스크롤과 나눠 쓸 수 없고, 열이 넘치는 표에선 스크롤이 우선이다.
  • 물리 키보드 keydown이 오면 터치 모드를 풀어 활성 입력창을 되살린다(외장 키보드 태블릿).
  • 화면 폭(max-width)이 아니라 포인터 종류로 가르는 이유: 좁은 창의 데스크탑은 마우스로 쓰고, 넓은 태블릿도 손가락으로 쓴다. 문제의 원인은 화면 크기가 아니라 입력 방식이다.

5.3 저장/일관성

  • 노트 자동저장과 분리: 그리드 편집은 dataset API로만 나간다(노트 content는 datasetId만 있어 안 바뀜).
  • 낙관적 업데이트 + 실패 롤백. 동시 편집은 v1 범위 밖(단일 사용자 가정).

6. Import 연동 (크기 임계치 분기)

기존 Import 다이얼로그의 파싱(SheetJS)·미리보기는 그대로. [표로 가져오기]에서만 분기:

파싱된 2D(정규화) → cell 수 / 예상 직렬화 크기 계산
   ├─ 임계치 이하(예: ≤ 2,000셀)  → 기존 native Tiptap 표 삽입 (현행)
   └─ 임계치 초과                → ① POST /datasets(columns)
                                    ② POST rows:bulk (청크 반복)
                                    ③ datasetTable{datasetId} 노드 삽입
  • 임계치는 상수(조정 가능). 초과 시 미리보기 하단에 "대용량 표로 저장됩니다(그리드 블록)" 안내.
  • 파싱은 클라이언트 유지(BE 파일 업로드 불필요).

7. 성능·한계

  • 가상화로 10만 행도 스크롤 반응 유지(보이는 ~수십 행만 DOM).
  • dataset 셀 상한(예: 100만 셀)·페이지/청크 크기로 폭주 방지.
  • 임의 위치 대량 삽입은 재인덱싱 비용 — gap index로 완화(§10).

8. 공존·마이그레이션

  • 소형 표: 기존 native Tiptap 표 유지(가볍고 마크다운 친화). 기능·스타일 무변경.
  • 대형: dataset 블록. 필요 시 "표 → 데이터셋 변환"(기존 native 표를 dataset으로 승격) 별도 액션(선택, 후순위).
  • 기존 노트/데이터 마이그레이션 불필요(신규 경로만 추가).

9. 유스케이스

  1. 사용자가 5만 행 엑셀을 노트에 Import → 임계치 초과 → 그리드 블록 생성, 커서 위치에 삽입, 즉시 스크롤·편집 가능.
  2. 그리드에서 셀 수정/행 추가 → dataset patch로 저장(노트는 안 건드림), 새로고침 후 유지.
  3. 블록 삭제 → dataset 정리.

10. 결정 기록

  • 그리드 = TanStack Table + Virtual: DOM 완전 제어로 orino 디자인 토큰·인터랙션에 맞춤. 편집·복붙 UI는 자체 구현(비용↑이나 종속·라이선스 부담 없음). react-data-grid(커뮤니티 편집 내장)·AG Grid(Enterprise 유료)를 검토 후 제외.
  • 저장 = 행-JSON(dataset_row): 페이지 조회·행 patch가 단순. 셀 단위 정규화(수백만 로우)·청크(500행/row)는 후순위 최적화.
  • Import = 크기 임계치 분기: 소형은 가벼운 native 표 유지가 UX상 자연스럽다. 항상 dataset은 단순하나 작은 표까지 그리드로 무겁게 만든다.
  • 파싱 = 클라 재사용: 기존 SheetJS 파이프라인 재사용, BE 파일 업로드·서버 파서 도입 회피.
  • cells = 열 key 맵, API = 위치 배열(#797): 위치 배열로 저장하면 열 추가·삭제·순서변경마다 전 행을 재작성해야 한다(O(행수)). key 맵으로 두고 경계에서 투영하면 열 조작이 columns 갱신만으로 끝나고(O(1)) FE는 안 바뀐다.
  • 열 key는 재사용하지 않는다(#798): next_column_seq로 발급. "현재 열의 최대 번호+1"은 삭제 후 최대값이 내려가 지운 key를 재발급하고, 행에 남은 옛 값이 새 열에 되살아난다.
  • 열 삭제는 지연 정리(#794): 행에 남은 값은 즉시 지우지 않는다(O(n)이라 key 맵을 택한 이유가 무너진다). 투영이 columns 기준으로만 읽어 즉시 도달 불가해지고, 그 행을 다음에 수정할 때 사라진다.
  • label 유일성 — 출처에 따라 다르게(#804): 기계가 만든 label(Import 헤더·기본 이름)은 자동 구분(점수 (2)), 사람이 지정한 label(rename)은 409 거부. 단순 거부하면 중복 헤더를 가진 엑셀 Import가 깨진다.
  • 행 정체성 = dataset_row.id(#801): row_index는 순번이라 정체성이 될 수 없다. 수식의 행 참조는 id에 묶는다.
  • gap/fractional index가 수식의 선결 조건 → 철회: 분수 인덱스는 정렬 키가 안 밀리게 할 뿐, 행을 끼우면 5번째가 6번째 되는 건 똑같다 — 위치 기반 참조는 gap index로 안 고쳐진다. 정체성 문제의 답은 id이고, gap index는 삽입 성능 항목으로 남는다(#778).
  • 가로 넘침 시 행 폭은 min-width로 고정(#996): 스크롤 컨테이너 안 블록 요소는 보이는 폭까지만 차지해, 행의 border-b(가로줄)가 스크롤한 구간에서 끊겼다. 열 최소 폭 합계를 본문 컨테이너 min-width로 준다. 가상화로 행이 absolute라 max-content는 쓸 수 없다(§5.2).
  • 터치는 선택으로 입력창을 띄우지 않는다(#994): 선택 활성 입력창은 데스크탑의 타이핑·IME 연속성을 위한 장치인데, 터치에선 포커스가 곧 가상 키보드라 표 스크롤을 막았다. e.pointerType으로 갈라 터치는 "선택만 → 재탭하면 편집"으로 둔다(§5.2). 화면 폭이 아니라 입력 방식이 기준이다.
  • 열린 항목: 행 gap/fractional index 도입 시점(성능, 실측 후) · 표↔데이터셋 상호 변환(native 표 제거로 소멸) · 동시 편집 · 세로 병합(행 독립 가상화와 양립 불가 — §12).

11. 마일스톤 (이슈)

  1. BE — dataset/dataset_row 스키마(Liquibase) + CRUD + 페이지 조회 + rows:bulk + 행 patch ✅
  2. FE — datasetTable 노드 + NodeView + TanStack Table/Virtual 그리드 + 지연 로드/편집/patch ✅
  3. FE — Import 임계치 분기 → 폐기. native 표를 제거하고 dataset으로 단일화(#787·#789·#791)
  4. 열 조작 확장 ✅ — rename(#792) · add(#793) · delete(#794) · reorder(#795). 저장 모델을 key 맵으로 전환(#797)해 전부 O(1)
  5. 선택 — 행 gap/fractional index(#778, 성능·실측 후)
  6. 설계 완료, 구현 대기 — 수식 지원(Epic #799) · §12
  7. 열 속성·셀 서식 ✅ — 열 너비(#830) · 열 정렬(#828) = columns[] 속성 · 셀 배경색(#831) · 셀 정렬 override(#828) = dataset_cell_style sparse 테이블(§3). 값 스키마 무변경

12. 수식 지원 (Epic #799)

상태: 설계 완료, 구현 대기. 이 문서의 이전 판은 *"cells는 값만(서식·수식 없음)"*이라 적었으나, 수식을 지원하기로 하면서 그 서술은 폐기됐다.

수식이 들어오면 dataset은 "서버가 저장만 하는 값 덩어리"에서 **"서버가 의미를 이해하고 연산하는 데이터"**로 바뀐다. 열 key와 행 id가 연산의 주소가 된다.

주요 결정 (상세는 #799):

  • 임의 셀 참조까지(엑셀식) · 서버 계산 · 셀 단위 수식
  • 참조는 정체성에 바인딩, 표시는 위치로 — cells가 key 맵인 것과 같은 전략. 행 삽입·열 순서 변경에도 수식 재작성이 필요 없다
  • 참조 3종: 같은 행(=c0*c1, 행 id 안 씀) · 절대(=B5, row_id 바인딩) · 열 집계(=SUM(c2)). 가장 흔한 계산 열이 1번이라 행 정체성을 안 쓴다
  • 쓸 때 계산 + 값 저장 — 읽을 때 계산은 열 집계가 페이지 조회마다 전체 스캔을 유발하고, 서버 정렬·필터의 이득을 없앤다
  • 수식은 별도 sparse 테이블(dataset_formula + dataset_formula_ref) — cells는 계산된 값을 계속 담아 읽기 경로가 안 바뀐다
  • 함수: 산술 + SUM/AVG/COUNT/MIN/MAX (IF는 비교·논리 연산자와 세트라 별도)
  • 열 범위는 입력 시 정체성 집합으로 스냅샷 → 순서 변경이 의미를 안 바꾼다

범위 밖:

  • 세로 병합 — 본문은 각 행이 독립 absolute div(높이 고정)이고 가상화가 보이는 행만 그린다. 셀이 행을 넘을 수 없어 행 독립 가상화가 걸린다. → 별도 Epic #829(설계: Data-Grid-Cell-Merge). 다만 그 설계에서 이 "양립 불가" 판정은 가변 높이 전제라 과한 것으로 정정됐다 — 고정 높이에선 가로 병합은 가상화와 완전히 양립하고, 세로 병합도 오버레이 레이어로 성립한다.
  • 서식(정렬·색깔·크기) ✅ 구현됨 — 구조 문제가 아니라 수식과 같은 지점(셀 부가 정보)이라 같은 sparse 전략으로 풀었다: 열 너비(#830)·정렬(#828)은 columns[] 속성, 셀 배경색(#831)·정렬 override(#828)는 dataset_cell_style 테이블(§3). 값 스키마·읽기 경로는 그대로. 세로 병합만 별도 Epic로 남는다

13. 엑셀 지향 확장 (Epic #892)

상태: 착수. 표 엔진을 "엑셀처럼" 확장한다. 큰 방향은 확정 — BE 엔진 확장(클라 엔진으로 갈아타지 않음). §12가 깐 "서버 권위 · 주소 바인딩 · sparse 저장" 위에 그대로 쌓는다.

순서 (의존 관계)

넷은 독립이 아니라 수식 엔진을 뿌리로 쌓인다: 반응성은 "수식 재계산을 빠르게", (a) 자동합계·채우기핸들은 "수식을 생성하는 UX", (c) xlsx는 "수식·서식을 파일로 직렬화". 그래서 (b) 수식 확장 → 반응성 → (a) UX 증분 → (c) xlsx 순.

ADR-1 — 참조 모델: 엑셀 A1을 내부에 쓰지 않는다

탐구할 설계가 아니라 회귀 금지 가드레일이다. orino 내부 수식은 이미 열 key + 행 id 주소를 쓴다(§12) — 열 이름을 바꾸거나 행이 밀려도 안 깨지는 게 핵심 강점. 엑셀 A1(그리드 좌표)로 회귀하면 이 내성을 잃는다. 엑셀 A1 문법은 xlsx import/export 경계((c))에서만 우리 주소 모델과 상호 번역한다. 새 함수(IF·SUMIF 등) 추가는 참조 의미를 건드리지 않는다 — 그래서 이 결정은 (b)를 블록하지 않는다.

ADR-2 — 반응성: 서버 권위 유지 + 골든 교차검증

계산의 SSOT는 BE 엔진. 클라이언트 엔진(HyperFormula 등)으로 통째 교체하지 않는다 — BE에 파서·평가기·의존성 그래프가 이미 있어 엔진을 두 벌로 중복시키는 함정이 된다. 서버 권위의 유일한 대가는 "입력→API 왕복→결과"인데, 반응성이 필요하면 BE를 권위로 두고 FE에 BE와 동일 함수 집합만 구현한 경량 평가기를 얹되, 양쪽을 같은 conformance(골든) 스위트로 교차검증한다. 골든 스위트가 두 구현의 SSOT. → 그래서 골든 하네스를 (b)의 워킹 스켈레톤(#893)부터 심는다: 나중 리스크를 지금 공짜로 앞당겨 없앤다.

값 타입 미니 스펙 (IF·비교연산자 선결)

IF·비교연산자를 넣는 순간 값 체계가 Num/Err 2종에서 넓어진다. 파싱이 아니라 여기가 phase 1이 부풀 수 있는 지점이라 먼저 못 박는다.

  • 값 타입 4종: number · text · boolean · error(기존 #REF!/#VALUE!/#DIV/0! 확장). 열엔 타입이 없고 셀 단위로 평가·에러(§12의 O11 유지).
  • 비교연산자(= < > <= >= <>) → boolean. 양쪽이 숫자면 수치 비교, 아니면 텍스트 비교(대소문자 무시 — 엑셀식). 교차 타입은 엑셀 타입 순위 number < text < boolean(즉 임의 텍스트 > 임의 숫자, 1 < "a" = TRUE).
  • 빈 셀: 산술·수치 비교에선 0(기존 ref()가 이미 빈칸→0), 텍스트 비교에선 "".
  • IF 지연 평가: IF(cond, a, b) — cond 먼저. 에러면 전파, 아니면 고른 가지만 평가(안 고른 가지의 에러·비용을 억제).
  • AND/OR/NOT: boolean 대상, 숫자는 0=false / 그 외=true로 강제(엑셀식). 엑셀처럼 인자를 다 평가하되 에러는 전파.
  • 에러 전파: 피연산자 중 에러가 있으면 결과는 그 에러(좌→우 첫 에러). 비교·IF 조건·논리 어디서든 동일.

이 스펙이 정하는 건 (b)의 IF/비교 PR부터 적용된다. 워킹 스켈레톤(#893, 스칼라 함수 파이프라인 + ABS)은 number-only라 이 스펙을 안 건드린다 — 그래서 warmup으로 안전하고, 골든 하네스만 세운다.

마일스톤

  1. 워킹 스켈레톤(#893) — FormulaNode.Call 스칼라 함수 노드 + ABS 끝까지 관통 + FormulaConformanceTest 골든 하네스
  2. IF + 비교연산자 + AND/OR/NOT — 위 값타입 스펙 적용. 진짜 언락 지점
  3. SUMIF/COUNTIF — 2+집계 조합. 이 시점에 "환율 IF 자동환산 · 카테고리 SUMIF 합계" 예시가 orino에서 그대로 돈다
  4. 반응성 → (a) UX → (c) xlsx (Epic #892)

(c) xlsx — 내보내기 (#1308)

상태: 내보내기 완료. 가져오기는 미착수.

ADR-1이 말한 「경계」가 실제 코드 자리로 굳었다 — planner/dataset/export/FormulaA1Writer. 수식 트리(열 key + 행 id)를 A1으로 옮기는 유일한 곳이고, 내부 어디에도 A1을 들이지 않는다. 번역에 필요한 건 맵 둘뿐이다: 열 key → 열 인덱스, 행 id → 시트 행 번호.

내부 xlsx 왜
Ref(SAME_ROW, c1) B3 (상대) 수식이 놓인 행을 따라간다
Ref(ABSOLUTE, c2, rowId) C$4 (행 고정) 그 행에 묶인 참조는 끌어 복사해도 안 움직여야 한다
Agg(SUM, [c0,c1]) SUM(A$2:A$4, B$2:B$4) 헤더·푸터를 뺀 데이터 구간
AVG AVERAGE 이름이 다른 함수는 이 하나뿐
사라진 행 참조 #REF! 엑셀에도 같은 말이 있다
사라진 열 참조 (번역 포기 → 값) 이미 계산된 값이 cells에 있다

표간 참조는 값으로 굳힌다. 한 표를 한 시트로 내보내므로 ={요약!환율}1은 가리킬 자리가 없다 — 수식으로 쓰면 엑셀에서 #REF!가 된다. 여러 표를 한 통합문서로 묶는 것은 별건이다(어느 표를 함께 담을지가 새 질문이다: 노트 단위인가 참조 그래프 단위인가).

담는 것: 헤더(열 label) · 값(숫자로 읽히면 숫자 셀) · 수식(살아 있는 A1) · 셀 배경·정렬 · 열 너비 · 병합 · 푸터 요약(수식으로 — 숫자로 굳히면 파일에서 행을 고쳤을 때 요약만 옛 값으로 남는다). setForceFormulaRecalculation(true)로 열자마자 계산되게 한다.

배경색은 화면의 --cell-bg-*(oklch)를 sRGB로 환산해 굳힌다. xlsx엔 테마가 없어 라이트 값을 쓴다 — 근사색을 눈으로 고르면 화면과 파일이 달라져 사람이 둘을 오가며 확인하게 된다.

API: GET /api/datasets/{id}/export?format=xlsx → ResponseEntity<Resource>. 원장 내보내기(#1268)와 같이 성공 봉투를 쓰지 않는다 — 봉투에 담으면 브라우저가 파일로 저장하지 못한다. 파일 이름은 표 이름에서 나오며 서버가 정해 Content-Disposition에 싣는다.

CORS: exposeHeaders가 없으면 이름이 사라진다. orino.dev와 api.orino.dev는 서로 다른 오리진이고, 브라우저는 CORS 응답에서 안전 목록 밖 헤더를 JS에 숨긴다. 게이트웨이 corsPolicy.exposeHeaders에 Content-Disposition을 넣어야 화면이 이름을 읽는다. 로컬은 dev 프록시라 같은 오리진이어서 끝까지 안 드러난다 — 실제 브라우저 E2E(다운로드 이벤트)로만 잡힌다.

(c) xlsx — 가져오기 (#1310)

상태: 완료. 왕복이 닫혔다.

「가져오기엔 매핑 화면이 필요하다」는 틀린 서술이었다. 그건 원장 이관의 사정이다 — 목적지 스키마가 고정(날짜·금액·상호·분류·자산)이라 「이 열이 날짜인가」를 물어야 한다. 표에는 스키마가 없다. 시트가 곧 표고 첫 줄이 곧 열 이름이라 매핑할 대상 자체가 없다.

실제로 없던 것은 가져오기가 아니라 가져올 때 버려지던 것들이었다. 파일 읽기가 FE SheetJS라 수식은 값으로만, 서식·병합·열 너비는 아예 들어오지 않았다. #1268이 BE POI로 정하고 #1308이 그 위에 내보내기를 지었으므로, 읽기를 같은 엔진으로 옮기니 넷이 한꺼번에 살아났다.

FormulaA1Reader가 FormulaA1Writer의 쌍이다. 문법을 다시 만들지 않는다 — 주소만 바꿔 끼워 저장형 문자열로 내놓고, 괄호·우선순위·인자 개수·허용 함수는 기존 FormulaParser가 본다. 문법을 두 벌로 두면 한쪽만 고쳐지는 날이 온다.

xlsx 내부 비고
B3 (수식이 3행에 있음) Ref(SAME_ROW, c1) 자기 행이면 같은 행 — 행이 밀려도 안 깨지는 쪽
C$4 · C4(다른 행) Ref(ABSOLUTE, c2, rowId) 그 행의 id로
SUM(A$2:A$4) (데이터 구간 전체) Agg(SUM, [c0])
AVERAGE AVG
SUM(B2:B10) (부분 범위) 값으로 부분 범위 참조가 우리 모델에 없다((a)에서 RANGE ref 보류)
Sheet2!B2 · 모르는 함수 값으로 모르는 것을 아는 척 옮기면 파일과 다른 뜻이 자리 잡는다

행 id는 행을 만든 뒤에 생긴다 → 2패스. 값으로 먼저 넣어 id를 받고, 그 id 표로 A1을 옮겨 두 번째로 쓴다. 한 번에 하려면 임시 id라는 없는 개념을 만들어야 한다.

옮기지 못한 수식은 값으로 남기고 그 수를 화면이 말한다. 조용히 바꾸면 사람은 수식이 들어온 줄 알고, 나중에 숫자가 안 따라 움직이는 걸 보고서야 안다.

요약줄은 행이 아니라 열 설정으로 되돌린다. 마지막 줄의 비어 있지 않은 칸이 모두 자기 열의 데이터 구간을 집계할 때만 요약으로 읽는다 — 느슨하게 보면 남의 파일의 마지막 줄을 삼켜 행 하나가 사라진다.

색은 팔레트 토큰에 정확히 맞을 때만 옮긴다. 우리 모델엔 임의 색이 없어서, 가까운 색으로 끌어다 붙이면 원본과 다른 색을 원본인 척 보여주게 된다.

정렬은 파일이 실제로 정한 경우만 읽는다. POI는 안 정한 셀에도 기본값(가로 GENERAL · 세로 BOTTOM)을 돌려주므로, 값만 보면 「정한 적 없음」과 「아래 정렬로 정함」이 구분되지 않는다 — 구분하지 못하면 서식이 없던 표가 전부 아래 정렬로 들어온다. 원본 xml의 CTXf.isSetAlignment()로 본다.

API: POST /api/datasets/import/analyze → 시트 목록·미리보기, POST /api/datasets/import → 표 생성. 원장은 analyze → preview → execute 3단이지만 표는 매핑 단계가 없어 2단이다.

곁다리: 파싱이 BE로 가면서 SheetJS(xlsx)가 사라졌다. NoteTreeSidebar 청크가 460KB → 126KB(−73%)로 줄었다 — 노트 화면을 여는 사람은 가져오기를 쓰지 않아도 그걸 받고 있었다.

완료 판정은 왕복이다: 내보낸 파일을 도로 가져오면 값·수식·서식·병합·요약이 모두 제자리다. 어느 하나가 새면 그 자리에서 드러난다.

남은 것: 기존 표에 덮어쓰기·이어붙이기. 그때 비로소 「이 시트 열이 우리 어느 열인가」가 생기고 매핑 화면과 충돌 처리가 필요해진다 — 원장 이관과 같은 문제다.

Clone this wiki locally