Files
dbx-main/app/modules/performance/CLAUDE.md
T
king de5a8a3d0a fix(performance): 일자별 표 제목·기간 합계 행 — 페이지 스크롤에 고정(매출·광고비), 스크롤 막대 배경 투명
- 10-26 판은 표 상자 안 세로 스크롤이라 진짜 ERP 셸에서 상자 아래가 화면 밖에 잘리고 휠이 페이지로 안 넘어갔다
- 표 상자 세로 스크롤 없앰 → stickyHead 가 .erp-page 스크롤마다 제목 행·기간 합계 행 칸을 translateY 로 내림(표 끝에서 멈춤),
  내려온 동안 제목 칸이 아래 1px 선을 직접 그림(border-collapse 선 틈으로 뒤 줄이 비침 방지)
- 스크롤 막대 트랙 투명(scrollbar-color, 표 상자·실적 화면)
- perf_sticky.browser.test.js 를 진짜 erp_base.html 셸 렌더(perf_*_shell.html)로 — 휠 스크롤·가로 고정·표 끝 멈춤

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-26 14:17:25 +09:00

17 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 토큰)와 공유.

구조 (네 영역 분리)

  1. 수집 — adapters/(쇼핑몰 하나 = 어댑터 파일 하나 + registry.py 한 줄 + SQL seed 한 줄) + sync.py(공통 동기화, 같은 쇼핑몰 동시 실행 차단, 쇼핑몰별 실패 격리).
  2. 보안 — security/(AES-256-GCM, 키 버전, 비밀값 가리기) + credentials.py.
  3. 계산 — calc.py(주 = 월~일, 수수료 반올림은 commission() 한 곳, 요율 이력) + db.py.
  4. 화면 — 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, raw refund). 주문 내역 창 판매금액(배송비 뺀 raw goods — 저장 금액은 판매금액+배송비)·배송비·환불금액 칸·합계 + 맨 아래 "그날 매출 = 판매금액 + 배송비 − 환불".
  • 예전 규칙으로 받은 날은 [과거 매출 가져오기]로 다시 받아야 바뀜(최근 10일은 자동). 사용자 확인값 10/18: 카페24 적립금 16,820 · 네이버 배송비 87,500 · 환불 66,100 — 배포 뒤 대조.

매출 업데이트

  • 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로).
  • 업데이트 중에도 [매출 업데이트] 누르기 가능(2026-10-19) — 버튼이 "업데이트 중 · 진행 보기"로 바뀌고, 누르면 GET /api/sync/current 의 진행 중 작업(수동·자동)을 새로 시작하지 않고 진행 창으로 다시 연다.
  • 서버 시작 때 남은 perf_sync_runs running 행은 abandon_running_runs 로 "중단됨(서버 재시작)" 정리(앱은 프로세스 하나 — 진행 작업은 메모리에만). 예전엔 30분(STALE_RUN_AFTER) 동안 버튼이 '업데이트 중'으로 막히고 그 쇼핑몰이 '이미 진행 중'으로 건너뛰어졌다.
  • 자동 업데이트(auto_sync.py, 웹 프로세스 데몬 스레드) — 매일 09~19시 정각·30분마다 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀. env PERFORMANCE_AUTO_SYNC·_DAYS·_HOURS.
  • 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(WING 판매분석 대조는 원본 데이터 확인으로).

