feat(cafe24): 상품 상세페이지 관리 모듈 Phase 1

카페24 관리자에 직접 접속하지 않고 상품 상세페이지(description HTML)를 편집·예약 적용·복원하기 위한 모듈의 기반을 만든다. Phase 1 은 공통 Integration 계층, cafe24_db, OAuth 연결 화면까지다. 카페24 OAuth/API 클라이언트를 상품관리 모듈 안에 두지 않고 app/integrations/cafe24/ 로 분리했다. 향후 추가할 주문관리(주문 조회·송장 일괄등록·취소/반품/교환)가 같은 토큰과 클라이언트를 그대로 재사용해야 하기 때문이다. 라우터에서 httpx 를 직접 부르지 않고 Cafe24Client 만 쓰게 해서 재시도·rate limit·API 로그·토큰 갱신을 한 곳에 모았다. 토큰은 Fernet 으로 암호화해 저장한다(CAFE24_TOKEN_SECRET). DB 덤프가 유출돼도 access/refresh token 이 평문으로 남지 않게 하기 위함이며, API 로그와 연결 상태 화면에는 토큰·시크릿을 일절 기록/표시하지 않는다. 토큰 갱신은 행 잠금(SELECT ... FOR UPDATE) 안에서 한다. 카페24는 refresh token 을 회전시키므로, 이후 추가될 예약 worker 컨테이너와 web 컨테이너가 동시에 갱신하면 한쪽 토큰이 무효화된다. 기존 파일 변경은 목록에 한 줄씩 추가하는 형태로 44줄뿐이며 기존 라우트· 테이블·인증 로직은 건드리지 않았다. CAFE24_DB_URL 미설정 시 store 가 None 이라 앱은 정상 기동하고 모듈만 "설정 필요" 안내를 표시한다. 가드 헬퍼를 common.py 로 분리한 것은 router.py 가 routes_system.py 를 include 하는 구조에서 순환 import 가 생기기 때문이다. 검증: 신규 테스트 16개 통과(암호화 왕복, 토큰 만료·자동갱신, 상태 노출 시 토큰 미유출, 재시도 예산, 예약 상태 전이). dispatch 기존 테스트 9개 통과. cafe24_db_init.sql 은 로컬에 Docker 가 없어 미실행 — 서버 적용 시 확인 필요. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-14 00:23:02 +09:00
parent 31eab0d4cb
commit c6fb8ed375
29 changed files with 2689 additions and 0 deletions
@@ -0,0 +1,91 @@
+"""카페24 연동 공통 계층 (상품관리 + 향후 주문관리 공유).
+
+구성
+    config.py    환경변수 → Cafe24Config (하드코딩 금지)
+    crypto.py    토큰 Fernet 암복호화
+    oauth.py     인증 URL / code→token / refresh
+    tokens.py    TokenService — 저장·만료판정·자동갱신(행 잠금)
+    client.py    Cafe24Client — 전송·재시도·429/5xx·API 로그
+    products.py  상품 엔드포인트 래퍼
+    errors.py    공통 예외
+
+사용 예 (모듈 라우터에서):
+
+    from app.integrations.cafe24 import build_cafe24_api
+
+    api = build_cafe24_api(store)          # store = Cafe24Store
+    html = products.get_description(api.client, 123)
+
+CAFE24_* 환경변수가 없어도 import 는 성공한다. 실제 호출 시점에
+Cafe24ConfigError 가 나며, 라우터가 "설정 필요" 안내를 보여준다.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from . import products
+from .client import Cafe24Client
+from .config import (
+    ORDER_SCOPES,
+    PRODUCT_SCOPES,
+    Cafe24Config,
+    load_config,
+)
+from .errors import (
+    Cafe24ApiError,
+    Cafe24AuthError,
+    Cafe24ConfigError,
+    Cafe24Error,
+    Cafe24RateLimitError,
+)
+from .oauth import TokenBundle, build_authorize_url, exchange_code, new_state, refresh_tokens
+from .tokens import TokenService
+
+__all__ = [
+    "Cafe24Api",
+    "build_cafe24_api",
+    "Cafe24Client",
+    "Cafe24Config",
+    "TokenService",
+    "TokenBundle",
+    "load_config",
+    "build_authorize_url",
+    "exchange_code",
+    "refresh_tokens",
+    "new_state",
+    "products",
+    "PRODUCT_SCOPES",
+    "ORDER_SCOPES",
+    "Cafe24Error",
+    "Cafe24ConfigError",
+    "Cafe24AuthError",
+    "Cafe24RateLimitError",
+    "Cafe24ApiError",
+]
+
+
+@dataclass(frozen=True)
+class Cafe24Api:
+    """설정 + 토큰서비스 + 클라이언트 묶음. 라우터/worker 가 이것만 들고 다닌다."""
+
+    config: Cafe24Config
+    tokens: TokenService
+    client: Cafe24Client
+
+
+def build_cafe24_api(store: Any, *, scopes: tuple[str, ...] = PRODUCT_SCOPES) -> Cafe24Api:
+    """Cafe24Store 를 저장소로 쓰는 API 묶음 생성.
+
+    store 는 토큰 3개 메서드(get_token_row/save_token_row/token_lock)와
+    API 로그 기록용 log_api_call 을 제공해야 한다.
+    """
+    config = load_config(scopes=scopes)
+    token_service = TokenService(store, config)
+    client = Cafe24Client(
+        config,
+        token_service,
+        api_logger=getattr(store, "log_api_call", None),
+    )
+    return Cafe24Api(config=config, tokens=token_service, client=client)