Merge branch 'feat/google-ads-vat'

This commit is contained in:
2026-10-15 15:47:58 +09:00
6 changed files with 22 additions and 14 deletions
+1 -1
View File
File diff suppressed because one or more lines are too long
@@ -14,8 +14,9 @@
SELECT customer.currency_code, segments.date, metrics.cost_micros, metrics.impressions, metrics.clicks,
metrics.conversions, metrics.conversions_value FROM customer WHERE segments.date BETWEEN 'from' AND 'to'
- 날짜는 광고 계정 시간대 기준(한국 계정이면 KST). 광고가 없던 날은 행이 없을 수 있다.
- 금액 = cost_micros ÷ 1,000,000 을 원 단위로 반올림(구글 광고 비용은 부가세 별도). 계정 통화가 KRW 가 아니면 저장하지 않는다.
- ROAS(%) = 전환 가치 ÷ 비용 × 100(구글 광고 "전환 가치/비용"과 같은 값), 비용이 0 이면 없음.
- 금액(광고비) = **부가세 포함**(2026-10-15 사용자 요청) = cost_micros ÷ 1,000,000 × 1.1 을 원 단위로 반올림
(구글 광고 비용은 부가세 별도 — 쿠팡 광고비처럼 부가세 포함으로 맞춘다). 계정 통화가 KRW 가 아니면 저장하지 않는다.
- ROAS(%) = 전환 가치 ÷ 비용(부가세 별도) × 100 — 구글 광고 화면 "전환 가치/비용"과 같은 값 그대로, 비용이 0 이면 없음.
- 나머지 항목(노출수·클릭수·클릭률·전환수·전환 가치)은 광고비 탭 구글 머리글 → 일자별 표.
API 버전은 설정 칸(기본 DEFAULT_VERSION) — 구글은 버전을 약 1년 뒤 종료하므로 종료 안내가 오면 설정에서 올린다.
"""
@@ -40,9 +41,11 @@ API_BASE = "https://googleads.googleapis.com"
DEFAULT_VERSION = "v26" # 2026-10 기준 최신(구글 광고 API 는 매월 부 버전·분기마다 새 버전)
TOKEN_URI = "https://oauth2.googleapis.com/token"
MAX_DAYS = 366
VAT = Decimal("1.1") # 광고비 = 구글 비용 + 부가세 10%
# 일자별 표(광고비 탭 구글 머리글) 항목 — 순서 = 열 순서. 클릭률·ROAS 합계는 ad_spend.detail_table 이 이름으로 다시 계산.
M_COST, M_IMPR, M_CLICKS, M_CTR, M_CONV, M_VALUE, M_ROAS = "비용", "노출수", "클릭수", "클릭률(%)", "전환수", "전환 가치", "ROAS(%)"
M_SPEND, M_COST = "광고비(부가세 포함)", "비용(부가세 별도)"
M_IMPR, M_CLICKS, M_CTR, M_CONV, M_VALUE, M_ROAS = "노출수", "클릭수", "클릭률(%)", "전환수", "전환 가치", "ROAS(%)"
# 구글 오류 코드 → 고칠 곳 안내(오류 문구 뒤에 붙임)
_HINTS = {
@@ -88,8 +91,9 @@ def parse_service_account(raw: str) -> dict[str, Any]:
return info
def _won(micros: int) -> int:
return int((Decimal(int(micros)) / Decimal(1_000_000)).quantize(Decimal(1), rounding=ROUND_HALF_UP))
def _won(micros: int, rate: Decimal = Decimal(1)) -> int:
"""마이크로 단위 금액 × rate → 원(반올림). rate=VAT 면 부가세 포함."""
return int((Decimal(int(micros)) * rate / Decimal(1_000_000)).quantize(Decimal(1), rounding=ROUND_HALF_UP))
def _num(v: Any) -> Decimal:
@@ -280,12 +284,13 @@ class GoogleAdsSource(AdSource):
out: list[AdDay] = []
for day in sorted(sums):
a = sums[day]
amount = _won(int(a["cost"]))
amount = _won(int(a["cost"]), VAT) # 광고비 = 부가세 포함
cost = a["cost"] / Decimal(1_000_000)
roas = (a["value"] / cost * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if cost > 0 else None
ctr = (a["clicks"] / a["impr"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["impr"] > 0 else None
metrics = {
M_COST: amount,
M_SPEND: amount,
M_COST: _won(int(a["cost"])),
M_IMPR: int(a["impr"]),
M_CLICKS: int(a["clicks"]),
M_CTR: float(ctr) if ctr is not None else None,
@@ -200,7 +200,7 @@
</div>
<p class="perf-foot perf-muted">
광고비 기준: 쿠팡(윙)·쿠팡(로켓)은 광고 보고서의 청구금액(+부가가치세), 구글은 구글 광고 비용(부가세 별도).
광고비 기준: 쿠팡(윙)·쿠팡(로켓)은 광고 보고서의 청구금액(+부가가치세), 구글은 구글 광고 비용 + 부가세 10%(부가세 포함).
ROAS = 그 쇼핑몰 매출 ÷ 광고비 × 100(메타는 계산 안 함, 네이버·구글은 광고 쪽 값).
매출 대비 광고비 = 같은 기간 광고비 ÷ 매출 실적 총매출.
메타는 지금은 직접 입력합니다.
@@ -142,7 +142,7 @@
</table>
</div>
<p class="perf-foot perf-muted">
구글 광고: 비용은 구글 광고 화면의 "비용"(부가세 별도), ROAS = 전환 가치 ÷ 비용. 날짜는 광고 계정 시간대 기준이며 원화(KRW) 계정만 가져옵니다.
구글 광고: 광고비 = 구글 광고 화면의 "비용" + 부가세 10%(부가세 포함), ROAS = 전환 가치 ÷ 비용(구글 화면 값 그대로). 날짜는 광고 계정 시간대 기준이며 원화(KRW) 계정만 가져옵니다.
가져온 날은 직접 입력·업로드 값보다 우선해 덮어씁니다.
</p>
</div>
@@ -108,9 +108,11 @@ def test_fetch_days_converts_and_sends_headers(monkeypatch):
q = json.loads(api.content)["query"]
assert "segments.date BETWEEN '2026-10-01' AND '2026-10-03'" in q and "metrics.conversions_value" in q
d1, d2, d3 = days
assert (d1.day, d1.amount, d1.roas) == (date(2026, 10, 1), 123457, Decimal("500.00")) # 123,456.5원 → 반올림, 617,282.5 ÷ 123,456.5
assert d1.metrics == {"비용": 123457, "노출수": 20000, "클릭수": 400, "클릭률(%)": 2.0, "전환수": 12.5,
"전환 가치": 617283, "ROAS(%)": 500.0}
# 광고비 = 부가세 포함(2026-10-15): 123,456.5원 × 1.1 = 135,802.15 → 135,802. ROAS 는 구글 값 그대로(617,282.5 ÷ 123,456.5)
assert (d1.day, d1.amount, d1.roas) == (date(2026, 10, 1), 135802, Decimal("500.00"))
assert d1.metrics == {"광고비(부가세 포함)": 135802, "비용(부가세 별도)": 123457, "노출수": 20000, "클릭수": 400,
"클릭률(%)": 2.0, "전환수": 12.5, "전환 가치": 617283, "ROAS(%)": 500.0}
assert list(d1.metrics)[:2] == ["광고비(부가세 포함)", "비용(부가세 별도)"] # 일자별 표 열 순서
assert (d2.amount, d2.roas, d2.metrics["클릭률(%)"]) == (0, None, 0.0) # 비용 0 → ROAS 없음
assert (d3.amount, d3.roas) == (1, Decimal("300000.00"))
# 토큰은 한 번만 받아 두고 다시 쓴다
+2 -1
View File
@@ -380,7 +380,8 @@
승인 없는 프로젝트 = `CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION`(안내 문구 붙음).
토큰 = 서비스 계정 JWT(google-auth 서명) → `oauth2.googleapis.com/token`(httpx), 프로세스 안 캐시(만료 2분 전까지).
조회 = REST `googleAds:searchStream` GAQL `FROM customer` + `segments.date BETWEEN`(계정 시간대), 요청 1번.
금액 = `cost_micros ÷ 10⁶` 원 반올림(**부가세 별도** — 쿠팡은 부가세 포함이라 기준이 다름), ROAS = 전환 가치 ÷ 비용 × 100(소수 둘째),
금액 = `cost_micros ÷ 10⁶ × 1.1` 원 반올림 — **부가세 포함**(2026-10-15 사용자 요청, 쿠팡 청구금액과 같은 기준. 구글 비용 자체는 부가세 별도),
ROAS = 전환 가치 ÷ 비용(부가세 별도) × 100(소수 둘째, 구글 화면 값 그대로), 항목에 광고비(부가세 포함)·비용(부가세 별도) 둘 다,
항목 `metrics` = 비용·노출수·클릭수·클릭률(%)·전환수·전환 가치·ROAS(%) → 구글 머리글 클릭 = 일자별 표(`DETAIL_CHANNELS`).
통화가 KRW 가 아니면 저장 안 함. 구글 오류 코드는 고칠 곳 안내를 붙여 보여 줌(`_HINTS`: 권한 없음·토큰 미승인 등), 404 = API 버전 종료 안내.
- **저장**(`db.replace_ad_api_range`, 한 트랜잭션): API 가 준 날은 `source='api'` 로 덮어씀(직접 입력·업로드 값이 있던 날도),