수동 입력

  • 설정의 쇼핑몰별 수동 입력 토글(마이그레이션 002 manual_input·perf_manual_sales) — 켜면 일자별 표 날짜 칸에 총매출 직접 입력, 넣은 날은 API 값 대신(daily_amounts 한 곳). 수동 입력 켠 쇼핑몰은 API 가 설정돼 있어도 매출 업데이트(수동·자동·과거 매출 가져오기)에서 빠진다(2026-10-21, sync.sync_all 대상 고르기 한 곳) — 예전에 받은 API 값은 그대로 남음.
  • 일자별 표 [엑셀 업로드] 팝업(manual_upload.py, POST /performance/api/manual-sales/upload) — 1열 날짜·2열부터 쇼핑몰 이름 머리글, 수동 입력 켜진 쇼핑몰 열의 값 있는 칸만 반영(덮어씀, 빈 칸 그대로), 잘못된 칸이 하나라도 있으면 전부 저장 안 함, 샘플 = 모듈 폴더 upload_sample.xlsx.
  • 앞으로의 날짜도 입력·업로드 가능(2026-10-21) — 매출 수동 입력·광고비 날짜 칸, 매출 엑셀 업로드, 광고 보고서 업로드 모두(가져오기 API 는 여전히 오늘까지).
  • 계산식 입력(2026-10-21, formula.py parse_amount, 마이그레이션 008 formula 열) — 매출·광고비 날짜 칸에 = 없이 1000+2000(+ - * / 괄호, ×·÷)을 넣으면 서버가 계산(원 반올림)해 금액으로, 식은 formula 열에 저장 → 칸 is-formula 파랑 굵은 숫자, 다시 누르면 식. 숫자 입력·업로드·광고 API 로 덮으면 식 지움(db._set_formulas, 008 미적용이면 조용히 건너뜀). 광고비 탭 직접 입력값은 파랑 보통 굵기(굵게는 계산식만), 매출 탭 수동 입력값은 예전처럼 파랑 굵게.
  • 일자별 표 기간 합계 행은 맨 위(제목 행 바로 아래, 2026-10-21 calc.main_table) — 매출·광고비 공통, 연간 보기 "연간 합계"는 그대로 맨 아래.
  • 기간 빠른 선택 = 이번달·올해·직접선택(2026-10-26 — 오늘·이번주 버튼 삭제, dashboard.build_dashboard·ad_spend.build_ad_dashboard 의 nav.quick), 매출 실적 기본 기간도 이번달(router.dashboard_page period="month", 광고비는 원래 이번달). day·week 주소(?period=week)는 그대로 열린다.
  • 일자별 표 스크롤 고정(2026-10-26, 10-27 다시 .perf-main-wrap) — 페이지(.erp-page)를 스크롤해도 제목 행 + 맨 위 기간 합계 행 (tbody tr.perf-row-total:first-child)이 화면 위에 붙어 있다. 표 상자는 가로 스크롤 상자라 CSS sticky 가 페이지 스크롤에 안 먹어서 performance.js stickyHead 가 스크롤(capture)·창 크기·표 크기마다 두 줄 칸을 translateY 로 내린다(표 끝에서 멈춤, 내려온 동안 is-stuck → 제목 칸 ::after 가 아래 1px 선 — 표 칸 선(border-collapse)은 안 움직여 틈이 비쳤다). 표 상자 세로 스크롤 금지 — 10-26 판은 상자를 화면 높이로 묶어 상자 안에서 스크롤했는데, 진짜 셸에서는 상자 아래가 화면 밖에 잘리고(overscroll-behavior: contain) 휠이 페이지로 안 넘어갔다. 스크롤 막대 배경(트랙) 투명 = scrollbar-color: #c3c6cb transparent(표 상자·실적 화면 .erp-page). 테스트 tests/js/perf_sticky.browser.test.js (진짜 erp_base.html 셸 렌더 perf_*_shell.html 로 휠 스크롤 — 스텁 셸로는 이 문제가 안 보였다).
  • 열 순서 카페24·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰(마이그레이션 003).
  • 쿠팡(로켓)·애터미아자몰은 수동 입력 전용(adapters/manual.py, manual_only — 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐).
  • 직접 추가 쇼핑몰·그룹·순서 드래그(2026-10-22, 마이그레이션 009 is_custom·is_group·parent_code) — 설정 [+ 쇼핑몰 추가(수동 입력)] (코드 custom_…, get_adapter 가 CustomManualAdapter = 수동 입력 전용)·[+ 그룹 추가](group_…, 매출 없음·include_in_sales 꺼짐), 직접 추가 쇼핑몰만 그룹 select 로 묶음, 이름 변경·삭제(삭제 = 그 쇼핑몰 수동 입력·수수료도). 매출 실적 표 그룹 열 = 보이는 하위 합계(일 합계엔 안 더함), ▾/▸ 하위 열 접기(localStorage). ⠿ 드래그 → PUT /api/marketplace-order → sort_order, 화면 순서는 dashboard.ordered_marketplaces (그룹 바로 뒤 하위) 한 곳. 상세 docs/PERFORMANCE_MODULE.md "직접 추가 쇼핑몰·그룹".
  • 매출 실적 표 모양(2026-10-22) — table.perf-autofit(매출 탭만, 모든 기간 같음): 표가 100% 로 늘지 않고 열 너비 = 내용 길이, 날짜 열은 고정 210px 대신 자동 + 가로 스크롤해도 고정(sticky left, 오른쪽 그림자). 그룹 열 = 진한 보라 머리·왼쪽 묶음 선, 하위 열 = 옅은 보라 머리(위 띠)·옅은 칸, 마지막 하위(is-glast, 접히면 그룹 열 is-gclosed) = 오른쪽 선. 접기 단추 = 22px ⊟/⊞(SVG, 세로 막대가 돌아 바뀜). 접기·펴기 애니메이션 = 하위 칸 내용 .perf-gc 너비·칸 여백·투명도 260ms(setGroup(code, fold, animate), 끝나면 is-gfolded display:none, 빠르게 연속 클릭은 groupRun 번호로 마지막만, 움직임 줄이기면 바로).

