Merge branch 'feat/performance' into feat/project — 네이버 스마트스토어 매출 수집

This commit is contained in:
2026-09-30 13:34:03 +09:00
7 changed files with 611 additions and 18 deletions
+21 -1
View File
@@ -29,7 +29,7 @@
오류 클래스 = 연결 상태: `NotConfigured`(인증정보 미설정) · `AuthFailed`(인증 실패) · `TokenExpired` · `ApiError` · `NotImplementedYet`(연동 준비 중).
**연동 현황**: 카페24 = **구현됨**, 나머지 9개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 현황**: 카페24·11번가·네이버 스마트스토어 = **구현됨**(네이버는 1차 규칙, 실데이터 대조 전), 나머지 7개는 입력칸만 정의(수집은 `NotImplementedYet`). 쇼핑몰별 입력칸은
**연동 단계에서 공식 API 문서로 확정**한다.
### 카페24 (`adapters/cafe24.py`, 구현됨)
@@ -102,6 +102,26 @@
- `replace_range` — 기간을 통째로 다시 받아 취소·반품된 주문이 매출에서 빠진다(취소 사건을 따로 만들지 않음 → 지난 날짜
금액이 나중에 줄 수 있음). 구매자 이름·아이디·연락처는 저장하지 않는다.
### 네이버 스마트스토어 (`adapters/naver.py`, 구현됨 — 1차 규칙)
- 인증: 커머스API센터 애플리케이션 ID·시크릿 → 전자서명 `client_secret_sign = base64(bcrypt.hashpw("{client_id}_{timestamp ms}",
client_secret))` → `POST https://api.commerce.naver.com/external/v1/oauth2/token`(form: client_id·timestamp·client_secret_sign·
grant_type=client_credentials·type=SELF, 판매자 ID 입력 시 type=SELLER+account_id). 토큰(약 3시간)은 `access_token`·
`access_token_expires_at`(internal, 암호화)으로 저장해 만료 5분 전까지 재사용, 401 이면 한 번 새로 받아 다시 호출.
[연결 테스트]는 입력값으로 시험하므로 항상 새 토큰. **애플리케이션의 API 호출 IP 에 운영 서버 외부 IP 등록 필요.**
의존성 `bcrypt`(requirements.txt).
- 수집: 조건형 상품 주문 상세 조회 `GET /v1/pay-order/seller/product-orders?from=&to=&rangeType=PAYED_DATETIME&pageSize=100&page=`
— 한 번에 **24시간까지**(하루씩 0시~23:59:59.999 +09:00), from 부터 180일 안 주문만(네이버 안내, GitHub discussions #1875·#2380).
응답 모양은 `data.contents[].content.{order, productOrder, …}` 로 보고 목록·`content` 유무가 달라도 받는다(`product_order_items`),
다음 쪽은 `pagination.hasNext`(없으면 100건 꽉 차면). 호출 간격 0.35초, 429 는 1·2·4초 쉬고 다시.
- **1차 매출 규칙**: SALE = 주문 하나(`naver:{orderId}`), 날짜 = 결제일(`order.paymentDate`). 금액 = 상품주문
`totalPaymentAmount` 합 + 배송비(`deliveryFeeAmount − deliveryDiscountAmount`, 주문에서 최댓값 한 번). 할인 = `productDiscountAmount` 합.
취소·반품 완료(`CANCELED`·`RETURNED`)·미입금 취소(`CANCELED_BY_NOPAYMENT`) 상품주문은 뺀다. `replace_range` — 기간을 다시 받으면
나중에 취소된 주문이 빠진다(11번가와 같은 방식).
- **확정 전 할 일**: 설정 화면 **"쇼핑몰 원본 데이터 확인"**(네이버 선택) — 결제일 기준 상품주문 전체의 항목별 합계,
상태별 합계, 날짜별 "현재 규칙 매출"을 스마트스토어센터 화면 매출과 비교해 금액 항목(결제금액 vs 상품금액, 네이버 부담 할인,
배송비 묶음 기준)을 확정한다. 개인정보(주문자·수령인·주소·연락처·메모)는 값 없이 이름만.
### 연동 단계 체크리스트(쇼핑몰마다)
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 API·날짜 필드 확인