C.E.L_Slide_test2/README.md

Design Agent / C.E.L Slide Automation

1. 프로젝트 개요

MDX 문서를 입력받아 1280×720 프레젠테이션 슬라이드 HTML 로 자동 변환하는 파이프라인입니다.

• 입력: MDX 파일 (텍스트 + 표 + 불릿 + JSX 블록 + details + 이미지)
• 변환 흐름: V4 매칭 → Phase Z 렌더 파이프라인
• 출력: final.html (단일 슬라이드) + 단계별 산출물 (의사결정 추적)
• 최종 목표: 파이프라인 + AI 보정 + DB / 카탈로그 + 프론트엔드 에디터가 연결된 제품형 시스템

핵심 용어 (처음 보는 분 위해)

용어	의미
MDX	마크다운 + JSX 컴포넌트 결합 형식. 슬라이드의 원본 콘텐츠
Figma BEPs frame	디자인 원천. 32 개의 Figma 프레임을 HTML / CSS 로 변환해 figma_to_html_agent/blocks/ 에 누적
V4	MDX 섹션 ↔ Figma 프레임 매칭 시스템 (네 번째 버전). 콘텐츠 의미 / 구조 / 키워드 / 카디널리티 등 5 개 축으로 점수화. tests/matching/v4_full32_result.yaml 에 결과 저장
Phase Z	현재 활성 렌더 파이프라인. V4 매칭 결과를 받아 슬라이드 HTML 로 만듦
프레임 (Frame)	Figma 디자인 단위. 1 개의 슬라이드 영역(zone) 안에 들어감
Internal Region	zone 내부의 콘텐츠 배치 단위 (text 영역, table 영역, image 영역 등)
Frame Slot	frame 내부의 콘텐츠 자리 (예: pillar_1, quadrant_1, process_column)

위계

Slide → Zone → Internal Region → Frame → Frame Slot → Content

---

2. 전체 실행 구조 (22 단계 파이프라인)

22 단계를 3 개 블록으로 묶어 운영합니다:

• 블록 A — 렌더 전 계획 (Step 0~12): 모든 의사결정. 가장 중요한 영역.
• 블록 B — 렌더 (Step 13): Jinja2 + 프레임 partial → final.html.
• 블록 C — 렌더 후 점검 / 예외 처리 (Step 14~22): 시각 검증 + 필요 시 재시도. 블록 A 가 정밀하면 거의 동작 안 함.

flowchart TD
    Input([MDX 입력])

    subgraph BlockA["블록 A — 렌더 전 계획 (Step 0~12)"]
        S0["Step 0<br/>사전 준비<br/><sub>카탈로그 / 컨트랙트 / V4 결과</sub>"]
        S1["Step 1<br/>MDX 업로드"]
        S2["Step 2<br/>MDX 정규화<br/><sub>frontmatter / 목차 / 푸터 분리</sub>"]
        S3["Step 3<br/>콘텐츠 객체 추출<br/><sub>텍스트 / 표 / 이미지 / details</sub>"]
        S4["Step 4<br/>섹션 내부 구성 계획<br/><sub>전체 / 묶기 / 분할</sub>"]
        S5["Step 5<br/>V4 매칭 후보 추출<br/><sub>거절 제외 최대 6 개</sub>"]
        S6["Step 6<br/>구성 계획<br/><sub>어떤 섹션 묶음 = 한 zone</sub>"]
        S7["Step 7<br/>슬라이드 레이아웃 계획<br/><sub>8 개 프리셋 중 선택</sub>"]
        S8["Step 8<br/>Zone / Region 비율 계획"]
        S9["Step 9<br/>적용 계획<br/><sub>V4 후보를 어떻게 넣을지 번역</sub>"]
        S10["Step 10<br/>프레임 컨트랙트 확인"]
        S11["Step 11<br/>콘텐츠 → Region → Frame Slot 매핑"]
        S12["Step 12<br/>슬롯 데이터 생성"]
    end

    subgraph BlockB["블록 B — 렌더 (Step 13)"]
        S13["Step 13<br/>HTML 렌더<br/><sub>Jinja2 + 프레임 partial → final.html</sub>"]
    end

    subgraph BlockC["블록 C — 렌더 후 점검 / 예외 처리 (Step 14~22)"]
        S14["Step 14<br/>시각 점검<br/><sub>Selenium 으로 실제 렌더 검사</sub>"]
        S15["Step 15<br/>문제 분류<br/><sub>오버플로우 / 잘림 / 비율 어긋남</sub>"]
        S16["Step 16<br/>재시도 라우터<br/><sub>어떤 조치를 할지 선택</sub>"]
        S17["Step 17<br/>조치 실행<br/><sub>zone 비율 재시도 / 팝업 전환 / ...</sub>"]
        S18["Step 18<br/>실패 분류"]
        S19["Step 19<br/>다음 조치 제안"]
        S20["Step 20<br/>슬라이드 상태 결정<br/><sub>PASS / 시각 회귀 / ...</sub>"]
        S21["Step 21<br/>디버그 / 추적 기록"]
        S22["Step 22<br/>사용자 확인 / 내보내기"]
    end

    Visual{"시각 점검 OK?"}
    Repair{"수정 방식?"}
    AI["AI 보정 / 재구성<br/><i>(향후 예정)</i>"]

    Input --> S0 --> S1 --> S2 --> S3 --> S4 --> S5
    S5 --> S6 --> S7 --> S8 --> S9 --> S10 --> S11 --> S12
    S12 --> S13 --> S14 --> Visual
    Visual -->|예| S20 --> S21 --> S22
    Visual -->|아니오| S15 --> S16 --> S17 --> S18 --> S19 --> Repair
    Repair -->|결정론적<br/>zone 재시도 / 팝업 / 레이아웃 조정| S13
    Repair -->|AI 필요<br/>재구성 / 점수 낮음 / 반복 오버플로우| AI
    AI --> S13

    classDef plan fill:#e7f5ff,stroke:#1971c2,color:#000
    classDef render fill:#fff3cd,stroke:#f59f00,color:#000
    classDef check 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 S0,S1,S2,S3,S4,S5,S6,S7,S8,S9,S10,S11,S12 plan
    class S13 render
    class S14,S15,S16,S17,S18,S19,S20,S21,S22 check
    class Visual,Repair decision
    class AI future

