PHASE-Z-ROADMAP.md 신설 — 진행 계획 + 세부 todo

문서 역할 분담:
- README        : 프로젝트 개요 + 큰 그림 (가끔 갱신)
- OVERVIEW      : 22 단계 도면 (구조 잠금)
- STATUS-BOARD  : 각 단계 정확한 상태 (자주 갱신)
- CHANGE-LOG    : 결정 변경 이력
- ROADMAP (신규): 진행 계획 + 당장 할 일 + 세부 todo (자주 갱신)

내용:
1. 현재 위치 (MDX03 정상 경로 통과)
2. 지금까지 완료한 작업 6 가지 영역
3. 22 단계 진행 수준 (추정 % 표 + STATUS-BOARD 단일 출처 caveat)
4. 큰 로드맵 7 단계
5. 세부 todo (5.1 보고용 프로토타입 우선 / 5.2~5.8 단계별)
6. 당장 실행 순서 (보고용 프로토타입 → 22 단계 정리 복귀)
7. 문서 역할 분담 표

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/architecture/PHASE-Z-ROADMAP.md

@@ -0,0 +1,301 @@
+# 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 방지.