# 현재 상태

> **마지막 업데이트**: 2026-02-12
> **담당**: POP 화면 디자이너

---

## 진행 상태

| 단계 | 상태 | 설명 |
|------|------|------|
| v5 타입 정의 | 완료 | `pop-layout.ts` |
| v5 렌더러 | 완료 | `PopRenderer.tsx` |
| v5 캔버스 | 완료 | `PopCanvas.tsx` |
| v5 편집 패널 | 완료 | `ComponentEditorPanel.tsx` |
| v5 유틸리티 | 완료 | `gridUtils.ts` |
| 레거시 삭제 | 완료 | v1~v4 코드, 데이터 |
| 문서 정리 | 완료 | popdocs v5 기준 재정비 |
| 컴포넌트 팔레트 | 완료 | `ComponentPalette.tsx` |
| 드래그앤드롭 | 완료 | 스케일 보정, DND 상수 통합 |
| 그리드 가이드 재설계 | 완료 | CSS Grid 기반 통합 |
| 모드별 오버라이드 | 완료 | 위치/크기 모드별 저장 |
| 화면 밖 컴포넌트 | 완료 | 오른쪽 패널 배치, 드래그로 복원 |
| 숨김 기능 | 완료 | 모드별 숨김/숨김해제 |
| 리사이즈 겹침 검사 | 완료 | 실시간 겹침 방지 |
| Gap 프리셋 | 완료 | 좁게/보통/넓게 간격 조정 |
| 자동 줄바꿈 | 완료 | col > maxCol -> 맨 아래 배치 |
| 검토 필요 시스템 | 완료 | 오버라이드 없으면 검토 알림 |
| 브레이크포인트 재설계 | 완료 | 기기 기반 (479/767/1023px) |
| 세로 자동 확장 | 완료 | 캔버스 높이 동적 계산 |
| 그리드 셀 크기 강제 고정 | 완료 | gridTemplateRows로 행 높이 고정, overflow-hidden |
| origin/main 병합 | 완료 | ksh-v2-work-merge-test에서 충돌 3건 해결 |
| **컴포넌트 정의서 v8.0** | **완료** | 9개 컴포넌트 + 헌법 9조 + 모달 설계 + 호환성 검증 |
| **pop-dashboard 상세 설계** | **완료** | 멀티 아이템 + 4 서브타입 + 4 표시 모드 + 계산식 + 백엔드 호환 |
| **pop-dashboard 구현 계획서** | **완료** | 17단계 구현 순서 + 충돌 검사 + 정의-사용 매핑 + 함정 경고 |
| **pop-dashboard 코딩** | **완료** | 15개 신규 파일 + 3개 수정, 17단계 전체 구현 |
| **pop-dashboard 검수** | **완료** | 린트 0, 중복 0, 미사용 import 1건 수정 |
| **pop-dashboard 팔레트 등록** | **완료** | PopComponentType + PALETTE_ITEMS + DEFAULT_SIZE + LABELS 4곳 수정 |
| **POP 뷰어 컴포넌트 렌더링** | **완료** | 레지스트리 초기화 import + renderActualComponent 수정 |
| **POP 뷰어 스크롤 수정** | **완료** | overflow-hidden 제거, overflow-auto 공통 적용, min-h-full 추가 |
| **pop-dashboard 페이지 구조 재설계** | **완료** | DashboardPage 도입, migrateConfig, "페이지" 탭, PageEditor |
| **아이템 라벨 인라인 편집** | **완료** | ItemEditor 헤더에서 직접 라벨 편집 가능 |
| **설정 탭 세로 스크롤 수정** | **완료** | ComponentEditorPanel Tabs/TabsContent에 min-h-0 추가 |
| **대시보드 아이템 모드 설정 UI 보강** | **완료** | groupBy Combobox, 차트 축 입력, 통계 카테고리 편집기 |
| **SQL 빌더 방어 로직** | **완료** | validateDataSourceConfig, 빈 컬럼 방어, COUNT(*) 처리 |
| **대상 컬럼 조회 안 됨 수정** | **완료** | fetchTableColumns API 우선순위 변경 (tableManagementApi 우선) |
| **그리드 2열이 1열로 렌더링** | **완료** | MIN_CELL_WIDTH 160 -> 80 |
| **라벨/단위 잘림 수정** | **완료** | 4개 아이템 컴포넌트에서 truncate/hidden 제거, 폰트/패딩 상향 |
| **useEffect 데이터 리페칭 무한 루프** | **완료** | visibleItems -> visibleItemIds(JSON 문자열)로 의존성 안정화 |
| **파이 차트 미표시 (fetch 실패 + bigint 문자열)** | **완료** | apiClient(axios) 우선 사용 + Number() 변환 |
| **파이 차트 라벨/레전드 없음** | **완료** | Legend 컴포넌트 + custom label 포맷 추가 |
| **gaugeConfig 값 변경 안 됨** | **완료** | 스프레드 연산자 순서 수정 (...기존값 먼저, 새값 나중) |
| **게이지 가로 레이아웃 비율 깨짐** | **완료** | max-w-[200px] 고정 -> h-full w-auto 높이 기반 스케일링 |
| **좌우 버튼/인디케이터 공간 낭비** | **완료** | absolute 오버레이로 변경, 상하 마진 불균형 해소 |
| **KPI/통계 카드 왼쪽 정렬 불일치** | **완료** | items-center (justify-center) 추가로 4개 모드 정렬 통일 |
| **차트 X축/Y축 입력 혼동** | **완료** | 수동 입력 제거, 자동 설정 안내 텍스트 교체 |
| **디자이너 캔버스 헤더 제거 + 실제 데이터 렌더링** | **완료** | PreviewComponent -> ActualComp + pointer-events-none |
| **컴포넌트 목록 UI (위치 탭)** | **완료** | ComponentEditorPanel에 배치된 컴포넌트 리스트 + 선택 연동 |
| **미사용 import (PopComponentType)** | **완료** | COMPONENT_TYPE_LABELS 타입 변경 후 import 정리 누락 수정 |
| **라벨 정렬 + 페이지 미리보기 + 차트 디자인 개선** | **완료** | 라벨 정렬(좌/중/우), Eye 미리보기, CartesianGrid, abbreviateNumber |
| **글자 크기 커스텀 제거 + 반응형 복원** | **완료** | 절대 px 글자 크기 제거, `@container` 반응형 자동 유지 |
| **stale closure (handleUpdateComponent)** | **완료** | `setLayout(prev => ...)` 함수적 업데이트로 수정 |
| **setRenderTick 불필요 이중 렌더링** | **완료** | state + useEffect 삭제 |
| **.next 빌드 캐시 꼬임 (Docker 익명 볼륨)** | **완료** | `docker-compose down -v`로 볼륨 포함 삭제 후 재빌드 |
| **디버그 console.log 잔존 (대시보드)** | **완료** | 8개 전량 제거 |
| **Phase 0: usePopEvent 훅** | **완료** | screenId 기반 이벤트 버스 (publish/subscribe/sharedData) |
| **Phase 0: popSqlBuilder 유틸** | **완료** | dataFetcher.ts에서 SQL 빌더 5개 함수 추출 |
| **Phase 0: useDataSource 훅** | **완료** | DataSourceConfig 기반 CRUD 통합 (조회 분기 + 자동 새로고침) |
| **Phase 0: hooks/pop 배럴 파일** | **완료** | 공통 훅 re-export |

