# GooseFarm Ledger - TanStack Table 마이그레이션

**날짜**: 2025-11-04
**작성자**: admin
**관련 파일**: `goosefarminvesting/frontend/src/components/ledger/LedgerClient.tsx`

---

## 문제 상황

### 1. Tabulator 라이브러리 렌더링 실패
- **현상**: Supabase에서 100개 데이터 정상 로드되나 화면 표시 안됨
- **원인**: Next.js 14 App Router의 SSR/RSC와 Tabulator의 클라이언트 렌더링 타이밍 충돌
- **확인**: HTML 소스에는 데이터 존재, but Tabulator 초기화 실패

### 2. CRUD 기능 요구사항
- 엑셀처럼 웹에서 데이터 편집 필요
- 셀 인라인 편집, 행 추가/삭제
- TailwindCSS 디자인 시스템 통일성 유지

---

## 해결 방안

### 1. TanStack Table 선택 근거
- Headless UI (완전 커스텀 가능)
- 경량 (~15KB vs Tabulator ~500KB)
- TypeScript 완벽 지원
- React 18+ 최적화
- TailwindCSS와 자연스러운 통합

### 2. 구현 내용

**패키지 설치**:
```bash
npm install @tanstack/react-table
```

**주요 변경사항** (LedgerClient.tsx):
- Tabulator 제거, useReactTable 훅 사용
- EditableCell 컴포넌트 구현 (더블클릭 편집)
- 행 추가/삭제 핸들러 구현
- 숫자 포맷팅 (천단위 콤마)

**핵심 코드 구조**:
- LedgerClient.tsx:29-90: EditableCell 컴포넌트 (인라인 편집)
- LedgerClient.tsx:92-173: columns 정의 및 테이블 렌더링
- LedgerClient.tsx:106-110: handleDeleteRow (확인 다이얼로그)
- LedgerClient.tsx:112-126: handleAddRow (임시 ID 생성)

---

## 구현 완료

**커밋**: (frontend 저장소, 커밋 대기)
**배포**: Next.js dev 서버 실행 중 (localhost:3001)
**접속**: https://ro-being.com/goosefarm/ledger

---

## 기능 명세

### 인라인 편집
- 더블클릭으로 편집 모드 전환
- Enter: 저장, Escape: 취소
- input type 지원 (text, number, date)
- 포커스 아웃 시 자동 저장

### 행 관리
- "+ 행 추가" 버튼: 새 행 맨 위 추가
- "삭제" 버튼: confirm 다이얼로그 후 삭제
- 클라이언트 상태 관리 (useState)

### UI/UX
- hover: 파란색 배경 (편집 가능 표시)
- 편집 중: 파란색 테두리 input
- sticky 헤더 (스크롤 시 고정)
- 최대 높이 70vh (오버플로우 스크롤)

---

## 교훈

### 1. SSR과 클라이언트 라이브러리 호환성
- Next.js App Router는 기본 SSR
- 클라이언트 전용 라이브러리는 동적 임포트 필요
- Tabulator는 DOM 직접 조작으로 React와 충돌 가능성 높음
- 교훈: React 생태계에 최적화된 headless 라이브러리 우선 선택

### 2. 디버깅 시 데이터 플로우 확인
- SSR로 전달된 데이터 (HTML 소스)
- 클라이언트 컴포넌트로 props 전달 (100개 확인)
- 렌더링 실패는 컴포넌트 로직 문제
- 교훈: 임시로 JSON 출력하여 데이터 전달 검증

### 3. 라이브러리 선택 기준
- 번들 크기 (성능)
- TypeScript 지원 (타입 안전성)
- 프레임워크 호환성 (Next.js 14)
- 커스터마이징 자유도 (디자인 시스템)
- 교훈: 즉시 사용 가능한 무거운 라이브러리보다 headless 라이브러리가 장기적으로 유리

### 4. API 연동 미구현 상태
- 현재는 클라이언트 상태만 변경
- TODO 주석으로 API 호출 위치 표시
- 다음 단계: POST/PUT/DELETE 엔드포인트 구현 필요