38afbca839
- 공동구매 날짜 칸을 저장하면 같은 줄 차이 칸 = 카페24 − 저장 응답(총매출·수수료·차감) - 차이 칸에 data-diff-minus·data-base(카페24 값) — 일 행만, 합계 줄은 새로고침 때 - performance.js 캐시 버전 20261030a Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
532 lines
68 KiB
Markdown
532 lines
68 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번가·네이버 스마트스토어·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 관리자 "일별 매출내역"과 같은 기준**으로 센다(처음의 품목 결제금액 방식은 배송비가 빠지고 환불 날짜 기준이 달라
|
||
화면과 맞지 않아 교체).
|
||
|
||
> **2026-10-19 규칙 변경 — 적립금 제외**(사용자 요청): 매출(SALE) = 결제합계 **− 적립금 사용**(`initial_order_amount.points_spent_amount`),
|
||
> 환불 = 실제 환불액 + 예치금 환불(**적립금으로 돌려준 `used_points` 는 뺌** — 결제에서 뺐으니 앞뒤를 맞춤, 사용자 선택).
|
||
> 그래서 카페24 열은 이제 카페24 일별 매출내역의 결제합계·환불합계보다 적립금만큼 작다(아래 표·대조 설명은 그 전 기준).
|
||
> 사건 raw 에 `points`(결제 = 사용 적립금, 환불 = −돌려준 적립금)·`points_excluded: true`. 주문 내역 창에 **적립금 사용** 칸 + 합계
|
||
> (맨 아래 = 결제 쪽 합, 환불이 있으면 "환불 −n" 따로). 사용자 확인값: 10/18 적립금 사용 16,820원.
|
||
> 규칙을 바꾸기 전에 받은 날은 [과거 매출 가져오기]로 다시 받아야 바뀐다(최근 10일은 자동 업데이트가 다시 받음).
|
||
|
||
| 사건 | 조회 | 금액·날짜 |
|
||
|---|---|---|
|
||
| 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 을 추가.
|
||
- **2026-10-19 규칙 변경**(사용자 요청 — "판매금액에 배송비는 추가하고 환불 금액은 빼 주세요", 환불은 환불된 날):
|
||
SALE 금액 = 판매금액(총) **+ 배송비**(상품주문 `deliveryFeeAmount − deliveryDiscountAmount` 합, 주문마다 0 미만이면 0),
|
||
raw `{goods, ship}`. 환불 = 같은 조회를 `rangeType=CLAIM_COMPLETED_DATETIME` 으로 하루씩 다시 불러(매출 업데이트는 하루 2번 조회 —
|
||
진행 막대 단위 "일 조회") 그날 클레임이 끝난 상품주문 중 **CANCELED·RETURNED**(교환·미입금 취소 제외)마다
|
||
CANCEL/RETURN `naver:{productOrderId}-RF`, 금액 = −`totalPaymentAmount`(상품 결제금액, 배송비 환불은 넣지 않음), 날짜 = 환불(클레임 완료)일,
|
||
raw `{refund}`. 그래서 네이버 열 = 판매금액(총) + 배송비 − 환불금액(환불일). 주문 내역 창에 **배송비·환불금액** 칸 + 합계.
|
||
사용자 확인값: 10/18 배송비 87,500원·환불 66,100원 — 배포 뒤 10/18 주문 내역 맨 아래 합계와 비교해 맞는지 확인할 것
|
||
(환불이 다르면 배송비 환불·클레임 종류 포함 여부를 실데이터로 조정). `replace_range` 라 다시 받으면 그 기간 환불도 교체.
|
||
네이버는 조회 시작일 180일 제한이 있어 그보다 오래된 날은 다시 받을 수 없다(예전 규칙 그대로 남음).
|
||
- **배송비 대조(2026-10-19)**: 10/18 실데이터 — 상품주문 53건(주문 30건), `deliveryFeeAmount` 합 157,500(3,500×45)·`deliveryDiscountAmount` 합
|
||
119,000(3,500×34)·`sectionDeliveryFee` 0 → 지금 규칙(상품주문마다 배송비 − 할인) 38,500, 판매분석 배송비는 87,500(3,500×25).
|
||
배송비·할인이 상품주문마다 반복돼 주문/배송 묶음 단위로 세야 하는 것으로 보여, 진단 `GET /api/marketplaces/naver/reconcile?date=` 응답에
|
||
`ship_check`(상품주문·주문·배송 묶음(packageNumber) 단위 후보 합계 + 주문별 상품주문 배송비·할인·상태)를 추가.
|
||
**확정(같은 날)**: `per_package.max_fee` = `per_order.max_fee` = **87,500** = 판매분석 배송비(배송비 있는 묶음 25개 × 3,500).
|
||
→ 네이버는 배송비·할인을 상품주문마다 반복해 적고, 판매분석 '배송비'는 **배송 묶음마다 deliveryFeeAmount 한 번, 배송비 할인(조건부 무료 등)은 빼지 않은 값**.
|
||
규칙을 그렇게 바꿈(`group_orders` — 묶음 `packageNumber`, 없으면 주문). 붙여 준 10/18 상품주문 53건을 새 규칙에 넣어 87,500 확인.
|
||
주의: 할인된 배송비도 들어가므로 손님이 실제로 낸 배송비(38,500)보다 크다 — 판매분석 기준을 따른 것.
|
||
- 설정 화면 **"쇼핑몰 원본 데이터 확인"**(네이버 선택): 결제일 기준 상품주문 전체의 항목별 합계, 상태별 합계, 날짜별
|
||
매출·그중 결제 뒤 취소/반품(참고)·배송비(참고). 개인정보(주문자·수령인·주소·연락처·메모)는 값 없이 이름만.
|
||
|
||
### GS샵 (`adapters/gsshop.py`, 구현됨)
|
||
|
||
- 문서: 협력사 포털 → 제휴 API → 개발가이드(`partners.gsshop.com/api/apiDevGuide`, 본문은 `/docs/withgs-api-docs.html` Redoc).
|
||
- 인증: 헤더 `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일**, 상태 생략 =
|
||
전체, 커서(`nextCursor` null = 끝). 줄 = 주문상품(`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:` — 매출·환불 함께 교체). 개인정보(주문자·수령인·주소·요청사항·수거 주소·요청 사유·송장)는 저장 안 함.
|
||
- **실데이터 대조(2026-10-01, 9/6)**: 매출 29,600 = 주문 2건 `price` 합 **일치**(`orderedAt` 은 시간대 없이 한국 시간 — 17:57 주문도 9/6).
|
||
환불 11,900 = 9/5 주문(276435356)을 9/6 취소 — 클레임 `CANCEL/COMPLETED` `refundedDt` 9/6 과 `canceledAt` 9/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`) 하나 = SALE `kakao:{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`).
|
||
|
||
### 직접 추가 쇼핑몰·그룹·순서 드래그(마이그레이션 009, 2026-10-22)
|
||
|
||
- **직접 추가 쇼핑몰** — 설정 쇼핑몰 표 아래 [+ 쇼핑몰 추가(수동 입력)](관리자, `POST /api/marketplaces {kind:"shop", name}`).
|
||
코드 `custom_<16진 8자>`, `is_custom`, 맨 뒤 순서, 사용·매출 집계·수동 입력 켬. 어댑터는 `registry.get_adapter` 가 `custom_` 접두어면
|
||
`CustomManualAdapter`(수동 입력 전용 — 매출 업데이트 제외·인증/연결 테스트 없음, 상태 "수동 입력")를 돌려준다. 이름(30자, 다른 쇼핑몰·그룹과
|
||
겹치면 400 — 엑셀 업로드 머리글로 씀)·수수료율·날짜 칸 입력·엑셀 업로드는 기본 쇼핑몰과 같다. 행 오른쪽 [이름 변경]·[삭제]
|
||
(`PUT /api/marketplaces/{code} {name}`, `DELETE` — 그 쇼핑몰의 수동 입력·수수료·상태·테스트 매출 행도 한 트랜잭션으로 지움,
|
||
확인 문구에 입력해 둔 날 수 `GET /api/marketplaces/{code}/manual-days`). 기본 쇼핑몰은 이름·그룹·삭제 400(사용을 끈다).
|
||
- **그룹** — [+ 그룹 추가](`kind:"group"`, 코드 `group_…`, `is_group`, `include_in_sales = FALSE` — 매출 없음, 회의록 머리 카드 등 매출 집계
|
||
목록에 안 잡힘). 직접 추가 쇼핑몰 행의 **그룹 select** 로 묶는다(`PUT … {parent_code}` — 빈 값 = 그룹 없음, 그룹 안에 그룹·기본 쇼핑몰은 400).
|
||
그룹 삭제 = 하위는 그룹 없음으로.
|
||
- **매출 실적 표** — 그룹 열은 보이는 하위 쇼핑몰 열 바로 앞(`dashboard._group_columns` → 템플릿 `cols`), 칸 = 하위 쇼핑몰 Money 합
|
||
(수수료는 쇼핑몰별 요율로 계산한 것의 합). 일 합계·KPI·그래프·월 누적은 쇼핑몰 기준 그대로(그룹을 또 더하지 않음). 머리글 ▾/▸ 로 하위 열
|
||
접기/펴기(`data-group-child`, 접은 그룹은 localStorage `perf_groups_collapsed`). 쇼핑몰 필터로 하위를 하나도 안 고르면 그룹 열도 없음.
|
||
- **순서** — 설정 표 ⠿ 를 끌어 놓으면(`performance.js` pointer 이벤트) 화면 순서 그대로 `PUT /api/marketplace-order {codes}` → `sort_order`
|
||
10, 20, … 다시 매김(`reorder_marketplaces`). 드래그 단위는 tbody(그룹 없는 행 하나, 또는 그룹 + 하위) — 하위 쇼핑몰은 그 그룹 안에서만.
|
||
화면 순서 = `dashboard.ordered_marketplaces`(sort_order 순, 그룹 바로 뒤에 하위) — 설정 표·매출 실적 열·필터 공통. 설정 표도 예전
|
||
`registry` 순서 대신 이 순서(009 없어도 됨).
|
||
- **카페24(공구 제외) 열**(2026-10-30) — 직접 추가 쇼핑몰 이름이 "카페24 공동구매"(띄어쓰기 무시)면 그 열 바로 오른쪽에
|
||
카페24 − 카페24 공동구매(총매출·수수료·차감 매출 각각) 계산 열(`dashboard._cafe24_ex_gb_column`, 열 코드 `cafe24_ex_gb`, kind `diff`).
|
||
카페24·공동구매 둘 다 보일 때만, 표 열만(일 합계·KPI·그래프엔 안 더함), 클릭·메모 없음. 공동구매가 그룹 하위면 같은 그룹으로 접힘.
|
||
이름으로 찾으므로 설정에서 이름을 바꾸면 열이 사라진다. 공동구매 칸 저장 즉시 그 줄 차이 칸 = 카페24(td `data-base` 총매출,수수료,차감) − 저장 응답
|
||
(`performance.js saveManual`, 일 행만 — 주간·기간 합계 줄은 입력을 마친 뒤 새로고침 때). 테스트 `tests/js/perf_manual.test.js` "[공구 제외]".
|
||
- 테스트: `app/modules/performance/tests/test_custom_groups.py`, 화면 `tests/js/perf_groups.browser.test.js`(render_performance.py 의 `perf_*_groups.html`).
|
||
|
||
### 연동 단계 체크리스트(쇼핑몰마다)
|
||
|
||
- 공식 문서로 인증 방식·호출 제한·페이지네이션·주문 상태 코드·취소/반품 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 자동) |
|
||
| 설정 화면 진입 · **수수료율 조회·변경·이력 삭제**(`/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분을 넘긴 회차 뒤엔
|
||
밀린 회차를 몰아서 돌리지 않고 다음 회차부터, 서버 시작 시각 회차는 돌리지 않음. 자동 업데이트 중 누가 버튼을 누르면 그 진행
|
||
창을 같이 본다(취소는 관리자). 수동 입력 전용 쇼핑몰은 대상 아님. env `PERFORMANCE_AUTO_SYNC`(false=끄기)·
|
||
`PERFORMANCE_AUTO_SYNC_DAYS`(10)·`PERFORMANCE_AUTO_SYNC_HOURS`(9-19, 일정 저장 전 기본 시간대). uvicorn 단일 워커 기준(여러 프로세스면 회차마다 겹쳐
|
||
돌지만 같은 쇼핑몰 동시 실행은 DB 에서 막힘).
|
||
- **자동 업데이트 일정 설정**(2026-10-26, 마이그레이션 011 `perf_settings`): 실적 설정 "자동 업데이트" 카드(관리자)에서 **매출 실적·광고비를 따로** —
|
||
사용 여부 · 요일(월~일 동그라미, [매일]·[평일]) · 시작/끝 시각(시·분 고르기, 5분 단위) · 간격(5~720분, 5분 단위, 기본 30분).
|
||
회차 = 고른 요일의 시작, 시작+간격, … 끝 시각까지(끝과 딱 맞으면 끝도, 시작 = 끝이면 하루 한 번). 밤을 넘기는 시간대는 안 됨(끝 ≥ 시작).
|
||
저장 = `PUT /api/auto-sync-schedule {sales: 일정, ads: 일정}` → `perf_settings` key `auto_sync`(JSONB). 일정 = `{enabled, interval, days(0=월…6=일), start "HH:MM", end "HH:MM"}`.
|
||
스레드(`auto_sync.Scheduler`)는 1분마다 일정을 다시 읽어 바뀐 종류만 지금부터 다음 회차를 다시 계산(저장 직후 회차는 안 돌림), 회차가 되면 그 종류만 따로 스레드로
|
||
(`run_once(kinds=(kind,))`). 저장 값이 없거나 011 미적용·값이 깨졌으면 그 종류는 기본 일정. 화면 카운트다운은 매출 탭 = 매출 일정, 광고비 탭 = 광고비 일정
|
||
(`router._auto_sync_ctx(store, kind)` → `performance.js nextScheduleSlot`, 같은 규칙). env `PERFORMANCE_AUTO_SYNC=false` 면 일정과 상관없이 안 돈다(카드에 안내).
|
||
- **화면 자동 새로 고침**(2026-10-26): 자동 업데이트가 끝나도 열어 둔 화면 숫자가 그대로이던 문제 — 매출 실적·광고비 화면이 20초마다
|
||
`GET /api/update-status?kind=sales|ads` → `{running, done(마지막으로 끝난 작업 id, 보는 사람이 시작한 것 제외), user}`(`jobs.last_finished`,
|
||
메모리의 진행 작업만 — DB 안 읽음)를 보고, 화면을 그린 때 값(`update_watch.seen`, `router._update_watch`)과 다르고 도는 중이 아니면 `location.reload()`.
|
||
칸 입력 중(포커스)·창·메뉴·확인 창이 열려 있으면 닫힐 때까지 1.5초마다 다시 보고 마지막 업데이트 옆에 "새 데이터 있음" 안내. 탭이 안 보이면
|
||
묻지 않고 다시 보이면 바로 묻는다. 서버를 다시 켜면 작업 목록이 비어 그 전 업데이트로는 새로 고치지 않는다(다음 업데이트부터).
|
||
- **대시보드 [매출 업데이트]** = 지금 보고 있는 기간(오늘까지)을 `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`.
|
||
- **실패를 성공으로 만들지 않는다(2026-10-15 검토 F01·F05·F06, `docs/CODE_REVIEW_2026-10-15.md`)** — 기간을 통째로 교체(`replace_range`)하는
|
||
쇼핑몰은 일부만 받은 목록으로 교체하면 매출이 지워진다:
|
||
- 쿠팡: HTTP 200 이어도 JSON 이 아니거나 `data` 목록이 없으면 `ApiError`(정상 빈 목록 `data: []`·성공 표시가 있는 `data: null` 만 0건).
|
||
- 쪽 넘김: 마지막 쪽을 확인하지 못하면(쪽 수 상한 소진·같은 커서 반복) 실패. 쿠팡은 `TooManyPages` → 조회 구간을 반으로(하루까지),
|
||
하루도 넘치면 실패. 네이버·카카오·토스(주문·정산·클레임)·GS샵도 상한 소진·커서 반복이면 `ApiError`.
|
||
- [중지]: `ShopProgress.begin_saving()` 이 중지 확인과 running → saving 전환을 한 잠금에서 — `collect()` 끝 무렵 받아들인 중지는
|
||
저장하지 않고 "중지됨", 저장을 시작한 뒤의 중지는 409(중지 불가).
|
||
- **인증정보가 바뀌면 이전 토큰을 쓰지 않는다(F04)**: 저장 때 화면 항목 값이 실제로 바뀌면 그 쇼핑몰의 내부 값(토큰·만료)을 지운다
|
||
(같은 값 다시 저장은 그대로). 네이버·토스 토큰은 발급한 인증정보 지문(`access_token_for` = SHA-256, 원문 아님)과 지금 인증정보가
|
||
같을 때만 다시 쓴다 — 저장하지 않은 연결 테스트 값에도 같은 기준. GS샵 토큰 방식 캐시도 (협력사코드, 운영 KEY 지문) 기준.
|
||
배포 직후 지문이 없는 예전 토큰은 한 번 새로 받는다.
|
||
- **연결 테스트 `clear`(F09)**: 쇼핑몰·광고 테스트 API 공통 — 요청 `{values, clear}`, 비운 칸(clear)은 저장값 대신 빈 값으로 시험,
|
||
values·clear 중 하나라도 있으면 저장하지 않은 시험(`unsaved: true`) — 연결 상태·토큰을 저장하지 않는다(`router._cleared_keys`).
|
||
|
||
## 7. 화면
|
||
|
||
- **2026-10-19 변경**
|
||
- **설정 진단 카드 삭제** — "쇼핑몰 원본 데이터 확인"·"카페24 매출 대조"·"일별 한 번에 비교" 카드와 그 화면 스크립트를 뺐다
|
||
(사용자 요청 — 쇼핑몰별 규칙 대조가 끝나 더 안 씀). 서버 API `GET /api/marketplaces/{code}/reconcile`·`daily-check` 와
|
||
어댑터 `reconcile`은 다시 대조가 필요할 때를 위해 남겼다(화면 진입점 없음). 아래 절의 "원본 데이터 확인"·"매출 대조" 설명은 그 당시 기록.
|
||
- **보기 설정 · 매출 단위** — 설정 화면 "보기 설정" 카드(모듈 권한자 누구나): 원·천원·백만원. 이 브라우저 쿠키 `perf_unit`(1년, path `/performance`)에 두고
|
||
매출 실적 화면을 서버가 그 단위로 그린다(`dashboard.amount_text` — 천원 = 정수 반올림, 백만원 = 소수 한 자리, `router._unit_ctx` → 템플릿 `amt`·`money`).
|
||
표·월/연 누적 카드 머리에 "단위: 천원", KPI·연 누적은 "3,835천원". 수동 입력은 늘 원 단위로 넣는다(입력 직후 칸은 JS `unitWon`). 광고비 탭·그래프 말풍선은 원 그대로.
|
||
- **매출 칸 아래 광고비(ROAS%)** — 일자별 × 쇼핑몰 표의 매출 칸마다 그 쇼핑몰 광고비와 ROAS 를 광고비 색(`--perf-ad`) 작은 줄로(`dashboard._ad_lines`).
|
||
값은 광고비 탭과 같다(`ad_spend.channel_roas` — 구글·메타·네이버는 보고서 ROAS, 나머지는 그 쇼핑몰 매출 ÷ 광고비). 쇼핑몰 → 채널(`sales_ad_channels`):
|
||
카페24 = **구글·메타 두 줄**("구글 100,000(413%)"), 네이버 = 네이버 광고, 쿠팡 = 쿠팡(윙), 그 밖은 같은 코드 채널. 일 합계 칸 = 보이는 쇼핑몰 광고비 합(ROAS = 그 쇼핑몰들 매출 합 ÷ 광고비 합),
|
||
주간합계·기간 합계 행도 그 기간 값. 광고비가 없는 칸은 줄 없음, 광고비 표(005) 미적용·조회 실패면 줄 없이 매출만. 총매출·수수료·차감 매출 전환과 무관하게 늘 보인다.
|
||
|
||
- **탭**(2026-10-13): 왼쪽 위 큰 탭 둘 — [매출 실적](검정, `/performance/`) · [광고비](주황, `/performance/ads`) — 아이콘 + 고른 탭 색으로 구분,
|
||
설정은 맨 오른쪽 톱니 아이콘(프로젝트 모듈과 같은 Material Symbols `settings`, `/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 — 채널 × 날짜 하나에 금액, `source` manual/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**(2026-10-15, 마이그레이션 007)·**메타 = 메타 마케팅 API**(2026-10-16, 새 마이그레이션 없음) — 아래 "광고 API 연동".
|
||
- **광고 API 연동**(2026-10-15) — 구조: `ad_sources/`(채널 하나 = 파일 하나 + `registry.py` 한 줄, 쇼핑몰 어댑터와 같은 입력칸·연결 테스트 모양,
|
||
돌려주는 것은 날짜별 `AdDay`(금액·ROAS·항목)) + `ad_sync.py`(가져오기·저장·상태, 같은 채널 동시 실행 차단).
|
||
- **인증정보**: 실적 설정 → **광고 API 연동** 카드 [설정](관리자). 쇼핑몰과 같은 마스터 키·AES-256-GCM, 표만 따로
|
||
`perf_ad_credentials`(쇼핑몰 표는 `perf_marketplaces` 에 FK 로 묶여 있음), 암호문 AAD 이름 공간 `perf:ad:{채널}:{항목}`
|
||
(`credentials.aad_for(…, ns)` — 쇼핑몰 암호문과 바꿔 넣어도 복호화 안 됨). 비밀 원문은 화면으로 다시 보내지 않음.
|
||
[현재 키로 다시 암호화]·저장된 항목 수에 광고 인증정보도 포함. 연결 상태·마지막 가져오기는 `perf_ad_source_status`.
|
||
- **구글 광고**(`ad_sources/google_ads.py`): 입력 = 고객 ID(광고 계정 10자리) ·
|
||
로그인 고객 ID(MCC 를 거칠 때만) · 서비스 계정 키 JSON(비밀, 여러 줄) · API 버전(기본 `v26`, 구글이 종료 알리면 설정에서 올림).
|
||
서비스 계정 이메일을 구글 광고 → 관리 → 액세스 및 보안 → 사용자에 추가해 두어야 한다(도메인 위임 불필요, 2024-11~).
|
||
**개발자 토큰은 2026-09-09 폐지**(구글) — 접근 등급(Explorer 등)은 서비스 계정을 가진 Google Cloud 프로젝트에 붙고
|
||
Cloud Console → Google Ads API Overview 에서 신청. `developer-token` 머리글은 무시되며 다음 큰 버전부터 거부라 보내지 않는다(입력칸 없음).
|
||
승인 없는 프로젝트 = `CLOUD_PROJECT_NOT_APPROVED_FOR_PRODUCTION`(안내 문구 붙음).
|
||
토큰 = 서비스 계정 JWT(google-auth 서명) → `oauth2.googleapis.com/token`(httpx), 프로세스 안 캐시(만료 2분 전까지).
|
||
조회 = REST `googleAds:searchStream` GAQL `FROM customer` + `segments.date BETWEEN`(계정 시간대), 요청 1번.
|
||
금액 = `cost_micros ÷ 10⁶ × 1.1` 원 반올림 — **부가세 포함**(2026-10-15 사용자 요청, 쿠팡 청구금액과 같은 기준. 구글 비용 자체는 부가세 별도),
|
||
ROAS = 전환 가치 ÷ 비용(부가세 별도) × 100(소수 둘째, 구글 화면 값 그대로), 항목에 광고비(부가세 포함)·비용(부가세 별도) 둘 다,
|
||
항목 `metrics` = 비용·노출수·클릭수·클릭률(%)·전환수·전환 가치·ROAS(%) → 구글 머리글 클릭 = 일자별 표(`DETAIL_CHANNELS`).
|
||
통화가 KRW 가 아니면 저장 안 함. 구글 오류 코드는 고칠 곳 안내를 붙여 보여 줌(`_HINTS`: 권한 없음·토큰 미승인 등), 404 = API 버전 종료 안내.
|
||
- **메타 광고**(`ad_sources/meta_ads.py`, 2026-10-16): 입력 = 광고 계정 ID(여러 개 — 줄바꿈·쉼표, `act_` 있어도 됨, 30개까지, 비밀 아님 여러 줄) ·
|
||
액세스 토큰(비밀 — `ads_read` 권한, 비즈니스 설정 → 시스템 사용자 토큰 권장(만료 없음), 토큰 주인을 각 광고 계정에 배정) ·
|
||
앱 시크릿(비밀, 선택 — 앱에서 "API 호출에 앱 시크릿 필요"를 켰을 때만, `appsecret_proof` = HMAC-SHA256(토큰)) · API 버전(기본 `v26.0`).
|
||
조회 = `GET graph.facebook.com/{버전}/act_{계정}/insights` `level=account`·`time_increment=1`·`time_range`, 계정마다 `paging.next` 따라감
|
||
(다음 쪽 주소가 graph.facebook.com 이 아니면 중단 — 토큰을 다른 곳에 보내지 않음). 토큰은 메타 문서대로 `access_token` 매개변수
|
||
(주소에 들어가므로 오류 문구에 주소를 넣지 않고, httpx INFO 요청 로그는 켜지 않는다). 여러 계정은 날짜별로 더함, 날짜는 광고 계정 시간대.
|
||
기여(어트리뷰션)는 메타가 광고 관리자 설정을 따른다(2025-06 부터 API 기여 매개변수 무시) — 광고 관리자 화면 값과 같음.
|
||
금액 = 지출 금액(`spend`) 그대로 원 반올림 — **메타 지출 금액은 이미 부가세 포함**(2026-10-16 사용자 확인, × 1.1 은 구글만), ROAS = 구매 전환값 ÷ 지출 금액 × 100
|
||
(= 광고 관리자 "구매 ROAS"). 구매 전환값·구매수 = `action_values`·`actions` 에서 `omni_purchase` → `purchase` → 픽셀 구매 순서로 처음 있는 것 하나
|
||
(메타가 같은 구매를 여러 종류에 같은 값으로 겹쳐 주므로 더하지 않음). 항목 `metrics` = 지출 금액(부가세 포함 = 광고비)·노출수·클릭수·
|
||
클릭률(%)·링크 클릭·구매수·구매 전환값·ROAS(%) → 메타 머리글 클릭 = 일자별 표(`DETAIL_CHANNELS`).
|
||
**외화 계정**(2026-10-16, 사용자 요청 — USD 계정 1314634672357695): 원화가 아닌 계정은 지출 금액·구매 전환값을 **그날 환율로 원화 환산**한 뒤
|
||
다른 계정과 더한다(`fx.py` `krw_rates` — Frankfurter v2 `https://api.frankfurter.dev/v2/rates?base=USD"es=KRW&from=&to=`, API 키 없음,
|
||
여러 중앙은행 고시 환율 종합(blended)이라 주말 포함 매일 있음, 서울외국환중개 매매기준율과는 조금 다를 수 있음). 그날 값이 없으면 앞 10일 안 가장 가까운 날 값,
|
||
그래도 없거나 환율 서버 장애면 그 회차는 저장하지 않음(일부만 환산 금지, 오류 안내). 통화마다 기간 한 번 요청, 2일 이상 지난 날 환율은 프로세스 안 캐시.
|
||
광고비 = 지출 × 환율(메타 지출은 부가세 포함), ROAS 는 비율이라 환율과 무관. 계정 탭에 `지출 금액(USD)`·`적용 환율(원)`(합계 줄 = 광고비 가중 평균).
|
||
오류 코드 안내(`_HINTS`): 190 = 토큰 만료·무효(상태 "Token 만료"), 200·10 = 권한(ads_read·계정 배정),
|
||
100·803 = 계정 ID, 4·17·613·80000·80004 = 호출 한도, 2635 = 버전 종료. 연결 테스트 = 계정마다 이름·통화·시간대·상태.
|
||
**권한 오류 진단**(2026-10-16, 실제로 `(#200) Ad account owner has NOT grant ads_management or ads_read permission` 발생): 연결 테스트가
|
||
권한 오류를 받으면 메타에 ① `debug_token`(같은 토큰 — 앱·만료·`scopes`·`granular_scopes.target_ids`, 안 되면 `me/permissions`)
|
||
② `me/adaccounts`(이 토큰으로 보이는 계정)를 물어 원인 하나를 짚는다(`_diagnose`): ads_read 없음 → 토큰 재발급 /
|
||
입력한 계정이 안 보임 → 시스템 사용자 [자산 할당]에서 광고 계정 배정 후 토큰 재발급 / 권한이 다른 계정에만 → 대상 포함해 재발급 /
|
||
다 맞음 → 앱 쪽(비즈니스에 앱 연결·Marketing API 제품·제한 액세스면 토큰 주인이 앱 관리자·개발자인지). 진단 조회 실패는 무시(덧붙이는 정보).
|
||
**상세보기 계정별 탭**(2026-10-16): 메타 머리글 상세보기 = [합계 | 계정…] 탭. 가져올 때 그날 메타 행 `metrics` 에 계정별 값을
|
||
예약 키 `_accounts`(`ad_sources.base.ACCOUNTS_KEY` — `{계정 ID: {name, amount, roas, metrics}}`, 이름 = insights `account_name`)로 함께 저장
|
||
(새 마이그레이션 없음). `ad_spend.detail_table` 은 `_` 로 시작하는 키를 표 열·합계·화면 값에서 뺀다. `ad_spend.detail_tabs` = 합계 탭 +
|
||
계정 탭(그 계정이 광고를 낸 날만, 이름 = 가장 최근 날 이름, 순서 = 기간 광고비 큰 계정부터) + `accounts_missing`(계정별 값 없이 광고비만 있는 날 —
|
||
계정별 저장 전에 가져온 날, 다시 불러오면 생김, 화면 안내). 계정마다 따로 반올림해 계정 광고비 합이 합계와 1원 다를 수 있다.
|
||
계정별 값이 없는 채널(네이버·구글)은 `tabs: []` → 예전 그대로 표 하나.
|
||
광고비 탭 불러오기에서 난 권한 오류엔 "[연결 테스트]가 원인을 진단" 안내를 붙인다(`_DIAG_HINT`).
|
||
연결 테스트 문구는 **[진단]을 맨 앞에**, 메타 원문은 짧게(긴 안내 주소 뺌) 뒤에. 광고 연동 오류 문구 길이 한도는 `ad_sync.AD_MESSAGE_MAX`(1200자,
|
||
비밀값 가린 뒤) — 예전엔 공용 기본 300자에서 잘려 진단이 "[진…" 으로 끊겼다.
|
||
- **저장**(`db.replace_ad_api_range`, 한 트랜잭션): API 가 준 날은 `source='api'` 로 덮어씀(직접 입력·업로드 값이 있던 날도),
|
||
기간 안에서 API 가 안 준 날(광고 없음)은 **예전 API 값만** 지움 — 직접 입력·업로드 값은 그대로. 화면 초록 숫자 = API 값.
|
||
- **언제**: 광고비 탭 **[구글 광고 불러오기]**(설정된 연동만 보임, 지금 보는 기간 → 오늘까지, 모듈 권한자 92일·관리자 366일,
|
||
`POST /api/ad-sources/{code}/sync`) + **광고비 자동 업데이트 일정**(같은 최근 N일, 실적 설정 "자동 업데이트"의 광고비 일정 — 매출과 따로, 실패해도 매출과 무관 — `auto_sync.run_once`).
|
||
- API: `GET|PUT /api/ad-sources/{code}/credentials`·`POST /api/ad-sources/{code}/test`(관리자), `POST /api/ad-sources/{code}/sync`(모듈 권한).
|
||
- 007 미적용: 설정 카드에 안내, 저장은 503(안내 문구), 광고비 탭은 그대로(불러오기 버튼만 안 보임).
|
||
- **대시보드** `/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 오류/연동 준비 중/사용 중지, 마지막 테스트·동기화, 최근 오류), **광고 API 연동**(구글 광고·메타 광고 —
|
||
설정·연결 테스트·연결 상태·마지막 가져오기, 관리자), 마스터 키 상태·재암호화, 테스트 데이터 생성/삭제(`is_sample`).
|
||
|
||
## 8. 테스트
|
||
|
||
```bash
|
||
python -m app.modules.performance.tests.test_performance # 또는 pytest
|
||
```
|
||
|
||
암호화(왕복·AAD·변조·키 교체), 가리기, 수수료 반올림·요율 이력, 기간/주 계산, 표·누적 합계, 인증정보 비노출·재암호화,
|
||
동기화 격리·가리기·중복 방지·매출 기준일, 모의 데이터를 DB/네트워크 없이 검증한다.
|
||
`tests/test_google_ads.py` — 구글 광고 입력 검사, 토큰 교환·머리글·GAQL 기간·버전, 금액 반올림·ROAS·항목 변환, 오류 안내(권한·버전·통화·키),
|
||
광고 인증정보 AAD 이름 공간, 가져오기 저장·상태·비밀값 가림·동시 실행 차단, 불러오기 API(오늘까지 자름·92일 권한·미설정)를 가짜 구글 서버로 검증.
|
||
`tests/test_meta_ads.py` — 메타 광고 입력 검사(계정 ID 여러 개·토큰·버전), 요청 매개변수(기간·level·appsecret_proof·버전), 여러 계정 날짜별 합산·
|
||
쪽 넘김(메타 밖 주소 거부), 구매 값 겹침 처리·광고비 = 지출 그대로(× 1.1 없음)·ROAS·항목, 외화 환율·366일, 오류 코드 안내·토큰 미노출, 연결 테스트 문구,
|
||
실제 fetch_days → AdSyncService 저장·상태·토큰 가림을 가짜 메타 서버로 검증.
|