# Phase Z Roadmap

**문서 성격**: 앞으로의 진행 순서 + 큰 axis + 우선순위. *자주 갱신*.
**작성일**: 2026-05-08 (frontend 통합 session 반영)
**문서 역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`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).

> **현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한 `PROCESS_OVERVIEW.html` 프로토타입을 먼저 만드는 것이다.**

---

## 1. 현재 위치

- MDX03 정상 경로 통과 (PASS)
- Phase Z 22 단계 파이프라인 일반화 진행 중
- 보고용 프로토타입을 먼저 작성 예정

### 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 시각 점검 통과 / Step 20 상태 통과
- F29 missing asset bug 수정 완료
- missing image count = 0 / full MDX coverage = true

---

## 2. 이번 session 에서 닫힌 작업

이번 session 에서 closed 된 axis 목록:

- Step 5 보완 — V4 rank-1 → non-reject 최대 6 개 후보 list
- Step 6-A — `CompositionUnit` 에 `v4_candidates` 필드 추가 (additive, logic 무변)
- Step 7-conn — `select_layout_candidates` artifact 연결
- Step 8-conn — region / display candidates artifact 연결 (placeholder)
- Step 9 v0 — passive `application_plan` artifact (V4 후보 적용 계획 trace)
- cleanup-1 — stale 주석 (`pipeline 호출처 X`) 정정
- F29 visual fidelity 정정 — missing SVG → CSS gradient 재현
- README 통합 갱신 — 한글 / 22-step Mermaid / 로드맵 Mermaid
- push 완료 — origin (GitHub) + slide2 (Gitea)

### 2-B. Frontend 통합 session 닫힌 작업 (보고용 1차 초안)

frontend (`design_agent_front/design-agent`) 와 backend phase_z2 의 연결 axis :

- **Vite plugin endpoint 들** — 외부 backend 없이 단일 dev server 안에서 spawn :
  - `POST /api/run` (overrides body 받아 CLI 인자로 forward)
  - `GET /data/runs/{run_id}/{path}` (run artifact serving)
  - `GET /frame-preview/{frame_number}` (`data/figma_previews/{NN}.png` 서빙)
  - `GET /api/sample-mdx` (데모용 fixed mdx03 자동 로드)
- **Backend Step 7-A (override CLI 인자)** :
  - `--override-layout PRESET` (8 preset 중 하나 강제)
  - `--override-frame UNIT_ID=TEMPLATE_ID` (multiple)
  - `--override-zone-geometry ZONE_ID=X,Y,W,H` (multiple, horizontal-2 / vertical-2 만 적용)
  - catalog 미등록 frame 보호 — `frame_overrides_skipped` trace
- **Backend trace 확장** — `step09.units[].v4_all_judgments` (reject 포함 32 entry, `catalog_registered` flag, `frame_overrides_applied/skipped`, `layout_override_applied`, `auto_layout_preset`)
- **Frontend SlideCanvas** :
  - iframe 안 `.zone[data-zone-position]` + `.slide-body` boundingClientRect 측정 → zone overlay 좌표 정확
  - iframe contentDocument CSS injection (html/body margin/padding/min-height 강제 — standalone 표시용 잘림 방지)
  - 8 preset layout 별 zone overlay rendering
  - frame top-6 표시 + V4 label badge + figma_previews thumbnail + catalog 미등록 회색 차별
  - selected frame preview overlay (반투명 미리보기)
  - section drag-drop drop target (LeftMdxPanel 의 native drag → SlideCanvas zone drop)
  - **HTML 편집 모드** (글벗 editor.js 패턴 차용 : designMode + contentEditable + outline CSS) — 텍스트 변경 시 `hasPendingChanges` 트리거
  - **pendingLayout 모드** — 다른 layout "적용하기" → slide-body 영역만 빈 layout 으로 전환 + zone resize 8 방향 handle (edge × 4 + corner × 4) + section drag drop 자동 carry over
  - "선택대로 재생성하기" 버튼 — `userSelection.overrides` → `PipelineOverrides` 변환 후 `/api/run` forwarding
- **Frontend MDX 트리 분해 (frontend re-parse)** — `parseMdxText` 가 `##` 중목차 + `###` 소목차 분해. `loadRun` 에서 backend section 의 `raw_content` 앞에 `## __ROOT__` prefix 임시 추가해서 sub_sections 추출 (Stage 0 normalize 가 backend 에 통합 안 된 임시 우회)
- **데모 fixed input** — 페이지 로드 시 자동 `samples/mdx/03 ...` fetch → 사용자 업로드 단계 skip

