From 27ee92c0a69c084ee209ae478a19673c607345d1 Mon Sep 17 00:00:00 2001 From: king Date: Tue, 29 Sep 2026 16:38:44 +0900 Subject: [PATCH] =?UTF-8?q?fix(performance):=20=EC=B9=B4=ED=8E=9824=20?= =?UTF-8?q?=EB=A7=A4=EC=B6=9C=EC=9D=84=20=EC=B9=B4=ED=8E=9824=20"=EC=9D=BC?= =?UTF-8?q?=EB=B3=84=20=EB=A7=A4=EC=B6=9C=EB=82=B4=EC=97=AD"=20=EA=B8=B0?= =?UTF-8?q?=EC=A4=80=EC=9C=BC=EB=A1=9C(=EA=B2=B0=EC=A0=9C=ED=95=A9?= =?UTF-8?q?=EA=B3=84=C2=B7=ED=99=98=EB=B6=88=ED=95=A9=EA=B3=84)=20+=20?= =?UTF-8?q?=EB=A7=A4=EC=B6=9C=20=EB=8C=80=EC=A1=B0=20=EB=8F=84=EA=B5=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 원인: 품목 결제금액(배송비 제외)을 매출로, 취소·반품 완료일의 품목 금액을 환불로 잡아 카페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 --- app/modules/performance/adapters/base.py | 4 + app/modules/performance/adapters/cafe24.py | 284 +++++++++++------- app/modules/performance/db.py | 55 ++-- app/modules/performance/router.py | 10 + app/modules/performance/sync.py | 22 +- .../templates/performance/index.html | 2 +- .../templates/performance/settings.html | 13 +- .../performance/tests/test_performance.py | 154 ++++++---- app/static/performance.js | 54 ++++ docs/PERFORMANCE_MODULE.md | 28 +- 10 files changed, 421 insertions(+), 205 deletions(-) diff --git a/app/modules/performance/adapters/base.py b/app/modules/performance/adapters/base.py index 15e2396..a7e6328 100644 --- a/app/modules/performance/adapters/base.py +++ b/app/modules/performance/adapters/base.py @@ -144,6 +144,10 @@ class MarketplaceAdapter(ABC): auth_type: str = "api_key" # api_key / oauth / shared(공통 연동 계층 재사용) docs_url: str = "" implemented: bool = False # 실제 수집(fetch)이 구현됐는가 + # True 면 동기화 때 그 기간(sales_date)의 이 쇼핑몰 실데이터를 지우고 새로 넣는다(한 트랜잭션). + # 쇼핑몰 API 가 "기간 안 결제·환불"을 빠짐없이 돌려줄 때만 켠다 — 규칙이 바뀌거나 + # 주문이 사라져도 예전 행이 남지 않는다. False 면 같은 사건 ID 만 덮어쓴다(upsert). + replace_range: bool = False note: str = "" # 설정 화면 안내 문구 # ── 설정 ────────────────────────────────────────────── diff --git a/app/modules/performance/adapters/cafe24.py b/app/modules/performance/adapters/cafe24.py index 85cc105..7db0708 100644 --- a/app/modules/performance/adapters/cafe24.py +++ b/app/modules/performance/adapters/cafe24.py @@ -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) + ")"} diff --git a/app/modules/performance/db.py b/app/modules/performance/db.py index 4d7956a..5c00b60 100644 --- a/app/modules/performance/db.py +++ b/app/modules/performance/db.py @@ -215,7 +215,43 @@ class PerformanceDBStore: # ════════════════════════════════════════════════════════════ def upsert_events(self, code: str, events: Iterable[dict[str, Any]], *, is_sample: bool = False) -> int: """같은 (쇼핑몰, 사건 종류, 외부 사건 ID)는 덮어쓴다 — 여러 번 동기화해도 중복 없음.""" - sql = """ + rows = self._event_rows(code, events, is_sample) + if not rows: + return 0 + with self._pool.connection() as conn: + with conn.transaction(): + with conn.cursor() as cur: + cur.executemany(self._UPSERT_SQL, rows) + return len(rows) + + def replace_events(self, code: str, start: date, end: date, events: Iterable[dict[str, Any]]) -> int: + """기간(sales_date) 안 이 쇼핑몰 실데이터(is_sample 아님)를 지우고 새로 넣는다 — 한 트랜잭션. + 테스트 데이터는 건드리지 않는다. 실패하면 롤백되어 예전 데이터가 그대로 남는다.""" + rows = self._event_rows(code, events, False) + with self._pool.connection() as conn: + with conn.transaction(): + conn.execute( + "DELETE FROM perf_sales_events WHERE marketplace_code = %s AND is_sample = FALSE " + "AND sales_date BETWEEN %s AND %s", + (code, start, end), + ) + if rows: + with conn.cursor() as cur: + cur.executemany(self._UPSERT_SQL, rows) + return len(rows) + + @staticmethod + def _event_rows(code: str, events: Iterable[dict[str, Any]], is_sample: bool) -> list[tuple]: + return [ + (code, e["event_type"], e["external_event_id"], e["external_order_id"], e.get("external_line_id", ""), + e.get("order_date"), e.get("payment_date"), e["event_date"], e["sales_date"], + e.get("product_name", ""), e.get("option_name", ""), int(e.get("quantity") or 0), + int(e["amount"]), int(e.get("discount_amount") or 0), e.get("order_status", ""), + Jsonb(e.get("raw") or {}), is_sample) + for e in events + ] + + _UPSERT_SQL = """ INSERT INTO perf_sales_events (marketplace_code, event_type, external_event_id, external_order_id, external_line_id, order_date, payment_date, event_date, sales_date, product_name, option_name, quantity, @@ -229,22 +265,7 @@ class PerformanceDBStore: quantity = EXCLUDED.quantity, amount = EXCLUDED.amount, discount_amount = EXCLUDED.discount_amount, order_status = EXCLUDED.order_status, raw_data = EXCLUDED.raw_data, is_sample = EXCLUDED.is_sample, synced_at = now() - """ - rows = [ - (code, e["event_type"], e["external_event_id"], e["external_order_id"], e.get("external_line_id", ""), - e.get("order_date"), e.get("payment_date"), e["event_date"], e["sales_date"], - e.get("product_name", ""), e.get("option_name", ""), int(e.get("quantity") or 0), - int(e["amount"]), int(e.get("discount_amount") or 0), e.get("order_status", ""), - Jsonb(e.get("raw") or {}), is_sample) - for e in events - ] - if not rows: - return 0 - with self._pool.connection() as conn: - with conn.transaction(): - with conn.cursor() as cur: - cur.executemany(sql, rows) - return len(rows) + """ def daily_amounts(self, start: date, end: date, codes: list[str]) -> dict[tuple[date, str], int]: if not codes: diff --git a/app/modules/performance/router.py b/app/modules/performance/router.py index 479905d..bfdf077 100644 --- a/app/modules/performance/router.py +++ b/app/modules/performance/router.py @@ -270,6 +270,16 @@ def api_test_connection(request: Request, code: str, payload: dict[str, Any] = B return JSONResponse(result) +@router.get("/api/marketplaces/{code}/reconcile") +def api_reconcile(request: Request, code: str, date_: str = Query(..., alias="date")) -> JSONResponse: + """쇼핑몰 화면(예: 카페24 일별 매출내역)과 비교용 — 그날 원천 금액 항목별 합계. DB 는 바꾸지 않는다.""" + store, user = common.require_store(request, admin=True) + _code_or_404(store, code) + day = _parse_date(date_) + _, sync = common.services(request, store) + return JSONResponse(sync.reconcile(code, day, user=user["email"])) + + @router.post("/api/sample-data") def api_sample_data(request: Request, payload: dict[str, Any] = Body(...)) -> JSONResponse: store, _ = common.require_store(request, admin=True) diff --git a/app/modules/performance/sync.py b/app/modules/performance/sync.py index da95b1c..0551445 100644 --- a/app/modules/performance/sync.py +++ b/app/modules/performance/sync.py @@ -107,7 +107,13 @@ class SyncService: ctx = self._ctx(adapter, user=user) fetched, events = adapter.collect(ctx, start, end) known = ctx.credentials.known_secrets() - upserted = self._store.upsert_events(code, (event_row(ev, known) for ev in events)) + rows = [event_row(ev, known) for ev in events] + if adapter.replace_range: + # 그 기간을 통째로 다시 받은 쇼핑몰 — 기간 안 예전 행을 지우고 새로 넣는다(한 트랜잭션). + rows = [r for r in rows if start <= r["sales_date"] <= end] + upserted = self._store.replace_events(code, start, end, rows) + else: + upserted = self._store.upsert_events(code, rows) self._store.finish_run(run_id, ok=True, fetched=fetched, upserted=upserted) self._store.record_sync(code, status="ok", ok=True) return {**result, "ok": True, "status": "ok", "fetched": fetched, "upserted": upserted, @@ -127,6 +133,20 @@ class SyncService: targets = [a.code for a in all_adapters() if a.code in enabled and (not codes or a.code in codes)] return [self.sync_marketplace(c, start, end, trigger=trigger, user=user) for c in targets] + # ── 쇼핑몰 화면과 대조 ──────────────────────────────── + def reconcile(self, code: str, day: date, *, user: str = "") -> dict[str, Any]: + """어댑터가 지원하면(reconcile) 그날 원천 금액을 항목별로 합산해 돌려준다. DB 는 바꾸지 않는다.""" + adapter = get_adapter(code) + if adapter is None or not hasattr(adapter, "reconcile"): + return {"ok": False, "message": "이 쇼핑몰은 대조 기능을 지원하지 않습니다."} + ctx = None + try: + ctx = self._ctx(adapter, user=user) + return {"ok": True, **adapter.reconcile(ctx, day)} + except Exception as exc: # noqa: BLE001 + status, message = self._failure(exc, ctx) + return {"ok": False, "status": status, "label": STATUS_LABELS.get(status, status), "message": message} + # ── 테스트(모의) 데이터 ──────────────────────────────── def generate_samples(self, start: date, end: date, codes: list[str]) -> int: from .adapters import mock # noqa: WPS433 diff --git a/app/modules/performance/templates/performance/index.html b/app/modules/performance/templates/performance/index.html index 1ba74ca..c1f3341 100644 --- a/app/modules/performance/templates/performance/index.html +++ b/app/modules/performance/templates/performance/index.html @@ -235,4 +235,4 @@ } | tojson }} {% endblock %} -{% block scripts %}{% endblock %} +{% block scripts %}{% endblock %} diff --git a/app/modules/performance/templates/performance/settings.html b/app/modules/performance/templates/performance/settings.html index 3dc985b..572675e 100644 --- a/app/modules/performance/templates/performance/settings.html +++ b/app/modules/performance/templates/performance/settings.html @@ -115,6 +115,17 @@ +
+

