# 기능별 색인

> **용도**: "이 기능 어디있어?", "비슷한 기능 찾아줘"
> **검색 팁**: Ctrl+F로 기능명, 키워드 검색

---

## 렌더링

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 그리드 렌더링 | PopRenderer.tsx | `PopRenderer` | CSS Grid 기반 v5 렌더링 |
| 격자 셀 렌더링 | PopRenderer.tsx | `gridCells` (useMemo) | 12x20 = 240개 DOM 셀 |
| 위치 변환 | gridUtils.ts | `convertPositionToMode()` | 12칸 → 4/6/8칸 변환 |
| 모드 감지 | pop-layout.ts | `detectGridMode()` | 뷰포트 너비로 모드 판별 |
| 컴포넌트 스타일 | PopRenderer.tsx | `convertPosition()` | 그리드 좌표 → CSS |
| **실제 컴포넌트 렌더링** | PopRenderer.tsx | `renderActualComponent()` | 레지스트리에서 실제 컴포넌트 조회 후 렌더링 (뷰어 모드) |
| **디자인모드 실제 렌더링** | PopRenderer.tsx | `ComponentContent` (디자인 분기) | 디자인 모드에서도 ActualComp로 실제 데이터 렌더링, pointer-events-none |
| **레지스트리 초기화** | page.tsx (뷰어) | `import "@/lib/registry/pop-components"` | 뷰어에서 컴포넌트 레지스트리 초기화 (side-effect import) |

## 그리드 가이드

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 격자 셀 | PopRenderer.tsx | `gridCells` | CSS Grid 기반 격자선 (동적 행 수) |
| 열 라벨 | PopCanvas.tsx | `gridLabels.columns` | 1~12 표시 |
| 행 라벨 | PopCanvas.tsx | `gridLabels.rows` | 동적 계산 (dynamicCanvasHeight 기반) |
| 토글 | PopCanvas.tsx | `showGridGuide` 상태 | 격자 ON/OFF |

## 세로 자동 확장

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 동적 높이 | PopCanvas.tsx | `dynamicCanvasHeight` | 컴포넌트 배치 기반 자동 계산 |
| 최소 높이 | PopCanvas.tsx | `MIN_CANVAS_HEIGHT` | 600px 보장 |
| 여유 행 | PopCanvas.tsx | `CANVAS_EXTRA_ROWS` | 항상 3행 추가 |
| 격자 행 수 | PopRenderer.tsx | `gridCells` | maxRowEnd + 5 동적 계산 |

## 드래그 앤 드롭

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 드롭 영역 | PopCanvas.tsx | `useDrop` | 캔버스에 컴포넌트 드롭 |
| 좌표 계산 | gridUtils.ts | `mouseToGridPosition()` | 마우스 → 그리드 좌표 |
| 빈 위치 찾기 | gridUtils.ts | `findNextEmptyPosition()` | 자동 배치 |
| DnD 타입 정의 | PopCanvas.tsx | `DND_ITEM_TYPES` | 인라인 정의 |

## 편집

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 위치 편집 | ComponentEditorPanel.tsx | position 탭 | col, row 수정 |
| 크기 편집 | ComponentEditorPanel.tsx | position 탭 | colSpan, rowSpan 수정 |
| 라벨 편집 | ComponentEditorPanel.tsx | settings 탭 | 컴포넌트 라벨 |
| 표시/숨김 | ComponentEditorPanel.tsx | visibility 탭 | 모드별 표시 |

## 설정 패널

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 속성 편집 탭 | ComponentEditorPanel.tsx | `Tabs` | 위치/설정/표시/데이터 4탭 (min-h-0 스크롤 지원) |
| **배치 컴포넌트 목록** | ComponentEditorPanel.tsx | 위치 탭 내부 | 그리드에 배치된 컴포넌트 리스트 + 클릭 선택 연동 |

