# POP 변경 이력

형식: [Keep a Changelog](https://keepachangelog.com/)

---

## [미출시]

- Phase 4: 실제 컴포넌트 구현 (pop-field, pop-button 등)
- 데이터 바인딩 구현
- 워크플로우 연동

---

## [2026-02-05] v5 그리드 시스템 완전 통합

### 배경 (왜 v5로 전환했는가)

**문제 상황**:
- v4 Flexbox로 반응형 구현 시도 → 배치가 예측 불가능
- 캔버스에 "그리듯이" 배치하면 화면 크기별로 깨짐

**상급자 피드백**:
> "이런 식이면 나중에 문제가 생긴다."
> "스크린의 픽셀 규격과 마진 간격 규칙을 설정해라.
> 큰 화면 디자인의 전체 프레임 규격과 사이즈 간격 규칙을 정한 다음에
> 거기에 컴포넌트를 끼워 맞추듯 우리의 규칙 내로 움직이게 바탕을 잡아라."

**연구 내용**:
- Softr: 블록 기반, 제약 기반 레이아웃
- Ant Design: 24열 그리드, 8px 간격
- Material Design: 4/8/12열, 반응형 브레이크포인트

**결정**: CSS Grid 기반 그리드 시스템 (v5) 채택
→ 상세: [decisions/003-v5-grid-system.md](./decisions/003-v5-grid-system.md)

### popdocs 문서 구조 재정비

**배경**: 문서가 AI 에이전트 진입점 역할을 못함, 컨텍스트 효율화 필요

**적용 기법**: Progressive Disclosure (점진적 공개), Token as Currency

**추가된 파일**:
- `SAVE_RULES.md`: AI 저장/조회 규칙, 템플릿
- `STATUS.md`: 현재 진행 상태, 중단점
- `PROBLEMS.md`: 문제-해결 색인
- `INDEX.md`: 기능별 색인
- `sessions/`: 날짜별 작업 기록

**문서 계층**:
- Layer 1 (진입점): README, STATUS, SAVE_RULES
- Layer 2 (상세): CHANGELOG, PROBLEMS, INDEX, FILES, ARCHITECTURE
- Layer 3 (심화): decisions/, sessions/, archive/

### Breaking Changes
- **v1, v2, v3, v4 레이아웃 완전 삭제**
- 기존 POP 화면 데이터 전체 초기화 필요
- 레거시 컴포넌트 및 타입 삭제

### Added
- **CSS Grid 기반 그리드 시스템 (v5)**
  - 4개 모드별 칸 수: 4/6/8/12칸
  - 명시적 위치 지정 (col, row, colSpan, rowSpan)
  - 모드별 오버라이드 지원
  - 자동 위치 변환 (12칸 기준 → 다른 모드)

- **통합된 파일 구조**
  - `PopCanvas.tsx`: 그리드 캔버스 (DnD + 줌 + 모드 전환)
  - `PopRenderer.tsx`: 그리드 렌더링
  - `ComponentEditorPanel.tsx`: 속성 편집
  - `pop-layout.ts`: v5 전용 타입 정의
  - `gridUtils.ts`: 그리드 유틸리티 함수

### Removed
- `PopCanvasV4.tsx`, `PopCanvas.tsx (v3)`
- `PopFlexRenderer.tsx`, `PopLayoutRenderer.tsx`
- `ComponentEditorPanelV4.tsx`, `PopPanel.tsx`
- v1, v2, v3, v4 타입 정의 및 유틸리티 함수
- `test-v4` 테스트 페이지

### Changed
- `screenManagementService.ts`: v5 전용으로 단순화
- `screen_layouts_pop` 테이블: 기존 데이터 삭제, v5 전용
- `PopDesigner.tsx`: v5 전용으로 리팩토링
- 뷰어 페이지: v5 렌더러 전용

### Technical Details
```typescript
// v5 그리드 모드
type GridMode = "mobile_portrait" | "mobile_landscape" | "tablet_portrait" | "tablet_landscape";

// 그리드 설정
const GRID_BREAKPOINTS = {
  mobile_portrait: { columns: 4, rowHeight: 48, gap: 8, padding: 12 },
  mobile_landscape: { columns: 6, rowHeight: 44, gap: 8, padding: 16 },
  tablet_portrait: { columns: 8, rowHeight: 52, gap: 12, padding: 20 },
  tablet_landscape: { columns: 12, rowHeight: 56, gap: 12, padding: 24 },
};

// 컴포넌트 위치
interface PopGridPosition {
  col: number;      // 시작 열 (1부터)
  row: number;      // 시작 행 (1부터)
  colSpan: number;  // 열 크기
  rowSpan: number;  // 행 크기
}
```

---

## [2026-02-04] Phase 2.1 완료 - 배치 고정 기능

### Added
- **현재 모드 추적** (PopDesigner.tsx)
  - `currentViewportMode` 상태 추가
  - PopCanvasV4와 양방향 동기화
  - 모드 변경 시 자동 업데이트

- **배치 고정 기능**
  - "고정" 버튼 추가 (기본 모드 제외)
  - `handleLockLayoutV4()` - 현재 배치를 오버라이드에 저장
  - 배치 정보: direction, wrap, gap, alignItems, justifyContent, children 순서

- **오버라이드 초기화 기능**
  - `handleResetOverrideV4()` - 오버라이드 삭제
  - "자동으로 되돌리기" 버튼 (편집된 모드만 표시)
  - 자동 계산으로 되돌림

### Changed
- **PopCanvasV4 Props 구조 변경**
  - `currentMode` prop 추가 (외부에서 제어)
  - `onModeChange` 콜백 추가
  - `onLockLayout` 콜백 추가
  - 내부 `activeViewport` 상태 제거 (부모가 관리)

- **프리셋 버튼 동작**
  - 클릭 시 부모 상태 업데이트 (`onModeChange`)
  - `currentMode` prop 기반으로 활성 상태 표시

### Technical Details
```typescript
// 고정 로직
const handleLockLayoutV4 = () => {
  const newLayout = {
    ...layoutV4,
    overrides: {
      ...layoutV4.overrides,
      [currentViewportMode]: {
        containers: {
          root: {
            direction: layoutV4.root.direction,
            wrap: layoutV4.root.wrap,
            gap: layoutV4.root.gap,
            children: layoutV4.root.children, // 순서 고정
            // ... 기타 배치 속성
          }
        }
      }
    }
  };
};

// 초기화 로직
const handleResetOverrideV4 = (mode) => {
  const newOverrides = { ...layoutV4.overrides };
  delete newOverrides[mode];
  // overrides가 비면 undefined로 설정
};
```

### UI 변경
```
툴바:
[모바일↕] [모바일↔] [태블릿↕] [태블릿↔(기본)] [고정] [자동으로 되돌리기]

조건부 표시:
- "고정" 버튼: 기본 모드가 아닐 때
- "자동으로 되돌리기": 오버라이드가 있을 때
```

### 주의사항
- 크기는 고정하지 않음 (여전히 자동 스케일링)
- 배치만 오버라이드 (순서, 방향, 정렬)
- 최소/최대값 기능은 별도 구현 필요

---

## [2026-02-04] Phase 2 시작 - 오버라이드 UI 표시

### Added
- **오버라이드 데이터 구조** (pop-layout.ts)
  - `PopModeOverride` 인터페이스 추가
  - `PopLayoutDataV4.overrides` 필드 추가
  - 3개 모드 오버라이드 지원 (mobile_portrait, mobile_landscape, tablet_portrait)

- **프리셋 버튼 상태 표시** (PopCanvasV4.tsx)
  - 기본 모드: "(기본)" 텍스트 표시
  - 편집된 모드: "(편집)" 텍스트 + 노란색 강조
  - 자동 모드: 기본 스타일

### Changed
- **hasOverride 함수 구현**
  - `layout.overrides` 필드 체크
  - 컴포넌트/컨테이너 오버라이드 존재 여부 확인

---

## [2026-02-04] 비율 스케일링 시스템 구현

### Added
- **비율 스케일링 시스템** (업계 표준 Scale with Fixed Aspect Ratio)
  - 기준 너비: 1024px (10인치 태블릿 가로)
  - 최대 너비: 1366px (12인치 태블릿)
  - 8~12인치 화면에서 배치 유지, 크기만 비례 조정

- **뷰포트 감지** (page.tsx)
  - `viewportWidth` state 추가
  - resize 이벤트 리스너로 실시간 감지
  - `Math.min(window.innerWidth, 1366)` 최대값 제한

### Changed
- **PopFlexRenderer.tsx**
  - `BASE_VIEWPORT_WIDTH = 1024` 상수 추가
  - `scale = viewportWidth / BASE_VIEWPORT_WIDTH` 계산
  - `calculateSizeStyle()` 함수에 scale 파라미터 추가
  - 컴포넌트 크기 (fixedWidth, fixedHeight) 스케일 적용
  - 컨테이너 gap, padding 스케일 적용
  - 디자인 모드: scale = 1 (원본), 뷰어 모드: 실제 scale 적용

- **ComponentRendererV4**
  - `viewportWidth` prop 추가
  - 내부에서 scale 계산하여 sizeStyle에 적용

- **ContainerRenderer**
  - scaledGap, scaledPadding 계산하여 containerStyle에 적용

### Technical Details
```
비율 스케일링 계산:
scale = 실제 화면 너비 / 기준 너비 (1024px)

예시:
- 800px (8인치): scale = 0.78 → 200px 컴포넌트 → 156px
- 1024px (10인치): scale = 1.00 → 200px 컴포넌트 → 200px (기준)
- 1366px (12인치): scale = 1.33 → 200px 컴포넌트 → 266px
- 1920px (데스크톱): max-width 1366px 적용 → 12인치와 동일 + 여백
```

### Fixed
- **DndProvider 에러** (뷰어 페이지)
  - 원인: isDesignMode=false일 때 useDrag/useDrop 훅 호출
  - 해결: DraggableComponentWrapper에서 isDesignMode 체크 후 early return

---

## [2026-02-04] Flexbox 가로 배치 + Spacer + Undo/Redo 개선

### Added
- **Spacer 컴포넌트** (`pop-spacer`)
  - 빈 공간을 차지하여 레이아웃 정렬에 사용
  - 기본 크기: `width: fill`, `height: 48px`
  - 디자인 모드에서 점선 배경으로 표시
  - 실제 모드에서는 투명 (공간만 차지)

- **컴포넌트 순서 변경 (드래그 앤 드롭)**
  - 같은 컨테이너 내에서 컴포넌트 순서 변경 가능
  - 드래그 중인 컴포넌트는 반투명하게 표시
  - 드롭 위치는 파란색 테두리로 표시
  - `handleReorderComponentV4` 핸들러 추가

### Changed
- **기본 레이아웃 방향 변경** (Flexbox 가로 배치)
  - `direction: "vertical"` → `direction: "horizontal"`
  - `wrap: false` → `wrap: true` (자동 줄바꿈)
  - `alignItems: "stretch"` → `alignItems: "start"`
  - 컴포넌트가 가로로 나열되고, 공간 부족 시 다음 줄로 이동

- **컴포넌트 기본 크기 타입별 설정**
  - 필드: 200x48px (fixed)
  - 버튼: 120x48px (fixed)
  - 리스트: fill x 200px
  - 인디케이터: 120x80px (fixed)
  - 스캐너: 200x48px (fixed)
  - 숫자패드: 200x280px (fixed)
  - Spacer: fill x 48px

- **Undo/Redo 방식 개선** (데스크탑 모드와 동일)
  - `useLayoutHistory` 훅 제거
  - 별도 `history[]`, `historyIndex` 상태로 관리
  - `saveToHistoryV4()` 함수로 명시적 히스토리 저장
  - 컴포넌트 추가/삭제/수정/순서변경 시 히스토리 저장

- **디바이스 스크린 스크롤**
  - `overflow: auto` 추가 (컴포넌트가 넘치면 스크롤)
  - `height` → `minHeight` 변경 (컨텐츠에 따라 높이 증가)

### Technical Details
```
업계 표준 레이아웃 방식 (Figma, Webflow, FlutterFlow):
1. Flexbox 기반 Row/Column 배치
2. 크기 제어: Fill / Fixed / Hug
3. Spacer 컴포넌트로 정렬 조정
4. 화면 크기별 조건 분기 (반응형)

사용 예시:
[버튼A] [Spacer(fill)] [버튼B]  → 버튼B가 오른쪽 끝으로
[Spacer] [컴포넌트] [Spacer]   → 컴포넌트가 가운데로
```

---

## [2026-02-04] 드래그 리사이즈 + Undo/Redo 기능

### Added
- **useLayoutHistory.ts** - Undo/Redo 히스토리 훅
  - 최대 50개 히스토리 저장
  - `undo()`, `redo()`, `canUndo`, `canRedo`
  - `reset()` - 새 레이아웃 로드 시 히스토리 초기화

- **드래그 리사이즈 핸들** (PopFlexRenderer)
  - 오른쪽 핸들: 너비 조정 (cursor: ew-resize)
  - 아래쪽 핸들: 높이 조정 (cursor: ns-resize)
  - 오른쪽 아래 핸들: 너비+높이 동시 조정 (cursor: nwse-resize)
  - 선택된 컴포넌트에만 표시
  - 최소 크기 보장 (너비 48px, 높이 touchTargetMin)

### Changed
- **PopDesigner.tsx**
  - `useLayoutHistory` 훅 통합 (v3, v4 각각 독립적)
  - Undo/Redo 버튼 추가 (툴바 오른쪽)
  - 단축키 등록:
    - `Ctrl+Z` / `Cmd+Z`: 실행 취소
    - `Ctrl+Shift+Z` / `Cmd+Shift+Z` / `Ctrl+Y`: 다시 실행
  - `handleResizeComponentV4` 핸들러 추가

- **PopCanvasV4.tsx**
  - `onResizeComponent` prop 추가
  - PopFlexRenderer에 전달

- **PopFlexRenderer.tsx**
  - `onComponentResize` prop 추가
  - ComponentRendererV4에 리사이즈 핸들 추가
  - 드래그 이벤트 처리 (mousemove, mouseup)

### 단축키 목록
| 단축키 | 기능 |
|--------|------|
| `Delete` / `Backspace` | 선택된 컴포넌트 삭제 |
| `Ctrl+Z` / `Cmd+Z` | 실행 취소 (Undo) |
| `Ctrl+Shift+Z` / `Ctrl+Y` | 다시 실행 (Redo) |
| `Space` + 드래그 | 캔버스 패닝 |
| `Ctrl` + 휠 | 줌 인/아웃 |

---

## [2026-02-04] v4 통합 설계 모드 Phase 1 완료

### 목표
v4를 기본 레이아웃 모드로 통합하고, 새 화면은 자동으로 v4로 시작

### Added
- **ComponentPaletteV4.tsx** - v4 전용 컴포넌트 팔레트
  - 6개 컴포넌트 (필드, 버튼, 리스트, 인디케이터, 스캐너, 숫자패드)
  - 드래그 앤 드롭 지원

### Changed
- **PopDesigner.tsx** - v3/v4 통합 디자이너로 리팩토링
  - v3/v4 탭 제거 (자동 판별)
  - 새 화면 → v4로 시작
  - 기존 v3 화면 → v3로 로드 (하위 호환)
  - 빈 레이아웃 → v4로 시작 (컴포넌트 유무로 판별)
  - 레이아웃 버전 텍스트 표시 ("자동 레이아웃 (v4)" / "4모드 레이아웃 (v3)")

- **PopCanvasV4.tsx** - 4개 프리셋으로 변경
  - 기존: [모바일] [태블릿] [데스크톱]
  - 변경: [모바일↕] [모바일↔] [태블릿↕] [태블릿↔]
  - 기본 프리셋: 태블릿 가로 (1024x768)
  - 슬라이더 범위: 320~1200px
  - 비율 유지: 슬라이더 조절 시 높이도 비율에 맞게 자동 조정

### Fixed
- 새 화면이 v3로 열리는 문제
  - 원인: 백엔드가 빈 v2 레이아웃 반환 (version 필드 있음)
  - 해결: 컴포넌트 유무로 빈 레이아웃 판별 → v4로 시작

### Technical Details
```
레이아웃 로드 로직:
1. version 필드 확인
2. components 존재 여부 확인
3. version 있고 components 있음 → 해당 버전으로 로드
4. version 없거나 components 없음 → v4로 새로 시작
```

---

## [2026-02-04] Phase 2.1 완료 - 배치 고정 기능 (버그 수정)

### 🔥 주요 버그 수정
- **layoutV4.root 오염 문제 해결**: 다른 모드에서 편집 시 기본 레이아웃이 변경되던 버그 수정
- **tempLayout 도입**: 고정 전 임시 배치를 별도 상태로 관리하여 root를 보호
- **렌더러 병합 로직**: `PopFlexRenderer`에 오버라이드 자동 병합 기능 추가

### 데이터 흐름 개선
1. **기본 모드 (태블릿 가로)**
   - 드래그/속성 변경 → `layoutV4.root` 직접 수정 ✅
   - 모든 다른 모드의 기본값으로 사용

2. **다른 모드 (모바일 세로 등)**
   - 드래그 → `tempLayout` 임시 저장 (화면에만 표시)
   - "고정" 버튼 → `layoutV4.overrides[mode]`에 저장
   - 속성 패널 → 비활성화 + 안내 메시지

3. **렌더링**
   - `tempLayout` 있으면 최우선 표시 (고정 전 미리보기)
   - 오버라이드 있으면 `root`와 병합
   - 없으면 `root` 그대로 표시

### 수정 파일
- `PopDesigner.tsx`: tempLayout 상태 추가, 핸들러 수정
- `PopFlexRenderer.tsx`: 병합 로직 추가 (getMergedRoot)
- `PopCanvasV4.tsx`: tempLayout props 전달
- `ComponentEditorPanelV4.tsx`: 속성 패널 비활성화 로직

---

## [2026-02-04] Phase 3 완료 - visibility + 줄바꿈 컴포넌트

### 추가 기능
- **visibility 속성**: 모드별 컴포넌트 표시/숨김 제어
- **pop-break 컴포넌트**: 강제 줄바꿈 (flex-basis: 100%)
- **컴포넌트 오버라이드 병합**: 모드별 컴포넌트 설정 변경 가능

### 타입 정의
```typescript
interface PopComponentDefinitionV4 {
  // 기존 속성...
  
  // 🆕 모드별 표시/숨김
  visibility?: {
    tablet_landscape?: boolean;
    tablet_portrait?: boolean;
    mobile_landscape?: boolean;
    mobile_portrait?: boolean;
  };
}

// 🆕 줄바꿈 컴포넌트
type PopComponentType = 
  | "pop-field"
  | "pop-button"
  | "pop-list"
  | "pop-indicator"
  | "pop-scanner"
  | "pop-numpad"
  | "pop-spacer"
  | "pop-break";  // 새로 추가
```

### 렌더러 개선
- `isComponentVisible()`: visibility 체크 로직
- `getMergedComponent()`: 컴포넌트 오버라이드 병합
- pop-break 전용 렌더링 (디자인 모드: 점선, 실제: 높이 0)

### 삭제 함수 개선
- `cleanupOverridesAfterDelete()`: 컴포넌트 삭제 시 모든 오버라이드 정리
- containers.root.children 정리
- components 오버라이드 정리
- 빈 오버라이드 자동 제거

### UI 개선
- 속성 패널에 "표시" 탭 추가 (Eye 아이콘)
- 모드별 체크박스 UI
- 반응형 숨김 (hideBelow) 유지
- 팔레트에 "줄바꿈" 컴포넌트 추가

### 사용 예시
```
태블릿 가로:
[A] [B] [C] [D] [E]  ← 한 줄

모바일 세로:
[A] [B]
───────  ← 줄바꿈 (visibility: mobile만 true)
[C] [D] [E]
```

### 수정 파일
- `pop-layout.ts`: 타입 추가, 삭제 함수 수정
- `PopFlexRenderer.tsx`: visibility, 병합, pop-break 렌더링
- `ComponentEditorPanelV4.tsx`: 표시 탭 추가
- `ComponentPaletteV4.tsx`: 줄바꿈 추가

---

## [2026-02-04] v4 타입 및 렌더러

### Added
- **v4 타입 정의** (간결 버전)
  - `PopLayoutDataV4` - 단일 소스 레이아웃
  - `PopContainerV4` - 스택 컨테이너 (direction, wrap, gap, alignItems)
  - `PopComponentDefinitionV4` - 크기 제약 기반 (size: fixed/fill/hug)
  - `PopSizeConstraintV4` - 크기 규칙
  - `PopResponsiveRuleV4` - 반응형 규칙 (breakpoint별 변경)
  - `PopGlobalSettingsV4` - 전역 설정
  - `createEmptyPopLayoutV4()` - 생성 함수
  - `isV4Layout()` - 타입 가드
  - CRUD 함수들 (add, remove, update, find)

- **PopFlexRenderer.tsx** - v4 Flexbox 렌더러
  - 컨테이너 재귀 렌더링
  - 반응형 규칙 적용
  - 크기 제약 → CSS 변환

- **ComponentEditorPanelV4.tsx** - v4 속성 편집 패널
  - 크기 제약 편집 UI
  - 컨테이너 설정 UI

- **PopCanvasV4.tsx** - v4 전용 캔버스
  - 뷰포트 프리셋
  - 너비 슬라이더
  - 줌/패닝

---

## [2026-02-04] (earlier)

### Added
- 저장/조회 시스템 구축
  - rangraph: AI 장기 기억 (시맨틱 검색, 요약)
  - popdocs: 상세 기록 (파일 기반, 히스토리)
  - 이중 저장 체계로 검색 + 기록 분리

### Changed
- popdocs 문서 구조 정리
  - README.md: 저장/조회 규칙 추가
  - 기존 문서 archive/로 이동
- 문서 관리 전략 확정
  - 저장 시: 파일 형식 자동 파악 → 형식 맞춰 추가 → rangraph 요약
  - 조회 시: rangraph 시맨틱 검색

### Removed
- .cursorrules 변경 계획 철회 (Git 커밋 영향)

---

## [2026-02-03]

### Added
- v4 제약조건 기반 레이아웃 계획
  - 단일 소스 + 자동 적응
  - 3가지 규칙 (크기, 배치, 반응형)
  - ADR: `decisions/001-v4-constraint-based.md`

---

## [2026-02-02]

### Fixed
- 캔버스 rowSpan 문제
  - 원인: gridTemplateRows 고정 px
  - 해결: `1fr` 사용

---

## [2026-02-01]

### Fixed
- 4모드 자동 전환 문제
  - 해결: useResponsiveMode 훅 추가

---

## [2026-01-31]

### Added
- v3 섹션 제거, 순수 그리드 구조
- 4개 모드 독립 그리드

---

## [2026-01-30]

### Added
- POP 디자이너 기본 구조
- PopDesigner, PopCanvas 컴포넌트

---

## [2026-01-29]

### Added
- screen_layouts_pop 테이블
- POP 레이아웃 API (CRUD)

---

*최신이 위, 시간순 역순*