diff --git a/app/modules/performance/CLAUDE.md b/app/modules/performance/CLAUDE.md index 3e78db4..1e221fa 100644 --- a/app/modules/performance/CLAUDE.md +++ b/app/modules/performance/CLAUDE.md @@ -59,6 +59,7 @@ - 날짜 칸 직접 입력 + 쿠팡(윙)·쿠팡(로켓)·네이버 광고 보고서 업로드. - 쿠팡: 1열 날짜·19열 청구금액(+부가가치세). - 네이버: 3열 기간·4열 총비용·12열 ROAS(구매완료 광고수익률(%)), 머리글 클릭 = 일자별 보고서 항목. + 총비용·광고수익률은 **머리글 이름으로 찾음**(열 구성 바뀐 보고서 — 고정 12열이 비어 ROAS 누락됐던 문제, 2026-10-20). 광고수익률 칸이 없거나 비면 구매완료 전환매출액 ÷ 총비용. 저장된 `roas` 가 빈 예전 행은 `db.ad_roas` 가 metrics 에서 다시 구함(`ad_spend.roas_from_metrics`). - 일자별 보고서 창: ROAS 열은 **광고비 열 바로 오른쪽**, 네이버 "구매완료 광고수익률(%)" 머리글은 "ROAS(%)"로 표기(`ad_spend._roas_next_to_spend` → `labels`, 저장 키는 파일 머리글 그대로 — 예전 업로드도 그대로 적용). - 매출 대비 광고비 KPI. - 광고 API 연동(마이그레이션 007 `perf_ad_credentials`·`perf_ad_source_status`) — 실적 설정 **광고 API 연동** 카드, 쇼핑몰과 같은 마스터 키로 암호화(AAD `perf:ad:…`), `ad_sources/`(채널 하나 = 파일 하나) + `ad_sync.py`, 매출 자동 업데이트 회차에 함께. 결과는 `perf_ad_spend` `source='api'`(초록 숫자, API 가 안 준 날은 예전 API 값만 지움). diff --git a/app/modules/performance/ad_spend.py b/app/modules/performance/ad_spend.py index bf49839..b62bb01 100644 --- a/app/modules/performance/ad_spend.py +++ b/app/modules/performance/ad_spend.py @@ -228,11 +228,50 @@ def _json_num(num: Decimal | None) -> Any: return int(num) if num == num.to_integral_value() else float(round(num, 2)) +def _norm(name: Any) -> str: + return str(name or "").replace(" ", "") + + +# 네이버 보고서 ROAS = "구매완료 광고수익률(%)"(2026-10-20 사용자 확인). 그 칸이 없거나 비면 +# 구매완료 전환매출액 ÷ 총비용 × 100 으로 계산한다(같은 정의 — 총 전환매출액은 정의가 달라 쓰지 않음). +NAVER_ROAS_KEY = "구매완료광고수익률" +NAVER_REVENUE_KEY = "구매완료전환매출액" + + +def roas_from_metrics(metrics: Mapping[str, Any] | None, amount: int | None) -> Decimal | None: + """보고서 항목(머리글 → 값)에서 ROAS(%) — 광고수익률 칸, 없으면 전환매출액 ÷ 광고비. 못 구하면 None. + 저장된 roas 가 빈 예전 업로드(열 위치가 달라 12열이 비었던 파일)도 이것으로 다시 구한다(db.ad_roas).""" + if not isinstance(metrics, Mapping): + return None + for key in (NAVER_ROAS_KEY, NAVER_REVENUE_KEY): + for k, v in metrics.items(): + if key not in _norm(k) or isinstance(v, bool) or not isinstance(v, (int, float, Decimal)): + continue + if key == NAVER_ROAS_KEY: + return Decimal(str(v)) + if amount and int(amount) > 0: + return (Decimal(str(v)) * 100 / int(amount)).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) + return None + + +def _naver_cols(header: tuple[str, ...]) -> tuple[int, int | None]: + """머리글로 (총비용 열, ROAS 열) 찾기 — 네이버 보고서는 열 구성을 바꿀 수 있어 고정 위치(4열·12열)가 어긋난다. + 머리글에 없으면 예전 고정 위치. ROAS 는 머리글은 있는데 광고수익률 칸이 없으면 None(전환매출액으로 계산).""" + names = [_norm(h) for h in header] + amount = next((i for i, n in enumerate(names) if n.startswith("총비용")), NAVER_AMOUNT_COL) + roas_col = next((i for i, n in enumerate(names) if NAVER_ROAS_KEY in n), None) + if roas_col is None and not any(names): + roas_col = NAVER_ROAS_COL + return amount, roas_col + + def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResult: - """네이버 광고 보고서 → (날짜, 총비용) + 그날 ROAS(12열) + 나머지 항목. 잘못된 줄이 있으면 errors.""" + """네이버 광고 보고서 → (날짜, 총비용) + 그날 ROAS(구매완료 광고수익률) + 나머지 항목. 잘못된 줄이 있으면 errors. + 총비용·ROAS 열은 머리글 이름으로 찾는다(없으면 4열·12열).""" rows = read_rows(content, filename) res = ParseResult() header: tuple[Any, ...] = () + amount_col, roas_col = NAVER_AMOUNT_COL, NAVER_ROAS_COL 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 @@ -245,6 +284,7 @@ def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResu except ValueError: if not header: # 머리글(1행 "기간") header = tuple(str(h or "").strip() for h in row) + amount_col, roas_col = _naver_cols(header) res.columns = [h for i, h in enumerate(header) if i not in NAVER_SKIP_COLS and h] res.skipped += 1 continue @@ -254,17 +294,17 @@ def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResu res.skipped += 1 continue try: - amt = parse_amount(row[NAVER_AMOUNT_COL] if len(row) > NAVER_AMOUNT_COL else None) + amt = parse_amount(row[amount_col] if len(row) > amount_col else None) except ValueError: - res.errors.append(f"{r}행 4열: 총비용이 숫자가 아닙니다.") + res.errors.append(f"{r}행 {amount_col + 1}열: 총비용이 숫자가 아닙니다.") continue try: - ro = _number(row[NAVER_ROAS_COL] if len(row) > NAVER_ROAS_COL else None) + ro = _number(row[roas_col] if roas_col is not None and len(row) > roas_col else None) except ValueError: - res.errors.append(f"{r}행 12열: 광고수익률(ROAS)이 숫자가 아닙니다.") + res.errors.append(f"{r}행 {(roas_col or 0) + 1}열: 광고수익률(ROAS)이 숫자가 아닙니다.") continue if amt is None: - res.errors.append(f"{r}행 4열: {day.isoformat()} 총비용이 비어 있습니다.") + res.errors.append(f"{r}행 {amount_col + 1}열: {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: @@ -274,8 +314,6 @@ def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResu 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}열" @@ -286,6 +324,10 @@ def parse_naver(content: bytes, *, today: date, filename: str = "") -> ParseResu except ValueError: m[name] = str(v)[:100] res.metrics[day] = m + if ro is None: + ro = roas_from_metrics(m, amt) # 광고수익률 칸이 없거나 빈 파일 — 전환매출액 ÷ 총비용 + if ro is not None: + res.roas[day] = ro if len(res.entries) > MAX_DATA_ROWS: raise UploadError(f"한 번에 {MAX_DATA_ROWS:,}일까지 올릴 수 있습니다.") if len(res.errors) > MAX_ERRORS: diff --git a/app/modules/performance/db.py b/app/modules/performance/db.py index 57efedc..0589c4a 100644 --- a/app/modules/performance/db.py +++ b/app/modules/performance/db.py @@ -440,16 +440,25 @@ class PerformanceDBStore: return len(entries) def ad_roas(self, start: date, end: date) -> dict[tuple[date, str], Decimal]: - """(날짜, 채널) → 보고서 ROAS(%) — 값이 있는 칸만. 005·006 미적용이면 빈 값(화면은 ROAS 없이).""" + """(날짜, 채널) → 보고서 ROAS(%) — 값이 있는 칸만. 005·006 미적용이면 빈 값(화면은 ROAS 없이). + roas 가 비었어도 보관된 보고서 항목(metrics)에 광고수익률·전환매출액이 있으면 그것으로 구한다 + (네이버 파일 열 위치가 달라 고정 12열이 비어 저장됐던 예전 업로드 — 다시 올리지 않아도 보이게, 2026-10-20).""" + from .ad_spend import roas_from_metrics # noqa: WPS433 + try: with self._pool.connection() as conn: rows = conn.execute( - "SELECT spend_date, channel_code, roas FROM perf_ad_spend " - "WHERE spend_date BETWEEN %s AND %s AND roas IS NOT NULL", (start, end), + "SELECT spend_date, channel_code, amount, roas, metrics FROM perf_ad_spend " + "WHERE spend_date BETWEEN %s AND %s AND (roas IS NOT NULL OR metrics IS NOT NULL)", (start, end), ).fetchall() except (pg_errors.UndefinedTable, pg_errors.UndefinedColumn): return {} - return {(r["spend_date"], r["channel_code"]): r["roas"] for r in rows} + out: dict[tuple[date, str], Decimal] = {} + for r in rows: + value = r["roas"] if r["roas"] is not None else roas_from_metrics(r["metrics"], r["amount"]) + if value is not None: + out[(r["spend_date"], r["channel_code"])] = value + return out def ad_details(self, code: str, start: date, end: date) -> list[dict[str, Any]]: """한 채널의 일자별 광고비·ROAS·보고서 항목(날짜 순). 006 미적용이면 AdMigrationNeeded.""" diff --git a/app/modules/performance/tests/test_ad_spend.py b/app/modules/performance/tests/test_ad_spend.py index b8353cc..4af00f2 100644 --- a/app/modules/performance/tests/test_ad_spend.py +++ b/app/modules/performance/tests/test_ad_spend.py @@ -240,6 +240,32 @@ def test_naver_report_reads_date_cost_roas_and_metrics(): assert "겹칩니다" in errs and "총비용이 숫자가 아닙니다" in errs and "ROAS" in errs and "앞으로의 날짜" in errs +def test_naver_report_finds_columns_by_header(): + """열 구성을 바꾼 보고서 — 총비용·광고수익률이 4열·12열이 아니어도 머리글로 찾는다(2026-10-20: 12열이 비어 ROAS 누락).""" + csv_text = ("광고 계정 이름,광고 계정 ID,기간,노출수,클릭수,총비용,구매완료 광고수익률(%),구매완료 전환매출액\n" + "0_미라네주방,38461,2026.09.23.,30043,461,300672,67.58,203194\n") + res = ads.parse_naver(csv_text.encode("utf-8"), today=TODAY, filename="n.csv") + assert not res.errors, res.errors + assert res.entries == [(date(2026, 9, 23), 300672)] and str(res.roas[date(2026, 9, 23)]) == "67.58" + + +def test_naver_report_without_roas_column_computes_from_purchase_revenue(): + csv_text = ("광고 계정 이름,광고 계정 ID,기간,총비용,노출수,구매완료 전환매출액,총 전환매출액\n" + "0_미라네주방,38461,2026.09.22.,299817,31061,596016,15040200\n" + "0_미라네주방,38461,2026.09.24.,0,0,0,6331500\n") + res = ads.parse_naver(csv_text.encode("utf-8"), today=TODAY, filename="n.csv") + assert not res.errors, res.errors + assert str(res.roas[date(2026, 9, 22)]) == "198.79" # 596,016 ÷ 299,817 × 100 (총 전환매출액은 안 씀) + assert date(2026, 9, 24) not in res.roas # 광고비 0 — 계산 안 함 + + +def test_roas_from_metrics_for_stored_rows(): + assert ads.roas_from_metrics({"구매완료 광고수익률(%)": 501.11}, 299199) == Decimal("501.11") + assert ads.roas_from_metrics({"구매완료 광고수익률(%)": None, "구매완료 전환매출액": 600000}, 300000) == Decimal("200.00") + assert ads.roas_from_metrics({"총 전환매출액": 600000}, 300000) is None + assert ads.roas_from_metrics(None, 1) is None and ads.roas_from_metrics({"구매완료 전환매출액": 5}, 0) is None + + def test_naver_roas_from_report_weighted(): """네이버 칸 ROAS = 보고서 값(계산 안 함), 여러 날 = Σ(ROAS×광고비)÷Σ광고비, 광고비 0 인 날은 빼고.""" class S(_Store):