# Phase Z 진행 현황 및 향후 Todo

**문서 성격**: 진행 계획 + 당장 할 일 + 세부 todo. *자주 갱신*.
**작성일**: 2026-05-08
**역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md), 결정 변경 이력은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md), 22 단계 도면은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).

---

## 1. 현재 위치

Design Agent 는 MDX 문서를 입력받아 프레젠테이션 슬라이드 HTML 로 자동 변환하는 Phase Z 파이프라인을 구축 중. 현재까지는 MDX03 을 기준으로 22 단계 파이프라인의 정상 경로를 검증함.

### 1.1 MDX03 현재 결과

- V4 rank-1 frame 적용 완료
  - `03-1 → F13 / three_parallel_requirements` (그대로 사용 가능, 0.927)
  - `03-2 → F29 / process_product_two_way` (그대로 사용 가능, 0.920)
- rank 2~6 후보는 Step 9 의 `application_plan` 에 보존 (향후 사용자 선택용)
- `final.html` / `preview.png` 생성
- Step 14 시각 점검 통과 (visual_check_passed = true)
- Step 20 슬라이드 상태 통과 (overall = PASS)
- F29 missing asset bug 수정 완료
- missing image count = 0
- full MDX coverage = true

```
MDX03 기준 자동 슬라이드 생성 정상 경로 통과
다만 전체 22 단계 파이프라인은 일반화 단계이며, MDX01 / 02 / 04 등으로 검증을 확장해야 한다.
```

---

## 2. 지금까지 완료한 주요 작업

### 2.1 Slide base / spacing / typography 정리

- slide canvas: 1280×720
- title / divider / body / footer 위치 정리
- body height: 585
- grid gap: 14
- 5-layer typography 위계 정리 (대 16px / 소 12px / 콘텐츠 10px / ...)

### 2.2 Layout 카탈로그 정리

코드 dict 에 박혀 있던 layout 을 사람이 보고 수정할 수 있는 yaml 카탈로그로 분리.

- `templates/phase_z2/layouts/layouts.yaml` (8 개 preset)
- `templates/phase_z2/layouts/layouts_preview.html`
- 추가 함수: `select_layout_candidates(unit_count)`

8 개 layout: `single` / `horizontal-2` / `vertical-2` / `top-1-bottom-2` / `top-2-bottom-1` / `left-1-right-2` / `left-2-right-1` / `grid-2x2`

### 2.3 Region / Internal Region 카탈로그 정리

zone 안의 콘텐츠 배치 단위 (Internal Region) + 콘텐츠 표시 정책 (display strategy) 을 분리.

- `templates/phase_z2/regions/region_layouts.yaml` (6 개)
- `templates/phase_z2/regions/display_strategies.yaml` (4 개)
- `templates/phase_z2/regions/regions_preview.html`

핵심 원칙:
- **region_layout** = zone 내부 구조
- **display_strategy** = 콘텐츠 처리 정책
- `dropped` 는 decorative 요소에만 허용
- text / table / image / details 는 dropped 절대 금지

### 2.4 V4 후보 보존

기존: V4 rank-1 만 파이프라인에 들어옴 → rank 2~6 사라짐.
현재:
- rank-1 은 렌더에 사용 (정책 무변)
- non-reject 최대 6 개 후보 보존
- Step 9 의 application_plan 에 모든 후보 기록

### 2.5 Step 9 application_plan v0

Step 9 를 *frame 재평가* 가 아니라 *V4 후보를 어떻게 적용할지 번역* 으로 재정의.

V4 라벨 → 적용 방식 변환:
- `그대로 사용` → 바로 삽입
- `가벼운 편집` → 같은 프레임에 약간 조정
- `재구성` → 레이아웃 / Region 변경 (자동 X, 사람 확인)
- `거절` → 제외

### 2.6 F29 시각 fidelity 정정

F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수정.

- 수정 전: `header_left_bg.svg` / `header_right_bg.svg` / `body_bg.svg` 참조 (모두 없음)
- 수정 후: 원본 Figma HTML 처럼 CSS gradient 로 재현
- missing image 0 확인

---

## 3. 현재 22 단계 진행 수준