## 레이아웃 관리

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 컴포넌트 추가 | pop-layout.ts | `addComponentToV5Layout()` | v5에 컴포넌트 추가 |
| 빈 레이아웃 | pop-layout.ts | `createEmptyPopLayoutV5()` | 초기 레이아웃 생성 |
| 타입 가드 | pop-layout.ts | `isV5Layout()` | v5 여부 확인 |

## 상태 관리

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 레이아웃 상태 | PopDesigner.tsx | `useState<PopLayoutDataV5>` | 메인 레이아웃 |
| 히스토리 | PopDesigner.tsx | `history[]`, `historyIndex` | Undo/Redo |
| 선택 상태 | PopDesigner.tsx | `selectedComponentId` | 현재 선택 |
| 모드 상태 | PopDesigner.tsx | `currentMode` | 그리드 모드 |

## 저장/로드

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 레이아웃 로드 | PopDesigner.tsx | `useEffect` | 화면 로드 시 |
| 레이아웃 저장 | PopDesigner.tsx | `handleSave()` | 저장 버튼 |
| API 호출 | screen.ts (lib/api) | `screenApi.saveLayoutPop()` | 백엔드 통신 |

## 뷰포트/줌

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 프리셋 전환 | PopCanvas.tsx | `VIEWPORT_PRESETS` | 4개 모드 (width만, height 제거) |
| 줌 컨트롤 | PopCanvas.tsx | `canvasScale` | 30%~150% |
| 패닝 | PopCanvas.tsx | Space + 드래그 | 캔버스 이동 |
| 모드 감지 | pop-layout.ts | `detectGridMode()` | 너비 기반 모드 판별 |

## 브레이크포인트

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 그리드 설정 | pop-layout.ts | `GRID_BREAKPOINTS` | 모드별 칸 수, gap, padding |
| 모드 감지 | pop-layout.ts | `detectGridMode()` | viewportWidth → GridMode |
| 훅 연동 | useDeviceOrientation.ts | `BREAKPOINTS.TABLET_MIN` | 768px (태블릿 경계) |

## 자동 줄바꿈/검토

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 자동 배치 | gridUtils.ts | `convertAndResolvePositions()` | col > maxCol → 맨 아래 배치 |
| 검토 필요 판별 | gridUtils.ts | `needsReview()` | 오버라이드 없으면 true |
| 검토 패널 | PopCanvas.tsx | `ReviewPanel` | 검토 필요 컴포넌트 목록 |

---

## pop-dashboard

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| **메인 컴포넌트** | PopDashboardComponent.tsx | `PopDashboardComponent` | 뷰어용 대시보드 렌더링, Promise.allSettled 병렬 로딩 |
| **디자이너 미리보기** | PopDashboardPreview.tsx | `PopDashboardPreviewComponent` | 더미 데이터 기반 미리보기 |
| **설정 패널** | PopDashboardConfig.tsx | `PopDashboardConfigPanel` | 3탭 (기본/아이템/페이지) |
| **레지스트리 등록** | pop-dashboard/index.tsx | `PopComponentRegistry.registerComponent()` | 컴포넌트 등록 엔트리 |
| **마이그레이션** | PopDashboardComponent.tsx | `migrateConfig()` | 레거시 config -> pages 기반으로 런타임 변환 |
| **페이지 편집기** | PopDashboardConfig.tsx | `PageEditor` | 페이지별 독립 그리드 레이아웃 편집 UI |

### 서브타입 (items/)

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| KPI 카드 | items/KpiCard.tsx | `KpiCardComponent` | 숫자+단위+증감, Container Query 반응형 |
| 차트 | items/ChartItem.tsx | `ChartItemComponent` | Recharts (bar/pie/line) |
| 게이지 | items/GaugeItem.tsx | `GaugeItemComponent` | SVG 반원형 게이지 |
| 통계 카드 | items/StatCard.tsx | `StatCardComponent` | 카테고리별 건수 |

