c7cc94a09c
- F01 쿠팡: HTTP 200 비JSON·data 목록 없음은 수집 실패(기간 교체 안 함), 정상 빈 목록과 구분 - F02 회의록 [적용]: 업무 INSERT 와 줄 연결을 한 연결·한 트랜잭션(_insert_task), 확인은 잠그기 전·알림/메일은 커밋 뒤, 줄 바뀜 409 - F03 업무 등록 표: persist 실패 전파, 미저장이면 [적용] 중단, 초안 유지·다시 저장·이탈 경고 - F04 인증정보 변경 시 내부 토큰 삭제 + 네이버·토스 토큰을 발급 인증정보 지문(SHA-256)에 묶음, GS샵 방식 캐시도 키 지문 기준 - F05 쪽 수 상한·커서 반복 = 실패(쿠팡은 구간을 하루까지 나눠 재시도), 네이버·카카오·토스·GS샵 동일 기준 - F06 [중지] 확인과 저장 시작을 같은 잠금(begin_saving), 저장 시작 뒤 중지 불가 - F07/F08 긴급 공지: 내용 version·고친 공지 다시 그리기·확인에 version(409), 확인은 행 잠금 트랜잭션에서 수신자·표시 시각·취소 검증 - F09 쇼핑몰 연결 테스트도 clear 처리·저장 안 한 시험은 상태 유지(광고 테스트와 같은 계약) - F10 DB 테스트 skip·가짜 app.main/time.sleep 파일 범위 fixture, 오래된 기대값 갱신, pytest.ini·requirements-dev·tests/js/package.json·docs/TESTING.md - 결과·후속 과제: docs/CODE_REVIEW_2026-10-15_RESULT.md (마이그레이션·환경변수 변경 없음) Python 440 passed/63 skipped(DB 없음), 503 passed(로컬 PostgreSQL), jsdom 7종·Edge 6종 통과 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
269 lines
13 KiB
Python
269 lines
13 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)
|
|
"cancelled": "취소됨", # 화면 전용 — 매출 업데이트 창에서 [업데이트 취소](연결 상태는 바꾸지 않음)
|
|
"manual": "수동 입력", # 화면 전용 — API 없이 수동 입력만 쓰는 쇼핑몰(manual_only)
|
|
}
|
|
|
|
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 등) — 어댑터가 직접 저장.
|
|
multiline=True 면 여러 줄 입력칸(서비스 계정 JSON 키 등).
|
|
"""
|
|
|
|
key: str
|
|
label: str
|
|
secret: bool = False
|
|
required: bool = True
|
|
help: str = ""
|
|
placeholder: str = ""
|
|
internal: bool = False
|
|
multiline: 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)여야 합니다.")
|
|
|
|
|
|
def credential_fingerprint(credentials: Any, keys: Iterable[str]) -> str:
|
|
"""토큰을 발급한 인증정보 묶음의 지문(SHA-256 16진수) — 원문은 남기지 않는다(2026-10-15 검토 F04).
|
|
저장된 토큰은 이 지문이 지금 인증정보(연결 테스트의 새 입력값 포함)와 같을 때만 다시 쓴다 —
|
|
계정·키를 바꾸면 이전 계정 토큰을 쓰지 않고, 같은 값을 다시 저장하면 토큰을 새로 받지 않는다."""
|
|
import hashlib # noqa: WPS433
|
|
|
|
raw = "\x1f".join(f"{k}={(credentials.get(k) or '').strip()}" for k in keys)
|
|
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
|
|
|
|
|
|
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 면 API 연동이 없는 수동 입력 전용 쇼핑몰 — 매출 업데이트에서 빠지고, 인증 설정·연결 테스트가 없다.
|
|
manual_only: bool = False
|
|
# 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
|