575 lines
30 KiB
Markdown
575 lines
30 KiB
Markdown
# 문제-해결 색인
|
|
|
|
> **용도**: "이전에 비슷한 문제 어떻게 해결했어?"
|
|
> **검색 팁**: Ctrl+F로 키워드 검색 (에러 메시지, 컴포넌트명 등)
|
|
|
|
---
|
|
|
|
## 렌더링 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| rowSpan이 적용 안됨 | gridTemplateRows를 `1fr`로 변경 | 2026-02-02 | grid, rowSpan, CSS |
|
|
| 컴포넌트 크기 스케일 안됨 | viewportWidth 기반 scale 계산 추가 | 2026-02-04 | scale, viewport, 반응형 |
|
|
| **그리드 가이드 셀 크기 불균일** | gridAutoRows → gridTemplateRows로 행 높이 강제 고정 | 2026-02-06 | gridAutoRows, gridTemplateRows, 셀 크기, CSS Grid |
|
|
| **컴포넌트 콘텐츠가 셀 경계 벗어남** | overflow-visible → overflow-hidden 변경 | 2026-02-06 | overflow, 셀 크기, 콘텐츠 |
|
|
| **뷰어에서 플레이스홀더만 표시** | page.tsx에 레지스트리 초기화 import 추가 + renderActualComponent() 실제 컴포넌트 렌더링으로 교체 | 2026-02-09 | 뷰어, 플레이스홀더, 레지스트리, side-effect import |
|
|
| **뷰어에서 스크롤 불가 (콘텐츠 잘림)** | 최외곽 overflow-hidden 제거, overflow-auto 공통 적용, min-h-full 추가 | 2026-02-09 | 스크롤, overflow, h-screen, 뷰어 |
|
|
| **글자 크기 커스텀 vs @container 충돌** | 절대 px 글자 크기 전체 제거, @container 반응형 자동 유지 | 2026-02-11 | 글자 크기, @container, 반응형, overflow |
|
|
| **.next 빌드 캐시 꼬임 (Docker)** | `docker-compose down -v` + `--build` 재시작 | 2026-02-11 | .next, 캐시, Docker, 익명 볼륨, Turbopack |
|
|
|
|
## 상태 관리 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **stale closure (handleUpdateComponent)** | `setLayout(prev => ...)` 함수적 업데이트, layout 의존성 제거 | 2026-02-11 | stale closure, useCallback, setState |
|
|
|
|
## DnD (드래그앤드롭) 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| useDrag 에러 (뷰어에서) | isDesignMode 체크 후 early return | 2026-02-04 | DnD, useDrag, 뷰어 |
|
|
| DndProvider 중복 에러 | 최상위에서만 Provider 사용 | 2026-02-04 | DndProvider, react-dnd |
|
|
| **Expected drag drop context (뷰어)** | isDesignMode=false일 때 DraggableComponent 대신 일반 div 렌더링 | 2026-02-05 | DndProvider, useDrag, 뷰어, context |
|
|
| **컴포넌트 중첩(겹침)** | toast import 누락 → `sonner`에서 import | 2026-02-05 | 겹침, overlap, toast |
|
|
| **리사이즈 핸들 작동 안됨** | useDrop 2개 중복 → 단일 useDrop으로 통합 | 2026-02-05 | resize, 핸들, useDrop |
|
|
| **드래그 좌표 완전 틀림 (Row 92)** | 캔버스 scale 보정 누락 → `(offset - rect.left) / scale` | 2026-02-05 | scale, 좌표, transform |
|
|
| **DND 타입 상수 불일치** | 3개 파일에 중복 정의 → `constants/dnd.ts`로 통합 | 2026-02-05 | 상수, DND, 타입 |
|
|
| **컴포넌트 이동 안됨** | useDrop accept 타입 불일치 → 공통 상수 사용 | 2026-02-05 | 이동, useDrop, accept |
|
|
|
|
## 타입 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| 인터페이스 이름 불일치 | V5 접미사 제거, 통일 | 2026-02-05 | 타입, interface, Props |
|
|
| v3/v4 타입 혼재 | v5 전용으로 통합, 레거시 삭제 | 2026-02-05 | 버전, 타입, 마이그레이션 |
|
|
|
|
## 레이아웃 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **화면 밖 컴포넌트 정보 손실** | 자동 줄바꿈 로직 추가 (col > maxCol → col=1, row=맨아래+1) | 2026-02-06 | 자동배치, 줄바꿈, 정보손실 |
|
|
| Flexbox 배치 예측 불가 | CSS Grid로 전환 (v5) | 2026-02-05 | Flexbox, Grid, 반응형 |
|
|
| 4모드 각각 배치 힘듦 | 제약조건 기반 시스템 (v4) | 2026-02-03 | 모드, 반응형, 제약조건 |
|
|
| 4모드 자동 전환 안됨 | useResponsiveMode 훅 추가 | 2026-02-01 | 모드, 훅, 반응형 |
|
|
|
|
## 브레이크포인트/반응형 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **뷰어 반응형 모드 불일치** | detectGridMode() 사용으로 일관성 확보 | 2026-02-06 | 반응형, 뷰어, 모드 |
|
|
| **768~839px 모드 불일치** | TABLET_MIN 768로 변경, 브레이크포인트 재설계 | 2026-02-06 | 브레이크포인트, 768px |
|
|
| **useResponsiveMode vs GRID_BREAKPOINTS 불일치** | 뷰어에서 detectGridMode(viewportWidth) 사용 | 2026-02-06 | 훅, 상수, 일관성 |
|
|
|
|
## 저장/로드 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| 레이아웃 버전 충돌 | isV5Layout 타입 가드로 분기 | 2026-02-05 | 버전, 로드, 타입가드 |
|
|
| 빈 레이아웃 판별 실패 | components 존재 여부로 판별 | 2026-02-04 | 빈 레이아웃, 로드 |
|
|
|
|
## UI/UX 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| root 레이아웃 오염 | tempLayout 도입 (임시 상태 분리) | 2026-02-04 | tempLayout, 상태, 오염 |
|
|
| 속성 패널 다른 모드 수정 | isDefaultMode 체크로 비활성화 | 2026-02-04 | 속성패널, 모드, 비활성화 |
|
|
|
|
## 브랜치 병합 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **ksh-dashboard + ksh-v2-work 병합 시 7파일 17지점 충돌** | 의존성 순서로 해결: 타입 - 등록 - 컴포넌트 - 렌더러 - 패널. 양쪽 기능 통합(union) 전략 | 2026-02-11 | 병합, merge, 충돌, pop-icon, pop-dashboard |
|
|
| **PopComponentType 확장 충돌** | 양쪽 타입 union (`pop-icon` + `pop-dashboard`) 결합, DEFAULT_COMPONENT_GRID_SIZE에 양쪽 항목 추가 | 2026-02-11 | PopComponentType, union type, Record |
|
|
| **COMPONENT_TYPE_LABELS 불완전** | PopRenderer(`Record<PopComponentType, string>`)에 4개 항목 모두 추가하여 타입 안전성 확보 | 2026-02-11 | COMPONENT_TYPE_LABELS, Record, 타입 안전 |
|
|
| **isRealtime useEffect 충돌 (pop-text)** | ksh-dashboard 로직 채택 - `isRealtime` 조건부 interval로 불필요한 timer 방지 | 2026-02-11 | isRealtime, useEffect, setInterval, pop-text |
|
|
| **CSS 클래스 충돌 (ComponentEditorPanel Tabs)** | ksh-v2-work의 방어적 CSS 채택 (`overflow-hidden`, `min-h-0`, `m-0`) - 스크롤 동작 안정성 우선 | 2026-02-11 | CSS, overflow, Tabs, TabsContent, 스크롤 |
|
|
| **레지스트리 패턴에서 불필요 props 전달** | 버그 아님 - `React.ComponentType<any>` 타입이므로 extra props 자동 무시. 레지스트리 아키텍처 의도적 패턴 | 2026-02-11 | 레지스트리, props, ComponentType, any |
|
|
|
|
---
|
|
|
|
## 그리드 가이드 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| SVG 격자와 CSS Grid 좌표 불일치 | GridGuide.tsx 삭제, PopRenderer에서 CSS Grid 셀로 격자 렌더링 | 2026-02-05 | 격자, SVG, CSS Grid, 좌표 |
|
|
| 행/열 라벨 위치 오류 | PopCanvas에 absolute positioning 라벨 추가 | 2026-02-05 | 라벨, 행, 열, 정렬 |
|
|
| 격자선과 컴포넌트 불일치 | 동일한 CSS Grid 좌표계 사용 | 2026-02-05 | 통합, 정렬, 일체감 |
|
|
|
|
---
|
|
|
|
## 뷰어 플레이스홀더 버그 상세 (2026-02-09)
|
|
|
|
### 증상
|
|
설계 화면(디자이너)에서는 이미지/텍스트/타이틀 정상 표시.
|
|
뷰어(`/pop/screens/4114`) 접속 시 "pop-text 1", "pop-text 2" 같은 라벨만 보임.
|
|
|
|
### 원인 (2가지)
|
|
|
|
**원인 A**: `renderActualComponent()` 함수가 하드코딩된 플레이스홀더만 반환
|
|
```typescript
|
|
// 변경 전 (PopRenderer.tsx 555-564)
|
|
function renderActualComponent(component) {
|
|
const typeLabel = COMPONENT_TYPE_LABELS[component.type];
|
|
return (
|
|
<div>
|
|
<span>{component.label || typeLabel}</span>
|
|
</div>
|
|
);
|
|
}
|
|
```
|
|
|
|
**원인 B**: 뷰어 `page.tsx`에서 `PopComponentRegistry` 초기화 import 누락
|
|
- 디자이너에서는 `PopDesigner.tsx`가 컴포넌트를 import하여 레지스트리 초기화됨
|
|
- 뷰어에서는 아무도 레지스트리를 초기화하지 않아 빈 상태
|
|
|
|
### 해결
|
|
```typescript
|
|
// page.tsx - 레지스트리 초기화 (PopRenderer보다 먼저!)
|
|
import "@/lib/registry/pop-components";
|
|
import PopRenderer from "@/components/pop/designer/renderers/PopRenderer";
|
|
|
|
// PopRenderer.tsx - 실제 컴포넌트 렌더링
|
|
function renderActualComponent(component) {
|
|
const registeredComp = PopComponentRegistry.getComponent(component.type);
|
|
const ActualComp = registeredComp?.component;
|
|
if (ActualComp) {
|
|
return <ActualComp config={component.config} label={component.label} />;
|
|
}
|
|
// fallback: 플레이스홀더
|
|
}
|
|
```
|
|
|
|
### 교훈
|
|
> side-effect import (`import "..."`)는 해당 레지스트리를 사용하는 컴포넌트 import보다 **반드시 앞에** 위치해야 한다.
|
|
> JavaScript 모듈은 import 선언 순서대로 실행되므로, 순서가 뒤바뀌면 빈 레지스트리를 참조할 수 있다.
|
|
> 새 POP 컴포넌트를 등록할 때, 뷰어 페이지에도 초기화 import가 있는지 반드시 확인.
|
|
|
|
---
|
|
|
|
## 해결 완료 (이번 세션)
|
|
|
|
| 문제 | 상태 | 해결 방법 |
|
|
|------|------|----------|
|
|
| PopCanvas 타입 오류 | **해결** | 임시 타입 가드 추가 |
|
|
| 팔레트 UI 없음 | **해결** | ComponentPalette.tsx 신규 추가 |
|
|
| SVG 격자 좌표 불일치 | **해결** | CSS Grid 기반 통합 |
|
|
| 드래그 좌표 완전 틀림 | **해결** | scale 보정 + calcGridPosition 함수 |
|
|
| DND 타입 상수 불일치 | **해결** | constants/dnd.ts 통합 |
|
|
| 컴포넌트 이동 안됨 | **해결** | useDrop/useDrag 타입 통일 |
|
|
| 컴포넌트 중첩(겹침) | **해결** | toast import 추가 → 겹침 감지 로직 정상 작동 |
|
|
| 리사이즈 핸들 작동 안됨 | **해결** | useDrop 통합 (2개 → 1개) |
|
|
| 숨김 컴포넌트 드래그 안됨 | **해결** | handleMoveComponent에서 숨김 해제 + 위치 저장 단일 상태 업데이트 |
|
|
| 그리드 범위 초과 에러 | **해결** | adjustedCol 계산으로 드롭 위치 자동 조정 |
|
|
| Expected drag drop context (뷰어) | **해결** | isDesignMode=false일 때 일반 div 렌더링 |
|
|
| hiddenComponentIds 중복 정의 | **해결** | 중복 useMemo 제거 (라인 410-412) |
|
|
| 뷰어 반응형 모드 불일치 | **해결** | detectGridMode() 사용 |
|
|
| 그리드 가이드 셀 크기 불균일 | **해결** | gridTemplateRows로 행 높이 강제 고정 |
|
|
| Canvas vs Renderer 행 수 불일치 | **해결** | 숨김 필터 통일, 여유행 +3으로 통일 |
|
|
| 디버깅 console.log 잔존 | **해결** | reviewComponents 내 console.log 삭제 |
|
|
| 뷰어 실제 컴포넌트 렌더링 안 됨 | **해결** | 레지스트리 초기화 import + renderActualComponent 수정 |
|
|
|
|
---
|
|
|
|
## 드래그 좌표 버그 상세 (2026-02-05)
|
|
|
|
### 증상
|
|
- 컴포넌트를 아래로 드래그 → 위로 올라감
|
|
- Row 92 같은 비정상 좌표
|
|
- 드래그 이동/리사이즈 전혀 작동 안됨
|
|
|
|
### 원인
|
|
```
|
|
캔버스: transform: scale(0.8)
|
|
|
|
getBoundingClientRect() → 스케일 적용된 크기 (1024px → 819px)
|
|
getClientOffset() → 뷰포트 기준 실제 마우스 좌표
|
|
|
|
이 둘을 그대로 계산하면 좌표 완전 틀림
|
|
```
|
|
|
|
### 해결
|
|
```typescript
|
|
// 스케일 보정된 상대 좌표 계산
|
|
const relX = (offset.x - canvasRect.left) / canvasScale;
|
|
const relY = (offset.y - canvasRect.top) / canvasScale;
|
|
|
|
// 실제 캔버스 크기로 그리드 계산
|
|
calcGridPosition(relX, relY, customWidth, ...);
|
|
```
|
|
|
|
### 교훈
|
|
> CSS `transform: scale()` 적용된 요소에서 좌표 계산 시,
|
|
> `getBoundingClientRect()`는 스케일 적용된 값을 반환하지만
|
|
> 마우스 좌표는 뷰포트 기준이므로 **반드시 스케일 보정 필요**
|
|
|
|
---
|
|
|
|
## Expected drag drop context 에러 상세 (2026-02-05 심야)
|
|
|
|
### 증상
|
|
```
|
|
Invariant Violation: Expected drag drop context
|
|
at useDrag (...)
|
|
at DraggableComponent (...)
|
|
```
|
|
뷰어 페이지(`/pop/viewer/[screenId]`)에서 POP 화면 조회 시 에러 발생
|
|
|
|
### 원인
|
|
```
|
|
PopRenderer의 DraggableComponent에서 useDrag 훅을 무조건 호출
|
|
→ 뷰어 페이지에는 DndProvider가 없음
|
|
→ React 훅은 조건부 호출 불가 (Rules of Hooks)
|
|
→ DndProvider 없이 useDrag 호출 시 context 에러
|
|
```
|
|
|
|
### 해결
|
|
```typescript
|
|
// PopRenderer.tsx - 컴포넌트 렌더링 부분
|
|
if (isDesignMode) {
|
|
return (
|
|
<DraggableComponent ... /> // useDrag 사용
|
|
);
|
|
}
|
|
|
|
// 뷰어 모드: 드래그 없는 일반 렌더링
|
|
return (
|
|
<div className="..." style={positionStyle}>
|
|
<ComponentContent ... />
|
|
</div>
|
|
);
|
|
```
|
|
|
|
### 교훈
|
|
> React DnD의 `useDrag`/`useDrop` 훅은 반드시 `DndProvider` 내부에서만 호출해야 함.
|
|
> 디자인 모드와 뷰어 모드를 분기할 때, 훅이 포함된 컴포넌트 자체를 조건부 렌더링해야 함.
|
|
> 훅 내부에서 `canDrag: false`로 설정해도 훅 자체는 호출되므로 context 에러 발생.
|
|
|
|
### 관련 파일
|
|
- `gridUtils.ts`: convertAndResolvePositions(), needsReview()
|
|
- `PopCanvas.tsx`: ReviewPanel, ReviewItem
|
|
- `PopRenderer.tsx`: 자동 배치 위치 렌더링
|
|
|
|
---
|
|
|
|
## 뷰어 반응형 모드 불일치 상세 (2026-02-06)
|
|
|
|
### 증상
|
|
```
|
|
- 아이폰 SE, iPad Pro 프리셋은 정상 작동
|
|
- 브라우저 수동 리사이즈 시 6칸 모드(mobile_landscape)가 적용 안 됨
|
|
- 768~839px 구간에서 8칸으로 표시됨 (예상: 6칸)
|
|
```
|
|
|
|
### 원인
|
|
```
|
|
useResponsiveMode 훅:
|
|
- deviceType: width/height 비율로 "mobile"/"tablet" 판정
|
|
- isLandscape: width > height로 판정
|
|
- BREAKPOINTS.TABLET_MIN = 840 (당시)
|
|
|
|
GRID_BREAKPOINTS:
|
|
- mobile_landscape: 600~839px (6칸)
|
|
- tablet_portrait: 840~1023px (8칸)
|
|
|
|
결과:
|
|
- 768px 화면 → useResponsiveMode: "tablet" (768 < 840이지만 비율 판정)
|
|
- 768px 화면 → GRID_BREAKPOINTS: "mobile_landscape" (6칸)
|
|
- → 모드 불일치!
|
|
```
|
|
|
|
### 해결
|
|
|
|
**1단계: 브레이크포인트 재설계**
|
|
```typescript
|
|
// 기존
|
|
mobile_landscape: { minWidth: 600, maxWidth: 839 }
|
|
tablet_portrait: { minWidth: 840, maxWidth: 1023 }
|
|
|
|
// 변경 후
|
|
mobile_landscape: { minWidth: 480, maxWidth: 767 }
|
|
tablet_portrait: { minWidth: 768, maxWidth: 1023 }
|
|
```
|
|
|
|
**2단계: 훅 연동**
|
|
```typescript
|
|
// useDeviceOrientation.ts
|
|
BREAKPOINTS.TABLET_MIN: 768 // was 840
|
|
```
|
|
|
|
**3단계: 뷰어 모드 감지 방식 변경**
|
|
```typescript
|
|
// page.tsx (뷰어)
|
|
const currentModeKey = isPreviewMode
|
|
? getModeKey(deviceType, isLandscape) // 프리뷰: 수동 선택
|
|
: detectGridMode(viewportWidth); // 일반: 너비 기반 (일관성 확보)
|
|
```
|
|
|
|
### 교훈
|
|
> 반응형 모드 판정은 **단일 소스(GRID_BREAKPOINTS)**를 기준으로 해야 함.
|
|
> 훅과 상수가 각각 다른 기준을 사용하면 구간별 불일치 발생.
|
|
> 뷰어에서는 `detectGridMode(viewportWidth)` 직접 사용으로 일관성 확보.
|
|
|
|
---
|
|
|
|
## 뷰어 렌더링 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **뷰어에서 실제 컴포넌트 대신 플레이스홀더 표시** | (1) `page.tsx`에 레지스트리 초기화 import 추가 (2) `renderActualComponent()`에서 `PopComponentRegistry.getComponent()` 조회 후 실제 렌더링 | 2026-02-09 | 뷰어, 플레이스홀더, 레지스트리, import, renderActualComponent |
|
|
| **datetime 실시간 업데이트 기본값 불일치** | **미해결** - `DateTimeDisplay`의 `if (!config?.isRealtime) return`에서 undefined가 false로 평가되어 타이머 미작동. 설정 패널은 `?? true`로 기본 켜짐 표시. 권장: `const isRealtime = config?.isRealtime ?? true` | 2026-02-09 | datetime, isRealtime, undefined, 기본값, 타이머 |
|
|
|
|
---
|
|
|
|
## 병합 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **ScreenDesigner.tsx 3건 충돌** (origin/main 병합) | 함수 시그니처: ksh-v2-work 유지(isPop/defaultDevicePreview), 저장 로직: 3단계 분기 유지+console.log 제거, 툴바 props: origin/main 채택 | 2026-02-09 | 병합, merge, ScreenDesigner, 충돌 |
|
|
| **usePanelState 중복 선언** (병합 시 발견) | 충돌 1 해결 과정에서 L175의 중복 usePanelState 제거, L215의 완전한 버전만 유지 | 2026-02-09 | usePanelState, 중복, 병합 |
|
|
| **툴바 JSX 들여쓰기 불일치** (병합 후 린트) | origin/main 코드가 ksh-v2-work와 2칸 들여쓰기 차이. 기능 영향 없음. 추후 포매팅 정리 권장 | 2026-02-09 | 들여쓰기, 포매팅, 린트, prettier |
|
|
|
|
---
|
|
|
|
## 컴포넌트 등록 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **pop-dashboard 팔레트 미노출** | PopComponentType/PALETTE_ITEMS/DEFAULT_COMPONENT_GRID_SIZE/COMPONENT_TYPE_LABELS 4곳에 수동 등록 누락. 4곳 모두 추가 | 2026-02-10 | 팔레트, 등록, PopComponentType, 하드코딩, 레지스트리 |
|
|
| **미사용 import (AggregatedResult)** | PopDashboardComponent.tsx에서 type AggregatedResult import 제거 | 2026-02-10 | import, 미사용, 코드 품질 |
|
|
|
|
## pop-dashboard 데이터/SQL 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **대상 컬럼 조회 안 됨** | fetchTableColumns에서 tableManagementApi(axios) 우선 사용, dashboardApi(fetch) 폴백 | 2026-02-10 | 컬럼, schema, API, 인증, fetch, axios |
|
|
| **SUM()/COUNT() 빈 괄호 SQL** | validateDataSourceConfig으로 중간 상태 검증, 미완료 시 SQL 생성 차단 | 2026-02-10 | SQL, 집계, validate, 중간상태, 백엔드 |
|
|
| **API 30초 타임아웃 (auth/me 등)** | 잘못된 SQL이 백엔드 과부하 유발 -> SQL 차단 + 브라우저 새로고침 | 2026-02-10 | timeout, auth, 과부하, 브라우저 멈춤 |
|
|
| **Docker unhealthy (curl 미설치)** | healthcheck에 curl이 없어 false 양성. 서비스 자체는 정상. 확인만 필요 | 2026-02-10 | docker, healthcheck, curl, unhealthy |
|
|
|
|
## pop-dashboard 렌더링 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **2열 설정이 1열로 렌더링** | GridMode.tsx MIN_CELL_WIDTH 160->80. 초기 containerWidth=300에서 (300-8)/2=146 < 160이라 축소됨 | 2026-02-10 | 그리드, 열, 레이아웃, MIN_CELL_WIDTH, containerWidth |
|
|
| **라벨/단위/증감율 잘림** | 4개 아이템에서 truncate/hidden 제거, text-[10px]->text-xs, p-2->p-3 | 2026-02-10 | truncate, hidden, 라벨, 잘림, @container |
|
|
| **useEffect 불필요 데이터 재호출** | visibleItems 배열 참조 -> visibleItemIds(JSON 문자열) 의존성 안정화 | 2026-02-10 | useEffect, 의존성, 배열참조, JSON.stringify |
|
|
| **파이 차트 미표시** | (1) fetch 기반 API가 iframe에서 간헐 실패 -> apiClient(axios) 우선 (2) PostgreSQL bigint 문자열 -> Number() 변환 | 2026-02-10 | PieChart, fetch, axios, bigint, 문자열, Number |
|
|
| **파이 차트 라벨/레전드 없음** | ChartItem.tsx에 Legend 컴포넌트 + custom label 포맷(`name value (percent%)`) 추가 | 2026-02-10 | PieChart, Legend, label, Recharts |
|
|
| **게이지 가로 레이아웃 비율 깨짐** | max-w-[200px] 고정 -> h-full w-auto max-w-full 높이 기반 스케일링. SVG 래퍼를 flex-1 min-h-0으로 변경 | 2026-02-10 | 게이지, SVG, 비율, max-width, 가로 레이아웃 |
|
|
| **KPI/통계 카드 왼쪽 정렬** | KpiCard에 items-center, StatCard에 items-center justify-center 추가. 4개 아이템 정렬 통일 | 2026-02-10 | 정렬, items-center, KPI, StatCard |
|
|
|
|
## pop-dashboard 설정 패널 관련
|
|
|
|
| 문제 | 해결 | 날짜 | 키워드 |
|
|
|------|------|------|--------|
|
|
| **설정 패널 표시 모드/아이템 탭 클릭 시 에러** | ConfigPanelProps에서 `onChange`를 `onUpdate`로 변경. ComponentEditorPanel이 `onUpdate`로 전달하는데 대시보드만 `onChange`로 수신하여 TypeError 발생. `onUpdate: onChange` 구조분해로 해결 | 2026-02-10 | onChange, onUpdate, props, TypeError, 설정패널, 컨벤션 |
|
|
| **gaugeConfig min/max/target 변경 안 됨** | 스프레드 연산자 순서 버그. `{ max: newValue, ...item.gaugeConfig }` -> `{ ...item.gaugeConfig, max: newValue }`. 나중에 오는 속성이 우선 | 2026-02-10 | 스프레드, 순서, gaugeConfig, 덮어쓰기, onChange |
|
|
| **차트 X축/Y축 입력 혼동** | "X축 컬럼"과 "그룹핑(X축)" 중복으로 사용자 혼동. 수동 입력 제거, 자동 설정 안내 텍스트로 교체 | 2026-02-10 | xAxisColumn, groupBy, 중복, UX, 설정패널 |
|
|
| **React hooks 규칙 위반 (early return)** | `PopDashboardComponent.tsx`에서 `if (!config)` early return이 hooks보다 앞에 위치. 모든 hooks 선언 이후로 early return 이동, `visibleItems`에 `?? []` 안전 처리 추가 | 2026-02-10 | hooks, early return, Rules of Hooks, useState, useEffect |
|
|
| **config가 빈 객체 `{}`로 전달되어 items undefined** | `ComponentEditorPanel`이 `component.config \|\| {}`로 빈 객체 전달 -> `??`가 빈 객체를 통과 -> `cfg.items` undefined -> `.map()`, `.length`, `.filter()` TypeError. ConfigPanel: `{...DEFAULT_CONFIG, ...config}` spread 병합, Preview: `Array.isArray()` 가드 추가, Component: `Array.isArray()` 가드 추가 | 2026-02-10 | config, 빈 객체, nullish coalescing, undefined, items, TypeError |
|
|
|
|
|| **설정 탭 세로 스크롤 불가 (페이지 추가 시 콘텐츠 잘림)** | `ComponentEditorPanel.tsx`의 `Tabs`와 모든 `TabsContent`에 `min-h-0` 누락. Flexbox에서 flex 자식의 기본 `min-height: auto`가 콘텐츠 크기 이하로 축소를 막아 `overflow-auto`가 작동하지 않음. `Tabs`에 `min-h-0`, `TabsList`에 `shrink-0`, 4개 `TabsContent`에 `min-h-0` 추가로 해결 | 2026-02-10 | 스크롤, overflow, min-h-0, flex, TabsContent, 설정패널, 페이지 탭 |
|
|
|
|
---
|
|
|
|
## 설정 탭 스크롤 버그 상세 (2026-02-10)
|
|
|
|
### 증상
|
|
POP 디자이너에서 대시보드 컴포넌트 선택 -> 설정 탭 -> 페이지 탭에서 페이지를 3개 이상 추가하면 아래쪽 페이지가 잘려서 보이지 않음. 세로 스크롤 불가.
|
|
|
|
### 잘못된 접근 (실패 기록)
|
|
처음에 `PopDashboardConfigPanel`(자식)에서 문제를 해결하려고 시도:
|
|
1. 외곽 `div`를 `flex h-full flex-col`로 변경
|
|
2. 탭 콘텐츠에 `overflow-y-auto` 래퍼 추가
|
|
|
|
**실패 이유**: `PopDashboardConfigPanel`은 부모(`ComponentSettingsForm`)의 `overflow-auto`가 담당하는 스크롤 영역 안에 있으므로, 자식이 `h-full`로 높이를 채우면 부모의 스크롤 영역이 깨짐. 문제는 자식이 아니라 **부모의 높이 제약이 제대로 전파되지 않는 것**.
|
|
|
|
### 근본 원인
|
|
```
|
|
ResizablePanel (높이 확정)
|
|
└ ComponentEditorPanel: div.flex.h-full.flex-col
|
|
├ 헤더 (고정)
|
|
└ Tabs: flex.flex-1.flex-col ← min-h-0 누락!
|
|
├ TabsList (고정)
|
|
└ TabsContent: flex-1.overflow-auto ← min-h-0 누락!
|
|
└ ComponentSettingsForm
|
|
└ PopDashboardConfigPanel ← 콘텐츠가 길어짐
|
|
```
|
|
|
|
Flexbox의 `min-height: auto` 기본값 때문에:
|
|
- `Tabs`(flex-1)가 콘텐츠에 의해 무한 확장
|
|
- `TabsContent`(overflow-auto)도 콘텐츠에 의해 확장 -> 스크롤 발생 안 함
|
|
- 결과: `overflow-auto`가 있지만 높이 제약이 없어 스크롤바 미생성
|
|
|
|
### 해결
|
|
```typescript
|
|
// ComponentEditorPanel.tsx
|
|
// 변경 전
|
|
<Tabs defaultValue="position" className="flex flex-1 flex-col">
|
|
<TabsList className="w-full justify-start ...">
|
|
<TabsContent value="settings" className="flex-1 overflow-auto p-4">
|
|
|
|
// 변경 후
|
|
<Tabs defaultValue="position" className="flex min-h-0 flex-1 flex-col">
|
|
<TabsList className="w-full shrink-0 justify-start ...">
|
|
<TabsContent value="settings" className="min-h-0 flex-1 overflow-auto p-4">
|
|
```
|
|
|
|
### 교훈
|
|
> Flexbox에서 `overflow-auto`가 작동하려면, 해당 요소와 **모든 flex 조상에 `min-h-0`(또는 `min-w-0`)이 필요**하다.
|
|
> `flex-1`만으로는 높이가 제한되지 않는다. flex 자식의 기본 `min-height: auto`가 콘텐츠 크기 이하로 축소를 막기 때문이다.
|
|
> 스크롤 문제가 발생하면 자식 컴포넌트가 아니라 **부모 flex 체인부터 위로 추적**해야 한다.
|
|
|
|
---
|
|
|
|
## 폼 중간 상태 -> 잘못된 SQL -> 백엔드 장애 상세 (2026-02-10)
|
|
|
|
### 증상
|
|
브라우저 콘솔에 `timeout of 30000ms exceeded` 에러 반복. `/auth/me`, `/auth/status`, `/admin/menus` 등 핵심 API가 모두 30초 타임아웃. 브라우저가 멈추거나 자동 종료.
|
|
|
|
### 원인 체인
|
|
```
|
|
1. 대시보드 설정에서 집계 유형(SUM/AVG)만 선택, 대상 컬럼 미선택
|
|
↓
|
|
2. dataFetcher.ts의 buildAggregationSQL이 "SUM()" 같은 잘못된 SQL 생성
|
|
↓
|
|
3. 잘못된 SQL이 백엔드로 전송, PostgreSQL "function sum() does not exist" 에러
|
|
↓
|
|
4. refreshInterval(기본값)로 이 요청이 반복 전송
|
|
↓
|
|
5. 백엔드 과부하 -> Docker 컨테이너 unhealthy
|
|
↓
|
|
6. 인증/메뉴 등 다른 API도 30초 타임아웃
|
|
↓
|
|
7. 여러 API가 병렬로 30초씩 대기 -> 브라우저 멈춤
|
|
```
|
|
|
|
### 해결
|
|
```typescript
|
|
// dataFetcher.ts - SQL 생성 전 필수값 검증
|
|
function validateDataSourceConfig(ds: DataSourceConfig): string | null {
|
|
if (!ds.tableName) return "테이블이 선택되지 않았습니다";
|
|
if (ds.aggregation?.type && ds.aggregation.type !== "COUNT" && !ds.aggregation.column) {
|
|
return "집계 대상 컬럼이 선택되지 않았습니다";
|
|
}
|
|
// ... 조인 검증 등
|
|
return null; // 유효
|
|
}
|
|
|
|
// fetchAggregatedData에서 호출
|
|
const validationError = validateDataSourceConfig(dataSource);
|
|
if (validationError) {
|
|
return { value: 0, error: validationError };
|
|
}
|
|
```
|
|
|
|
### 교훈
|
|
> 프론트엔드 설정 폼의 "중간 상태"(일부만 입력)가 백엔드에 전달되면 연쇄 장애로 이어질 수 있다.
|
|
> SQL/API 호출 전에 반드시 `validate` 함수를 배치하고, 미완료 상태에서는 요청 자체를 차단해야 한다.
|
|
> 특히 `refreshInterval`이 있는 자동 갱신 기능은 잘못된 요청을 반복 전송할 수 있어 더 위험하다.
|
|
|
|
---
|
|
|
|
## 그리드 2열 -> 1열 축소 상세 (2026-02-10)
|
|
|
|
### 증상
|
|
디자이너에서 페이지를 2열로 설정했는데, 실제 화면에서는 아이템이 세로로 쌓여 1열로 표시됨.
|
|
|
|
### 원인
|
|
```
|
|
GridModeComponent에서 반응형 열 축소 로직:
|
|
MIN_CELL_WIDTH = 160px
|
|
containerWidth = 300px (초기값, ResizeObserver 발동 전)
|
|
gap = 8px
|
|
|
|
cellWidth = (300 - 8) / 2 = 146px
|
|
146 < 160 → actualColumns = 1 (축소!)
|
|
|
|
ResizeObserver가 실제 너비를 반영해도,
|
|
초기 렌더링에서 이미 1열로 결정됨
|
|
```
|
|
|
|
### 해결
|
|
```typescript
|
|
// GridMode.tsx
|
|
const MIN_CELL_WIDTH = 80; // was 160
|
|
// 80px이면 146 >= 80 → 2열 유지
|
|
```
|
|
|
|
### 교훈
|
|
> 반응형 열 축소 로직의 MIN_CELL_WIDTH는 실제 사용 시나리오를 고려해야 한다.
|
|
> ResizeObserver가 발동하기 전 초기 containerWidth 기본값이 작을 수 있으므로,
|
|
> MIN_CELL_WIDTH를 너무 크게 설정하면 의도치 않게 열이 축소된다.
|
|
|
|
---
|
|
|
|
## stale closure (handleUpdateComponent)
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| **문제** | `PopDesigner.tsx`의 `handleUpdateComponent`에서 `layout` state를 직접 참조하여, 빠른 연속 설정 변경 시 이전 state가 캡처되어 변경값 유실 |
|
|
| **증상** | 정렬 버튼을 빠르게 클릭하면 이전 클릭의 변경이 덮어씌워짐 |
|
|
| **원인** | `useCallback`의 의존성 배열에 `layout`이 있지만, `layout` 갱신 전에 다음 호출이 발생하면 이전 클로저가 사용됨 |
|
|
| **해결** | `setLayout(prev => ...)` 함수적 업데이트로 변경, 의존성에서 `layout` 제거 → `[saveToHistory]`만 유지 |
|
|
| **날짜** | 2026-02-11 |
|
|
| **키워드** | stale closure, useCallback, setState, 함수적 업데이트, 빠른 연속 변경 |
|
|
|
|
### 교훈
|
|
> `useCallback` 안에서 state를 직접 참조하면 빠른 연속 호출 시 이전 값이 캡처된다.
|
|
> 항상 `setState(prev => ...)` 패턴으로 최신 state에 접근해야 한다.
|
|
> 특히 사용자 인터랙션(버튼 클릭)이 빠르게 반복될 수 있는 곳에서 주의.
|
|
|
|
---
|
|
|
|
## .next 빌드 캐시 꼬임 (Docker 익명 볼륨)
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| **문제** | `ChartItem.tsx`를 수정했으나 브라우저에 반영되지 않음. 디버그 console.log도 콘솔에 나타나지 않음 |
|
|
| **증상** | 다른 컴포넌트(StatCard, Gauge)는 최신 코드 실행, 차트만 이전 코드 실행 |
|
|
| **원인** | Docker compose에서 `/app/.next`가 익명 볼륨으로 분리되어 호스트의 `.next` 삭제와 독립적. Turbopack 모듈 캐시가 특정 파일 변경을 인식하지 못함 |
|
|
| **해결** | `docker-compose -f ... down -v` (볼륨 포함 삭제) + `docker-compose -f ... up -d --build` (재빌드) |
|
|
| **날짜** | 2026-02-11 |
|
|
| **키워드** | .next, 캐시, Docker, 익명 볼륨, Turbopack, HMR, 빌드 |
|
|
|
|
### 교훈
|
|
> Docker compose에서 `/app/.next`가 익명 볼륨인 경우, 호스트에서 `rm -rf .next`를 해도 컨테이너 캐시에 영향 없음.
|
|
> `docker-compose down -v`로 볼륨까지 제거해야 캐시가 초기화됨.
|
|
> 파일 수정이 브라우저에 반영 안 되면: (1) 디버그 로그 추가 (2) 로그가 안 나오면 캐시 문제 의심 (3) 볼륨 포함 재빌드.
|
|
|
|
---
|
|
|
|
## 글자 크기 커스텀 vs @container 반응형 충돌
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| **문제** | 글자 크기 3그룹(라벨/메인값/보조)을 절대 px(12~64px)로 설정하면, 유동적인 그리드 셀 크기와 충돌하여 텍스트가 잘리거나 넘침 |
|
|
| **증상** | "매우 크게(64px)" 설정 시 값이 셀 경계를 벗어남. 작은 셀에 큰 글자가 들어가면서 정보 가독성 저하 |
|
|
| **원인** | `@container` 반응형(`text-xs @[200px]:text-3xl`)은 셀 크기에 따라 자동 조절되는데, 절대 px가 이를 덮어씀 |
|
|
| **해결** | 글자 크기 커스텀 기능 전체 제거. `@container` 반응형 자동 크기만 유지. 정렬은 라벨만 좌/중/우 선택 |
|
|
| **날짜** | 2026-02-11 |
|
|
| **키워드** | 글자 크기, @container, 반응형, overflow, 대시보드 |
|
|
|
|
### 교훈
|
|
> 대시보드처럼 고밀도 정보를 표시하는 컴포넌트에서는 절대 크기 지정을 피하고, 컨테이너 크기에 따른 자동 반응형이 더 안정적이다.
|
|
> "정보를 한눈에 파악"이 목적인 컴포넌트에서는 정보가 잘리게 만드는 기능 자체가 목적에 반한다.
|
|
|
|
---
|
|
|
|
## 미사용 import (PopComponentType)
|
|
|
|
| 항목 | 내용 |
|
|
|------|------|
|
|
| **문제** | `ComponentEditorPanel.tsx`에서 `COMPONENT_TYPE_LABELS` 타입을 `Record<PopComponentType, string>` -> `Record<string, string>`으로 변경한 후, `PopComponentType`의 유일한 사용처가 사라졌으나 import가 남아있었음 |
|
|
| **해결** | import에서 `PopComponentType` 제거 |
|
|
| **날짜** | 2026-02-10 |
|
|
| **키워드** | 미사용 import, 타입 변경, PopComponentType |
|
|
|
|
### 교훈
|
|
> 타입을 변경하거나 제거할 때, 해당 타입이 import된 것이라면 변경 후 파일 내 다른 참조가 남아있는지 Grep으로 확인해야 한다.
|
|
|
|
---
|
|
|
|
*새 문제-해결 추가 시 해당 카테고리 테이블에 행 추가*
|