C.E.L_Slide_test2/README.md

# C.E.L. Slide Pipeline

## 이 프로젝트는 무엇인가

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

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

---

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

### 전체 흐름

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

### 구조

- **slide-base:** 1280×720 슬라이드 프레임. 대목차 + 구분선 + 본문 영역 + 핵심 인사이트(footer)
- **zone:** 본문 영역 안에서 중목차(##) 기준으로 나뉘는 영역 (top/bottom 등)
- **블록:** zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것
- **catalog:** 블록의 메타 정보 (구조, 슬롯, 매칭 조건)

### 주요 파일

| 파일 | 역할 |
|------|------|
| `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 측정만 하고, 정렬/위계/가독성 같은 시각 품질은 미검증 |

---

## 어떻게 개선하려 하는가

블록을 **구조 부품화**하고, 스타일을 **토큰으로 분리**하며, 파이프라인을 **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) | 블록 작성 규칙 (에이전트 간 계약서) |