---

## 다음 작업 (우선순위)

### 현재: 대시보드 집계 함수 설정 유효성 검증 강화 (v2 시뮬레이션 검증 완료)

> 팀원 pull 후 대시보드 500 에러 (문자열 컬럼에 SUM 적용)
> 8개 시나리오 시뮬레이션 완료, STEP 7.5 추가 (subType 변경 시 비호환 aggregation 자동 전환)

| 순서 | 작업 | 상태 |
|------|------|------|
| 1 | import + 유틸 상수/함수 6개 | 대기 |
| 2 | DataSourceEditor props에 subType 추가 | 대기 |
| 3 | 집계 함수 Select 동적 생성 (subType별) | 대기 |
| 4 | 집계 함수 변경 시 컬럼 초기화 + groupBy 보존 | 대기 |
| 5 | 대상 컬럼 Combobox 숫자 필터링 | 대기 |
| 6 | chart 모드 groupBy 경고 | 대기 |
| 7 | DataSourceEditor 호출부 subType 전달 | 대기 |
| **7.5** | **subType 변경 시 비호환 aggregation 전환** | **대기** |

수정 파일: `PopDashboardConfig.tsx` 1개만. 상세: `popdocs/PLAN.md` "현재 구현 계획"

### 대기

- 브라우저 확인: 라벨 정렬, 페이지 미리보기, 차트 디자인, 게이지/통계카드
- Phase 2: pop-button 컴포넌트 구현
- Phase 2: pop-icon 검토/개선

