18 KiB

Raw Blame History

POP 변경 이력

형식: Keep a Changelog

[미출시]

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

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

// 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

// 고정 로직
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에 오버라이드 자동 병합 기능 추가

데이터 흐름 개선

기본 모드 (태블릿 가로)
- 드래그/속성 변경 → layoutV4.root 직접 수정 ✅
- 모든 다른 모드의 기본값으로 사용
다른 모드 (모바일 세로 등)
- 드래그 → tempLayout 임시 저장 (화면에만 표시)
- "고정" 버튼 → layoutV4.overrides[mode]에 저장
- 속성 패널 → 비활성화 + 안내 메시지
렌더링
- 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%)
컴포넌트 오버라이드 병합: 모드별 컴포넌트 설정 변경 가능

타입 정의

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)

최신이 위, 시간순 역순

18 KiB Raw Blame History

POP 변경 이력

[미출시]

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

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

popdocs 문서 구조 재정비

Breaking Changes

Added

Removed

Changed

Technical Details

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

Added

Changed

Technical Details

UI 변경

주의사항

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

Added

Changed

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

Added

Changed

Technical Details

Fixed

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

Added

Changed

Technical Details

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

Added

Changed

단축키 목록

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

목표

Added

Changed

Fixed

Technical Details

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

🔥 주요 버그 수정

데이터 흐름 개선

수정 파일

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

추가 기능

타입 정의

렌더러 개선

삭제 함수 개선

UI 개선

사용 예시

수정 파일

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

Added

[2026-02-04] (earlier)

Added

Changed

Removed

[2026-02-03]

Added

[2026-02-02]

Fixed

[2026-02-01]

Fixed

[2026-01-31]

Added

[2026-01-30]

Added

[2026-01-29]

Added

18 KiB

Raw Blame History