---
name: 4-report
description: 분석 4단계의 ④ 정리. 분석 결과를 한 장 HTML 리포트로 내보낼 때 사용한다. "리포트 만들어줘", "report.html", "분석 결과 한 페이지로 정리해줘", "HTML 리포트로 출력", "의사결정 리포트", "매거진 톤 리포트", "popcorn-report 스타일로", 카톡·메일로 보낼 단일 파일 리포트가 필요한 상황. 데이터팝콘 표준 리포트 디자인(popcorn-report).
---

# ④ 정리 — Popcorn Report Design System

분석 4단계의 마지막. 결과를 **한 페이지 정적 HTML**로 만든다. 의사결정자용 요약, 정기 분석 보고, 트렌드 인사이트에 쓴다.

**산출물**: `findings.md` + `report_YYYYMMDD.html`
**앞 단계**: `datapopcorn-analysis:3-suspect` (EDA·함정 판정)

## 리포트 작성 전 — 함정 통과 확인 (필수)

1. `traps_check.md`에서 **걸림** 판정 항목을 찾는다.
2. 걸린 항목은 **한계·재현 카드에 그대로 옮긴다.**
3. **검증 안 된 수치는 헤드라인·KPI에 쓰지 않는다.**
4. 헤드라인이 `hypothesis.md`의 가설에 답하는지 확인한다. 가설과 무관한 발견은 섹션으로 내리고 헤드라인은 가설에 답한다.
5. `traps_check.md`가 없으면 → `datapopcorn-analysis:3-suspect`를 먼저 호출한다. **기록 없이 리포트를 만들지 않는다.**

---

## 출력 형태

- **단일 HTML 파일** — 차트는 이미지로 임베드, 외부 의존성은 웹폰트 하나뿐
- 인쇄 가능 (Cmd+P → PDF)
- 모바일 반응형 (900px / 640px breakpoint)
- 파일명: `report_YYYYMMDD.html`. 카톡·메일 전송용 단일 파일은 `report_YYYYMMDD_공유용.html`

---

## 만드는 순서

