13 KiB
13 KiB
기능별 색인
용도: "이 기능 어디있어?", "비슷한 기능 찾아줘" 검색 팁: 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 | 이벤트 콜백 타입 |
새 기능 추가 시 해당 카테고리 테이블에 행 추가