c710e184e7
- 버튼은 업데이트 중 '업데이트 중 · 진행 보기', 누르면 진행 중 작업(수동·자동)을 새로 시작하지 않고 진행 창으로 - 서버 시작 때 perf_sync_runs running 행을 '중단됨(서버 재시작)'으로 정리 — 30분 막힘 방지 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.1 KiB
8.1 KiB
[실적] 실적 모듈 — app/modules/performance/, performance_db
이 모듈만 고칠 때 읽는 요약. 상세는
docs/PERFORMANCE_MODULE.md(큰 문서 —grep -n '^#'로 목차 보고 필요한 절만 읽기). 정적 파일:app/static/performance.css,performance.js. 템플릿:templates/. 테스트:tests/. 다른 모듈과 연결: 카페24 어댑터는app/integrations/cafe24토큰 재사용 · Project 주간 회의록 머리 카드가performance_store매출을 읽기 전용으로 씀 ·APP_ENCRYPTION_KEY는 입출고(Gmail 토큰)와 공유.
구조 (네 영역 분리)
- 수집 —
adapters/(쇼핑몰 하나 = 어댑터 파일 하나 +registry.py한 줄 + SQL seed 한 줄) +sync.py(공통 동기화, 같은 쇼핑몰 동시 실행 차단, 쇼핑몰별 실패 격리). - 보안 —
security/(AES-256-GCM, 키 버전, 비밀값 가리기) +credentials.py. - 계산 —
calc.py(주 = 월~일, 수수료 반올림은commission()한 곳, 요율 이력) +db.py. - 화면 —
dashboard.py/router.py/템플릿.
규칙
- 쇼핑몰 API 인증정보는
.env가 아니라 설정 화면에서 입력 → 마스터 키APP_ENCRYPTION_KEY로 암호화해 DB 저장, secret 원문은 화면으로 다시 보내지 않는다. - 쇼핑몰 API 는 백엔드에서만 호출, 오류·로그·raw 는
redact후 저장. - 매출 기준일: 결제 = 결제일, 취소·반품 = 발생일(
sync.sales_date_for). 금액은 원 단위 정수. - 권한키
performance. 설정 화면은 모듈 권한자 누구나(일반 사용자는 수수료율만), 수수료 외 설정 API 는is_admin. - 1단계는 모의 데이터(
is_sample)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. - 쇼핑몰 화면 수치와 맞출 때는 필드 추측 말고 붙여넣기 비교 + 원본 필드 합계로 진단부터.
카페24 적립금 · 네이버 배송비·환불 (2026-10-19 규칙 변경)
- 카페24 매출 = 결제합계 − 적립금 사용, 환불 = 실제 + 예치금(적립금 환불 제외). raw
points. 주문 내역 창 적립금 사용 칸·합계. - 네이버 매출 = 판매금액(총) + 배송비(raw
goods·ship— 배송 묶음마다deliveryFeeAmount한 번, 할인 안 뺌 = 판매분석 배송비, 10/18 87,500 확인), 환불 = 클레임 완료일(CLAIM_COMPLETED_DATETIME) 조회의 취소·반품 완료 상품주문 −결제금액(naver:{상품주문}-RF, rawrefund). 주문 내역 창 배송비·환불금액 칸·합계. - 예전 규칙으로 받은 날은 [과거 매출 가져오기]로 다시 받아야 바뀜(최근 10일은 자동). 사용자 확인값 10/18: 카페24 적립금 16,820 · 네이버 배송비 87,500 · 환불 66,100 — 배포 뒤 대조.
매출 업데이트
- 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로).
- 업데이트 중에도 [매출 업데이트] 누르기 가능(2026-10-19) — 버튼이 "업데이트 중 · 진행 보기"로 바뀌고, 누르면
GET /api/sync/current의 진행 중 작업(수동·자동)을 새로 시작하지 않고 진행 창으로 다시 연다. - 서버 시작 때 남은
perf_sync_runsrunning 행은abandon_running_runs로 "중단됨(서버 재시작)" 정리(앱은 프로세스 하나 — 진행 작업은 메모리에만). 예전엔 30분(STALE_RUN_AFTER) 동안 버튼이 '업데이트 중'으로 막히고 그 쇼핑몰이 '이미 진행 중'으로 건너뛰어졌다. - 자동 업데이트(
auto_sync.py, 웹 프로세스 데몬 스레드) — 매일 09~19시 정각·30분마다 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀. envPERFORMANCE_AUTO_SYNC·_DAYS·_HOURS. - 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(WING 판매분석 대조는 원본 데이터 확인으로).
수동 입력
- 설정의 쇼핑몰별 수동 입력 토글(마이그레이션 002
manual_input·perf_manual_sales) — 켜면 일자별 표 날짜 칸에 총매출 직접 입력, 넣은 날은 API 값 대신(daily_amounts한 곳). - 일자별 표 [엑셀 업로드] 팝업(
manual_upload.py,POST /performance/api/manual-sales/upload) — 1열 날짜·2열부터 쇼핑몰 이름 머리글, 수동 입력 켜진 쇼핑몰 열의 값 있는 칸만 반영(덮어씀, 빈 칸 그대로), 잘못된 칸이 하나라도 있으면 전부 저장 안 함, 샘플 = 모듈 폴더upload_sample.xlsx. - 열 순서 카페24·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰(마이그레이션 003).
- 쿠팡(로켓)·애터미아자몰은 수동 입력 전용(
adapters/manual.py,manual_only— 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐).
매출 실적 화면 (2026-10-19)
- 일자별 표 매출 칸 아래 광고비(ROAS%) 주황 줄(
--perf-ad,dashboard._ad_lines) — 광고비 탭과 같은 값(ad_spend.channel_roas). 쇼핑몰 → 광고 채널은dashboard.sales_ad_channels: 카페24 = 구글·메타 두 줄(이름 붙임), 네이버 = 네이버, 나머지는ROAS_SALES_CODE(쿠팡 ← 쿠팡(윙)). 일 합계 = 보이는 쇼핑몰 광고비 합(ROAS = 매출 합 ÷ 광고비 합). 광고비 표 없으면 줄 없음. - 매출 단위 원·천원·백만원 — 설정 "보기 설정"(누구나, 이 브라우저 쿠키
perf_unit), 서버가amount_text(천원 정수·백만원 소수 한 자리)로 그림(router._unit_ctx→ 템플릿amt). 광고비 탭은 원 그대로. - 설정의 진단 카드(쇼핑몰 원본 데이터 확인·카페24 매출 대조·일별 한 번에 비교)는 2026-10-19 화면에서 뺐다(서버 API
marketplaces/{code}/reconcile·daily-check는 진단용으로 남김).
광고비 (/performance/ads)
- 탭은 [매출 실적]·[광고비] + 맨 오른쪽 설정 톱니.
ad_spend.py, 마이그레이션 005perf_ad_spend. 구글·메타·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 일 광고비를 연·월·일로.- 칸 = "광고비(ROAS%)"(ROAS = 그 쇼핑몰 매출 ÷ 광고비). 구글·메타·네이버는 계산 안 함 — 광고 보고서 ROAS(마이그레이션 006
roas·metrics). - 날짜 칸 직접 입력 + 쿠팡(윙)·쿠팡(로켓)·네이버 광고 보고서 업로드.
- 쿠팡: 1열 날짜·19열 청구금액(+부가가치세).
- 네이버: 3열 기간·4열 총비용·12열 ROAS, 머리글 클릭 = 일자별 보고서 항목.
- 매출 대비 광고비 KPI.
- 광고 API 연동(마이그레이션 007
perf_ad_credentials·perf_ad_source_status) — 실적 설정 광고 API 연동 카드, 쇼핑몰과 같은 마스터 키로 암호화(AADperf:ad:…),ad_sources/(채널 하나 = 파일 하나) +ad_sync.py, 매출 자동 업데이트 회차에 함께. 결과는perf_ad_spendsource='api'(초록 숫자, API 가 안 준 날은 예전 API 값만 지움). - 구글 = Google Ads API(2026-10-15) — 고객 ID·(MCC)·서비스 계정 JSON·API 버전(기본 v26). 개발자 토큰은 2026-09-09 구글 폐지 — 접근 등급은 서비스 계정의 Cloud 프로젝트, 머리글 안 보냄. 광고비 탭 [구글 광고 불러오기](보는 기간). 광고비 = 비용 × 1.1(부가세 포함)·ROAS(전환 가치 ÷ 비용, 구글 값 그대로)·항목.
- 메타 = 메타 마케팅 API(2026-10-16,
ad_sources/meta_ads.py, 새 마이그레이션 없음) — 광고 계정 ID(여러 개, 날짜별 합산)·액세스 토큰(ads_read, 시스템 사용자 토큰 권장)·앱 시크릿(선택)·API 버전(기본 v26.0). 광고비 = 지출 금액 그대로(메타는 이미 부가세 포함 — × 1.1 은 구글만)·ROAS = 구매 전환값 ÷ 지출 금액(광고 관리자 구매 ROAS). USD 등 외화 계정은 그날 환율로 원화 환산(fx.py, Frankfurter 중앙은행 고시 환율 종합, 키 없음). 상세보기 [합계 | 계정별] 탭, [메타 광고 불러오기]·자동 업데이트 회차.