> ⚠️ 아래 % 는 *추정치*. 정확한 ✅ / ⚠ / ❌ 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 가 단일 출처.

| Step | 단계 | 추정 % |
|---|---|---|
| 0 | 사전 준비 / 카탈로그 / 컨트랙트 | 65% |
| 1 | MDX 업로드 | 100% |
| 2 | MDX 정규화 | 65% |
| 3 | Content Object 추출 | 45% |
| 4 | Internal Composition Planning | 40% |
| 5 | V4 매칭 후보 추출 | 85% |
| 6 | 구성 계획 | 80% |
| 7 | 슬라이드 레이아웃 계획 | 85% |
| 8 | Zone / Region 비율 계획 | 75% |
| 9 | 적용 계획 (application_plan) | 70% |
| 10 | 프레임 컨트랙트 확인 | 65% |
| 11 | 슬롯 매핑 | 45% |
| 12 | 슬롯 데이터 생성 | 85% |
| 13 | HTML 렌더 | 85% |
| 14 | 시각 점검 | 70% |
| 15 | 문제 분류 | 80% |
| 16 | 재시도 라우터 | 85% |
| 17 | 조치 실행 | 40% |
| 18 | 실패 분류 | 85% |
| 19 | 다음 조치 제안 | 60% |
| 20 | 슬라이드 상태 결정 | 95% |
| 21 | 디버그 / 추적 기록 | 45% |
| 22 | 사용자 확인 / 내보내기 | 20% |

전체 요약:
- MDX03 정상 경로 = 완료
- 22 단계 일반화 = 약 **65~70%**
- 제품형 전체 = 중간 단계

---

## 4. 앞으로의 큰 로드맵

전체 방향은 다음 순서로 간다 (자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조):

```
1. 22 단계 파이프라인 안정화 (현재)
2. Phase Q 재검토 후 Phase Z 반영
3. AI 보정 / 재구성 단계
4. DB / 카탈로그 정리
5. 프론트엔드 연결
6. HTML 수정 기능 추가
7. 프레임 지속 업데이트
```

샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*.

---

## 5. 세부 Todo

### 5.1 보고용 프로토타입 작성 — 우선 진행

현재 가장 먼저 할 일은 *실제 개발 진행이 아니라*, 보고와 피드백을 위한 프로토타입 작성.

**목적**:
- 현재 파이프라인이 어떤 구조인지 설명
- MDX03 결과를 시각적으로 보여줌
- 22 단계 흐름 설명
- layout / region / frame / application_plan 개념 설명
- 아직 미구현인 부분 명확히 표시
- 향후 front / AI / DB / editor 방향에 대한 피드백 수집

**보고용 프로토타입에 포함할 내용**:
- 프로젝트 개요
- MDX03 실제 결과 (preview.png / final.html / PASS status)
- 22 단계 파이프라인 타임라인
- V4 rank 후보 예시
- Layout / Region / Frame 설명
- Step 9 application_plan 예시
- 아직 미구현인 기능 (HTML 수정 / 이미지 크기 조정 / AI 보정 / DB / 프론트 에디터)
- 향후 로드맵

**프로토타입 후보 파일**:
- `PROCESS_OVERVIEW.html` (기존 파일 갱신)
- 또는 `PHASE_Z_REPORT_PROTOTYPE.html` (신규)

### 5.2 22 단계 파이프라인 정리 (보고 이후 복귀)

주요 작업:
- 프레임 ↔ Phase Z 연결 구조 정리 (V4 frame 후보 → Phase Z 렌더 경로 연결 확장)
- 시각 점검 범위 확장 (누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사)
- MDX 정규화 / 정리 방식 보완 (Step 2 / 3 / 4)
- MDX 01 / 02 / 04 검증을 통한 예외 케이스 보완
- Step 21 디버그 추적 보강

### 5.3 Phase Q 재검토 및 반영

기존 `src/` 안 옛 25 개 모듈 검토.

분류 기준:
- **keep as-is** — 다른 곳에서 사용 중
- **migrate to Phase Z** — 도메인 가치 있음, Phase Z 로 이식
- **reference only** — 학습 자료로만 보존
- **delete** — 완전 obsolete

