# ADSUM 애드섬 — 마케팅 성과 자동 집계 대시보드 (데모)

메타·구글·카카오모먼트·네이버 4개 광고 채널과 **스마트스토어 실매출**을 함께 집계하는
사내용 대시보드의 제안용 데모입니다.

> 원 공고 전사본: [기능명세(의뢰자 원본).txt](./기능명세(의뢰자%20원본).txt)
> (예산 700만 · 30일 · 지원자 61명 · 클라이언트 김포 · 사전 미팅 오프라인)

---

## 화면

| 파일 | 설명 |
|---|---|
| [index.html](index.html) | 대시보드 — KPI · **매출 기준 3분리** · 중복 진단 · 채널별 성과 · **목표 CPA 4단계 판정** · 베스트/워스트 · 자동 인사이트 |
| [admin.html](admin.html) | 관리자 — 연동 상태 · **배치/롤링 재수집** · 지표 매핑 · 목표 CPA 설정 · 권한 3역할 · **검토 항목 8건** |

로컬 실행: 정적 파일이므로 아무 웹서버로 열면 됩니다. 예) `python -m http.server 8088`
ASCII 별칭: [/adsum](../adsum/index.html) · [/adsum/admin](../adsum/admin/index.html)

---

## 체험 시나리오 — 이 순서로 보시면 3분입니다

### 대시보드

1. **[매출 기준]을 세 번 눌러 보세요** ★ 핵심
   `채널 합산 360% → 광고 기여 248% → 전체 실매출(MER) 303%`
   같은 광고비인데 ROAS가 셋 다 다릅니다. **광고 API 4개만 붙이면 첫 번째 숫자만 보입니다.**

2. **[중복 진단] 카드**
   채널 합산이 광고 기여 매출보다 **45% 많습니다.** 매체마다 기여 인정 기간이 달라
   한 건의 주문을 메타·구글·네이버가 각각 전액으로 신고하기 때문입니다.

3. **[수집 방식]을 `일 1회 수집`으로 바꿔 보세요** ★
   과거 60일 수치가 **전부 내려갑니다.** 채널 신고 매출이 34% 낮아집니다.
   전환은 지연 도착하는데 D+1에 한 번 긁고 끝내면 그 날짜가 성숙도 62%에서 굳기 때문입니다.
   (매출 기준이 `전체 실매출`이면 매출 KPI는 안 바뀝니다 — 주문 금액은 어트리뷰션과 무관하게 확정입니다.
   `채널 합산`으로 바꾸면 금액이 실제로 달라집니다.)

4. **[목표 CPA 트래킹] → [비교 보기]** ★
   요구사항대로 "CPA > 목표"만 비교하면 **전환 0건 소재 3건이 목록에서 통째로 사라집니다.**
   그 3건이 최근 7일에 이미 **269만원**을 썼습니다. 슬라이더로 판정 기준을 바꾸면 건수가 실시간으로 바뀝니다.

5. **소재 표 → [이미지] 버튼** ★
   ① 저장된 URL → **실제로 `403 URL signature expired`가 뜹니다**
   ② `image_hash` 재해결 → 정상 ③ 자체 스토리지 사본 → 정상

6. **[베스트/워스트]**
   기준(소진 30만원·전환 3건)을 안 걸면 1위가 되는 소재를 경고 카드로 함께 보여 줍니다.

7. **[자동 생성 인사이트] → [LLM 전송 페이로드 미리보기]**
   소재 디자인 요소 5축(형식·톤·인물·가격표기·주조색)을 실제 데이터로 계산한 뒤 문장으로 옮깁니다.
   외부 모델로 나가는 JSON에는 **금액이 한 건도 없습니다.**

### 관리자

8. **[연동 상태]** — 광고 4채널 + **커머스API 1채널**. 카카오는 `권한 심사 대기 D+10`이며
   CSV 수동 업로드로 임시 수집 중입니다. 대시보드의 카카오 행에도 **"수동 수집" 배지**가 붙어 있습니다.