각 axis 상세 의사결정 / 폐기 / lock 은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) 참조.

---

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

> 아래 수치는 MDX03 정상 경로 기준의 *추정 진행률*이다.
> 22 단계별 공식 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 를 *single source of truth* 로 한다.

| 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 | 사용자 확인 / 내보내기 | 10% |

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

---

## 4. 큰 로드맵

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

자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조. 샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*.

---

## 5. 우선순위 (2026-05-08 갱신 — frontend 통합 session 후)

```
0. 보고용 link 1차 (현재 — 닫는 중)

1. §7-B 항목별 목적 / input / output 정리 + Phase Q audit & salvage
   - 먼저 lens 잡고 (각 보완 항목의 목적·input·output)
   - 그 lens 로 Phase Q 모듈 10 개 검토 (Keep / Migrate / Reference / Delete)
   - 통합 정책은 [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) §0-A 따름 (10 원칙 lock)
   - 산출물: docs/architecture/PHASE-Q-AUDIT.md

2. 22 단계 backend 본체 보완
   - audit 결과 반영 (Migrate 항목 우선 통합)
   - frontend session 에서 발견된 보완 지점 (§7-B A 그룹) 반영
   - Stage 0 normalize / V4 fallback / zone 좌표 export / slide-base iframe / catalog 확장 등

3. Frontend 추가 보완 (AI 투입 / HTML 수정 backend 적용 / DB 연결)
   - §7-B B 그룹 (zone-section assignment / edited HTML → MDX 등)
   - §7-B D 그룹 (filtered reason UI / min_height 한계 / status badge 안내)

4. 전체 일반화 + 시스템 audit
   4a. MDX 01 / 02 / 04 fresh run (regression / status / coverage 검증)
   4b. 코드 audit (dead code / stale comment / type drift)
   4c. frame catalog audit (등록 수 / contract 일관성 / preview.png 일관성)
   4d. DB / data 활용 audit (assets / runs / static 폴더 정리 수준)

5. Clean up (4 의 결과를 input 으로)
```

§7-B 의 항목 구현 순서는 §1 의 audit 결과로 재정렬됨 — 본 §5 가 최상위 axis.

---

## 6. 보고용 프로토타입 계획

**파일**: `PROCESS_OVERVIEW.html` (기존 갱신) 또는 `PHASE_Z_REPORT_PROTOTYPE.html` (신규).

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

**목적**:
- 현재 파이프라인 구조 설명
- MDX03 결과 시각적으로 보여줌
- 미구현 영역 명확히 표시
- 향후 front / AI / DB / editor 방향에 대한 피드백 수집

---

## 7. Pipeline 복귀 후 Todo

보고 / 피드백 수집 후 22 단계 안정화 작업 재개. 우선순위 후보:

- **MDX04 검증** — `samples/mdx_batch/04.mdx` fresh run → status / rank-1 frame / 미연결 여부 확인
- **시각 점검 확장** (Step 14 보강) — 누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사
- **프레임 어댑터 확장** — Figma / V4 에는 있지만 Phase Z 에 미연결인 frame 의 contract / partial / builder 추가
- **MDX 정규화 보강** (Step 2 / 3 / 4) — Content Object 추출 + Internal Composition Planning 활성화
- **Step 21 디버그 추적 보강** — schema 채우기 (현재 빈 상태)
- **MDX01 / 02 검증** — 다른 sample 로 일반화 확장

