From 1d12ac878b96e8664d529dbebea8d5dfbf212322 Mon Sep 17 00:00:00 2001 From: king Date: Tue, 29 Sep 2026 17:59:24 +0900 Subject: [PATCH] =?UTF-8?q?fix(performance):=20=EC=B9=B4=ED=8E=9824=20?= =?UTF-8?q?=ED=99=98=EB=B6=88=ED=95=A9=EA=B3=84=EB=A5=BC=20=EC=9D=BC?= =?UTF-8?q?=EB=B3=84=20=EB=A7=A4=EC=B6=9C=EB=82=B4=EC=97=AD=EA=B3=BC=20?= =?UTF-8?q?=EA=B0=99=EA=B2=8C=20=E2=80=94=20=EC=A0=81=EB=A6=BD=EA=B8=88=20?= =?UTF-8?q?=ED=99=98=EB=B6=88=20+=20=EB=84=A4=EC=9D=B4=EB=B2=84=ED=8E=98?= =?UTF-8?q?=EC=9D=B4=20=EC=B7=A8=EC=86=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 실데이터 대조 결과 카페24 일별 매출 환불합계 = 환불 목록(실제 환불액 + 적립금·예치금 환불) + 환불 목록에 없는 취소·반품(네이버페이 취소 등, 품목 취소일 기준) 9/26: 178,220 + 1,080 + 96,500 = 275,800, 9/27: 145,000 + 55,800 = 200,800 일치. - normalize_refund 금액에 적립금·예치금 환불 포함(refund_total) - unrefunded_claims: orders date_type=cancel_date|return_complete_date 의 C40~43/R40~43 품목 중 앞뒤 60일 환불 목록에 없는 주문 → CANCEL/RETURN 사건(c24:{품목코드}-CL) - 대조 화면 환불합계를 적용 규칙으로 표시 + "적용 규칙" 후보 - 테스트 추가 Co-Authored-By: Claude Opus 5.5 --- app/modules/performance/adapters/cafe24.py | 101 ++++++++++++++++-- .../templates/performance/index.html | 2 +- .../templates/performance/settings.html | 2 +- .../performance/tests/test_performance.py | 46 +++++++- app/static/performance.js | 15 +-- docs/PERFORMANCE_MODULE.md | 13 ++- 6 files changed, 157 insertions(+), 22 deletions(-) diff --git a/app/modules/performance/adapters/cafe24.py b/app/modules/performance/adapters/cafe24.py index b768ac7..e8acc3a 100644 --- a/app/modules/performance/adapters/cafe24.py +++ b/app/modules/performance/adapters/cafe24.py @@ -55,6 +55,10 @@ 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"}) +REFUND_LOOKAROUND_DAYS = 60 # 카페24 자체몰 주문 채널 — market_id 는 외부 마켓만이 아니라 주문 채널·간편결제도 담는다 # (실데이터 확인 2026-09-30: mobile=모바일웹, NCHECKOUT=네이버페이, KAKAOPAY=톡체크아웃). @@ -141,6 +145,11 @@ def order_total(order: dict[str, Any]) -> int: - sum(a[k] for k in DISCOUNT_FIELDS) - sum(a[k] for k in COUPON_FIELDS)) +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 {} @@ -314,6 +323,49 @@ class Cafe24Adapter(MarketplaceAdapter): 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일 환불 목록(완료일·접수일)에 그 주문이 있으면 제외해 + 환불 목록 쪽과 두 번 빼지 않는다.""" + from app.timezone import today_kst # noqa: WPS433 + + found: dict[str, dict[str, Any]] = {} + for date_type in NO_RECORD_DATE_TYPES: + for s, e in _chunks(start, end): + for o in self._paged(ctx, "/admin/orders", "orders", + {"start_date": s.isoformat(), "end_date": e.isoformat(), + "date_type": date_type, "embed": "items"}, ORDER_LIMIT): + oid = str(o.get("order_id") or "") + for i in o.get("items") or []: + 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 None or not (start <= day <= end): + continue + key = str(i.get("order_item_code") or f"{oid}-{i.get('item_no')}") + qty = int(i.get("quantity") or 0) + amount = ((_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"))) + 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": max(0, amount), + "product_name": str(i.get("product_name") or "")[:40], + "naver_pay_claim_status": str(i.get("naver_pay_claim_status") or ""), + } + if not found: + return [] + lo = start - timedelta(days=REFUND_LOOKAROUND_DAYS) + hi = max(end, min(end + timedelta(days=REFUND_LOOKAROUND_DAYS), today_kst())) + refunded = {str(r.get("order_id") or "") for dt in ("refund_date", "accepted_refund_date") + for r in self.refunds(ctx, lo, hi, dt)} + return [c for c in found.values() if c["order_id"] not in refunded] + def market_ids(self, ctx: AdapterContext, refunds: list[dict[str, Any]]) -> dict[str, tuple[Any, Any, Any]]: """환불의 원 주문 (market_id, order_place_id, order_place_name) — 주문일 60일 구간·100건씩 묶어 조회. 못 찾으면 자체몰.""" @@ -343,6 +395,8 @@ class Cafe24Adapter(MarketplaceAdapter): 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).""" @@ -368,12 +422,15 @@ class Cafe24Adapter(MarketplaceAdapter): )] def normalize_refund(self, refund: dict[str, Any]) -> list[SaleEvent]: - """환불 → CANCEL/RETURN(−). 원 주문의 market_id 로 결제와 같은 쇼핑몰 열에 넣는다.""" + """환불 → CANCEL/RETURN(−). 원 주문의 market_id 로 결제와 같은 쇼핑몰 열에 넣는다. + 금액 = 실제 환불액 + 적립금·예치금 환불(카페24 일별 매출 환불합계와 같음, 실데이터 확인).""" + if refund.get("_kind") == "claim": + return self.normalize_claim(refund) day = _day(refund.get("refund_date")) code = str(refund.get("refund_code") or "") if day is None or not code: return [] - amount = _won(refund.get("actual_refund_amount")) + amount = refund_total(refund) return [SaleEvent( marketplace_code=target_code(refund.get("_market_id"), refund.get("_order_place_id")), event_type="RETURN" if code.upper().startswith("R") else "CANCEL", @@ -387,6 +444,23 @@ class Cafe24Adapter(MarketplaceAdapter): "quantity": refund.get("quantity"), "order_item_code": refund.get("order_item_code")}, )] + def normalize_claim(self, c: dict[str, Any]) -> list[SaleEvent]: + """환불 목록에 없는 취소·반품 품목(네이버페이 등) → CANCEL/RETURN(−), 취소일(반품완료일).""" + if not c.get("amount") or c.get("day") is None: + return [] + is_return = str(c.get("status"))[:1] == "R" + return [SaleEvent( + marketplace_code=target_code(c.get("market_id"), c.get("place_id")), + event_type="RETURN" if is_return else "CANCEL", + external_event_id=f"{EVENT_PREFIX}{c['item_code']}-CL", external_order_id=str(c.get("order_id") or ""), + external_line_id=str(c["item_code"]), order_date=c.get("order_date"), event_date=c["day"], + amount=-int(c["amount"]), quantity=-int(c.get("quantity") or 0), product_name=c.get("product_name") or "", + order_status="반품완료" if is_return else "취소완료", + raw={"order_id": c.get("order_id"), "item_code": c["item_code"], "status": c.get("status"), + "market_id": c.get("market_id"), "naver_pay_claim_status": c.get("naver_pay_claim_status"), + "no_refund_record": True}, + )] + # ── 대조(설정 화면 "카페24 매출 대조") ───────────────── def reconcile(self, ctx: AdapterContext, day: date) -> dict[str, Any]: """그날 결제 주문·환불을 항목별로 합산 — 카페24 일별 매출내역과 비교해 규칙을 확정하는 용도. @@ -465,8 +539,8 @@ class Cafe24Adapter(MarketplaceAdapter): } 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}} + 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) @@ -474,8 +548,18 @@ class Cafe24Adapter(MarketplaceAdapter): 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"] += _won(r.get("actual_refund_amount")) + 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) @@ -555,7 +639,9 @@ class Cafe24Adapter(MarketplaceAdapter): claimed = csum(lambda c: True) # 카페24 "환불합계" 후보 — 화면 값과 같은 줄을 찾는다(화면에서 값을 입력하면 강조) candidates = [ - {"key": "completed", "label": "환불완료일 · 실제 환불액 (현재 적용)", "amount": comp["actual_refund_amount"]}, + {"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"]}, @@ -578,6 +664,9 @@ class Cafe24Adapter(MarketplaceAdapter): "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), "formula": "결제합계 = 상품구매금액 + 배송비 − 할인(" + ", ".join(DISCOUNT_FIELDS) + diff --git a/app/modules/performance/templates/performance/index.html b/app/modules/performance/templates/performance/index.html index f20d3e5..b66215f 100644 --- a/app/modules/performance/templates/performance/index.html +++ b/app/modules/performance/templates/performance/index.html @@ -239,4 +239,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 7144ec3..5664b04 100644 --- a/app/modules/performance/templates/performance/settings.html +++ b/app/modules/performance/templates/performance/settings.html @@ -143,4 +143,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 d7a38a9..915eeb9 100644 --- a/app/modules/performance/tests/test_performance.py +++ b/app/modules/performance/tests/test_performance.py @@ -425,7 +425,7 @@ class _FakeCafe24(__import__("app.modules.performance.adapters.cafe24", fromlist 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]} - if params.get("date_type", "").endswith("_complete_date"): + if params.get("date_type", "").endswith("_complete_date") or params.get("date_type") == "cancel_date": return {"orders": self.claims.get(params["date_type"], []) if idx == 0 else []} return {"orders": self.orders_pages[idx] if idx < len(self.orders_pages) else []} @@ -549,6 +549,50 @@ def test_cafe24_normalize_matches_daily_report(): assert calls[1]["offset"] == 1000 and all(c["limit"] == 1000 and c["date_type"] == "pay_date" for c in calls) +def test_cafe24_refund_total_includes_points_and_naverpay_cancels(): + """카페24 일별 매출 환불합계 = 환불 목록(실제 + 적립금·예치금) + 환불 목록에 없는 취소·반품(네이버페이 등). + 실데이터: 9/26 = 178,220 + 1,080 + 네이버페이 취소 96,500 = 275,800, 9/27 = 145,000 + 네이버페이 55,800.""" + import app.timezone as _tz + from app.modules.performance.adapters.base import AdapterContext + + ctx = AdapterContext(code="cafe24", credentials=None) + item = lambda code, st, price, qty=1, day="2026-09-26 15:00:00", **kw: { + "order_item_code": code, "order_status": st, "quantity": qty, "product_price": f"{price}.00", + "option_price": "0.00", "product_name": "상품", "cancel_date": day, **kw} + refund = {**_c24_refund("C20260926-01", "O1", 63_720), "used_points": "1080.00", + "refund_date": "2026-09-26T20:25:08+09:00"} + fake = _FakeCafe24([[]], [[refund]], claims={ + "cancel_date": [ + {**_c24_order("O1"), "items": [item("O1-01", "C40", 64_800)]}, # 환불 목록 있음 → 제외 + {**_c24_order("NP1", market="NCHECKOUT"), "items": [item("NP1-01", "C40", 55_800), + item("NP1-02", "N40", 9_000)]}, # 정상 품목 제외 + {**_c24_order("NP2", market="NCHECKOUT"), "items": [item("NP2-01", "C40", 20_000, 2, + coupon_discount_price="1000.00")]}, + {**_c24_order("NP3", market="NCHECKOUT"), "items": [item("NP3-01", "C40", 5_000, day="2026-09-27 01:00:00")]}, + {**_c24_order("NP4", market="NCHECKOUT"), "items": [item("NP4-01", "C00", 5_000)]}, # 취소신청만 → 제외 + ], + "return_complete_date": [{**_c24_order("NP1", market="NCHECKOUT"), "items": [item("NP1-01", "C40", 55_800)]}], + }) + orig, _tz.today_kst = _tz.today_kst, (lambda: date(2026, 9, 29)) + try: + _, events = fake.collect(ctx, date(2026, 9, 26), date(2026, 9, 26)) + rec = fake.reconcile(ctx, date(2026, 9, 26)) + finally: + _tz.today_kst = orig + by = {e.external_event_id: e for e in events if e.event_type != "SALE"} + assert by["c24:C20260926-01"].amount == -(63_720 + 1_080) # 적립금 환불 포함 + assert by["c24:NP1-01-CL"].amount == -55_800 and by["c24:NP1-01-CL"].event_type == "CANCEL" + assert by["c24:NP1-01-CL"].event_date == date(2026, 9, 26) and by["c24:NP1-01-CL"].marketplace_code == "cafe24" + assert by["c24:NP2-01-CL"].amount == -(40_000 - 1_000) # 판매가×수량 − 품목 쿠폰 + assert set(by) == {"c24:C20260926-01", "c24:NP1-01-CL", "c24:NP2-01-CL"} # 다른 날·신청·환불 기록 있는 주문 제외 + rs = rec["refunds"]["self"] + assert rs["no_record_count"] == 2 and rs["no_record"] == 55_800 + 39_000 + assert rs["total"] == 63_720 + 1_080 + 55_800 + 39_000 + cand = {c["key"]: c["amount"] for c in rec["refund_candidates"]} + assert cand["applied"] == rs["total"] + assert {c["item_code"] for c in rec["no_record_claims"]} == {"NP1-01", "NP2-01"} + + def test_cafe24_scope_and_replace_range(): import app.modules.performance.sync as syncmod from app.modules.performance.adapters.base import AdapterContext diff --git a/app/static/performance.js b/app/static/performance.js index e023872..ecf11f6 100644 --- a/app/static/performance.js +++ b/app/static/performance.js @@ -509,11 +509,14 @@ [" 참고: 실결제금액", 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"], + ["환불 건수(환불 목록)", rs.count, rm.count, "cnt"], + [" · 실제 환불액", rs.actual_refund_amount, rm.actual_refund_amount, "sub"], + [" · 적립금 환불", rs.used_points, rm.used_points, "sub"], + [" · 예치금 환불", rs.used_credits, rm.used_credits, "sub"], + ["환불 목록 없는 취소·반품 품목 수(네이버페이 등)", rs.no_record_count, rm.no_record_count, "cnt"], + [" · 취소·반품 금액", rs.no_record, rm.no_record, "sub"], + ["환불합계", rs.total, rm.total, "key"], + ["순매출(결제합계 − 환불합계)", s.total - rs.total, m.total - rm.total, "key"], ]); out.innerHTML = '" + @@ -534,7 +537,7 @@ return '

