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,74 @@
+"""카페24 연동 설정 — 환경변수만 읽는다(하드코딩 금지).
+
+app/main.py 의 env() 헬퍼와 동일하게 os.getenv + strip 규칙을 쓴다.
+integrations 계층은 app.main 을 import 하지 않는다(순환 import 방지).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# 상품관리에 필요한 최소 scope. 향후 주문관리는 ORDER_SCOPES 를 더한다.
+PRODUCT_SCOPES: tuple[str, ...] = ("mall.read_product", "mall.write_product")
+ORDER_SCOPES: tuple[str, ...] = ("mall.read_order", "mall.write_order")
+
+DEFAULT_API_VERSION = "2026-03-01"
+
+
+def _env(name: str, default: str = "") -> str:
+    value = os.getenv(name, "").strip()
+    return value if value else default
+
+
+@dataclass(frozen=True)
+class Cafe24Config:
+    mall_id: str
+    client_id: str
+    client_secret: str
+    redirect_uri: str
+    api_version: str
+    token_secret: str
+    scopes: tuple[str, ...]
+
+    @property
+    def configured(self) -> bool:
+        """OAuth 를 시작할 수 있는 최소 조건."""
+        return bool(self.mall_id and self.client_id and self.client_secret and self.redirect_uri)
+
+    @property
+    def missing(self) -> list[str]:
+        """설정 안내 화면에 표시할 미설정 환경변수 이름들."""
+        pairs = (
+            ("CAFE24_MALL_ID", self.mall_id),
+            ("CAFE24_CLIENT_ID", self.client_id),
+            ("CAFE24_CLIENT_SECRET", self.client_secret),
+            ("CAFE24_REDIRECT_URI", self.redirect_uri),
+            ("CAFE24_TOKEN_SECRET", self.token_secret),
+        )
+        return [name for name, value in pairs if not value]
+
+    @property
+    def api_base(self) -> str:
+        return f"https://{self.mall_id}.cafe24api.com/api/v2"
+
+    @property
+    def scope_param(self) -> str:
+        return ",".join(self.scopes)
+
+
+def load_config(*, scopes: tuple[str, ...] = PRODUCT_SCOPES) -> Cafe24Config:
+    """환경변수에서 설정을 읽는다. 값이 없어도 예외를 던지지 않는다.
+
+    미설정 판단은 호출부가 `configured` / `missing` 으로 한다
+    (앱 기동을 막지 않기 위해 — 다른 모듈과 동일한 정책).
+    """
+    return Cafe24Config(
+        mall_id=_env("CAFE24_MALL_ID"),
+        client_id=_env("CAFE24_CLIENT_ID"),
+        client_secret=_env("CAFE24_CLIENT_SECRET"),
+        redirect_uri=_env("CAFE24_REDIRECT_URI"),
+        api_version=_env("CAFE24_API_VERSION", DEFAULT_API_VERSION),
+        token_secret=_env("CAFE24_TOKEN_SECRET"),
+        scopes=scopes,
+    )