C.E.L_Slide_test2/README.md

# 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<br/>MDX Upload & Normalize"]
    S1_2 --> S3_4["Step 3-4<br/>Content Object &<br/>Internal Composition Planning"]
    S3_4 --> S5["Step 5<br/>V4 Frame Evidence<br/><sub>rank 1 + non-reject max-6</sub>"]
    S5 --> S6["Step 6<br/>Composition Planning"]
    S6 --> S7["Step 7<br/>Layout Candidates<br/><sub>8 preset vocabulary</sub>"]
    S7 --> S8["Step 8<br/>Zone / Internal Region /<br/>Display Strategy"]
    S8 --> S9["Step 9<br/>Application Plan<br/><sub>V4 후보 → 적용 방식 번역</sub>"]
    S9 --> S10_12["Step 10-12<br/>Frame Contract / Slot Mapping / Payload"]
    S10_12 --> S13["Step 13<br/>Render final.html<br/><sub>Jinja2 + frame partial</sub>"]
    S13 --> S14["Step 14<br/>Visual Runtime Check<br/><sub>Selenium</sub>"]
    S14 --> Visual{"Visual OK?"}
    Visual -->|Yes| S20["Step 20<br/>PASS / Slide Status"]
    Visual -->|No| S15_19["Step 15-19<br/>Fit Classification / Router /<br/>Retry / Next Action"]
    S15_19 --> Repair{"Repair 방식?"}
    Repair -->|Deterministic<br/>zone_ratio / popup / layout_adjust| S13
    Repair -->|AI Required<br/>restructure / low score / overflow 반복| AI["AI Repair / Restructure Layer<br/><sub>(향후 axis)</sub>"]
    AI --> S13
    S20 --> S21_22["Step 21-22<br/>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<br/>Stabilization<br/><sub>frame 연결 / visual check 보강 /<br/>MDX 정리 / 01·02·04 검증</sub>"]
    R2["2. Phase Q Audit & Salvage<br/><sub>옛 25 모듈 검토 → Z 이식</sub>"]
    R3["3. AI Repair /<br/>Restructure Layer<br/><sub>low score / reject /<br/>restructure / overflow</sub>"]
    R4["4. DB / Catalog<br/>Integration<br/><sub>frame / V4 / runs / overrides</sub>"]
    R5["5. Frontend Connection<br/><sub>run / timeline /<br/>rank 후보 / plan</sub>"]
    R6["6. HTML Editing /<br/>User Overrides<br/><sub>user_overrides.json</sub>"]
    R7["7. Continuous Frame<br/>Adapter Updates<br/><sub>Figma → Phase Z adapter</sub>"]

    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) |