Files
dbx-main/app/modules/performance/adapters/cafe24.py
T
king 27ee92c0a6 fix(performance): 카페24 매출을 카페24 "일별 매출내역" 기준으로(결제합계·환불합계) + 매출 대조 도구
원인: 품목 결제금액(배송비 제외)을 매출로, 취소·반품 완료일의 품목 금액을 환불로 잡아
카페24 화면(결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰, 환불합계 = 환불완료일 실제 환불액)과 달랐다.

- SALE: 결제일 기준 주문 단위 결제합계(initial_order_amount — 결제 당시 금액)
- CANCEL/RETURN: GET /admin/refunds 환불완료일, 실제 환불액(환불코드 R=반품)
- 환불도 원 주문 market_id 로 자체몰만(다른 마켓 연동 주문 제외)
- 기간 교체(replace_range): 동기화한 기간의 카페24 실데이터를 지우고 새로 넣음(한 트랜잭션,
  테스트 데이터 제외) — 예전 품목 단위 행이 남아 이중 집계되지 않게
- 설정 화면 "카페24 매출 대조": 날짜별로 카페24 화면 열 순서대로 원천 금액 합산(자체몰/마켓 구분, 저장 안 함)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:38:44 +09:00

305 lines
16 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""카페24 — 공통 연동 계층(app/integrations/cafe24) 재사용.
카페24는 이미 OAuth 로 연결해 쓰고 있다(상품관리). 실적 설정에서 인증정보를 따로
받지 않고, 같은 토큰 저장소(cafe24_db)와 클라이언트(재시도·429·토큰 자동 갱신)를 쓴다.
주문 읽기 권한(mall.read_order)이 필요하다 — config.DEFAULT_SCOPES 에 포함, 권한 추가 후
카페24 상품관리 → 시스템에서 한 번 다시 연결해야 한다.
카페24 관리자 "일별 매출내역"과 같은 기준으로 센다(Admin API 문서 2026-09-01 확인).
- 결제합계(SALE, +): GET /admin/orders date_type=pay_date(결제일), 결제된(paid=T) 주문마다
상품구매금액 + 배송비 − 할인 − 쿠폰 (주문의 initial_order_amount — 결제 당시 금액)
환불은 따로 빼므로 취소 후 금액(actual_order_amount)이 아니라 결제 당시 금액을 쓴다.
- 환불합계(CANCEL/RETURN, −): GET /admin/refunds date_type=refund_date(환불완료일),
실제 환불액(actual_refund_amount). 환불코드가 R 로 시작하면 반품, 그 밖은 취소.
- 수집 기간을 통째로 다시 받는다(replace_range) — 결제·환불 모두 기간 안 날짜로 조회되므로
그 기간의 카페24 실데이터를 지우고 새로 넣는다. 규칙이 바뀌거나 주문이 사라져도 이중 집계 없음.
- 자체몰 주문만(market_id 가 self/빈값). 카페24 로 연동돼 들어온 다른 마켓(스마트스토어·쿠팡 등)
주문은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외(환불도 원 주문의 market_id 로 판단).
네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 포함.
- 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. orders limit ≤ 1000, refunds limit ≤ 500, offset ≤ 15000.
- 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않는다 — raw 에는 금액·상태 필드만.
- 할인 항목 구성·마켓 주문 포함 여부는 `reconcile()`(설정 화면 "카페24 매출 대조")로 카페24 화면과
대조해 확정한다.
"""
from __future__ import annotations
from datetime import date, timedelta
from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
from typing import Any, Iterable
from .base import (
AdapterContext,
ApiError,
AuthFailed,
MarketplaceAdapter,
NotConfigured,
SaleEvent,
TokenExpired,
)
ORDER_SCOPE = "mall.read_order"
ORDER_LIMIT = 1000
REFUND_LIMIT = 500
LOOKUP_BATCH = 100
MAX_OFFSET = 15000
CHUNK_DAYS = 60
SELF_MARKETS = {"", "self", None}
# 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (initial_order_amount 의 필드)
DISCOUNT_FIELDS = ("membership_discount_amount", "set_product_discount_amount", "app_discount_amount",
"market_other_discount_amount", "shipping_fee_discount_amount")
COUPON_FIELDS = ("coupon_discount_price", "coupon_shipping_fee_amount")
AMOUNT_FIELDS = ("order_price_amount", "shipping_fee", *DISCOUNT_FIELDS, *COUPON_FIELDS,
"points_spent_amount", "credits_spent_amount", "payment_amount")
def _won(value: Any) -> int:
"""카페24 금액 문자열("29000.00") → 원 단위 정수."""
try:
return int(Decimal(str(value or "0")).quantize(Decimal(1), rounding=ROUND_HALF_UP))
except (InvalidOperation, ValueError):
return 0
def _day(value: Any) -> date | None:
""""2018-07-04T11:21:35+09:00" / "2017-07-10 15:55:51" → date (카페24 는 KST 로 준다)."""
s = str(value or "").strip()
if len(s) < 10:
return None
try:
return date.fromisoformat(s[:10])
except ValueError:
return None
def order_amounts(order: dict[str, Any]) -> dict[str, int]:
"""결제 당시 금액(initial_order_amount, 없으면 actual_order_amount) 항목별 원 단위."""
a = order.get("initial_order_amount") or order.get("actual_order_amount") or {}
return {k: _won(a.get(k)) for k in AMOUNT_FIELDS}
def order_total(order: dict[str, Any]) -> int:
"""결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰."""
a = order_amounts(order)
return (a["order_price_amount"] + a["shipping_fee"]
- sum(a[k] for k in DISCOUNT_FIELDS) - sum(a[k] for k in COUPON_FIELDS))
def is_self_market(market_id: Any) -> bool:
return market_id in SELF_MARKETS
def _chunks(start: date, end: date) -> Iterable[tuple[date, date]]:
s = start
while s <= end:
e = min(end, s + timedelta(days=CHUNK_DAYS - 1))
yield s, e
s = e + timedelta(days=1)
class Cafe24Adapter(MarketplaceAdapter):
code = "cafe24"
name = "카페24"
auth_type = "shared"
implemented = True
replace_range = True
docs_url = "https://apidocs.cafe24.com/docs/admin/get-orders"
note = ("카페24 상품관리에서 연결한 OAuth 토큰을 함께 씁니다(여기서 따로 입력하지 않음). "
"주문 읽기 권한이 필요해 권한 추가 후 한 번 다시 연결해야 합니다.")
# ── 연결 ──────────────────────────────────────────────
def is_configured(self, ctx: AdapterContext) -> bool:
return True
def _repo(self, ctx: AdapterContext):
return getattr(ctx.app_state, "cafe24_store", None) if ctx.app_state is not None else None
def shared_status(self, ctx: AdapterContext) -> dict:
from app.integrations.cafe24.config import load_config # 지연 import
from app.integrations.cafe24.tokens import TokenService # 지연 import
repo = self._repo(ctx)
config = load_config()
if repo is None:
return {"connected": False, "missing": config.missing or ["CAFE24_DB_URL"], "needs_reauth": False}
return TokenService(repo, config).status()
def authenticate(self, ctx: AdapterContext) -> None:
st = self.shared_status(ctx)
if not st.get("connected"):
if st.get("missing"):
raise NotConfigured("카페24 연동 환경변수가 설정되지 않았습니다.")
if st.get("needs_reauth") and str(st.get("reason", "")).startswith("refresh"):
raise TokenExpired("카페24 연결이 만료되었습니다. 카페24 상품관리 → 시스템에서 재연결하세요.")
raise AuthFailed("카페24에 연결되어 있지 않습니다. 카페24 상품관리 → 시스템에서 연결하세요.")
if ORDER_SCOPE not in str(st.get("scopes") or ""):
raise AuthFailed("카페24 토큰에 주문 읽기 권한(mall.read_order)이 없습니다. "
"카페24 상품관리 → 시스템에서 다시 연결하세요.")
def _client(self, ctx: AdapterContext):
from app.integrations.cafe24 import build_cafe24_api # 지연 import
return build_cafe24_api(self._repo(ctx)).client
def _get(self, ctx: AdapterContext, path: str, params: dict[str, Any]) -> dict[str, Any]:
from app.integrations.cafe24.errors import ( # 지연 import
Cafe24ApiError,
Cafe24AuthError,
Cafe24ConfigError,
Cafe24RateLimitError,
)
try:
return self._client(ctx).get(path, params=params)
except Cafe24ConfigError as exc:
raise NotConfigured(str(exc)) from None
except Cafe24AuthError as exc:
raise AuthFailed(str(exc)) from None
except Cafe24RateLimitError as exc:
raise ApiError(f"카페24 호출 제한(429): {exc}") from None
except Cafe24ApiError as exc:
status = getattr(exc, "status", None)
if status == 403:
raise AuthFailed(f"카페24 권한 오류(403): {exc}. 주문 권한 추가 후 재연결하세요.") from None
raise ApiError(f"카페24 API 오류({status}): {exc}") from None
def test_connection(self, ctx: AdapterContext) -> str:
from app.timezone import today_kst # noqa: WPS433
self.authenticate(ctx)
today = today_kst().isoformat()
self._get(ctx, "/admin/orders", {"start_date": today, "end_date": today, "date_type": "pay_date", "limit": 1})
return "카페24 연결 정상(주문 조회 권한 확인)."
# ── 조회 ──────────────────────────────────────────────
def _paged(self, ctx: AdapterContext, path: str, key: str, params: dict[str, Any],
limit: int) -> Iterable[dict[str, Any]]:
offset = 0
while True:
if offset > MAX_OFFSET:
raise ApiError(f"카페24 조회 건수가 너무 많습니다({params.get('start_date')}~{params.get('end_date')}). "
"기간을 줄여 다시 시도하세요.")
rows = self._get(ctx, path, {**params, "limit": limit, "offset": offset}).get(key) or []
yield from rows
if len(rows) < limit:
return
offset += limit
def paid_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
for s, e in _chunks(start, end):
yield from self._paged(ctx, "/admin/orders", "orders",
{"start_date": s.isoformat(), "end_date": e.isoformat(),
"date_type": "pay_date", "embed": "items"}, ORDER_LIMIT)
def refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
for s, e in _chunks(start, end):
yield from self._paged(ctx, "/admin/refunds", "refunds",
{"start_date": s.isoformat(), "end_date": e.isoformat(),
"date_type": "refund_date"}, REFUND_LIMIT)
def market_ids(self, ctx: AdapterContext, refunds: list[dict[str, Any]]) -> dict[str, Any]:
"""환불의 원 주문 market_id — 주문일 60일 구간·100건씩 묶어 조회."""
pairs = sorted({(_day(r.get("order_date")) or date.min, str(r.get("order_id") or ""))
for r in refunds if r.get("order_id")})
out: dict[str, Any] = {}
i = 0
while i < len(pairs):
first = pairs[i][0]
group = [p for p in pairs[i:i + LOOKUP_BATCH] if (p[0] - first).days < CHUNK_DAYS]
ids = [oid for _, oid in group]
if first != date.min:
params = {"order_id": ",".join(ids), "start_date": first.isoformat(),
"end_date": group[-1][0].isoformat(), "date_type": "order_date", "limit": LOOKUP_BATCH}
for o in self._get(ctx, "/admin/orders", params).get("orders") or []:
out[str(o.get("order_id"))] = o.get("market_id")
i += len(group)
return out
# ── 수집(어댑터 공통 흐름) ──────────────────────────────
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
yield from self.paid_orders(ctx, start, end)
def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
rows = [r for r in self.refunds(ctx, start, end) if str(r.get("status") or "T") == "T"]
markets = self.market_ids(ctx, rows)
for r in rows:
yield {**r, "_market_id": markets.get(str(r.get("order_id")), "self")}
def normalize_order(self, order: dict[str, Any]) -> list[SaleEvent]:
if not is_self_market(order.get("market_id")) or order.get("paid") != "T":
return []
pay_day = _day(order.get("payment_date"))
if pay_day is None:
return []
items = order.get("items") or []
names = [str(i.get("product_name") or "") for i in items if i.get("product_name")]
name = names[0] + (f" 외 {len(names) - 1}건" if len(names) > 1 else "") if names else ""
oid = str(order.get("order_id") or "")
return [SaleEvent(
event_type="SALE", external_event_id=f"{oid}-PAY", external_order_id=oid,
order_date=_day(order.get("order_date")), payment_date=pay_day, event_date=pay_day,
amount=max(0, order_total(order)), product_name=name,
quantity=sum(int(i.get("quantity") or 0) for i in items), order_status="결제완료",
discount_amount=sum(order_amounts(order)[k] for k in DISCOUNT_FIELDS + COUPON_FIELDS),
raw={"order_id": oid, "market_id": order.get("market_id"), "order_place_id": order.get("order_place_id"),
"items": len(items), **{f"initial_{k}": v for k, v in order_amounts(order).items()}},
)]
def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]:
if not is_self_market(refund.get("_market_id")):
return []
day = _day(refund.get("refund_date"))
code = str(refund.get("refund_code") or "")
if day is None or not code:
return []
amount = _won(refund.get("actual_refund_amount"))
return [SaleEvent(
event_type="RETURN" if code.upper().startswith("R") else "CANCEL",
external_event_id=code, external_order_id=str(refund.get("order_id") or ""),
external_line_id=",".join(refund.get("order_item_code") or []),
order_date=_day(refund.get("order_date")), event_date=day, amount=-amount,
quantity=-int(refund.get("quantity") or 0), order_status="환불완료",
raw={"refund_code": code, "order_id": refund.get("order_id"), "status": refund.get("status"),
"actual_refund_amount": refund.get("actual_refund_amount"),
"used_points": refund.get("used_points"), "used_credits": refund.get("used_credits"),
"quantity": refund.get("quantity"), "order_item_code": refund.get("order_item_code")},
)]
# ── 대조(설정 화면 "카페24 매출 대조") ─────────────────
def reconcile(self, ctx: AdapterContext, day: date) -> dict[str, Any]:
"""그날 결제 주문·환불을 항목별로 합산 — 카페24 일별 매출내역과 비교해 규칙을 확정하는 용도.
자체몰/다른 마켓을 나눠 합산한다. 개인정보는 담지 않는다.
"""
self.authenticate(ctx)
def empty() -> dict[str, int]:
return {"orders": 0, "items": 0, "lines": 0, **{k: 0 for k in AMOUNT_FIELDS}, "total": 0}
groups = {"self": empty(), "market": empty()}
unpaid = 0
for o in self.paid_orders(ctx, day, day):
if o.get("paid") != "T":
unpaid += 1
continue
g = groups["self" if is_self_market(o.get("market_id")) else "market"]
g["orders"] += 1
g["items"] += sum(int(i.get("quantity") or 0) for i in o.get("items") or [])
g["lines"] += len(o.get("items") or [])
for k, v in order_amounts(o).items():
g[k] += v
g["total"] += order_total(o)
rows = [r for r in self.refunds(ctx, day, day) if str(r.get("status") or "T") == "T"]
markets = self.market_ids(ctx, rows)
refunds = {"self": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0},
"market": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0}}
for r in rows:
g = refunds["self" if is_self_market(markets.get(str(r.get("order_id")), "self")) else "market"]
g["count"] += 1
for k in ("actual_refund_amount", "used_points", "used_credits"):
g[k] += _won(r.get(k))
return {"date": day.isoformat(), "orders": groups, "refunds": refunds, "unpaid_orders": unpaid,
"formula": "결제합계 = 상품구매금액 + 배송비 − 할인(" + ", ".join(DISCOUNT_FIELDS) +
") − 쿠폰(" + ", ".join(COUPON_FIELDS) + ")"}