# 실적(쇼핑몰 통합 매출) 모듈 > `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 상품관리 → 시스템에서 재연결). 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~C43(취소완료). 입금전취소 C47~C49 제외 | −같은 품목 금액, 품목 `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**(`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}` — 기간 지정 수집(최대 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. 테스트 ```bash python -m app.modules.performance.tests.test_performance # 또는 pytest ``` 암호화(왕복·AAD·변조·키 교체), 가리기, 수수료 반올림·요율 이력, 기간/주 계산, 표·누적 합계, 인증정보 비노출·재암호화, 동기화 격리·가리기·중복 방지·매출 기준일, 모의 데이터를 DB/네트워크 없이 검증한다.