e7b1e17579
- 실적 설정 "광고 API 연동" 카드: 개발자 토큰·고객 ID·로그인 고객 ID(MCC)·서비스 계정 JSON·API 버전(기본 v26) → 쇼핑몰과 같은 마스터 키로 암호화(perf_ad_credentials, AAD perf:ad:…), 연결 테스트·상태(perf_ad_source_status) - ad_sources/(채널 하나 = 파일 하나) + google_ads.py: 서비스 계정 JWT 토큰(httpx) → REST searchStream GAQL, 비용(cost_micros 원 반올림, 부가세 별도)·ROAS(전환 가치÷비용)·노출·클릭·전환 항목, KRW 계정만, 오류 코드별 안내 - ad_sync.py: 기간 한 트랜잭션 저장(source='api', 안 준 날은 예전 API 값만 지움), 같은 채널 동시 실행 차단, 비밀값 가림 - 광고비 탭 [구글 광고 불러오기](보는 기간, 92일 넘으면 관리자) + 매출 자동 업데이트 회차에 함께, API 값 초록 숫자, 구글 머리글 = 일자별 항목 표 - 마이그레이션 007, 테스트 test_google_ads.py(가짜 구글 서버) — performance 테스트 83개 통과 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
71 lines
3.1 KiB
Python
71 lines
3.1 KiB
Python
"""광고 API 연동 — 공통 인터페이스.
|
|
|
|
광고 채널 코드(code)는 광고비 표 채널 코드(ad_spend.CHANNELS)와 같다 — 가져온 값은 그 채널 열로 들어간다.
|
|
인증정보는 쇼핑몰 인증정보와 같은 방식(설정 화면 입력 → 마스터 키로 암호화 → perf_ad_credentials)이고,
|
|
꺼낼 때는 ctx.credentials.get(key) 로만(서버 안에서만 복호화). 오류는 adapters.base 의 AdapterError 계열 —
|
|
status 가 곧 연결 상태 코드(설정 화면 표시)다. 오류 문구에 비밀값을 넣지 않는다.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass, field
|
|
from datetime import date
|
|
from decimal import Decimal
|
|
from typing import Any
|
|
|
|
from ..adapters.base import AdapterContext, CredentialField, NotConfigured
|
|
|
|
|
|
@dataclass
|
|
class AdDay:
|
|
"""광고 API 가 돌려준 하루치 — 금액은 원 단위 정수, ROAS 는 %(없으면 None), 나머지 항목은 화면 이름 그대로."""
|
|
|
|
day: date
|
|
amount: int
|
|
roas: Decimal | None = None
|
|
metrics: dict[str, Any] = field(default_factory=dict)
|
|
|
|
|
|
class AdSource:
|
|
code: str = "" # 광고비 채널 코드(google 등)
|
|
name: str = "" # 설정 화면 이름
|
|
docs_url: str = ""
|
|
note: str = "" # 설정 창 맨 위 안내
|
|
|
|
# 인증정보 서비스(credentials.CredentialService)가 쇼핑몰 어댑터와 같은 방식으로 다루게 맞춘 속성
|
|
@property
|
|
def uses_shared_integration(self) -> bool:
|
|
return False
|
|
|
|
def credential_fields(self) -> list[CredentialField]:
|
|
return []
|
|
|
|
def visible_fields(self) -> list[CredentialField]:
|
|
return [f for f in self.credential_fields() if not f.internal]
|
|
|
|
def validate_credentials(self, values: dict[str, str]) -> list[str]:
|
|
"""저장 전 검사. values 의 "__stored__" = 저장된 값이 있음(원문은 꺼내지 않음). 값 자체를 오류 문구에 넣지 않는다."""
|
|
errors: list[str] = []
|
|
for f in self.visible_fields():
|
|
v = (values.get(f.key) or "").strip()
|
|
if f.required and not v:
|
|
errors.append(f"{f.label} 을(를) 입력하세요.")
|
|
elif v and len(v) > 20000:
|
|
errors.append(f"{f.label} 값이 너무 깁니다.")
|
|
return errors
|
|
|
|
def is_configured(self, ctx: AdapterContext) -> bool:
|
|
return all(ctx.credentials.has(f.key) for f in self.visible_fields() if f.required)
|
|
|
|
def require_configured(self, ctx: AdapterContext) -> None:
|
|
if not self.is_configured(ctx):
|
|
raise NotConfigured("필수 인증정보가 입력되지 않았습니다. 실적 설정 → 광고 API 연동에서 입력하세요.")
|
|
|
|
def test_connection(self, ctx: AdapterContext) -> str:
|
|
"""성공하면 사람이 읽을 짧은 문구. 실패는 AdapterError."""
|
|
raise NotImplementedError
|
|
|
|
def fetch_days(self, ctx: AdapterContext, start: date, end: date) -> list[AdDay]:
|
|
"""기간(양 끝 포함)의 날짜별 광고비. 광고가 없던 날은 빠질 수 있다(저장 쪽이 그날의 예전 API 값을 지운다)."""
|
|
raise NotImplementedError
|