page-builder/MAIN_PLAN.md

메인 플랜 (Page Builder)

현재 완료된 단계

• builder-1 ~ builder-8: 기본 에디터, 텍스트/버튼/섹션 블록, DnD, Undo/Redo, 블록 삭제/복제 등 핵심 UX 구현
• builder-9-templates-advanced (현재 브랜치):
  • Hero / Features / CTA / FAQ / Pricing / Testimonials / Blog / Team / Footer 템플릿 섹션
  • 프리뷰 페이지 및 모바일 뷰포트 E2E
  • CI 환경에서 Prisma Client generate + API 테스트용 DATABASE_URL 설정
  • API 테스트에서 Prisma를 메모리 기반 목으로 교체하여 DB 없이 테스트 통과

다음 단계 개요

1. builder-10-block-types

   • 더 다양한 블록 타입 추가 (예: 이미지, 아이콘이 있는 카드, 구분선, 리스트 등)
   • Zustand store에 타입/props 정의 및 액션 추가
   • 에디터 UI에 새 블록 버튼 및 속성 패널 연동
   • 새 블록 타입에 대한 유닛 테스트 + E2E 테스트 추가

2. builder-11-editor-ux-advanced

   • 드래그앤드롭 UX 고도화 (섹션/컬럼 이동 UX 개선, 드롭 힌트 강화)
   • 키보드 숏컷 확장 및 포커스 관리 개선
   • 인라인 편집 UX 다듬기

3. builder-12-theme-output

   • Tailwind 기반 디자인 시스템 정리 (색상/타이포/간격 스케일)
   • Public/Preview 렌더링 품질 개선 (반응형, 여백, 타이포그래피)
   • 샘플 테마 프리셋 추가

---

builder-10-block-types 상세 플랜

1) 대상 블록 타입 정의

• 이미지 블록(image)
  • props: src, alt, align, width, borderRadius 등
• 구분선(divider)
  • props: style (solid/dashed), thickness, color, marginY
• 리스트(list)
  • props: items (문자열 배열), ordered (true/false), align
• (필요시) 카드(card)
  • props: title, description, imageSrc, align

※ 실제 구현 범위는 TDD를 진행하면서 우선순위 높은 것부터 차례대로 확장한다.

2) TDD 순서

1. 유닛 테스트부터 작성 (실패 상태로 시작)
   • tests/unit/editorStore.spec.ts
     • addImageBlock, addDividerBlock, addListBlock 등 새 액션 테스트 추가
     • 블록이 올바른 기본 props 와 함께 blocks 배열에 추가되는지 확인
     • 섹션/컬럼 내부에 배치되는 경우 위치 정보(sectionId, columnId) 테스트
2. 스토어 구현 (editorStore.ts)
   • Block 타입에 새 type 과 props 구조 추가
   • EditorState에 새 액션 시그니처 추가
   • createEditorState 내부에 실제 로직 구현 (createId 활용, 기존 텍스트/버튼/섹션 패턴 재사용)
3. 에디터 UI 연동 (editor/page.tsx)
   • 사이드바에 새 블록 버튼 추가 (이미지, 구분선, 리스트 등)
   • 캔버스 렌더링 분기에 새 블록 타입별 렌더링 로직 추가
   • 속성 패널에서 최소한의 필수 props 편집 가능하도록 구현
4. E2E 테스트 추가 (Playwright)
   • tests/e2e/editor.spec.ts
     • 새 블록 타입 버튼 클릭 → 캔버스에 올바르게 렌더링되는지 확인
     • 속성 패널에서 값 수정 시 캔버스 반영 확인 (예: 이미지 src, 리스트 아이템 수정)
5. 리팩터링 & 안정화
   • 중복되는 렌더링/props 처리 로직 정리
   • 필요시 추가 유닛 테스트/E2E로 회귀 방지

---

builder-11-editor-ux-advanced 상세 플랜

1) DnD UX 고도화

• 목표

  • 블록/섹션 드래그앤드롭이 시각적으로 명확하고, 의도한 위치로 안정적으로 이동하도록 개선
  • 2컬럼 섹션 컬럼 이동, 블록 순서 변경 관련 E2E를 CI에서도 신뢰할 수 있게 만들기

