docs: start Phase Q audit and lock salvage policy

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-08 18:06:15 +09:00
parent b56fd20ae5
commit 3b6d86a73c
2 changed files with 448 additions and 5 deletions
--- a/docs/architecture/PHASE-Z-ROADMAP.md
+++ b/docs/architecture/PHASE-Z-ROADMAP.md
@@ -1,7 +1,7 @@
 # Phase Z Roadmap

 **문서 성격**: 앞으로의 진행 순서 + 큰 axis + 우선순위. *자주 갱신*.
-**작성일**: 2026-05-08
+**작성일**: 2026-05-08 (frontend 통합 session 반영)
 **문서 역할 분담**: 본 문서는 *진행 계획*. 정확한 단계별 상태는 [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md), 결정 변경 이력은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md), 22 단계 도면은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).

 > **현재 당장 할 일은 개발 진행이 아니라, 보고와 피드백을 위한 `PROCESS_OVERVIEW.html` 프로토타입을 먼저 만드는 것이다.**
@@ -41,6 +41,34 @@
 - README 통합 갱신 — 한글 / 22-step Mermaid / 로드맵 Mermaid
 - push 완료 — origin (GitHub) + slide2 (Gitea)

+### 2-B. Frontend 통합 session 닫힌 작업 (보고용 1차 초안)
+
+frontend (`design_agent_front/design-agent`) 와 backend phase_z2 의 연결 axis :
+
+- **Vite plugin endpoint 들** — 외부 backend 없이 단일 dev server 안에서 spawn :
+  - `POST /api/run` (overrides body 받아 CLI 인자로 forward)
+  - `GET /data/runs/{run_id}/{path}` (run artifact serving)
+  - `GET /frame-preview/{frame_number}` (`data/figma_previews/{NN}.png` 서빙)
+  - `GET /api/sample-mdx` (데모용 fixed mdx03 자동 로드)
+- **Backend Step 7-A (override CLI 인자)** :
+  - `--override-layout PRESET` (8 preset 중 하나 강제)
+  - `--override-frame UNIT_ID=TEMPLATE_ID` (multiple)
+  - `--override-zone-geometry ZONE_ID=X,Y,W,H` (multiple, horizontal-2 / vertical-2 만 적용)
+  - catalog 미등록 frame 보호 — `frame_overrides_skipped` trace
+- **Backend trace 확장** — `step09.units[].v4_all_judgments` (reject 포함 32 entry, `catalog_registered` flag, `frame_overrides_applied/skipped`, `layout_override_applied`, `auto_layout_preset`)
+- **Frontend SlideCanvas** :
+  - iframe 안 `.zone[data-zone-position]` + `.slide-body` boundingClientRect 측정 → zone overlay 좌표 정확
+  - iframe contentDocument CSS injection (html/body margin/padding/min-height 강제 — standalone 표시용 잘림 방지)
+  - 8 preset layout 별 zone overlay rendering
+  - frame top-6 표시 + V4 label badge + figma_previews thumbnail + catalog 미등록 회색 차별
+  - selected frame preview overlay (반투명 미리보기)
+  - section drag-drop drop target (LeftMdxPanel 의 native drag → SlideCanvas zone drop)
+  - **HTML 편집 모드** (글벗 editor.js 패턴 차용 : designMode + contentEditable + outline CSS) — 텍스트 변경 시 `hasPendingChanges` 트리거
+  - **pendingLayout 모드** — 다른 layout "적용하기" → slide-body 영역만 빈 layout 으로 전환 + zone resize 8 방향 handle (edge × 4 + corner × 4) + section drag drop 자동 carry over
+  - "선택대로 재생성하기" 버튼 — `userSelection.overrides` → `PipelineOverrides` 변환 후 `/api/run` forwarding
+- **Frontend MDX 트리 분해 (frontend re-parse)** — `parseMdxText` 가 `##` 중목차 + `###` 소목차 분해. `loadRun` 에서 backend section 의 `raw_content` 앞에 `## __ROOT__` prefix 임시 추가해서 sub_sections 추출 (Stage 0 normalize 가 backend 에 통합 안 된 임시 우회)
+- **데모 fixed input** — 페이지 로드 시 자동 `samples/mdx/03 ...` fetch → 사용자 업로드 단계 skip
+
 각 axis 상세 의사결정 / 폐기 / lock 은 [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) 참조.

 ---
@@ -99,14 +127,37 @@

 ---

