C.E.L_Slide_test2/docs/architecture/PHASE-Z-ROADMAP.md

Phase Z 진행 현황 및 향후 Todo

문서 성격: 진행 계획 + 당장 할 일 + 세부 todo. 자주 갱신. 작성일: 2026-05-08 역할 분담: 본 문서는 진행 계획. 정확한 단계별 상태는 PHASE-Z-PIPELINE-STATUS-BOARD.md, 결정 변경 이력은 PHASE-Z-CHANGE-LOG.md, 22 단계 도면은 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 가 단일 출처.

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

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