### 후속

- Phase 3: pop-table (table-list 서브타입 우선)
- Phase 4: pop-search, pop-field, pop-lookup
- Phase 6: pop-system
- 대시보드 교체: dataFetcher.ts를 useDataSource로 교체 (훅 안정화 후)
- 레거시 삭제: `frontend/components/pop/dashboard/`
- 디자이너-레지스트리 자동 연동 리팩토링 (하드코딩 제거)

---

## 최근 주요 변경 (2026-02-11)

### Phase 0 공통 인프라 구현 (완료)

| 항목 | 내용 |
|------|------|
| usePopEvent | screenId 기반 이벤트 버스 (publish/subscribe/sharedData/cleanupScreen) |
| popSqlBuilder | dataFetcher.ts에서 SQL 빌더 로직 추출 (순수 유틸, 5개 함수) |
| useDataSource | DataSourceConfig 기반 CRUD 통합 (조회 분기 + 자동 새로고침 + 필터 병합) |
| 배럴 파일 | hooks/pop/index.ts - public API re-export |
| 검수 | 린트 0, 중복 0, 시뮬레이션 8시나리오 정상 |
| Git | ksh-button -> ksh-v2-work merge -> origin push |

### 대시보드 스타일 정리 + 페이지 미리보기 + 차트 디자인 개선 (완료)

| 항목 | 내용 |
|------|------|
| 글자 크기 제거 | 절대 px 커스텀 삭제, `@container` 반응형 자동 복원 |
| 라벨 정렬 | 4개 아이템에 좌/중/우 정렬 기능 (값은 항상 가운데) |
| 페이지 미리보기 | Eye 버튼으로 디자이너 캔버스에 특정 페이지 렌더링 |
| 차트 디자인 | CartesianGrid, abbreviateNumber(K/M), 대각선 X축 라벨 |
| stale closure | handleUpdateComponent 함수적 setState로 수정 |
| .next 캐시 | Docker 익명 볼륨 문제 → `down -v` + `--build` 재시작 |

### pop-dashboard 차트/게이지/UI 디자인 개선 (2026-02-10, 완료)

| 항목 | 내용 |
|------|------|
| 차트 데이터 | apiClient(axios) 우선 사용, bigint 문자열 -> 숫자 변환 |
| 파이 차트 UX | Legend + custom label(`name value (percent%)`) 추가 |
| 게이지 설정 | 스프레드 연산자 순서 버그 수정 (min/max/target 변경 가능) |
| 게이지 비율 | 가로 레이아웃에서 높이 기반 SVG 스케일링 |
| 네비게이션 | 좌우 버튼 + 인디케이터 오버레이 디자인 (공간 절약) |
| 카드 정렬 | KPI/통계 카드 가운데 정렬 통일 |
| 차트 설정 | X/Y축 수동 입력 제거, 자동 설정 안내 텍스트 |

### pop-dashboard 아이템 모드 완성 + SQL 방어 + 레이아웃/라벨 수정 (완료)

| 항목 | 내용 |
|------|------|
| 설정 UI 보강 | groupBy(X축) Combobox, 차트 축 입력, 통계 카테고리 편집기 |
| SQL 방어 로직 | validateDataSourceConfig으로 중간 상태 SQL 차단 |
| 그리드 레이아웃 | MIN_CELL_WIDTH 160->80으로 2열 유지 보장 |
| 라벨/단위 잘림 | 4개 아이템에서 truncate/hidden 제거, 폰트/패딩 상향 |
| API 연동 | fetchTableColumns에서 tableManagementApi(axios) 우선 사용 |
| 데이터 리페칭 | useEffect 의존성 visibleItemIds로 안정화 |

