# task-1670.1 완료 보고서

## S - Situation
블로그 이미지 생성 파이프라인(`image_router.py`, `satori_cli.js`, `server.py`)이 운영 중이며, 광고 배너 작업에서는 QC 게이트·디자인 일관성·한글 타이포 노하우가 축적되어 있다.

## C - Complication
블로그 이미지 생성 품질이 광고 배너 대비 현저히 낮다. 폰트 크기 위계 미적용, 색상 팔레트 불일관, 빈 이미지 미감지, 텍스트 영역 과다 등 문제가 블로그 이미지 파이프라인에 미반영 상태였다.

## Q - Question
광고 배너에서 학습된 QA 노하우(QC 게이트, 디자인 일관성, 한글 타이포)를 블로그 이미지 파이프라인에 체계적으로 적용하여 이미지 품질을 동일 수준으로 끌어올릴 수 있는가?

## A - Answer
5개 영역에 걸쳐 체계적으로 적용 완료. (1) YAML 가이드라인 문서화, (2) Claude CLI 프롬프트에 가이드라인 자동 주입, (3) 동일 글 내 공유 팔레트로 디자인 일관성 확보, (4) QC 게이트 함수로 파일크기/해상도/밝기/색상다양성/텍스트비율 5개 항목 자동 검증, (5) Satori 4종 레이아웃에 lineHeight 1.6·palette 파라미터 적용. pytest 96건 전체 통과(기존 89 + 신규 7), JS 문법 검증 통과.

## 구현 상세

### 1. 블로그 이미지 디자인 가이드라인 (신규)
- typography: 제목 28px+, 본문 16px+, word-break: keep-all, line-height 1.6
- layout: 텍스트 영역 40% 이하, 패딩 32px+, 간격 16px+
- color: WCAG AA 4.5:1, 중간톤 금지, 팔레트 일관성
- quality: 최소 800x400, 15KB 이상, 빈 이미지 감지

### 2. _prompt_to_html() 가이드라인 주입
- 기존 디자인 토큰 섹션 뒤에 "블로그 이미지 품질 가이드라인" 8개 항목 삽입
- Claude CLI가 HTML 생성 시 폰트 위계·텍스트 비율·WCAG AA·행간 준수

### 3. 동일 글 내 팔레트 일관성
- `_generate_blog_images()`에 `shared_palette` 딕셔너리 추가 (primary/secondary/accent)
- infographic 타입 프롬프트에 `[palette: primary=...,secondary=...,accent=...]` 힌트 자동 포함
- Satori CLI가 palette 태그를 파싱하여 레이아웃에 적용

### 4. QC 게이트 (`_validate_image_quality()`)
- 5개 검증 항목: 파일 크기(15KB+), 해상도(800x400+), 밝기 분포(20~245), 색상 다양성(50색+), 텍스트 영역 비율(40% 이하)
- PIL/numpy 미설치 시 graceful skip
- generate_image() 양쪽 성공 분기(1차/fallback)에서 자동 호출

### 5. Satori 레이아웃 개선
- 5개 함수(card/processFlow/comparisonTable/checklist/infographic)에 palette 파라미터 추가
- 모든 텍스트 요소에 lineHeight: 1.6 적용
- `parsePalette()`/`stripPalette()` 유틸리티로 프롬프트에서 palette 태그 파싱
- 기본값 fallback으로 기존 동작 완벽 호환

## 생성/수정 파일 목록
- `/home/jay/workspace/tools/ai-image-gen/blog-image-guidelines.yaml` (신규)
- `/home/jay/workspace/tools/ai-image-gen/image_router.py` (수정: 가이드라인 주입 + QC 게이트 함수 + QC 호출)
- `/home/jay/workspace/dashboard/server.py` (수정: shared_palette + palette_hint)
- `/home/jay/workspace/tools/ai-image-gen/satori-test/satori_cli.js` (수정: palette 파싱 + lineHeight + 5개 레이아웃 함수)
- `/home/jay/workspace/tools/ai-image-gen/test_image_router.py` (수정: TestValidateImageQuality 7개 테스트 추가)

## 테스트 결과
- pytest: 96 passed in 5.11s (기존 89 + 신규 7)
- Python 문법 검증: image_router.py ✓, server.py ✓
- JavaScript 문법 검증: satori_cli.js ✓ (node --check)

## 발견 이슈 및 해결

### 자체 해결 (3건)
1. **PNG 압축으로 인한 단색 이미지 크기 부족** — 테스트에서 np.zeros/np.full 대신 미세 노이즈 포함 이미지 사용으로 15KB 크기 검사 통과
   - 상세: test_image_router.py의 dark/bright/monotone 테스트에서 range 노이즈 패턴 적용
2. **Satori palette 태그가 infographicMatch 정규식과 간섭** — `stripPalette()`로 palette 태그를 먼저 제거 후 type 매칭
3. **QC 게이트 passed 판정 로직** — 모든 경고를 실패로 처리하지 않고, "최소" 또는 "빈 이미지" 키워드가 포함된 치명적 경고만 실패 판정

## 모델 사용 기록
- 불칸 / YAML 생성 + image_router.py 수정 + server.py 수정 / sonnet / -
- 이리스 / satori_cli.js 5개 레이아웃 함수 수정 / sonnet / -
- 아르고스 / QC 게이트 테스트 7개 작성 / sonnet / -

## 머지 판단
- **머지 필요**: No (worktree 미사용, 시스템 작업)

## 세션 통계
- 총 도구 호출: 35회

### 수정 파일 목록
- /home/jay/workspace/tools/ai-image-gen/satori-test/satori_cli.js: 21회 (Edit)
- /home/jay/workspace/tools/ai-image-gen/image_router.py: 4회 (Edit)
- bash_cmd: 3회 (Bash)
- /home/jay/workspace/dashboard/server.py: 2회 (Edit)
- /home/jay/workspace/tools/ai-image-gen/test_image_router.py: 2회 (Edit)
- /home/jay/workspace/memory/reports/task-1670.1.md: 1회 (Write)
- /home/jay/workspace/memory/tasks/task-1670.1.md: 1회 (dispatch)
- /home/jay/workspace/tools/ai-image-gen/blog-image-guidelines.yaml: 1회 (Write)

### 도구 사용 현황
- Edit: 29회
- Bash: 3회
- Write: 2회
- dispatch: 1회