From 0a9327c50c3eca38cf64193fa6c9e2b4f0dc8e61 Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Fri, 8 May 2026 10:31:13 +0900 Subject: [PATCH] =?UTF-8?q?PHASE-Z-ROADMAP=20refactor=20=E2=80=94=20Codex?= =?UTF-8?q?=20=EA=B2=80=ED=86=A0=20=EC=95=88=20+=20Step=2022=20=EC=A0=95?= =?UTF-8?q?=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit §1 상단에 lock phrase blockquote 추가: "현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한 PROCESS_OVERVIEW.html 프로토타입을 먼저 만드는 것이다." §2 — 토픽별 6 영역 → axis 명 list (Step 5 보완 / 6-A / 7-conn / 8-conn / Step 9 v0 / cleanup-1 / F29 / README / push 완료). CHANGE-LOG reference 로 추적성 확보. §3 — Step 22 추정 % 20% → 10% (UI 미시작 정합). caveat 강화 (STATUS-BOARD 가 single source of truth 명시). §4 — 큰 로드맵 7 단계 한 블록. §5 — 우선순위 3 줄 분리 (1. 프로토타입 / 2. 보고 / 3. 복귀). §6 — 보고용 프로토타입 계획 (포함 내용 / 목적) 별도 섹션. §7 — Pipeline 복귀 후 Todo (MDX04 / 시각 점검 확장 / 어댑터 / MDX 정규화 / Step 21 / MDX01 02 검증) 별도 섹션. §8 — 문서 역할 분담 표 (README / OVERVIEW / STATUS-BOARD / CHANGE-LOG / ROADMAP / PROCESS_OVERVIEW 6 문서). Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/architecture/PHASE-Z-ROADMAP.md | 285 +++++++-------------------- 1 file changed, 72 insertions(+), 213 deletions(-) diff --git a/docs/architecture/PHASE-Z-ROADMAP.md b/docs/architecture/PHASE-Z-ROADMAP.md index 72ad4ee..2f31a67 100644 --- a/docs/architecture/PHASE-Z-ROADMAP.md +++ b/docs/architecture/PHASE-Z-ROADMAP.md @@ -1,100 +1,54 @@ -# Phase Z 진행 현황 및 향후 Todo +# Phase Z Roadmap -**문서 성격**: 진행 계획 + 당장 할 일 + 세부 todo. *자주 갱신*. +**문서 성격**: 앞으로의 진행 순서 + 큰 axis + 우선순위. *자주 갱신*. **작성일**: 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). +**문서 역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`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. 현재 위치 -Design Agent 는 MDX 문서를 입력받아 프레젠테이션 슬라이드 HTML 로 자동 변환하는 Phase Z 파이프라인을 구축 중. 현재까지는 MDX03 을 기준으로 22 단계 파이프라인의 정상 경로를 검증함. +- MDX03 정상 경로 통과 (PASS) +- Phase Z 22 단계 파이프라인 일반화 진행 중 +- 보고용 프로토타입을 먼저 작성 예정 -### 1.1 MDX03 현재 결과 +### 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` 에 보존 (향후 사용자 선택용) +- rank 2~6 후보 Step 9 `application_plan` 에 보존 - `final.html` / `preview.png` 생성 -- Step 14 시각 점검 통과 (visual_check_passed = true) -- Step 20 슬라이드 상태 통과 (overall = PASS) +- Step 14 시각 점검 통과 / Step 20 상태 통과 - F29 missing asset bug 수정 완료 -- missing image count = 0 -- full MDX coverage = true - -``` -MDX03 기준 자동 슬라이드 생성 정상 경로 통과 -다만 전체 22 단계 파이프라인은 일반화 단계이며, MDX01 / 02 / 04 등으로 검증을 확장해야 한다. -``` +- missing image count = 0 / full MDX coverage = true --- -## 2. 지금까지 완료한 주요 작업 +## 2. 이번 session 에서 닫힌 작업 -### 2.1 Slide base / spacing / typography 정리 +이번 session 에서 closed 된 axis 목록: -- slide canvas: 1280×720 -- title / divider / body / footer 위치 정리 -- body height: 585 -- grid gap: 14 -- 5-layer typography 위계 정리 (대 16px / 소 12px / 콘텐츠 10px / ...) +- 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.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 확인 +각 axis 상세 의사결정 / 폐기 / lock 은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) 참조. --- ## 3. 현재 22 단계 진행 수준 -> ⚠️ 아래 % 는 *추정치*. 정확한 ✅ / ⚠ / ❌ 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 가 단일 출처. +> 아래 수치는 MDX03 정상 경로 기준의 *추정 진행률*이다. +> 22 단계별 공식 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 를 *single source of truth* 로 한다. | Step | 단계 | 추정 % | |---|---|---| @@ -107,7 +61,7 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수 | 6 | 구성 계획 | 80% | | 7 | 슬라이드 레이아웃 계획 | 85% | | 8 | Zone / Region 비율 계획 | 75% | -| 9 | 적용 계획 (application_plan) | 70% | +| 9 | 적용 계획 (`application_plan`) | 70% | | 10 | 프레임 컨트랙트 확인 | 65% | | 11 | 슬롯 매핑 | 45% | | 12 | 슬롯 데이터 생성 | 85% | @@ -120,7 +74,7 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수 | 19 | 다음 조치 제안 | 60% | | 20 | 슬라이드 상태 결정 | 95% | | 21 | 디버그 / 추적 기록 | 45% | -| 22 | 사용자 확인 / 내보내기 | 20% | +| 22 | 사용자 확인 / 내보내기 | 10% | 전체 요약: - MDX03 정상 경로 = 완료 @@ -129,173 +83,78 @@ F29 partial 이 *존재하지 않는* SVG asset 3 개를 참조하던 문제 수 --- -## 4. 앞으로의 큰 로드맵 - -전체 방향은 다음 순서로 간다 (자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조): +## 4. 큰 로드맵 ``` 1. 22 단계 파이프라인 안정화 (현재) -2. Phase Q 재검토 후 Phase Z 반영 -3. AI 보정 / 재구성 단계 +2. Phase Q 재검토 후 Phase Z 반영 (audit & salvage) +3. AI 보정 / 재구성 단계 (AI Repair / Restructure) 4. DB / 카탈로그 정리 5. 프론트엔드 연결 6. HTML 수정 기능 추가 7. 프레임 지속 업데이트 ``` -샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*. +자세한 단계별 설명은 [`README.md`](../../README.md) §4 참조. 샘플 MDX (03 / 04 / 01 / 02) 는 *로드맵 단계 X* — *22 단계 보완용 검증 재료*. --- -## 5. 세부 Todo +## 5. 우선순위 -### 5.1 보고용 프로토타입 작성 — 우선 진행 +``` +1. 보고용 HTML 프로토타입 작성 ← 지금 당장 할 일 +2. 보고 / 피드백 수집 +3. Phase Z 파이프라인 작업 복귀 (22 단계 정리 계속) +``` -현재 가장 먼저 할 일은 *실제 개발 진행이 아니라*, 보고와 피드백을 위한 프로토타입 작성. +--- + +## 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 결과를 시각적으로 보여줌 -- 22 단계 흐름 설명 -- layout / region / frame / application_plan 개념 설명 -- 아직 미구현인 부분 명확히 표시 +- 현재 파이프라인 구조 설명 +- MDX03 결과 시각적으로 보여줌 +- 미구현 영역 명확히 표시 - 향후 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` (신규) +## 7. Pipeline 복귀 후 Todo -### 5.2 22 단계 파이프라인 정리 (보고 이후 복귀) +보고 / 피드백 수집 후 22 단계 안정화 작업 재개. 우선순위 후보: -주요 작업: -- 프레임 ↔ Phase Z 연결 구조 정리 (V4 frame 후보 → Phase Z 렌더 경로 연결 확장) -- 시각 점검 범위 확장 (누락 이미지 / 표 잘림 / 비율 어긋남 / 빈 공간 검사) -- MDX 정규화 / 정리 방식 보완 (Step 2 / 3 / 4) -- MDX 01 / 02 / 04 검증을 통한 예외 케이스 보완 -- Step 21 디버그 추적 보강 +- **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 로 일반화 확장 -### 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 검증 +이 후 단계 = 큰 로드맵의 §2 ~ §7 (Phase Q audit → AI repair → DB → 프론트 → HTML 수정 → frame 지속). --- -## 6. 당장 실행 순서 - -``` -1. 보고용 프로토타입 작성 ← 지금 당장 할 일 -2. 보고 / 피드백 수집 -3. Phase Z 파이프라인 작업 복귀 -4. 22 단계 정리 계속 -5. 이후 Phase Q 검토 → AI → DB → 프론트 → 에디터 순서로 확장 -``` - ---- - -## 7. 문서 역할 분담 - -본 프로젝트의 문서들은 다음과 같이 책임이 분리됨: +## 8. 문서 역할 분담 | 문서 | 역할 | 갱신 빈도 | |---|---|---| -| [`README.md`](../../README.md) | 프로젝트 개요 + 22 단계 / 로드맵 / 운영 원칙 | 가끔 (큰 방향 변경 시) | +| [`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) | 각 단계의 정확한 상태 (✅ / ⚠ / ❌) | 자주 | -| [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 | -| **`PHASE-Z-ROADMAP.md`** (본 문서) | **진행 계획 + 당장 할 일 + 세부 todo** | **자주** | -| `PROCESS_OVERVIEW.html` (또는 `PHASE_Z_REPORT_PROTOTYPE.html`) | 보고용 시각 자료 | 보고 시점 | +| [`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 / 우선순위** | **자주** | +| `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 | 각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.