각 단계의 자세한 진행 상태는 PHASE-Z-PIPELINE-STATUS-BOARD.md 가 단일 출처입니다 (자주 갱신됨).

---

3. 현재 완료 수준

3.1 MDX03 정상 경로 — 통과

기준 샘플 (samples/mdx_batch/03.mdx) 의 자동 렌더 경로가 정상으로 닫혔습니다.

overall                : PASS
visual_check_passed    : true
full_mdx_coverage      : true
adapter_needed_count   : 0
content_truncated_count: 0
units                  : 03-1 → F13 (그대로 사용 가능, 0.927)
                         03-2 → F29 (그대로 사용 가능, 0.920)

3.2 22 단계 진행 수준

전체 약 65~70%. MDX03 정상 경로는 닫혔고, 일반화 (다른 MDX / 예외 케이스 / 재시도 / UI) 는 진행 중.

상세 ✅ / ⚠ / ❌ 표는 PHASE-Z-PIPELINE-STATUS-BOARD.md 에서 확인.

3.3 검증 / 실험 저장소 성격

본 저장소는 제품형 시스템 까지 가는 과정에서 다음 샘플을 검증 재료 로 사용:

• samples/mdx_batch/03.mdx — 기준 샘플 (정상 경로 확인)
• samples/mdx_batch/04.mdx — 다음 검증 예정
• samples/mdx/01. ...mdx / 02. ...mdx — 향후 검증

샘플 MDX 는 로드맵 단계가 아니라 22 단계 파이프라인을 보완하기 위한 검증 재료입니다.

3.4 결정 변경 이력

설계 변경 / 폐기된 안 / 일치 정정의 시간 순 기록은 PHASE-Z-CHANGE-LOG.md 참조.

---

4. 향후 로드맵