매출 실적 화면 (2026-10-19)

  • KPI 는 수수료 차감 매출 하나만 화면 왼쪽 한 줄(.perf-kpi-line — 금액 + 비교 기간 대비 %, 모든 기간 공통). 총매출·수수료·월/연 누적 카드는 뺐다.

  • 일자별 표 기본 보기 = 수수료 차감 매출(라우터 기본 metric=net, 예전에 고른 보기 localStorage 는 안 씀).

  • 마지막 업데이트 옆 다음 업데이트까지 남은 시간 초 단위 실시간(router._auto_sync_ctx → performance.js initNextUpdate, 자동 업데이트 규칙 auto_sync.next_slot 과 같게 화면이 다음 회차 계산, 서버 시각으로 PC 시계 보정, 자동 업데이트 꺼지면 숨김).

  • 일자별 표 매출 칸 아래 광고비(ROAS%) 주황 줄(--perf-ad, dashboard._ad_lines) — 광고비 탭과 같은 값(ad_spend.channel_roas). 쇼핑몰 → 광고 채널은 dashboard.sales_ad_channels: 카페24 = 구글·메타 두 줄(이름 붙임), 네이버 = 네이버, 나머지는 ROAS_SALES_CODE(쿠팡 ← 쿠팡(윙)). 일 합계 = 보이는 쇼핑몰 광고비 합, ROAS = 일 합계 금액 ÷ 일 합계 광고비(2026-10-19 — 예전엔 광고비 있는 쇼핑몰 매출만 더했다; roas 총매출·roas_net 수수료 차감 매출 기준, 보기 기준에 따라 하나만). 광고비 표 없으면 줄 없음.

  • 매출 단위 원·천원·백만원 — 설정 "보기 설정"(누구나, 이 브라우저 쿠키 perf_unit), 서버가 amount_text(천원 정수·백만원 소수 한 자리)로 그림(router._unit_ctx → 템플릿 amt). 광고비 탭은 원 그대로.

  • 설정의 진단 카드(쇼핑몰 원본 데이터 확인·카페24 매출 대조·일별 한 번에 비교)는 2026-10-19 화면에서 뺐다(서버 API marketplaces/{code}/reconcile·daily-check 는 진단용으로 남김).

날짜 칸 메모 (2026-10-22, 마이그레이션 010 perf_cell_memos)

  • 매출 실적·광고비 일자별 표의 쇼핑몰(광고 채널) 날짜 칸 전부(td[data-memo-code] — 매출 탭은 수동 입력 칸 + API 쇼핑몰 칸, 같은 날 넓힘; 그룹 열·주간합계·합계 줄은 아님) 우클릭 → [메모 삽입] / [메모 수정]·[메모 삭제](.perf-ctx 메뉴, 창에서 입력, Ctrl+Enter 저장). 왼쪽 클릭은 그대로(입력 칸 = 금액 입력, API 칸 = 주문 내역). PUT /performance/api/cell-memos/{kind}/{코드}/{날짜} (kind = sales 쇼핑몰 / ad 광고 채널, 빈 메모 = 지움, 1,000자), 모듈 권한자 누구나.
  • 메모 있는 칸 = 오른쪽 위 빨간 삼각형(has-memo, 엑셀 메모처럼), 마우스 올리면 노란 메모 상자(.perf-memo-tip). 금액과 따로 저장(금액 지워도 남음). 화면 데이터 memo_cells("날짜|코드" → 메모, db.cell_memos), 010 미적용이면 표시 없음·저장만 503. 표를 스크롤하면 열린 메뉴는 닫힌다.
  • 테스트 test_cell_memos.py, tests/js/perf_memo_ads.browser.test.js.
  • 표 몸통 칸에는 풍선 도움말(title) 없음(2026-10-22 사용자 요청) — 입력 칸·날짜 칸(공휴일은 칸 안 글자)·광고비 줄 모두. 열 머리글 말풍선은 그대로. 새 칸 기능에 title 을 다시 달지 말 것(설명은 표 아래 안내 문구에).