이 후 단계 = 큰 로드맵의 §2 ~ §7 (Phase Q audit → AI repair → DB → 프론트 → HTML 수정 → frame 지속).

---

## 7-B. Frontend 통합으로 드러난 보완 지점 (2026-05-08)

이번 frontend session 에서 *기능적인 것을 해결하기 위해 frontend 가 임시로 채운 부분* + *backend 본체가 보완해야 의미 있는 axis* 정리.

> **본 표는 §5 의 1 단계 audit lens** — 각 항목의 *목적 / input / output* 을 먼저 채우면 Phase Q 모듈 검토 시 *명확한 질문* 이 됨 ("이 schema 와 같은 코드가 Phase Q 에 있나? Migrate / Reference / Delete 어느 쪽?"). audit 결과로 본 §7-B 의 구현 우선순위가 재정렬됨.

### A. Backend 본체 보완 (큰 axis)

| # | 항목 | 이유 / 영향 | 임시 대체 |
|---|---|---|---|
| A-1 | **Stage 0 normalize 통합** — `mdx_normalizer.normalize_mdx_content` 를 phase_z2 가 호출 | 표준 input (정리된 bullet MDX) 외 (HTML-heavy raw) 입력 처리 못 함. step03 추출이 1 ContentObject 로 뭉침 → cardinality strict frame 과 mismatch → filter | frontend 가 raw_content 앞에 `## __ROOT__` prefix 붙여 sub_sections 만 추출. content_objects 는 통째로 (별 axis 보류 — `project_phase_z_normalize_gap.md`) |
| A-2 | **Catalog 확장** — frame_contracts.yaml + frame_partials 더 많은 frame 등록 (현재 3 개 → 32 개 목표) | 사용자 frame 변경 의미 거의 불가 (V4 32 후보 중 use_as_is/light_edit 만 있어도 catalog 미등록이면 backend 가 skip). MDX03 외 다른 sample 일반화 어려움 | frontend 가 `catalog_registered: false` 카드 시각 차별 + handleGenerate 에서 forward 미시도. 사용자에게 "catalog 미등록 — render path 미연결" toast |
| A-3 | **Frame preview png 일관성** — 모든 catalog frame 의 일관된 preview.png 자동 생성 | `figma_to_html_agent/blocks/{frame_id}/preview.png` 가 inconsistent (일부 frame 만 존재). frontend 가 어떤 source 든 통일해야 | 32 개 모두 있는 `data/figma_previews/{NN}.png` (Figma original export) 사용. frame 별 *실제 렌더 결과* 가 아닌 *Figma 디자인* 표시 |
| A-4 | **slide-base.html iframe-friendly mode** — body padding / centering / min-height 가 standalone 모드용. iframe embed 시 잘림 | frontend 가 매 iframe onLoad 마다 contentDocument 에 reset CSS 주입 (모든 frame 영향) | frontend CSS injection 으로 우회. 진짜 fix 는 slide-base 가 query string `?embedded=1` 같은 시그널 받아 conditional padding |
| A-5 | **V4 후보 자동 fallback** — rank-1 capacity / cardinality / structure mismatch 시 자동 rank-2/3 시도 | 03-1 처럼 rank-1 (`three_parallel_requirements`, strict cardinality 3) 가 추출 0 items 와 mismatch → filtered_capacity. 사용자 입장에서 "왜 빠졌는지" 알기 어려움 | (없음. frontend 는 reject + filtered 결과를 그대로 받아 표시) |
| A-6 | **Zone DOM 좌표 export** — backend 가 `.zone[data-zone-position]` / `.slide-body` 의 절대 px 좌표를 step08 또는 별도 step 에 export | frontend 가 매 iframe onLoad 마다 boundingClientRect 측정 — 비용 + iframe 안 DOM 변경 시 stale | (없음. iframe 측정으로 우회) |