### pop-dashboard 페이지(슬라이드) 구조 재설계 (완료)

| 항목 | 내용 |
|------|------|
| 변경 구조 | 평면 아이템 리스트 -> 페이지 단위 독립 그리드 레이아웃 |
| 핵심 타입 | `DashboardPage` (id, label, gridColumns, gridRows, gridCells) |
| 마이그레이션 | `migrateConfig()` - 레거시 config 런타임 변환 (저장 데이터 미변경) |
| UI 변경 | "레이아웃" 탭 -> "페이지" 탭, PageEditor, 인라인 라벨 편집 |
| 버그 수정 | ComponentEditorPanel 스크롤 문제 (Flexbox min-h-0) |

### pop-dashboard 전체 구현 (완료)

| 항목 | 내용 |
|------|------|
| 신규 파일 | 15개 (컴포넌트 4 + 모드 4 + 유틸 2 + 메인 3 + 등록 2) |
| 수정 파일 | 6개 (types.ts, index.ts, pop-text.tsx, pop-layout.ts, ComponentPalette.tsx, PopRenderer.tsx) |
| 서브타입 | kpi-card, chart, gauge, stat-card |
| 표시 모드 | arrows, auto-slide, scroll (grid 독립 모드 폐기 -> 페이지 내부 그리드로 전환) |
| 계산식 | 재귀 하강 파서 (eval 미사용) |
| 데이터 | @INFRA-EXTRACT 직접 API 호출 (훅 대체 예정) |

### POP 컴포넌트 정의서 v8.0 확정

| 항목 | 내용 |
|------|------|
| 컴포넌트 | 9개 확정 (pop-text~pop-system) |
| 헌법 | 9조 (제9조 모달 화면 설계 추가) |
| 공통 인프라 | DataSourceConfig, ColumnBinding, JoinConfig, useDataSource, usePopEvent, PopActionConfig |
| 모달 설계 | 인라인 + 외부 참조 이중 방식 |
| 호환성 검증 | DB/백엔드/프론트 모두 기존 시스템으로 가능 (마이그레이션 불필요) |

### 9개 컴포넌트 요약

| 컴포넌트 | 카테고리 | 한 줄 정의 |
|----------|---------|-----------|
| pop-text | display | 보여주기만 함 (완성) |
| pop-dashboard | display | 여러 집계 아이템을 묶어서 다양한 방식으로 보여줌 |
| pop-table | display | 데이터 목록을 보여주고 편집함 |
| pop-button | action | 누르면 액션 실행 |
| pop-icon | action | 누르면 어딘가로 이동 |
| pop-search | input | 조건을 입력해서 조회/필터링 |
| pop-field | input | 저장할 값을 입력 |
| pop-lookup | input | 모달에서 값을 골라서 반환 |
| pop-system | system | 시스템 설정 통합 (프로필, 테마, 보이기/숨기기) |

---

## 알려진 문제