### 표시 모드 (modes/)

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 좌우 버튼 | modes/ArrowsMode.tsx | `ArrowsModeComponent` | 좌우 화살표 + 인디케이터 (콘텐츠 위 오버레이) |
| 자동 슬라이드 | modes/AutoSlideMode.tsx | `AutoSlideModeComponent` | 자동 전환 + 터치 일시정지 + 인디케이터 오버레이 |
| 그리드 | modes/GridMode.tsx | `GridModeComponent` | CSS Grid + @container 셀 |
| 스크롤 | modes/ScrollMode.tsx | `ScrollModeComponent` | scroll-snap 가로 스크롤 |

### 유틸리티 (utils/)

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| 수식 계산 | utils/formula.ts | `evaluateFormula()` | 재귀 하강 파서 (eval 미사용) |
| 수식 포맷 | utils/formula.ts | `formatFormulaResult()` | value/fraction/percent/ratio |
| 수식 검증 | utils/formula.ts | `validateExpression()` | 변수 ID 유효성 검사 |
| 숫자 축약 | utils/formula.ts | `abbreviateNumber()` | 1.2만, 1.2억 등 |
| **데이터 검증** | utils/dataFetcher.ts | `validateDataSourceConfig()` | 테이블/컬럼/조인 미완료 시 SQL 차단 |
| 집계 데이터 | utils/dataFetcher.ts | `fetchAggregatedData()` | @INFRA-EXTRACT API 호출 (validate 포함) |
| SQL 생성 | utils/dataFetcher.ts | `buildAggregationSQL()` | DataSourceConfig -> SQL (COUNT(*) 자동 처리) |
| WHERE 생성 | utils/dataFetcher.ts | `buildWhereClause()` | 필터 조건 -> WHERE (빈 컬럼 무시) |
| 테이블 목록 | utils/dataFetcher.ts | `fetchTableList()` | 설정 패널용 |
| 컬럼 목록 | utils/dataFetcher.ts | `fetchTableColumns()` | tableManagementApi 우선, dashboardApi 폴백 |
| **숫자 변환** | utils/dataFetcher.ts | `fetchAggregatedData()` 내부 | PostgreSQL bigint 문자열 -> Number() 변환 (PieChart 필수) |

### 타입 (types.ts에 추가)

| 타입 | 용도 |
|------|------|
| `DataSourceConfig` | 데이터 소스 설정 (Phase 0 공통) |
| `ColumnBinding` | 컬럼 바인딩 (Phase 0 공통) |
| `JoinConfig` | 테이블 조인 (Phase 0 공통) |
| `PopActionConfig` | 액션 설정 (Phase 0 공통) |
| `PopDashboardConfig` | 대시보드 전체 설정 |
| `DashboardItem` | 개별 아이템 설정 |
| `DashboardCell` | 그리드 모드 셀 |
| `DashboardPage` | 페이지(슬라이드) - 독립 그리드 레이아웃 (id, label, gridColumns, gridRows, gridCells) |
| `FormulaConfig` | 계산식 설정 |
| `ItemVisibility` | 아이템 내 요소별 보이기/숨기기 |
| `StatCategory` | 통계 카드 카테고리 (label, filter, color) |
| `GaugeConfig` | 게이지 설정 (min, max, target, colorRanges) |
| `KpiCardConfig` | KPI 카드 설정 (unit, colorRanges, showTrend, trendPeriod) |
| `ChartItemConfig` | 차트 설정 (chartType, xAxisColumn, yAxisColumn, colors) |

### 설정 패널 UI 요소 (PopDashboardConfig.tsx)

| 기능 | 컴포넌트/위치 | 설명 |
|------|-------------|------|
| groupBy(X축) Combobox | DataSourceEditor 내부 | 집계 활성 시 X축 카테고리 컬럼 선택 |
| 차트 축 설정 | ItemEditor > Chart 모드 | xAxisColumn, yAxisColumn 입력 |
| 통계 카테고리 편집 | ItemEditor > StatCard 모드 | 카테고리별 라벨/필터/색상 인라인 편집 |
| 표시요소(Visibility) | ItemEditor 하단 | 라벨/값/단위/증감율/보조라벨/목표값 체크박스 |

---

## 파일별 주요 기능

