3203ff87a4
- POST /api/sync background=true 로 수집을 백그라운드 스레드에서 돌리고 작업 번호를 바로 돌려줌,
GET /api/sync/jobs/{id}·/api/sync/current 로 진행 상황 조회(jobs.py, 메모리 보관)
- 어댑터 진행 알림(ctx.progress plan/step/add): 네이버 = 일, 11번가·카페24 = 조회 구간, 받은 자료 건수
- 창: 쇼핑몰마다 막대(대기·수집 중 n/전체·저장 중·완료 n건·실패·건너뜀·경과), 전체 막대(평균),
수집 없는/인증정보 없는 쇼핑몰은 건너뜀 한 줄, 창을 닫아도 서버에서 계속
- [매출 업데이트]·[과거 매출 가져오기] 모두 진행 창 사용, 이미 진행 중이면 그 진행 상황을 보여 줌
- 테스트 1개 추가(27개 통과), performance.js/css 캐시 버전, 문서 갱신
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
224 lines
22 KiB
Markdown
224 lines
22 KiB
Markdown
# 실적(쇼핑몰 통합 매출) 모듈
|
||
|
||
> `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·11번가·네이버 스마트스토어 = **구현됨**, 나머지 7개는 입력칸만 정의(수집은 `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~43/R40~43 이고 앞뒤 60일 환불 목록(완료일·접수일)에 그 주문이 없을 때 | −(판매가+옵션)×수량 − 품목 할인·쿠폰, 품목 취소일(반품은 반품완료일). 네이버페이 취소가 여기 해당 (네이버가 환불해 카페24 환불 목록에 없음). 사건 ID = `c24:{품목코드}-CL` (`unrefunded_claims`) |
|
||
|
||
- 할인 = 회원·세트상품·앱·마켓 기타·배송비 할인, 쿠폰 = 상품쿠폰 + 배송비쿠폰(`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 을 추가.
|
||
- 설정 화면 **"쇼핑몰 원본 데이터 확인"**(네이버 선택): 결제일 기준 상품주문 전체의 항목별 합계, 상태별 합계, 날짜별
|
||
매출·그중 결제 뒤 취소/반품(참고)·배송비(참고). 개인정보(주문자·수령인·주소·연락처·메모)는 값 없이 이름만.
|
||
|
||
### 연동 단계 체크리스트(쇼핑몰마다)
|
||
|
||
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 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일). 같은 사건은 덮어써서 여러 번 해도 중복 없음.
|
||
- **진행 창**(두 버튼 공통, `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`). 창을 닫아도 수집은 계속된다.
|
||
- 카페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. 테스트
|
||
|
||
```bash
|
||
python -m app.modules.performance.tests.test_performance # 또는 pytest
|
||
```
|
||
|
||
암호화(왕복·AAD·변조·키 교체), 가리기, 수수료 반올림·요율 이력, 기간/주 계산, 표·누적 합계, 인증정보 비노출·재암호화,
|
||
동기화 격리·가리기·중복 방지·매출 기준일, 모의 데이터를 DB/네트워크 없이 검증한다.
|