flowchart LR
    R1["1. 22 단계 파이프라인<br/>안정화<br/><sub>프레임 연결 / 시각 점검 보강 /<br/>MDX 정리 / 01·02·04 검증</sub>"]
    R2["2. 옛 코드 검토<br/>및 반영<br/><sub>Phase Q 25 모듈 audit</sub>"]
    R3["3. AI 보정 /<br/>재구성 단계<br/><sub>점수 낮음 / 모두 거절 /<br/>재구성 / 오버플로우 반복</sub>"]
    R4["4. DB / 카탈로그<br/>정리<br/><sub>프레임 / V4 / 실행이력 / 사용자 변경</sub>"]
    R5["5. 프론트엔드 연결<br/><sub>실행 목록 / 타임라인 /<br/>매칭 후보 / 적용 계획</sub>"]
    R6["6. HTML 수정 기능<br/><sub>user_overrides.json</sub>"]
    R7["7. 프레임 지속<br/>업데이트<br/><sub>Figma → Phase Z 어댑터 추가</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 단계 파이프라인 안정화). MDX03 정상 경로 닫힘 → 일반화 진행 중.

단계별 상세

1. 22 단계 파이프라인 안정화 (현재)

• 프레임 ↔ Phase Z 연결 구조 정리
  • F14 / F11 / F18 등 Phase Z 가 아직 받지 못하는 Figma 프레임의 어댑터 추가
  • Figma 새 디자인이나 V4 새 매칭이 아니라, 이미 두 곳 (Figma / V4) 에 있는 프레임을 Phase Z 런타임이 받아 쓸 수 있게 연결만
• 시각 점검 범위 확장 (Step 14)
  • 누락 이미지 / 표 잘림 / 이미지 비율 어긋남 / 빈 공간 검사
• MDX 정규화 / 정리 방법 적용 (Step 2 / 3 / 4)
• MDX 01 / 02 / 04 검증으로 예외 케이스 발견 + 파이프라인 일반화

2. 옛 코드 검토 및 반영

• src/ 안 옛 25 개 모듈 (slide_measurer, space_allocator, content_editor 등) 각각 검토
• 살릴 기능 / 폐기할 모듈 / 학습 자료로만 둘 것 분류
• 살릴 것은 Phase Z 로 이식

3. AI 보정 / 재구성 단계

• 점수 낮음 / 모두 거절 / 재구성 필요 / 오버플로우 반복 케이스 처리
• AI 가 MDX 원문은 보존하면서 슬롯 데이터 / Region / 팝업 / 레이아웃 제안
• 연결되는 단계: Step 9 / 12 / 17 / 19 / 21

4. DB / 카탈로그 정리

• 프레임 카탈로그 / 컨트랙트
• V4 결과
• 실행 이력 / 단계별 산출물
• 사용자 변경 이력 (어떤 후보를 골랐는지 등)

5. 프론트엔드 연결

• 실행 목록 / preview.png / final.html 보기
• 22 단계 타임라인 (각 단계 산출물 시각화)
• V4 1~6 위 후보 표시 + 사용자 선택
• 레이아웃 / Region / 적용 계획 표시
• 시각 점검 / 재시도 / 다음 조치 결과

6. HTML 수정 기능

• 텍스트 수정
• 이미지 크기 / 위치 조정
• 프레임 후보 변경 (V4 의 1 위 외 다른 위 선택)
• 레이아웃 / Region 조정
• user_overrides.json 으로 저장 (final.html 직접 수정 X — MDX 원문 보존 원칙 정합)

7. 프레임 지속 업데이트

• Figma → HTML 변환 추가 (figma_to_html_agent/)
• Phase Z 어댑터 연결 (단계 1 의 작업과 같은 방식)
• 컨트랙트 / partial / 빌더 추가
• V4 카탈로그와 런타임 동기화

---

5. 운영 원칙

5.1 절대 원칙

• MDX 원문 무손실 보존 — AI 가 일반 경로에서 MDX 원문을 재작성 / 삭제 / 요약하지 않음. 원문은 본문 미리보기 또는 자세히보기 / 팝업 어딘가에 반드시 보존.
• 자유 디자인 금지 — Figma 프레임 DB / 카탈로그 / 컨트랙트 기반으로만 디자인 결정. AI 가 프레임 / 레이아웃 / 새 디자인 패턴을 생성하지 않음.
• 그릇 변경 원칙 — 콘텐츠가 안 맞을 때 콘텐츠를 줄이지 않음. 대신 그릇 (레이아웃 / zone / Region / 프레임 / 표시 방식) 을 변경. 공통 CSS / padding / tolerance 임의 축소 금지.
• dropped 절대 룰 — text_block / table / image / details 콘텐츠는 절대 삭제하지 않음. 장식 요소 (decorative_element) 만 공간 부족 시 dropped 가능.

5.2 V4 ↔ Phase Z 책임 분담

시스템	역할
V4	프레임 선택 — 점수 + 라벨 (그대로 사용 / 가벼운 편집 / 재구성 / 거절)
Step 5	V4 후보를 거절 제외 최대 6 개로 정리
Step 6	구성 단위 결정 (어느 섹션 묶음 = 1 zone) — 현재는 V4 1 위를 그대로 채택
Step 9	V4 후보를 어떻게 적용할지 번역 (V4 점수를 다시 계산하지 않음)

V4 라벨 → 적용 방식 변환:

• 그대로 사용 → 바로 삽입
• 가벼운 편집 → 같은 프레임에 약간 조정
• 재구성 → 레이아웃 / Region 변경 (자동으로는 적용 안 함, 사람 확인)
• 거절 → 제외

5.3 렌더 정책

• 현재 렌더는 V4 의 1 위 후보 사용
• 2~6 위는 보존만 — 향후 프론트엔드에서 사용자가 선택할 수 있게
• final.html 을 직접 수정하지 않음 — 프론트엔드에서 변경 시 user_overrides.json 으로 누적 (원문 보존 원칙과 정합)

---

Repository Mirrors

본 프로젝트는 두 저장소에서 미러로 관리됩니다:

• GitHub : https://github.com/keimin86/design_agent
• Gitea : https://gitea.hmac.kr/Kyeongmin/C.E.L_Slide_test2

두 저장소의 README 와 코드 베이스는 동일하게 유지 (push 시 둘 다 fast-forward).

---

참고 문서

문서	역할
CLAUDE.md	프로젝트 규칙 + Phase Z 위계
PHASE-Z-PIPELINE-OVERVIEW.md	22 단계 도면 (구조 잠금)
PHASE-Z-PIPELINE-STATUS-BOARD.md	현재 진행 상태 (✅ / ⚠ / ❌)
PHASE-Z-CHANGE-LOG.md	결정 변경 이력
PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md	콘텐츠 객체 + Internal Region + Frame Slot 명세
PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md	Step 14~19 점검 / 라우팅 명세
IMPROVEMENT-REDESIGN.md	Phase Z 통합 설계
PROCESS_OVERVIEW.html	임원 보고용 A4 2 페이지 (프로세스 + 구조도)
PROGRESS.md	전체 Phase 이력 (Phase 1~T + R' + Z)