From b60a089e6cc1c59097b312837b3e09830d51eadf Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Fri, 17 Apr 2026 14:08:02 +0900 Subject: [PATCH] =?UTF-8?q?README=EB=A5=BC=20=ED=94=84=EB=A1=9C=EC=A0=9D?= =?UTF-8?q?=ED=8A=B8=20=EC=84=A4=EB=AA=85=20=EC=A4=91=EC=8B=AC=EC=9C=BC?= =?UTF-8?q?=EB=A1=9C=20=EC=9E=AC=EA=B5=AC=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 무엇인가 → 구성/구현 → 문제점 → 개선 방향(AS-IS/TO-BE) → 현황 → 다음 단계 - 설계/계획 내용은 docs/architecture/ 문서로 분리 참조 Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 344 +++++++++++++++++++----------------------------------- 1 file changed, 123 insertions(+), 221 deletions(-) diff --git a/README.md b/README.md index ff62a26..46e245d 100644 --- a/README.md +++ b/README.md @@ -1,196 +1,38 @@ # C.E.L. Slide Pipeline -MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다. +## 이 프로젝트는 무엇인가 -## 한 줄 요약 +MDX 기반 콘텐츠를 입력하면, 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다. -**텍스트 콘텐츠를 넣으면, 코드가 구조를 분석하고 디자인을 입혀서 슬라이드로 만들어줍니다.** +텍스트 콘텐츠를 넣으면, 구조를 분석하고 BEPs(Figma) 디자인을 매칭하여 슬라이드를 만들어줍니다. --- -## 현재 프로세스 (AS-IS) +## 어떻게 구성/구현되어 있는가 + +### 전체 흐름 ``` -1. MDX 입력 - - MDX 파일 읽기 - - 정규화 (제목/본문/이미지/표/핵심요약 분리) - -2. 꼭지 추출 (AI) - - 중목차별 핵심 주제 파악 - - 각 꼭지의 성격 분류 - -3. zone 구분 (코드) - - 중목차(##) 기준으로 영역 분할 (top/bottom) - - 콘텐츠 양 기준으로 비중(weight) 산출 - -4. BEPs 디자인 매칭 (코드) - - catalog에서 tag/schema 기준으로 블록 검색 - - 매칭되면 → 해당 블록에 콘텐츠 삽입 - - 미매칭이면 → 기존 스타일 따라 코드가 고정 렌더 (1회) - -5. 조립 (코드) - - slide-base(1280×720)에 zone별 배치 - - 상세 내용은 첨부 파일로 분리 - -6. 검증 - - overflow 측정 (Selenium) - - 구조 검증 (본문 visible, 링크 수) - -7. 출력 - - final.html + 첨부 HTML +MDX 입력 → 정규화 → 꼭지 추출(AI) → zone 구분 → BEPs 매칭 → 조립 → 검증 → 출력 ``` -### 현재 수준 +### 구조 -| 대상 | 상태 | -|------|------| -| MDX 03 (3개 목표 + 비교표) | ✅ 정상 동작 | -| MDX 02 (목표 + 프로세스 + 상세표) | △ 구조 동작, 시각 품질 보정 중 | +- **slide-base:** 1280×720 슬라이드 프레임. 대목차 + 구분선 + 본문 영역 + 핵심 인사이트(footer) +- **zone:** 본문 영역 안에서 중목차(##) 기준으로 나뉘는 영역 (top/bottom 등) +- **블록:** zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것 +- **catalog:** 블록의 메타 정보 (구조, 슬롯, 매칭 조건) ---- - -## 개선 프로세스 (TO-BE) - -``` -1. MDX 입력 - - MDX 파일 읽기 - - 정규화 (제목/본문/이미지/표/핵심요약 분리) - -2. zone 구분 (코드) - - 중목차(##) 기준으로 영역 분할 - -3. BEPs 디자인 매칭 검토 - 3-1. 매칭 시 (direct-fit) - - 해당 디자인 선택 - - zone 크기에 맞게 재구성 - 3-2. 미매칭 시 (recipe/composition) - - 중목차에 대한 꼭지 정리 (AI) - - 꼭지별 유사 디자인 선택 - - 해당 중목차/소목차에 맞게 redesign - - 입력 → 조정 반복 (빈 공간/overflow 자동 조절) - -4. 검증 - - overflow / 빈 공간 측정 - - 시각 품질 검증 (정렬, 위계, 가독성) - -5. 출력 - - final.html + 첨부 HTML -``` - -### AS-IS → TO-BE 핵심 차이 - -| 항목 | AS-IS | TO-BE | -|------|-------|-------| -| 꼭지 추출 시점 | zone 구분 전에 항상 실행 | 미매칭 시에만 (3-2) | -| 디자인 미매칭 | 코드 고정 렌더 1회 | redesign + 반복 조정 | -| 빈 공간 처리 | 그냥 둠 | 자동 재분배 | -| 검증 | overflow만 | 시각 품질까지 | -| 스타일 관리 | 블록마다 직접값 | 토큰 기반 통일 | -| 블록 역할 | 완성 HTML | 구조 부품 (스타일 분리) | - -### 실행 원칙 - -- **direct-fit 기준:** 구조, 슬롯, 시각 위계가 기존 블록과 거의 1:1로 대응될 때만 허용 -- **recipe-path 목적:** 미매칭 콘텐츠를 새로운 구조로 재정리하되, 기존 visual language를 최대한 상속 -- **fit 루프 우선순위:** 줄바꿈 → 간격 조정 → preview 축약 → 폰트 1단계 축소 - ---- - -## 핵심 원칙 - -| 원칙 | 설명 | -|------|------| -| **콘텐츠가 기준** | 디자인이 콘텐츠에 맞춤 (콘텐츠를 디자인에 맞추지 않음) | -| **코드가 판단** | AI는 꼭지 추출만, 레이아웃/디자인 선택은 규칙 기반 | -| **기존 디자인 재활용** | Figma에서 추출한 BEPs 블록을 우선 활용, 없으면 같은 스타일로 생성 | -| **넘치면 분리** | 슬라이드에 안 들어가는 상세 내용은 첨부로 분리 (자세히보기) | -| **통일이 아닌 다양성** | 같은 구조라도 콘텐츠에 따라 다른 표현 가능 | - ---- - -## 토큰 기반 CSS 체계 - -블록마다 스타일이 제각각인 문제를 해결하기 위해, 공통 기준값을 토큰으로 관리합니다. - -### 2층 구조 - -``` -1층: Global Hierarchy Tokens (모든 블록 공통) - typography — 대목차/중목차/소목차/본문/캡션/footer - spacing — padding/gap/indent/margin - colors — 제목/본문/배경/보더/강조 - -2층: Component Semantic Tokens (블록 역할별) - body-strong, detail-link, pill-label, - table-header, compare-badge, callout 등 -``` - -### 글자 위계 (typography) - -| 위계 | 토큰 | font-size | font-weight | -|------|------|-----------|-------------| -| 대목차 | `--font-slide-title` | 22px | 700 | -| 중목차 | `--font-zone-title` | 13px | 700 | -| 소목차 | `--font-sub-title` | 12px | 700 | -| 본문 | `--font-body` | 11px | 500 | -| 캡션 | `--font-caption` | 10px | 400 | -| footer | `--font-footer` | 20px | 700 | - -### 블록 작성 규칙 - -- **구조 스타일 OK:** `display:flex`, `grid`, `align-items`, `overflow` -- **직접값 금지:** `font-size: 11px`, `color: #475569` 직접 박지 않음 -- **토큰 참조:** `font-size: var(--font-body)`, `color: var(--color-body)` - -상세: [BLOCK-RULES.md](docs/architecture/BLOCK-RULES.md) - ---- - -## 프로젝트 구조 - -### 파이프라인 핵심 +### 주요 파일 | 파일 | 역할 | |------|------| -| `src/pipeline.py` | 전체 파이프라인 오케스트레이션 | -| `src/section_parser.py` | 중목차 추출, schema 분류, subsection typing | -| `src/block_reference.py` | BEPs 디자인 매칭 (catalog 검색) | -| `src/block_assembler.py` | 슬라이드 HTML 조립, recipe executor, direct render | -| `src/space_allocator.py` | zone 크기/비율 계산 | -| `src/pipeline_context.py` | 파이프라인 데이터 모델 (PopupItem 등) | - -### 템플릿 - -| 경로 | 역할 | -|------|------| -| `templates/blocks/slide-base.html` | 슬라이드 프레임 (구조만, 스타일은 외부 CSS) | -| `templates/blocks/new/` | Figma 추출 블록 | -| `templates/blocks/redesign/` | 재디자인 블록 | -| `templates/catalog.yaml` | BEPs 블록 메타 (when/slots/template) | - -### 스타일 (토큰 기반) - -``` -templates/styles/ -├── tokens/ -│ ├── typography.css ← 글자 위계 (35변수) -│ ├── spacing.css ← 여백/간격 (28변수) -│ └── colors.css ← 색상 2층 (41변수) -├── themes/ ← 톤 변형 (light/dark/formal) — 예정 -├── base/ -│ └── slide-base.css ← slide-base 스타일 (토큰 참조, 직접값 0) -└── blocks/ ← 블록별 CSS — 예정 -``` - -**CSS 로딩 순서:** tokens → base → blocks → themes - -### 검증 - -| 파일 | 역할 | -|------|------| -| `src/slide_measurer.py` | Selenium overflow 측정 | -| `src/step_visualizer.py` | 단계별 디버그 보드 생성 | -| `src/validators.py` | 구조 검증 | +| `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` | 블록 메타 정보 | ### 산출물 @@ -199,56 +41,116 @@ templates/styles/ | 파일 | 내용 | |------|------| | `final.html` | 최종 슬라이드 | -| `final_context.json` | 전체 파이프라인 결과 데이터 | +| `final_context.json` | 파이프라인 결과 데이터 | | `steps/*.html` | 단계별 디버그 보드 | | `첨부*_상세*.html` | popup 상세 내용 | -### 설계 문서 +--- + +## 무슨 문제가 있는가 + +| 문제 | 설명 | +|------|------| +| **블록마다 스타일이 제각각** | 각 블록 HTML 안에 font-size, color, padding이 직접 박혀있어서, 같은 슬라이드 안에서 블록이 섞이면 위계가 안 맞음 | +| **slide-base에 구조+스타일 혼재** | 프레임 HTML 안에 전체 CSS가 인라인으로 들어있어서 유지보수가 어려움 | +| **블록이 완성 HTML** | 블록이 구조+스타일+값을 모두 포함하고 있어서, 재사용/조합이 안 됨 | +| **매칭 안 되면 고정 렌더** | BEPs에 맞는 블록이 없을 때 코드가 1회 고정 렌더하고 끝. 반복 조정 없음 | +| **빈 공간/overflow 방치** | 렌더 후 빈 공간이 있어도 조정 안 하고, overflow만 감지 | +| **검증이 약함** | overflow 측정만 하고, 정렬/위계/가독성 같은 시각 품질은 미검증 | + +--- + +## 어떻게 개선하려 하는가 + +블록을 **구조 부품화**하고, 스타일을 **토큰으로 분리**하며, 파이프라인을 **direct-fit / recipe 2경로**로 정리합니다. + +### AS-IS (현재) + +``` +1. MDX 입력 → 정규화 +2. 꼭지 추출 (AI, 항상 실행) +3. zone 구분 +4. BEPs 매칭 → 매칭이면 삽입, 미매칭이면 고정 렌더 (1회) +5. 조립 +6. 검증 (overflow만) +7. 출력 +``` + +### TO-BE (목표) + +``` +1. MDX 입력 → 정규화 +2. zone 구분 +3. BEPs 매칭 검토 + 3-1. 매칭 시 (direct-fit) + - 블록 선택 + zone 크기에 맞게 재구성 + 3-2. 미매칭 시 (recipe/composition) + - 꼭지 정리 (AI, 이때만) + - 유사 디자인 선택 + redesign + - 입력 → 조정 반복 (빈 공간/overflow 자동 조절) +4. 검증 (overflow + 시각 품질) +5. 출력 +``` + +### 핵심 차이 + +| 항목 | AS-IS | TO-BE | +|------|-------|-------| +| AI 개입 | 항상 | 미매칭 시에만 | +| 미매칭 처리 | 고정 렌더 1회 | redesign + 반복 조정 | +| 빈 공간 | 방치 | 자동 재분배 | +| 스타일 관리 | 블록마다 직접값 | 토큰 기반 통일 | +| 블록 역할 | 완성 HTML | 구조 부품 (스타일 분리) | +| 검증 | overflow만 | 시각 품질까지 | + +--- + +## 지금 어디까지 되었고, 어디가 안 되었는가 + +### 된 것 + +| 항목 | 상태 | +|------|------| +| MDX 03 파이프라인 | ✅ 정상 동작 (prerequisites-3col + process-product-2col) | +| MDX 02 파이프라인 | △ 구조 동작, 시각 품질 보정 중 | +| 토큰 정의 | ✅ typography(35변수), spacing(28변수), colors(41변수) | +| slide-base CSS 분리 | ✅ 인라인 style 제거, 토큰 참조로 전환 | +| 블록 작성 규칙 문서 | ✅ BLOCK-RULES.md | +| Figma 블록 추출 | 진행 중 (figma_to_html_agent/blocks/) | +| 개선 설계 문서 | ✅ IMPROVEMENT-PLAN.md | + +### 안 된 것 + +| 항목 | 상태 | +|------|------| +| 기존 블록 토큰 전환 | 미착수 (legacy 블록에 직접값 잔존) | +| 폴더 구조 정리 | 미착수 (structures/recipes/legacy 분리) | +| TF-IDF 기반 매칭 | 미구현 | +| fit 루프 (빈 공간 재분배) | 미구현 | +| 시각 품질 검증 | 약함 (overflow만) | +| theme 변형 (light/dark/formal) | 미착수 | + +--- + +## 다음 단계 방향 + +| 순서 | 단계 | 내용 | +|------|------|------| +| 1 | 폴더 구조 정리 | structures/recipes/legacy 분리 | +| 2 | 기존 블록 점진 전환 | 분류(direct-fit/recipe/rewrite) → 토큰 기반 전환 | +| 3 | catalog 고도화 | 파일명 중심 → 속성 테이블 기반 매칭 | +| 4 | 파이프라인 연결 | TF-IDF 매칭 + recipe/composition 경로 | +| 5 | fit 루프 확장 | 빈 공간 재분배, preview 축약, 자동 조정 반복 | +| 6 | 시각 품질 검증 | 정렬, 위계, 가독성 검증 강화 | + +상세: [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md) + +--- + +## 참고 문서 | 문서 | 내용 | |------|------| | [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md) | 개선 설계 (목표/방향/6단계 계획) | | [TOKENS-v1.md](docs/architecture/TOKENS-v1.md) | 토큰 위계 기준표 초안 | | [BLOCK-RULES.md](docs/architecture/BLOCK-RULES.md) | 블록 작성 규칙 (에이전트 간 계약서) | - ---- - -## Source of Truth - -| 기준 | 위치 | -|------|------| -| 구조 판정 | `normalized.sections` | -| 블록 매칭 | `catalog/blocks.yaml` (예정, 현재 `catalog.yaml`) | -| 스타일 기준 | `styles/tokens/` + `styles/themes/` | - ---- - -## 역할 분리 (동시 진행) - -``` -figma_to_html_agent (원재료) design_agent (조립 시스템) -───────────────────── ────────────────────── -"이 블록은 무엇인가" "이 블록을 언제 쓸까" -구조 유형 발견 토큰 기준 확정 -슬롯 정의 catalog 필드 설계 -자산 메타 direct-fit vs recipe 규칙 -seam/crop/anchor theme/token 적용 - fit/validation - - ↓ 접점: 블록 작성 규칙 문서 (BLOCK-RULES.md) ↓ - 블록화 시 이 규칙에 맞춰 전환 -``` - ---- - -## 향후 개선 방향 - -### 진행 중 -1. **토큰 기반 CSS 체계** — typography/spacing/colors 확정, slide-base 분리 완료 -2. **Figma 블록 추출** — `figma_to_html_agent/blocks/`에서 1:1 변환 진행 중 - -### 다음 단계 -3. **폴더 구조 정리** — structures/recipes/legacy 분리 -4. **기존 블록 점진 전환** — 분류(direct-fit/recipe/rewrite) → 토큰 기반 전환 -5. **파이프라인 연결** — TF-IDF 매칭 + fit 루프 확장 + 시각 품질 검증 -6. **다양한 MDX 확장** — MDX 02, 03 이후 추가 문서 유형 검증