kyeongmin
85c680f02a
전체 26 files (20 추가 + 6 수정), 10507 insertions. Phase Z 문서 : - docs/architecture/PHASE-Z-CHANGE-LOG.md (신설) — axis-by-axis 의사결정 history (newest-on-top). Step 7-A 부터 6 entry 박힘 + 2026-05-08 / 2026-05-08 #2 (compat 매트릭스 폐기 / 6-B 폐기 / F14 표현 정정 / label gate policy 분리). - docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md (수정) — Step 5/6/9 Gap note append (구조 무변, append-only). 6-B 폐기 사실 + Refinement F. - docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md (수정) — snapshot date 2026-05-08 갱신. §3 핵심 missing item 5 (Step 5/6/9 boundary axis breakdown + 폐기 기록). §6 한 줄 갱신 — 다음 axis 후보 A~F. Project root docs : - PLAN.md / PROGRESS.md / README.md (수정) — 토큰 체계 / 폴더 구조 / 설계 문서 / 역할 분리 반영. - IMPROVEMENT-REDESIGN.md (신설) — Phase Z 설계 핵심 문서. - PROCESS_OVERVIEW.html (신설) — 파이프라인 개요 시각. - docs/tasks/* (신설) — Phase Z task 문서. V4 catalog (Phase Z runtime 필수 의존성) : - tests/matching/v4_full32_result.yaml (신설, 4888 줄) — V4 매칭 결과 32 frame × 10 MDX section. lookup_v4_match() / lookup_v4_candidates() 가 본 파일 read. Phase Z runtime 이 *없으면 즉시 abort* — clone 후 즉시 동작 가능 보장. Samples : - samples/mdx_batch/04.mdx (신설) — MDX04 기본 sample. - samples/mdx/04. DX 지연 요인.mdx (신설) — MDX04 원본. Phase Q legacy 보존 (별 axis "Phase Q audit & salvage" 영역) : - src/block_matcher_tfidf.py / catalog_blocks.py / frame_extractor.py / pipeline_v2.py — Phase Q (옛 파이프라인) src 신규 untracked 파일들. Phase Z runtime 와 의존성 0. Phase Q audit axis 에서 검토 예정. - scripts/eval_block_matcher.py / fetch_all_frame_screenshots.py / match_17_units_my_matcher.py / match_mdx_strict.py / match_mdx_to_frames_tfidf.py / ocr_augment_texts.py / run_pipeline_v2.py / previews/ — Phase Q 작업 시 사용한 옛 script. 같이 보존. - run_mdx03_pipeline.py (수정) — Phase Q 진입점 (no flag) + Phase Z 진입점 (--phase-z2 flag) 동시 wrapper. Phase Z 만 사용 시 `python -m src.phase_z2_pipeline samples/mdx_batch/03.mdx <run_id>` 직접 호출. 비-scope : - tests/matching/ (v4_full32_result.yaml 외 ~63MB) — V4 진화 history / reports / DECK / ATTACH. Phase Q audit axis 에서 검토. - tests/pipeline/ (~15MB) — pipeline data. Phase Q audit 영역. - templates/catalog/blocks.yaml — 옛 block catalog. Phase Q audit. - templates/phase_z2/frames/ — 옛 frame partial 위치. Phase Q audit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
159 lines
7.0 KiB
Markdown
159 lines
7.0 KiB
Markdown
# 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`](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](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](IMPROVEMENT-REDESIGN.md) | **Phase Z 통합 설계** (위계 / 용어 / 5 단계 흐름) |
|
||
| [docs/architecture/FRAME-INTEGRATION-MAP.md](docs/architecture/FRAME-INTEGRATION-MAP.md) | **32 frame Zone 적용 분류** (`zone_direct/adapt/extract/reference_only`) |
|
||
| [docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md](docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md) | **Frame / Style / Token 인벤토리** (32 frame + 18 token + 6 legacy) |
|
||
| [PROCESS_OVERVIEW.html](PROCESS_OVERVIEW.html) | 임원 보고용 A4 2 페이지 (프로세스 + 구조도) |
|
||
| [tests/PIPELINE.md](tests/PIPELINE.md) | 매칭 시스템 (V1~V4) 통합 정리 |
|
||
| [PROGRESS.md](PROGRESS.md) | 전체 Phase 이력 (Phase 1~T + R' + Z) |
|
||
| [CLAUDE.md](CLAUDE.md) | 프로젝트 규칙 + Phase Z 위계 |
|
||
| [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md) | 개선 설계 (이전 Phase Q 까지) |
|
||
| [TOKENS-v1.md](docs/architecture/TOKENS-v1.md) | 토큰 위계 기준표 |
|
||
| [BLOCK-RULES.md](docs/architecture/BLOCK-RULES.md) | 블록 작성 규칙 |
|