Files
dbx-main/app/modules/performance/adapters/cafe24.py
T
king f63f82d642 fix(performance): 카페24 market_id 의 자체몰 채널(모바일웹·네이버페이·톡체크아웃)을 자체몰로 분류
실데이터 대조 결과 "다른 마켓 연동"으로 보이던 주문은 mobile(모바일웹)·NCHECKOUT(네이버페이)·
KAKAOPAY(톡체크아웃) — 모두 카페24 자체몰 주문. 금액은 이미 카페24 열이었지만 대조 표시가 오해를 불렀다.

- SELF_CHANNELS 로 자체몰 채널 명시, channel_kind(self/market/unknown)
- MARKET_MAP 에서 결제수단과 헷갈리는 일반 이름(naver, kakao 등) 제거
- 매출 대조: "카페24 열 / 다른 쇼핑몰 열" + "주문 채널별" 표(자체몰 채널/외부 마켓/알 수 없는 채널)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 16:59:16 +09:00

383 lines
20 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
"""카페24 — 공통 연동 계층(app/integrations/cafe24) 재사용.
카페24는 이미 OAuth 로 연결해 쓰고 있다(상품관리). 실적 설정에서 인증정보를 따로
받지 않고, 같은 토큰 저장소(cafe24_db)와 클라이언트(재시도·429·토큰 자동 갱신)를 쓴다.
주문 읽기 권한(mall.read_order)이 필요하다 — config.DEFAULT_SCOPES 에 포함, 권한 추가 후
카페24 상품관리 → 시스템에서 한 번 다시 연결해야 한다.
카페24 관리자 "일별 매출내역"과 같은 기준으로 센다(Admin API 문서 2026-09-01 확인).
- 결제합계(SALE, +): GET /admin/orders date_type=pay_date(결제일), 결제된(paid=T) 주문마다
상품구매금액 + 배송비 − 할인 − 쿠폰 (주문의 initial_order_amount — 결제 당시 금액)
환불은 따로 빼므로 취소 후 금액(actual_order_amount)이 아니라 결제 당시 금액을 쓴다.
- 환불합계(CANCEL/RETURN, −): GET /admin/refunds date_type=refund_date(환불완료일),
실제 환불액(actual_refund_amount). 환불코드가 R 로 시작하면 반품, 그 밖은 취소.
- 수집 기간을 통째로 다시 받는다(replace_range) — 결제·환불 모두 기간 안 날짜로 조회되므로
그 기간의 카페24 실데이터를 지우고 새로 넣는다. 규칙이 바뀌거나 주문이 사라져도 이중 집계 없음.
- 자체몰 주문(market_id 가 self/빈값)은 카페24 열. 카페24 마켓 통합관리로 들어온 다른 마켓 주문
(스마트스토어·쿠팡 등)은 MARKET_MAP 으로 해당 쇼핑몰 열에 넣는다(환불도 원 주문으로 판단).
MARKET_MAP 에 없는 마켓은 카페24 열 — 전체 합계는 항상 카페24 일별 매출내역과 같다.
네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 카페24 열.
카페24 가 만든 사건은 모두 외부 사건 ID 앞에 "c24:" — 다시 받을 때 이것만 골라 교체하므로
해당 쇼핑몰을 나중에 직접 연동해도 그 데이터는 건드리지 않는다(단, 같은 주문을 양쪽에서 받지 않게
직접 연동을 켜는 쇼핑몰은 MARKET_MAP 에서 빼야 한다).
- 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. orders limit ≤ 1000, refunds limit ≤ 500, offset ≤ 15000.
- 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않는다 — raw 에는 금액·상태 필드만.
- 할인 항목 구성·마켓 주문 포함 여부는 `reconcile()`(설정 화면 "카페24 매출 대조")로 카페24 화면과
대조해 확정한다.
"""
from __future__ import annotations
from datetime import date, timedelta
from decimal import ROUND_HALF_UP, Decimal, InvalidOperation
from typing import Any, Iterable
from .base import (
AdapterContext,
ApiError,
AuthFailed,
MarketplaceAdapter,
NotConfigured,
SaleEvent,
TokenExpired,
)
ORDER_SCOPE = "mall.read_order"
ORDER_LIMIT = 1000
REFUND_LIMIT = 500
LOOKUP_BATCH = 100
MAX_OFFSET = 15000
CHUNK_DAYS = 60
EVENT_PREFIX = "c24:"
# 카페24 자체몰 주문 채널 — market_id 는 외부 마켓만이 아니라 주문 채널·간편결제도 담는다
# (실데이터 확인 2026-09-30: mobile=모바일웹, NCHECKOUT=네이버페이, KAKAOPAY=톡체크아웃).
# 이 주문들은 카페24 자체몰 매출이다. 비교는 소문자로.
SELF_CHANNELS: dict[str, str] = {
"": "자체몰", "self": "자체몰(PC)", "cafe24": "자체몰", "mobile": "모바일웹", "mobile_d": "모바일앱",
"ncheckout": "네이버페이", "kakaopay": "톡체크아웃",
}
# 카페24 마켓 통합관리가 가져온 외부 마켓 주문의 market_id(또는 order_place_id) → 우리 쇼핑몰 열.
# 여기에도 SELF_CHANNELS 에도 없는 채널은 "알 수 없는 채널"로 카페24 열에 남긴다 — 전체 합계는 항상
# 카페24 화면과 같다. 결제수단(네이버페이·카카오페이)과 헷갈릴 수 있는 일반 이름(naver, kakao)은 넣지 않는다.
# 실제 값은 설정 → "카페24 매출 대조"의 주문 채널별 표로 확인해 보탠다.
MARKET_MAP: dict[str, str] = {
"shopn": "naver", "smartstore": "naver", "storefarm": "naver",
"coupang": "coupang",
"sk11st": "elevenst", "11st": "elevenst", "elevenst": "elevenst",
"gmarket": "gmarket",
"lotteon": "lotteon",
"gsshop": "gsshop",
"kakaotalkstore": "kakao", "talkstore": "kakao", "kakaostyle": "kakao",
"ohouse": "ohouse", "todayhouse": "ohouse", "bucketplace": "ohouse",
"tossshopping": "toss",
}
def _key(value: Any) -> str:
return str(value or "").strip().lower()
def channel_kind(market_id: Any, order_place_id: Any = None) -> str:
"""self(자체몰 채널) / market(외부 마켓, 해당 쇼핑몰 열) / unknown(모르는 채널 → 카페24 열)."""
if market_id is None or _key(market_id) in SELF_CHANNELS:
return "self"
if _key(market_id) in MARKET_MAP or _key(order_place_id) in MARKET_MAP:
return "market"
return "unknown"
def target_code(market_id: Any, order_place_id: Any = None) -> str:
"""이 주문을 집계할 쇼핑몰 열. 자체몰 채널·모르는 채널은 카페24."""
if channel_kind(market_id, order_place_id) != "market":
return "cafe24"
return MARKET_MAP.get(_key(market_id)) or MARKET_MAP[_key(order_place_id)]
# 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (initial_order_amount 의 필드)
DISCOUNT_FIELDS = ("membership_discount_amount", "set_product_discount_amount", "app_discount_amount",
"market_other_discount_amount", "shipping_fee_discount_amount")
COUPON_FIELDS = ("coupon_discount_price", "coupon_shipping_fee_amount")
AMOUNT_FIELDS = ("order_price_amount", "shipping_fee", *DISCOUNT_FIELDS, *COUPON_FIELDS,
"points_spent_amount", "credits_spent_amount", "payment_amount")
def _won(value: Any) -> int:
"""카페24 금액 문자열("29000.00") → 원 단위 정수."""
try:
return int(Decimal(str(value or "0")).quantize(Decimal(1), rounding=ROUND_HALF_UP))
except (InvalidOperation, ValueError):
return 0
def _day(value: Any) -> date | None:
""""2018-07-04T11:21:35+09:00" / "2017-07-10 15:55:51" → date (카페24 는 KST 로 준다)."""
s = str(value or "").strip()
if len(s) < 10:
return None
try:
return date.fromisoformat(s[:10])
except ValueError:
return None
def order_amounts(order: dict[str, Any]) -> dict[str, int]:
"""결제 당시 금액(initial_order_amount, 없으면 actual_order_amount) 항목별 원 단위."""
a = order.get("initial_order_amount") or order.get("actual_order_amount") or {}
return {k: _won(a.get(k)) for k in AMOUNT_FIELDS}
def order_total(order: dict[str, Any]) -> int:
"""결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰."""
a = order_amounts(order)
return (a["order_price_amount"] + a["shipping_fee"]
- sum(a[k] for k in DISCOUNT_FIELDS) - sum(a[k] for k in COUPON_FIELDS))
def is_self_market(market_id: Any) -> bool:
"""카페24 자체몰 채널(PC·모바일·네이버페이·톡체크아웃 등)인가."""
return channel_kind(market_id) == "self"
def _chunks(start: date, end: date) -> Iterable[tuple[date, date]]:
s = start
while s <= end:
e = min(end, s + timedelta(days=CHUNK_DAYS - 1))
yield s, e
s = e + timedelta(days=1)
class Cafe24Adapter(MarketplaceAdapter):
code = "cafe24"
name = "카페24"
auth_type = "shared"
implemented = True
replace_range = True
event_prefix = EVENT_PREFIX
docs_url = "https://apidocs.cafe24.com/docs/admin/get-orders"
note = ("카페24 상품관리에서 연결한 OAuth 토큰을 함께 씁니다(여기서 따로 입력하지 않음). "
"주문 읽기 권한이 필요해 권한 추가 후 한 번 다시 연결해야 합니다.")
# ── 연결 ──────────────────────────────────────────────
def is_configured(self, ctx: AdapterContext) -> bool:
return True
def _repo(self, ctx: AdapterContext):
return getattr(ctx.app_state, "cafe24_store", None) if ctx.app_state is not None else None
def shared_status(self, ctx: AdapterContext) -> dict:
from app.integrations.cafe24.config import load_config # 지연 import
from app.integrations.cafe24.tokens import TokenService # 지연 import
repo = self._repo(ctx)
config = load_config()
if repo is None:
return {"connected": False, "missing": config.missing or ["CAFE24_DB_URL"], "needs_reauth": False}
return TokenService(repo, config).status()
def authenticate(self, ctx: AdapterContext) -> None:
st = self.shared_status(ctx)
if not st.get("connected"):
if st.get("missing"):
raise NotConfigured("카페24 연동 환경변수가 설정되지 않았습니다.")
if st.get("needs_reauth") and str(st.get("reason", "")).startswith("refresh"):
raise TokenExpired("카페24 연결이 만료되었습니다. 카페24 상품관리 → 시스템에서 재연결하세요.")
raise AuthFailed("카페24에 연결되어 있지 않습니다. 카페24 상품관리 → 시스템에서 연결하세요.")
if ORDER_SCOPE not in str(st.get("scopes") or ""):
raise AuthFailed("카페24 토큰에 주문 읽기 권한(mall.read_order)이 없습니다. "
"카페24 상품관리 → 시스템에서 다시 연결하세요.")
def _client(self, ctx: AdapterContext):
from app.integrations.cafe24 import build_cafe24_api # 지연 import
return build_cafe24_api(self._repo(ctx)).client
def _get(self, ctx: AdapterContext, path: str, params: dict[str, Any]) -> dict[str, Any]:
from app.integrations.cafe24.errors import ( # 지연 import
Cafe24ApiError,
Cafe24AuthError,
Cafe24ConfigError,
Cafe24RateLimitError,
)
try:
return self._client(ctx).get(path, params=params)
except Cafe24ConfigError as exc:
raise NotConfigured(str(exc)) from None
except Cafe24AuthError as exc:
raise AuthFailed(str(exc)) from None
except Cafe24RateLimitError as exc:
raise ApiError(f"카페24 호출 제한(429): {exc}") from None
except Cafe24ApiError as exc:
status = getattr(exc, "status", None)
if status == 403:
raise AuthFailed(f"카페24 권한 오류(403): {exc}. 주문 권한 추가 후 재연결하세요.") from None
raise ApiError(f"카페24 API 오류({status}): {exc}") from None
def test_connection(self, ctx: AdapterContext) -> str:
from app.timezone import today_kst # noqa: WPS433
self.authenticate(ctx)
today = today_kst().isoformat()
self._get(ctx, "/admin/orders", {"start_date": today, "end_date": today, "date_type": "pay_date", "limit": 1})
return "카페24 연결 정상(주문 조회 권한 확인)."
# ── 조회 ──────────────────────────────────────────────
def _paged(self, ctx: AdapterContext, path: str, key: str, params: dict[str, Any],
limit: int) -> Iterable[dict[str, Any]]:
offset = 0
while True:
if offset > MAX_OFFSET:
raise ApiError(f"카페24 조회 건수가 너무 많습니다({params.get('start_date')}~{params.get('end_date')}). "
"기간을 줄여 다시 시도하세요.")
rows = self._get(ctx, path, {**params, "limit": limit, "offset": offset}).get(key) or []
yield from rows
if len(rows) < limit:
return
offset += limit
def paid_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
for s, e in _chunks(start, end):
yield from self._paged(ctx, "/admin/orders", "orders",
{"start_date": s.isoformat(), "end_date": e.isoformat(),
"date_type": "pay_date", "embed": "items"}, ORDER_LIMIT)
def refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
for s, e in _chunks(start, end):
yield from self._paged(ctx, "/admin/refunds", "refunds",
{"start_date": s.isoformat(), "end_date": e.isoformat(),
"date_type": "refund_date"}, REFUND_LIMIT)
def market_ids(self, ctx: AdapterContext, refunds: list[dict[str, Any]]) -> dict[str, tuple[Any, Any]]:
"""환불의 원 주문 (market_id, order_place_id) — 주문일 60일 구간·100건씩 묶어 조회. 못 찾으면 자체몰."""
pairs = sorted({(_day(r.get("order_date")) or date.min, str(r.get("order_id") or ""))
for r in refunds if r.get("order_id")})
out: dict[str, Any] = {}
i = 0
while i < len(pairs):
first = pairs[i][0]
group = [p for p in pairs[i:i + LOOKUP_BATCH] if (p[0] - first).days < CHUNK_DAYS]
ids = [oid for _, oid in group]
if first != date.min:
params = {"order_id": ",".join(ids), "start_date": first.isoformat(),
"end_date": group[-1][0].isoformat(), "date_type": "order_date", "limit": LOOKUP_BATCH}
for o in self._get(ctx, "/admin/orders", params).get("orders") or []:
out[str(o.get("order_id"))] = (o.get("market_id"), o.get("order_place_id"))
i += len(group)
return out
# ── 수집(어댑터 공통 흐름) ──────────────────────────────
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
yield from self.paid_orders(ctx, start, end)
def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
rows = [r for r in self.refunds(ctx, start, end) if str(r.get("status") or "T") == "T"]
markets = self.market_ids(ctx, rows)
for r in rows:
mid, place = markets.get(str(r.get("order_id")), ("self", None))
yield {**r, "_market_id": mid, "_order_place_id": place}
def normalize_order(self, order: dict[str, Any]) -> list[SaleEvent]:
"""결제 주문 → SALE. 자체몰은 카페24 열, 마켓 연동 주문은 해당 쇼핑몰 열(MARKET_MAP)."""
if order.get("paid") != "T":
return []
pay_day = _day(order.get("payment_date"))
if pay_day is None:
return []
items = order.get("items") or []
names = [str(i.get("product_name") or "") for i in items if i.get("product_name")]
name = names[0] + (f" 외 {len(names) - 1}건" if len(names) > 1 else "") if names else ""
oid = str(order.get("order_id") or "")
target = target_code(order.get("market_id"), order.get("order_place_id"))
return [SaleEvent(
marketplace_code=target,
event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}-PAY", external_order_id=oid,
order_date=_day(order.get("order_date")), payment_date=pay_day, event_date=pay_day,
amount=max(0, order_total(order)), product_name=name,
quantity=sum(int(i.get("quantity") or 0) for i in items), order_status="결제완료",
discount_amount=sum(order_amounts(order)[k] for k in DISCOUNT_FIELDS + COUPON_FIELDS),
raw={"order_id": oid, "market_id": order.get("market_id"), "order_place_id": order.get("order_place_id"),
"items": len(items), **{f"initial_{k}": v for k, v in order_amounts(order).items()}},
)]
def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]:
"""환불 → CANCEL/RETURN(−). 원 주문의 market_id 로 결제와 같은 쇼핑몰 열에 넣는다."""
day = _day(refund.get("refund_date"))
code = str(refund.get("refund_code") or "")
if day is None or not code:
return []
amount = _won(refund.get("actual_refund_amount"))
return [SaleEvent(
marketplace_code=target_code(refund.get("_market_id"), refund.get("_order_place_id")),
event_type="RETURN" if code.upper().startswith("R") else "CANCEL",
external_event_id=f"{EVENT_PREFIX}{code}", external_order_id=str(refund.get("order_id") or ""),
external_line_id=",".join(refund.get("order_item_code") or []),
order_date=_day(refund.get("order_date")), event_date=day, amount=-amount,
quantity=-int(refund.get("quantity") or 0), order_status="환불완료",
raw={"refund_code": code, "order_id": refund.get("order_id"), "status": refund.get("status"),
"actual_refund_amount": refund.get("actual_refund_amount"),
"used_points": refund.get("used_points"), "used_credits": refund.get("used_credits"),
"quantity": refund.get("quantity"), "order_item_code": refund.get("order_item_code")},
)]
# ── 대조(설정 화면 "카페24 매출 대조") ─────────────────
def reconcile(self, ctx: AdapterContext, day: date) -> dict[str, Any]:
"""그날 결제 주문·환불을 항목별로 합산 — 카페24 일별 매출내역과 비교해 규칙을 확정하는 용도.
groups["self"] = 카페24 열(자체몰 채널 + 알 수 없는 채널), groups["market"] = 다른 쇼핑몰 열로 가는
외부 마켓 주문. by_channel = 주문 채널(market_id)별 내역. 개인정보는 담지 않는다.
"""
self.authenticate(ctx)
def empty() -> dict[str, int]:
return {"orders": 0, "items": 0, "lines": 0, **{k: 0 for k in AMOUNT_FIELDS}, "total": 0}
def channel(mid: Any, place: Any) -> dict[str, Any]:
key = "" if mid is None else str(mid)
kind = channel_kind(mid, place)
return by_channel.setdefault(key, {
"market_id": key or "(없음)", "label": SELF_CHANNELS.get(_key(mid), ""), "names": set(),
"kind": kind, "target": target_code(mid, place),
"orders": 0, "total": 0, "refund_count": 0, "refund_amount": 0,
})
groups = {"self": empty(), "market": empty()}
by_channel: dict[str, dict[str, Any]] = {}
unpaid = 0
for o in self.paid_orders(ctx, day, day):
if o.get("paid") != "T":
unpaid += 1
continue
ch = channel(o.get("market_id"), o.get("order_place_id"))
ch["orders"] += 1
ch["total"] += order_total(o)
for n in (o.get("order_place_name"), o.get("order_place_id")):
if n:
ch["names"].add(str(n))
g = groups["self" if ch["target"] == "cafe24" else "market"]
g["orders"] += 1
g["items"] += sum(int(i.get("quantity") or 0) for i in o.get("items") or [])
g["lines"] += len(o.get("items") or [])
for k, v in order_amounts(o).items():
g[k] += v
g["total"] += order_total(o)
rows = [r for r in self.refunds(ctx, day, day) if str(r.get("status") or "T") == "T"]
markets = self.market_ids(ctx, rows)
refunds = {"self": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0},
"market": {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0}}
for r in rows:
mid, place = markets.get(str(r.get("order_id")), ("self", None))
ch = channel(mid, place)
g = refunds["self" if ch["target"] == "cafe24" else "market"]
g["count"] += 1
for k in ("actual_refund_amount", "used_points", "used_credits"):
g[k] += _won(r.get(k))
ch["refund_count"] += 1
ch["refund_amount"] += _won(r.get("actual_refund_amount"))
channels_out = sorted(({**v, "names": sorted(v["names"])} for v in by_channel.values()),
key=lambda v: v["total"], reverse=True)
return {"date": day.isoformat(), "orders": groups, "refunds": refunds, "unpaid_orders": unpaid,
"by_channel": channels_out,
"formula": "결제합계 = 상품구매금액 + 배송비 − 할인(" + ", ".join(DISCOUNT_FIELDS) +
") − 쿠폰(" + ", ".join(COUPON_FIELDS) + ")"}