# Design Agent Frontend MVP - Phase Z Simulation

이 문서는 `design-agent` 프론트엔드 프로젝트가 백엔드 파이프라인(Phase Z)의 각 단계와 어떻게 연결되는지 설명합니다.

---

## 📋 STAGE-to-CODE 매핑 가이드

본 MVP는 백엔드 없이도 파이프라인의 흐름을 시뮬레이션할 수 있도록 설계되었습니다.

### STAGE 1: MDX 분석 (Normalization)
- **백엔드 로직:** `section_parser.py` (H2, H3 태그 및 텍스트 블록 추출)
- **프론트엔드 시뮬레이션:** `designAgentApi.ts` 내 `parseMdxFile()`
  - 파일의 텍스트를 읽어 실제 `#`, `##`, `###` 패턴을 분석합니다.
  - 결과를 `NormalizedContent` 객체로 변환합니다.

### STAGE 2: 레이아웃 매칭 (Zone Mapping)
- **백엔드 로직:** `layout_selector.py` (섹션 개수/성격에 따른 8개 프리셋 선택)
- **프론트엔드 시뮬레이션:** `designAgentApi.ts` 내 `generateSlidePlan()`
  - 분석된 섹션 개수에 따라 `single`, `horizontal-2`, `grid-2x2` 등을 자동으로 결정합니다.
  - 각 섹션을 1280x720 캔버스의 특정 `Zone`에 할당합니다.

### STAGE 3: 프레임 매칭 (V1~V4)
- **백엔드 로직:** `block_reference.py` (Figma 프레임 DB와 콘텐츠 매칭)
- **프론트엔드 시뮬레이션:** `mockDesignAgentData.ts` 및 `FramePanel.tsx`
  - 각 Zone(또는 Region)에 대해 V4 매칭 점수가 높은 Top-3 프레임을 제안합니다.

### STAGE 4: 사용자 조정 (Override)
- **백엔드 로직:** `pipeline.py` (사용자 수동 선택값 반영)
- **프론트엔드 구현:** `Home.tsx` 및 `slidePlanUtils.ts`
  - 사용자가 선택한 Layout이나 Frame 정보를 `UserSelection.overrides`에 저장합니다.
  - `applyLayout`, `applyFrame` 함수가 이 상태 변화를 관리합니다.

### STAGE 5: 최종 조립 및 검증
- **백엔드 로직:** `block_assembler.py` (Jinja2 템플릿 조립 및 Selenium 검증)
- **프론트엔드 구현:** 하단 액션 바의 **Finalize Slide** 버튼
  - 현재 구성된 플랜 데이터를 서버로 전송할 준비가 된 지점입니다.

---

## 🛠️ 핵심 파일 구조

- `client/src/services/designAgentApi.ts`: 파이프라인 단계별 로직 시뮬레이션 핵심.
- `client/src/types/designAgent.ts`: Phase Z 위계(Slide > Zone > Region > Frame) 정의.
- `client/src/components/SlideCanvas.tsx`: 16:9 비율 및 레이아웃 프리셋 시각화.
- `client/src/utils/slidePlanUtils.ts`: 사용자 선택 및 데이터 가공 유틸리티.

---

## 🚀 향후 통합 계획

1. **API 교체:** `designAgentApi.ts`의 시뮬레이션 함수들을 실제 백엔드 엔드포인트 호출로 교체합니다.
2. **실시간 프리뷰:** 백엔드에서 생성된 `final.html`을 캔버스 내 `iframe` 등으로 직접 렌더링하도록 확장합니다.
3. **팝업 연동:** `display_strategy`에 따른 상세 원문 보기 기능을 실제 MDX 원문과 연결합니다.