"""① 쇼핑몰 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) "cancelled": "취소됨", # 화면 전용 — 매출 업데이트 창에서 [업데이트 취소](연결 상태는 바꾸지 않음) } 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" class Cancelled(AdapterError): """사용자가 매출 업데이트를 취소함 — 어댑터가 ctx.progress.check() 에서 받는다. 연결 오류가 아니다.""" status = "cancelled" # ════════════════════════════════════════════════════════════ # 설정 입력칸 · 공통 매출 사건 # ════════════════════════════════════════════════════════════ @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) # 어느 쇼핑몰 열로 집계할지 — None 이면 이 어댑터의 쇼핑몰. 다른 쇼핑몰 주문을 대신 받아 오는 # 연동(예: 카페24 마켓 통합관리가 가져온 스마트스토어 주문)은 해당 쇼핑몰 코드를 넣는다. marketplace_code: str | None = None 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: ... class Progress: """수집 진행 알림(매출 업데이트 창의 진행 막대용). 기본은 아무것도 하지 않는다 — sync 가 진행 상황을 모으는 객체(jobs.ShopProgress)로 바꿔 넣는다. 어댑터: 조회를 시작하기 전에 plan(전체 단계 수, 단위) → 단계 하나(하루·조회 구간)를 끝낼 때마다 step(items=그 단계에서 받은 건수). 하다가 할 일이 늘면 add(늘어난 단계 수). API 를 부르기 직전마다 check() — 사용자가 [업데이트 취소]를 눌렀으면 Cancelled 를 던져 거기서 멈춘다.""" def plan(self, total: int, unit: str = "단계") -> None: return None def add(self, n: int) -> None: return None def step(self, n: int = 1, *, items: int = 0) -> None: return None def check(self) -> None: return None @dataclass class AdapterContext: code: str credentials: CredentialAccessor app_state: Any = None # 공통 연동 계층 재사용(예: 카페24 토큰 저장소) timeout_sec: float = 20.0 progress: Progress = field(default_factory=Progress) # ════════════════════════════════════════════════════════════ # 어댑터 # ════════════════════════════════════════════════════════════ 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 # replace_range 일 때 이 어댑터가 만든 사건을 가려내는 외부 사건 ID 접두어. 다른 쇼핑몰 열로 보낸 # 사건(marketplace_code 지정)도 이 접두어로 찾아 함께 교체한다 — 그 쇼핑몰의 직접 연동분은 건드리지 않음. event_prefix: str = "" 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