fix(performance): 카페24 매출을 카페24 "일별 매출내역" 기준으로(결제합계·환불합계) + 매출 대조 도구
원인: 품목 결제금액(배송비 제외)을 매출로, 취소·반품 완료일의 품목 금액을 환불로 잡아 카페24 화면(결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰, 환불합계 = 환불완료일 실제 환불액)과 달랐다. - SALE: 결제일 기준 주문 단위 결제합계(initial_order_amount — 결제 당시 금액) - CANCEL/RETURN: GET /admin/refunds 환불완료일, 실제 환불액(환불코드 R=반품) - 환불도 원 주문 market_id 로 자체몰만(다른 마켓 연동 주문 제외) - 기간 교체(replace_range): 동기화한 기간의 카페24 실데이터를 지우고 새로 넣음(한 트랜잭션, 테스트 데이터 제외) — 예전 품목 단위 행이 남아 이중 집계되지 않게 - 설정 화면 "카페24 매출 대조": 날짜별로 카페24 화면 열 순서대로 원천 금액 합산(자체몰/마켓 구분, 저장 안 함) Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -5,18 +5,21 @@
|
||||
주문 읽기 권한(mall.read_order)이 필요하다 — config.DEFAULT_SCOPES 에 포함, 권한 추가 후
|
||||
카페24 상품관리 → 시스템에서 한 번 다시 연결해야 한다.
|
||||
|
||||
수집 규칙 (Admin API GET /admin/orders, 문서 버전 2026-09-01 확인)
|
||||
- 결제(SALE): date_type=pay_date(결제일), embed=items. 결제된(paid=T) 주문의 품목마다
|
||||
품목 결제금액(payment_amount — 할인 반영, 배송비 제외)을 매출로. 사건 날짜 = 결제일.
|
||||
- 취소(CANCEL): date_type=cancel_complete_date. 품목 상태 C40~C43(취소완료)만,
|
||||
결제 때와 같은 품목 금액을 음수로. 입금전취소(C47~C49)는 매출이 아니었으므로 제외.
|
||||
- 반품(RETURN): date_type=return_complete_date. 품목 상태 R40~R43(반품완료)만 음수로.
|
||||
부분 반품(0 < claim_quantity < quantity)은 수량 비율로 나눈다.
|
||||
- 교환(E**)은 매출 변화 없음으로 보고 1단계에서는 반영하지 않는다.
|
||||
- 자체몰 주문만(market_id 가 self/빈값). 카페24 로 들어온 다른 마켓(스마트스토어·쿠팡 등)
|
||||
주문은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외한다. 네이버페이 결제는 자체몰 주문이라 포함.
|
||||
- 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. limit 최대 1000, offset 최대 15000.
|
||||
카페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 로 연동돼 들어온 다른 마켓(스마트스토어·쿠팡 등)
|
||||
주문은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외(환불도 원 주문의 market_id 로 판단).
|
||||
네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 포함.
|
||||
- 한 호출 검색기간 3개월 미만 → 60일씩 나눠 요청. orders limit ≤ 1000, refunds limit ≤ 500, offset ≤ 15000.
|
||||
- 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않는다 — raw 에는 금액·상태 필드만.
|
||||
- 할인 항목 구성·마켓 주문 포함 여부는 `reconcile()`(설정 화면 "카페24 매출 대조")로 카페24 화면과
|
||||
대조해 확정한다.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@@ -36,13 +39,20 @@ from .base import (
|
||||
)
|
||||
|
||||
ORDER_SCOPE = "mall.read_order"
|
||||
PAGE_LIMIT = 1000
|
||||
ORDER_LIMIT = 1000
|
||||
REFUND_LIMIT = 500
|
||||
LOOKUP_BATCH = 100
|
||||
MAX_OFFSET = 15000
|
||||
CHUNK_DAYS = 60
|
||||
CANCEL_DONE = {"C40", "C41", "C42", "C43"}
|
||||
RETURN_DONE = {"R40", "R41", "R42", "R43"}
|
||||
SELF_MARKETS = {"", "self", None}
|
||||
|
||||
# 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (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") → 원 단위 정수."""
|
||||
@@ -63,27 +73,29 @@ def _day(value: Any) -> date | None:
|
||||
return None
|
||||
|
||||
|
||||
def item_amount(item: dict[str, Any]) -> int:
|
||||
"""품목 결제금액. payment_amount 가 없으면 (판매가+옵션가)×수량 − 품목 할인으로 계산."""
|
||||
if item.get("payment_amount") not in (None, ""):
|
||||
return _won(item["payment_amount"])
|
||||
qty = int(item.get("quantity") or 0)
|
||||
gross = (_won(item.get("product_price")) + _won(item.get("option_price"))) * qty
|
||||
discounts = (_won(item.get("additional_discount_price")) + _won(item.get("coupon_discount_price"))
|
||||
+ _won(item.get("app_item_discount_amount")))
|
||||
return max(0, gross - discounts)
|
||||
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 _raw(order: dict[str, Any], item: dict[str, Any]) -> dict[str, Any]:
|
||||
"""저장용 원본 — 금액·상태만(개인정보 제외)."""
|
||||
keys = ("order_item_code", "order_status", "status_code", "product_no", "product_code", "variant_code",
|
||||
"product_price", "option_price", "quantity", "claim_quantity", "additional_discount_price",
|
||||
"coupon_discount_price", "app_item_discount_amount", "payment_amount", "claim_code")
|
||||
return {
|
||||
"order_id": order.get("order_id"), "market_id": order.get("market_id"),
|
||||
"order_place_id": order.get("order_place_id"), "paid": order.get("paid"),
|
||||
**{k: item.get(k) for k in keys},
|
||||
}
|
||||
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:
|
||||
return market_id in SELF_MARKETS
|
||||
|
||||
|
||||
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):
|
||||
@@ -91,6 +103,7 @@ class Cafe24Adapter(MarketplaceAdapter):
|
||||
name = "카페24"
|
||||
auth_type = "shared"
|
||||
implemented = True
|
||||
replace_range = True
|
||||
docs_url = "https://apidocs.cafe24.com/docs/admin/get-orders"
|
||||
note = ("카페24 상품관리에서 연결한 OAuth 토큰을 함께 씁니다(여기서 따로 입력하지 않음). "
|
||||
"주문 읽기 권한이 필요해 권한 추가 후 한 번 다시 연결해야 합니다.")
|
||||
@@ -129,7 +142,7 @@ class Cafe24Adapter(MarketplaceAdapter):
|
||||
|
||||
return build_cafe24_api(self._repo(ctx)).client
|
||||
|
||||
def _get(self, ctx: AdapterContext, params: dict[str, Any]) -> dict[str, Any]:
|
||||
def _get(self, ctx: AdapterContext, path: str, params: dict[str, Any]) -> dict[str, Any]:
|
||||
from app.integrations.cafe24.errors import ( # 지연 import
|
||||
Cafe24ApiError,
|
||||
Cafe24AuthError,
|
||||
@@ -138,7 +151,7 @@ class Cafe24Adapter(MarketplaceAdapter):
|
||||
)
|
||||
|
||||
try:
|
||||
return self._client(ctx).get("/admin/orders", params=params)
|
||||
return self._client(ctx).get(path, params=params)
|
||||
except Cafe24ConfigError as exc:
|
||||
raise NotConfigured(str(exc)) from None
|
||||
except Cafe24AuthError as exc:
|
||||
@@ -155,98 +168,137 @@ class Cafe24Adapter(MarketplaceAdapter):
|
||||
from app.timezone import today_kst # noqa: WPS433
|
||||
|
||||
self.authenticate(ctx)
|
||||
today = today_kst()
|
||||
self._get(ctx, {"start_date": today.isoformat(), "end_date": today.isoformat(),
|
||||
"date_type": "pay_date", "limit": 1})
|
||||
today = today_kst().isoformat()
|
||||
self._get(ctx, "/admin/orders", {"start_date": today, "end_date": today, "date_type": "pay_date", "limit": 1})
|
||||
return "카페24 연결 정상(주문 조회 권한 확인)."
|
||||
|
||||
# ── 수집 ──────────────────────────────────────────────
|
||||
def _orders(self, ctx: AdapterContext, start: date, end: date, date_type: str) -> Iterable[dict[str, Any]]:
|
||||
"""기간을 60일씩 나눠 페이지를 넘기며 주문(+items)을 모두 가져온다."""
|
||||
s = start
|
||||
while s <= end:
|
||||
e = min(end, s + timedelta(days=CHUNK_DAYS - 1))
|
||||
offset = 0
|
||||
while True:
|
||||
if offset > MAX_OFFSET:
|
||||
raise ApiError(f"카페24 조회 건수가 너무 많습니다({s}~{e}). 기간을 줄여 다시 시도하세요.")
|
||||
data = self._get(ctx, {"start_date": s.isoformat(), "end_date": e.isoformat(),
|
||||
"date_type": date_type, "embed": "items",
|
||||
"limit": PAGE_LIMIT, "offset": offset})
|
||||
orders = data.get("orders") or []
|
||||
yield from orders
|
||||
if len(orders) < PAGE_LIMIT:
|
||||
break
|
||||
offset += PAGE_LIMIT
|
||||
s = e + timedelta(days=1)
|
||||
# ── 조회 ──────────────────────────────────────────────
|
||||
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, Any]:
|
||||
"""환불의 원 주문 market_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")
|
||||
i += len(group)
|
||||
return out
|
||||
|
||||
# ── 수집(어댑터 공통 흐름) ──────────────────────────────
|
||||
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
|
||||
for o in self._orders(ctx, start, end, "pay_date"):
|
||||
yield {"kind": "paid", "order": o}
|
||||
yield from self.paid_orders(ctx, start, end)
|
||||
|
||||
def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
|
||||
for o in self._orders(ctx, start, end, "cancel_complete_date"):
|
||||
yield {"kind": "cancel", "order": o}
|
||||
for o in self._orders(ctx, start, end, "return_complete_date"):
|
||||
yield {"kind": "return", "order": o}
|
||||
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")}
|
||||
|
||||
@staticmethod
|
||||
def _is_self_order(order: dict[str, Any]) -> bool:
|
||||
return order.get("market_id") in SELF_MARKETS
|
||||
|
||||
def normalize_order(self, raw: dict[str, Any]) -> list[SaleEvent]:
|
||||
order = raw.get("order") or {}
|
||||
if not self._is_self_order(order) or order.get("paid") != "T":
|
||||
def normalize_order(self, order: dict[str, Any]) -> list[SaleEvent]:
|
||||
if not is_self_market(order.get("market_id")) or order.get("paid") != "T":
|
||||
return []
|
||||
pay_day = _day(order.get("payment_date"))
|
||||
if pay_day is None:
|
||||
return []
|
||||
order_id = str(order.get("order_id") or "")
|
||||
events = []
|
||||
for item in order.get("items") or []:
|
||||
code = str(item.get("order_item_code") or "")
|
||||
if not code:
|
||||
continue
|
||||
events.append(SaleEvent(
|
||||
event_type="SALE", external_event_id=f"{code}-S", external_order_id=order_id,
|
||||
external_line_id=code, order_date=_day(order.get("order_date")), payment_date=pay_day,
|
||||
event_date=pay_day, amount=item_amount(item), product_name=str(item.get("product_name") or ""),
|
||||
option_name=str(item.get("option_value") or "") if isinstance(item.get("option_value"), str) else "",
|
||||
quantity=int(item.get("quantity") or 0), order_status=str(item.get("order_status") or ""),
|
||||
raw=_raw(order, item),
|
||||
))
|
||||
return events
|
||||
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 "")
|
||||
return [SaleEvent(
|
||||
event_type="SALE", external_event_id=f"{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, raw: dict[str, Any]) -> list[SaleEvent]:
|
||||
order = raw.get("order") or {}
|
||||
if not self._is_self_order(order):
|
||||
def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]:
|
||||
if not is_self_market(refund.get("_market_id")):
|
||||
return []
|
||||
kind = raw.get("kind")
|
||||
done, ev_type, suffix = (CANCEL_DONE, "CANCEL", "C") if kind == "cancel" else (RETURN_DONE, "RETURN", "R")
|
||||
order_id = str(order.get("order_id") or "")
|
||||
events = []
|
||||
for item in order.get("items") or []:
|
||||
code = str(item.get("order_item_code") or "")
|
||||
status = str(item.get("order_status") or "")
|
||||
if not code or status not in done:
|
||||
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(
|
||||
event_type="RETURN" if code.upper().startswith("R") else "CANCEL",
|
||||
external_event_id=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 일별 매출내역과 비교해 규칙을 확정하는 용도.
|
||||
|
||||
자체몰/다른 마켓을 나눠 합산한다. 개인정보는 담지 않는다.
|
||||
"""
|
||||
self.authenticate(ctx)
|
||||
|
||||
def empty() -> dict[str, int]:
|
||||
return {"orders": 0, "items": 0, "lines": 0, **{k: 0 for k in AMOUNT_FIELDS}, "total": 0}
|
||||
|
||||
groups = {"self": empty(), "market": empty()}
|
||||
unpaid = 0
|
||||
for o in self.paid_orders(ctx, day, day):
|
||||
if o.get("paid") != "T":
|
||||
unpaid += 1
|
||||
continue
|
||||
if kind == "cancel":
|
||||
day = _day(item.get("cancel_date")) or _day(order.get("cancel_date"))
|
||||
else:
|
||||
day = _day(item.get("return_confirmed_date")) or _day(item.get("refund_date"))
|
||||
if day is None:
|
||||
continue
|
||||
amount = item_amount(item)
|
||||
qty = int(item.get("quantity") or 0)
|
||||
claim = int(item.get("claim_quantity") or 0)
|
||||
if kind == "return" and 0 < claim < qty:
|
||||
amount = int((Decimal(amount) * claim / qty).quantize(Decimal(1), rounding=ROUND_HALF_UP))
|
||||
qty = claim
|
||||
events.append(SaleEvent(
|
||||
event_type=ev_type, external_event_id=f"{code}-{suffix}", external_order_id=order_id,
|
||||
external_line_id=code, order_date=_day(order.get("order_date")),
|
||||
payment_date=_day(order.get("payment_date")), event_date=day, amount=-amount,
|
||||
product_name=str(item.get("product_name") or ""), quantity=-qty, order_status=status,
|
||||
raw=_raw(order, item),
|
||||
))
|
||||
return events
|
||||
g = groups["self" if is_self_market(o.get("market_id")) 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:
|
||||
g = refunds["self" if is_self_market(markets.get(str(r.get("order_id")), "self")) else "market"]
|
||||
g["count"] += 1
|
||||
for k in ("actual_refund_amount", "used_points", "used_credits"):
|
||||
g[k] += _won(r.get(k))
|
||||
return {"date": day.isoformat(), "orders": groups, "refunds": refunds, "unpaid_orders": unpaid,
|
||||
"formula": "결제합계 = 상품구매금액 + 배송비 − 할인(" + ", ".join(DISCOUNT_FIELDS) +
|
||||
") − 쿠폰(" + ", ".join(COUPON_FIELDS) + ")"}
|
||||
|
||||
Reference in New Issue
Block a user