Files
dbx-main/app/modules/performance/adapters/base.py
T
king c7cc94a09c fix: 2026-10-15 코드 검토 F01~F10 — 수집 실패 전파·트랜잭션 경계·저장 실패·공지 버전/확인 조건·테스트 체계
- 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>
2026-10-15 18:41:42 +09:00

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