From ee011cb30701f16a3f6a0affae8f564b522e469d Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Fri, 8 May 2026 10:14:20 +0900 Subject: [PATCH] =?UTF-8?q?README=20=EB=8B=A4=EB=93=AC=EA=B8=B0:=20?= =?UTF-8?q?=ED=95=9C=EA=B8=80=20/=20=EB=8B=A8=EA=B3=84=EB=B3=84=20?= =?UTF-8?q?=EB=B0=95=EC=8A=A4=20/=20=EC=9A=A9=EC=96=B4=20=EC=84=A4?= =?UTF-8?q?=EB=AA=85=20/=20=EB=82=B4=EB=B6=80=20jargon=20=EC=A0=9C?= =?UTF-8?q?=EA=B1=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 이전 commit (b127606) 의 문제 정정 : - "박힘" / "박힌 axis" / "axis" 같은 세션 내부 표현 제거 → 평이한 한글 (단계 / 작업 / 정상으로 닫힘) - 22-step Mermaid 의 그룹화 (Step 1-2, 3-4, 10-12, 15-19) 풀어서 각 단계 별도 박스 - 모든 라벨 한글로 통일 (영문 mix 제거) - §1 에 핵심 용어 표 추가 — MDX / V4 / Phase Z / Frame / Internal Region / Frame Slot 처음 보는 사람도 이해할 수 있도록 한 줄 설명 - §3 의 partial / missing 분류 표 제거 — STATUS-BOARD 참조 한 줄로 단순화 (22-step 진행 수준 표는 자주 갱신되어야 하는 문서, README 적합 X) - §3 "박힌 axis (시간 순)" 섹션 제거 → CHANGE-LOG 참조 한 줄로 대체 내용 자체는 동일 (구조 / 로드맵 / 운영 원칙 / Mermaid 다이어그램 2 개). Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 385 ++++++++++++++++++++++++++---------------------------- 1 file changed, 188 insertions(+), 197 deletions(-) diff --git a/README.md b/README.md index 0eff81c..9262a73 100644 --- a/README.md +++ b/README.md @@ -2,106 +2,112 @@ ## 1. 프로젝트 개요 -MDX 문서를 입력받아 1280×720 프레젠테이션 슬라이드 HTML 로 자동 변환하는 파이프라인. +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 가 연결된 *제품형* 시스템 +- **입력**: MDX 파일 (텍스트 + 표 + 불릿 + JSX 블록 + details + 이미지) +- **변환 흐름**: V4 매칭 → Phase Z 렌더 파이프라인 +- **출력**: `final.html` (단일 슬라이드) + 단계별 산출물 (의사결정 추적) +- **최종 목표**: 파이프라인 + AI 보정 + DB / 카탈로그 + 프론트엔드 에디터가 연결된 *제품형* 시스템 -원천 디자인 = 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* 로 번역. +### 핵심 용어 (처음 보는 분 위해) ---- +| 용어 | 의미 | +|---|---| +| **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) | -## 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) +--- + +## 2. 전체 실행 구조 (22 단계 파이프라인) + +22 단계를 3 개 블록으로 묶어 운영합니다: + +- **블록 A — 렌더 전 계획 (Step 0~12)**: 모든 의사결정. 가장 중요한 영역. +- **블록 B — 렌더 (Step 13)**: Jinja2 + 프레임 partial → final.html. +- **블록 C — 렌더 후 점검 / 예외 처리 (Step 14~22)**: 시각 검증 + 필요 시 재시도. *블록 A 가 정밀하면 거의 동작 안 함*. + +```mermaid +flowchart TD + Input([MDX 입력]) + + subgraph BlockA["블록 A — 렌더 전 계획 (Step 0~12)"] + S0["Step 0
사전 준비
카탈로그 / 컨트랙트 / V4 결과"] + S1["Step 1
MDX 업로드"] + S2["Step 2
MDX 정규화
frontmatter / 목차 / 푸터 분리"] + S3["Step 3
콘텐츠 객체 추출
텍스트 / 표 / 이미지 / details"] + S4["Step 4
섹션 내부 구성 계획
전체 / 묶기 / 분할"] + S5["Step 5
V4 매칭 후보 추출
거절 제외 최대 6 개"] + S6["Step 6
구성 계획
어떤 섹션 묶음 = 한 zone"] + S7["Step 7
슬라이드 레이아웃 계획
8 개 프리셋 중 선택"] + S8["Step 8
Zone / Region 비율 계획"] + S9["Step 9
적용 계획
V4 후보를 어떻게 넣을지 번역"] + S10["Step 10
프레임 컨트랙트 확인"] + S11["Step 11
콘텐츠 → Region → Frame Slot 매핑"] + S12["Step 12
슬롯 데이터 생성"] + end + + subgraph BlockB["블록 B — 렌더 (Step 13)"] + S13["Step 13
HTML 렌더
Jinja2 + 프레임 partial → final.html"] + end + + subgraph BlockC["블록 C — 렌더 후 점검 / 예외 처리 (Step 14~22)"] + S14["Step 14
시각 점검
Selenium 으로 실제 렌더 검사"] + S15["Step 15
문제 분류
오버플로우 / 잘림 / 비율 어긋남"] + S16["Step 16
재시도 라우터
어떤 조치를 할지 선택"] + S17["Step 17
조치 실행
zone 비율 재시도 / 팝업 전환 / ..."] + S18["Step 18
실패 분류"] + S19["Step 19
다음 조치 제안"] + S20["Step 20
슬라이드 상태 결정
PASS / 시각 회귀 / ..."] + S21["Step 21
디버그 / 추적 기록"] + S22["Step 22
사용자 확인 / 내보내기"] + end + + Visual{"시각 점검 OK?"} + Repair{"수정 방식?"} + AI["AI 보정 / 재구성
(향후 예정)"] + + 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 -->|결정론적
zone 재시도 / 팝업 / 레이아웃 조정| S13 + Repair -->|AI 필요
재구성 / 점수 낮음 / 반복 오버플로우| 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`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) 가 단일 출처입니다 (자주 갱신됨). --- ## 3. 현재 완료 수준 -### 3.1 MDX03 정상 경로 (PASS) +### 3.1 MDX03 정상 경로 — 통과 + +기준 샘플 (`samples/mdx_batch/03.mdx`) 의 자동 렌더 경로가 정상으로 닫혔습니다. ``` overall : PASS @@ -109,49 +115,29 @@ 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) +units : 03-1 → F13 (그대로 사용 가능, 0.927) + 03-2 → F29 (그대로 사용 가능, 0.920) ``` -### 3.2 22-step 진행 수준 +### 3.2 22 단계 진행 수준 -상세는 [`STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) 의 표 참조. 큰 그림: +전체 약 **65~70%**. MDX03 정상 경로는 닫혔고, 일반화 (다른 MDX / 예외 케이스 / 재시도 / UI) 는 진행 중. -- **✅ 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) +상세 ✅ / ⚠ / ❌ 표는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) 에서 확인. -→ 22-step 일반화 진행 수준 ≈ **65~70%**. MDX03 정상 경로는 *닫힘*. 일반화 (다른 MDX / edge case / fallback path / UI) 는 진행 중. +### 3.3 검증 / 실험 저장소 성격 -### 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_batch/03.mdx` — 기준 샘플 (정상 경로 확인) +- `samples/mdx_batch/04.mdx` — 다음 검증 예정 - `samples/mdx/01. ...mdx` / `02. ...mdx` — 향후 검증 -샘플 MDX 는 *로드맵 단계* 가 아니라 *22-step pipeline 보완을 위한 검증 재료*. +**샘플 MDX 는 로드맵 단계가 아니라 22 단계 파이프라인을 보완하기 위한 검증 재료입니다.** + +### 3.4 결정 변경 이력 + +설계 변경 / 폐기된 안 / 일치 정정의 시간 순 기록은 [`PHASE-Z-CHANGE-LOG.md`](docs/architecture/PHASE-Z-CHANGE-LOG.md) 참조. --- @@ -159,13 +145,13 @@ CHANGE-LOG 에 박힘: ```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["1. 22 단계 파이프라인
안정화
프레임 연결 / 시각 점검 보강 /
MDX 정리 / 01·02·04 검증"] + R2["2. 옛 코드 검토
및 반영
Phase Q 25 모듈 audit"] + R3["3. AI 보정 /
재구성 단계
점수 낮음 / 모두 거절 /
재구성 / 오버플로우 반복"] + R4["4. DB / 카탈로그
정리
프레임 / V4 / 실행이력 / 사용자 변경"] + R5["5. 프론트엔드 연결
실행 목록 / 타임라인 /
매칭 후보 / 적용 계획"] + R6["6. HTML 수정 기능
user_overrides.json"] + R7["7. 프레임 지속
업데이트
Figma → Phase Z 어댑터 추가"] R1 --> R2 --> R3 --> R4 --> R5 --> R6 --> R7 @@ -178,99 +164,104 @@ flowchart LR class R4,R5,R6,R7 later ``` -**현재 위치** : 단계 (1) 22-step Pipeline Stabilization. MDX03 정상 경로 닫힘 / 일반화 진행 중. +**현재 위치**: 단계 1 (22 단계 파이프라인 안정화). 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 일반화) +**1. 22 단계 파이프라인 안정화 (현재)** -2. Phase Q 재검토 후 Phase Z 반영 - ├ src/ 안 옛 25 모듈 audit (slide_measurer, space_allocator, content_editor 등) - ├ 살릴 기능 식별 → Phase Z 로 이식 - └ tests/matching/ 의 V4 진화 history / DECK / ATTACH 자료도 같이 검토 +- 프레임 ↔ 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 검증으로 예외 케이스 발견 + 파이프라인 일반화 -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 +**2. 옛 코드 검토 및 반영** -4. DB / Catalog 정리 - ├ frame catalog / contracts - ├ V4 results - ├ run history / step artifacts - ├ user overrides - └ 선택 이력 (rank-N 사용자 선택 trace) +- `src/` 안 옛 25 개 모듈 (slide_measurer, space_allocator, content_editor 등) 각각 검토 +- 살릴 기능 / 폐기할 모듈 / 학습 자료로만 둘 것 분류 +- 살릴 것은 Phase Z 로 이식 -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 결과 +**3. AI 보정 / 재구성 단계** -6. HTML 수정 기능 추가 - ├ 텍스트 수정 - ├ 이미지 크기 / 위치 조정 - ├ frame 후보 변경 (rank-N 선택) - ├ layout / region 조정 - └ user_overrides.json 저장 (final.html 직접 수정 X — MDX 원문 보존 정합) +- 점수 낮음 / 모두 거절 / 재구성 필요 / 오버플로우 반복 케이스 처리 +- AI 가 MDX 원문은 보존하면서 슬롯 데이터 / Region / 팝업 / 레이아웃 제안 +- 연결되는 단계: Step 9 / 12 / 17 / 19 / 21 -7. 이후 frame 지속 업데이트 - ├ Figma → HTML 변환 추가 (figma_to_html_agent) - ├ Phase Z adapter 연결 (1 의 frame ↔ Phase Z 연결 axis 와 같은 결) - ├ contract / partial / builder 추가 - └ V4 catalog 와 runtime 동기화 -``` +**4. DB / 카탈로그 정리** -→ MDX03 / 04 / 01 / 02 검증은 **(1) 22-step 정리 안의 *수단*** — 별 단계 X. +- 프레임 카탈로그 / 컨트랙트 +- 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. 운영 원칙 -### 5.1 절대 lock +### 5.1 절대 원칙 -- **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 가능. +- **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** = 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` +| 시스템 | 역할 | +|---|---| +| **V4** | 프레임 *선택* — 점수 + 라벨 (그대로 사용 / 가벼운 편집 / 재구성 / 거절) | +| **Step 5** | V4 후보를 거절 제외 최대 6 개로 정리 | +| **Step 6** | 구성 단위 결정 (어느 섹션 묶음 = 1 zone) — 현재는 V4 1 위를 그대로 채택 | +| **Step 9** | V4 후보를 *어떻게 적용할지* 번역 (V4 점수를 다시 계산하지 않음) | + +V4 라벨 → 적용 방식 변환: +- `그대로 사용` → 바로 삽입 +- `가벼운 편집` → 같은 프레임에 약간 조정 +- `재구성` → 레이아웃 / Region 변경 (자동으로는 적용 안 함, 사람 확인) +- `거절` → 제외 ### 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` 으로 누적 (원문 보존 정합). +- 현재 렌더는 V4 의 1 위 후보 사용 +- 2~6 위는 보존만 — 향후 프론트엔드에서 사용자가 선택할 수 있게 +- `final.html` 을 직접 수정하지 않음 — 프론트엔드에서 변경 시 `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 +- **Gitea** : https://gitea.hmac.kr/Kyeongmin/C.E.L_Slide_test2 -두 저장소의 README 와 코드 base 는 동일하게 유지 (push 시 둘 다 fast-forward). +두 저장소의 README 와 코드 베이스는 동일하게 유지 (push 시 둘 다 fast-forward). --- @@ -279,11 +270,11 @@ flowchart LR | 문서 | 역할 | |---|---| | [`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 통합 설계 핵심 | +| [`PHASE-Z-PIPELINE-OVERVIEW.md`](docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md) | 22 단계 도면 (구조 잠금) | +| [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md) | 현재 진행 상태 (✅ / ⚠ / ❌) | +| [`PHASE-Z-CHANGE-LOG.md`](docs/architecture/PHASE-Z-CHANGE-LOG.md) | 결정 변경 이력 | +| [`PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md`](docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md) | 콘텐츠 객체 + Internal Region + Frame Slot 명세 | +| [`PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md`](docs/architecture/PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md) | Step 14~19 점검 / 라우팅 명세 | +| [`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) |