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:
2026-09-29 16:38:44 +09:00
parent 04a1fddd95
commit 27ee92c0a6
10 changed files with 421 additions and 205 deletions
+168 -116
View File
@@ -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) + ")"}