광고비 (/performance/ads)

  • 탭은 [매출 실적]·[광고비] + 맨 오른쪽 설정 톱니.
  • 표 모양(2026-10-22) — 매출 실적 표와 같은 perf-autofit(열 너비 = 내용 길이, 날짜 열 가로 스크롤 고정).
  • 기타광고비 열(etc, 애터미아자몰 오른쪽, 2026-10-22) — 쇼핑몰에 딸리지 않은 광고비 직접 입력. 매출 쇼핑몰이 없어(ad_spend.NO_SALES) ROAS 없음·매출 탭 광고비 줄에 안 나옴, 광고비 합계·매출 대비 광고비에는 들어감.
  • ad_spend.py, 마이그레이션 005 perf_ad_spend. 구글·메타·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 일 광고비를 연·월·일로.
  • 칸 = "광고비(ROAS%)"(ROAS = 그 쇼핑몰 매출 ÷ 광고비). 구글·메타·네이버는 계산 안 함 — 광고 보고서 ROAS(마이그레이션 006 roas·metrics).
  • 날짜 칸 직접 입력 + 쿠팡(윙)·쿠팡(로켓)·네이버 광고 보고서 업로드.
    • 쿠팡: 1열 날짜·19열 청구금액(+부가가치세).
    • 네이버: 3열 기간·4열 총비용·12열 ROAS(구매완료 광고수익률(%)), 머리글 클릭 = 일자별 보고서 항목. 총비용·광고수익률은 머리글 이름으로 찾음(열 구성 바뀐 보고서 — 고정 12열이 비어 ROAS 누락됐던 문제, 2026-10-20). 광고수익률 칸이 없거나 비면 구매완료 전환매출액 ÷ 총비용. 저장된 roas 가 빈 예전 행은 db.ad_roas 가 metrics 에서 다시 구함(ad_spend.roas_from_metrics).
    • 일자별 보고서 창: ROAS 열은 광고비 열 바로 오른쪽, 네이버 "구매완료 광고수익률(%)" 머리글은 "ROAS(%)"로 표기(ad_spend._roas_next_to_spend → labels, 저장 키는 파일 머리글 그대로 — 예전 업로드도 그대로 적용).
  • 매출 대비 광고비 KPI.
  • 광고 API 연동(마이그레이션 007 perf_ad_credentials·perf_ad_source_status) — 실적 설정 광고 API 연동 카드, 쇼핑몰과 같은 마스터 키로 암호화(AAD perf:ad:…), ad_sources/(채널 하나 = 파일 하나) + ad_sync.py, 매출 자동 업데이트 회차에 함께.
  • [광고비 업데이트](2026-10-20, 예전 채널별 [구글/메타 광고 불러오기] 버튼 삭제) — 광고비 탭 오른쪽 위, 매출 탭과 같은 모양: 마지막 업데이트(광고 API 마지막 성공 가져오기 ad_sync.last_ad_update_at) · 다음 업데이트까지(매출과 같은 회차 카운트다운) · 버튼. 설정된 광고 API 전부를 진행 창 작업으로(POST /api/ad-sync → jobs kind="ads", 채널별 막대 수집 50% → 저장 → 완료, 채널별 [중지]·[업데이트 취소]는 저장 직전까지, 진행·취소·중지 API 는 매출과 같은 /api/sync/jobs/…). 진행 중이면 새로 시작 안 하고 합류(GET /api/ad-sync/current, 매출 업데이트와 별개). 자동 업데이트 회차(auto_sync.run_once)는 매출과 광고비를 동시에 각각 진행 창 작업으로, 이미 돌고 있는 종류만 그 회차 건너뜀. 결과는 perf_ad_spend source='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 중앙은행 고시 환율 종합, 키 없음). 상세보기 [합계 | 계정별] 탭, [광고비 업데이트]·자동 업데이트 회차. 기간으로 물으면 메타가 지출·노출·클릭을 0 으로 주는 문제(2026-10-21 운영 확인, v26.0 — 링크 클릭·구매는 정상, 하루만 물으면 정상) → "지출·노출 0 인데 링크 클릭·구매가 있는" 날만 하루씩 다시 물어 바꾼다(meta_ads._refetch_suspect_days). 원본 진단: scripts/meta_insights_raw.py (docker exec -i dbx-main python - 시작일 [종료일] < scripts/meta_insights_raw.py, 읽기 전용).