Kyeongmin/C.E.L_Slide_test2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b6d86a73c7ddd5b22ffba3c6db4f5b97de49438
C.E.L_Slide_test2/docs/architecture/PHASE-Z-ROADMAP.md
kyeongmin 3b6d86a73c docs: start Phase Q audit and lock salvage policy 
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 18:06:15 +09:00

16 KiB
Raw Blame History

Phase Z Roadmap

문서 성격: 앞으로의 진행 순서 + 큰 axis + 우선순위. 자주 갱신. 작성일: 2026-05-08 (frontend 통합 session 반영) 문서 역할 분담: 본 문서는 진행 계획. 정확한 단계별 상태는 PHASE-Z-PIPELINE-STATUS-BOARD.md, 결정 변경 이력은 PHASE-Z-CHANGE-LOG.md, 22 단계 도면은 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 참조.

3. 현재 22 단계 진행 수준

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

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

Reference in New Issue View Git Blame Copy Permalink