README 재정리: AS-IS / TO-BE 프로세스 구조 명시

- 현재 프로세스(AS-IS) 7단계 정리 - 개선 프로세스(TO-BE) 5단계 정리 - 핵심 차이: 꼭지 추출 시점, redesign 반복 조정, 빈 공간 재분배, 시각 검증 - 프로젝트 구조/산출물/향후 방향 포함 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-16 16:53:51 +09:00
parent 1ff6c6cbb2
commit 46e53beeaf
1 changed files with 109 additions and 280 deletions
--- a/README.md
+++ b/README.md
@@ -1,322 +1,151 @@
 # C.E.L. Slide Pipeline

-MDX 기반 콘텐츠를 분석해 1280x720 슬라이드 HTML로 변환하는 파이프라인입니다.
+MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다.

-이 문서는 현재 코드 기준으로 이 프로젝트가 무엇을 하는지, 어떤 프로세스로 동작하는지, 현재 어디까지 와 있는지, 앞으로 무엇을 개선하려는지를 빠르게 파악하기 위한 개요 문서입니다.
+## 한 줄 요약

-## 무엇을 하는가
+**텍스트 콘텐츠를 넣으면, 코드가 구조를 분석하고 디자인을 입혀서 슬라이드로 만들어줍니다.**

-이 프로젝트는 MDX 문서를 입력으로 받아 다음 과정을 거쳐 슬라이드 결과물을 생성합니다.
+---

- 콘텐츠 정규화
- 문서 의미 분석
- 슬라이드 구조 해석
- schema / recipe / block 선택
- HTML 조립
- fit / overflow 검증
- 최종 산출물 저장
+## 현재 프로세스 (AS-IS)