-## 5. 우선순위
+## 5. 우선순위 (2026-05-08 갱신 — frontend 통합 session 후)

 ```
-1. 보고용 HTML 프로토타입 작성        ← 지금 당장 할 일
-2. 보고 / 피드백 수집
-3. Phase Z 파이프라인 작업 복귀 (22 단계 정리 계속)
+0. 보고용 link 1차 (현재 — 닫는 중)
+
+1. §7-B 항목별 목적 / input / output 정리 + Phase Q audit & salvage
+   - 먼저 lens 잡고 (각 보완 항목의 목적·input·output)
+   - 그 lens 로 Phase Q 모듈 10 개 검토 (Keep / Migrate / Reference / Delete)
+   - 통합 정책은 [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) §0-A 따름 (10 원칙 lock)
+   - 산출물: docs/architecture/PHASE-Q-AUDIT.md
+
+2. 22 단계 backend 본체 보완
+   - audit 결과 반영 (Migrate 항목 우선 통합)
+   - frontend session 에서 발견된 보완 지점 (§7-B A 그룹) 반영
+   - Stage 0 normalize / V4 fallback / zone 좌표 export / slide-base iframe / catalog 확장 등
+
+3. Frontend 추가 보완 (AI 투입 / HTML 수정 backend 적용 / DB 연결)
+   - §7-B B 그룹 (zone-section assignment / edited HTML → MDX 등)
+   - §7-B D 그룹 (filtered reason UI / min_height 한계 / status badge 안내)
+
+4. 전체 일반화 + 시스템 audit
+   4a. MDX 01 / 02 / 04 fresh run (regression / status / coverage 검증)
+   4b. 코드 audit (dead code / stale comment / type drift)
+   4c. frame catalog audit (등록 수 / contract 일관성 / preview.png 일관성)
+   4d. DB / data 활용 audit (assets / runs / static 폴더 정리 수준)
+
+5. Clean up (4 의 결과를 input 으로)
 ```

+§7-B 의 항목 구현 순서는 §1 의 audit 결과로 재정렬됨 — 본 §5 가 최상위 axis.
+
 ---

 ## 6. 보고용 프로토타입 계획
@@ -146,6 +197,53 @@

 ---

