# Design Agent / C.E.L Slide Automation
## 1. 프로젝트 개요
MDX 문서를 입력받아 1280×720 프레젠테이션 슬라이드 HTML 로 자동 변환하는 파이프라인.
- **입력**: MDX (텍스트 + 표 + bullets + JSX block + details + image)
- **변환**: V4 frame matching → Phase Z render pipeline
- **출력**: `final.html` (단일 슬라이드) + step artifact (의사결정 trace)
- **최종 목표**: pipeline + AI repair + DB/catalog + frontend editor 가 연결된 *제품형* 시스템
원천 디자인 = Figma BEPs frame (32 frame) → `figma_to_html_agent/blocks/` 에 HTML/CSS 변환물 누적. V4 catalog (`tests/matching/v4_full32_result.yaml`) 가 MDX section ↔ frame 매칭 점수/label 산출. Phase Z 가 V4 결과를 받아 *render-able slide* 로 번역.
---
## 2. 전체 실행 구조 (22-step pipeline)
```mermaid
flowchart TD
Input([MDX Input])
Input --> S1_2["Step 1-2
MDX Upload & Normalize"]
S1_2 --> S3_4["Step 3-4
Content Object &
Internal Composition Planning"]
S3_4 --> S5["Step 5
V4 Frame Evidence
rank 1 + non-reject max-6"]
S5 --> S6["Step 6
Composition Planning"]
S6 --> S7["Step 7
Layout Candidates
8 preset vocabulary"]
S7 --> S8["Step 8
Zone / Internal Region /
Display Strategy"]
S8 --> S9["Step 9
Application Plan
V4 후보 → 적용 방식 번역"]
S9 --> S10_12["Step 10-12
Frame Contract / Slot Mapping / Payload"]
S10_12 --> S13["Step 13
Render final.html
Jinja2 + frame partial"]
S13 --> S14["Step 14
Visual Runtime Check
Selenium"]
S14 --> Visual{"Visual OK?"}
Visual -->|Yes| S20["Step 20
PASS / Slide Status"]
Visual -->|No| S15_19["Step 15-19
Fit Classification / Router /
Retry / Next Action"]
S15_19 --> Repair{"Repair 방식?"}
Repair -->|Deterministic
zone_ratio / popup / layout_adjust| S13
Repair -->|AI Required
restructure / low score / overflow 반복| AI["AI Repair / Restructure Layer
(향후 axis)"]
AI --> S13
S20 --> S21_22["Step 21-22
Debug / Trace / Export / Front 연결"]
classDef stage fill:#e7f5ff,stroke:#1971c2,color:#000
classDef render fill:#fff3cd,stroke:#f59f00,color:#000
classDef telemetry fill:#f3f0ff,stroke:#7048e8,color:#000
classDef decision fill:#ffd8a8,stroke:#d9480f,color:#000
classDef future fill:#f8f9fa,stroke:#868e96,color:#000,stroke-dasharray: 5 5
class S1_2,S3_4,S5,S6,S7,S8,S9,S10_12 stage
class S13 render
class S14,S15_19,S20,S21_22 telemetry
class Visual,Repair decision
class AI future
```
**Block 구분** : `Block A (PRE-RENDER PLANNING, Step 0~12)` · `Block B (RENDER, Step 13)` · `Block C (POST-RENDER TELEMETRY / EXCEPTION HANDLING, Step 14~22)`. *진짜 fit policy 의 자리* = Block A. C block 은 *exception 처리 layer*.
**텍스트 list** (모든 22 step) :
```
Block A — PRE-RENDER PLANNING (Step 0~12)
Step 0 precondition (catalog / contract / V4 / template / asset)
Step 1 MDX 업로드
Step 2 MDX 정규화 (frontmatter / heading tree / footer)
Step 3 Content Object 추출 (text_block / table / image / details / ...)
Step 4 Section Internal Composition Planning (whole / group / split)
Step 5 V4 Matching Evidence (non-reject max-6 후보 list)
Step 6 Composition Planning (composition unit 결정)
Step 7 Slide-Level Layout Planning (8 preset vocabulary)
Step 8 Zone + Internal Region Ratio Planning
Step 9 Region-Level Frame / Display Selection (application_plan)
Step 10 Frame Contract 확인
Step 11 Content → Internal Region → Frame Slot Mapping
Step 12 Slot Payload 생성
Block B — RENDER (Step 13)
Step 13 Render (Jinja2 + frame partial → final.html)
Block C — POST-RENDER TELEMETRY / EXCEPTION HANDLING (Step 14~22)
Step 14 Selenium Visual Runtime Check
Step 15 Fit Classification
Step 16 Overflow Router
Step 17 Implemented Action 실행 (zone_ratio_retry / details_popup_escalation / ...)
Step 18 Failure Classification
Step 19 Next Action Proposal
Step 20 Slide Status 결정 (PASS / RENDERED_WITH_VISUAL_REGRESSION / ...)
Step 21 Debug / Trace 기록
Step 22 사용자 확인 / Export
```
각 step 의 ✅ / ⚠ / ❌ 정확한 상태는 [`STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) 가 single source of truth.
**위계 (Slide → Frame Slot)**:
```
Slide → Zone → Internal Region → Frame → Frame Slot → Content
```
22-step 도면 lock = [`docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md`](docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md)
현재 snapshot = [`docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md)
axis history = [`docs/architecture/PHASE-Z-CHANGE-LOG.md`](docs/architecture/PHASE-Z-CHANGE-LOG.md)
---
## 3. 현재 완료 수준
### 3.1 MDX03 정상 경로 (PASS)
```
overall : PASS
visual_check_passed : true
full_mdx_coverage : true
adapter_needed_count : 0
content_truncated_count: 0
units : 03-1 → F13 (use_as_is, 0.927)
03-2 → F29 (use_as_is, 0.920)
```
### 3.2 22-step 진행 수준
상세는 [`STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) 의 표 참조. 큰 그림:
- **✅ implemented**: Step 1 / 12 / 13 / 15 / 16 / 18 / 20
- **⚠ partial**: Step 0 / 2 / 5 / 6 / 7 / 8 / 9 / 10 / 14 / 17 / 19 / 21
- **❌ missing 또는 future**: Step 3 (content_object) / 4 (internal composition) / 11 (slot mapping) / 22 (UI)
→ 22-step 일반화 진행 수준 ≈ **65~70%**. MDX03 정상 경로는 *닫힘*. 일반화 (다른 MDX / edge case / fallback path / UI) 는 진행 중.
### 3.3 박힌 axis (시간 순)
이번 session 박힌 주요 axis:
- **Step 7-A / 7-B**: layout catalog yaml + select_layout_candidates(unit_count) (catalog axis)
- **Step 8-A / 8-B-1 / 8-B-2**: region_layouts.yaml + display_strategies.yaml + 후보 함수
- **Step 5 보완**: V4 rank-1 → non-reject max-6 후보 list
- **Step 6-A**: CompositionUnit 에 v4_candidates 필드 (additive, logic 무변)
- **Step 7-conn / 8-conn**: catalog 후보 함수 → runtime artifact 연결 (passive 기록)
- **Step 9 v0**: passive application_plan artifact (V4 후보 + layout/region/display 통합 trace)
- **F29 visual fidelity fix**: missing SVG 3 개 → CSS gradient 재현 (figma 원본 R8 룰 따라)
- **cleanup-1**: stale 주석 정정 (`pipeline 호출처 X` → 호출처 박힘)
### 3.4 폐기된 안 (history 보존)
CHANGE-LOG 에 박힘:
- **compat 매트릭스 안** (Step 9 초기 안) — V4 cardinality 재계산 위험으로 폐기
- **6-B (frame ownership transfer)** — misframed axis. V4 가 frame 선택, Step 6 은 전사, Step 9 는 번역. "Step 6 의 frame 채택 책임 이전" = 허구.
### 3.5 검증 / 실험 repo 성격
본 repo 는 *제품형 시스템* 까지의 진행 과정에서 *검증 재료* 로 다음 sample 사용:
- `samples/mdx_batch/03.mdx` — 기준 sample (MDX03 정상 경로 lock)
- `samples/mdx_batch/04.mdx` — MDX04 검증 예정
- `samples/mdx/01. ...mdx` / `02. ...mdx` — 향후 검증
샘플 MDX 는 *로드맵 단계* 가 아니라 *22-step pipeline 보완을 위한 검증 재료*.
---
## 4. 향후 로드맵
```mermaid
flowchart LR
R1["1. 22-step Pipeline
Stabilization
frame 연결 / visual check 보강 /
MDX 정리 / 01·02·04 검증"]
R2["2. Phase Q Audit & Salvage
옛 25 모듈 검토 → Z 이식"]
R3["3. AI Repair /
Restructure Layer
low score / reject /
restructure / overflow"]
R4["4. DB / Catalog
Integration
frame / V4 / runs / overrides"]
R5["5. Frontend Connection
run / timeline /
rank 후보 / plan"]
R6["6. HTML Editing /
User Overrides
user_overrides.json"]
R7["7. Continuous Frame
Adapter Updates
Figma → Phase Z adapter"]
R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7
classDef current fill:#fff3cd,stroke:#f59f00,color:#000
classDef future fill:#f3f0ff,stroke:#7048e8,color:#000
classDef later fill:#f8f9fa,stroke:#868e96,color:#000,stroke-dasharray: 5 5
class R1 current
class R2,R3 future
class R4,R5,R6,R7 later
```
**현재 위치** : 단계 (1) 22-step Pipeline Stabilization. MDX03 정상 경로 닫힘 / 일반화 진행 중.
### 단계별 상세
```
1. 22-step 파이프라인 정리 (현재)
├ frame ↔ Phase Z 연결 구조 정리 (= V4 frame 후보 → Phase Z render path 연결 확장)
│ · F14 / F11 / F18 등 미연결 frame 의 contract / partial / builder adapter
│ · Figma 새 디자인 X / V4 새 매칭 X — 이미 두 layer 에 있는 frame 의 adapter
├ visual check 범위 정리 (Step 14 보강)
│ · missing image / table clipping / image aspect mismatch / underfilled zone
├ MDX 정규화 / 정리 방법 적용 (Step 2 / 3 / 4)
└ MDX 01 / 02 / 04 검증을 통해 보완 (edge case 발견 + pipeline 일반화)
2. Phase Q 재검토 후 Phase Z 반영
├ src/ 안 옛 25 모듈 audit (slide_measurer, space_allocator, content_editor 등)
├ 살릴 기능 식별 → Phase Z 로 이식
└ tests/matching/ 의 V4 진화 history / DECK / ATTACH 자료도 같이 검토
3. AI 적용 관련 프로세스 정립 및 적용
├ low score / all reject / light_edit / restructure / overflow 반복 케이스
├ AI repair / restructure / popup / layout adjust
├ MDX 원문 보존 lock (AI 가 원문 삭제 / 요약 / 재작성 X)
└ 연결 step: Step 9 / 12 / 17 / 19 / 21
4. DB / Catalog 정리
├ frame catalog / contracts
├ V4 results
├ run history / step artifacts
├ user overrides
└ 선택 이력 (rank-N 사용자 선택 trace)
5. Front 연결
├ run 목록 / preview.png / final.html
├ 22-step timeline (각 step artifact 시각)
├ V4 rank 1~6 후보 표시 + 사용자 선택
├ layout / region / application_plan 표시
└ visual check / retry / failure / next action 결과
6. HTML 수정 기능 추가
├ 텍스트 수정
├ 이미지 크기 / 위치 조정
├ frame 후보 변경 (rank-N 선택)
├ layout / region 조정
└ user_overrides.json 저장 (final.html 직접 수정 X — MDX 원문 보존 정합)
7. 이후 frame 지속 업데이트
├ Figma → HTML 변환 추가 (figma_to_html_agent)
├ Phase Z adapter 연결 (1 의 frame ↔ Phase Z 연결 axis 와 같은 결)
├ contract / partial / builder 추가
└ V4 catalog 와 runtime 동기화
```
→ MDX03 / 04 / 01 / 02 검증은 **(1) 22-step 정리 안의 *수단*** — 별 단계 X.
---
## 5. 운영 기준
### 5.1 절대 lock
- **MDX 원문 무손실 보존** — AI 가 normal path 에서 MDX 원문을 *재작성 / 삭제 / 요약 X*. 원문은 본문 preview 또는 details/popup 에 *반드시* 보존.
- **자유 디자인 금지** — Figma frame DB / catalog / frame contract 기반으로만 디자인 결정. AI 가 frame / layout / 새 디자인 패턴 *생성 X*.
- **그릇 변경 원칙** — 콘텐츠가 안 맞을 때 *콘텐츠를 줄이지 않음*. *그릇* (layout / zone / region / frame / display strategy) 을 변경. 공통 CSS / padding / tolerance 임의 축소 *금지*.
- **dropped 절대 룰** — `text_block / table / image / details` 는 dropped 절대 X (catalog `forbidden_for` lock). decorative_element 만 dropped 가능.
### 5.2 V4 ↔ Phase Z 책임 분담
- **V4** = frame 선택 (점수 + label: use_as_is / light_edit / restructure / reject)
- **Step 5 (Phase Z)** = V4 후보 list 추출 (non-reject max-6, raw 32 entry 영속)
- **Step 6** = composition unit 결정 (어느 section 묶음 = 1 zone unit). 현재 V4 rank-1 default 전사
- **Step 9 v0** = V4 후보 → application_plan 번역 (V4 axis 재계산 X)
- `use_as_is` → `direct_insert`
- `light_edit` → `same_frame_with_adjustment`
- `restructure` → `layout_or_region_change` (auto_applicable=False, human_review delegate)
- `reject` → `exclude`
### 5.3 렌더 정책
- **현재 렌더** = V4 rank-1 (Step 6 default)
- **rank 2~6 보존** = Step 9 application_plan + Step 5 evidence 에 trace. 향후 frontend 에서 사용자 선택 가능.
- **final.html 직접 수정 X** — frontend 에서 변경 시 `user_overrides.json` 으로 누적 (원문 보존 정합).
---
## Repository Mirrors
본 프로젝트는 두 repository 에서 mirror 로 관리됨:
- **GitHub** : https://github.com/keimin86/design_agent
- **Gitea** : https://gitea.hmac.kr/Kyeongmin/C.E.L_Slide_test2
두 저장소의 README 와 코드 base 는 동일하게 유지 (push 시 둘 다 fast-forward).
---
## 참고 문서
| 문서 | 역할 |
|---|---|
| [`CLAUDE.md`](CLAUDE.md) | 프로젝트 규칙 + Phase Z 위계 |
| [`PHASE-Z-PIPELINE-OVERVIEW.md`](docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md) | 22-step 도면 (구조 lock) |
| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) | 현재 snapshot (✅ / ⚠ / ❌) |
| [`PHASE-Z-CHANGE-LOG.md`](docs/architecture/PHASE-Z-CHANGE-LOG.md) | axis-by-axis 의사결정 history |
| [`PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md`](docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md) | content_object + Internal Region + Frame Slot SPEC |
| [`PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md`](docs/architecture/PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md) | Step 14~19 telemetry layer SPEC |
| [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md) | Phase Z 통합 설계 핵심 |
| [`PROCESS_OVERVIEW.html`](PROCESS_OVERVIEW.html) | 임원 보고용 A4 2 페이지 (프로세스 + 구조도) |
| [`PROGRESS.md`](PROGRESS.md) | 전체 Phase 이력 (Phase 1~T + R' + Z) |