Files
dbx-main/app/modules/performance/CLAUDE.md
T
king 3d14ff4a85 feat(performance): 기간 빠른 선택 이번달·올해만(기본 이번달) · 일자별 표 제목·기간 합계 행 스크롤 고정
- 매출 실적·광고비 탭 오늘·이번주 버튼 삭제, 매출 실적 기본 기간 = 이번달
- 일자별 표 상자(.perf-main-wrap)를 화면 높이로 묶어 상자 안 세로 스크롤 — 제목 행 + 맨 위 기간 합계 행 sticky
  (합계 행 top = 제목 행 높이 --perf-head-h, stickyHead 가 ResizeObserver 로 잼), 날짜 열 가로 고정은 그대로
- 테스트: perf_sticky.browser.test.js(실제 브라우저), test_ad_spend 빠른 선택 순서

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

109 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# [실적] 실적 모듈 — `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, `.perf-main-wrap`) — 표 상자를 화면 높이(`100vh − 상단 바 − 24px`)로 묶어 상자 안에서 세로 스크롤,
제목 행 + 맨 위 기간 합계 행(`tbody tr.perf-row-total:first-child`)이 sticky. 합계 행 top = 제목 행 높이(`--perf-head-h`, `performance.js stickyHead`
가 ResizeObserver 로 잼). 상자가 가로 스크롤이라 페이지 스크롤 기준 sticky 는 안 먹어서 상자 안 스크롤로 했다. 테스트 `tests/js/perf_sticky.browser.test.js`.
- 열 순서 카페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`, 읽기 전용).