카페24 매출 대조

+

카페24 관리자 → 통계 → 일별 매출내역과 같은 날짜를 비교합니다. 그날 결제 주문과 환불을 카페24 API 에서 + 바로 합산하며(저장하지 않음), 자체몰과 다른 마켓 연동 주문을 나눠 보여 줍니다.

+
+ + +
+
+
+

테스트 데이터

현재 {{ "{:,}".format(sample_count) }}건
@@ -131,4 +142,4 @@ {% endblock %} -{% block scripts %}{% endblock %} +{% block scripts %}{% endblock %} diff --git a/app/modules/performance/tests/test_performance.py b/app/modules/performance/tests/test_performance.py index 21d494b..1365cae 100644 --- a/app/modules/performance/tests/test_performance.py +++ b/app/modules/performance/tests/test_performance.py @@ -245,6 +245,11 @@ class FakeStore: def record_test(self, code, *, status, ok, error=""): self.status[code] = {"status": status, "ok": ok, "error": error, "test": True} + def replace_events(self, code, start, end, events): + self.events = {k: v for k, v in self.events.items() + if not (k[0] == code and not v["is_sample"] and start <= v["sales_date"] <= end)} + return self.upsert_events(code, events) + def upsert_events(self, code, events, *, is_sample=False): n = 0 for e in events: @@ -379,88 +384,123 @@ def test_not_implemented_and_mock(): # ════════════════════════════════════════════════════════════ -# 카페24 어댑터(가짜 API 응답) +# 카페24 어댑터(가짜 API 응답) — 카페24 "일별 매출내역" 기준 # ════════════════════════════════════════════════════════════ -def _c24_item(code, status="N40", price="30000.00", qty=1, pay="29000.00", **kw): - return {"order_item_code": code, "order_status": status, "product_name": "냄비", "option_value": "", - "product_price": price, "option_price": "0.00", "quantity": qty, "payment_amount": pay, - "coupon_discount_price": "1000.00", "claim_quantity": 0, **kw} +def _c24_order(oid, market="self", paid="T", price=50_000, ship=3_000, coupon=5_000, member=1_000, items=2, **kw): + amt = {"order_price_amount": f"{price}.00", "shipping_fee": f"{ship}.00", "coupon_discount_price": f"{coupon}.00", + "membership_discount_amount": f"{member}.00", "points_spent_amount": "0.00", "payment_amount": "0.00"} + return {"order_id": oid, "market_id": market, "paid": paid, "order_date": "2026-09-28T10:00:00+09:00", + "payment_date": "2026-09-29T11:21:35+09:00", "buyer_name": "홍길동", "receiver_address": "서울시", + "bank_account_no": "1234567890", "initial_order_amount": amt, + "actual_order_amount": {**amt, "order_price_amount": "0.00"}, # 취소 후 금액은 쓰지 않는다 + "items": [{"order_item_code": f"{oid}-{i:02d}", "product_name": f"상품{i}", "quantity": 1} + for i in range(1, items + 1)], **kw} -def _c24_order(oid, items, market="self", paid="T", **kw): - return {"order_id": oid, "market_id": market, "paid": paid, "order_date": "2026-09-27T10:00:00+09:00", - "payment_date": "2026-09-28T11:21:35+09:00", "buyer_name": "홍길동", "receiver_address": "서울시", - "bank_account_no": "1234567890", "items": items, **kw} +def _c24_refund(code, oid, amount, status="T", order_date="2026-09-20T09:00:00+09:00"): + return {"refund_code": code, "order_id": oid, "order_date": order_date, "refund_date": "2026-09-29T17:31:50+09:00", + "actual_refund_amount": f"{amount}.00", "used_points": "0.00", "used_credits": "0.00", "quantity": 1, + "order_item_code": [f"{oid}-01"], "status": status, "refund_bank_account_no": "1234567890"} class _FakeCafe24(__import__("app.modules.performance.adapters.cafe24", fromlist=["Cafe24Adapter"]).Cafe24Adapter): - def __init__(self, pages): - self.pages = pages # date_type → [응답 orders 목록(페이지별)] + def __init__(self, orders_pages, refunds_pages=(), lookup=None): + self.orders_pages = orders_pages # 결제일 조회 페이지들 + self.refunds_pages = list(refunds_pages) + self.lookup = lookup or {} # order_id → market_id (환불 원 주문 조회) self.calls = [] def authenticate(self, ctx): return None - def _get(self, ctx, params): - self.calls.append(params) - pages = self.pages.get(params["date_type"], []) - idx = params.get("offset", 0) // 1000 - return {"orders": pages[idx] if idx < len(pages) else []} + def _get(self, ctx, path, params): + self.calls.append((path, params)) + idx = params.get("offset", 0) // max(1, params.get("limit", 1)) + if path == "/admin/refunds": + return {"refunds": self.refunds_pages[idx] if idx < len(self.refunds_pages) else []} + if params.get("date_type") == "order_date": # 원 주문 market_id 조회 + ids = params["order_id"].split(",") + return {"orders": [{"order_id": i, "market_id": self.lookup.get(i, "self")} for i in ids]} + return {"orders": self.orders_pages[idx] if idx < len(self.orders_pages) else []} -def test_cafe24_normalize(): - from app.modules.performance.adapters.cafe24 import Cafe24Adapter, item_amount +def test_cafe24_normalize_matches_daily_report(): + from app.modules.performance.adapters.base import AdapterContext + from app.modules.performance.adapters.cafe24 import order_total - paid = _c24_order("20260928-01", [_c24_item("20260928-01-01"), _c24_item("20260928-01-02", pay="10000.00")]) - market = _c24_order("20260928-02", [_c24_item("20260928-02-01")], market="shopn") # 스마트스토어 연동 주문 - unpaid = _c24_order("20260928-03", [_c24_item("20260928-03-01", status="N00")], paid="F") - canceled = _c24_order("20260928-01", [ - _c24_item("20260928-01-01", status="C40", cancel_date="2026-09-29 09:00:00"), - _c24_item("20260928-01-02", status="N40")]) - precancel = _c24_order("20260928-04", [_c24_item("20260928-04-01", status="C48", cancel_date="2026-09-29 09:00:00")]) - returned = _c24_order("20260928-05", [_c24_item("20260928-05-01", status="R40", qty=3, pay="90000.00", - claim_quantity=1, return_confirmed_date="2026-09-30 10:00:00")]) - fake = _FakeCafe24({"pay_date": [[paid, market, unpaid]], - "cancel_complete_date": [[canceled, precancel]], - "return_complete_date": [[returned]]}) - ctx = __import__("app.modules.performance.adapters.base", fromlist=["AdapterContext"]).AdapterContext( - code="cafe24", credentials=None) - fetched, events = fake.collect(ctx, date(2026, 9, 23), date(2026, 9, 30)) - by = {(e.event_type, e.external_line_id): e for e in events} - assert fetched == 6 - assert by[("SALE", "20260928-01-01")].amount == 29_000 and by[("SALE", "20260928-01-02")].amount == 10_000 - assert by[("SALE", "20260928-01-01")].event_date == date(2026, 9, 28) # 결제일 - assert ("SALE", "20260928-02-01") not in by and ("SALE", "20260928-03-01") not in by # 마켓 주문·미결제 제외 - c = by[("CANCEL", "20260928-01-01")] - assert c.amount == -29_000 and c.event_date == date(2026, 9, 29) and c.external_event_id == "20260928-01-01-C" - assert ("CANCEL", "20260928-01-02") not in by and ("CANCEL", "20260928-04-01") not in by # 미취소·입금전취소 제외 - r = by[("RETURN", "20260928-05-01")] - assert r.amount == -30_000 and r.quantity == -1 and r.event_date == date(2026, 9, 30) # 3개 중 1개 반품 + ctx = AdapterContext(code="cafe24", credentials=None) + fake = _FakeCafe24( + [[_c24_order("A"), _c24_order("B", market="shopn"), _c24_order("C", paid="F")]], + [[_c24_refund("C20260929-01", "A", 12_610), _c24_refund("R20260929-02", "X", 20_000), + _c24_refund("C20260929-03", "M", 9_000), _c24_refund("C20260929-04", "A", 5_000, status="F")]], + lookup={"M": "shopn"}, + ) + fetched, events = fake.collect(ctx, date(2026, 9, 29), date(2026, 9, 29)) + by = {(e.event_type, e.external_event_id): e for e in events} + # 결제합계 = 상품구매금액 + 배송비 − 할인 − 쿠폰 (결제 당시 금액) + sale = by[("SALE", "A-PAY")] + assert sale.amount == 50_000 + 3_000 - 1_000 - 5_000 == 47_000 + assert sale.event_date == date(2026, 9, 29) and sale.quantity == 2 and sale.product_name == "상품1 외 1건" + assert not any(e.external_order_id in ("B", "C") and e.event_type == "SALE" for e in events) # 마켓·미결제 제외 + # 환불: 환불완료일, 실제 환불액, R→반품 / 그 밖→취소, 마켓 주문·미완료 환불 제외 + assert by[("CANCEL", "C20260929-01")].amount == -12_610 + assert by[("RETURN", "R20260929-02")].amount == -20_000 + assert ("CANCEL", "C20260929-03") not in by and ("CANCEL", "C20260929-04") not in by + assert by[("CANCEL", "C20260929-01")].event_date == date(2026, 9, 29) for e in events: - assert "buyer_name" not in e.raw and "receiver_address" not in e.raw and "bank_account_no" not in e.raw - # 금액: payment_amount 없으면 (판매가+옵션)×수량 − 할인 - assert item_amount({"product_price": "10000.00", "option_price": "500.00", "quantity": 2, - "coupon_discount_price": "1000.00"}) == 20_000 + assert "buyer_name" not in str(e.raw) and "1234567890" not in str(e.raw) # 개인정보 미저장 + assert order_total({"initial_order_amount": {"order_price_amount": "1578300.00", "shipping_fee": "45500.00", + "coupon_discount_price": "57000.00"}}) == 1_566_800 # 9/29 화면값 + # 대조: 자체몰/마켓 나눠 합산 + rec = fake.reconcile(ctx, date(2026, 9, 29)) + assert rec["orders"]["self"]["orders"] == 1 and rec["orders"]["self"]["total"] == 47_000 + assert rec["orders"]["market"]["orders"] == 1 and rec["unpaid_orders"] == 1 + assert rec["refunds"]["self"]["actual_refund_amount"] == 32_610 and rec["refunds"]["market"]["count"] == 1 # 60일 단위 분할 + 페이지 넘김(1000건이면 다음 페이지) - page1 = [_c24_order(f"x-{i}", []) for i in range(1000)] - fake2 = _FakeCafe24({"pay_date": [page1, [paid]]}) - got = list(fake2.fetch_orders(ctx, date(2026, 7, 1), date(2026, 9, 30))) - pay_calls = [c for c in fake2.calls if c["date_type"] == "pay_date"] + page1 = [_c24_order(f"x-{i}") for i in range(1000)] + fake2 = _FakeCafe24([page1, [_c24_order("y")]]) + got = list(fake2.paid_orders(ctx, date(2026, 7, 1), date(2026, 9, 30))) + calls = [p for path, p in fake2.calls if path == "/admin/orders"] assert len(got) == 2002 # 60일 구간 2개 × (1000건 페이지 + 다음 페이지 1건) - assert pay_calls[0]["start_date"] == "2026-07-01" and pay_calls[0]["end_date"] == "2026-08-29" - assert pay_calls[1]["offset"] == 1000 and all(c["limit"] == 1000 and c["embed"] == "items" for c in pay_calls) - assert any(c["start_date"] == "2026-08-30" for c in pay_calls) - # 주문 권한 없는 토큰 → 인증 실패(재연결 안내) + assert calls[0]["start_date"] == "2026-07-01" and calls[0]["end_date"] == "2026-08-29" + assert calls[1]["offset"] == 1000 and all(c["limit"] == 1000 and c["date_type"] == "pay_date" for c in calls) + + +def test_cafe24_scope_and_replace_range(): + import app.modules.performance.sync as syncmod + from app.modules.performance.adapters.base import AdapterContext + from app.modules.performance.adapters.cafe24 import Cafe24Adapter + + ctx = AdapterContext(code="cafe24", credentials=None) real = Cafe24Adapter() - real.shared_status = lambda ctx: {"connected": True, "scopes": "mall.read_product,mall.write_product"} + real.shared_status = lambda c: {"connected": True, "scopes": "mall.read_product,mall.write_product"} try: real.authenticate(ctx) except AuthFailed as exc: assert "mall.read_order" in exc.message else: raise AssertionError("주문 권한 없으면 인증 실패여야 합니다") - real.shared_status = lambda ctx: {"connected": True, "scopes": "mall.read_product,mall.read_order"} + real.shared_status = lambda c: {"connected": True, "scopes": "mall.read_product,mall.read_order"} real.authenticate(ctx) + # 기간 교체: 그 기간의 예전 실데이터(품목 단위 등)는 지우고, 테스트 데이터·기간 밖은 남긴다 + st = FakeStore() + st.upsert_events("cafe24", [{"event_type": "SALE", "external_event_id": "old-item-S", "external_order_id": "A", + "event_date": date(2026, 9, 29), "sales_date": date(2026, 9, 29), "amount": 1}]) + st.upsert_events("cafe24", [{"event_type": "SALE", "external_event_id": "outside", "external_order_id": "Z", + "event_date": date(2026, 9, 1), "sales_date": date(2026, 9, 1), "amount": 1}]) + st.upsert_events("cafe24", [{"event_type": "SALE", "external_event_id": "sample", "external_order_id": "S", + "event_date": date(2026, 9, 29), "sales_date": date(2026, 9, 29), "amount": 1}], + is_sample=True) + fake = _FakeCafe24([[_c24_order("A")]]) + orig = syncmod.get_adapter + syncmod.get_adapter = lambda c: fake + try: + r = SyncService(st, CredentialService(st, lambda: ring())).sync_marketplace( + "cafe24", date(2026, 9, 29), date(2026, 9, 29)) + finally: + syncmod.get_adapter = orig + ids = {k[2] for k in st.events if k[0] == "cafe24"} + assert r["ok"] and ids == {"A-PAY", "outside", "sample"}, ids def test_registry_and_event_validation(): diff --git a/app/static/performance.js b/app/static/performance.js index 2be3082..6922482 100644 --- a/app/static/performance.js +++ b/app/static/performance.js @@ -470,6 +470,60 @@ } finally { btn.disabled = false; btn.textContent = label; } } + // ── 카페24 매출 대조 — 카페24 "일별 매출내역" 열 순서대로 ── + const recon = document.getElementById("perf-recon"); + if (recon) recon.addEventListener("click", async function () { + const day = document.getElementById("perf-recon-date").value; + const out = document.getElementById("perf-recon-result"); + if (!day) return; + recon.disabled = true; + out.innerHTML = '

