# Phase 2 계획 — 파이프라인 고도화 + 검색 + 시각화 자동화

## Phase 1 완료 현황 (2026-03-25)

| 항목 | 상태 | 수량 |
|------|------|------|
| 블록 라이브러리 | ✅ | 46개 (6 카테고리) |
| catalog.yaml | ✅ | 46개 등록, when/not_for/slots/height_cost |
| BLOCK_SLOTS | ✅ | 46개 동기화 |
| _apply_defaults | ✅ | 46개 동기화 |
| SVG premium | ✅ | venn-diagram 검증 (3개 고정) |
| Figma 에셋 | ✅ | 스크린샷 16장, 에셋 15개+ |
| 5단계 파이프라인 | ✅ | 코드 동작 (BF-4~10 수정 완료/진행중) |
| Kei API 연동 | ✅ | 1단계(실장) + 3단계(편집자) |
| catalog→renderer 매핑 | ✅ | mtime 캐시 (BF-10) |
| grid 역할 분리 | ✅ | BF-9 (코드가 grid, Sonnet은 blocks만) |

---

## Phase 2 목표

**파이프라인을 실제 사용 가능한 수준으로 고도화한다.**

Phase 1은 "기반 구축 + 블록 라이브러리"였고,
Phase 2는 "AI가 블록을 정확히 선택 + 고품질 결과물 생성"이다.

---

## Phase 2-A: FAISS 블록 검색 인덱스

### 목적
디자인 팀장(Step B)이 콘텐츠를 보고 46개 블록 중 적합한 것을 **검색**으로 찾는다.
현재는 catalog.yaml 전문이 프롬프트에 들어가는데, 46개가 넘으면 토큰 낭비 + 선택 정확도 저하.

### 구현
```
1. 각 블록의 (id + visual + when + not_for)를 임베딩
2. FAISS 인덱스 구축 (46개 벡터)
3. 콘텐츠 꼭지 분석 결과를 쿼리 → 상위 5~8개 후보 반환
4. 팀장 프롬프트에 후보 블록만 포함 (전체 46개 대신)
```

### 효과
- 프롬프트 토큰 절약 (46개 전문 → 5~8개만)
- 선택 정확도 향상 (관련 블록만 보여주니까)
- 블록 100개+까지 확장 가능

### 파일
- `src/block_search.py` (신규)
- `data/block_index.faiss` (생성)
- `src/design_director.py` (catalog 전문 → 검색 결과로 교체)

### 의존성
- sentence-transformers 또는 Anthropic embeddings
- FAISS (faiss-cpu)

---

## Phase 2-B: SVG N개 자동 배치

### 목적
현재 venn-diagram은 3개 원 고정. 콘텐츠에 따라 2~7개 원이 필요할 수 있음.
수학적 계산(cos/sin)으로 N개를 자동 배치한다.

### 구현
```
1. renderer.py에 SVG 좌표 계산 함수 추가
   - calc_circle_positions(n, center, radius) → [(cx, cy), ...]
   - 360/N 간격, 12시 방향부터 시계방향

2. venn-diagram.html 템플릿을 동적으로 변경
   - items[]에 사전 계산된 cx, cy가 포함
   - 원 크기도 N에 따라 자동 조정 (N=3: r=120, N=5: r=80, N=7: r=60)

3. Gemini 참고 디자인 흐름 (선택적)
   - SVG 초안 → Gemini에게 "이 구조로 고급 디자인" 요청
   - 생성 이미지의 색감/그라데이션을 참고하여 SVG tokens 업데이트
   - 최종은 항상 SVG (AI 이미지는 참고만)
```

### 파일
- `src/svg_calculator.py` (신규)
- `templates/blocks/visuals/venn-diagram.html` (동적 좌표 지원)
- `src/renderer.py` (SVG 계산 호출 추가)

### 검증 완료 사항
- 3/4/5개 수학적 계산: ✅ (Phase 1에서 테스트)
- SVG premium 디자인 (radialGradient+filter): ✅
- AI 이미지 방식 폐기: ✅ (텍스트 위치 불일치로 사용 불가)

---

## Phase 2-C: 2단계 Step A 고도화 (Opus + FAISS)

### 목적
현재 Step A는 규칙 4줄(프리셋 4개 중 선택)인데,
원래 의도는 **Opus가 FAISS로 적합한 구조/블록을 검색해서 배치와 크기까지 정하는 것**.

### 구현
```
현재 (Phase 1):
  Step A: 규칙 기반 프리셋 선택 (코드)
  Step B: Sonnet이 블록 매핑

Phase 2:
  Step A: Opus + FAISS로 구조/블록 검색 + 배치/크기 결정
  Step B: Sonnet이 Step A 결과를 grid에 매칭 + 글자수 가이드
```

### 세부
1. Opus가 콘텐츠를 보고 "이 콘텐츠에는 비교형+정의형+관계도가 적합" 판단
2. FAISS에서 각 유형에 맞는 블록 후보 검색
3. 후보 중 배치/크기를 결정 (좌 65% 비교표, 우 35% 정의 카드, 하단 관계도)
4. Step B(Sonnet)에게 이 배치 구조 + 후보 블록을 전달

