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 API 에서 + 바로 합산하며(저장하지 않음), 자체몰과 다른 마켓 연동 주문을 나눠 보여 줍니다.
+카페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 = '| ' + 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 화면과 다른 줄이 있으면 할인 항목 구성·마켓 포함 여부를 이 결과로 조정한다. ### 연동 단계 체크리스트(쇼핑몰마다)