"""카페24 — 공통 연동 계층(app/integrations/cafe24) 재사용. 카페24는 이미 OAuth 로 연결해 쓰고 있다(상품관리). 실적 설정에서 인증정보를 따로 받지 않고, 같은 토큰 저장소(cafe24_db)와 클라이언트(재시도·429·토큰 자동 갱신)를 쓴다. 주문 읽기 권한(mall.read_order)이 필요하다 — config.DEFAULT_SCOPES 에 포함, 권한 추가 후 카페24 상품관리 → 시스템에서 한 번 다시 연결해야 한다. 수집 규칙 (Admin API GET /admin/orders, 문서 버전 2026-09-01 확인) - 결제(SALE): date_type=pay_date(결제일), embed=items. 결제된(paid=T) 주문의 품목마다 품목 결제금액(payment_amount — 할인 반영, 배송비 제외)을 매출로. 사건 날짜 = 결제일. - 취소(CANCEL): date_type=cancel_complete_date. 품목 상태 C40~C43(취소완료)만, 결제 때와 같은 품목 금액을 음수로. 입금전취소(C47~C49)는 매출이 아니었으므로 제외. - 반품(RETURN): date_type=return_complete_date. 품목 상태 R40~R43(반품완료)만 음수로. 부분 반품(0 < claim_quantity < quantity)은 수량 비율로 나눈다. - 교환(E**)은 매출 변화 없음으로 보고 1단계에서는 반영하지 않는다. - 자체몰 주문만(market_id 가 self/빈값). 카페24 로 들어온 다른 마켓(스마트스토어·쿠팡 등) 주문은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외한다. 네이버페이 결제는 자체몰 주문이라 포함. - 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. limit 최대 1000, offset 최대 15000. - 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않는다 — raw 에는 금액·상태 필드만. """ 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" PAGE_LIMIT = 1000 MAX_OFFSET = 15000 CHUNK_DAYS = 60 CANCEL_DONE = {"C40", "C41", "C42", "C43"} RETURN_DONE = {"R40", "R41", "R42", "R43"} SELF_MARKETS = {"", "self", None} 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 item_amount(item: dict[str, Any]) -> int: """품목 결제금액. payment_amount 가 없으면 (판매가+옵션가)×수량 − 품목 할인으로 계산.""" if item.get("payment_amount") not in (None, ""): return _won(item["payment_amount"]) qty = int(item.get("quantity") or 0) gross = (_won(item.get("product_price")) + _won(item.get("option_price"))) * qty discounts = (_won(item.get("additional_discount_price")) + _won(item.get("coupon_discount_price")) + _won(item.get("app_item_discount_amount"))) return max(0, gross - discounts) def _raw(order: dict[str, Any], item: dict[str, Any]) -> dict[str, Any]: """저장용 원본 — 금액·상태만(개인정보 제외).""" keys = ("order_item_code", "order_status", "status_code", "product_no", "product_code", "variant_code", "product_price", "option_price", "quantity", "claim_quantity", "additional_discount_price", "coupon_discount_price", "app_item_discount_amount", "payment_amount", "claim_code") return { "order_id": order.get("order_id"), "market_id": order.get("market_id"), "order_place_id": order.get("order_place_id"), "paid": order.get("paid"), **{k: item.get(k) for k in keys}, } class Cafe24Adapter(MarketplaceAdapter): code = "cafe24" name = "카페24" auth_type = "shared" implemented = 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, params: dict[str, Any]) -> dict[str, Any]: from app.integrations.cafe24.errors import ( # 지연 import Cafe24ApiError, Cafe24AuthError, Cafe24ConfigError, Cafe24RateLimitError, ) try: return self._client(ctx).get("/admin/orders", 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() self._get(ctx, {"start_date": today.isoformat(), "end_date": today.isoformat(), "date_type": "pay_date", "limit": 1}) return "카페24 연결 정상(주문 조회 권한 확인)." # ── 수집 ────────────────────────────────────────────── def _orders(self, ctx: AdapterContext, start: date, end: date, date_type: str) -> Iterable[dict[str, Any]]: """기간을 60일씩 나눠 페이지를 넘기며 주문(+items)을 모두 가져온다.""" s = start while s <= end: e = min(end, s + timedelta(days=CHUNK_DAYS - 1)) offset = 0 while True: if offset > MAX_OFFSET: raise ApiError(f"카페24 조회 건수가 너무 많습니다({s}~{e}). 기간을 줄여 다시 시도하세요.") data = self._get(ctx, {"start_date": s.isoformat(), "end_date": e.isoformat(), "date_type": date_type, "embed": "items", "limit": PAGE_LIMIT, "offset": offset}) orders = data.get("orders") or [] yield from orders if len(orders) < PAGE_LIMIT: break offset += PAGE_LIMIT s = e + timedelta(days=1) def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: for o in self._orders(ctx, start, end, "pay_date"): yield {"kind": "paid", "order": o} def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: for o in self._orders(ctx, start, end, "cancel_complete_date"): yield {"kind": "cancel", "order": o} for o in self._orders(ctx, start, end, "return_complete_date"): yield {"kind": "return", "order": o} @staticmethod def _is_self_order(order: dict[str, Any]) -> bool: return order.get("market_id") in SELF_MARKETS def normalize_order(self, raw: dict[str, Any]) -> list[SaleEvent]: order = raw.get("order") or {} if not self._is_self_order(order) or order.get("paid") != "T": return [] pay_day = _day(order.get("payment_date")) if pay_day is None: return [] order_id = str(order.get("order_id") or "") events = [] for item in order.get("items") or []: code = str(item.get("order_item_code") or "") if not code: continue events.append(SaleEvent( event_type="SALE", external_event_id=f"{code}-S", external_order_id=order_id, external_line_id=code, order_date=_day(order.get("order_date")), payment_date=pay_day, event_date=pay_day, amount=item_amount(item), product_name=str(item.get("product_name") or ""), option_name=str(item.get("option_value") or "") if isinstance(item.get("option_value"), str) else "", quantity=int(item.get("quantity") or 0), order_status=str(item.get("order_status") or ""), raw=_raw(order, item), )) return events def normalize_refund(self, raw: dict[str, Any]) -> list[SaleEvent]: order = raw.get("order") or {} if not self._is_self_order(order): return [] kind = raw.get("kind") done, ev_type, suffix = (CANCEL_DONE, "CANCEL", "C") if kind == "cancel" else (RETURN_DONE, "RETURN", "R") order_id = str(order.get("order_id") or "") events = [] for item in order.get("items") or []: code = str(item.get("order_item_code") or "") status = str(item.get("order_status") or "") if not code or status not in done: continue if kind == "cancel": day = _day(item.get("cancel_date")) or _day(order.get("cancel_date")) else: day = _day(item.get("return_confirmed_date")) or _day(item.get("refund_date")) if day is None: continue amount = item_amount(item) qty = int(item.get("quantity") or 0) claim = int(item.get("claim_quantity") or 0) if kind == "return" and 0 < claim < qty: amount = int((Decimal(amount) * claim / qty).quantize(Decimal(1), rounding=ROUND_HALF_UP)) qty = claim events.append(SaleEvent( event_type=ev_type, external_event_id=f"{code}-{suffix}", external_order_id=order_id, external_line_id=code, order_date=_day(order.get("order_date")), payment_date=_day(order.get("payment_date")), event_date=day, amount=-amount, product_name=str(item.get("product_name") or ""), quantity=-qty, order_status=status, raw=_raw(order, item), )) return events