9. **[배치] → [배치 실행]** — 로그가 실시간으로 쌓입니다. 재수집 창(3/7/14/30일)을 바꾸면
   **회수량과 API 호출 수의 트레이드오프**가 그래프로 바뀝니다.
10. **[목표 CPA]** — 값을 고치면 위 판정 집계가 즉시 다시 계산됩니다.
11. **[권한]** — 역할을 바꾸면 실제로 표시가 달라집니다.
12. **[검토 항목]** — 8건, 등급별 필터.

---

## ⚠️ 착수 전 확인이 필요한 항목

### 1. "매출"을 주는 API가 4개 중 어디에도 없습니다 ★

요구사항 2-2는 광고비·매출·ROAS를 함께 표기하라고 합니다. 그런데 광고 API가 주는 매출은
각 매체가 자체 추적한 전환매출입니다. 판매 채널이 스마트스토어인데
**스마트스토어는 외부 스크립트 설치가 자유롭지 않아 메타 픽셀을 직접 심을 수 없습니다.**
별도 솔루션을 경유하지 않으면 메타·카카오 신고 매출이 0이거나 심하게 과소로 나옵니다.

→ **네이버 커머스API(주문)를 5번째 소스로 추가**해 실매출을 단일 기준선으로 삼았습니다.

### 2. 채널 ROAS를 더하면 실매출을 넘습니다

메타 클릭 7일 / 구글 기본 30일 / 네이버 간접전환 7~20일 — 기여 인정 기간이 전부 다릅니다.
→ 합계 지표는 **MER(실매출 ÷ 광고비)** 을 기본값으로 두고, 채널별 표의 합계 행에
**"기간이 달라 합산 불가"** 를 명시했습니다.

### 3. 일별 1회 수집이면 어제 숫자가 영원히 틀립니다

구글은 전환 지연으로 과거 리포팅 값이 몇 주간 갱신되고, 메타는 2026년 3월 어트리뷰션 개편으로
**측정법 자체가 바뀌었습니다.** → **롤링 재수집 + 확정/잠정 배지**로 대응했습니다.

### 4. 카카오모먼트는 30일 안에 안 끝날 수 있습니다

비즈니스 앱 전환 → 본인인증 → 권한 심사가 선행되며 **심사 기간이 공식적으로 명시돼 있지 않습니다.**
→ 착수 첫날 신청 + 3채널 선오픈 + CSV 대체 동선.

그 밖에 — **이미지 URL 만료**(발견 4), **전환 0건 소재의 판정 누락**(발견 5),
**LLM 전송 시 사내 매출 유출**(발견 7), **소액 소재가 베스트 1위가 되는 문제**(발견 8)도 반영했습니다.

자세한 근거와 링크는 [분석/기획_설계.md](분석/기획_설계.md) 2장을 참고하세요.

---

## 기획·분석 문서

- **[분석/시나리오_사용자여정.md](분석/시나리오_사용자여정.md)** — 마케터·대표·대행사 세 인물의 흐름,
  자동화 전후 타임라인 비교, 기능별 존재 이유 전수 매핑, 7장에 미팅 확인 항목 9가지
- [분석/기획_설계.md](분석/기획_설계.md) — 니즈 분석, 리서치 8건(근거 링크), 레퍼런스 실측 2종,
  요구사항 커버리지, 제안 스택, 공수 68일 산정
- [지원서_위시캣.md](지원서_위시캣.md)

---

## 디자인 실측 명세

### ① 도메인 레퍼런스 (무엇을 만들까)

