카페24 (Admin API GET /admin/orders, 문서 2026-09-01 기준) - 결제(SALE): date_type=pay_date, embed=items — 결제된 주문의 품목 결제금액(할인 반영·배송비 제외), 결제일 - 취소(CANCEL): cancel_complete_date, 품목 C40~C43 만 음수(입금전취소 C47~C49 제외) - 반품(RETURN): return_complete_date, 품목 R40~R43 음수, 부분 반품은 claim_quantity 비율 - 자체몰 주문만(market_id=self) — 카페24로 연동된 다른 마켓 주문은 이중 집계 방지로 제외 - 60일 단위 분할(한 호출 3개월 미만), limit 1000 페이지 넘김, 개인정보 미저장(raw 는 금액·상태만) - 기존 app/integrations/cafe24 토큰·클라이언트 재사용, 연결 테스트는 주문 권한까지 확인 - DEFAULT_SCOPES 에 mall.read_order 추가(읽기만) — 카페24 상품관리 → 시스템에서 재연결 필요 과거 매출 가져오기(설정, 관리자): 기간 지정 수집(최대 366일), 일반 사용자는 403 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 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 = 구현됨, 나머지 9개는 입력칸만 정의(수집은 NotImplementedYet). 쇼핑몰별 입력칸은
연동 단계에서 공식 API 문서로 확정한다.
카페24 (adapters/cafe24.py, 구현됨)
auth_type="shared" — 기존 app/integrations/cafe24 OAuth 토큰(cafe24_db)과 클라이언트(재시도·429·토큰 자동 갱신)를
재사용한다. 토큰에 mall.read_order 가 있어야 한다(DEFAULT_SCOPES 포함, 권한 추가 후 카페24 상품관리 → 시스템에서 재연결).
Admin API GET /admin/orders(문서 버전 2026-09-01 확인: 검색기간 한 호출 3개월 미만, limit ≤ 1000, offset ≤ 15000).
| 사건 | 조회 | 대상 | 금액·날짜 |
|---|---|---|---|
| SALE | date_type=pay_date, embed=items |
paid=T 주문의 모든 품목 |
+품목 결제금액(payment_amount, 할인 반영·배송비 제외), 결제일 |
| CANCEL | date_type=cancel_complete_date |
품목 상태 C40 |
−같은 품목 금액, 품목 cancel_date |
| RETURN | date_type=return_complete_date |
품목 상태 R40~R43(반품완료) | −품목 금액(부분 반품은 claim_quantity/quantity 비율), return_confirmed_date |
- 사건 ID =
{order_item_code}-S|C|R(중복 방지). 교환(E**)은 1단계에서 반영 안 함. - 자체몰 주문만(
market_id= self/빈값). 카페24 로 연동돼 들어온 다른 마켓 주문(스마트스토어·쿠팡 등)은 해당 쇼핑몰 어댑터와 이중 집계되지 않게 제외. 네이버페이 결제(order_place_id=NCHECKOUT)는 자체몰 주문이라 포함. - 기간은 60일씩 나눠 요청, 1000건 단위 페이지. 개인정보(구매자 이름·주소·연락처·계좌)는 저장하지 않고 raw 에는 금액·상태만.
- 실데이터로 확인할 것: 품목
payment_amount가 적립금·예치금 사용분을 어떻게 반영하는지, 부분 취소/반품 시 품목이 분리되는지(claim_quantity해석). 카페24 관리자 화면 매출과 한 주 정도 대조 후 필요하면 규칙 조정.
연동 단계 체크리스트(쇼핑몰마다)
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 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 자동) |
| 설정 화면 · 수수료 · 인증정보 · 연결 테스트 · 테스트 데이터 · 재암호화 | is_admin |
화면에서 설정 탭을 숨기는 것과 별개로 모든 설정 API 가 common.require_store(admin=True) 로 403 을 낸다.
6. 동기화 (sync.py)
SyncService.sync_all()/sync_marketplace()— 버튼·향후 cron/worker 공용. 기본 기간: 오늘 포함 최근PERFORMANCE_SYNC_DAYS(기본 7)일.- 과거 매출 가져오기(설정 화면, 관리자):
POST /api/sync {from, to}— 기간 지정 수집(최대 366일, 미래는 오늘까지). 처음 연동했거나 빠진 기간을 채울 때. 같은 사건은 덮어써서 여러 번 해도 중복 없음. 일반 사용자가 기간을 주면 403. - 같은 쇼핑몰 동시 실행 금지:
perf_sync_runs의status='running'부분 유니크 인덱스(30분 넘은 running 은 정리). - 쇼핑몰 하나 실패 → 그 쇼핑몰만 상태 오류(
perf_connection_status), 나머지 계속. 대시보드는 저장된 데이터로 계속 표시하고 상단에 오류 쇼핑몰만 표시. - 중복 방지:
UNIQUE(marketplace_code, event_type, external_event_id)+ON CONFLICT DO UPDATE.
7. 화면
- 대시보드
/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/네트워크 없이 검증한다.