27ee92c0a6
원인: 품목 결제금액(배송비 제외)을 매출로, 취소·반품 완료일의 품목 금액을 환불로 잡아 카페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>
220 lines
10 KiB
Python
220 lines
10 KiB
Python
"""① 쇼핑몰 API 수집 — 공통 인터페이스.
|
|
|
|
쇼핑몰 하나 = 어댑터 파일 하나. 새 쇼핑몰은 `MarketplaceAdapter` 를 상속한 파일을
|
|
만들고 `registry.py` 에 한 줄 추가하면 설정 화면·동기화·대시보드에 자동으로 붙는다.
|
|
|
|
흐름: 쇼핑몰 원본 → 어댑터(fetch_* → normalize_*) → 공통 SaleEvent → sync 서비스가 DB 저장
|
|
|
|
어댑터가 지켜야 할 것:
|
|
- 인증정보는 `ctx.credentials.get(key)` 로만 꺼낸다(복호화는 서버 안에서만).
|
|
- 새 토큰은 `ctx.credentials.set(key, value)` 로 저장한다(자동 암호화).
|
|
- 오류는 아래 AdapterError 계열로 던진다. 메시지에 비밀값을 넣지 않는다
|
|
(sync 서비스가 한 번 더 가리지만, 애초에 넣지 않는 것이 원칙).
|
|
- 금액은 원 단위 정수(int). 결제는 +, 취소/반품은 − 로 만든다.
|
|
- 날짜 기준을 섞지 않는다: order_date / payment_date / event_date 를 각각 채운다.
|
|
집계 기준일(sales_date)은 sync 서비스가 정한다(결제=결제일, 취소·반품=발생일).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from abc import ABC
|
|
from dataclasses import dataclass, field
|
|
from datetime import date
|
|
from typing import Any, Iterable, Protocol
|
|
|
|
# 연결 상태 코드 → 화면 표시. DB CHECK 제약과 같은 목록.
|
|
STATUS_LABELS: dict[str, str] = {
|
|
"ok": "정상 연결",
|
|
"not_configured": "인증정보 미설정",
|
|
"auth_failed": "인증 실패",
|
|
"token_expired": "Token 만료",
|
|
"api_error": "API 오류",
|
|
"not_implemented": "연동 준비 중",
|
|
"unknown": "확인 전",
|
|
"disabled": "사용 중지", # DB 에는 저장하지 않는 화면 전용 상태(쇼핑몰 사용 OFF)
|
|
}
|
|
|
|
EVENT_TYPES = ("SALE", "CANCEL", "RETURN", "ADJUST")
|
|
|
|
|
|
# ════════════════════════════════════════════════════════════
|
|
# 오류 — status 가 곧 연결 상태 코드
|
|
# ════════════════════════════════════════════════════════════
|
|
class AdapterError(Exception):
|
|
status = "api_error"
|
|
|
|
def __init__(self, message: str = "") -> None:
|
|
super().__init__(message or STATUS_LABELS.get(self.status, "오류"))
|
|
self.message = message or STATUS_LABELS.get(self.status, "오류")
|
|
|
|
|
|
class NotConfigured(AdapterError):
|
|
status = "not_configured"
|
|
|
|
|
|
class AuthFailed(AdapterError):
|
|
status = "auth_failed"
|
|
|
|
|
|
class TokenExpired(AdapterError):
|
|
status = "token_expired"
|
|
|
|
|
|
class ApiError(AdapterError):
|
|
status = "api_error"
|
|
|
|
|
|
class NotImplementedYet(AdapterError):
|
|
status = "not_implemented"
|
|
|
|
|
|
# ════════════════════════════════════════════════════════════
|
|
# 설정 입력칸 · 공통 매출 사건
|
|
# ════════════════════════════════════════════════════════════
|
|
@dataclass(frozen=True)
|
|
class CredentialField:
|
|
"""설정 화면 입력칸 하나. secret=True 면 저장 후 값을 화면으로 다시 보내지 않는다.
|
|
|
|
internal=True 는 화면에 안 보이는 내부 값(access/refresh token 등) — 어댑터가 직접 저장.
|
|
"""
|
|
|
|
key: str
|
|
label: str
|
|
secret: bool = False
|
|
required: bool = True
|
|
help: str = ""
|
|
placeholder: str = ""
|
|
internal: bool = False
|
|
|
|
|
|
@dataclass
|
|
class SaleEvent:
|
|
"""쇼핑몰 원본을 공통 형식으로 바꾼 매출 사건 하나(주문 라인 단위 권장)."""
|
|
|
|
event_type: str # SALE / CANCEL / RETURN / ADJUST
|
|
external_event_id: str # 쇼핑몰 안에서 이 사건을 유일하게 가리키는 값(중복 방지 키)
|
|
external_order_id: str
|
|
event_date: date # 사건 발생일(결제=결제일, 취소=취소일, 반품=반품완료일)
|
|
amount: int # 원 단위 정수. 결제 +, 취소/반품 −
|
|
external_line_id: str = ""
|
|
order_date: date | None = None
|
|
payment_date: date | None = None
|
|
product_name: str = ""
|
|
option_name: str = ""
|
|
quantity: int = 0
|
|
discount_amount: int = 0
|
|
order_status: str = ""
|
|
raw: dict[str, Any] = field(default_factory=dict)
|
|
|
|
def validate(self) -> None:
|
|
if self.event_type not in EVENT_TYPES:
|
|
raise ValueError(f"알 수 없는 사건 종류: {self.event_type}")
|
|
if not self.external_event_id or not self.external_order_id:
|
|
raise ValueError("external_event_id / external_order_id 가 필요합니다.")
|
|
if not isinstance(self.amount, int) or isinstance(self.amount, bool):
|
|
raise ValueError("amount 는 원 단위 정수여야 합니다.")
|
|
if self.event_type == "SALE" and self.amount < 0:
|
|
raise ValueError("결제(SALE) 금액은 음수일 수 없습니다.")
|
|
if self.event_type in ("CANCEL", "RETURN") and self.amount > 0:
|
|
raise ValueError("취소/반품 금액은 음수(또는 0)여야 합니다.")
|
|
|
|
|
|
class CredentialAccessor(Protocol):
|
|
def get(self, key: str) -> str: ...
|
|
|
|
def set(self, key: str, value: str) -> None: ...
|
|
|
|
def has(self, key: str) -> bool: ...
|
|
|
|
|
|
@dataclass
|
|
class AdapterContext:
|
|
code: str
|
|
credentials: CredentialAccessor
|
|
app_state: Any = None # 공통 연동 계층 재사용(예: 카페24 토큰 저장소)
|
|
timeout_sec: float = 20.0
|
|
|
|
|
|
# ════════════════════════════════════════════════════════════
|
|
# 어댑터
|
|
# ════════════════════════════════════════════════════════════
|
|
class MarketplaceAdapter(ABC):
|
|
code: str = ""
|
|
name: str = ""
|
|
auth_type: str = "api_key" # api_key / oauth / shared(공통 연동 계층 재사용)
|
|
docs_url: str = ""
|
|
implemented: bool = False # 실제 수집(fetch)이 구현됐는가
|
|
# True 면 동기화 때 그 기간(sales_date)의 이 쇼핑몰 실데이터를 지우고 새로 넣는다(한 트랜잭션).
|
|
# 쇼핑몰 API 가 "기간 안 결제·환불"을 빠짐없이 돌려줄 때만 켠다 — 규칙이 바뀌거나
|
|
# 주문이 사라져도 예전 행이 남지 않는다. False 면 같은 사건 ID 만 덮어쓴다(upsert).
|
|
replace_range: bool = False
|
|
note: str = "" # 설정 화면 안내 문구
|
|
|
|
# ── 설정 ──────────────────────────────────────────────
|
|
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]
|
|
|
|
@property
|
|
def uses_shared_integration(self) -> bool:
|
|
return self.auth_type == "shared"
|
|
|
|
def validate_credentials(self, values: dict[str, str]) -> list[str]:
|
|
"""저장 전 검사. 값 자체를 오류 문구에 넣지 않는다."""
|
|
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) > 2000:
|
|
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 authenticate(self, ctx: AdapterContext) -> None:
|
|
"""API 호출 전 준비(토큰 발급 등). 기본은 할 일 없음."""
|
|
if not self.is_configured(ctx):
|
|
raise NotConfigured("필수 인증정보가 입력되지 않았습니다.")
|
|
|
|
def refresh_token(self, ctx: AdapterContext) -> None:
|
|
"""OAuth 쇼핑몰: refresh token 으로 access token 재발급 후 ctx.credentials.set(...)."""
|
|
return None
|
|
|
|
def test_connection(self, ctx: AdapterContext) -> str:
|
|
"""성공 시 사람이 읽을 짧은 문구 반환. 실패는 AdapterError."""
|
|
self.authenticate(ctx)
|
|
raise NotImplementedYet(f"{self.name} API 연동은 다음 단계에서 구현됩니다.")
|
|
|
|
# ── 수집 ──────────────────────────────────────────────
|
|
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
|
|
raise NotImplementedYet(f"{self.name} 주문 수집은 다음 단계에서 구현됩니다.")
|
|
|
|
def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
|
|
return []
|
|
|
|
def normalize_order(self, raw: dict[str, Any]) -> list[SaleEvent]:
|
|
raise NotImplementedYet(f"{self.name} 주문 변환은 다음 단계에서 구현됩니다.")
|
|
|
|
def normalize_refund(self, raw: dict[str, Any]) -> list[SaleEvent]:
|
|
return []
|
|
|
|
def collect(self, ctx: AdapterContext, start: date, end: date) -> tuple[int, list[SaleEvent]]:
|
|
"""기간의 주문·취소/반품을 받아 공통 사건으로 변환. (원본 건수, 사건 목록)."""
|
|
self.authenticate(ctx)
|
|
fetched = 0
|
|
events: list[SaleEvent] = []
|
|
for raw in self.fetch_orders(ctx, start, end):
|
|
fetched += 1
|
|
events.extend(self.normalize_order(raw))
|
|
for raw in self.fetch_refunds(ctx, start, end):
|
|
fetched += 1
|
|
events.extend(self.normalize_refund(raw))
|
|
for ev in events:
|
|
ev.validate()
|
|
return fetched, events
|