C.E.L. Slide Pipeline

이 프로젝트는 무엇인가

MDX 기반 콘텐츠를 입력하면, 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다.

텍스트 콘텐츠를 넣으면, 구조를 분석하고 BEPs(Figma) 디자인을 매칭하여 슬라이드를 만들어줍니다.

---

어떻게 구성/구현되어 있는가

전체 흐름

MDX 입력 → 정규화 → 꼭지 추출(AI) → zone 구분 → BEPs 매칭 → 조립 → 검증 → 출력

구조

• slide-base: 1280×720 슬라이드 프레임. 대목차 + 구분선 + 본문 영역 + 핵심 인사이트(footer)
• 레이아웃: slide-body 안의 zone 분배 형태 (Type A/B/B'/B'')
• zone: 레이아웃이 정한 콘텐츠 영역 (top/bottom 등)
• 프레임 (구 "블록"): zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것
• catalog: 프레임의 메타 정보 (구조, 슬롯, 매칭 조건)

⚠️ Phase Z (2026-04-28) 부터 "블록" → "프레임" 으로 용어 통일. 기존 코드 (block_reference.py, templates/blocks/, BLOCK-RULES.md 등) 는 점진적 정리.

주요 파일

파일	역할
src/pipeline.py	파이프라인 오케스트레이션
src/section_parser.py	중목차 추출, 구조 분류
src/block_reference.py	BEPs 디자인 매칭
src/block_assembler.py	슬라이드 HTML 조립
templates/blocks/slide-base.html	슬라이드 프레임
templates/catalog.yaml	블록 메타 정보

산출물

각 실행은 data/runs/{run_id}/ 아래에 저장됩니다.

파일	내용
final.html	최종 슬라이드
final_context.json	파이프라인 결과 데이터
steps/*.html	단계별 디버그 보드
첨부*_상세*.html	popup 상세 내용

---

무슨 문제가 있는가

문제	설명
블록마다 스타일이 제각각	각 블록 HTML 안에 font-size, color, padding이 직접 박혀있어서, 같은 슬라이드 안에서 블록이 섞이면 위계가 안 맞음
slide-base에 구조+스타일 혼재	프레임 HTML 안에 전체 CSS가 인라인으로 들어있어서 유지보수가 어려움
블록이 완성 HTML	블록이 구조+스타일+값을 모두 포함하고 있어서, 재사용/조합이 안 됨
매칭 안 되면 고정 렌더	BEPs에 맞는 블록이 없을 때 코드가 1회 고정 렌더하고 끝. 반복 조정 없음
빈 공간/overflow 방치	렌더 후 빈 공간이 있어도 조정 안 하고, overflow만 감지
검증이 약함	overflow 측정만 하고, 정렬/위계/가독성 같은 시각 품질은 미검증

---

어떻게 개선하려 하는가

핵심은 3가지입니다.

1. 블록을 구조 부품화 — 완성 HTML이 아니라, 구조만 담고 스타일은 토큰으로 분리
2. 스타일을 토큰으로 통일 — 블록마다 제각각인 폰트/색/여백을 공통 기준으로
3. 2경로 파이프라인 — 매칭되면 바로 쓰고(direct-fit), 안 되면 재구성(recipe)

AS-IS → TO-BE

⚠️ 아래 AS-IS / TO-BE 는 Phase Q ~ T 시점의 흐름. 현재 (Phase Z) 흐름은 IMPROVEMENT-REDESIGN.md 참조.

AS-IS (Phase Q ~ T):
  AI가 먼저 꼭지를 추출하고
  → 매칭 블록이 있으면 삽입, 없으면 코드가 1회 고정 렌더
  → 빈 공간이 있어도 그냥 둠
  → 블록마다 font-size, color가 직접 박혀있어서 섞이면 위계 안 맞음

TO-BE (Phase Q ~ T):
  중목차 기준으로 zone을 먼저 나누고
  → TF-IDF로 BEPs 매칭 시도
  → 매칭되면 블록 삽입 + 크기 조절 (direct-fit)
  → 안 되면 AI가 꼭지 정리 + 유사 디자인으로 redesign + 반복 조정 (recipe)
  → 빈 공간/overflow를 자동 재분배
  → 모든 블록이 토큰 기반이라 스타일 통일

NEW (Phase Z, 2026-04-28 ~):
  STAGE 1) MDX 분석 + 레이아웃 매칭 (Type A/B/B'/B'')
  STAGE 2) Zone 별 텍스트 1차 배치
  STAGE 3) Zone 별 프레임 매칭 — V1~V4 (완벽/어정쩡/안됨 분기)
  STAGE 4) 프레임 검토 + 컨테이너 조정 (5차 Fallback)
  STAGE 5) HTML 조립 (slide-base + Jinja2) + 검증 + 출력
  ⭐ AI = zone 안 콘텐츠만 / HTML 구조 = 코드 (Jinja2)
  ⭐ 자유 디자인 금지 — 프레임 DB 참고 필수
  ⭐ MDX 원문 무손실 보존

---

현재 상태

대상	슬라이드 변환	파이프라인 자동화
MDX 03 (3개 목표 + 비교표)	✅ 완료	✅ 파이프라인 연결
MDX 02 (목표 + 프로세스 + 상세표)	✅ 완료	△ 파이프라인 연결, 시각 품질 개선 중
MDX 01 (Type A, sidebar 구조)	✅ 완료 (개별)	미연결
토큰 기반 CSS 체계	-	✅ 정의 완료, slide-base 적용
Figma 블록 추출	-	진행 중 (figma_to_html_agent/blocks/)
매칭 시스템 (V1~V4)	-	✅ 별도 검증 완료 (tests/) — TARGET 3/4
Phase Z 통합 설계	-	✅ 설계 완료 (IMPROVEMENT-REDESIGN.md) — 구현 대기

---

다음 단계 방향 — Phase Z 매칭 시스템 통합

상세: IMPROVEMENT-REDESIGN.md

단계	내용
Phase Z-1	통합 prototype — Stage 1.7 만 V4 로 교체, MDX 03 회귀
Phase Z-2	매칭 + 프리셋 (Type A/B/B'/B'') 통합
Phase Z-3	컨테이너 검증 + 5 차 Fallback
Phase Z-4	전체 통합 + 검증

핵심 위계 (Phase Z 정리) :

slide → slide-base → slide-body → 레이아웃 → Zone → 프레임

5 단계 새 흐름 :

1. MDX 분석 + 레이아웃 매칭
2. Zone 별 텍스트 배치
3. Zone 별 프레임 매칭 (완벽 / 어정쩡 / 안 됨)
4. 프레임 검토 + 컨테이너 조정
5. HTML 조립 + 검증 + 출력

---

참고 문서

문서	내용
IMPROVEMENT-REDESIGN.md	Phase Z 통합 설계 (위계 / 용어 / 5 단계 흐름)
docs/architecture/FRAME-INTEGRATION-MAP.md	32 frame Zone 적용 분류 (zone_direct/adapt/extract/reference_only)
docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md	Frame / Style / Token 인벤토리 (32 frame + 18 token + 6 legacy)
PROCESS_OVERVIEW.html	임원 보고용 A4 2 페이지 (프로세스 + 구조도)
tests/PIPELINE.md	매칭 시스템 (V1~V4) 통합 정리
PROGRESS.md	전체 Phase 이력 (Phase 1~T + R' + Z)
CLAUDE.md	프로젝트 규칙 + Phase Z 위계
IMPROVEMENT-PLAN.md	개선 설계 (이전 Phase Q 까지)
TOKENS-v1.md	토큰 위계 기준표
BLOCK-RULES.md	블록 작성 규칙