| 사이트 | 실측값 | 가져온 것 |
|---|---|---|
| **[Airbridge](https://airbridge.io)** | 배경 `#0a0a0c` · 카드 `#18181b` · 잉크 `#fafafa` · CTA `#155dfc` · 경계선 `rgba(255,255,255,.08)` · h1 72/72 ls −1.08px w600 · 버튼 r8 h48 fs15 w500 · 섹션 60px · 컨테이너 1280px · 트랜지션 `.15s cubic-bezier(0,0,.2,1)` | 다크 데이터 제품 계조 전체 + UI 트랜지션 속도 |
| **[Triple Whale](https://triplewhale.com)** | h1 76/83.6 ls −3.8px w300 · 버튼 r10 h64 · 섹션 80/100/130px | **MER 중심 IA** — [매출 기준] 세그먼트의 출처 |
| **[Funnel](https://funnel.io)** | h1 64/70.4 w600 · 버튼 r4 h52 · 카드 r12 · `#013f33` / `#f86c54` / `#1cb1f3` | 수집 신뢰를 전면에 두는 문법 → [확정/잠정] 배지 배치 |

### ② 디자인 레퍼런스 (수상작 · 작업 내용과 무관)

| 사이트 | 수상 | 가져온 것 |
|---|---|---|
| **[Dragonfly](https://dragonfly.xyz)** | **Awwwards SOTD 2026.07.22** (Studio Freight · 7.39) | 스페이서 스케일 4/8/12/16/24/32/48/64px · 이징 `cubic-bezier(.23,1,.32,1)` / `(.19,1,.22,1)` · 자간 −0.066em → **−0.02em으로 축소 이식** |
| **[TRIONN](https://trionn.com)** | **Awwwards SOTD + Developer Award 2026.07.27** | 리빌 이징 `.5s cubic-bezier(.16,1,.3,1)` · 다크 3계조 `#040508`/`#d8d8d8`/`#434343` |

> **수상작의 파격은 그대로 이식하지 않았습니다.** 두 사이트 모두 117~185px 디스플레이 타이포를 씁니다.
> 의뢰자가 *"화려한 디자인보다 정확한 데이터 집계와 직관적 정보 구조가 최우선"* 이라고 명시했으므로
> 모션 강도는 **대시보드 = 약(절제)** 기준을 따랐습니다.
> 넣은 것: 차트 그리기 · 카운트업 · 게이지 성장 · 리빌(stagger 40ms) · 토글 전환 · 토스트.
> 뺀 것: 히어로 패럴랙스 · 스크롤 하이재킹 · 대형 디스플레이 타이포 · 장식성 마퀴.

---

## 기술 구성 (데모)

- 순수 HTML/CSS/JS — 빌드 불필요, 외부 차트 라이브러리 없음
- **모든 수치가 실제로 계산됩니다.** 주문을 먼저 생성하고 각 주문에 광고 터치를 붙인 뒤,
  각 채널이 자기가 터치한 주문의 **전액**을 자기 전환매출로 신고하는 구조라
  중복 신고율이 데이터에서 자연스럽게 발생합니다 (하드코딩된 수치 없음)
- 전환 지연은 성숙도 곡선 `1 − e^(−age/2.36) × 0.5804` 으로 모델링
  (D+1 62% · D+3 84% · D+7 97%). 수집 방식 토글이 이 곡선의 적용 지점을 바꿉니다
- 차트는 canvas 직접 구현 (devicePixelRatio 대응, 백그라운드 탭에서도 최종 프레임 보장)
- CSV는 Blob + UTF-8 BOM (엑셀 한글 대응) · 17열 · 확정/잠정 열 포함
- 소재 썸네일은 외부 요청 없이 소재 속성으로 SVG를 그립니다
- 375px 가로 스크롤 0 · 표는 자체 컨테이너 내부 스크롤
- **브랜드·상품·소재·수치·계정은 전부 가상입니다.** 실제 광고 계정과 연결돼 있지 않습니다

실서비스 제안 스택: Next.js + Python 배치 + PostgreSQL(upsert 키 설계) + Claude API
([기획_설계.md](분석/기획_설계.md) 5장)