카페24에서 불러오는 중…

'; + try { + const r = await api("GET", "/performance/api/marketplaces/cafe24/reconcile?date=" + encodeURIComponent(day)); + if (!r.ok) { out.innerHTML = '

' + esc((r.label ? r.label + " — " : "") + r.message) + "

"; return; } + const s = r.orders.self, m = r.orders.market, rs = r.refunds.self, rm = r.refunds.market; + const disc = ["membership_discount_amount", "set_product_discount_amount", "app_discount_amount", + "market_other_discount_amount", "shipping_fee_discount_amount"]; + const coup = ["coupon_discount_price", "coupon_shipping_fee_amount"]; + const LABEL = { + membership_discount_amount: "회원할인", set_product_discount_amount: "세트상품할인", app_discount_amount: "앱할인", + market_other_discount_amount: "마켓 기타할인", shipping_fee_discount_amount: "배송비할인", + coupon_discount_price: "상품쿠폰", coupon_shipping_fee_amount: "배송비쿠폰", + }; + const sum = function (g, keys) { return keys.reduce(function (a, k) { return a + (g[k] || 0); }, 0); }; + const rows = [ + ["주문수", s.orders, m.orders, "cnt"], ["품목수(수량 합계)", s.items, m.items, "cnt"], ["품목수(품목 줄 수)", s.lines, m.lines, "cnt"], + ["상품구매금액", s.order_price_amount, m.order_price_amount], ["배송비", s.shipping_fee, m.shipping_fee], + ["할인 합계", sum(s, disc), sum(m, disc)], + ].concat(disc.map(function (k) { return [" · " + LABEL[k], s[k], m[k], "sub"]; })) + .concat([["쿠폰 합계", sum(s, coup), sum(m, coup)]]) + .concat(coup.map(function (k) { return [" · " + LABEL[k], s[k], m[k], "sub"]; })) + .concat([ + ["결제합계(계산)", s.total, m.total, "key"], + [" 참고: 실결제금액", s.payment_amount, m.payment_amount, "sub"], + [" 참고: 적립금 사용", s.points_spent_amount, m.points_spent_amount, "sub"], + [" 참고: 예치금 사용", s.credits_spent_amount, m.credits_spent_amount, "sub"], + ["환불 건수", rs.count, rm.count, "cnt"], + ["환불합계(실제 환불액)", rs.actual_refund_amount, rm.actual_refund_amount, "key"], + [" 참고: 환불 적립금", rs.used_points, rm.used_points, "sub"], + [" 참고: 환불 예치금", rs.used_credits, rm.used_credits, "sub"], + ["순매출(결제합계 − 환불합계)", s.total - rs.actual_refund_amount, m.total - rm.actual_refund_amount, "key"], + ]); + out.innerHTML = '" + + rows.map(function (x) { + const cls = x[3] === "key" ? ' class="perf-row-week"' : ""; + const f = function (v) { return x[3] === "cnt" ? fmt(v) : won(v); }; + return ""; + }).join("") + "
' + esc(r.date) + + "자체몰(실적 반영)다른 마켓 연동(제외)
' + esc(x[0]) + + '' + f(x[1]) + '' + f(x[2]) + "
" + + '

