Files
dbx-main/docs/PERFORMANCE_MODULE.md
T
king 6f43f8066a fix(performance): 카페24 결제합계에서 품목 상품추가할인 빼기 + 대조 표에 카페24 열별 차이
일별 비교 결과 결제합계가 틀린 날은 모두 카페24 상품구매금액이 100원 단위가
아닌 날이고, 차이만큼 더하면 정확히 100원 단위가 된다(9/23 1,860,738+62,
9/22 2,620,740+260, 9/12 7,889,287+13 …). 카페24 화면의 상품구매금액은
품목 상품추가할인(items[].additional_discount_price, 문서: 상품추가할인액)을
뺀 값인데, initial_order_amount 에는 이 할인이 없어 우리가 그만큼 많았다.

- order_total: 판매가 합계 − 품목 상품추가할인 + 배송비 − 할인 − 쿠폰
- order_total_now: 취소·반품 품목의 추가할인은 제외
- 대조 표: 상품구매금액을 추가할인 뺀 값으로 + 판매가 합계·추가할인 세부 줄
- 일별 비교에서 날짜를 눌러 연 대조 표에 붙여넣은 카페24 열과 열별 차이 표시
- 테스트 추가

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-29 21:43:50 +09:00

15 KiB
Raw Blame History

실적(쇼핑몰 통합 매출) 모듈

app/modules/performance/ · DB performance_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 상품관리 → 시스템에서 재연결).

카페24 관리자 "일별 매출내역"과 같은 기준으로 센다(처음의 품목 결제금액 방식은 배송비가 빠지고 환불 날짜 기준이 달라 화면과 맞지 않아 교체).

사건 조회 금액·날짜
SALE(결제합계) GET /admin/orders date_type=pay_date, embed=items, paid=T +(상품구매금액 + 배송비 − 할인 − 쿠폰), initial_order_amount(결제 당시 금액 — 환불을 따로 빼므로 취소 후 금액 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` — 품목 상태 C4043/R4043 이고 앞뒤 60일 환불 목록(완료일·접수일)에 그 주문이 없을 때
  • 할인 = 회원·세트상품·앱·마켓 기타·배송비 할인, 쿠폰 = 상품쿠폰 + 배송비쿠폰(DISCOUNT_FIELDS/COUPON_FIELDS).
  • 기간 교체(replace_range=True): 결제·환불 모두 기간 안 날짜로 조회되므로 동기화 때 그 기간의 카페24 실데이터를 지우고 새로 넣는다(한 트랜잭션, 테스트 데이터 제외). 규칙이 바뀌어도 예전 행이 남지 않는다 → 규칙을 고친 뒤에는 같은 기간을 [과거 매출 가져오기]로 다시 받으면 된다.
  • 주의 — market_id 는 외부 마켓만이 아니라 자체몰 주문 채널·간편결제도 담는다(실데이터 확인 2026-09-30: mobile=모바일웹, NCHECKOUT=네이버페이, KAKAOPAY=톡체크아웃). 이들은 SELF_CHANNELS 로 카페24 열. 대조 도구의 "주문 채널별" 표가 채널마다 자체몰 채널 / 외부 마켓 / 알 수 없는 채널(→ 카페24 열)을 보여 준다. MARKET_MAP 에는 결제수단과 헷갈릴 수 있는 일반 이름(naver, kakao)을 넣지 않는다.
  • 마켓 연동 주문은 해당 쇼핑몰 열로: 자체몰 채널은 카페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 열(주문수·품목수·상품구매금액·배송비·할인·쿠폰·실결제·적립금·예치금·결제·환불·순매출)과 열별 차이가 같이 나온다.
  • 결제합계의 상품구매금액 = 판매가 합계 − 품목 상품추가할인(items[].additional_discount_price). 주문 금액(initial_order_amount)에는 이 할인이 없다(2026-09 실데이터: 카페24 상품구매금액이 100원 단위가 아닌 날만 결제합계가 그만큼 많았음, 예 9/23 +62).

연동 단계 체크리스트(쇼핑몰마다)

  • 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 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(cryptography AESGCM) → 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} 로 다시 가져온다 ("이번달"이면 1일~오늘). 모듈 권한자는 92일까지, 더 긴 기간(올해 등, 최대 366일)은 관리자만.
  • 과거 매출 가져오기(설정 화면, 관리자): 같은 API 로 임의 기간(최대 366일). 같은 사건은 덮어써서 여러 번 해도 중복 없음.
  • 카페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. 화면

  • 대시보드 /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/네트워크 없이 검증한다.