"""카페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')}). " "기간을 줄여 다시 시도하세요.") ctx.progress.check() # [업데이트 취소]면 여기서 멈춤 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): n = 0 for o in self._paged(ctx, "/admin/orders", "orders", {"start_date": s.isoformat(), "end_date": e.isoformat(), "date_type": "pay_date", "embed": "items"}, ORDER_LIMIT): n += 1 yield o ctx.progress.step(items=n) 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): n = 0 for r in self._paged(ctx, "/admin/refunds", "refunds", {"start_date": s.isoformat(), "end_date": e.isoformat(), "date_type": date_type}, REFUND_LIMIT): n += 1 yield r ctx.progress.step(items=n) 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): scanned = 0 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): scanned += 1 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")), } ctx.progress.step(items=scanned) if not found: return [] lo = start - timedelta(days=REFUND_LOOKAROUND_DAYS) hi = max(end, min(end + timedelta(days=REFUND_LOOKAROUND_DAYS), today_kst())) ctx.progress.add(2 * len(list(_chunks(lo, hi)))) # 환불 목록 대조(완료일·접수일) — 찾은 게 있을 때만 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]]: # 진행 막대: 60일 구간마다 결제 주문 1 + 환불 1 + 환불 없는 취소·반품(취소일·반품완료일) 2 c = len(list(_chunks(start, end))) ctx.progress.plan(c * (2 + len(NO_RECORD_DATE_TYPES)), "구간") 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, # 적립금 사용분은 매출에서 뺀다(2026-10-19 사용자 요청) — 결제합계 − 적립금(points_spent_amount) amount=max(0, order_total(order) - order_amounts(order)["points_spent_amount"]), 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()}, "points": order_amounts(order)["points_spent_amount"], "points_excluded": True}, )] def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]: """환불 → CANCEL/RETURN(−). 원 주문의 market_id 로 결제와 같은 쇼핑몰 열에 넣는다. 금액 = 실제 환불액 + 예치금 환불 — 적립금으로 돌려준 금액은 뺀다(2026-10-19, 결제에서 적립금을 빼므로 앞뒤를 맞춤. 예전 = 카페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 [] points = _won(refund.get("used_points")) amount = refund_total(refund) - points 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"), "points": -points, "points_excluded": True}, )] 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) + ")"}