' + esc(r.formula) + ". 미결제 주문 " + fmt(r.unpaid_orders) + + "건 제외. 카페24 화면과 다른 줄이 있으면 알려 주세요 — 규칙을 맞추겠습니다.

"; + } catch (err) { + out.innerHTML = '

' + esc(err.message) + "

"; + } finally { recon.disabled = false; } + }); + // ── 과거 매출 가져오기(기간 지정 수집, 관리자) ── const backfill = document.getElementById("perf-backfill"); if (backfill) backfill.addEventListener("click", async function () { diff --git a/docs/PERFORMANCE_MODULE.md b/docs/PERFORMANCE_MODULE.md index 9758bd2..727d81d 100644 --- a/docs/PERFORMANCE_MODULE.md +++ b/docs/PERFORMANCE_MODULE.md @@ -36,20 +36,24 @@ `auth_type="shared"` — 기존 `app/integrations/cafe24` OAuth 토큰(cafe24_db)과 클라이언트(재시도·429·토큰 자동 갱신)를 재사용한다. 토큰에 `mall.read_order` 가 있어야 한다(`DEFAULT_SCOPES` 포함, 권한 추가 후 카페24 상품관리 → 시스템에서 재연결). -Admin API `GET /admin/orders`(문서 버전 2026-09-01 확인: 검색기간 한 호출 3개월 미만, limit ≤ 1000, offset ≤ 15000). -| 사건 | 조회 | 대상 | 금액·날짜 | -|---|---|---|---| -| SALE | `date_type=pay_date`, `embed=items` | `paid=T` 주문의 모든 품목 | +품목 결제금액(`payment_amount`, 할인 반영·배송비 제외), 결제일 | -| CANCEL | `date_type=cancel_complete_date` | 품목 상태 C40~C43(취소완료). 입금전취소 C47~C49 제외 | −같은 품목 금액, 품목 `cancel_date` | -| RETURN | `date_type=return_complete_date` | 품목 상태 R40~R43(반품완료) | −품목 금액(부분 반품은 `claim_quantity/quantity` 비율), `return_confirmed_date` | +**카페24 관리자 "일별 매출내역"과 같은 기준**으로 센다(처음의 품목 결제금액 방식은 배송비가 빠지고 환불 날짜 기준이 달라 +화면과 맞지 않아 교체). -- 사건 ID = `{order_item_code}-S|C|R` (중복 방지). 교환(E**)은 1단계에서 반영 안 함. -- **자체몰 주문만**(`market_id` = self/빈값). 카페24 로 연동돼 들어온 다른 마켓 주문(스마트스토어·쿠팡 등)은 해당 쇼핑몰 - 어댑터와 이중 집계되지 않게 제외. 네이버페이 결제(`order_place_id=NCHECKOUT`)는 자체몰 주문이라 포함. -- 기간은 60일씩 나눠 요청, 1000건 단위 페이지. 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않고 raw 에는 금액·상태만. -- **실데이터로 확인할 것**: 품목 `payment_amount` 가 적립금·예치금 사용분을 어떻게 반영하는지, 부분 취소/반품 시 품목이 - 분리되는지(`claim_quantity` 해석). 카페24 관리자 화면 매출과 한 주 정도 대조 후 필요하면 규칙 조정. +| 사건 | 조회 | 금액·날짜 | +|---|---|---| +| SALE(결제합계) | `GET /admin/orders` `date_type=pay_date`, `embed=items`, `paid=T` | +(상품구매금액 + 배송비 − 할인 − 쿠폰), `initial_order_amount`(결제 당시 금액 — 환불을 따로 빼므로 취소 후 금액 X), 결제일. 주문 1건 = 사건 1건(`{order_id}-PAY`) | +| CANCEL / RETURN(환불합계) | `GET /admin/refunds` `date_type=refund_date`, `status=T` | −실제 환불액(`actual_refund_amount`), 환불완료일. 환불코드 R… = 반품, 그 밖 = 취소. 사건 ID = 환불코드 | + +- 할인 = 회원·세트상품·앱·마켓 기타·배송비 할인, 쿠폰 = 상품쿠폰 + 배송비쿠폰(`DISCOUNT_FIELDS`/`COUPON_FIELDS`). +- **기간 교체(`replace_range=True`)**: 결제·환불 모두 기간 안 날짜로 조회되므로 동기화 때 그 기간의 카페24 실데이터를 지우고 + 새로 넣는다(한 트랜잭션, 테스트 데이터 제외). 규칙이 바뀌어도 예전 행이 남지 않는다 → 규칙을 고친 뒤에는 같은 기간을 + [과거 매출 가져오기]로 다시 받으면 된다. +- **자체몰 주문만**(`market_id` = self/빈값). 환불은 원 주문을 100건씩 조회해 `market_id` 로 판단. 네이버페이는 자체몰 주문. +- 60일 단위 분할(한 호출 3개월 미만), orders limit 1000 / refunds limit 500 페이지. 개인정보는 저장하지 않는다. +- **카페24 매출 대조**(설정 화면, `GET /api/marketplaces/cafe24/reconcile?date=`): 그날 결제 주문·환불을 카페24 화면 열 순서대로 + (주문수·품목수·상품구매금액·배송비·할인·쿠폰·결제합계·환불합계·순매출) 자체몰/다른 마켓으로 나눠 합산. 저장하지 않음. + 카페24 화면과 다른 줄이 있으면 할인 항목 구성·마켓 포함 여부를 이 결과로 조정한다. ### 연동 단계 체크리스트(쇼핑몰마다)