Repository navigation
Data Grid Block
범위: 데이터 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 참고.
Data-Import v1은 엑셀·CSV를 native Tiptap 표로 삽입한다. 이 방식의 한계:
-
성능: ProseMirror/Tiptap 표는 상태 업데이트마다 재렌더 → 수천 셀부터 입력이 버벅인다(
prosemirror-tables엔 가상화 없음). - 저장/전송: 표가 노트 content(단일 JSON 문서) 안에 통째로 들어가 매번 통째 저장·로드된다.
- 한계: 실용상 수 MB. 그래서 v1은 행/열 상한으로 컷했다.
native 표 커맨드로는 "인라인 편집 + 대용량"을 동시에 못 한다(물리적 한계). 업계 정석(Notion DB 블록, 가상화 데이터 그리드)은 대용량 표 데이터를 문서에서 분리하고 가상화 렌더한다.
노트 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에 벌크 업로드
member (1) ──< (N) dataset (1) ──< (N) dataset_row
│ └ row_index · cells(JSON 문자열 배열)
└ columns(JSON) · row_count
| 컬럼 | 타입 | 설명 |
|---|---|---|
| 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) |
| 컬럼 | 타입 | 설명 |
|---|---|---|
| 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 테이블).
| 컬럼 | 타입 | 설명 |
|---|---|---|
| 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과 같은 처리).
모두 소유자(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) |
- 페이지 크기: 기본
limit100, 최대 500. 벌크 청크: 요청당 최대 ~2,000행 권장. - 인가:
getOwnedDataset(memberId, id)— 타인 404.
-
atom block leaf 노드,
attrs: { datasetId }. content엔 이 노드만(데이터 없음). - ReactNodeView로 그리드 렌더. 블록 선택·삭제는 ProseMirror(블록 통째). 삭제 감지 시 dataset 정리(childPage 삭제 감지 패턴 재사용).
- TanStack Table: 헤드리스 테이블 로직(열/셀 모델). TanStack Virtual: 행 가상화(보이는 행 + 버퍼만 DOM).
-
지연 로드: 가상화 스크롤 위치 → 필요한
row_index범위를GET /rows?offset&limit로 페이지 fetch + 캐시(react-query 무한/윈도우). 미로드 행은 스켈레톤. -
편집(자체 구현): 셀 클릭 → inline input/contentEditable, 확정 시 해당 행
PATCH(디바운스). 복사/붙여넣기 = clipboard 이벤트 → 대상 셀 범위 채우고 영향 행 배치 patch. 행/열 추가·삭제 = 툴바 → API. -
열 헤더: dataset
columns.
행·세로병합 오버레이·열 선택 핸들 바는 모두 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 폭에 기여하지 않는다. 그래서 열 정의에서 폭을 직접 계산한다.
단일 셀을 선택하면 그 셀 위에 빈 <input>을 미리 띄운다 — 선택 직후 글자를 치면 곧바로 덮어쓰기가 되고 한글 IME 조합이 끊기지 않게 하는 장치다. 그런데 터치에선 이 입력창이 포커스되는 순간 가상 키보드가 뜬다. 표를 잡으려는 첫 터치가 곧 셀 선택이라, 열이 넘치는 표를 좌우로 스크롤할 수 없었다.
pointerdown의 e.pointerType으로 갈라 처리한다.
| 마우스·펜 | 터치 | |
|---|---|---|
| 1번째 | 선택 + 활성 입력창(타이핑 대기) | 선택만 — 입력창 없음 → 키보드 안 뜸, 스크롤 가능 |
| 같은 셀 다시 | (변화 없음) | 편집 진입 — 이때만 키보드 |
| 편집 | 더블클릭 | 같은 셀 재탭 |
| 드래그 | 범위 선택 | 범위 선택 안 함 — 스크롤에 양보 |
- 더블탭을 쓰지 않는 이유: 브라우저 확대 제스처와 겹쳐 모바일에서 신뢰할 수 없다. "선택된 셀 재탭"은 Excel·Sheets 모바일과 같은 관례다.
- 터치 드래그를 범위 선택으로 잡지 않는 이유: 같은 제스처를 스크롤과 나눠 쓸 수 없고, 열이 넘치는 표에선 스크롤이 우선이다.
- 물리 키보드 keydown이 오면 터치 모드를 풀어 활성 입력창을 되살린다(외장 키보드 태블릿).
- 화면 폭(
max-width)이 아니라 포인터 종류로 가르는 이유: 좁은 창의 데스크탑은 마우스로 쓰고, 넓은 태블릿도 손가락으로 쓴다. 문제의 원인은 화면 크기가 아니라 입력 방식이다.
- 노트 자동저장과 분리: 그리드 편집은 dataset API로만 나간다(노트 content는 datasetId만 있어 안 바뀜).
- 낙관적 업데이트 + 실패 롤백. 동시 편집은 v1 범위 밖(단일 사용자 가정).
기존 Import 다이얼로그의 파싱(SheetJS)·미리보기는 그대로. [표로 가져오기]에서만 분기:
파싱된 2D(정규화) → cell 수 / 예상 직렬화 크기 계산
├─ 임계치 이하(예: ≤ 2,000셀) → 기존 native Tiptap 표 삽입 (현행)
└─ 임계치 초과 → ① POST /datasets(columns)
② POST rows:bulk (청크 반복)
③ datasetTable{datasetId} 노드 삽입
- 임계치는 상수(조정 가능). 초과 시 미리보기 하단에 "대용량 표로 저장됩니다(그리드 블록)" 안내.
- 파싱은 클라이언트 유지(BE 파일 업로드 불필요).
- 가상화로 10만 행도 스크롤 반응 유지(보이는 ~수십 행만 DOM).
- dataset 셀 상한(예: 100만 셀)·페이지/청크 크기로 폭주 방지.
- 임의 위치 대량 삽입은 재인덱싱 비용 — gap index로 완화(§10).
- 소형 표: 기존 native Tiptap 표 유지(가볍고 마크다운 친화). 기능·스타일 무변경.
- 대형: dataset 블록. 필요 시 "표 → 데이터셋 변환"(기존 native 표를 dataset으로 승격) 별도 액션(선택, 후순위).
- 기존 노트/데이터 마이그레이션 불필요(신규 경로만 추가).
- 사용자가 5만 행 엑셀을 노트에 Import → 임계치 초과 → 그리드 블록 생성, 커서 위치에 삽입, 즉시 스크롤·편집 가능.
- 그리드에서 셀 수정/행 추가 → dataset patch로 저장(노트는 안 건드림), 새로고침 후 유지.
- 블록 삭제 → dataset 정리.
- 그리드 = 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).
-
BE —✅dataset/dataset_row스키마(Liquibase) + CRUD + 페이지 조회 +rows:bulk+ 행 patch -
FE —✅datasetTable노드 + NodeView + TanStack Table/Virtual 그리드 + 지연 로드/편집/patch -
FE — Import 임계치 분기→ 폐기. native 표를 제거하고 dataset으로 단일화(#787·#789·#791) -
열 조작 확장✅ — rename(#792) · add(#793) · delete(#794) · reorder(#795). 저장 모델을 key 맵으로 전환(#797)해 전부 O(1) - 선택 — 행 gap/fractional index(#778, 성능·실측 후)
- 설계 완료, 구현 대기 — 수식 지원(Epic #799) · §12
-
열 속성·셀 서식✅ — 열 너비(#830) · 열 정렬(#828) =columns[]속성 · 셀 배경색(#831) · 셀 정렬 override(#828) =dataset_cell_stylesparse 테이블(§3). 값 스키마 무변경
상태: 설계 완료, 구현 대기. 이 문서의 이전 판은 *"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로 남는다
상태: 착수. 표 엔진을 "엑셀처럼" 확장한다. 큰 방향은 확정 — BE 엔진 확장(클라 엔진으로 갈아타지 않음). §12가 깐 "서버 권위 · 주소 바인딩 · sparse 저장" 위에 그대로 쌓는다.
넷은 독립이 아니라 수식 엔진을 뿌리로 쌓인다: 반응성은 "수식 재계산을 빠르게", (a) 자동합계·채우기핸들은 "수식을 생성하는 UX", (c) xlsx는 "수식·서식을 파일로 직렬화". 그래서 (b) 수식 확장 → 반응성 → (a) UX 증분 → (c) xlsx 순.
탐구할 설계가 아니라 회귀 금지 가드레일이다. orino 내부 수식은 이미 열 key + 행 id 주소를 쓴다(§12) — 열 이름을 바꾸거나 행이 밀려도 안 깨지는 게 핵심 강점. 엑셀 A1(그리드 좌표)로 회귀하면 이 내성을 잃는다. 엑셀 A1 문법은 xlsx import/export 경계((c))에서만 우리 주소 모델과 상호 번역한다. 새 함수(IF·SUMIF 등) 추가는 참조 의미를 건드리지 않는다 — 그래서 이 결정은 (b)를 블록하지 않는다.
계산의 SSOT는 BE 엔진. 클라이언트 엔진(HyperFormula 등)으로 통째 교체하지 않는다 — BE에 파서·평가기·의존성 그래프가 이미 있어 엔진을 두 벌로 중복시키는 함정이 된다. 서버 권위의 유일한 대가는 "입력→API 왕복→결과"인데, 반응성이 필요하면 BE를 권위로 두고 FE에 BE와 동일 함수 집합만 구현한 경량 평가기를 얹되, 양쪽을 같은 conformance(골든) 스위트로 교차검증한다. 골든 스위트가 두 구현의 SSOT. → 그래서 골든 하네스를 (b)의 워킹 스켈레톤(#893)부터 심는다: 나중 리스크를 지금 공짜로 앞당겨 없앤다.
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으로 안전하고, 골든 하네스만 세운다.
-
워킹 스켈레톤(#893) —
FormulaNode.Call스칼라 함수 노드 +ABS끝까지 관통 +FormulaConformanceTest골든 하네스 - IF + 비교연산자 + AND/OR/NOT — 위 값타입 스펙 적용. 진짜 언락 지점
- SUMIF/COUNTIF — 2+집계 조합. 이 시점에 "환율 IF 자동환산 · 카테고리 SUMIF 합계" 예시가 orino에서 그대로 돈다
- 반응성 → (a) UX → (c) xlsx (Epic #892)
상태: 내보내기 완료. 가져오기는 미착수.
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(다운로드 이벤트)로만 잡힌다.
상태: 완료. 왕복이 닫혔다.
「가져오기엔 매핑 화면이 필요하다」는 틀린 서술이었다. 그건 원장 이관의 사정이다 — 목적지 스키마가 고정(날짜·금액·상호·분류·자산)이라 「이 열이 날짜인가」를 물어야 한다. 표에는 스키마가 없다. 시트가 곧 표고 첫 줄이 곧 열 이름이라 매핑할 대상 자체가 없다.
실제로 없던 것은 가져오기가 아니라 가져올 때 버려지던 것들이었다. 파일 읽기가 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%)로 줄었다 — 노트 화면을 여는 사람은 가져오기를 쓰지 않아도 그걸 받고 있었다.
완료 판정은 왕복이다: 내보낸 파일을 도로 가져오면 값·수식·서식·병합·요약이 모두 제자리다. 어느 하나가 새면 그 자리에서 드러난다.
남은 것: 기존 표에 덮어쓰기·이어붙이기. 그때 비로소 「이 시트 열이 우리 어느 열인가」가 생기고 매핑 화면과 충돌 처리가 필요해진다 — 원장 이관과 같은 문제다.