# task-849.1 완료 보고서: Meta 캐러셀 광고 이미지 자동 생성 PoC

## S (Situation)
Meta 캐러셀 광고에 사용할 이미지를 수동으로 제작하고 있어, 카피 변경 시마다 디자이너 의존이 필요한 상황이다. 상시 A 세트 5장 슬라이드의 자동 생성 PoC가 요구되었다.

## C (Complication)
2가지 접근법(B안: HTML 템플릿 + Playwright 캡처, C안: AI 배경 + HTML 오버레이)을 동시 테스트해야 하며, 금소법 준수를 위해 수치 정확성이 100% 보장되어야 한다. AI 배경에 한글 텍스트가 포함되면 안 되는 제약도 있다.

## Q (Question)
JSON 데이터 기반으로 5장의 1080x1080 PNG 캐러셀 이미지를 자동 생성하고, B안/C안 품질을 비교할 수 있는가?

## A (Answer)
Python CLI 스크립트로 5장 전체 자동 생성 완료. B안(슬라이드 2,3,4)은 HTML/CSS 인포그래픽, C안(슬라이드 1,5)은 gpt-image-1 배경 + HTML 오버레이로 구현. 실행 1회로 5장 생성, 비용 $0.022(AI 배경 2장). pyright 에러 0건, 수치 정확성 검증 통과.

---

## 생성/수정 파일 목록

| 파일 | 설명 |
|------|------|
| `tools/carousel-gen/generate_carousel.py` | 메인 CLI 스크립트 (191줄) |
| `tools/carousel-gen/data/set_a.json` | 상시A 카피 데이터 (5슬라이드) |
| `tools/carousel-gen/templates/infographic.html` | B안 HTML 템플릿 (407줄) |
| `tools/carousel-gen/templates/emotional.html` | C안 HTML 템플릿 (498줄) |
| `tools/carousel-gen/output/slide_1_고통 인식.png` | 슬라이드 1 (C안, 767KB) |
| `tools/carousel-gen/output/slide_2_문제 심화.png` | 슬라이드 2 (B안, 406KB) |
| `tools/carousel-gen/output/slide_3_신뢰 근거.png` | 슬라이드 3 (B안, 412KB) |
| `tools/carousel-gen/output/slide_4_차별화.png` | 슬라이드 4 (B안, 417KB) |
| `tools/carousel-gen/output/slide_5_CTA.png` | 슬라이드 5 (C안, 833KB) |
| `tools/carousel-gen/backgrounds/bg_slide_1.png` | AI 생성 배경 캐시 (슬라이드 1) |
| `tools/carousel-gen/backgrounds/bg_slide_5.png` | AI 생성 배경 캐시 (슬라이드 5) |

## 테스트 결과

### 검증 항목 (5/5 PASS)

1. **이미지 크기 검증**: 5장 모두 1080x1080 PNG — PASS
2. **한글 렌더링**: Noto Sans CJK KR 폰트로 깨짐 없이 렌더링 — PASS
3. **수치 정확성**: 원문 대조 검증 완료
   - 정착지원금 최대 1,000만원 ✓
   - 직전연봉 50% ✓
   - 해외여행 4회/년 ✓
   - 30개 지원 패키지 ✓
   - "잔여수수료" 사용 (잔존수당 미사용) ✓
4. **B안/C안 비교**: B안은 정보 전달에 적합(깔끔한 인포그래픽), C안은 감성적 임팩트가 강함(AI 배경 효과)
5. **Meta 광고 품질**: 텍스트 비율 20% 이하, 네이비+골드 컬러 시스템, 프로페셔널 디자인

### pyright 결과
- 0 errors, 0 warnings, 0 informations

### B안 vs C안 품질 비교

| 항목 | B안 (HTML 온리) | C안 (AI 배경 + HTML) |
|------|-----------------|---------------------|
| 적용 슬라이드 | 2, 3, 4 | 1, 5 |
| 평균 파일 크기 | 412 KB | 800 KB |
| 생성 시간 | <1초/장 | ~15초/장 (AI API 호출) |
| 생성 비용 | $0 | $0.011/장 |
| 시각적 특징 | 깔끔한 인포그래픽, 수치/리스트 강조 | 감성적 분위기, 프리미엄 느낌 |
| 적합 용도 | 정보 전달, 데이터 제시 | 후킹, 감성 호소, CTA |

## 발견 이슈 및 해결

### 자체 해결 (3건)

1. **`.env.keys` export 접두사 미처리** — `load_env_keys()`에서 `export ` 접두사 파싱 로직 추가
   - 수정: `generate_carousel.py:33` — `if line.startswith("export "): line = line[7:]`

2. **JS 함수명 불일치** — `generate_carousel.py`가 `window.renderSlide()` 호출했으나 템플릿의 함수명은 `render()`
   - 수정: `generate_carousel.py:97` — `render(window.SLIDE_DATA)` 직접 호출로 변경

3. **pyright 타입 에러 2건** — `result.data`와 `b64_json`의 Optional 타입 미처리
   - 수정: `generate_carousel.py:74-76` — null 체크 + RuntimeError 추가

## CLI 사용법

```bash
# 전체 생성 (AI 배경 포함)
python3 /home/jay/workspace/tools/carousel-gen/generate_carousel.py --set "상시A" --output ./output/

# AI 배경 스킵 (빠른 테스트)
python3 /home/jay/workspace/tools/carousel-gen/generate_carousel.py --set "상시A" --output ./output/ --skip-ai

# 배경 캐시가 있으면 자동 재사용 (API 재호출 없음)
```

## 비고
- AI 배경 이미지는 `backgrounds/` 디렉토리에 캐시되어, 재실행 시 API 재호출 없이 재사용
- 새 카피 세트 추가 시 `data/set_b.json` 등 JSON 파일 추가 + `set_map` 딕셔너리에 등록
- 현재 Google Fonts CDN에서 Noto Sans KR을 로드하므로 인터넷 연결 필요 (오프라인 시 시스템 폰트 fallback)