환불 기준 비교 — 카페24 화면의 그날 "환불합계"와 같은 칸을 찾아 주세요

' + '
' + esc(r.date) + "카페24 열(자체몰 채널)다른 쇼핑몰 열(외부 마켓)
' + "" + - row("환불완료일 기준 · 완료 현재 적용", b.completed, "perf-row-week") + + row("환불완료일 기준 · 완료 적용(합계 포함 칸)", b.completed, "perf-row-week") + row("환불접수일 기준 · 전체 상태", b.accepted_all) + (b.by_pay_date ? row("결제일 기준 · 그날 결제한 주문의 환불(오늘까지" + (b.by_pay_date.refund_dates.length ? ", 환불일 " + esc(b.by_pay_date.refund_dates.join(", ")) : "") + ")", b.by_pay_date) : "") + diff --git a/docs/PERFORMANCE_MODULE.md b/docs/PERFORMANCE_MODULE.md index 30f832a..db2e070 100644 --- a/docs/PERFORMANCE_MODULE.md +++ b/docs/PERFORMANCE_MODULE.md @@ -43,7 +43,8 @@ | 사건 | 조회 | 금액·날짜 | |---|---|---| | 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 = 환불코드 | +| CANCEL / RETURN(환불합계) | `GET /admin/refunds` `date_type=refund_date`, `status=T` | −(실제 환불액 + 적립금·예치금 환불), 환불완료일. 환불코드 R… = 반품, 그 밖 = 취소. 사건 ID = 환불코드 | +| CANCEL / RETURN(환불 목록 없는 취소·반품) | `GET /admin/orders` `date_type=cancel_date|return_complete_date`, `embed=items` — 품목 상태 C40~43/R40~43 이고 앞뒤 60일 환불 목록(완료일·접수일)에 그 주문이 없을 때 | −(판매가+옵션)×수량 − 품목 할인·쿠폰, 품목 취소일(반품은 반품완료일). 네이버페이 취소가 여기 해당 (네이버가 환불해 카페24 환불 목록에 없음). 사건 ID = `c24:{품목코드}-CL` (`unrefunded_claims`) | - 할인 = 회원·세트상품·앱·마켓 기타·배송비 할인, 쿠폰 = 상품쿠폰 + 배송비쿠폰(`DISCOUNT_FIELDS`/`COUPON_FIELDS`). - **기간 교체(`replace_range=True`)**: 결제·환불 모두 기간 안 날짜로 조회되므로 동기화 때 그 기간의 카페24 실데이터를 지우고 @@ -129,12 +130,10 @@ - **대시보드 [매출 업데이트]** = 지금 보고 있는 기간(오늘까지)을 `POST /api/sync {from, to}` 로 다시 가져온다 ("이번달"이면 1일~오늘). 모듈 권한자는 92일까지, 더 긴 기간(올해 등, 최대 366일)은 관리자만. - **과거 매출 가져오기**(설정 화면, 관리자): 같은 API 로 임의 기간(최대 366일). 같은 사건은 덮어써서 여러 번 해도 중복 없음. -- 카페24 **환불 기준**은 현재 환불완료일(refund_date)·실제 환불액. 대조 도구의 "환불 기준 비교"(완료일 vs 접수일, 적립금·예치금 - 포함 여부)로 카페24 "환불합계"와 같은 기준을 확인한 뒤 확정한다(9/23~27 순매출이 카페24보다 크게 나온 원인 조사 중). - 9/26 은 결제합계가 카페24와 같고(3,568,265) 환불만 97,580 모자라며, 완료일·접수일·적립금 포함 어느 기준으로도 맞지 않았다 - → 환불 API 에 안 잡히는 환불이 있다고 보고, 대조 도구에 **환불합계 후보**(카페24 값 입력 시 일치 줄 강조)·**환불 건별**· - **그날 취소/반품/교환 완료 품목**(`GET /admin/orders` `date_type=cancel_complete_date|return_complete_date|exchange_complete_date`, - `embed=items`, 품목별 판매가·결제금액·환불 기록 유무, `claim_items()`)을 추가해 빠진 건을 찾는다. +- 카페24 **환불합계 규칙(확정, 2026-09-29 실데이터)**: 카페24 "일별 매출내역" 환불합계 = 환불 목록의 (실제 환불액 + 적립금·예치금 환불) + + 환불 목록에 없는 취소·반품(네이버페이 등, 취소일 기준). 9/26 = 178,220 + 1,080 + 네이버페이 취소 96,500 = 275,800, + 9/27 = 145,000 + 네이버페이 55,800 = 200,800 으로 일치. 대조 도구에 환불합계 후보(값 입력 시 일치 줄 강조)·환불 건별· + 취소/반품 완료 품목·그날 결제 주문 중 줄어든 주문 표가 있어 규칙이 어긋나면 이것으로 다시 찾는다. - 같은 쇼핑몰 동시 실행 금지: `perf_sync_runs` 의 `status='running'` 부분 유니크 인덱스(30분 넘은 running 은 정리). - 쇼핑몰 하나 실패 → 그 쇼핑몰만 상태 오류(`perf_connection_status`), 나머지 계속. 대시보드는 저장된 데이터로 계속 표시하고 상단에 오류 쇼핑몰만 표시.
기준건수실제 환불액적립금·예치금 환불합계(포함)