feat(performance): 토스쇼핑 매출 = 순 거래액(매출 − 환불) — 정산 건별 REFUND 를 환불일에 차감

- 사용자 지정: 토스쇼핑 파트너스 "순 거래액" 기준(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 <noreply@anthropic.com>
This commit is contained in:
2026-10-01 10:12:07 +09:00
parent a45f78217c
commit d75dec2a50
6 changed files with 176 additions and 38 deletions
+15 -9
View File
@@ -29,7 +29,7 @@
오류 클래스 = 연결 상태: `NotConfigured`(인증정보 미설정) · `AuthFailed`(인증 실패) · `TokenExpired` · `ApiError` · `NotImplementedYet`(연동 준비 중).
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑 = **구현됨**(토스쇼핑은 매출 규칙 잠정), 나머지 5개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 현황**: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑 = **구현됨**, 나머지 5개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 단계에서 공식 API 문서로 확정**한다.
### 카페24 (`adapters/cafe24.py`, 구현됨)
@@ -147,7 +147,7 @@
**GS샵 수수료율은 0%**. 배송비 제외, `ordType` 이 SALE 이 아니면 RETURN 음수. `replace_range`.
원본 데이터 확인에 날짜별 현재 규칙 매출·취소/반품·배송비(참고).
### 토스쇼핑 (`adapters/toss.py`, 구현됨 — 매출 규칙 잠정)
### 토스쇼핑 (`adapters/toss.py`, 구현됨)
- 문서: `https://shopping-docs.toss.im/dev` (공개, 전체 목록 `llms.txt`, 쪽 주소 뒤 `.md` = 원문). 문의는 문서의 디스코드.
- 인증: 토스쇼핑 파트너스 → 상점 이름 > 가맹점·계정 관리 > **자체 개발** → [키 발급](**호출 IP 입력 — 운영 서버 외부 IP**, 등록된
@@ -162,13 +162,19 @@
전체, 커서(`nextCursor` null = 끝). 줄 = 주문상품(`orderProductId`), 주문 = `orderId`. 금액 항목: `price`(판매가 × 수량)·
`originPrice`(정상가 × 수량)·`totalDiscountPrice`(= `tossShoppingDiscount` + `tossPayDiscount`)·`tossPayPoint`·`deliveryFee`
(묶음 `deliveryFeeGroupId` 마다). 결제일 필드는 따로 없고 `orderedAt`(주문 = 결제) · `canceledAt` · `confirmedAt`.
- **매출 규칙(잠정, 파트너스 화면과 대조 전)**: SALE = 주문 하나(`toss:{orderId}`), 날짜 = `orderedAt` 의 한국 날짜, 금액 =
`price` 합(할인 전, 배송비 제외), 할인은 `discount_amount` 로만. 결제 전(`BEFORE_PAYMENT`)만 빼고 결제 뒤 취소·반품도 주문일 매출에
둔다(네이버와 같은 방식 → 지난 날짜 매출이 나중에 줄지 않음). `replace_range`. 개인정보(주문자·수령인·주소·요청사항·송장)는 저장 안 함.
- 정산 API `GET /settlement-steps`(`dateCondition` PAYOUT_DATE·PAYOUT_BASE_DATE·TRANSACTION_DATE…, 31일, `stepType` PAY|REFUND,
셀러 부담 쿠폰 `shoppingDiscountMerchant`, 정산 지급액 `settlementAmount`)은 구매확정·취소된 건만 나온다 — 규칙 확정 때 필요하면 쓴다.
- 확정 방법: 설정 화면 "쇼핑몰 원본 데이터 확인" → 토스쇼핑, 매출이 있던 기간 → 날짜별 현재 규칙 매출·상태별 항목 합계를 토스쇼핑
파트너스 매출 화면과 비교해 맞는 항목(`price` / `price − totalDiscountPrice` / 취소 제외 여부)으로 규칙을 고친다.
- **매출 규칙 = 파트너스 "순 거래액" = 매출 − 환불**(2026-10-01 사용자 지정, 9/6 화면: 매출 29,600 − 환불 11,900 = 순 거래액 17,700).
- 매출 SALE = 주문 하나(`toss:{orderId}`), 날짜 = `orderedAt` 의 한국 날짜, 금액 = `price` 합(할인 전, 배송비 제외), 할인은
`discount_amount` 로만. 결제 전(`BEFORE_PAYMENT`)만 빼고 나중에 취소·반품된 주문도 주문일 매출에 둔다(화면 "매출"도 환불 전).
- 환불 CANCEL = 정산 건별 `GET /api/v3/shopping-fep/settlement-steps?dateCondition=TRANSACTION_DATE&fromDate&toDate&size=100&nextToken`
(31일, 결제·환불·배송비 줄)의 **`stepType=REFUND` 상품 줄**(배송비 줄 = `orderProductId` 없음 → 제외), 날짜 = 환불 거래 일시
`transactionTs` 의 한국 날짜, 금액 = −|`orderProductPrice`|(없으면 판매가 × 수량). 사건 ID `toss:R{orderProductId}-{거래일시}`.
클레임 목록 API 는 날짜로 거를 수 없고(REQUESTED·REVOKED 만 7일 조회) 결제완료 단계의 고객 취소는 클레임으로 안 잡혀서 쓰지 않는다.
- `replace_range`(접두어 `toss:` — 매출·환불 함께 교체). 진행 막대 = 주문 + 정산 31일 구간 수. 개인정보(주문자·수령인·주소·요청사항·
송장)는 저장 안 함.
- 정산 줄의 다른 항목: 셀러 부담 쿠폰 `shoppingDiscountMerchant`, 정산 지급액 `settlementAmount`, 수수료 `payFee`·`productFee`.
- 대조: 설정 화면 "쇼핑몰 원본 데이터 확인" → 토스쇼핑 — 날짜별 **매출(주문일)·환불(환불일)·순 거래액**(`day_cols`)과 주문 상태별·
정산 stepType 별 항목 합계. 파트너스 화면 숫자와 다르면 금액 항목(`price` / `price − totalDiscountPrice`, 환불 `orderProductPrice` /
`orderProductPaidAmount`)이나 날짜 기준을 여기서 보고 고친다(실데이터 대조는 아직 — 운영 서버 IP 에서만 호출됨).
### 연동 단계 체크리스트(쇼핑몰마다)