1. `assets/template.html`을 복사한다. **완성된 예시가 들어있다** — 구조를 새로 쓰지 않는다.
2. 아래 [채울 슬롯](#채울-슬롯) 표대로 예시 값을 실제 값으로 교체한다.
3. 반복 블록(KPI 4개, 섹션 N개, 리스트 항목)은 **HTML 블록을 실제 개수만큼 복제**해서 채운다.
4. 차트 PNG를 같은 폴더에 두고 `<img src="...">` 경로를 맞춘다.
5. 단일 파일이 필요하면 `scripts/inline_assets.py`로 이미지를 인라인한다.

```bash
python scripts/inline_assets.py report_20260811.html report_20260811_공유용.html
```

### 채울 슬롯

| 슬롯 | 내용 | 규칙 |
|---|---|---|
| `TOPIC_LABEL` | eyebrow 라벨 | 영문 대문자, 예: `SEOUL AIR QUALITY 2024` |
| `HEADLINE` | 메인 헤드라인 | **결론 직설형** 또는 의문형. "○○ 분석" 금지 |
| `LEAD_PARAGRAPH` | 리드 문단 | 2~3문장. 무엇을 봤고 무엇이 나왔나 |
| `HERO_INSIGHT` | 히어로 인사이트 박스 | 핵심 수치 1개 + 한 문장 |
| Snapshot 3~5개 | 라벨 + 값 | 기간·데이터 소스·표본 크기·조회일 |
| KPI 4개 | label / value / note | **정확히 4개.** value는 숫자, note는 비교 기준 |
| 섹션 2개 이상 | 라벨 / 제목 / 부제 / 차트 / 인사이트 | 섹션당 인사이트 **최대 1개** |
| 근거 | 수치·출처 리스트 | 데이터가 직접 가리키는 것만 |
| 액션 | 체크박스 리스트 | ✅ = 데이터 근거 있음, ⚠️ = 일반 권고(검증 필요) |
| 한계·재현 | 걸린 함정 + 재현 방법 | 🔁 로 재현 레시피 표시 |

**출력 HTML에 `{{`나 `{{#each}}` 같은 템플릿 문법이 남아 있으면 실패다.** 반복 블록은 복제해서 값을 채운다.

---

## 디자인 시스템 (CSS 변수 — 그대로 사용)

```css
:root {
  --bg: #f7f6f1;          /* 베이지 배경 */
  --card: #ffffff;        /* 카드 흰색 */
  --text: #1a1a1a;        /* 본문 다크 */
  --muted: #6b6b6b;       /* 보조 텍스트 */
  --accent: #e53935;      /* 강조 빨강 */
  --teal: #2e7d7a;        /* 보조 청록 */
  --line: #d7d1c7;        /* 구분선 */
  --shadow: 0 24px 80px rgba(0,0,0,0.08);
}
```

### 6:3:1 컬러 비율
- **중성색 60%**: 베이지 배경 + 화이트 카드 + 회색 텍스트
- **메인 30%**: 검정 본문 + 검정 인사이트 박스
- **포인트 10%**: 빨강 강조(`#e53935`), 청록 보조(`#2e7d7a`)

### 폰트 — Pretendard (⚠️ Google Fonts에 없다)

Pretendard는 Google Fonts에서 제공하지 않는다. **jsDelivr CDN**을 쓴다.

```html
<link rel="stylesheet"
      href="https://cdn.jsdelivr.net/gh/orioncactus/pretendard@v1.3.9/dist/web/variable/pretendardvariable-dynamic-subset.css">
```
```css
font-family: "Pretendard Variable", Pretendard, -apple-system, BlinkMacSystemFont,
             system-ui, "Apple SD Gothic Neo", "Noto Sans KR", "Malgun Gothic", sans-serif;
```

- 메인 헤드라인: `clamp(34px, 5vw, 62px)` + `font-weight: 800` + `letter-spacing: -0.04em`
- 섹션 라벨(eyebrow): 12~13px + `letter-spacing: 0.18em` + `text-transform: uppercase`
- 오프라인에서 봐야 하면 폰트를 base64로 임베드하거나 시스템 폰트 fallback을 받아들인다

### 라운드 / 그림자 / 배경
- 카드 라운드 **28px**, 그림자 `0 24px 80px rgba(0,0,0,0.08)`
- 배경 (시그니처 패턴):
```css
background:
  radial-gradient(circle at top left, rgba(229,57,53,0.08), transparent 22%),
  linear-gradient(180deg, #faf8f3 0%, var(--bg) 100%);
```

---

## 레이아웃 골격 (필수 5개 섹션)

```
┌─────────────────────────────────────────────────┐
│ [Hero] eyebrow + 큰 헤드라인 + 리드 + 인사이트   │ + Snapshot 사이드
├─────────────────────────────────────────────────┤
│ [KPIs] 4개 카드 grid (label / value / note)      │
├─────────────────────────────────────────────────┤
│ [Section 01 · TREND OVERVIEW]                    │
│   section-header + 차트 + 인사이트 1개           │
├─────────────────────────────────────────────────┤
│ [Section 02 · BREAKDOWN]                         │
│   section-header + 차트 + 인사이트 1개           │
├─────────────────────────────────────────────────┤
│ [Action Cards] 03 · ACTIONABLE INSIGHT           │
│   근거 / 액션 / 한계·재현                        │
└─────────────────────────────────────────────────┘
```

### 액션 카드 3분할 (이름 고정)

| 카드 | 제목 | 들어갈 것 |
|---|---|---|
| 1 | **근거** | 데이터가 직접 가리키는 수치 + 출처 |
| 2 | **액션** | ☐ 체크박스. `✅` 데이터 근거 있음 / `⚠️` 일반 권고(검증 필요) 구분 표시. "누가 / 언제 / 무엇을" |
| 3 | **한계·재현** | 걸린 함정 + 다음 해석 방향 + `🔁` 재현 레시피(어떤 스크립트를 어떤 인자로) |

카드 이름을 바꾸지 않는다. `3-suspect`의 판정 결과가 3번 카드로 그대로 들어온다.

### 섹션 라벨 작명
- **영문 + 숫자**: `01 · TREND OVERVIEW`, `02 · CATEGORY BREAKDOWN`, `03 · ACTIONABLE INSIGHT`
- 점은 `·` (middle dot, U+00B7). 하이픈 X
- 모두 대문자, letter-spacing 넓게

### 헤드라인 톤
- **결론 직설형**: "서울 25개 구, PM2.5 격차는 14.7%"
- 의문형도 OK — 단, 본문에서 답을 줄 것: "비 오는 날 따릉이는 정말 안 타나?"
- ❌ "○○ 분석 결과", "○○ 데이터 리포트"
- ❌ **누구나 아는 사실은 헤드라인이 아니다.** "여름에 아이스커피가 더 팔린다" 같은 자명한 문장 금지

### 인사이트 박스
```html
<div class="insight">종로구는 평균보다 8% 높다.</div>
```
- 검정 배경 + 흰 글씨, **섹션당 최대 1개** (남용하면 강조가 죽는다)
- 핵심 수치 1개 + 한 문장 결론

---

## 차트 통합

- **PNG 권장** — `<img>`로 임베드, 단일 파일 portable
- 해상도 1600px 이상 (Retina), 배경 `#fff`

```python
import matplotlib.pyplot as plt
import seaborn as sns
from matplotlib import font_manager, rcParams

# 1. 폰트 — set_theme() 먼저, 그 다음 폰트 재지정
sns.set_theme(style="white", context="notebook")
installed = {f.name for f in font_manager.fontManager.ttflist}
for name in ("Pretendard", "Pretendard Variable", "AppleGothic", "Malgun Gothic", "NanumGothic"):
    if name in installed:
        rcParams["font.family"] = name
        break
rcParams["axes.unicode_minus"] = False   # 음수 기호 깨짐 방지

# 2. 컬러 팔레트 — CSS 변수와 매칭
COLORS = {"accent": "#e53935", "teal": "#2e7d7a", "muted": "#6b6b6b", "line": "#d7d1c7"}

# 3. 저장
fig.savefig("chart_01.png", dpi=200, bbox_inches="tight",
            facecolor="white", edgecolor="none")
```

로컬에 한글 폰트가 하나도 없으면 라벨이 □□□로 깨진다. 위 루프가 아무것도 못 찾으면 사용자에게 알리고 영문 라벨로 대체한다.

### 차트 종류·라벨
- 시계열 → 라인 (`COLORS["accent"]`) · 카테고리 비교 → 수평 막대 · 분포 → 박스플롯 · 관계 → 산점도 + 회귀선
- **수치를 차트에 직접 노출**, 격자선·축 라벨 최소화
- 단위는 축 제목에 포함 (`(㎍/㎥)`), 범례는 외부 또는 생략

---

## 강제 규칙

1. **CSS 변수 그대로** — 컬러를 임의로 바꾸지 않는다
2. **템플릿 문법 잔존 금지** — 출력 HTML에 `{{`가 남으면 실패. 반복 블록은 복제해 채운다
3. **섹션당 인사이트 박스 1개**
4. **KPI는 정확히 4개**
5. **액션 카드는 항상 3개, 이름 고정** — 근거 / 액션 / 한계·재현
6. **헤드라인은 결론·의문형** — 단순 제목·자명한 문장 금지
7. **섹션 라벨 `01 ·` 번호 + middle dot**
8. **검증 안 된 수치는 헤드라인·KPI에 금지** — 한계 카드로 보낸다
9. **Pretendard는 jsDelivr CDN** — Google Fonts에서 import 금지(존재하지 않음)

---

## 흔한 실패

| 증상 | 원인 | 고치는 법 |
|---|---|---|
| 폰트가 시스템 기본으로 나옴 | Google Fonts에서 Pretendard import | jsDelivr CDN 링크로 교체 |
| HTML에 `{{#each ...}}` 노출 | 템플릿을 그대로 저장 | 블록을 실제 개수만큼 복제해 값 채움 |
| 차트 한글이 □□□ | matplotlib 폰트 미설정 | `rcParams["font.family"]` 감지 루프 |
| 카톡에서 차트 안 보임 | 상대경로 PNG 참조 | `scripts/inline_assets.py`로 인라인 |
| 인사이트 박스 도배 | 섹션당 여러 개 | 섹션당 1개로 줄임 |

---

## 참고 파일

- `assets/template.html` — 값이 채워진 완성 예시. 복사해서 값만 교체
- `scripts/inline_assets.py` — 로컬 PNG·JS를 인라인해 단일 파일로 변환

## 메타

- **버전**: v3 (2026-08-11) — `popcorn-report` → `4-report`로 개명(4단계 = 스킬 1:1 정렬). v2에서 Pretendard CDN 수정(Google Fonts에 없음), Handlebars 템플릿을 완성 예시 HTML로 교체, 액션 카드 3분할 통일
- **연관 스킬**: 앞 단계 `3-suspect` · 전체 오케스트레이터 `data-analysis-pipeline`
- **유지보수**: 데이터팝콘 표준 리포트 톤. 컬러·레이아웃 변경 시 사내 합의 필요
