From d75dec2a50669702f6bc44838aeff3a1c7973077 Mon Sep 17 00:00:00 2001
From: king
Date: Thu, 1 Oct 2026 10:12:07 +0900
Subject: [PATCH] =?UTF-8?q?feat(performance):=20=ED=86=A0=EC=8A=A4?=
=?UTF-8?q?=EC=87=BC=ED=95=91=20=EB=A7=A4=EC=B6=9C=20=3D=20=EC=88=9C=20?=
=?UTF-8?q?=EA=B1=B0=EB=9E=98=EC=95=A1(=EB=A7=A4=EC=B6=9C=20=E2=88=92=20?=
=?UTF-8?q?=ED=99=98=EB=B6=88)=20=E2=80=94=20=EC=A0=95=EC=82=B0=20?=
=?UTF-8?q?=EA=B1=B4=EB=B3=84=20REFUND=20=EB=A5=BC=20=ED=99=98=EB=B6=88?=
=?UTF-8?q?=EC=9D=BC=EC=97=90=20=EC=B0=A8=EA=B0=90?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- 사용자 지정: 토스쇼핑 파트너스 "순 거래액" 기준(9/6 화면 매출 29,600 − 환불 11,900 = 17,700)
- 환불: GET /settlement-steps dateCondition=TRANSACTION_DATE 의 stepType=REFUND 상품 줄 → CANCEL 사건,
날짜 = transactionTs 한국 날짜, 금액 = -|orderProductPrice|, 배송비 줄 제외, 31일 구간 + nextToken
(클레임 목록은 날짜로 거를 수 없고 결제완료 단계 고객 취소가 안 잡혀 정산 쪽을 사용)
- 원본 데이터 확인: 날짜별 매출(주문일)·환불(환불일)·순 거래액 + 정산 stepType 별 항목 합계
- 원본 확인 표의 매출 열 이름도 day_cols 로 바꿀 수 있게(performance.js), 캐시 버전 20261001b
- 테스트·문서 갱신
Co-Authored-By: Claude Opus 5.5
---
app/modules/performance/adapters/toss.py | 121 +++++++++++++++---
.../templates/performance/index.html | 2 +-
.../templates/performance/settings.html | 4 +-
.../performance/tests/test_performance.py | 60 +++++++--
app/static/performance.js | 3 +-
docs/PERFORMANCE_MODULE.md | 24 ++--
6 files changed, 176 insertions(+), 38 deletions(-)
diff --git a/app/modules/performance/adapters/toss.py b/app/modules/performance/adapters/toss.py
index 49d8e24..f58ca87 100644
--- a/app/modules/performance/adapters/toss.py
+++ b/app/modules/performance/adapters/toss.py
@@ -11,14 +11,17 @@
API 는 https://shopping-fep.toss.im, 헤더 Authorization: Bearer {token}. HTTP 200 + resultType FAIL 로 오류를 준다.
호출 제한: 셀러·API 별 읽기 초당 50회(넘으면 TOO_MANY_REQUEST).
-매출 수집 — 주문 내역 조회 GET /api/v3/shopping-fep/orders/v2?startDate=&endDate=&limit=50&nextCursor=
- (한 번에 31일까지, 상태 생략 = 전체 상태, 커서 페이지). 줄 = 주문상품(orderProductId), 묶음 = 주문(orderId).
- **잠정 규칙(토스쇼핑 파트너스 화면과 대조 전)**:
- - SALE = 주문 하나(`toss:{orderId}`), 날짜 = 주문 시각(orderedAt, 한국 날짜 — 토스쇼핑은 주문 = 결제).
- - 금액 = 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외. 할인(totalDiscountPrice = 토스쇼핑 할인 +
- 토스페이 할인)은 discount_amount 로만 보관. 결제 전(BEFORE_PAYMENT)만 빼고, 결제 뒤 취소·반품도 주문일 매출에 둔다
- (원본 데이터 확인 표에 참고 열로 따로) → 지난 날짜 매출이 나중에 줄지 않는다(네이버와 같은 방식).
- - 실데이터로 파트너스 화면 매출과 맞춰 본 뒤 규칙을 확정한다(설정 화면 "쇼핑몰 원본 데이터 확인").
+매출 = 토스쇼핑 파트너스 "순 거래액" = 매출 − 환불(2026-10-01 사용자 지정, 9/6 화면: 매출 29,600 − 환불 11,900 = 17,700).
+ - 매출 SALE — 주문 내역 조회 GET /api/v3/shopping-fep/orders/v2?startDate=&endDate=&limit=50&nextCursor=
+ (한 번에 31일까지, 상태 생략 = 전체 상태, 커서 페이지). 줄 = 주문상품(orderProductId), 묶음 = 주문(orderId).
+ 주문 하나 = 사건 하나(`toss:{orderId}`), 날짜 = 주문 시각(orderedAt, 한국 날짜 — 토스쇼핑은 주문 = 결제),
+ 금액 = 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외. 할인(totalDiscountPrice = 토스쇼핑 할인 + 토스페이 할인)은
+ discount_amount 로만 보관. 결제 전(BEFORE_PAYMENT)만 빼고 결제 뒤 취소·반품도 주문일 매출에 둔다(화면 "매출"도 환불 전 금액).
+ - 환불 CANCEL — 정산 건별 목록 GET /api/v3/shopping-fep/settlement-steps?dateCondition=TRANSACTION_DATE&fromDate=&toDate=
+ &size=100&nextToken= 의 stepType=REFUND 줄(상품 줄만 — 배송비 줄은 orderProductId 가 없음). 날짜 = 환불 거래 일시
+ (transactionTs, 한국 날짜), 금액 = −|orderProductPrice|(정산 기준 금액, 없으면 판매가 × 수량). 결제완료 단계의 고객 취소는
+ 클레임 목록에 안 잡히고 클레임 목록은 날짜로 거를 수 없어 정산 쪽을 쓴다. 사건 ID `toss:R{orderProductId}-{거래일시}`.
+ - 설정 화면 "쇼핑몰 원본 데이터 확인"에 날짜별 매출·환불·순 거래액 — 파트너스 화면과 같은지 본다.
- 구매자·수령인 이름·연락처·주소·요청사항은 저장하지 않는다.
"""
@@ -45,6 +48,8 @@ from .naver import field_summary, flatten
TOKEN_URL = "https://oauth2.cert.toss.im/token"
HOST = "https://shopping-fep.toss.im"
ORDERS_PATH = "/api/v3/shopping-fep/orders/v2"
+SETTLEMENT_PATH = "/api/v3/shopping-fep/settlement-steps"
+SETTLEMENT_SIZE = 100 # 문서 1~100
SCOPE = "toss-shopping-fep:write"
EVENT_PREFIX = "toss:"
PAGE_SIZE = 50 # 문서 최대 50
@@ -135,6 +140,24 @@ def group_orders(items: Iterable[dict[str, Any]], start: date, end: date) -> dic
return orders
+def refund_rows(items: Iterable[dict[str, Any]], start: date, end: date) -> list[dict[str, Any]]:
+ """정산 건별 목록 → 환불(stepType REFUND) 상품 줄만, 환불일(transactionTs 한국 날짜)이 [start, end] 인 것.
+ 금액은 양수로(사건에서 − 를 붙인다). 배송비 줄(orderProductId 없음)은 매출에 배송비를 넣지 않으므로 뺀다."""
+ out = []
+ for it in items:
+ if str(it.get("stepType") or "") != "REFUND" or not it.get("orderProductId") or not it.get("orderId"):
+ continue
+ day = kst_day(it.get("transactionTs"))
+ if day is None or not (start <= day <= end):
+ continue
+ amount = abs(_won(it.get("orderProductPrice"))) or abs(_won(it.get("stockPrice"))) * max(1, _won(it.get("quantity")))
+ out.append({"orderId": str(it["orderId"]), "orderProductId": str(it["orderProductId"]),
+ "_day": day, "_ts": str(it.get("transactionTs") or ""), "amount": amount,
+ "qty": _won(it.get("quantity")), "name": str(it.get("displayProductName") or ""),
+ "order_day": kst_day(it.get("originTransactionTs"))})
+ return out
+
+
def summary(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
"""원본 확인 표 — 항목별 채워진 줄·숫자 합계·예시 값(개인정보·자유 입력 항목은 값 숨김)."""
fields = field_summary([flatten(r) for r in rows])
@@ -293,23 +316,64 @@ class TossAdapter(MarketplaceAdapter):
break
return out
- def _items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
+ def _settlement_items(self, ctx: AdapterContext, a: date, b: date) -> list[dict[str, Any]]:
+ """거래일 기준 [a, b](31일 이하)의 정산 건별 줄 전체(결제·환불·배송비), nextToken 으로 끝까지."""
+ params: dict[str, Any] = {"dateCondition": "TRANSACTION_DATE", "fromDate": a.isoformat(),
+ "toDate": b.isoformat(), "size": SETTLEMENT_SIZE}
+ out: list[dict[str, Any]] = []
+ token = None
+ for _ in range(MAX_PAGES):
+ body = self._get(ctx, SETTLEMENT_PATH, {**params, **({"nextToken": token} if token else {})})
+ rows = [r for r in body.get("items") or [] if isinstance(r, dict)]
+ out.extend(rows)
+ token = body.get("nextToken")
+ if not token or not rows:
+ break
+ return out
+
+ @staticmethod
+ def _windows(start: date, end: date) -> list[tuple[date, date]]:
windows = []
a = start
while a <= end:
b = min(end, a + timedelta(days=WINDOW_DAYS - 1))
windows.append((a, b))
a = b + timedelta(days=1)
- ctx.progress.plan(len(windows), "31일 구간")
- for a, b in windows:
+ return windows
+
+ def _items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
+ """주문 내역(매출) — 31일 구간마다 진행 막대 한 칸(plan 은 부르는 쪽이 주문 + 정산 구간 수로 정한다)."""
+ for a, b in self._windows(start, end):
rows = self._window_items(ctx, a, b)
ctx.progress.step(items=len(rows))
yield from rows
+ def _refund_items(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
+ """정산 건별(환불이 들어 있음) — 31일 구간마다 진행 막대 한 칸."""
+ for a, b in self._windows(start, end):
+ rows = self._settlement_items(ctx, a, b)
+ ctx.progress.step(items=len(rows))
+ yield from rows
+
# ── 수집 ──────────────────────────────────────────────
def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
+ ctx.progress.plan(2 * len(self._windows(start, end)), "31일 구간") # 주문 내역 + 정산(환불)
yield from group_orders(self._items(ctx, start, end), start, end).values()
+ def fetch_refunds(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]:
+ yield from refund_rows(self._refund_items(ctx, start, end), start, end)
+
+ def normalize_refund(self, r: dict[str, Any]) -> list[SaleEvent]:
+ oid, day = str(r.get("orderId") or ""), r.get("_day")
+ if not oid or day is None:
+ return []
+ return [SaleEvent(
+ event_type="CANCEL", external_event_id=f"{EVENT_PREFIX}R{r['orderProductId']}-{r.get('_ts') or day}"[:200],
+ external_order_id=oid, external_line_id=str(r.get("orderProductId") or ""), event_date=day,
+ order_date=r.get("order_day"), amount=-abs(int(r.get("amount") or 0)),
+ product_name=str(r.get("name") or "")[:200], quantity=int(r.get("qty") or 0), order_status="환불",
+ )]
+
def normalize_order(self, o: dict[str, Any]) -> list[SaleEvent]:
oid, day = str(o.get("orderId") or ""), o.get("_day")
if not oid or day is None:
@@ -342,11 +406,18 @@ class TossAdapter(MarketplaceAdapter):
토스쇼핑 파트너스 화면 매출과 어느 항목이 맞는지 실데이터로 확정하는 용도. 개인정보 항목은 값 없이 이름만."""
self.authenticate(ctx)
to = min(max(to or day, day), day + timedelta(days=PROBE_MAX_DAYS - 1))
+ ctx.progress.plan(2 * len(self._windows(day, to)), "31일 구간")
try:
items = list(self._items(ctx, day, to))
except AdapterError as exc:
return {"date": day.isoformat(), "to": to.isoformat(), "probes": [
{"key": "orders", "label": "주문 내역", "path": ORDERS_PATH, "ok": False, "error": exc.message[:300]}]}
+ settle_err = ""
+ try:
+ settle = list(self._refund_items(ctx, day, to))
+ except AdapterError as exc:
+ settle, settle_err = [], exc.message[:300]
+ refunds = refund_rows(settle, day, to)
by_status: dict[str, list[dict[str, Any]]] = {}
for it in items:
by_status.setdefault(str(it.get("orderProductStatus") or "?"), []).append(it)
@@ -358,14 +429,34 @@ class TossAdapter(MarketplaceAdapter):
" — 결제 뒤 취소·반품(매출 포함)" if st in CLAIMED_STATUS else ""),
"path": "orderProductStatus", "ok": True, "count": len(rows),
"fields": [f for f in summary(rows) if f["sum"] is not None]})
+ if settle_err:
+ probes.append({"key": "settlement", "label": "정산 건별(거래일 기준 — 환불)", "path": SETTLEMENT_PATH,
+ "ok": False, "error": settle_err})
+ else:
+ probes.append({"key": "settlement", "label": "정산 건별(거래일 기준, 결제·환불·배송비 줄 전체)",
+ "path": SETTLEMENT_PATH + " (TRANSACTION_DATE)", "ok": True, "count": len(settle),
+ "fields": summary(settle)})
+ steps: dict[str, list[dict[str, Any]]] = {}
+ for it in settle:
+ kind = str(it.get("stepType") or "?") + ("" if it.get("orderProductId") else " · 배송비 줄")
+ steps.setdefault(kind, []).append(it)
+ for kind, rows in sorted(steps.items()):
+ probes.append({"key": f"step-{kind}", "label": f"정산 {kind}"
+ + (" — 환불(순 거래액에서 뺌)" if kind == "REFUND" else ""),
+ "path": "stepType", "ok": True, "count": len(rows),
+ "fields": [f for f in summary(rows) if f["sum"] is not None]})
days = []
orders = group_orders(items, day, to)
d = day
while d <= to:
day_orders = [o for o in orders.values() if o["_day"] == d]
- days.append({"date": d.isoformat(), "orders": len(day_orders), "amount": sum(o["amount"] for o in day_orders),
- "claimed": sum(o["claimed"] for o in day_orders), "ship": sum(o["ship"] for o in day_orders)})
+ sales = sum(o["amount"] for o in day_orders)
+ refund = sum(r["amount"] for r in refunds if r["_day"] == d)
+ days.append({"date": d.isoformat(), "orders": len(day_orders), "amount": sales, "claimed": refund,
+ "ship": sales - refund})
d += timedelta(days=1)
return {"date": day.isoformat(), "to": to.isoformat(), "probes": probes, "days": days,
- "rule": "주문일(orderedAt, 한국 날짜) 기준 주문상품 price(판매가 × 수량) 합 — 할인 전, 배송비 제외, "
- "결제 뒤 취소·반품분 포함, 결제 전 제외. 잠정 규칙 — 토스쇼핑 파트너스 매출과 비교해 확정"}
+ "day_cols": {"amount": "매출(주문일)", "claimed": "환불(환불일)", "ship": "순 거래액(저장되는 매출)"},
+ "rule": "순 거래액 = 매출 − 환불. 매출 = 주문일(orderedAt) 기준 주문상품 price(판매가 × 수량) 합(할인 전, "
+ "배송비 제외, 나중에 취소·반품된 주문 포함, 결제 전 제외). 환불 = 정산 건별 REFUND 상품 줄의 "
+ "orderProductPrice, 환불 거래일(transactionTs) 기준. 토스쇼핑 파트너스의 매출·환불·순 거래액과 비교"}
diff --git a/app/modules/performance/templates/performance/index.html b/app/modules/performance/templates/performance/index.html
index 71102cf..49aa57c 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 f380e4f..9450650 100644
--- a/app/modules/performance/templates/performance/settings.html
+++ b/app/modules/performance/templates/performance/settings.html
@@ -124,7 +124,7 @@
· 네이버: 결제일 기준 상품주문 전체(상태별 합계 포함)와 날짜별 "현재 규칙 매출" — 스마트스토어센터 매출과 비교해 주세요.
· 11번가: 주문·클레임·정산 조회 주소별 동작 여부. 정산은 정산일 기준일 수 있어 매출이 있던 날부터 넉넉히(예: 3주).
· GS샵: 매출 내역·배송비 내역(매출인식일 기준)의 항목별 합계 — 협력사 포털 매출 화면의 같은 기간 숫자와 비교해 주세요.
- · 토스쇼핑: 주문 내역(주문일 기준, 상태별 합계 포함)과 날짜별 "현재 규칙 매출" — 토스쇼핑 파트너스 매출과 비교해 주세요.
+ · 토스쇼핑: 날짜별 매출·환불·순 거래액(= 저장되는 매출)과 주문 상태별·정산 항목 합계 — 토스쇼핑 파트너스의 같은 날 숫자와 비교해 주세요.