### B. Backend Override path 확장 (Step D-ext 나머지)

| # | 항목 | 이유 |
|---|---|---|
| B-1 | **Zone-section assignment override** — `--override-section-assignment ZONE_ID=section_id,section_id` CLI 인자 + composition planner 의 자동 결정을 user override 로 강제 | pendingLayout 모드의 section drag drop 결과가 backend 에 적용되도록. 현재 frontend visual 만 |
| B-2 | **Edited HTML → MDX 역변환** — 글벗의 `html_to_slide_mdx` 패턴 차용. frontend 의 `iframe.contentDocument.querySelector('.slide').outerHTML` → backend → MDX → pipeline 재실행 | 편집 모드에서 사용자가 텍스트 수정한 결과가 새 final.html 에 반영. 현재 frontend visual 만 |
| B-3 | **Sub-section (### 단위) drag drop 처리** — backend 가 sub-section id 를 인식해서 zone 에 sub-section 단위로 매핑 | LeftMdxPanel 의 트리 (S1.1, S1.2 ...) drag drop 결과가 의미 있게 적용되도록 |
| B-4 | **다른 layout 의 zone-geometry override** — 현재 horizontal-2 / vertical-2 만. top-1-bottom-2 / top-2-bottom-1 / left-1-right-2 / left-2-right-1 / grid-2x2 도 지원 | 사용자가 어떤 layout 에서든 자유 zone resize 가능 |

### C. Frontend 일관성 정리 (drift 정리)

| # | 항목 |
|---|---|
| C-1 | `userSelection.selectedZoneId` schema — `zone.id` (e.g., `zone-03-1`, `pending-zone-N`) vs `zone.zone_id` (e.g., `top`, `primary`) 양쪽 매칭 일관화 |
| C-2 | `zone_sections` / `zone_geometries` / `zone_frames` 의 key 통일 (zone_id 또는 region.id) |
| C-3 | `effectiveSlidePlan` swap 로직이 누락된 component 정리 (FramePanel / LayoutPanel / 기타) |
| C-4 | Toaster 제거 후 inline status bar 도입 (선택) — 현재 toast 호출은 silent (비표시) |
| C-5 | resize 좌표 schema 통일 (slide-body 내부 0~1 vs 1280×720 절대) — pendingLayout 만 활성으로 단순화한 상태이지만 향후 다양한 mode 지원 시 명확화 |

### D. UX 보완

| # | 항목 |
|---|---|
| D-1 | **filtered_section_reasons 노출 UI** — backend `step20_slide_status.json` 의 filter 사유를 frontend 가 헤더 / 패널에 표시 (Step 8 coverage UI) |
| D-2 | **Zone resize 시 frame min_height 한계 표시** — frame contract 의 min_height_px 를 frontend 가 받아서 resize limit + visual hint |
| D-3 | **데모 외 사용자 업로드 흐름 일관화** — 자동 mdx03 로드와 사용자 직접 업로드의 시각 차별. "데모 모드" 표시 |
| D-4 | **Step 20 status badge 의미 안내** — PASS / RENDERED_WITH_VISUAL_REGRESSION / PARTIAL_COVERAGE 의 사용자 친화 설명 |

---

## 8. 문서 역할 분담

| 문서 | 역할 | 갱신 빈도 |
|---|---|---|
| [`README.md`](../../README.md) | 외부 / 내부 공유용 프로젝트 개요 | 가끔 (큰 방향 변경 시) |
| [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md) | 22 단계 도면 (구조 잠금) | 거의 안 바뀜 |
| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 22 단계별 현재 상태의 single source of truth | 자주 |
| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 의사결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
| **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** |
| [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) | Phase Q 모듈의 Keep / Migrate / Reference / Delete 결정 + Salvage Plan + ROADMAP §7-B 우선순위 재정렬의 input | audit 진행 중 (모듈별로 1 turn) |
| `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 |

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