From 40d94e28922be31887d32bd3b0a1ca6c5855e3c7 Mon Sep 17 00:00:00 2001 From: king Date: Wed, 30 Sep 2026 01:20:18 +0900 Subject: [PATCH] =?UTF-8?q?feat(performance):=2011=EB=B2=88=EA=B0=80=20?= =?UTF-8?q?=EB=A7=A4=EC=B6=9C=20=EC=88=98=EC=A7=91=20=E2=80=94=20=EC=A3=BC?= =?UTF-8?q?=EB=AC=B8=20=EC=83=81=ED=83=9C=20=EB=AA=A9=EB=A1=9D=20=EA=B8=B0?= =?UTF-8?q?=EC=A4=80,=20=EA=B2=B0=EC=A0=9C=EC=9D=BC=C2=B7=ED=8C=90?= =?UTF-8?q?=EB=A7=A4=EA=B8=88=EC=95=A1+=EB=B0=B0=EC=86=A1=EB=B9=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit "11번가 원본 데이터 확인"(9/9~9/29) 실데이터로 확정: - 주문 상태 목록(결제완료·발송대기·배송중·배송완료)은 지금 그 상태인 주문만 주고, 배송완료 목록에 구매확정 주문도 남는다. 취소된 주문은 취소완료 목록으로 빠진다 - ordAmt − ordPayAmt = 11번가 부담 쿠폰(tmallApplyDscAmt 11,060), 수수료는 판매금액 기준(34,900 × 13% = 4,537) - fetch_orders: 목록 4개를 [기간, 기간+30일(오늘까지)] 7일씩 불러 주문일(결제일)이 기간 안인 줄만, 주문번호+순번 중복 제거 - SALE 금액 = ordAmt + 배송비(주문번호마다 최댓값을 가장 앞 줄에 한 번), ordAmt − ordPayAmt 는 discount_amount 에. 구매자 정보는 raw 에 넣지 않음 - replace_range(11st: 접두어) — 다시 받으면 취소·반품된 주문이 빠진다 - "해당 건이 없습니다"(-1)는 0건. 테스트 추가, 미구현 시험은 G마켓으로 Co-Authored-By: Claude Opus 5.5 --- app/modules/performance/adapters/elevenst.py | 111 ++++++++++++++++-- .../performance/tests/test_performance.py | 61 +++++++++- docs/PERFORMANCE_MODULE.md | 16 +++ 3 files changed, 178 insertions(+), 10 deletions(-) diff --git a/app/modules/performance/adapters/elevenst.py b/app/modules/performance/adapters/elevenst.py index c3cabf9..c0fe7e2 100644 --- a/app/modules/performance/adapters/elevenst.py +++ b/app/modules/performance/adapters/elevenst.py @@ -3,10 +3,14 @@ 인증: 셀러오피스(openapi.11st.co.kr → 서비스등록·확인)에서 발급한 Open API Key 를 요청 헤더 `openapikey` 에 넣는다. 셀러 API 는 등록한 IP 에서만 호출된다("Seller API 정보 수정"에서 서버 IP 등록, 셀링툴(사방넷 등)과 함께 쓸 수 있음). (공식 이용방법 openapi.11st.co.kr → OpenApiOperationGuide SERVICE_METHOD, 2026-09-30 확인) +응답은 XML(euc-kr). 없는 주소는 500 + resultCode -997 "등록된 API 정보가 존재하지 않습니다", 건이 없으면 -1 "해당 건이 없습니다". -연결 테스트는 결제완료(발주확인할) 주문 목록을 오늘 하루로 조회한다 — GET /rest/ordservices/complete/{시작}/{끝} -(yyyyMMddHHmm). 엔드포인트 상세 문서는 로그인 뒤에만 보여 널리 쓰이는 경로를 쓰고, 실제 호출 결과로 확인한다. -응답은 XML. 매출 수집(fetch_orders)은 맞출 셀러오피스 화면을 정한 뒤 구현한다. +매출(2026-09-30 실데이터로 확정 — 설정 화면 "11번가 원본 데이터 확인"): + - 주문 상태 목록 4개(결제완료·발송대기·배송중·배송완료)는 지금 그 상태인 주문만 준다. 배송완료 목록에 구매확정 주문도 남는다. + - SALE = 주문 한 줄, 날짜 = 결제일(ordStlEndDt, 없으면 주문일 ordDt), 금액 = ordAmt(판매금액, 11번가 부담 쿠폰 전) + + 배송비(dlvCst, 주문번호당 한 번). ordAmt − ordPayAmt = 11번가 부담 할인(tmallApplyDscAmt). 수수료는 판매금액 기준. + - 취소·반품된 주문은 목록에서 빠진다 → 기간을 통째로 다시 받아(replace_range) 매출에서 빠진다(취소 사건을 따로 만들지 않음). + - 정산 내역(/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd})은 정산확정일(stlDy) 기준 — 확인 도구에서만 쓴다. """ from __future__ import annotations @@ -14,9 +18,17 @@ from __future__ import annotations import re import xml.etree.ElementTree as ET from datetime import date, timedelta -from typing import Any +from typing import Any, Iterable -from .base import AdapterContext, AdapterError, ApiError, AuthFailed, CredentialField, MarketplaceAdapter +from .base import ( + AdapterContext, + AdapterError, + ApiError, + AuthFailed, + CredentialField, + MarketplaceAdapter, + SaleEvent, +) HOST = "https://api.11st.co.kr" @@ -114,10 +126,45 @@ def field_summary(records: list[dict[str, str]]) -> list[dict[str, Any]]: return list(names.values()) +# 매출 수집 — 주문 상태 목록 4개(지금 그 상태인 주문만 준다). 배송완료 목록에는 구매확정된 주문도 남는다(실데이터 확인). +# 취소·반품된 주문은 이 목록들에서 빠진다 → 기간을 통째로 다시 받아(replace_range) 매출에서 자연히 빠지게 한다. +ORDER_PATHS = ("/rest/ordservices/complete/{s}/{e}", "/rest/ordservices/packaging/{s}/{e}", + "/rest/ordservices/shipping/{s}/{e}", "/rest/ordservices/completed/{s}/{e}") +ORDER_STATUS = {"complete": "결제완료", "packaging": "발송대기", "shipping": "배송중", "completed": "배송완료"} +# 목록의 날짜 조건이 주문일인지 상태 변경일(배송완료일 등)인지 문서로 확인 못 해, 기간 뒤로 넉넉히 더 불러 +# 주문일로 거른다(나중에 배송완료된 주문도 빠지지 않게). +LOOKAHEAD_DAYS = 30 +EVENT_PREFIX = "11st:" +# raw 에 남길 항목 — 금액·날짜·상태·상품만(구매자 정보 제외) +RAW_KEEP = ("ordNo", "ordPrdSeq", "ordDt", "ordStlEndDt", "ordAmt", "ordPayAmt", "dlvCst", "ordQty", "prdNo", + "atmtBuyCnfrmYN", "pocnfrmDt", "selPrc", "ordPrdStat") + + +def _won(value: Any) -> int: + try: + return int(round(float(str(value or "0").replace(",", "")))) + except ValueError: + return 0 + + +def _day(value: Any) -> date | None: + """"2026-09-09 15:13:16" / "2026/09/09" / "20260909" → date.""" + s = re.sub(r"[^0-9]", "", str(value or ""))[:8] + if len(s) < 8: + return None + try: + return date(int(s[:4]), int(s[4:6]), int(s[6:8])) + except ValueError: + return None + + class ElevenstAdapter(MarketplaceAdapter): code = "elevenst" name = "11번가" auth_type = "api_key" + implemented = True + replace_range = True + event_prefix = EVENT_PREFIX docs_url = "https://openapi.11st.co.kr/" note = ("11번가 셀러오피스 → 오픈API 에서 발급한 키를 입력합니다. 셀러 API 는 등록한 IP 에서만 호출되므로 " "'Seller API 정보 수정 → IP 직접 입력'에 이 서버의 외부 IP 를 넣어야 합니다.") @@ -127,6 +174,57 @@ class ElevenstAdapter(MarketplaceAdapter): CredentialField("api_key", "Open API Key", secret=True), ] + # ── 수집 ────────────────────────────────────────────── + def fetch_orders(self, ctx: AdapterContext, start: date, end: date) -> Iterable[dict[str, Any]]: + """주문 상태 목록 4개를 [start, end+30일(오늘까지)] 7일씩 불러 주문일이 [start, end] 인 줄만. + 같은 줄(주문번호+순번)이 두 목록에 나오면(조회 사이 상태 변경) 한 번만. + 배송비는 주문번호마다 줄들의 dlvCst 최댓값을 가장 앞 순번 줄에 한 번(_ship).""" + from app.timezone import today_kst # noqa: WPS433 + + hi = max(end, min(end + timedelta(days=LOOKAHEAD_DAYS), today_kst())) + seen: set[str] = set() + rows: list[dict[str, Any]] = [] + for tmpl in ORDER_PATHS: + status = ORDER_STATUS[tmpl.split("/")[3]] + s = start + while s <= hi: + e = min(hi, s + timedelta(days=PROBE_CHUNK_DAYS - 1)) + body = self._get(ctx, tmpl.format(s=s.strftime("%Y%m%d") + "0000", e=e.strftime("%Y%m%d") + "2359")) + for r in xml_records(body): + key = f"{r.get('ordNo')}-{r.get('ordPrdSeq')}" + day = _day(r.get("ordStlEndDt") or r.get("ordDt")) + if not r.get("ordNo") or key in seen or day is None or not (start <= day <= end): + continue + seen.add(key) + rows.append({**r, "_status": status}) + s = e + timedelta(days=1) + ship: dict[str, tuple[int, int]] = {} # 주문번호 → (배송비, 가장 앞 순번) + for r in rows: + oid, seq = str(r["ordNo"]), _won(r.get("ordPrdSeq")) + cur = ship.get(oid, (0, seq)) + ship[oid] = (max(cur[0], _won(r.get("dlvCst"))), min(cur[1], seq)) + for r in rows: + fee, first = ship[str(r["ordNo"])] + yield {**r, "_ship": fee if _won(r.get("ordPrdSeq")) == first else 0} + + def normalize_order(self, r: dict[str, Any]) -> list[SaleEvent]: + """주문 한 줄 → SALE. 금액 = 판매금액(ordAmt, 11번가 부담 쿠폰 전) + 배송비(_ship, 주문번호당 한 줄). + 수수료가 판매금액 기준이라(34,900 × 13% = 4,537, 정산 실데이터) 판매자 매출은 할인 전 금액으로 본다.""" + oid, seq = str(r.get("ordNo") or ""), str(r.get("ordPrdSeq") or "") + day = _day(r.get("ordStlEndDt") or r.get("ordDt")) + if not oid or day is None: + return [] + amount = _won(r.get("ordAmt")) + _won(r.get("_ship")) + opt = str(r.get("slctPrdOptNm") or "") + return [SaleEvent( + event_type="SALE", external_event_id=f"{EVENT_PREFIX}{oid}-{seq}", external_order_id=oid, + external_line_id=seq, order_date=_day(r.get("ordDt")), payment_date=day, event_date=day, + amount=max(0, amount), product_name=str(r.get("prdNm") or "")[:200], option_name=opt[:200], + quantity=int(_won(r.get("ordQty"))), discount_amount=max(0, _won(r.get("ordAmt")) - _won(r.get("ordPayAmt"))), + order_status=str(r.get("_status") or ""), + raw={k: r.get(k) for k in RAW_KEEP if r.get(k) not in (None, "")}, + )] + def _get(self, ctx: AdapterContext, path: str) -> bytes: import httpx # 지연 import @@ -185,5 +283,4 @@ class ElevenstAdapter(MarketplaceAdapter): d = today_kst().strftime("%Y%m%d") body = self._get(ctx, f"/rest/ordservices/complete/{d}0000/{d}2359") _, _, orders = xml_result(body) - return (f"11번가 연결 정상(주문 조회 권한 확인, 오늘 결제완료 {orders}건). " - "매출 수집은 다음 단계에서 구현됩니다.") + return f"11번가 연결 정상(주문 조회 권한 확인, 오늘 결제완료 {orders}건)." diff --git a/app/modules/performance/tests/test_performance.py b/app/modules/performance/tests/test_performance.py index c0a7820..5782473 100644 --- a/app/modules/performance/tests/test_performance.py +++ b/app/modules/performance/tests/test_performance.py @@ -383,10 +383,12 @@ def test_not_implemented_and_mock(): st = FakeStore() creds = CredentialService(st, lambda: ring()) svc = SyncService(st, creds) - r = svc.sync_marketplace("elevenst", date(2026, 9, 29), date(2026, 9, 29)) + gm = next(a for a in all_adapters() if a.code == "gmarket") + r = svc.sync_marketplace("gmarket", date(2026, 9, 29), date(2026, 9, 29)) assert r["status"] == "not_configured" # 키 미입력 - creds.save(next(a for a in all_adapters() if a.code == "elevenst"), {"api_key": "k-123456"}) - r = svc.sync_marketplace("elevenst", date(2026, 9, 29), date(2026, 9, 29)) + secret = next(f.key for f in gm.visible_fields() if f.secret) + creds.save(gm, {f.key: ("k-123456" if f.key == secret else "v") for f in gm.visible_fields()}) + r = svc.sync_marketplace("gmarket", date(2026, 9, 29), date(2026, 9, 29)) assert r["status"] == "not_implemented" and "k-123456" not in r["message"] import httpx orig_get, httpx.get = httpx.get, (lambda url, headers=None, timeout=None: httpx.Response(200, content=b"")) @@ -884,6 +886,59 @@ def test_elevenst_connection(): httpx.get = orig +def test_elevenst_collect_sales(): + """11번가 매출 = 주문 상태 목록(결제완료·발송대기·배송중·배송완료)의 줄, 결제일(없으면 주문일) 기준, + 금액 = ordAmt + 배송비(주문번호마다 최댓값을 가장 앞 줄에 한 번). 같은 줄이 두 목록에 나와도 한 번, 기간 밖 주문일은 제외. + 실데이터 9/9: ordAmt 34,900 / ordPayAmt 34,900, 9/10: ordAmt 83,800 / ordPayAmt 72,740(11번가 쿠폰 11,060).""" + import httpx + + import app.modules.performance.sync as syncmod + import app.timezone as _tz + from app.modules.performance.adapters import elevenst as ev + + def line(no, seq, day, amt, pay, ship=0, qty=1): + return (f"{no}{seq}{day} 15:13:16" + f"{amt}{pay}{ship}{qty}" + f"밀폐용기홍길동18550503") + completed = ("" + line("20260909099415322", 1, "2026-09-09", 34900, 34900) + + line("20260910099718265", 1, "2026-09-10", 83800, 72740, qty=2) + + line("20260910099718265", 2, "2026-09-10", 10000, 10000, ship=3000) + + line("20260801000000001", 1, "2026-08-01", 5000, 5000) + "").encode() + packaging = ("" + line("20260909099415322", 1, "2026-09-09", 34900, 34900) + + line("20260911000000002", 1, "2026-09-11", 20000, 20000, ship=3000) + "").encode() + empty = "-1해당 건이 없습니다.".encode() + calls = [] + + def route(url, headers=None, timeout=None): + calls.append(url) + if "/ordservices/completed/" in url: + return httpx.Response(200, content=completed) + if "/ordservices/packaging/" in url: + return httpx.Response(200, content=packaging) + return httpx.Response(200, content=empty) + + st = FakeStore() + creds = CredentialService(st, lambda: ring()) + creds.save(next(a for a in all_adapters() if a.code == "elevenst"), {"api_key": "KEY-11ST"}) + orig, orig_today = httpx.get, _tz.today_kst + httpx.get, _tz.today_kst = route, (lambda: date(2026, 9, 30)) + try: + r = SyncService(st, creds).sync_marketplace("elevenst", date(2026, 9, 9), date(2026, 9, 11)) + finally: + httpx.get, _tz.today_kst = orig, orig_today + assert r["ok"], r + ev_ = {k[2]: v for k, v in st.events.items() if k[0] == "elevenst"} + assert set(ev_) == {"11st:20260909099415322-1", "11st:20260910099718265-1", "11st:20260910099718265-2", + "11st:20260911000000002-1"} # 중복 1번, 8/1 주문 제외 + assert ev_["11st:20260909099415322-1"]["amount"] == 34_900 and ev_["11st:20260909099415322-1"]["sales_date"] == date(2026, 9, 9) + assert ev_["11st:20260910099718265-1"]["amount"] == 83_800 + 3_000 # 2번 줄의 배송비를 앞 줄에 한 번 + assert ev_["11st:20260910099718265-1"]["discount_amount"] == 11_060 + assert ev_["11st:20260910099718265-2"]["amount"] == 10_000 + assert ev_["11st:20260911000000002-1"]["amount"] == 23_000 + assert "홍길동" not in repr(st.events) and "18550503" not in repr(st.events) # 구매자 정보 미저장 + assert any("/20260930" in u for u in calls) and not any("/20261001" in u for u in calls) # 오늘까지만 더 불러옴 + + def test_registry_and_event_validation(): codes = [a.code for a in all_adapters()] assert len(codes) == len(set(codes)) == 10 diff --git a/docs/PERFORMANCE_MODULE.md b/docs/PERFORMANCE_MODULE.md index 7815cac..4ff165b 100644 --- a/docs/PERFORMANCE_MODULE.md +++ b/docs/PERFORMANCE_MODULE.md @@ -83,6 +83,22 @@ 그 주문의 마지막 클레임 품목에 한 번 더한다. 톡체크아웃·자체몰의 환불 기록 없는 취소는 카페24 환불합계에 없음 (9/4: 98,700 + 네이버페이 19,900 + 배송비 3,500 = 122,100 / 9/16: 톡체크아웃 취소 9,900 제외 → 201,100). +### 11번가 (`adapters/elevenst.py`, 구현됨) + +- 인증: 셀러오피스 Open API Key → 헤더 `openapikey`. **셀러 API 는 등록 IP 에서만** 호출된다(Seller API 정보 수정 → + IP 직접 입력에 운영 서버 외부 IP, 셀링툴 사방넷과 함께 사용 가능). 응답은 XML(euc-kr 선언 → 직접 디코딩). +- 없는 주소 = 500 + `-997 등록된 API 정보가 존재하지 않습니다`, 건 없음 = `-1 해당 건이 없습니다`(0건으로 처리). +- 상세 문서가 로그인 뒤에만 있어 설정 화면 **"11번가 원본 데이터 확인"**(`reconcile(day, to)`, 후보 주소별 동작·항목 합계, + 개인정보 값 숨김)으로 실데이터를 보고 확정했다(2026-09-30). +- 주문 상태 목록 4개(`/rest/ordservices/complete|packaging|shipping|completed/{yyyyMMddHHmm}/{…}`)는 **지금 그 상태인 주문만** + 준다. 배송완료 목록에 구매확정 주문도 남는다. 취소·반품된 주문은 목록에서 빠지고 `/rest/claimservice/canceledorders|…` 에 있다. +- SALE = 주문 한 줄(`11st:{ordNo}-{ordPrdSeq}`), 날짜 = 결제일(`ordStlEndDt`, 없으면 주문일 `ordDt`), 금액 = `ordAmt` + (판매금액, 11번가 부담 쿠폰 전) + 배송비(`dlvCst`, 주문번호마다 최댓값을 가장 앞 줄에 한 번). `ordAmt − ordPayAmt` = 11번가 + 부담 할인(`discount_amount` 에 기록). 수수료는 판매금액 기준(정산 `selFee` = 34,900 × 13%). +- `replace_range` — 기간을 통째로 다시 받아 취소·반품된 주문이 매출에서 빠진다(취소 사건을 따로 만들지 않음 → 지난 날짜 + 금액이 나중에 줄 수 있음). 목록의 날짜 조건이 주문일인지 상태 변경일인지 몰라 **기간 뒤 30일(오늘까지)을 더 불러 주문일로 거른다.** +- 정산 내역 `/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd}` 은 정산확정일(`stlDy`) 기준 — 확인 도구에서만 쓴다. + ### 연동 단계 체크리스트(쇼핑몰마다) - 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 API·날짜 필드 확인