Files
dbx-main/app/modules/performance/adapters/cafe24.py
T
king b52b182d47 fix(performance): 카페24 마켓 통합관리 미사용 — MARKET_MAP 비우기, "카페24 경유" 표시 제거
이 쇼핑몰은 카페24 마켓 통합관리로 들어오는 매출이 없다(사용자 확인). 설정 화면에
네이버·쿠팡 등 9개 쇼핑몰이 "카페24 경유"로 표시돼 카페24 수집분이 그 열로 가는
것처럼 보였다.

- MARKET_MAP = {} — 카페24로 들어온 주문은 market_id 와 관계없이 카페24 열
  (경로 기능은 남겨 두고, 쓰게 되면 매핑만 넣으면 됨)
- 경로 시험은 테스트용 매핑 주입(_with_markets)으로 유지 + 기본값 비어 있음 테스트
- 문서·대조 안내 문구 갱신

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

755 lines
46 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 의 payment_amount·points_spent_amount·credits_spent_amount + 주문의 naver_point)
"상품구매금액 + 배송비 − 할인 − 쿠폰"은 할인 필드에 안 잡히는 차이(수십~수만 원)가 생겨 쓰지 않는다
(2026-09-23 실데이터: 카페24 1,874,738 = 1,713,128 + 10,110 + 151,500, 상품식은 1,874,800).
네 값이 모두 0인 주문도 0원(카페24와 같음).
환불은 따로 빼므로 취소 후 금액(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 열.
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:"
# 매출 대조 전용 — 클레임 완료 주문 조회 날짜 유형과 "완료" 상태(입금전취소 C47~49 는 결제 전이라 제외)
CLAIM_DATE_TYPES = (("cancel_complete_date", "취소완료"), ("cancel_date", "주문취소일"),
("return_complete_date", "반품완료"), ("exchange_complete_date", "교환완료"))
CLAIM_DONE = frozenset({"C40", "C41", "C42", "C43", "R40", "R41", "R42", "R43", "E40"})
UNPAID_CANCEL = frozenset({"C47", "C48", "C49"})
# 환불 목록(/admin/refunds)에 없는 취소·반품(네이버페이 등) — 카페24 일별 매출 환불합계에는 들어간다(실데이터 확인)
NO_RECORD_DATE_TYPES = ("cancel_date", "return_complete_date")
NO_RECORD_DONE = frozenset({"C40", "C41", "C42", "C43", "R40", "R41", "R42", "R43"})
NO_RECORD_CHANNEL = "ncheckout" # 네이버페이만 — 톡체크아웃·자체몰의 환불 기록 없는 취소는 카페24 환불합계에 없다
REFUND_LOOKAROUND_DAYS = 60
# 카페24 자체몰 주문 채널 — market_id 는 외부 마켓만이 아니라 주문 채널·간편결제도 담는다
# (실데이터 확인 2026-09-30: mobile=모바일웹, NCHECKOUT=네이버페이, KAKAOPAY=톡체크아웃).
# 이 주문들은 카페24 자체몰 매출이다. 비교는 소문자로.
SELF_CHANNELS: dict[str, str] = {
# self 는 PC 전용이 아니다 — 주문경로(order_place_name)가 "PC쇼핑몰"·"모바일웹"으로 나뉘어 섞여 있다(실데이터 확인).
"": "자체몰", "self": "자체몰", "cafe24": "자체몰", "mobile": "모바일웹", "mobile_d": "모바일앱",
"ncheckout": "네이버페이", "kakaopay": "톡체크아웃",
}
# 카페24 마켓 통합관리가 가져온 외부 마켓 주문의 market_id(또는 order_place_id) → 우리 쇼핑몰 열.
# 이 쇼핑몰은 카페24 마켓 통합관리를 쓰지 않는다(2026-09 사용자 확인) — 비워 두어 카페24로 들어온 주문은 모두
# 카페24 열. 나중에 쓰게 되면 대조 화면 "주문 채널별" 표의 market_id 로 확인해 예: {"shopn": "naver"} 처럼 넣는다
# (그 쇼핑몰을 직접 연동한다면 넣지 않는다 — 같은 주문을 두 번 받게 됨). 결제수단과 헷갈리는 이름(naver, kakao) 금지.
MARKET_MAP: dict[str, str] = {}
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)]
# 참고식(상품구매금액 + 배송비 − 할인 − 쿠폰)의 필드 — 결제합계는 PAID_FIELDS + naver_point 로 센다
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")
PAID_FIELDS = ("payment_amount", "points_spent_amount", "credits_spent_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}, "naver_point": _won(order.get("naver_point"))}
def goods_total(w: dict[str, int]) -> int:
"""참고식: 상품구매금액 + 배송비 − 할인 − 쿠폰."""
return (w["order_price_amount"] + w["shipping_fee"]
- sum(w[k] for k in DISCOUNT_FIELDS) - sum(w[k] for k in COUPON_FIELDS))
def _paid_total(w: dict[str, int]) -> int:
"""결제합계 = 실결제금액 + 적립금 + 예치금 + 네이버포인트. 넷 다 0인 주문은 카페24도 0원으로 센다
(9/25 가상계좌·휴대폰 9,900 주문 — 상품식으로 넣으면 그만큼 많아짐)."""
return sum(w[k] for k in PAID_FIELDS) + w["naver_point"]
def order_total(order: dict[str, Any]) -> int:
"""결제합계(결제 당시) — 카페24 일별 매출내역 결제합계와 같은 기준."""
return _paid_total(order_amounts(order))
def refund_total(refund: dict[str, Any]) -> int:
"""환불합계 = 실제 환불액 + 적립금·예치금 환불."""
return _won(refund.get("actual_refund_amount")) + _won(refund.get("used_points")) + _won(refund.get("used_credits"))
def order_total_now(order: dict[str, Any]) -> int:
"""취소·반품 반영 후 현재 결제합계(actual_order_amount). 없으면 결제 당시 금액."""
a = order.get("actual_order_amount") or order.get("initial_order_amount") or {}
return _paid_total({**{k: _won(a.get(k)) for k in AMOUNT_FIELDS}, "naver_point": _won(order.get("naver_point"))})
def is_self_market(market_id: Any) -> bool:
"""카페24 자체몰 채널(PC·모바일·네이버페이·톡체크아웃 등)인가."""
return channel_kind(market_id) == "self"
# 대조 진단 — 이름에 이 말이 들어간 숫자 필드만 합산(계좌·연락처 같은 개인정보 숫자는 이름이 달라 제외)
DIAG_WORDS = ("price", "amount", "discount", "point", "fee", "credit", "mileage", "sale", "benefit", "incentive", "coupon")
def _num(value: Any) -> Decimal | None:
if isinstance(value, bool) or value is None:
return None
try:
d = Decimal(str(value).strip())
except (InvalidOperation, ValueError):
return None
return d if d.is_finite() else None
def money_fields(obj: Any) -> dict[str, int]:
"""dict 의 금액성 숫자 필드(이름에 DIAG_WORDS) → 원 단위. 중첩은 한 단계까지 "부모.자식"."""
out: dict[str, int] = {}
if not isinstance(obj, dict):
return out
for k, v in obj.items():
if isinstance(v, dict):
for k2, v2 in money_fields(v).items():
out[f"{k}.{k2}"] = v2
continue
if not any(w in str(k).lower() for w in DIAG_WORDS):
continue
n = _num(v)
if n is not None:
out[str(k)] = int(n.quantize(Decimal(1), rounding=ROUND_HALF_UP))
return out
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,
date_type: str = "refund_date") -> Iterable[dict[str, Any]]:
"""환불 목록. date_type: refund_date(환불완료일, 기본) / accepted_refund_date(환불접수일)."""
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": date_type}, REFUND_LIMIT)
def claim_items(self, ctx: AdapterContext, day: date) -> dict[str, Any]:
"""그날 취소완료·반품완료·교환완료된 주문의 클레임 품목(대조 전용). 환불 API 에 안 잡히는 건
(네이버페이 취소 등)을 찾기 위한 것. 조회 실패는 errors 에 담고 계속한다. 개인정보 제외."""
items: list[dict[str, Any]] = []
errors: list[str] = []
seen: set[str] = set()
full_cancel_shipping = 0
for date_type, label in CLAIM_DATE_TYPES:
try:
orders = list(self._paged(ctx, "/admin/orders", "orders",
{"start_date": day.isoformat(), "end_date": day.isoformat(),
"date_type": date_type, "embed": "items"}, ORDER_LIMIT))
except ApiError as exc:
errors.append(f"{label}: {exc}")
continue
for o in orders:
oid = str(o.get("order_id") or "")
its = o.get("items") or []
claimed = [i for i in its if str(i.get("order_status") or "")[:1] in ("C", "R", "E")
and str(i.get("order_status") or "") not in UNPAID_CANCEL]
if claimed and len(claimed) == len(its) and oid not in seen and \
all(str(i.get("order_status") or "") in CLAIM_DONE and str(i.get("order_status"))[:1] == "C" for i in its):
full_cancel_shipping += order_amounts(o)["shipping_fee"]
for i in claimed:
key = str(i.get("order_item_code") or f"{oid}-{i.get('item_no')}")
if key in seen:
continue
seen.add(key)
status = str(i.get("order_status") or "")
qty = int(i.get("quantity") or 0)
items.append({
"via": label, "order_id": oid, "item_code": key,
"channel": str(o.get("order_place_name") or o.get("market_id") or ""),
"paid": o.get("paid") == "T", "pay_date": str(o.get("payment_date") or "")[:10],
"status": status, "status_text": str(i.get("status_text") or ""),
"done": status in CLAIM_DONE,
"claim_code": str(i.get("claim_code") or ""),
"product_name": str(i.get("product_name") or "")[:40], "quantity": qty,
"product_amount": (_won(i.get("product_price")) + _won(i.get("option_price"))) * qty,
"payment_amount": _won(i.get("payment_amount")),
"coupon": _won(i.get("coupon_discount_price")),
"naver_pay_claim_status": str(i.get("naver_pay_claim_status") or ""),
"cancel_date": str(i.get("cancel_date") or "")[:16],
"refund_date": str(i.get("refund_date") or "")[:16],
"return_confirmed_date": str(i.get("return_confirmed_date") or "")[:16],
})
seen.add(oid)
return {"items": items, "errors": errors, "full_cancel_shipping": full_cancel_shipping}
def unrefunded_claims(self, ctx: AdapterContext, start: date, end: date) -> list[dict[str, Any]]:
"""환불 목록에 기록이 없는 네이버페이 취소·반품 완료 품목. 날짜 = 품목 취소일(반품은 반품완료일).
금액 = 판매가(+옵션)×수량 − 품목 할인·쿠폰. 주문 전체가 취소·반품되면 배송비(− 배송비 할인·쿠폰)도 환불로
보고 그 주문의 마지막 클레임 품목에 한 번 더한다. 앞뒤 60일 환불 목록(완료일·접수일)에 그 주문이 있으면
제외해 환불 목록 쪽과 두 번 빼지 않는다.
카페24 일별 매출 환불합계와 대조한 결과(2026-09): 네이버페이만 센다 — 톡체크아웃(KAKAOPAY)·자체몰의
환불 기록 없는 취소는 넣지 않는다(9/16 톡체크아웃 취소 9,900 제외, 9/4 네이버페이 전체취소 배송비 3,500 포함)."""
from app.timezone import today_kst # noqa: WPS433
found: dict[str, dict[str, Any]] = {}
for date_type in NO_RECORD_DATE_TYPES:
for s, e in _chunks(start, end):
for o in self._paged(ctx, "/admin/orders", "orders",
{"start_date": s.isoformat(), "end_date": e.isoformat(),
"date_type": date_type, "embed": "items"}, ORDER_LIMIT):
if NO_RECORD_CHANNEL not in (_key(o.get("market_id")), _key(o.get("order_place_id"))):
continue
oid = str(o.get("order_id") or "")
its = o.get("items") or []
claimed: list[tuple[date, str, dict[str, Any]]] = []
for i in its:
status = str(i.get("order_status") or "")
if status not in NO_RECORD_DONE:
continue
keys = (("cancel_date", "refund_date", "return_confirmed_date") if status[:1] == "C"
else ("return_confirmed_date", "refund_date", "cancel_date"))
day = next((d for d in (_day(i.get(k)) for k in keys) if d), None)
if day is not None:
claimed.append((day, str(i.get("order_item_code") or f"{oid}-{i.get('item_no')}"), i))
if not claimed:
continue
all_claimed = len(claimed) == len(its)
w = order_amounts(o)
ship = max(0, w["shipping_fee"] - w["coupon_shipping_fee_amount"] - w["shipping_fee_discount_amount"])
last = max((d, k) for d, k, _ in claimed)
for day, key, i in claimed:
if not (start <= day <= end):
continue
status = str(i.get("order_status") or "")
qty = int(i.get("quantity") or 0)
amount = max(0, (_won(i.get("product_price")) + _won(i.get("option_price"))) * qty
- _won(i.get("additional_discount_price")) - _won(i.get("coupon_discount_price"))
- _won(i.get("app_item_discount_amount")))
ship_refund = ship if all_claimed and (day, key) == last else 0
found[key] = {
"order_id": oid, "item_code": key, "status": status, "day": day,
"market_id": o.get("market_id"), "place_id": o.get("order_place_id"),
"place_name": o.get("order_place_name"), "order_date": _day(o.get("order_date")),
"quantity": qty, "amount": amount + ship_refund, "shipping_refund": ship_refund,
"product_name": str(i.get("product_name") or "")[:40],
"naver_pay_claim_status": str(i.get("naver_pay_claim_status") or ""),
# 대조용 — 주문 전체가 취소·반품됐는지, 그 주문 배송비
"order_all_claimed": all_claimed, "order_shipping_fee": w["shipping_fee"],
"item_payment_amount": _won(i.get("payment_amount")),
"coupon": _won(i.get("coupon_discount_price")),
}
if not found:
return []
lo = start - timedelta(days=REFUND_LOOKAROUND_DAYS)
hi = max(end, min(end + timedelta(days=REFUND_LOOKAROUND_DAYS), today_kst()))
refunded = {str(r.get("order_id") or "") for dt in ("refund_date", "accepted_refund_date")
for r in self.refunds(ctx, lo, hi, dt)}
return [c for c in found.values() if c["order_id"] not in refunded]
def market_ids(self, ctx: AdapterContext, refunds: list[dict[str, Any]]) -> dict[str, tuple[Any, Any, Any]]:
"""환불의 원 주문 (market_id, order_place_id, order_place_name) — 주문일 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"), o.get("order_place_name"))
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, _name = markets.get(str(r.get("order_id")), ("self", None, None))
yield {**r, "_market_id": mid, "_order_place_id": place}
for c in self.unrefunded_claims(ctx, start, end):
yield {**c, "_kind": "claim"}
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 로 결제와 같은 쇼핑몰 열에 넣는다.
금액 = 실제 환불액 + 적립금·예치금 환불(카페24 일별 매출 환불합계와 같음, 실데이터 확인)."""
if refund.get("_kind") == "claim":
return self.normalize_claim(refund)
day = _day(refund.get("refund_date"))
code = str(refund.get("refund_code") or "")
if day is None or not code:
return []
amount = refund_total(refund)
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")},
)]
def normalize_claim(self, c: dict[str, Any]) -> list[SaleEvent]:
"""환불 목록에 없는 취소·반품 품목(네이버페이 등) → CANCEL/RETURN(−), 취소일(반품완료일)."""
if not c.get("amount") or c.get("day") is None:
return []
is_return = str(c.get("status"))[:1] == "R"
return [SaleEvent(
marketplace_code=target_code(c.get("market_id"), c.get("place_id")),
event_type="RETURN" if is_return else "CANCEL",
external_event_id=f"{EVENT_PREFIX}{c['item_code']}-CL", external_order_id=str(c.get("order_id") or ""),
external_line_id=str(c["item_code"]), order_date=c.get("order_date"), event_date=c["day"],
amount=-int(c["amount"]), quantity=-int(c.get("quantity") or 0), product_name=c.get("product_name") or "",
order_status="반품완료" if is_return else "취소완료",
raw={"order_id": c.get("order_id"), "item_code": c["item_code"], "status": c.get("status"),
"market_id": c.get("market_id"), "naver_pay_claim_status": c.get("naver_pay_claim_status"),
"no_refund_record": True},
)]
# ── 대조(설정 화면 "카페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},
"naver_point": 0, "goods_total": 0, "total": 0}
def channel(mid: Any, place: Any, place_name: Any = None) -> dict[str, Any]:
"""(market_id, 주문경로) 한 쌍 = 한 줄. self 안에도 PC쇼핑몰·모바일웹 경로가 섞여 있어 나눠 본다."""
mkey = "" if mid is None else str(mid)
pname = str(place_name or place or "")
kind = channel_kind(mid, place)
return by_channel.setdefault((mkey, pname), {
"market_id": mkey or "(없음)", "place": pname, "place_id": str(place 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,
# 기기 — 주문의 order_from_mobile(T=모바일에서 주문). PC 채널(self)에도 모바일 주문이 섞여 있다.
"pc_orders": 0, "pc_total": 0, "mobile_orders": 0, "mobile_total": 0,
})
groups = {"self": empty(), "market": empty()}
by_channel: dict[str, dict[str, Any]] = {}
by_payment: dict[str, dict[str, Any]] = {} # 결제수단 조합별(카페24 열 주문만)
unpaid = 0
paid_self: dict[str, int] = {} # 그날 결제된 카페24 열 주문 → (결제 당시 − 현재) 금액
reduced: dict[str, dict[str, Any]] = {} # 그중 금액이 줄어든 주문(취소·반품) — 환불 기록과 대조
# 진단 — 어떤 원본 필드가 카페24 화면 열과 맞는지 찾는 용도(결제 주문 전체, 개인정보 제외)
diag = {"order": {}, "initial": {}, "actual": {}, "item": {}}
odd: list[dict[str, Any]] = [] # 판매가×수량 합이 주문 상품금액과 다르거나 100원 단위가 아닌 주문
for o in self.paid_orders(ctx, day, day):
if o.get("paid") != "T":
unpaid += 1
continue
for part, src in (("order", {k: v for k, v in o.items() if not isinstance(v, (dict, list))}),
("initial", o.get("initial_order_amount")), ("actual", o.get("actual_order_amount"))):
for k, v in money_fields(src).items():
diag[part][k] = diag[part].get(k, 0) + v
its = o.get("items") or []
for i in its:
for k, v in money_fields(i).items():
diag["item"][k] = diag["item"].get(k, 0) + v
gross = sum((_won(i.get("product_price")) + _won(i.get("option_price"))) * int(i.get("quantity") or 0) for i in its)
opa = order_amounts(o)["order_price_amount"]
if (gross != opa or opa % 100) and len(odd) < 60:
odd.append({"order_id": str(o.get("order_id") or ""),
"channel": str(o.get("order_place_name") or o.get("market_id") or ""),
"order_price_amount": opa, "items_gross": gross, "total": order_total(o),
"items": [{"code": str(i.get("order_item_code") or ""), "status": str(i.get("order_status") or ""),
"quantity": int(i.get("quantity") or 0),
"fields": {k: v for k, v in money_fields(i).items() if v}} for i in its]})
ch = channel(o.get("market_id"), o.get("order_place_id"), o.get("order_place_name"))
total = order_total(o)
ch["orders"] += 1
ch["total"] += total
dev = "mobile" if str(o.get("order_from_mobile") or "").upper() == "T" else "pc"
ch[f"{dev}_orders"] += 1
ch[f"{dev}_total"] += total
if ch["target"] == "cafe24":
names = [str(n) for n in (o.get("payment_method_name") or o.get("payment_method") or []) if n]
pkey = " + ".join(names) or "(없음)"
pm = by_payment.setdefault(pkey, {"method": pkey, "orders": 0, "total": 0})
pm["orders"] += 1
pm["total"] += total
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["goods_total"] += goods_total(order_amounts(o))
g["total"] += order_total(o)
if ch["target"] == "cafe24":
oid_ = str(o.get("order_id") or "")
paid_self[oid_] = order_total(o) - order_total_now(o)
if paid_self[oid_] > 0:
reduced[oid_] = {
"order_id": oid_, "channel": str(o.get("order_place_name") or o.get("market_id") or ""),
"payment": " + ".join(str(n) for n in (o.get("payment_method_name") or []) if n),
"initial": order_total(o), "now": order_total_now(o), "diff": paid_self[oid_],
"statuses": sorted({f"{i.get('order_status') or ''} {i.get('status_text') or ''}".strip()
for i in o.get("items") or []}),
"naver_pay": sorted({str(i.get("naver_pay_claim_status")) for i in o.get("items") or []
if i.get("naver_pay_claim_status")}),
"claim_dates": sorted({str(i.get(k))[:10] for i in o.get("items") or []
for k in ("cancel_date", "refund_date", "return_confirmed_date")
if i.get(k)}),
"refunded": 0, "refund_dates": [],
}
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 = {k: {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0,
"no_record_count": 0, "no_record": 0, "total": 0} for k in ("self", "market")}
for r in rows:
mid, place, place_name = markets.get(str(r.get("order_id")), ("self", None, None))
ch = channel(mid, place, place_name)
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))
g["total"] += refund_total(r)
ch["refund_count"] += 1
ch["refund_amount"] += refund_total(r)
no_record = self.unrefunded_claims(ctx, day, day)
for c in no_record:
ch = channel(c["market_id"], c["place_id"], c["place_name"])
g = refunds["self" if ch["target"] == "cafe24" else "market"]
g["no_record_count"] += 1
g["no_record"] += c["amount"]
g["total"] += c["amount"]
ch["refund_count"] += 1
ch["refund_amount"] += c["amount"]
channels_out = sorted(({**v, "names": sorted(v["names"])} for v in by_channel.values()),
key=lambda v: v["total"], reverse=True)
# 환불 기준 비교 — 카페24 "환불합계"가 어느 기준인지 확정하는 용도.
# 완료일(refund_date, 완료 T) vs 접수일(accepted_refund_date, 상태 T/F/M 전부)
# 각각 실제 환불액만 / 적립금·예치금 환불 포함
def rsum(items: Iterable[dict[str, Any]]) -> dict[str, int]:
out = {"count": 0, "actual_refund_amount": 0, "used_points": 0, "used_credits": 0}
for x in items:
out["count"] += 1
for k in ("actual_refund_amount", "used_points", "used_credits"):
out[k] += _won(x.get(k))
out["with_points"] = out["actual_refund_amount"] + out["used_points"] + out["used_credits"]
return out
accepted = list(self.refunds(ctx, day, day, "accepted_refund_date"))
status_names = {"T": "환불완료", "F": "환불전", "M": "환불보류"}
refund_basis = {
"completed": rsum(rows),
"accepted_all": rsum(accepted),
"accepted_by_status": [
{"status": s, "label": status_names.get(s, s or "(없음)"),
**rsum(x for x in accepted if str(x.get("status") or "") == s)}
for s in sorted({str(x.get("status") or "") for x in accepted})
],
}
# 환불 건별 목록(완료일 기준 + 접수일 기준, 환불코드로 합침) — 개인정보(이메일·계좌) 제외
extra = markets | self.market_ids(ctx, [a for a in accepted if str(a.get("order_id")) not in markets])
refund_list: dict[str, dict[str, Any]] = {}
for basis, items in (("completed", rows), ("accepted", accepted)):
for x in items:
code = str(x.get("refund_code") or "")
mid, place, place_name = extra.get(str(x.get("order_id")), ("self", None, None))
e = refund_list.setdefault(code, {
"refund_code": code, "order_id": str(x.get("order_id") or ""),
"channel": str(place_name or mid or ""), "status": str(x.get("status") or ""),
"accepted_date": str(x.get("accepted_refund_date") or "")[:16].replace("T", " "),
"refund_date": str(x.get("refund_date") or "")[:16].replace("T", " "),
"quantity": int(x.get("quantity") or 0),
"actual_refund_amount": _won(x.get("actual_refund_amount")),
"used_points": _won(x.get("used_points")), "used_credits": _won(x.get("used_credits")),
"cancel_fee_amount": _won(x.get("cancel_fee_amount")),
"methods": [str(m) for m in (x.get("refund_methods") or []) if m],
"in_completed": False, "in_accepted": False,
})
e["in_" + basis] = True
claims = self.claim_items(ctx, day)
refunded_orders = {r["order_id"] for r in refund_list.values()}
for c in claims["items"]:
c["has_refund"] = c["order_id"] in refunded_orders
def csum(pred) -> dict[str, int]:
sel = [c for c in claims["items"] if c["done"] and pred(c)]
return {"count": len(sel), "payment_amount": sum(c["payment_amount"] for c in sel),
"product_amount": sum(c["product_amount"] for c in sel)}
# 결제일 기준 — 그날 결제된 주문이 그 뒤(오늘까지) 환불된 금액. 카페24 일별 매출이 환불을 원 주문 결제일에
# 빼는지 확인하는 용도(최근일만 맞고 지난 날일수록 차이가 커지는 현상).
from app.timezone import today_kst # noqa: WPS433
later = [x for x in self.refunds(ctx, day, max(day, today_kst()))
if str(x.get("order_id") or "") in paid_self and str(x.get("status") or "T") == "T"]
by_pay = rsum(later)
by_pay["amount_diff"] = sum(v for v in paid_self.values() if v > 0)
by_pay["refund_dates"] = sorted({str(x.get("refund_date") or "")[:10] for x in later})
refund_basis["by_pay_date"] = by_pay
for x in later:
r_ = reduced.get(str(x.get("order_id") or ""))
if r_ is not None:
r_["refunded"] += _won(x.get("actual_refund_amount")) + _won(x.get("used_points")) + _won(x.get("used_credits"))
r_["refund_dates"] = sorted({*r_["refund_dates"], str(x.get("refund_date") or "")[:10]})
comp = refund_basis["completed"]
no_refund = csum(lambda c: not c["has_refund"])
claimed = csum(lambda c: True)
# 카페24 "환불합계" 후보 — 화면 값과 같은 줄을 찾는다(화면에서 값을 입력하면 강조)
candidates = [
{"key": "applied", "label": "적용 규칙 · 환불 목록(실제 + 적립금·예치금) + 환불 목록 없는 취소·반품(네이버페이 등)",
"amount": refunds["self"]["total"] + refunds["market"]["total"]},
{"key": "completed", "label": "환불완료일 · 실제 환불액 (이전 규칙)", "amount": comp["actual_refund_amount"]},
{"key": "completed_pts", "label": "환불완료일 · 실제 환불액 + 적립금·예치금", "amount": comp["with_points"]},
{"key": "pay_date", "label": "결제일 기준 · 그날 결제 주문의 환불(오늘까지) · 실제 환불액",
"amount": by_pay["actual_refund_amount"]},
{"key": "pay_date_pts", "label": "결제일 기준 · 그날 결제 주문의 환불(오늘까지) · 실제 + 적립금·예치금",
"amount": by_pay["with_points"]},
{"key": "pay_date_diff", "label": "결제일 기준 · 그날 결제 주문의 (결제 당시 금액 − 현재 금액)",
"amount": by_pay["amount_diff"]},
{"key": "accepted", "label": "환불접수일(전체 상태) · 실제 환불액", "amount": refund_basis["accepted_all"]["actual_refund_amount"]},
{"key": "accepted_pts", "label": "환불접수일(전체 상태) · 실제 + 적립금·예치금", "amount": refund_basis["accepted_all"]["with_points"]},
{"key": "claim_pay", "label": "취소·반품·교환 완료 품목 · 품목 결제금액", "amount": claimed["payment_amount"]},
{"key": "claim_prod", "label": "취소·반품·교환 완료 품목 · 판매가(+옵션)×수량", "amount": claimed["product_amount"]},
{"key": "claim_pay_ship", "label": "완료 품목 결제금액 + 전체취소 주문 배송비",
"amount": claimed["payment_amount"] + claims["full_cancel_shipping"]},
{"key": "completed_plus_noref", "label": "환불완료 실제 환불액 + 환불 기록 없는 완료 품목 결제금액",
"amount": comp["actual_refund_amount"] + no_refund["payment_amount"]},
{"key": "completed_pts_plus_noref", "label": "환불완료 (실제+적립금) + 환불 기록 없는 완료 품목 결제금액",
"amount": comp["with_points"] + no_refund["payment_amount"]},
]
return {"date": day.isoformat(), "orders": groups, "refunds": refunds, "unpaid_orders": unpaid,
"by_channel": channels_out, "refund_basis": refund_basis,
"refund_list": sorted(refund_list.values(), key=lambda r: r["refund_code"]),
"claims": claims, "refund_candidates": candidates,
"no_record_claims": [{**c, "day": c["day"].isoformat(),
"order_date": c["order_date"].isoformat() if c["order_date"] else None}
for c in no_record],
"reduced_orders": sorted(reduced.values(), key=lambda r: r["diff"] - r["refunded"], reverse=True),
"by_payment": sorted(by_payment.values(), key=lambda v: v["total"], reverse=True),
"diag": {part: dict(sorted(v.items())) for part, v in diag.items()}, "odd_orders": odd,
"formula": "결제합계 = 실결제금액 + 적립금 + 예치금 + 네이버포인트(결제 당시). 참고식 = 상품구매금액 + 배송비 − 할인("
+ ", ".join(DISCOUNT_FIELDS) + ") − 쿠폰(" + ", ".join(COUPON_FIELDS) + ")"}