Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
45 KiB
실적(쇼핑몰 통합 매출) 모듈
app/modules/performance/· DBperformance_db· URL/performance/· 권한키performance여러 쇼핑몰의 주문/매출을 수집 → DB 저장 → 화면 조회 구조로 한 화면에서 본다. API 장애·호출 제한이 있어도 이미 저장된 실적은 그대로 보인다.
1. 구조 — 네 영역 분리
| 영역 | 파일 | 역할 |
|---|---|---|
| ① 쇼핑몰 API 수집 | adapters/base.py, adapters/<쇼핑몰>.py, adapters/registry.py, sync.py |
어댑터 = 쇼핑몰 하나. sync.py 가 어댑터 결과를 공통 사건으로 DB 저장 |
| ② 인증정보·보안 | security/crypto.py, security/redact.py, credentials.py |
AES-256-GCM 암·복호화, 비밀값 가리기, 저장/화면 요약/재암호화 |
| ③ 계산·저장 | calc.py, db.py |
기간·주(월~일)·수수료·반올림·집계(순수 함수) / performance_db |
| ④ 화면 | dashboard.py, router.py, common.py, templates/performance/, static/performance.{css,js} |
화면 데이터 조립, 라우트·권한, UI |
쇼핑몰 추가 = 어댑터 파일 하나 + registry.py 한 줄 + SQL seed 한 줄(perf_marketplaces). 대시보드·설정·동기화는 자동으로 붙는다.
2. 어댑터 공통 인터페이스 (MarketplaceAdapter)
| 메서드 | 설명 |
|---|---|
credential_fields() |
설정 화면 입력칸 정의(CredentialField: key/label/secret/required/help, internal=토큰 등 화면 비표시) |
validate_credentials(values) |
저장 전 검사(값을 오류 문구에 넣지 않음) |
authenticate(ctx) / refresh_token(ctx) |
토큰 발급·갱신. 새 토큰은 ctx.credentials.set(key, value) → 자동 암호화 저장 |
test_connection(ctx) |
성공 문구 반환, 실패는 AdapterError 계열 |
fetch_orders / fetch_refunds(ctx, start, end) |
원본 수집 |
normalize_order / normalize_refund(raw) |
원본 → SaleEvent 목록 |
collect(ctx, start, end) |
위를 묶어 (원본 건수, 사건 목록) — sync 서비스가 부른다 |
오류 클래스 = 연결 상태: NotConfigured(인증정보 미설정) · AuthFailed(인증 실패) · TokenExpired · ApiError · NotImplementedYet(연동 준비 중).
연동 현황: 카페24·11번가·네이버 스마트스토어·GS샵·토스쇼핑·쿠팡·카카오 = 구현됨(쿠팡은 2026-10-12 — 매출 규칙은 WING 실데이터 대조 전, 카카오는 2026-10-13 — 판매자센터 대조 전), 나머지 3개는 입력칸만 정의(수집은 NotImplementedYet). 쇼핑몰별 입력칸은
연동 단계에서 공식 API 문서로 확정한다.
카페24 (adapters/cafe24.py, 구현됨)
auth_type="shared" — 기존 app/integrations/cafe24 OAuth 토큰(cafe24_db)과 클라이언트(재시도·429·토큰 자동 갱신)를
재사용한다. 토큰에 mall.read_order 가 있어야 한다(DEFAULT_SCOPES 포함, 권한 추가 후 카페24 상품관리 → 시스템에서 재연결).
카페24 관리자 "일별 매출내역"과 같은 기준으로 센다(처음의 품목 결제금액 방식은 배송비가 빠지고 환불 날짜 기준이 달라 화면과 맞지 않아 교체).
| 사건 | 조회 | 금액·날짜 |
|---|---|---|
| SALE(결제합계) | GET /admin/orders date_type=pay_date, embed=items, paid=T |
+(실결제금액 + 적립금 + 예치금 + 네이버포인트), initial_order_amount + 주문 naver_point(결제 당시 금액 — 환불을 따로 빼므로 취소 후 금액 X), 결제일. 주문 1건 = 사건 1건({order_id}-PAY) |
| 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 |
- 할인 = 회원·세트상품·앱·마켓 기타·배송비 할인, 쿠폰 = 상품쿠폰 + 배송비쿠폰(
DISCOUNT_FIELDS/COUPON_FIELDS). - 기간 교체(
replace_range=True): 결제·환불 모두 기간 안 날짜로 조회되므로 동기화 때 그 기간의 카페24 실데이터를 지우고 새로 넣는다(한 트랜잭션, 테스트 데이터 제외). 규칙이 바뀌어도 예전 행이 남지 않는다 → 규칙을 고친 뒤에는 같은 기간을 [과거 매출 가져오기]로 다시 받으면 된다. - 주의 —
market_id는 외부 마켓만이 아니라 자체몰 주문 채널·간편결제도 담는다(실데이터 확인 2026-09-30:mobile=모바일웹,NCHECKOUT=네이버페이,KAKAOPAY=톡체크아웃). 이들은SELF_CHANNELS로 카페24 열. 대조 도구의 "주문 채널별" 표가 채널마다 자체몰 채널 / 외부 마켓 / 알 수 없는 채널(→ 카페24 열)을 보여 준다.MARKET_MAP에는 결제수단과 헷갈릴 수 있는 일반 이름(naver, kakao)을 넣지 않는다. - 현재
MARKET_MAP은 비어 있다 — 이 쇼핑몰은 카페24 마켓 통합관리를 쓰지 않는다(2026-09 사용자 확인). 카페24로 들어온 주문은 모두 카페24 열이고 설정 화면의 "카페24 경유" 표시도 나오지 않는다. 아래는 나중에 마켓 통합관리를 쓸 때의 동작. - 마켓 연동 주문은 해당 쇼핑몰 열로: 자체몰 채널은 카페24 열. 카페24 마켓 통합관리가 가져온
다른 마켓 주문은
MARKET_MAP(market_id 또는 order_place_id → 우리 쇼핑몰 코드)으로 네이버·쿠팡·11번가 등 열에 넣는다 (SaleEvent.marketplace_code). 연결표에 없는 마켓은 카페24 열 — 전체 합계는 항상 카페24 일별 매출내역과 같다 (9/28 대조로 자체몰+마켓 합계가 모든 줄에서 일치 확인). 환불은 원 주문을 100건씩 조회해 같은 열로. 네이버페이는 자체몰. - 카페24 가 만든 사건 ID 는 모두
c24:접두어(event_prefix) — 다시 받을 때 카페24 열 + 다른 열의c24:행만 교체해 그 쇼핑몰의 직접 연동분은 건드리지 않는다. 어떤 쇼핑몰을 직접 API 로 연동하면 같은 주문을 두 번 받지 않도록 그 마켓을MARKET_MAP에서 빼야 한다. 설정 화면 API 설정 칸의 "카페24 경유" 표시 = 카페24 수집 때 함께 반영되는 쇼핑몰. - 실제 market_id 값은 "카페24 매출 대조"의 마켓별 표(market_id / 주문경로 / 반영 열)로 확인하고, "(연결표 없음)"으로 나오는
마켓이 우리 쇼핑몰이면
MARKET_MAP에 추가한다. - 60일 단위 분할(한 호출 3개월 미만), orders limit 1000 / refunds limit 500 페이지. 개인정보는 저장하지 않는다.
- 카페24 매출 대조(설정 화면,
GET /api/marketplaces/cafe24/reconcile?date=): 그날 결제 주문·환불을 카페24 화면 열 순서대로 (주문수·품목수·상품구매금액·배송비·할인·쿠폰·결제합계·환불합계·순매출) 자체몰/다른 마켓으로 나눠 합산. 저장하지 않음. 카페24 화면과 다른 줄이 있으면 할인 항목 구성·마켓 포함 여부를 이 결과로 조정한다. - 일별 한 번에 비교(같은 카드,
GET /api/marketplaces/{code}/daily-check?from=&to=&live=1, 최대 62일): 카페24 일별 매출내역 표를 붙여 넣으면(날짜 + 뒤 세 숫자 = 결제합계·환불합계·순매출, 첫 숫자 = 주문수) 날짜마다 저장값(c24:사건 전체, 다른 마켓 열 포함)과 지금 API·현재 규칙으로 다시 계산한 값(adapter.collect, 저장 안 함)을 비교한다. 저장값만 틀림 → 예전 규칙으로 받은 것([다시 가져오기] 버튼), API 값도 틀림 → 규칙 차이(결제/환불) → 날짜 클릭으로 그날 대조. 날짜를 눌러 연 대조 표에는 붙여넣은 카페24 열(주문수·품목수·상품구매금액·배송비·할인·쿠폰·실결제·적립금·예치금·결제·환불·순매출)과 열별 차이가 같이 나온다. - 결제합계 = 실결제금액 + 적립금 + 예치금 + 네이버포인트(initial_order_amount 의 payment_amount·points_spent_amount· credits_spent_amount + 주문의 naver_point). "상품구매금액 + 배송비 − 할인 − 쿠폰"은 할인 필드에 안 잡히는 차이가 있어 쓰지 않음 (2026-09-23: 카페24 1,874,738 = 1,713,128 + 10,110 + 151,500, 상품식 1,874,800). 네 값이 모두 0인 주문도 0원 (9/25 가상계좌·휴대폰 9,900 — 카페24도 0원).
- 환불 목록 없는 취소는 네이버페이(NCHECKOUT)만 환불합계에 넣는다. 주문 전체가 취소·반품되면 배송비(− 배송비 할인·쿠폰)도 그 주문의 마지막 클레임 품목에 한 번 더한다. 톡체크아웃·자체몰의 환불 기록 없는 취소는 카페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}), 날짜 = 결제일.- 정산된 주문: 정산 내역(
/rest/settlement/settlementList/{yyyyMMdd}/{yyyyMMdd}, 정산확정일stlDy기준 → 기간 뒤 45일 (오늘까지)을 더 불러 결제일ordStlEndDt로 거름)의 판매금액합계selPrcAmt합. 셀러오피스 "판매 상세내역"과 같고 배송비(도서산간 등)가 별도 줄로 들어 있다 — 9/10 주문 83,800 + 배송비 줄 3,000 = 86,800(주문 목록dlvCst는 0). - 정산 전 주문: 주문 상태 목록의
ordAmt(판매금액, 11번가 부담 쿠폰 전) + 배송비(dlvCst최댓값 한 번). 기간 뒤 30일을 더 불러 주문일로 거른다. 정산되면 다음 업데이트 때 정산 값으로 바뀐다. ordAmt − ordPayAmt= 정산cupnAmt= 11번가 부담 할인(discount_amount). 수수료는 판매금액 기준(34,900 × 13% = 4,537).
- 정산된 주문: 정산 내역(
replace_range— 기간을 통째로 다시 받아 취소·반품된 주문이 매출에서 빠진다(취소 사건을 따로 만들지 않음 → 지난 날짜 금액이 나중에 줄 수 있음). 구매자 이름·아이디·연락처는 저장하지 않는다.
네이버 스마트스토어 (adapters/naver.py, 구현됨)
- 인증: 커머스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초 쉬고 다시. - 매출 규칙 = 스마트스토어센터 판매분석 "판매금액(총)"(2026-09-30 사용자 확인): 판매분석 9/1 매출 4,455,600원 = 판매금액(총) —
할인(판매자·네이버 부담) 뒤 금액, 배송비(332,486원)는 별도, 결제 뒤 취소·반품도 결제일에 포함하고 환불(346,340원)은 환불일에
따로 빼서 판매금액(순) 4,109,260원(예: 9/1 결제 0원인 상품에 환불 5건 75,040원). 주방세제 2.3L 16,640 = 17,900 − 네이버 부담 1,260.
처음 규칙(취소·반품 빼고 배송비 더함)은 4,245,300원으로 달랐다.
- SALE = 주문 하나(
naver:{orderId}), 날짜 = 결제일(order.paymentDate), 금액 = 상품주문totalPaymentAmount합(배송비 제외), 할인 =productDiscountAmount합. 결제 뒤 취소·반품(CANCELED·RETURNED)도 포함, 입금대기·미입금 취소만 뺀다 → 지난 날짜 매출이 나중에 줄지 않는다.replace_range. - 환불(판매금액(순))은 아직 사건으로 만들지 않는다 — 필요하면 클레임 완료일 기준 CANCEL/RETURN 을 추가.
- SALE = 주문 하나(
- 설정 화면 "쇼핑몰 원본 데이터 확인"(네이버 선택): 결제일 기준 상품주문 전체의 항목별 합계, 상태별 합계, 날짜별 매출·그중 결제 뒤 취소/반품(참고)·배송비(참고). 개인정보(주문자·수령인·주소·연락처·메모)는 값 없이 이름만.
GS샵 (adapters/gsshop.py, 구현됨)
- 문서: 협력사 포털 → 제휴 API → 개발가이드(
partners.gsshop.com/api/apiDevGuide, 본문은/docs/withgs-api-docs.htmlRedoc). - 인증: 헤더
supCd(협력사코드) +token= base64(AES256(yyyyMMddHHmmss+ 협력사코드)), 키는 제휴 API 메인 화면(로그인 후). 키 = 포털 제휴 API 메인의 운영 KEY(개발 KEY 아님). 문서에 암호화 모드·키를 바이트로 쓰는 법이 없어 키 변형(글자 그대로 / 16진수 풀기 / 앞 32자,key_variants) × 모드(CBC·IV=키 앞 16 → ECB → CBC·IV=0) 순서로 시도하고 통과한 조합을 기억. 토큰이 틀리면 HTTP 200 +{"result":"fail","code":"401 UNAUTHORIZED"}. 운영 주소withgs-api.gsshop.com(문서 예시atwithgs-api는 테스트용 — 두 곳 모두 응답). 입력칸 키는 처음 만든vendor_code·api_key그대로(라벨만 협력사코드·AES256 키). - 매출:
GET /api/v2/settlement/out/sales/period?supCode&fromDate&toDate&pageIdx&rowsPerPage— 매출인식일 기준, 한 번에 10일, 쪽당 1만 건,{data, hasMorePage, totalCount}. 배송비는/shippingFee/period. 응답 줄 항목 이름이 문서 예시에 없어 ("property1") 실데이터로 확인(2026-09-30, 9/3):saleAwareDt·ordNo·ordItemNo·ordType(SALE…)·prdNm·chrQty·salePrice(할인 전, 줄 합계)·dcTotAmt·custChrAmt(= salePrice − dcTotAmt, 고객 결제금액)·supGiveAmt(협력사 지급액). 9/3: 211,100 − 19,528 = 191,572, 지급 179,435, 배송비 내역 7,000. - 주문일 기준 조회 API 는 없다 — 협력사 포털 주문 통계(총주문금액·주문일, 할인 후 금액: 45,900 × 85% = 39,015)와는 날짜 기준이 달라 날마다 똑같이 맞지 않는다(매출인식일 = 정산 기준).
- 매출 규칙: 매출 내역 한 줄 = 사건(
gs:{ordNo}-{ordItemNo}-{ordType}-{saleAwareDt}), 날짜 = 매출인식일, 금액 =supGiveAmt(협력사 지급액) = 협력사 포털 주문 통계의 금액(2026-09-30 확인: 6호세트 포털 176,715 ÷ 9 = 19,635 = API supGiveAmt 19,635 — 판매가 23,100·고객 결제 20,330. 7호세트 45,900 × 85%, 주부체험 9,900 × 90% — 상품마다 GS 수수료율이 다름). 9/1~9/29 지급액 4,972,689 vs 포털 순주문 4,823,074 — 남는 차이는 주문일 ↔ 매출인식일·취소분. 이미 GS 수수료를 뺀 금액이라 GS샵 수수료율은 0%. 배송비 제외,ordType이 SALE 이 아니면 RETURN 음수.replace_range. 원본 데이터 확인에 날짜별 현재 규칙 매출·취소/반품·배송비(참고).
토스쇼핑 (adapters/toss.py, 구현됨)
- 문서:
https://shopping-docs.toss.im/dev(공개, 전체 목록llms.txt, 쪽 주소 뒤.md= 원문). 문의는 문서의 디스코드. - 인증: 토스쇼핑 파트너스 → 상점 이름 > 가맹점·계정 관리 > 자체 개발 → [키 발급](호출 IP 입력 — 운영 서버 외부 IP, 등록된
IP 만 호출 가능) → Access Key·Secret Key.
POST https://oauth2.cert.toss.im/token(form:grant_type=client_credentials·client_id=Access Key·client_secret=Secret Key·scope=toss-shopping-fep:write). 토큰expires_in약 1년 — 문서가 매번 발급하면 이용이 제한될 수 있다고 해서access_token·access_token_expires_at(internal, 암호화)으로 저장해 재사용, 만료 1시간 전·401 이면 새로. [연결 테스트]는 입력값으로 시험하므로 항상 새 토큰. 입력칸 키는 처음 만든api_key(Access Key)·api_secret(Secret Key) 그대로 (라벨만 변경 — 예전 "판매자 ID" 칸은 없앰). - API:
https://shopping-fep.toss.im,Authorization: Bearer {token}. 오류가 HTTP 200 +resultType: "FAIL"(error.errorCode·reason)로도 온다. 읽기 초당 50회(넘으면TOO_MANY_REQUEST) → 호출 간격 0.1초, 제한이면 1·2·4초 쉬고 다시. - 수집: 주문 내역 조회
GET /api/v3/shopping-fep/orders/v2?startDate&endDate&limit=50&nextCursor— 한 번에 31일, 상태 생략 = 전체, 커서(nextCursornull = 끝). 줄 = 주문상품(orderProductId), 주문 =orderId. 금액 항목:price(판매가 × 수량)·originPrice(정상가 × 수량)·totalDiscountPrice(=tossShoppingDiscount+tossPayDiscount)·tossPayPoint·deliveryFee(묶음deliveryFeeGroupId마다). 결제일 필드는 따로 없고orderedAt(주문 = 결제) ·canceledAt·confirmedAt. - 매출 규칙 = 파트너스 "순 거래액" = 매출 − 환불(2026-10-01 사용자 지정, 9/6 화면: 매출 29,600 − 환불 11,900 = 순 거래액 17,700).
- 매출 SALE = 주문 하나(
toss:{orderId}), 날짜 =orderedAt의 한국 날짜, 금액 =price합(할인 전, 배송비 제외), 할인은discount_amount로만. 결제 전(BEFORE_PAYMENT)만 빼고 나중에 취소·반품된 주문도 주문일 매출에 둔다(화면 "매출"도 환불 전). - 환불 = 환불일에 뺀다, 주문상품마다 한 번(사건 ID
toss:R{orderProductId}),merge_refunds: ① 클레임 목록GET /api/v3/shopping-fep/claims?size=100&nextToken(유형·상태 조건 없음 = 전체 — 이 API 는 그 밖엔 날짜로 못 거른다, 최대 1만 건)의 환불 완료(isRefunded)CANCEL·RETURN— 날짜 =refundedDt. 반품은 이것뿐(주문 내역엔 반품 완료 날짜 없음). 사건 종류 CANCEL / RETURN. ② 클레임이 없는 결제취소(CANCELED_PAYMENT) — 날짜 = 주문 내역canceledAt(결제완료 단계 고객 취소는 클레임이 안 생김). 클레임이 있는 주문상품은 클레임 날짜만 쓴다(그 날짜가 기간 밖이어도 취소 시각으로 다시 넣지 않음 — 날짜가 흔들리지 않게). 금액 = 그 주문상품의price(판매가 × 수량 — 매출과 같은 기준), 주문 내역에 없으면 클레임order.price. 다른 날 주문의 환불을 잡으려고 수집 때 기간 앞 90일(CANCEL_LOOKBACK_DAYS) 주문 내역도 부른다. 교환·미환불 클레임은 제외. - 수집은
collect를 직접 구현(주문 내역을 매출·환불 금액·취소 시각에 함께 쓰려고). 진행 막대 = 기간 주문 구간 + 앞 90일 구간 + 클레임 1.replace_range(접두어toss:— 매출·환불 함께 교체). 개인정보(주문자·수령인·주소·요청사항·수거 주소·요청 사유·송장)는 저장 안 함.
- 매출 SALE = 주문 하나(
- 실데이터 대조(2026-10-01, 9/6): 매출 29,600 = 주문 2건
price합 일치(orderedAt은 시간대 없이 한국 시간 — 17:57 주문도 9/6). 환불 11,900 = 9/5 주문(276435356)을 9/6 취소 — 클레임CANCEL/COMPLETEDrefundedDt9/6 과canceledAt9/6 둘 다 일치, 정산 건별 REFUND 에는 없다(9/6 거래일 정산 = PAY 2줄 + 배송비 2줄뿐 — 구매확정 전 취소는 정산에 안 올라옴) → 정산은 환불에 쓰지 않는다. - 원본 데이터 확인(토스쇼핑): 날짜별 매출(주문일)·환불(환불일)·순 거래액(
day_cols, = 저장되는 값) + 환불 출처별 비교 (refund_candidates: 적용 규칙 · 클레임 환불 완료 · 주문 취소 시각 · 정산 REFUND(참고), 날짜별 합계 + 건별 주문번호·금액·메모)- 주문 상태별·클레임·정산 항목 합계. 화면 숫자와 다르면 출처별 열로 어느 쪽이 빠졌는지 본다.
- 정산 줄의 다른 항목: 셀러 부담 쿠폰
shoppingDiscountMerchant, 정산 지급액settlementAmount, 수수료payFee·productFee.
쿠팡 (adapters/coupang.py, 구현됨 — 규칙 대조 전)
-
시간 초과 대응(2026-10-13): 31일치 배송완료(FINAL_DELIVERY) 발주서처럼 건수가 많으면 쿠팡 게이트웨이가 504 "Request timed out" 을 낸다. 502·503·504·응답 시간 초과(
GatewayTimeout)면 그 구간을 반으로(31→15→7→3→1일) 줄여 다시 부르고, 줄인 크기는 같은 상태의 다음 구간에도 쓴다(로켓그로스도 같은 방식). 하루 구간도 계속 시간 초과면 3·6초 쉬고 2번 더 부른 뒤 실패. 오류 문구 끝에 실패한 구간·상태[주문일 …~…, 상태 …]를 붙인다. -
맞출 화면(2026-10-12 사용자 지정): WING → 비즈니스 인사이트 → 판매분석, 판매자배송 + 로켓그로스, 날짜 선택 → 매출(원). 판매분석 자체를 주는 Open API 는 없다(developers.coupang.com API 목록 확인) → 주문 API 두 개를 결제일(한국 시간) 로 합친다.
-
인증: Vendor ID + Access Key + Secret Key, 요청마다 CEA HMAC 서명. 키는 '자체개발' + 이 서버 IP 를 허용 IP 에.
-
판매자배송: 발주서 목록(일단위 페이징)
/v5/vendors/{vendorId}/ordersheets— 주문일(createdAtFrom/To,yyyy-mm-dd+09:00, 31일까지) × 상태 6개(ACCEPT·INSTRUCT·DEPARTURE·DELIVERING·FINAL_DELIVERY·NONE_TRACKING), 50건씩nextToken. 주문일 하루 앞부터 불러paidAt으로 다시 거른다. 줄 금액 =orderPrice(판매가 × 수량, 쿠폰 할인 전), 같은 발주서·줄은 한 번만. 결제 뒤 취소된 줄 (canceled·cancelCount)도 결제일 매출(지난 날짜가 줄지 않게, 원본 확인에 따로). 완료 반품·결제 전 취소는 목록에 없다(쿠팡 안내). -
로켓그로스:
/rg_open_api/apis/api/v1/vendors/{vendorId}/rg/orders?paidDateFrom=yyyymmdd&paidDateTo=— 결제일, 30일까지, 분당 50회 (호출 간격 1.25초),paidAt은 밀리초. 줄 금액 =unitSalesPrice × salesQuantity. 출고된 주문만 나온다(쿠팡 안내 — 오늘 주문은 늦게 잡힐 수 있음). -
사건: 주문 하나 = SALE(판매자배송
coupang:{orderId}, 로켓그로스coupang:rg:{orderId}),replace_range(접두어coupang:). 배송비는 매출 제외. 구매자·수령자·통관·배송 메모·직접 입력 항목은 저장·표시하지 않는다. -
원본 데이터 확인(쿠팡): 날짜별 매출 후보 — ① 현재 규칙(판매자배송 판매가 + 로켓그로스) ② 판매자배송 판매가 ③ 할인 뒤 ④ 취소분 뺀 값 ⑤ 로켓그로스 + 판매량 — 를 WING 판매분석의 같은 날 "매출(원)"·"판매량" 과 비교해 규칙을 확정한다(
candidates_title). 로켓그로스만 거부돼도 판매자배송 결과는 보인다.
카카오 (adapters/kakao.py, 구현됨 — 판매자센터 대조 전, 2026-10-13)
- 카카오쇼핑 Open API(shopping-developers.kakao.com). 주소
https://kapi.kakao.com, 모든 호출에 헤더 3개:Authorization: KakaoAK {앱 어드민 키}(카카오쇼핑 API 허락된 카카오디벨로퍼스 앱) ·Target-Authorization: KakaoAK {판매자 API 인증키}(판매자센터 → 정보관리 → 판매채널 정보 → API 인증키) ·channel-ids: 101(톡스토어, 선물하기 1, 둘 다1,101). 입력칸admin_key·api_key(처음 입력칸 이름 유지)·channel_ids(선택). 두 키가 같은 앱이면 code -2, 판매자 키 무효면 -401, 앱-판매자 연결 전이면 "대행사 매핑/권한 확인" → 모두 인증 실패로 안내. Open API 는 카카오쇼핑 검토(“API 연동 검토 요청”)로 허락된 앱만 쓸 수 있다. - 수집: 결제일시 기준 주문내역
GET /v2/shopping/orders/paidAt?from=&to=&size=100(24시간까지 — 하루씩, 다음 쪽token) → 금액이 없어 결제된 주문마다 주문정보GET /v1/shopping/order?order_id=(목록modifiedAt이 같으면 메모리 캐시 재사용). - 사건: 결제(
paymentId) 하나 = SALEkakao:{paymentId}, 날짜 = 결제일. 금액 = 상품 줄마다(productPrice + optionPrice) × quantity − sellerDiscountPrice − sellerCouponDiscountPrice − adminDiscountPrice합, 배송비 제외. 미결제(Created·PayRequest·PayWaiting·PayChecking·PayFailed·UnpaidCancelComplete)만 빼고 결제 뒤 취소·반품은 포함(네이버와 같은 기준).replace_range. 문서에 결제금액 항목이 없어 만든 식이라 원본 데이터 확인의 항목 합계로 판매자센터 매출과 대조해 확정한다. - 개인정보(
orderer·orderDeliveryRequest·orderTicketReceiver, 클레임의 수거·교환 이름·주소·연락처·사유 글)는 받자마자 값을 지운다.
수동 입력(마이그레이션 002, 2026-10-12)
- 설정 → 쇼핑몰 표 수동 입력 토글(관리자,
perf_marketplaces.manual_input, 기본 꺼짐). 켜면 실적 일자별 표에서 그 쇼핑몰의 오늘까지 날짜 칸을 눌러 총매출을 입력한다(제목 ✎, 수동 값은 파란 숫자). Enter·Tab·↓ 저장 후 아래 칸, Shift+Enter·↑ 위 칸, Esc 취소, 칸을 벗어나면 저장. 입력을 마치면 새로고침해 합계·수수료·그래프를 서버 계산으로 다시 그린다. 입력은 모듈 권한자 누구나 (PUT /performance/api/manual-sales/{code}/{day},{amount}— 비우면 지움, 쉼표·"원" 허용, ±1조 이내, 앞날·꺼진 쇼핑몰은 400). - 값은
perf_manual_sales(쇼핑몰 × 날짜 하나,updated_by). 넣은 날은 그 값이 API 수집값을 대신하고(합산 아님), 넣지 않은 날은 API 값. 대체는PerformanceDBStore.daily_amounts한 곳에서 해 실적 화면·회의록 머리 카드가 같은 숫자를 본다. 수수료는 그날 요율로 계산. 토글을 끄면 값은 남지만 집계에 쓰지 않는다. 매출 업데이트(동기화)는 수동 값을 지우지 않는다. - 002 미적용: 읽기는 수동 값 없음으로 조용히 동작, 토글·저장은 503 안내.
- 열 순서(003 +
registry.py): 카페24 · 네이버 · 쿠팡(윙) · 쿠팡(로켓) · 오늘의집 · G마켓 · 카카오 · GS샵 · 11번가 · 롯데ON · 토스 · 애터미아자몰. 기존coupang(WING API) 이름은쿠팡(윙).naver이름은네이버(004, 예전네이버 스마트스토어). - 수동 입력 전용 쇼핑몰(003,
adapters/manual.py—manual_only = True):쿠팡(로켓)(coupang_rocket)·애터미아자몰(atomy). API 가 없어 매출 업데이트(sync_all)에서 빠지고, 설정 화면에 인증 설정·연결 테스트 버튼이 없으며 연결 상태는 "수동 입력". 수동 입력 토글은 늘 켜짐(화면 disabled, API 로 끄면 400). 매출은 일자별 표 날짜 칸에 직접 입력. - 수동 입력 엑셀 업로드(
manual_upload.py, 일자별 표 머리 [엑셀 업로드] → 팝업): 샘플GET /api/manual-sales/sample.xlsx(모듈 폴더upload_sample.xlsx), 업로드POST /api/manual-sales/upload(모듈 권한자 누구나 — 날짜 칸 입력과 같은 권한). 양식: 첫 시트 1행 머리글, 1열 날짜(엑셀 날짜·2026-10-12·2026.10.12·20261012), 2열부터 쇼핑몰 이름(설정 이름·짧은 이름·코드, 띄어쓰기·대소문자 무시). 수동 입력이 켜진 쇼핑몰 열만, 값이 있는 칸만 반영(같은 날 값 덮어씀, 빈 칸은 기존 값 그대로, 0 은 0원). 꺼진 쇼핑몰·모르는 이름 열은 건너뛰고 알려 줌. 숫자 아님·날짜 못 읽음·앞으로의 날짜·같은 쇼핑몰+날짜 두 번이면 아무것도 저장하지 않고 칸 위치(B3 등) 목록을 돌려준다. 저장은 한 트랜잭션(set_manual_sales_bulk). 5MB·2,000일 상한. - 표 열 제목은 가운데·굵게·검정(
.perf-table thead th).
연동 단계 체크리스트(쇼핑몰마다)
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 API·날짜 필드 확인
SaleEvent규칙: 금액은 원 단위 정수, 결제+/ 취소·반품−,external_event_id는 쇼핑몰 안에서 사건을 유일하게 가리키는 값(중복 방지 키),order_date/payment_date/event_date를 섞지 말고 각각 채운다- 오류 메시지·
raw에 비밀값을 넣지 않는다(sync 가 한 번 더 가리지만 원칙은 넣지 않는 것) implemented = True, 단위 테스트(원본 샘플 → 사건 변환) 추가
3. 매출 기준·계산 (calc.py, sync.sales_date_for)
- 집계 기준일(
sales_date): 결제 = 결제일(payment_date, 없으면event_date), 취소·반품 = 발생일. 지난주 실적이 나중에 바뀌지 않게 하려는 선택.order_date/payment_date를 따로 보관하므로 기준을 바꿀 수 있다 (바꿀 곳은sales_date_for한 곳 + 기존 행 재계산). - 수수료 =
round_half_up(일·쇼핑몰 매출 합 × 그날 요율 / 100)—calc.commission()한 곳. 음수(취소)도 같은 규칙. 주문별이 아니라 일·쇼핑몰 합계 단위 반올림이다. - 수수료율 이력:
perf_commission_rates(effective_from). 어떤 날의 요율 = 그날 이전 가장 최근 시작일의 요율, 첫 요율 이전은 0%. "처음부터(과거 전체)"는2000-01-01로 저장. - 주 = 월요일~일요일. 증감률: 진행 중인 기간은 직전 기간의 같은 경과일수까지와 비교(전주 같은 기간), 비교 대상이 0 이하면 표시하지 않음.
- 월·연 누적 기준일: 선택 기간이 오늘을 포함하면 오늘(이번주가 다음 달에 걸쳐도 "이번달"), 지난 기간이면 기간 끝.
4. 인증정보 보안
- 저장: 설정 화면 입력 → 서버에서 AES-256-GCM(
cryptographyAESGCM) →perf_credentials(항목 하나 = 행 하나,encrypted_value = "v{키버전}:{base64url(nonce+암호문+tag)}",key_version). - AAD =
perf:{쇼핑몰}:{항목}— 암호문을 다른 칸으로 옮기면 복호화 실패. - 화면으로는 secret 항목의 저장 여부만 보낸다(원문·일부·길이 X). 일반 항목(Vendor ID 등)만 원문 표시.
- 빈 칸 저장 = 기존 값 유지. 선택 항목은 "저장된 값 지우기".
- 저장 정책: [연결 테스트]는 입력한 새 값으로 시험하고 저장하지 않음(상태도 기록 안 함). [저장]은 테스트 결과와 무관하게 저장(쇼핑몰 일시 장애 대비) 후 자동으로 저장값 연결 테스트.
- 오류 메시지·로그·
raw_data는security/redact.py로 key/secret/token/password/Authorization/Cookie 를 가린 뒤 저장. - 쇼핑몰 API 는 백엔드에서만 호출. 브라우저는
/performance/api/*만 부른다.
마스터 키
| 변수 | 설명 |
|---|---|
APP_ENCRYPTION_KEY |
현재 키(32바이트: openssl rand -hex 32 64자 hex 또는 base64). DB·Git 에 넣지 않는다 |
APP_ENCRYPTION_KEY_VERSION |
현재 키 버전(기본 1) |
APP_ENCRYPTION_KEY_V{n} |
교체 중 남겨 두는 예전 키 |
교체 절차: 새 키를 APP_ENCRYPTION_KEY, 버전 +1, 예전 키를 APP_ENCRYPTION_KEY_V{예전} 에 → 재기동 →
설정 화면 [현재 키로 다시 암호화](POST /performance/api/rekey) → 예전 버전 0개 확인 후 _V{n} 삭제.
키를 잃으면 저장된 인증정보는 복구할 수 없다 — 키는 서버 .env 와 별도 안전한 곳에 백업한다
(DB 백업만으로는 복호화 불가 — 의도된 설계).
5. 권한 (서버에서 검사)
| 기능 | 권한 |
|---|---|
| 대시보드 · 매출 업데이트 · 금액 상세 | performance (admin 자동) |
설정 화면 진입 · 수수료율 조회·변경·이력 삭제(/api/marketplaces/{code}/rates) |
performance (2026-10-01부터 일반 사용자도) |
| 사용·매출 집계 토글 · 인증정보 · 연결 테스트 · 원본 데이터 확인·대조 · 과거 매출 가져오기(92일 초과) · 테스트 데이터 · 재암호화 | is_admin |
일반 사용자의 설정 화면(탭 이름 "수수료 설정")은 쇼핑몰 표에 쇼핑몰·수수료율·마지막 동기화만, 다른 칸·카드는 템플릿이 관리자에게만
그린다. 화면과 별개로 수수료 API 를 뺀 설정 API 는 모두 common.require_store(admin=True) 로 403 을 낸다.
6. 동기화 (sync.py)
SyncService.sync_all()/sync_marketplace()— 버튼·자동 업데이트 공용. 기본 기간: 오늘 포함 최근PERFORMANCE_SYNC_DAYS(기본 7)일.- 자동 업데이트(
auto_sync.py, 2026-10-13): 웹 프로세스 시작 때 데몬 스레드(main._lifespan) — 매일 09:00~19:00(KST) 정각·30분마다(하루 21회) 오늘 포함 최근 10일을 [매출 업데이트]와 같은 방식(진행 창 작업jobs,trigger='schedule'(DB CHECK 허용값), 사용자 "자동 업데이트")으로 다시 가져온다. 그 시각에 다른 업데이트가 돌고 있으면 그 회차는 건너뜀, 30분을 넘긴 회차 뒤엔 밀린 회차를 몰아서 돌리지 않고 다음 회차부터, 서버 시작 시각 회차는 돌리지 않음. 자동 업데이트 중 누가 버튼을 누르면 그 진행 창을 같이 본다(취소는 관리자). 수동 입력 전용 쇼핑몰은 대상 아님. envPERFORMANCE_AUTO_SYNC(false=끄기)·PERFORMANCE_AUTO_SYNC_DAYS(10)·PERFORMANCE_AUTO_SYNC_HOURS(9-19). uvicorn 단일 워커 기준(여러 프로세스면 회차마다 겹쳐 돌지만 같은 쇼핑몰 동시 실행은 DB 에서 막힘). - 대시보드 [매출 업데이트] = 지금 보고 있는 기간(오늘까지)을
POST /api/sync {from, to}로 다시 가져온다 ("이번달"이면 1일~오늘). 모듈 권한자는 92일까지, 더 긴 기간(올해 등, 최대 366일)은 관리자만. - 과거 매출 가져오기(설정 화면, 관리자): 같은 API 로 임의 기간(최대 366일). 같은 사건은 덮어써서 여러 번 해도 중복 없음.
- 진행 창(두 버튼 공통,
runSyncWithProgress):POST /api/sync {…, background: true}→ 수집을 스레드로 돌리고 작업 번호를 바로 돌려줌 → 화면이GET /api/sync/jobs/{id}를 0.8초마다 불러 쇼핑몰별 막대 + 전체 막대를 그린다(jobs.py, 메모리 보관 — uvicorn 단일 워커 기준, 서버 재시작 시 진행 정보만 사라짐). 어댑터가ctx.progress.plan(전체, 단위)/step(items=)/add(n)로 알린다 — 네이버 = 일, 11번가 = 7일 구간(정산 + 주문 상태 4개), 카페24 = 60일 구간(결제·환불·환불 없는 취소 2종, 대조 필요 시 +). 상태: 대기 → 수집 중 n/전체 · 받은 자료 → 저장 중 → 완료 n건 반영 | 실패 | 건너뜀. 수집이 없거나 인증정보가 없는 쇼핑몰은 막대에서 빼고 "건너뜀" 한 줄(전체 진행률에 안 넣음). 전체 = 막대 쇼핑몰 진행률 평균. 이미 돌고 있는 업데이트가 있으면 새로 시작하지 않고 그 진행 상황을 보여 준다(GET /api/sync/current). 창을 닫아도 수집은 계속된다. - [업데이트 취소](진행 창 왼쪽 아래, 시작한 사람·관리자,
POST /api/sync/jobs/{id}/cancel): 돌고 있는 쇼핑몰은 다음 API 호출 직전(ctx.progress.check()→Cancelled)에 멈추고 저장하지 않는다(저장은 수집이 끝난 뒤 한 트랜잭션이라 기존 매출 그대로), 차례가 안 온 쇼핑몰은 "취소됨"으로 건너뛴다. 이미 저장이 끝난 쇼핑몰 결과는 남고, 저장 중이던 쇼핑몰은 그 저장을 끝낸다. 취소된 실행은perf_sync_runs에 failed + "업데이트 취소", 연결 상태(perf_connection_status)는 바꾸지 않는다. - 쇼핑몰별 [중지](진행 창 쇼핑몰 이름 옆, 대기·수집 중일 때만, 시작한 사람·관리자,
POST /api/sync/jobs/{id}/shops/{code}/stop): 그 쇼핑몰만 위와 같은 방식으로 멈추고(저장 안 함, 기존 매출 그대로) 다음 쇼핑몰로 넘어간다. 차례가 안 온 쇼핑몰을 미리 중지하면 차례가 왔을 때 건너뛴다.ShopProgress.stop_requested→cancel_requested/check(), 상태 "중지됨"(stopped_only),perf_sync_runs는 failed + "쇼핑몰 중지". 저장 중·끝난 쇼핑몰은 409. - 카페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), 나머지 계속. 대시보드는 저장된 데이터로 계속 표시하고 상단에 오류 쇼핑몰만 표시. - 중복 방지:
UNIQUE(marketplace_code, event_type, external_event_id)+ON CONFLICT DO UPDATE.
7. 화면
- 탭(2026-10-13): 왼쪽 위 큰 탭 둘 — [매출 실적](검정,
/performance/) · [광고비](주황,/performance/ads) — 아이콘 + 고른 탭 색으로 구분, 설정은 맨 오른쪽 톱니 아이콘(프로젝트 모듈과 같은 Material Symbolssettings,/performance/settings)._tabs.html. - 광고비
/performance/ads?period=…(기본 이번달) — 매출 실적과 같은 기간 이동(오늘/이번주/이번달/올해/직접선택)·표(일자 × 채널, 연간은 월)·일별 추이·채널 비중·월/연 누적. 채널(2026-10-14) = 구글·메타·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 (ad_spend.CHANNELS, 앱이 정함 — 쇼핑몰 채널 코드는 실적 쇼핑몰 코드와 같고 쿠팡(윙)만coupang_wing). 모든 칸 직접 입력 가능, 칸 표시 = 광고비(ROAS%) — ROAS = 그 칸 기간의 매출 실적 총매출 ÷ 광고비 × 100(정수 반올림,ad_spend.roas). 매출 쇼핑몰 =ROAS_SALES_CODE(같은 쇼핑몰, 쿠팡(윙) =coupang). 구글·메타·네이버는 ROAS 계산 안 함(FILE_ROAS— 광고 보고서의 ROAS 값,perf_ad_spend.roas, 마이그레이션 006; 여러 날 = Σ(그날 ROAS × 광고비) ÷ Σ광고비, 광고비 0 인 날 제외 —file_roas), 합계 열·월/연 누적 = 매출 실적에 들어가는 쇼핑몰 전체 매출. 광고비가 없는 칸은 ROAS 없음. 광고비를 고치면 옛 ROAS 는 지우고 새로고침 때 다시 계산. KPI: 기간 광고비(전기간 대비), 매출 대비 광고비(같은 기간 광고비 ÷ 매출 실적 총매출), 월·연 누적. 저장perf_ad_spend(마이그레이션 005 — 채널 × 날짜 하나에 금액,sourcemanual/upload/api), 미적용이면 화면에 안내·API 503.- 날짜 칸을 눌러 직접 입력(
PUT /api/ad-spend/{channel}/{day}, 비우면 지움, 오늘까지) — 파란 숫자. 매출 수동 입력과 같은 JS(MANUAL_API). - [파일 업로드](
POST /api/ad-spend/upload?channel=) — 양식이 정해진 채널만(ad_spend.PARSERS). 여러 파일을 한 번에(2026-10-14,files+ 파일마다modified= 브라우저 File.lastModified, 최대 30개) — 같은 날짜가 여러 파일에 있으면 파일 날짜(수정 시각)가 최신인 파일 값 (같으면 나중 파일,ad_spend.merge_results), 오류는[파일 이름]을 붙여 모두 보여 주고 하나라도 있으면 전부 저장 안 함. 업로드가 끝나면 창을 닫고 새로고침. 파일에 있는 날만 덮어쓰고(주황 숫자), 잘못된 줄이 하나라도 있으면 아무것도 저장하지 않는다. 쿠팡(윙)·쿠팡(로켓)(같은 양식, 윙은 2026-10-14) = 쿠팡 광고 보고서 CSV(UTF-8/CP949)·엑셀: 1열 날짜(2026년 10월 01일), 19열 청구금액(+부가가치세). 1열에 날짜가 있는 줄의 19열 값(2026-10-14 — 윙 보고서는 캠페인 줄에도 날짜가 있고 19열이 비어 있어 예전엔 "청구금액이 비어 있습니다" 로 막혔다): 19열이 빈 줄은 건너뛰고, 같은 날짜에 값이 있는 줄이 여럿이면 더한다. "전체" 합계 줄·머리글·1열이 빈 캠페인 줄은 건너뜀. 날짜 줄은 있는데 값이 한 줄도 없던 날은 넘어간다(응답empty_days에만, 창은 그대로 닫힘). 청구금액이 한 줄도 없는 파일도 오류 없이 넘어감 (날짜 줄 자체가 없을 때만 양식 오류). - 네이버(2026-10-14) = 네이버 광고 보고서 CSV·엑셀(하루 한 줄): 3열 기간(
2026.09.30.), 4열 총비용 = 광고비, 12열 구매완료 광고수익률(%) = 그날 ROAS(roas), 나머지 항목(노출수·클릭수·클릭률·전환수·구매완료 수·장바구니·총 전환매출액 …)은 머리글 이름 그대로metrics(JSONB). 광고 계정 이름·ID 는 넣지 않음. 직접 입력으로 광고비를 고쳐도 ROAS·상세는 그대로. - 네이버 머리글 클릭 → 지금 보는 기간의 일자별 보고서 표(
GET /api/ad-spend/naver/details?from=&to=,ad_spend.detail_table): 열 = 파일 머리글 순서, 맨 아래 합계(숫자 항목은 합, 클릭률 = 클릭수 ÷ 노출수, 광고수익률 = 총비용 가중 평균).DETAIL_CHANNELS. - 구글·메타 업로드 양식/API 는 아직 — 지금은 직접 입력.
- 날짜 칸을 눌러 직접 입력(
- 대시보드
/performance/?period=day|week|month|year|custom&d=&from=&to=&m=<쇼핑몰>…기간 버튼(오늘/이번주/이번달/올해/직접선택) + 이전/다음, 쇼핑몰 필터, KPI 5개, 일자×쇼핑몰 표(주간합계·기간합계, 연간은 월 행), [총매출|수수료|수수료 차감 매출] 전환(서버가 세 값을 다 그리고 CSS 로 전환, 선택은 localStorage), 일별 추이·쇼핑몰 비중(SVG), 월 누적(비중), 연간 누적(월별, 지나지 않은 달 빈칸). 금액 클릭 → 주문 상세(GET /api/events, 31일 이내). - 설정
/performance/settings— 사용/매출 집계 토글, 수수료율(적용 시작일·이력), API 설정 창, 연결 상태 (정상/미설정/인증 실패/Token 만료/API 오류/연동 준비 중/사용 중지, 마지막 테스트·동기화, 최근 오류), 마스터 키 상태·재암호화, 테스트 데이터 생성/삭제(is_sample).
8. 테스트
python -m app.modules.performance.tests.test_performance # 또는 pytest
암호화(왕복·AAD·변조·키 교체), 가리기, 수수료 반올림·요율 이력, 기간/주 계산, 표·누적 합계, 인증정보 비노출·재암호화, 동기화 격리·가리기·중복 방지·매출 기준일, 모의 데이터를 DB/네트워크 없이 검증한다.