• 작업 항목 (TDD)

  1. tests/e2e/editor.spec.ts
     • "블록 드래그앤드롭으로 순서를 변경할 수 있어야 한다" 시나리오를 현재 UX에 맞게 단순/안정화
     • "2컬럼 섹션에서 블록을 다른 컬럼 영역으로 드래그하면 컬럼이 변경되어야 한다" 시나리오를 실제 드롭 영역 구조에 맞춰 조정
  2. EditorPage/SortableEditorBlock
     • 드롭 대상 컬럼/섹션의 hit-area를 넓히거나, 불필요한 overlay가 pointer events를 가로채지 않게 레이아웃 조정
     • DnD Kit 설정(sensors, collision detection 등) 필요 시 보정
  3. 필요 시 editorStore 유닛 테스트에서
     • reorderBlocks, moveBlock 조합 케이스(섹션/컬럼 간 이동)를 명시적으로 테스트해 회귀 방지

2) 키보드/포커스 UX 개선

• 목표

  • ArrowUp/ArrowDown 으로 선택 블록이 예측 가능하게 이동
  • Cmd/Ctrl+Z / Cmd/Ctrl+Shift+Z / Cmd/Ctrl+D 와 같은 단축키가 OS에 관계없이 일관되게 동작

• 작업 항목 (TDD)

  1. tests/e2e/editor.spec.ts
     • "ArrowUp/ArrowDown 키로 선택된 블록을 위/아래로 이동하며 순차적으로 선택할 수 있어야 한다" 테스트를 CI에서도 통과하도록 재정의
       • 초기 선택 상태, 포커스 위치, 기대되는 data-selected/aria-selected 값을 명확히 기술
  2. EditorPage의 전역 keydown 핸들러
     • ArrowUp/Down 선택 이동 로직을 단순/명확하게 정리 (현재 선택이 없을 때 첫 블록 선택 등)
     • OS별 Cmd/Ctrl 판별 로직(navigator.platform)과 E2E에서 보내는 키 조합을 일치시켜 유지

3) 인라인 편집 UX 정리

• 목표

  • 텍스트 블록 더블클릭 → 인라인 편집 진입
  • Enter → 커밋, Esc → 취소, 포커스 아웃 시 안전하게 커밋

• 작업 항목 (TDD)

  1. tests/e2e/editor.spec.ts
     • "텍스트 블록을 더블클릭해서 내용을 수정할 수 있어야 한다" 시나리오를
       • 더블클릭 → 편집 모드 진입
       • Enter 커밋 / Esc 취소 흐름까지 포함하도록 보완
  2. EditorPage의 인라인 편집 상태(editingBlockId, editingText)
     • 더블클릭/포커스 아웃/Enter/Esc 이벤트에 대한 상태 전이와 updateBlock 호출 타이밍을 명확히 정의

이 모든 작업도 builder-10과 동일하게 실패하는 테스트 추가 → 최소 구현 → 리팩터링 → CI/E2E 확인 순서로 진행한다.

---

디버깅/CI 관련 기록 (요약)

• CI에서 prisma generate 단계가 DATABASE_URL 없음으로 실패 → 워크플로에서 더미 DATABASE_URL 주입으로 해결

• 유닛 테스트에서 API 테스트가 실제 DB 접속 시도 →

  • CI: Run unit tests 스텝에도 더미 DATABASE_URL 추가
  • 테스트 코드: PrismaClient를 메모리 기반 목으로 교체, 라우트를 동적 import 하도록 수정

• Playwright E2E (에디터):

  • 레이아웃 상 사이드바/속성 패널이 캔버스 블록 클릭을 가로채면서 locator.click 타임아웃이 발생하는 이슈 확인
  • divider/list 블록용 E2E는 블록 추가 직후 자동 선택 상태와 속성 패널 조작만 검증하도록 작성해 부분적으로 우회
  • 기존 테스트들(블록 삭제, 복제, 키보드 이동 등)은 동일한 클릭 간섭 문제 영향 범위에 있어 후속 단계에서 레이아웃/테스트 전략 리팩터링 필요

이후 단계(builder-11-editor-ux-advanced, builder-12-theme-output)에서도 모든 기능 추가는 TDD(실패 테스트 → 구현 → 리팩터링) 순서를 유지한다.