feat(performance): 카페24 마켓 연동 주문을 해당 쇼핑몰 열로 집계

- 카페24 마켓 통합관리가 가져온 주문(market_id ≠ self)을 MARKET_MAP 으로 네이버·쿠팡·11번가 등 열에
  (SaleEvent.marketplace_code). 연결표에 없는 마켓은 카페24 열 — 전체 합계는 카페24 일별 매출내역과 같음
- 환불도 원 주문의 마켓으로 같은 열에
- 카페24 사건 ID 에 c24: 접두어, 기간 교체는 카페24 열 + 다른 열의 c24: 행만 — 직접 연동분은 보존
- 매출 대조 마켓별 표에 "반영 열", 설정 화면에 "카페24 경유" 표시

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-29 16:54:10 +09:00
parent 4cb37688ed
commit 19396f1745
10 changed files with 156 additions and 61 deletions
+6
View File
@@ -105,6 +105,9 @@ class SaleEvent:
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:
@@ -148,6 +151,9 @@ class MarketplaceAdapter(ABC):
# 쇼핑몰 API 가 "기간 안 결제·환불"을 빠짐없이 돌려줄 때만 켠다 — 규칙이 바뀌거나
# 주문이 사라져도 예전 행이 남지 않는다. False 면 같은 사건 ID 만 덮어쓴다(upsert).
replace_range: bool = False
# replace_range 일 때 이 어댑터가 만든 사건을 가려내는 외부 사건 ID 접두어. 다른 쇼핑몰 열로 보낸
# 사건(marketplace_code 지정)도 이 접두어로 찾아 함께 교체한다 — 그 쇼핑몰의 직접 연동분은 건드리지 않음.
event_prefix: str = ""
note: str = "" # 설정 화면 안내 문구
# ── 설정 ──────────────────────────────────────────────
+53 -15
View File
@@ -13,9 +13,13 @@
실제 환불액(actual_refund_amount). 환불코드가 R 로 시작하면 반품, 그 밖은 취소.
- 수집 기간을 통째로 다시 받는다(replace_range) — 결제·환불 모두 기간 안 날짜로 조회되므로
그 기간의 카페24 실데이터를 지우고 새로 넣는다. 규칙이 바뀌거나 주문이 사라져도 이중 집계 없음.
- 자체몰 주문만(market_id 가 self/빈값). 카페24 로 연동돼 들어온 다른 마켓(스마트스토어·쿠팡 등)
주문은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외(환불도 원 주문의 market_id 로 판단).
네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 포함.
- 자체몰 주문(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 화면과
@@ -45,6 +49,33 @@ LOOKUP_BATCH = 100
MAX_OFFSET = 15000
CHUNK_DAYS = 60
SELF_MARKETS = {"", "self", None}
EVENT_PREFIX = "c24:"
# 카페24 마켓 통합관리가 가져온 주문의 market_id(또는 order_place_id) → 우리 쇼핑몰 열.
# 여기 없는 마켓(예: 옥션·인터파크)은 카페24 열에 남긴다 — 전체 합계는 항상 카페24 화면과 같다.
# 실제 값은 설정 → "카페24 매출 대조"의 마켓별 표(market_id / 주문경로 / 반영 열)로 확인해 보탠다.
MARKET_MAP: dict[str, str] = {
"shopn": "naver", "smartstore": "naver", "storefarm": "naver", "naver": "naver",
"coupang": "coupang",
"sk11st": "elevenst", "11st": "elevenst", "elevenst": "elevenst",
"gmarket": "gmarket",
"lotteon": "lotteon", "lotte": "lotteon",
"gsshop": "gsshop", "gs": "gsshop",
"kakao": "kakao", "kakaotalkstore": "kakao", "talkstore": "kakao", "kakaostyle": "kakao",
"ohouse": "ohouse", "todayhouse": "ohouse", "bucketplace": "ohouse",
"toss": "toss", "tossshopping": "toss",
}
def target_code(market_id: Any, order_place_id: Any = None) -> str:
"""이 주문을 집계할 쇼핑몰 열. 자체몰·모르는 마켓은 카페24."""
if is_self_market(market_id):
return "cafe24"
for key in (market_id, order_place_id):
code = MARKET_MAP.get(str(key or "").strip().lower())
if code:
return code
return "cafe24"
# 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (initial_order_amount 의 필드)
DISCOUNT_FIELDS = ("membership_discount_amount", "set_product_discount_amount", "app_discount_amount",
@@ -104,6 +135,7 @@ class Cafe24Adapter(MarketplaceAdapter):
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 토큰을 함께 씁니다(여기서 따로 입력하지 않음). "
"주문 읽기 권한이 필요해 권한 추가 후 한 번 다시 연결해야 합니다.")
@@ -198,8 +230,8 @@ class Cafe24Adapter(MarketplaceAdapter):
{"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, Any]:
"""환불의 원 주문 market_id — 주문일 60일 구간·100건씩 묶어 조회."""
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] = {}
@@ -212,7 +244,7 @@ class Cafe24Adapter(MarketplaceAdapter):
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")
out[str(o.get("order_id"))] = (o.get("market_id"), o.get("order_place_id"))
i += len(group)
return out
@@ -224,10 +256,12 @@ class Cafe24Adapter(MarketplaceAdapter):
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:
yield {**r, "_market_id": markets.get(str(r.get("order_id")), "self")}
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]:
if not is_self_market(order.get("market_id")) or order.get("paid") != "T":
"""결제 주문 → SALE. 자체몰은 카페24 열, 마켓 연동 주문은 해당 쇼핑몰 열(MARKET_MAP)."""
if order.get("paid") != "T":
return []
pay_day = _day(order.get("payment_date"))
if pay_day is None:
@@ -236,8 +270,10 @@ class Cafe24Adapter(MarketplaceAdapter):
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(
event_type="SALE", external_event_id=f"{oid}-PAY", external_order_id=oid,
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="결제완료",
@@ -247,16 +283,16 @@ class Cafe24Adapter(MarketplaceAdapter):
)]
def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]:
if not is_self_market(refund.get("_market_id")):
return []
"""환불 → 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=code, external_order_id=str(refund.get("order_id") or ""),
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="환불완료",
@@ -287,7 +323,8 @@ class Cafe24Adapter(MarketplaceAdapter):
if not is_self_market(o.get("market_id")):
key = str(o.get("market_id"))
bm = by_market.setdefault(key, {"market_id": key, "names": set(), "orders": 0, "total": 0,
"refund_count": 0, "refund_amount": 0})
"refund_count": 0, "refund_amount": 0,
"target": target_code(o.get("market_id"), o.get("order_place_id"))})
bm["orders"] += 1
bm["total"] += order_total(o)
for n in (o.get("order_place_name"), o.get("order_place_id")):
@@ -305,14 +342,15 @@ class Cafe24Adapter(MarketplaceAdapter):
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 = markets.get(str(r.get("order_id")), "self")
mid, place = markets.get(str(r.get("order_id")), ("self", None))
g = refunds["self" if is_self_market(mid) else "market"]
g["count"] += 1
for k in ("actual_refund_amount", "used_points", "used_credits"):
g[k] += _won(r.get(k))
if not is_self_market(mid):
bm = by_market.setdefault(str(mid), {"market_id": str(mid), "names": set(), "orders": 0, "total": 0,
"refund_count": 0, "refund_amount": 0})
"refund_count": 0, "refund_amount": 0,
"target": target_code(mid, place)})
bm["refund_count"] += 1
bm["refund_amount"] += _won(r.get("actual_refund_amount"))
markets_out = sorted(({**v, "names": sorted(v["names"])} for v in by_market.values()),