| 파일 | 핵심 기능 |
|------|----------|
| PopDesigner.tsx | 레이아웃 로드/저장, 컴포넌트 CRUD, 히스토리 |
| PopCanvas.tsx | DnD, 줌, 패닝, 모드 전환, 행/열 라벨, 격자 토글 |
| PopRenderer.tsx | CSS Grid 렌더링, 격자 셀, 위치 변환, 컴포넌트 표시 |
| ComponentEditorPanel.tsx | 속성 편집 (위치, 크기, 설정, 표시) |
| ComponentPalette.tsx | 컴포넌트 팔레트 (드래그 가능한 컴포넌트 목록) |
| pop-layout.ts | 타입 정의, 유틸리티 함수, 상수 |
| gridUtils.ts | 좌표 계산, 겹침 감지, 자동 배치 |
| pop-components/types.ts | Phase 0 공통 + 대시보드 전용 타입 |
| pop-dashboard/PopDashboardComponent.tsx | 대시보드 뷰어 메인 컴포넌트 |
| pop-dashboard/PopDashboardConfig.tsx | 대시보드 설정 패널 (3탭) |
| pop-dashboard/utils/formula.ts | 수식 파싱/계산/검증/숫자 축약 |
| pop-dashboard/utils/dataFetcher.ts | @INFRA-EXTRACT 데이터 API 호출 |

---

## 공통 훅 (hooks/pop/)

| 기능 | 파일 | 함수/컴포넌트 | 설명 |
|------|------|--------------|------|
| **이벤트 버스** | hooks/pop/usePopEvent.ts | `usePopEvent(screenId)` | screenId 기반 격리된 이벤트 통신 |
| 이벤트 발행 | hooks/pop/usePopEvent.ts | `publish(eventName, payload)` | 같은 화면 구독자에게 이벤트 전파 |
| 이벤트 구독 | hooks/pop/usePopEvent.ts | `subscribe(eventName, callback)` | 이벤트 구독, unsubscribe 반환 |
| 공유 데이터 조회 | hooks/pop/usePopEvent.ts | `getSharedData(key)` | screenId별 격리된 key-value 조회 |
| 공유 데이터 저장 | hooks/pop/usePopEvent.ts | `setSharedData(key, value)` | screenId별 격리된 key-value 저장 |
| 화면 정리 | hooks/pop/usePopEvent.ts | `cleanupScreen(screenId)` | 리스너 + sharedData 전체 정리 |
| **데이터 CRUD** | hooks/pop/useDataSource.ts | `useDataSource(config)` | DataSourceConfig 기반 DB 통합 훅 |
| 데이터 조회 | hooks/pop/useDataSource.ts | `refetch(options?)` | 필터 오버라이드 가능한 재조회 |
| 데이터 생성 | hooks/pop/useDataSource.ts | `save(record)` | dataApi.createRecord 래핑 |
| 데이터 수정 | hooks/pop/useDataSource.ts | `update(id, record)` | dataApi.updateRecord 래핑 |
| 데이터 삭제 | hooks/pop/useDataSource.ts | `remove(id)` | dataApi.deleteRecord 래핑 |
| SQL 검증 | hooks/pop/popSqlBuilder.ts | `validateDataSourceConfig(config)` | 테이블/컬럼/조인 미완료 시 에러 반환 |
| SQL 생성 | hooks/pop/popSqlBuilder.ts | `buildAggregationSQL(config)` | DataSourceConfig -> SELECT SQL |
| 배럴 파일 | hooks/pop/index.ts | re-export | `@/hooks/pop`으로 import 가능 |

### 공통 훅 타입

| 타입 | 파일 | 용도 |
|------|------|------|
| `DataSourceResult` | hooks/pop/useDataSource.ts | 조회 결과 (rows, value, total) |
| `MutationResult` | hooks/pop/useDataSource.ts | CRUD 결과 (success, data, error) |
| `EventCallback` | hooks/pop/usePopEvent.ts | 이벤트 콜백 타입 |

---

*새 기능 추가 시 해당 카테고리 테이블에 행 추가*