| 문제 | 상태 | 비고 |
|------|------|------|
| 뷰어에서 실제 컴포넌트 렌더링 안 됨 | **해결됨** | 레지스트리 초기화 import + `renderActualComponent()` 실제 컴포넌트 조회/렌더링으로 교체 |
| 뷰어에서 스크롤 안 됨 (하단 컴포넌트 잘림) | **해결됨** | `overflow-hidden` 제거, `overflow-auto` 공통 적용 |
| datetime 실시간 업데이트 기본값 불일치 | **해결됨** | `isRealtime ?? true`로 기본값 통일 |
| pop-dashboard 팔레트 미노출 | **해결됨** | PopComponentType, PALETTE_ITEMS, DEFAULT_SIZE, LABELS 4곳 수동 등록 |
| 타입 이름 불일치 | 해결됨 | V5 접미사 제거 |
| SVG 격자 좌표 불일치 | 해결됨 | GridGuide 삭제, CSS Grid 통합 |
| 드래그 좌표 계산 오류 | 해결됨 | 스케일 보정 적용 |
| DND 타입 상수 불일치 | 해결됨 | constants/dnd.ts로 통합 |
| 숨김 컴포넌트 드래그 안됨 | 해결됨 | 상태 업데이트 순서 수정 |
| 그리드 범위 초과 에러 | 해결됨 | 드롭 위치 자동 조정 |
| Expected drag drop context | 해결됨 | 뷰어 모드에서 일반 div 렌더링 |
| Gap 프리셋 UI 안 보임 | 해결됨 | 그리드 라벨에 adjustedGap 적용 |
| 화면 밖 컴포넌트 정보 손실 | 해결됨 | 자동 줄바꿈으로 항상 그리드 안에 배치 |
| 뷰어 반응형 모드 불일치 | 해결됨 | detectGridMode() 사용으로 일관성 확보 |
| hiddenComponentIds 중복 정의 | 해결됨 | 중복 useMemo 제거 |
| 그리드 가이드 셀 크기 불균일 | 해결됨 | gridTemplateRows로 행 높이 강제 고정 |
| Canvas/Renderer 행 수 불일치 | 해결됨 | 숨김 필터 통일, 여유행 +3 |
| 디버깅 console.log 잔존 | 해결됨 | reviewComponents 내 삭제 |
| 설정 탭 세로 스크롤 불가 | **해결됨** | ComponentEditorPanel Tabs/TabsContent에 min-h-0 추가 |
| 아이템 라벨 편집 불가 (접힌 상태) | **해결됨** | ItemEditor 헤더 span -> Input 교체 |
| 대상 컬럼 조회 안 됨 | **해결됨** | fetchTableColumns API 우선순위 변경 (tableManagementApi 우선) |
| 잘못된 SQL로 백엔드 장애 | **해결됨** | validateDataSourceConfig으로 중간 상태 SQL 차단 |
| API 30초 타임아웃 (auth/me 등) | **해결됨** | 잘못된 SQL 차단 + 브라우저 새로고침 |
| 2열 설정이 1열로 렌더링 | **해결됨** | MIN_CELL_WIDTH 160 -> 80 |
| 라벨/단위/증감율 잘림 | **해결됨** | truncate/hidden 제거, 폰트/패딩 상향 |
| useEffect 데이터 불필요 재호출 | **해결됨** | visibleItemIds 의존성 안정화 |

---

## 최근 세션

| 날짜 | 요약 | 상세 |
|------|------|------|
| 2026-02-11 | 스타일 정리 + 라벨 정렬 + Phase 0 공통 훅 구현 (usePopEvent/useDataSource) | [sessions/2026-02-11.md](./sessions/2026-02-11.md) |
| 2026-02-10 | pop-dashboard 코딩 + 페이지 구조 재설계 + 설정 탭 스크롤 수정 | [sessions/2026-02-10.md](./sessions/2026-02-10.md) |
| 2026-02-09 | 컴포넌트 정의서 v8.0, 뷰어 렌더링 버그 수정, datetime 이슈 분석 | [sessions/2026-02-09.md](./sessions/2026-02-09.md) |
| 2026-02-06 | 브레이크포인트 재설계, 세로 자동 확장, v5.1 자동 줄바꿈 | [sessions/2026-02-06.md](./sessions/2026-02-06.md) |
| 2026-02-05 심야 | 반응형 레이아웃, 숨김 기능, 겹침 검사 | [sessions/2026-02-05.md](./sessions/2026-02-05.md) |
| 2026-02-05 저녁 | v5 통합, 그리드 가이드 재설계 | [sessions/2026-02-05.md](./sessions/2026-02-05.md) |

---

## 관련 결정

| ADR | 제목 | 날짜 |
|-----|------|------|
| - | pop-dashboard 상세 설계 토의 (POPUPDATE_2.md + plan 파일) | 2026-02-09 |
| - | POP 컴포넌트 정의서 v8.0 (POPUPDATE_2.md) | 2026-02-09 |
| 006 | v5.1 자동 줄바꿈 + 검토 필요 시스템 | 2026-02-06 |
| 005 | 브레이크포인트 재설계 (기기 기반) + 세로 자동 확장 | 2026-02-06 |
| 004 | 그리드 가이드 CSS Grid 통합 | 2026-02-05 |
| 003 | v5 CSS Grid 채택 | 2026-02-05 |
| 001 | v4 제약조건 기반 | 2026-02-03 |

---

*전체 히스토리: [CHANGELOG.md](./CHANGELOG.md)*