-최종 산출물은 보통 다음 형태로 저장됩니다.
+```
+1. MDX 입력
+   - MDX 파일 읽기
+   - 정규화 (제목/본문/이미지/표/핵심요약 분리)

- `final.html`
- `final_context.json`
- `steps/*.html`
- popup / detail HTML
+2. 꼭지 추출 (AI)
+   - 중목차별 핵심 주제 파악
+   - 각 꼭지의 성격 분류

-## 한눈에 보는 프로세스
+3. zone 구분 (코드)
+   - 중목차(##) 기준으로 영역 분할 (top/bottom)
+   - 콘텐츠 양 기준으로 비중(weight) 산출

-```text
-MDX Input
-  ↓
-Stage 0  Normalize
-  ↓
-Stage 1A/1B  AI Meaning Analysis
-  ↓
-Phase Y  Group / Schema / Recipe Parsing
-  ↓
-Stage 1.5a  Space Allocation
-  ↓
-Stage 1.7  Block Selection
-  ↓
-Stage 1.8  Fit / Measure / Adjustment
-  ↓
-Stage 2  Assemble final slide HTML
-  ↓
-Stage 4  Validate with Selenium / Vision
-  ↓
-Stage 5  Save final artifacts
+4. BEPs 디자인 매칭 (코드)
+   - catalog에서 tag/schema 기준으로 블록 검색
+   - 매칭되면 → 해당 블록에 콘텐츠 삽입
+   - 미매칭이면 → 기존 스타일 따라 코드가 고정 렌더 (1회)
+
+5. 조립 (코드)
+   - slide-base(1280×720)에 zone별 배치
+   - 상세 내용은 첨부 파일로 분리
+
+6. 검증
+   - overflow 측정 (Selenium)
+   - 구조 검증 (본문 visible, 링크 수)
+
+7. 출력
+   - final.html + 첨부 HTML
 ```

-핵심 원칙은 다음과 같습니다.
+### 현재 수준

- source of truth는 `normalized.sections`
- 문서명 하드코딩보다 shape, schema, recipe, tag를 우선한다
- 흐름의 우선순위는 `구조 -> payload -> layout -> fit`
- popup / detail은 overflow를 덮는 임시 장치가 아니라 `메인 요약 + 상세 보기`의 표현 계약이다
+| 대상 | 상태 |
+|------|------|
+| MDX 03 (3개 목표 + 비교표) | ✅ 정상 동작 |
+| MDX 02 (목표 + 프로세스 + 상세표) | △ 구조 동작, 시각 품질 보정 중 |

-## 타입 구조
+---

-현재 메인 타입 선택은 사실상 `Type A`와 `Type B`입니다.
+## 개선 프로세스 (TO-BE)

-### Type A
+```
+1. MDX 입력
+   - MDX 파일 읽기
+   - 정규화 (제목/본문/이미지/표/핵심요약 분리)

- 본문 외에 sidebar, reference, 부록성 영역이 함께 필요한 슬라이드
- 현재는 Type B보다 덜 닫혀 있고, AI 생성 + renderer 경로 비중이 더 큼
+2. zone 구분 (코드)
+   - 중목차(##) 기준으로 영역 분할

-### Type B
+3. BEPs 디자인 매칭 검토
+   3-1. 매칭 시
+        - 해당 디자인 선택
+        - zone 크기에 맞게 재구성
+   3-2. 미매칭 시
+        - 중목차에 대한 꼭지 정리 (AI)
+        - 꼭지별 유사 디자인 선택
+        - 해당 중목차/소목차에 맞게 redesign
+        - 입력 → 조정 반복 (빈 공간/overflow 자동 조절)

- top / bottom 같은 본문 zone 조합으로 해결되는 슬라이드
- 현재 가장 안정적인 메인 경로
- 최근 구조화 작업은 대부분 이 Type B 경로를 중심으로 진행됨
+4. 검증
+   - overflow / 빈 공간 측정
+   - 시각 품질 검증 (정렬, 위계, 가독성)

-### Type B' / B''
+5. 출력
+   - final.html + 첨부 HTML
+```

- 역사적으로 실험/호환 과정에서 나온 변형 경로
- 일부 legacy 코드와 과거 산출물에 흔적이 남아 있음
- 현재 메인 1급 타입이라기보다, 과거 흐름과 검증된 표시 계약을 담고 있는 보조 경로에 가까움
+### AS-IS → TO-BE 핵심 차이

-## 단계별 파이프라인
+| 항목 | AS-IS | TO-BE |
+|------|-------|-------|
+| 꼭지 추출 시점 | zone 구분 전에 항상 실행 | 미매칭 시에만 (3-2) |
+| 디자인 미매칭 | 코드 고정 렌더 1회 | redesign + 반복 조정 |
+| 빈 공간 처리 | 그냥 둠 | 자동 재분배 |
+| 검증 | overflow만 | 시각 품질까지 |

-| 단계 | 담당 | 주요 파일 | 하는 일 | 주요 산출물 |
-|---|---|---|---|---|
-| Stage 0 | 코드 | `src/mdx_normalizer.py` | MDX를 정규화하고 sections, tables, images, popups로 분리 | `NormalizedContent` |
-| Stage 1A | AI (Kei/Opus) | `src/kei_client.py` | title, core message, topic, 초기 layout 힌트 추출 | `Analysis`, `Topic[]` |
-| Phase Y | 코드 | `src/pipeline.py`, `src/section_parser.py` | `normalized.sections` 기반으로 group, schema, recipe, zone/page_structure 결정 | `PageStructure`, `mdx_sections` |
-| Stage 1B | AI (Kei/Opus) | `src/kei_client.py` | topic별 relation, source_data, 표현 힌트 보강 | 보강된 `Topic[]` |
-| Stage 1B-ST | AI (Kei/Opus) | `src/kei_client.py` | structured_text 생성 | `Topic.structured_text` |
-| Stage 1.5a | 코드 | `src/space_allocator.py` | zone / container 크기, preset, font hierarchy 계산 | `containers`, `font_hierarchy` |
-| Stage 1.7 | 코드 | `src/block_reference.py`, `templates/catalog.yaml` | tag_match, schema_match, fallback 기준으로 block 선택 | `references` |
-| Stage 1.8 | 코드 + Selenium + 일부 AI | `src/pipeline.py`, `src/slide_measurer.py` | fit 측정, overflow 확인, 재배분, 보정 | `fit_result`, `measurement` |
-| Stage 2 | 코드 중심 | `src/block_assembler.py` | Type B 기준 slide-base + block template + payload 조립 | `generated_html` |
-| Stage 3 | 코드 | `src/renderer.py` | Type A 쪽 Jinja/renderer 조립, Type B는 대체로 생략 | `rendered_html` |
-| Stage 4 | 코드 + Vision AI | `src/slide_measurer.py`, `src/kei_client.py` | Selenium overflow 측정, screenshot, vision quality 평가 | `measurement`, `quality_score` |
-| Stage 5 | 코드 | `src/pipeline.py` | `final.html`, `final_context.json`, popup/detail html 저장 | run 산출물 |
+---

-## 현재 메인 실행 경로
+## 핵심 원칙

-### Type B 메인 경로
+| 원칙 | 설명 |
+|------|------|
+| **콘텐츠가 기준** | 디자인이 콘텐츠에 맞춤 (콘텐츠를 디자인에 맞추지 않음) |
+| **코드가 판단** | AI는 꼭지 추출만, 레이아웃/디자인 선택은 규칙 기반 |
+| **기존 디자인 재활용** | Figma에서 추출한 BEPs 블록을 우선 활용, 없으면 같은 스타일로 생성 |
+| **넘치면 분리** | 슬라이드에 안 들어가는 상세 내용은 첨부로 분리 (자세히보기) |
+| **통일이 아닌 다양성** | 같은 구조라도 콘텐츠에 따라 다른 표현 가능 (recipe = 표현 범주) |

-지금 실전에서 가장 중요한 경로는 아래입니다.
+---

-1. Stage 0에서 MDX를 정규화
-2. Stage 1A / 1B에서 AI가 문서 의미와 topic 추출
-3. Phase Y에서 코드가 `normalized.sections`를 읽고 page_structure를 다시 생성
-4. Stage 1.7에서 block / recipe 후보 선택
-5. Stage 1.8에서 fit / overflow 검증
-6. Stage 2에서 `assemble_slide_html_final()`로 최종 HTML 조립
-7. Stage 4 / 5에서 측정과 산출물 저장
-
-Type B의 핵심 파일은 아래입니다.
-
- `src/pipeline.py`
- `src/section_parser.py`
- `src/block_reference.py`
- `src/block_assembler.py`
- `src/space_allocator.py`
- `templates/catalog.yaml`
-
-### Type A 경로
-
-Type A는 현재도 살아 있지만, Type B만큼 단단하게 닫힌 상태는 아닙니다.
-
- AI 생성 비중이 더 큼
- `src/renderer.py` 의존도가 더 큼
- sidebar / reference 구조를 포함하는 문서에서 의미가 큼
-
-## schema -> recipe -> block
-
-최근 구조화에서 가장 중요한 변화 중 하나는 `schema -> recipe -> block` 레이어입니다.
-
-### schema
-
-콘텐츠의 의미 구조입니다.
-
-예:
-
- `parallel_cluster`
- `parallel_cluster_plus_visual`
- `compare_asymmetric_paired`
- `sequence_plus_visual`
- `single_block`
-
-### recipe
-
-block 이름이 아니라 표현 규칙입니다.
-
-예:
-
- `single_block`
- `two_col_text_visual`
- `two_col_text_detail`
- `stacked_summary_detail`
-
-recipe는 보통 이런 계약을 가질 수 있습니다.
-
- left / right kind
- top / bottom kind
- ratio
- vertical align
- direct render 우선 여부
-
-### block
-
-실제 구현 템플릿 후보입니다.
-
-예:
-
- `prerequisites-3col`
- `process-product-2col`
- `compare-detail-gradient`
- `card-icon-desc`
-
-즉, “무슨 문서냐”보다 “무슨 구조냐”를 먼저 읽고, 그 구조에 맞는 표현 규칙을 정한 뒤, 마지막에 구현 block을 고르는 방향으로 가고 있습니다.
-
-## popup / detail 계약
-
-popup은 현재 다음 철학으로 정리되는 중입니다.
-
- 메인 슬라이드에는 zone 크기에 맞는 요약만 남긴다
- 큰 표, 시각 컴포넌트, 과다 bullet은 상세 popup으로 분리한다
- 메인에서는 `자세히보기` 링크를 제공한다
-
-현재 popup 관련 핵심은 아래입니다.
-
- `PopupItem` 모델로 popup 데이터를 명시적으로 다루기 시작함
- `popup_id`와 `popup_file` 생애주기를 분리해 관리 중
- 최종 목표는 popup 판단을 휴리스틱이 아니라 명시적 contract로 만드는 것
-
-다만 아직 일부 구간에는 추측 로직과 이중 관리가 남아 있어, 이 부분은 계속 정리 중입니다.
-
-## run 산출물 구조
-
-각 실행은 `data/runs/{run_id}/` 아래에 저장됩니다.
-
-주요 파일은 다음과 같습니다.
-
- `final.html`
- `final_context.json`
- `steps/*.html`
- popup / detail HTML
-
-### final.html
-
- 최종 렌더 결과
- 실제 눈으로 보는 산출물
-
-### final_context.json
-
- 각 단계 결과를 최종 context 형태로 저장
- block 선택, page_structure, measurement, quality_score 등을 확인할 때 가장 중요
-
-### steps/*.html
-
- 단계별 디버그 / 설명용 보드
- 현재도 검토용으로 유용하지만, 일부 인코딩과 설명 품질은 더 다듬을 필요가 있음
-
-## 자주 봐야 하는 파일
+## 프로젝트 구조

 ### 파이프라인 핵심

- [src/pipeline.py](src/pipeline.py)
- [src/pipeline_context.py](src/pipeline_context.py)
- [src/section_parser.py](src/section_parser.py)
- [src/block_reference.py](src/block_reference.py)
- [src/block_assembler.py](src/block_assembler.py)
- [src/space_allocator.py](src/space_allocator.py)
+| 파일 | 역할 |
+|------|------|
+| `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/catalog.yaml](templates/catalog.yaml)
- [templates/blocks/new/prerequisites-3col.html](templates/blocks/new/prerequisites-3col.html)
- [templates/blocks/redesign/process-product-2col.html](templates/blocks/redesign/process-product-2col.html)
- [templates/blocks/cards/compare-detail-gradient.html](templates/blocks/cards/compare-detail-gradient.html)
- `templates/blocks/slide-base.html`
+| 파일 | 역할 |
+|------|------|
+| `templates/catalog.yaml` | BEPs 블록 목록 (when/slots/template) |
+| `templates/blocks/slide-base.html` | 슬라이드 기본 틀 (1280×720) |
+| `templates/blocks/new/` | Figma 추출 블록 (prerequisites-3col 등) |
+| `templates/blocks/redesign/` | 재디자인 블록 (process-product-2col 등) |

-### 검증 / 측정
+### 검증

- [src/slide_measurer.py](src/slide_measurer.py)
- [src/validators.py](src/validators.py)
- [src/step_visualizer.py](src/step_visualizer.py)
+| 파일 | 역할 |
+|------|------|
+| `src/slide_measurer.py` | Selenium overflow 측정 |
+| `src/step_visualizer.py` | 단계별 디버그 보드 생성 |
+| `src/validators.py` | 구조 검증 |

-### 계획 / 히스토리
+### 산출물

- [PIPELINE.md](PIPELINE.md)
- [docs/history/PHASE-Y-PLAN.md](docs/history/PHASE-Y-PLAN.md)
+각 실행은 `data/runs/{run_id}/` 아래에 저장됩니다.

-## 현재 상태
+| 파일 | 내용 |
+|------|------|
+| `final.html` | 최종 슬라이드 |
+| `final_context.json` | 전체 파이프라인 결과 데이터 |
+| `steps/*.html` | 단계별 디버그 보드 |
+| `첨부*_상세*.html` | popup 상세 내용 |

-### 비교적 잘 닫혀가는 것
-
- Type B 메인 경로
- `normalized.sections` 기반 구조 해석
- schema / recipe 기반 block selection의 골격
- redesign block 자산화
- popup / detail 2단 표현 계약의 초안 연결
-
-### 아직 정리 중인 것
-
- Type A 전체 안정화
- popup을 완전한 source of truth로 정리
- tag_match 와 schema_match의 완전한 동등 점수 비교
- step 보드 인코딩 / 설명 품질
- fit loop의 공간 재분배 고도화
- legacy 경로와 문서 정리
-
-### 최근 Type B에서 특히 중요해진 방향
-
- recipe direct render가 block 선택에 끌려가지 않도록 구조 계약을 더 강하게 만든다
- Type B direct render가 Type B'의 검증된 표시 계약을 최대한 재사용하도록 정리한다
- sample은 복제 대상이 아니라 evaluation rule의 기준으로 사용한다
- validation은 “같아야 한다”보다 “어긋나면 안 된다”에 초점을 둔다
+---

 ## 향후 개선 방향

-현재 이후의 개선 방향은 아래 축으로 정리됩니다.
-
-### 1. 구조 계약 강화
-
- top / bottom zone의 contract를 더 구체화
- `parallel_cluster_plus_visual`, `full_text + detail_preview` 같은 recipe를 표현 범주 수준으로 강화
- recipe가 block를 끌고 가는 것이 아니라 recipe가 block를 통제하도록 정리
-
-### 2. 표시 계약 통합
-
- Type B direct render가 Type B'에서 이미 검증된 bullet / indent / body-text 구조를 재사용하도록 통합
- `.rdr-*` 계열 신규 CSS를 계속 키우기보다, 기존 검증된 계약을 최대한 재사용
-
-### 3. detail preview 개선
-
- popup source가 표면 `헤더 + 일부 행`
- popup source가 리스트면 `앞부분 몇 개`
- popup source가 컴포넌트면 구조화된 preview
-
-즉 “링크만 있는 상세”가 아니라 “상세가 있다는 걸 바로 이해할 수 있는 preview”를 만드는 방향
-
-### 4. fit loop 고도화
-
-지금은 주로 overflow 대응 중심이지만, 앞으로는 아래까지 확장하려고 합니다.
-
- 빈 공간 감지
- 이미지 확대
- preview 행 수 조정
- zone 비율 재배분
-
-### 5. 검증판과 final 일치화
-
- `stage_4` 보드와 실제 `final_context.json` / `final.html`의 상태 차이를 줄이기
- 검수 보드를 더 믿을 수 있는 상태로 정리
-
-## 읽는 순서 추천
-
-프로세스를 빠르게 파악하려면 아래 순서가 좋습니다.
-
-1. 이 `README.md`
-2. [src/pipeline.py](src/pipeline.py)
-3. [src/section_parser.py](src/section_parser.py)
-4. [src/block_assembler.py](src/block_assembler.py)
-5. 최근 run의 `final_context.json`
-
-히스토리와 설계 변화까지 보려면 아래 문서를 이어서 보면 좋습니다.
-
- [PIPELINE.md](PIPELINE.md)
- [docs/history/PHASE-Y-PLAN.md](docs/history/PHASE-Y-PLAN.md)
+1. **3-2 입력→조정 반복 구현** — redesign 후 빈 공간/overflow 자동 재분배
+2. **검증 강화** — overflow뿐 아니라 정렬, 위계, 가독성까지 시각 품질 검증
+3. **BEPs 매칭 범위 확대** — 더 많은 Figma 블록 추출 및 catalog 등록
+4. **다양한 MDX 확장** — MDX 02, 03 이후 추가 문서 유형 검증