+## 7-B. Frontend 통합으로 드러난 보완 지점 (2026-05-08)
+
+이번 frontend session 에서 *기능적인 것을 해결하기 위해 frontend 가 임시로 채운 부분* + *backend 본체가 보완해야 의미 있는 axis* 정리.
+
+> **본 표는 §5 의 1 단계 audit lens** — 각 항목의 *목적 / input / output* 을 먼저 채우면 Phase Q 모듈 검토 시 *명확한 질문* 이 됨 ("이 schema 와 같은 코드가 Phase Q 에 있나? Migrate / Reference / Delete 어느 쪽?"). audit 결과로 본 §7-B 의 구현 우선순위가 재정렬됨.
+
+### A. Backend 본체 보완 (큰 axis)
+
+| # | 항목 | 이유 / 영향 | 임시 대체 |
+|---|---|---|---|
+| A-1 | **Stage 0 normalize 통합** — `mdx_normalizer.normalize_mdx_content` 를 phase_z2 가 호출 | 표준 input (정리된 bullet MDX) 외 (HTML-heavy raw) 입력 처리 못 함. step03 추출이 1 ContentObject 로 뭉침 → cardinality strict frame 과 mismatch → filter | frontend 가 raw_content 앞에 `## __ROOT__` prefix 붙여 sub_sections 만 추출. content_objects 는 통째로 (별 axis 보류 — `project_phase_z_normalize_gap.md`) |
+| A-2 | **Catalog 확장** — frame_contracts.yaml + frame_partials 더 많은 frame 등록 (현재 3 개 → 32 개 목표) | 사용자 frame 변경 의미 거의 불가 (V4 32 후보 중 use_as_is/light_edit 만 있어도 catalog 미등록이면 backend 가 skip). MDX03 외 다른 sample 일반화 어려움 | frontend 가 `catalog_registered: false` 카드 시각 차별 + handleGenerate 에서 forward 미시도. 사용자에게 "catalog 미등록 — render path 미연결" toast |
+| A-3 | **Frame preview png 일관성** — 모든 catalog frame 의 일관된 preview.png 자동 생성 | `figma_to_html_agent/blocks/{frame_id}/preview.png` 가 inconsistent (일부 frame 만 존재). frontend 가 어떤 source 든 통일해야 | 32 개 모두 있는 `data/figma_previews/{NN}.png` (Figma original export) 사용. frame 별 *실제 렌더 결과* 가 아닌 *Figma 디자인* 표시 |
+| A-4 | **slide-base.html iframe-friendly mode** — body padding / centering / min-height 가 standalone 모드용. iframe embed 시 잘림 | frontend 가 매 iframe onLoad 마다 contentDocument 에 reset CSS 주입 (모든 frame 영향) | frontend CSS injection 으로 우회. 진짜 fix 는 slide-base 가 query string `?embedded=1` 같은 시그널 받아 conditional padding |
+| A-5 | **V4 후보 자동 fallback** — rank-1 capacity / cardinality / structure mismatch 시 자동 rank-2/3 시도 | 03-1 처럼 rank-1 (`three_parallel_requirements`, strict cardinality 3) 가 추출 0 items 와 mismatch → filtered_capacity. 사용자 입장에서 "왜 빠졌는지" 알기 어려움 | (없음. frontend 는 reject + filtered 결과를 그대로 받아 표시) |
+| A-6 | **Zone DOM 좌표 export** — backend 가 `.zone[data-zone-position]` / `.slide-body` 의 절대 px 좌표를 step08 또는 별도 step 에 export | frontend 가 매 iframe onLoad 마다 boundingClientRect 측정 — 비용 + iframe 안 DOM 변경 시 stale | (없음. iframe 측정으로 우회) |
+
+### B. Backend Override path 확장 (Step D-ext 나머지)
+
+| # | 항목 | 이유 |
+|---|---|---|
+| B-1 | **Zone-section assignment override** — `--override-section-assignment ZONE_ID=section_id,section_id` CLI 인자 + composition planner 의 자동 결정을 user override 로 강제 | pendingLayout 모드의 section drag drop 결과가 backend 에 적용되도록. 현재 frontend visual 만 |
+| B-2 | **Edited HTML → MDX 역변환** — 글벗의 `html_to_slide_mdx` 패턴 차용. frontend 의 `iframe.contentDocument.querySelector('.slide').outerHTML` → backend → MDX → pipeline 재실행 | 편집 모드에서 사용자가 텍스트 수정한 결과가 새 final.html 에 반영. 현재 frontend visual 만 |
+| B-3 | **Sub-section (### 단위) drag drop 처리** — backend 가 sub-section id 를 인식해서 zone 에 sub-section 단위로 매핑 | LeftMdxPanel 의 트리 (S1.1, S1.2 ...) drag drop 결과가 의미 있게 적용되도록 |
+| B-4 | **다른 layout 의 zone-geometry override** — 현재 horizontal-2 / vertical-2 만. top-1-bottom-2 / top-2-bottom-1 / left-1-right-2 / left-2-right-1 / grid-2x2 도 지원 | 사용자가 어떤 layout 에서든 자유 zone resize 가능 |
+
+### C. Frontend 일관성 정리 (drift 정리)
+
+| # | 항목 |
+|---|---|
+| C-1 | `userSelection.selectedZoneId` schema — `zone.id` (e.g., `zone-03-1`, `pending-zone-N`) vs `zone.zone_id` (e.g., `top`, `primary`) 양쪽 매칭 일관화 |
+| C-2 | `zone_sections` / `zone_geometries` / `zone_frames` 의 key 통일 (zone_id 또는 region.id) |
+| C-3 | `effectiveSlidePlan` swap 로직이 누락된 component 정리 (FramePanel / LayoutPanel / 기타) |
+| C-4 | Toaster 제거 후 inline status bar 도입 (선택) — 현재 toast 호출은 silent (비표시) |
+| C-5 | resize 좌표 schema 통일 (slide-body 내부 0~1 vs 1280×720 절대) — pendingLayout 만 활성으로 단순화한 상태이지만 향후 다양한 mode 지원 시 명확화 |
+
+### D. UX 보완
+
+| # | 항목 |
+|---|---|
+| D-1 | **filtered_section_reasons 노출 UI** — backend `step20_slide_status.json` 의 filter 사유를 frontend 가 헤더 / 패널에 표시 (Step 8 coverage UI) |
+| D-2 | **Zone resize 시 frame min_height 한계 표시** — frame contract 의 min_height_px 를 frontend 가 받아서 resize limit + visual hint |
+| D-3 | **데모 외 사용자 업로드 흐름 일관화** — 자동 mdx03 로드와 사용자 직접 업로드의 시각 차별. "데모 모드" 표시 |
+| D-4 | **Step 20 status badge 의미 안내** — PASS / RENDERED_WITH_VISUAL_REGRESSION / PARTIAL_COVERAGE 의 사용자 친화 설명 |
+
+---
+
 ## 8. 문서 역할 분담

 | 문서 | 역할 | 갱신 빈도 |
@@ -155,6 +253,7 @@
 | [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) | 22 단계별 현재 상태의 single source of truth | 자주 |
 | [`PHASE-Z-CHANGE-LOG.md`](PHASE-Z-CHANGE-LOG.md) | 의사결정 변경 이력 (axis 단위, 시간 순) | 작업 단위 |
 | **`PHASE-Z-ROADMAP.md`** (본 문서) | **앞으로의 진행 순서 / 큰 axis / 우선순위** | **자주** |
+| [`PHASE-Q-AUDIT.md`](PHASE-Q-AUDIT.md) | Phase Q 모듈의 Keep / Migrate / Reference / Delete 결정 + Salvage Plan + ROADMAP §7-B 우선순위 재정렬의 input | audit 진행 중 (모듈별로 1 turn) |
 | `PROCESS_OVERVIEW.html` | 보고 / 피드백용 시각 프로토타입 | 보고 시점 |

 각 문서가 자기 역할만 하면 drift / 중복 / outdated 방지.