### 의존성
- Phase 2-A (FAISS 인덱스) 완료 필요
- Kei API (Opus) 안정 동작

### 파일
- `src/design_director.py` (Step A 전면 재작성)
- `src/block_search.py` (Phase 2-A에서 생성)

---

## Phase 2-D: 5단계 재검토 강화

### 현재 문제
```
IMPROVEMENT 분석에서 발견된 문제:
  - HTML을 프롬프트에 실제 전달하지 않음 (블록 데이터 양만 전달)
  - shrink action이 no-op
  - rewrite action이 no-op
  - 조정 후 재편집이 정확하지 않음
```

### 구현
```
1. HTML 코드 요약을 프롬프트에 전달
   - 전체 HTML은 너무 크니까, 블록별 텍스트 길이 + 구조 요약

2. shrink action 구현
   - char_guide를 줄여서 재편집 유도

3. rewrite action 구현
   - 특정 블록의 텍스트를 완전히 재작성

4. 조정 횟수 제한
   - 무한 루프 방지: 최대 2회 재조정
```

### 파일
- `src/pipeline.py` (_review_balance, _apply_adjustments 개선)

---

## Phase 2-E: 누락 기능 구현

### E-1: Pillow 이미지 크기 읽기
```
콘텐츠에 이미지가 포함될 때:
  - Pillow로 원본 크기 확인
  - 가로/세로 비율에 따라 블록 선택 (image-full vs image-side-text)
  - 팀장에게 이미지 크기 정보 전달
```
- 파일: `src/design_director.py` (Step B에 이미지 정보 추가)

### E-2: `<details>/<summary>` 완성
```
현재 details-block.html은 있지만 파이프라인에서 활용 안 됨:
  - 실장이 detail_target으로 판단한 꼭지를 details-block으로 연결
  - 편집자가 summary + detail 두 버전 작성
  - 인쇄 시 자동 펼침 JavaScript
```
- 파일: `src/pipeline.py`, `templates/blocks/emphasis/details-block.html`

### E-3: 디자인 실무자 AI 조정
```
현재 4단계는 순수 코드(Jinja2)만.
CLAUDE.md에는 "텍스트에 맞게 폰트/여백/박스 조정"이라고 되어있음.
  - Sonnet이 렌더링된 HTML을 보고 CSS 미세 조정 제안
  - 또는 CSS 변수를 동적으로 조정하는 코드
```
- 파일: `src/renderer.py` 또는 `src/pipeline.py`
- 우선순위: 낮음 (다른 것이 더 급함)

---

## ~~Phase 2-F: 출력 확장~~ (design_agent 범위 밖)

**글벗에서 처리:**
- design_agent는 HTML 생성까지만 담당
- .astro 변환 → 글벗이 design_agent API 호출 후 HTML → .astro 래핑
- 글벗 연동 → 글벗 쪽에서 design_agent의 `/api/generate` 호출

---

## 작업 순서 (의존 관계)

```
Phase 2-A (FAISS) ─────────────────────┐
                                        ├→ Phase 2-C (Step A: Opus+FAISS)
Phase 2-B (SVG N개) ── 독립, 병렬 가능   │
                                        │
Phase 2-D (5단계 강화) ── 독립, 병렬 가능 │
                                        │
Phase 2-E (누락 기능) ── 독립, 병렬 가능  │
                                        │
Phase 2-F (출력 확장) ─── 글벗에서 처리 (design_agent 범위 밖)
```

### 추천 실행 순서
```
1순위: Phase 2-A (FAISS) — 블록 선택 정확도의 핵심
2순위: Phase 2-B (SVG N개) — 시각화 자동화
3순위: Phase 2-D (5단계 강화) — 결과물 품질
4순위: Phase 2-E (누락 기능) — 완성도
5순위: Phase 2-C (Step A: Opus) — Phase 2-A 완료 필요
※ Phase 2-F (출력 확장) — 글벗에서 처리, design_agent 범위 밖
```

---

## 기술 스택 추가

| 역할 | 도구 | Phase |
|------|------|-------|
| 블록 검색 | FAISS + sentence-transformers | 2-A |
| SVG 계산 | Python math (cos/sin) | 2-B |
| Step A | Opus via Kei API + FAISS | 2-C |
| 이미지 크기 | Pillow | 2-E |
| .astro 출력 | Jinja2 + StarlightPage 템플릿 | 2-F |

---

## 성공 기준

```
Phase 2 완료 시:
  ✅ 텍스트 원고 입력 → 85점 슬라이드 HTML 자동 생성
  ✅ 블록 선택이 콘텐츠에 정확히 매칭 (FAISS 검색)
  ✅ 관계도/다이어그램 N개 자동 배치 (SVG)
  ✅ 재검토 루프가 실질적으로 동작
  ✅ Starlight에서 바로 볼 수 있는 .astro 출력
```