검토 후보 (도메인 가치 추정):
- `slide_measurer.py` — Selenium 측정 정밀도 (현재 Phase Z 보다 정교할 가능성)
- `space_allocator.py` — zone 분배 로직
- `content_editor.py` — AI 콘텐츠 편집 (fallback path 영역)
- `content_verifier.py` — 콘텐츠 검증
- `fit_verifier.py` — fit 평가 (Phase Z router 와 다른 시각)
- `block_reference.py` — block reference 시스템

### 5.4 AI 보정 / 재구성 단계

대상 케이스:
- V4 점수가 낮은 경우
- 후보가 모두 거절인 경우
- 가벼운 편집 필요
- 재구성 필요
- 오버플로우 반복
- 그대로 frame 에 넣기 어려운 경우

원칙:
- MDX 원문 보존
- AI 는 *삭제가 아니라* 재구성 / slot 재배치 / popup 전환 제안
- 자동 적용 가능 여부와 사람 확인 필요 여부를 추적에 기록

### 5.5 DB / 카탈로그 정리

현재는 파일 기반. 향후 DB 화 대상:
- 프레임 카탈로그 / 컨트랙트
- 레이아웃 카탈로그
- region / display 카탈로그
- V4 결과
- 실행 이력
- 단계별 산출물
- 사용자 변경 이력
- 선택 이력 (어떤 후보를 골랐는지)

### 5.6 프론트엔드 연결

프론트 위치: `D:\ad-hoc\kei\design_agent_front\design-agent`

초기 목표는 *editor 가 아니라 read-only viewer*.

1 차로 보여줄 것:
- 실행 목록
- preview.png / final.html
- 22 단계 타임라인
- V4 1~6 위 후보
- 레이아웃 / Region / 적용 계획
- 시각 점검 결과
- 최종 상태

### 5.7 HTML 수정 기능

프론트 연결 이후 editor 기능 추가.

기능:
- 텍스트 수정
- 이미지 크기 / 위치 조정
- 프레임 후보 변경 (V4 1 위 외 다른 위 선택)
- 레이아웃 / Region 조정
- 팝업 / 자세히보기 선택
- 내보내기

원칙:
- `final.html` 직접 영구 수정 X
- `user_overrides.json` 형태로 저장
- MDX 원문 보존

### 5.8 프레임 지속 업데이트

Figma 와 V4 에는 있으나 Phase Z 런타임에 연결되지 않은 프레임을 계속 어댑터로 연결.

프레임 하나당 필요한 작업:
1. `templates/phase_z2/catalog/frame_contracts.yaml` (컨트랙트 entry)
2. `templates/phase_z2/families/{template_id}.html` (Phase Z 런타임 partial)
3. `src/phase_z2_mapper.py` (PAYLOAD_BUILDERS / ITEM_PARSERS entry)
4. fresh run 검증

---

## 6. 당장 실행 순서

```
1. 보고용 프로토타입 작성        ← 지금 당장 할 일
2. 보고 / 피드백 수집
3. Phase Z 파이프라인 작업 복귀
4. 22 단계 정리 계속
5. 이후 Phase Q 검토 → AI → DB → 프론트 → 에디터 순서로 확장
```

---

## 7. 문서 역할 분담

본 프로젝트의 문서들은 다음과 같이 책임이 분리됨:

| 문서 | 역할 | 갱신 빈도 |
|---|---|---|
| [`README.md`](../../README.md) | 프로젝트 개요 + 22 단계 / 로드맵 / 운영 원칙 | 가끔 (큰 방향 변경 시) |
| [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md) | 22 단계 도면 (구조 잠금) | 거의 안 바뀜 |
| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 각 단계의 정확한 상태 (✅ / ⚠ / ❌) | 자주 |
| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
| **`PHASE-Z-ROADMAP.md`** (본 문서) | **진행 계획 + 당장 할 일 + 세부 todo** | **자주** |
| `PROCESS_OVERVIEW.html` (또는 `PHASE_Z_REPORT_PROTOTYPE.html`) | 보고용 시각 자료 | 보고 시점 |

각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.