feat(performance): 네이버 광고 보고서 업로드(ROAS·보고서 항목) + 머리글 클릭 일자별 상세
- 네이버 업로드: 3열 기간·4열 총비용(광고비)·12열 구매완료 광고수익률(ROAS), 나머지 항목은 metrics(JSONB) - 네이버·구글·메타 칸 ROAS = 보고서 값(여러 날은 광고비 가중 평균), 쇼핑몰 매출로 계산하지 않음 - 네이버 머리글 클릭 → 지금 기간 일자별 보고서 표 + 합계(GET /api/ad-spend/naver/details) - performance_db 마이그레이션 006: perf_ad_spend.roas·metrics Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -7,6 +7,10 @@
|
||||
쿠팡(윙)·쿠팡(로켓) 업로드 양식(2026-10-13·14 사용자 제공 — 둘 다 같은 쿠팡 광고 보고서 CSV/엑셀):
|
||||
1행 머리글, 1열 = 날짜("2026년 10월 01일"), 19열 = 청구금액(+부가가치세) → 그날 광고비.
|
||||
날짜 줄 아래 캠페인 줄(1열 빈 칸)과 맨 위 "전체" 합계 줄은 건너뛴다.
|
||||
네이버 업로드 양식(2026-10-14 사용자 제공 — 네이버 광고 보고서 CSV/엑셀, 하루 한 줄):
|
||||
1행 머리글, 3열 = 기간(날짜 "2026.09.30."), 4열 = 총비용 → 그날 광고비, 12열 = 구매완료 광고수익률(%) → 그날 ROAS.
|
||||
나머지 열(노출수·클릭수·클릭률·전환수·구매완료 수·장바구니·총 전환매출액 …)은 머리글 이름 그대로 metrics 에 보관 —
|
||||
화면에서 네이버 머리글을 누르면 일자별 표(마이그레이션 006: perf_ad_spend.roas·metrics).
|
||||
|
||||
HTTP·DB 와 무관한 순수 함수(읽기·조립) — 라우터가 파일 바이트와 저장소를 넘긴다.
|
||||
"""
|
||||
@@ -17,7 +21,7 @@ import csv
|
||||
import io
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import date
|
||||
from decimal import ROUND_HALF_UP, Decimal
|
||||
from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
|
||||
from typing import Any, Callable, Mapping, Sequence
|
||||
|
||||
from . import calc
|
||||
@@ -42,9 +46,11 @@ CHANNELS: tuple[tuple[str, str], ...] = (
|
||||
CHANNEL_NAMES = dict(CHANNELS)
|
||||
CHANNEL_CODES = tuple(c for c, _ in CHANNELS)
|
||||
# ROAS(매출 ÷ 광고비 × 100) 의 매출 = 이 쇼핑몰 매출 실적 총매출. 쿠팡(윙)은 매출 쪽 코드가 coupang.
|
||||
# 구글·메타는 ROAS 를 계산하지 않는다 — ROAS 값을 따로 넣는다(2026-10-14 사용자 요청).
|
||||
NO_ROAS = frozenset({"google", "meta"})
|
||||
ROAS_SALES_CODE: dict[str, str] = {c: c for c in CHANNEL_CODES if c not in NO_ROAS}
|
||||
# 구글·메타·네이버는 ROAS 를 계산하지 않는다 — 광고 보고서의 ROAS 값을 따로 넣는다(perf_ad_spend.roas, 2026-10-14).
|
||||
# 여러 날(주·월·합계)의 ROAS = Σ(그날 ROAS × 그날 광고비) ÷ Σ광고비(ROAS 가 있는 날만) = 광고 매출 합 ÷ 광고비 합.
|
||||
FILE_ROAS = frozenset({"google", "meta", "naver"})
|
||||
NO_ROAS = FILE_ROAS # 예전 이름(계산 안 하는 채널)
|
||||
ROAS_SALES_CODE: dict[str, str] = {c: c for c in CHANNEL_CODES if c not in FILE_ROAS}
|
||||
ROAS_SALES_CODE["coupang_wing"] = "coupang"
|
||||
|
||||
|
||||
@@ -56,12 +62,32 @@ def roas(sales: int, spend: int) -> int | None:
|
||||
|
||||
|
||||
def roas_basis(code: str) -> str:
|
||||
"""머리글 말풍선 — ROAS 에 쓰는 매출(구글·메타는 빈 값 = 계산 안 함)."""
|
||||
"""머리글 말풍선 — ROAS 에 쓰는 매출(구글·메타·네이버는 빈 값 = 계산 안 함, 보고서 값)."""
|
||||
return "" if code not in ROAS_SALES_CODE else CHANNEL_NAMES.get(code, code)
|
||||
|
||||
|
||||
def channel_roas(code: str, sales_of: Callable[[str], int], spend: int) -> int | None:
|
||||
"""채널 칸의 ROAS — 구글·메타는 늘 None(계산 안 함)."""
|
||||
def file_roas(code: str, file_roas_map: Mapping[tuple[date, str], Any], spends: Mapping[tuple[date, str], int],
|
||||
s: date, e: date) -> int | None:
|
||||
"""보고서 ROAS 채널의 기간 ROAS — Σ(ROAS × 광고비) ÷ Σ광고비(ROAS 가 있고 광고비가 있는 날만)."""
|
||||
rev = Decimal(0)
|
||||
spend = 0
|
||||
for (d, c), r in file_roas_map.items():
|
||||
if c != code or not s <= d <= e or r is None:
|
||||
continue
|
||||
amt = int(spends.get((d, c)) or 0)
|
||||
if amt > 0:
|
||||
rev += Decimal(str(r)) * amt
|
||||
spend += amt
|
||||
if spend <= 0:
|
||||
return None
|
||||
return int((rev / spend).quantize(Decimal(1), rounding=ROUND_HALF_UP))
|
||||
|
||||
|
||||
def channel_roas(code: str, sales_of: Callable[[str], int], spend: int,
|
||||
file_of: Callable[[str], int | None] | None = None) -> int | None:
|
||||
"""채널 칸의 ROAS — 쇼핑몰 매출 ÷ 광고비. 구글·메타·네이버는 보고서 ROAS(file_of), 없으면 None."""
|
||||
if code in FILE_ROAS:
|
||||
return file_of(code) if file_of else None
|
||||
mcode = ROAS_SALES_CODE.get(code)
|
||||
return None if mcode is None else roas(sales_of(mcode), spend)
|
||||
|
||||
@@ -70,8 +96,14 @@ ROCKET_AMOUNT_COL = 18 # 19열 청구금액(+부가가치세)
|
||||
SKIP_LABELS = frozenset({"전체", "합계", "총계", "날짜"})
|
||||
|
||||
|
||||
NAVER_DATE_COL = 2 # 3열 기간(날짜)
|
||||
NAVER_AMOUNT_COL = 3 # 4열 총비용
|
||||
NAVER_ROAS_COL = 11 # 12열 구매완료 광고수익률(%)
|
||||
NAVER_SKIP_COLS = (0, 1, 2) # 광고 계정 이름·ID·기간은 metrics 에 넣지 않음
|
||||
|
||||
|
||||
class AdMigrationNeeded(Exception):
|
||||
"""광고비 표(마이그레이션 005: perf_ad_spend)가 아직 없음."""
|
||||
"""광고비 표(마이그레이션 005: perf_ad_spend) 또는 ROAS·상세 칸(006)이 아직 없음."""
|
||||
|
||||
|
||||
@dataclass
|
||||
@@ -79,6 +111,10 @@ class ParseResult:
|
||||
entries: list[tuple[date, int]] = field(default_factory=list) # (날짜, 금액)
|
||||
errors: list[str] = field(default_factory=list)
|
||||
skipped: int = 0 # 건너뛴 줄(캠페인 줄·합계 줄)
|
||||
# 보고서 ROAS·상세 항목(네이버) — 날짜 → ROAS(%) · {머리글: 값}. 비어 있으면 금액만 저장.
|
||||
roas: dict[date, Decimal] = field(default_factory=dict)
|
||||
metrics: dict[date, dict[str, Any]] = field(default_factory=dict)
|
||||
columns: list[str] = field(default_factory=list) # 상세 항목 머리글(파일 순서)
|
||||
|
||||
|
||||
# ════════════════════════════════════════════════════════════
|
||||
@@ -162,10 +198,133 @@ def parse_coupang_rocket(content: bytes, *, today: date, filename: str = "") ->
|
||||
return res
|
||||
|
||||
|
||||
def _number(value: Any) -> Decimal | None:
|
||||
"""숫자 칸 → Decimal(쉼표·%·원 허용). 빈 칸이면 None, 숫자가 아니면 ValueError."""
|
||||
if value is None or (isinstance(value, str) and not value.strip()):
|
||||
return None
|
||||
if isinstance(value, bool):
|
||||
raise ValueError
|
||||
text = str(value).replace(",", "").replace("%", "").replace("원", "").strip()
|
||||
try:
|
||||
num = Decimal(text)
|
||||
except InvalidOperation:
|
||||
raise ValueError from None
|
||||
if not num.is_finite():
|
||||
raise ValueError
|
||||
return num
|
||||
|
||||
|
||||
def _json_num(num: Decimal | None) -> Any:
|
||||
if num is None:
|
||||
return None
|
||||
return int(num) if num == num.to_integral_value() else float(round(num, 2))
|
||||
|
||||
|
||||
def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResult:
|
||||
"""네이버 광고 보고서 → (날짜, 총비용) + 그날 ROAS(12열) + 나머지 항목. 잘못된 줄이 있으면 errors."""
|
||||
rows = read_rows(content, filename)
|
||||
res = ParseResult()
|
||||
header: tuple[Any, ...] = ()
|
||||
seen: dict[date, int] = {}
|
||||
for r, row in enumerate(rows, start=1):
|
||||
raw_day = row[NAVER_DATE_COL] if len(row) > NAVER_DATE_COL else None
|
||||
text = str(raw_day or "").strip()
|
||||
if not text or text.replace(" ", "") in SKIP_LABELS:
|
||||
res.skipped += 1
|
||||
continue
|
||||
try:
|
||||
day = parse_date(raw_day)
|
||||
except ValueError:
|
||||
if not header: # 머리글(1행 "기간")
|
||||
header = tuple(str(h or "").strip() for h in row)
|
||||
res.columns = [h for i, h in enumerate(header) if i not in NAVER_SKIP_COLS and h]
|
||||
res.skipped += 1
|
||||
continue
|
||||
res.errors.append(f"{r}행 3열: 날짜를 읽을 수 없습니다({text[:30]}).")
|
||||
continue
|
||||
if day is None:
|
||||
res.skipped += 1
|
||||
continue
|
||||
try:
|
||||
amt = parse_amount(row[NAVER_AMOUNT_COL] if len(row) > NAVER_AMOUNT_COL else None)
|
||||
except ValueError:
|
||||
res.errors.append(f"{r}행 4열: 총비용이 숫자가 아닙니다.")
|
||||
continue
|
||||
try:
|
||||
ro = _number(row[NAVER_ROAS_COL] if len(row) > NAVER_ROAS_COL else None)
|
||||
except ValueError:
|
||||
res.errors.append(f"{r}행 12열: 광고수익률(ROAS)이 숫자가 아닙니다.")
|
||||
continue
|
||||
if amt is None:
|
||||
res.errors.append(f"{r}행 4열: {day.isoformat()} 총비용이 비어 있습니다.")
|
||||
elif abs(amt) > MAX_AMOUNT or (ro is not None and abs(ro) > Decimal("10000000")):
|
||||
res.errors.append(f"{r}행: 금액·ROAS 가 너무 큽니다.")
|
||||
elif day > today:
|
||||
res.errors.append(f"{r}행: 앞으로의 날짜({day.isoformat()})는 입력할 수 없습니다.")
|
||||
elif day in seen:
|
||||
res.errors.append(f"{r}행: {day.isoformat()} 이 {seen[day]}행과 겹칩니다.")
|
||||
else:
|
||||
seen[day] = r
|
||||
res.entries.append((day, amt))
|
||||
if ro is not None:
|
||||
res.roas[day] = ro
|
||||
m: dict[str, Any] = {}
|
||||
for i, v in enumerate(row):
|
||||
name = header[i] if i < len(header) else f"{i + 1}열"
|
||||
if i in NAVER_SKIP_COLS or not name:
|
||||
continue
|
||||
try:
|
||||
m[name] = _json_num(_number(v))
|
||||
except ValueError:
|
||||
m[name] = str(v)[:100]
|
||||
res.metrics[day] = m
|
||||
if len(res.entries) > MAX_DATA_ROWS:
|
||||
raise UploadError(f"한 번에 {MAX_DATA_ROWS:,}일까지 올릴 수 있습니다.")
|
||||
if len(res.errors) > MAX_ERRORS:
|
||||
break
|
||||
if not res.entries and not res.errors:
|
||||
raise UploadError("광고비 날짜 줄이 없습니다. 3열 기간(예: 2026.09.30.), 4열 총비용, 12열 광고수익률 양식인지 확인하세요.")
|
||||
return res
|
||||
|
||||
|
||||
# 업로드 양식이 정해진 채널 → 파일 읽기 함수(채널 순서 = 업로드 창 선택 순서). 쿠팡(윙)도 로켓과 같은 양식(2026-10-14).
|
||||
PARSERS: dict[str, Callable[..., ParseResult]] = {"coupang_wing": parse_coupang_rocket, "coupang_rocket": parse_coupang_rocket}
|
||||
PARSERS: dict[str, Callable[..., ParseResult]] = {
|
||||
"naver": parse_naver, "coupang_wing": parse_coupang_rocket, "coupang_rocket": parse_coupang_rocket}
|
||||
_COUPANG_HELP = "쿠팡 광고 보고서(CSV 또는 엑셀) — 1열 날짜, 19열 청구금액(+부가가치세)을 그날 광고비로 넣습니다."
|
||||
UPLOAD_HELP = {"coupang_wing": _COUPANG_HELP, "coupang_rocket": _COUPANG_HELP}
|
||||
UPLOAD_HELP = {
|
||||
"naver": "네이버 광고 보고서(CSV 또는 엑셀) — 3열 기간(날짜), 4열 총비용 = 그날 광고비, 12열 구매완료 광고수익률 = ROAS. "
|
||||
"나머지 항목은 네이버 머리글을 누르면 일자별로 볼 수 있습니다.",
|
||||
"coupang_wing": _COUPANG_HELP, "coupang_rocket": _COUPANG_HELP}
|
||||
# 머리글을 누르면 일자별 상세 표가 열리는 채널(보고서 항목을 보관하는 채널)
|
||||
DETAIL_CHANNELS = frozenset({"naver"})
|
||||
|
||||
|
||||
def detail_table(rows: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
"""일자별 상세(GET /api/ad-spend/{channel}/details) — rows: date·amount·roas·metrics(저장소).
|
||||
열 = 파일 머리글 순서(처음 나온 순), 합계 = 숫자 열 합 + 클릭률·ROAS 는 가중 평균."""
|
||||
cols: list[str] = []
|
||||
for r in rows:
|
||||
for k in (r.get("metrics") or {}):
|
||||
if k not in cols:
|
||||
cols.append(k)
|
||||
sums: dict[str, Decimal] = {}
|
||||
for r in rows:
|
||||
for k, v in (r.get("metrics") or {}).items():
|
||||
if isinstance(v, (int, float)) and not isinstance(v, bool):
|
||||
sums[k] = sums.get(k, Decimal(0)) + Decimal(str(v))
|
||||
total: dict[str, Any] = {k: _json_num(v) for k, v in sums.items()}
|
||||
for k in cols:
|
||||
if "클릭률" in k and sums.get("노출수"):
|
||||
total[k] = float(round(sums.get("클릭수", Decimal(0)) * 100 / sums["노출수"], 2))
|
||||
elif ("수익률" in k or "ROAS" in k.upper()):
|
||||
spend = sum(int(r.get("amount") or 0) for r in rows if r.get("roas") is not None and int(r.get("amount") or 0) > 0)
|
||||
rev = sum(Decimal(str(r["roas"])) * int(r.get("amount") or 0) for r in rows
|
||||
if r.get("roas") is not None and int(r.get("amount") or 0) > 0)
|
||||
total[k] = float(round(rev / spend, 2)) if spend else None
|
||||
out_rows = [{"date": r["date"], "amount": int(r.get("amount") or 0),
|
||||
"roas": float(r["roas"]) if r.get("roas") is not None else None,
|
||||
"values": r.get("metrics") or {}} for r in rows]
|
||||
return {"columns": cols, "rows": out_rows, "total": total}
|
||||
|
||||
|
||||
# ════════════════════════════════════════════════════════════
|
||||
@@ -194,6 +353,11 @@ def build_ad_dashboard(store: Any, *, kind: str, anchor: date, today: date,
|
||||
except AdMigrationNeeded:
|
||||
amounts, sources, migration_needed = {}, {}, True
|
||||
cells = {k: calc.Money(gross=int(v)) for k, v in amounts.items()}
|
||||
roas_reader = getattr(store, "ad_roas", None)
|
||||
try:
|
||||
roas_map = roas_reader(q_start, q_end) if roas_reader and not migration_needed else {}
|
||||
except AdMigrationNeeded:
|
||||
roas_map = {}
|
||||
|
||||
cur = calc.sum_range(cells, codes, period.start, period.end)
|
||||
prev = calc.sum_range(cells, codes, cmp_start, cmp_end)
|
||||
@@ -257,11 +421,13 @@ def build_ad_dashboard(store: Any, *, kind: str, anchor: date, today: date,
|
||||
for row in table:
|
||||
s = date.fromisoformat(row["from"]) if row.get("from") else period.start
|
||||
e = date.fromisoformat(row["to"]) if row.get("to") else period.end
|
||||
row["roas"] = {c: channel_roas(c, lambda m: sales_sum([m], s, e), row["cells"][c]["gross"]) for c in codes}
|
||||
row["roas"] = {c: channel_roas(c, lambda m: sales_sum([m], s, e), row["cells"][c]["gross"],
|
||||
lambda f: file_roas(f, roas_map, amounts, s, e)) for c in codes}
|
||||
row["roas_total"] = roas(sales_sum(total_codes, s, e), row["total"]["gross"]) if total_codes else None
|
||||
m_s, m_e = month_period.start, month_period.end
|
||||
for r in month["rows"]:
|
||||
r["roas"] = channel_roas(r["code"], lambda m: sales_sum([m], m_s, m_e), r["gross"])
|
||||
r["roas"] = channel_roas(r["code"], lambda m: sales_sum([m], m_s, m_e), r["gross"],
|
||||
lambda f: file_roas(f, roas_map, amounts, m_s, m_e))
|
||||
month["total"]["roas"] = roas(sales_sum(total_codes, m_s, m_e), month["total"]["gross"]) if total_codes else None
|
||||
year = calc.year_months(year_period.start.year, codes, cells, today=today)
|
||||
for i, r in enumerate(year["rows"], start=1):
|
||||
@@ -280,6 +446,7 @@ def build_ad_dashboard(store: Any, *, kind: str, anchor: date, today: date,
|
||||
"month": month,
|
||||
"year": year,
|
||||
"roas_basis": {c: roas_basis(c) for c in codes},
|
||||
"detail_channels": sorted(DETAIL_CHANNELS),
|
||||
"chart_daily": calc.daily_series(period, codes, cells),
|
||||
"chart_share": [{"code": c, "name": CHANNEL_NAMES[c], **share[c].as_dict()} for c in codes],
|
||||
# 업로드로 들어온 칸(표시용) — "날짜|채널"
|
||||
|
||||
Reference in New Issue
Block a user