359ff29e95
버튼 위에 올리면 커서 바로 위에 쇼핑몰(열) 이름 — 글자 크기는 열 제목과 같은 12px 굵게. 머리글 th 의 기본 title 말풍선은 버튼 title="" 로 막음. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
146 lines
26 KiB
Markdown
146 lines
26 KiB
Markdown
# [실적] 실적 모듈 — `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`, 웹 프로세스 데몬 스레드) — 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀. env `PERFORMANCE_AUTO_SYNC`(끄기)·`_DAYS`·`_HOURS`(일정 저장 전 기본 시간대).
|
|
- **일정 = 실적 설정 "자동 업데이트" 카드**(2026-10-26, 관리자, 마이그레이션 011 `perf_settings` key `auto_sync`) — 매출 실적·광고비 **따로**:
|
|
사용·요일(0=월…6=일, [매일]·[평일])·시작/끝 시각(5분 단위)·간격(5~720분, 5분 단위, 기본 30). 회차 = 고른 요일의 시작, 시작+간격, … 끝까지(끝과 맞으면 끝도).
|
|
`PUT /api/auto-sync-schedule {sales, ads}`(`auto_sync.validate_schedule`, 011 미적용 503). 스레드(`auto_sync.Scheduler`)가 1분마다 일정을 다시 읽어
|
|
바뀐 종류만 지금부터 다시 계산, 종류마다 따로 스레드(`run_once(kinds=(kind,))`). 저장 값 없음·011 미적용 = 기본(매일 9~19시 30분마다).
|
|
- 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(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` 로 휠 스크롤 — 스텁 셸로는 이 문제가 안 보였다).
|
|
- **새로고침해도 스크롤 유지**(2026-11-02) — 수기 입력을 마치면 합계를 다시 계산하려고 새로고침하는데, 세로 스크롤은 `.erp-page` 상자라 브라우저가 복원하지 않아 맨 위로 돌아갔다.
|
|
`performance.js keepScroll` 이 떠날 때 세로·가로 위치를 sessionStorage `perf_scroll` 에 저장 → **새로고침일 때만** 복원(같은 주소, 메뉴·기간 이동은 맨 위부터). 자동 새로 고침·업로드 뒤 새로고침도 같음.
|
|
- 열 순서 카페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` "직접 추가 쇼핑몰·그룹".
|
|
- **카페24(전체)·카페24(실적) 열**(2026-11-02, 예전 "공구 제외") — 카페24 열 이름 = 카페24(전체)(`_short_name`), 바로 오른쪽 카페24(실적) = 카페24 − 직접 추가 쇼핑몰 "자사몰(공동구매)"("카페24 공동구매"도, 이름으로 찾음·띄어쓰기 무시 — 없으면 전체 그대로, 쇼핑몰 필터·숨김과 무관하게 뺌).
|
|
광고비 줄은 카페24(전체)와 같은 구글·메타(`dashboard._cafe24_real_column`, kind `diff`, 표 열만 — 일 합계엔 안 더함, 클릭·메모 없음). 공동구매 칸을 저장하면 그 줄 칸이 바로 바뀜(`performance.js saveManual`, td `data-diff-minus`·`data-base`), 합계 줄은 입력 마친 뒤 새로고침 때. 상세 `docs/PERFORMANCE_MODULE.md` "직접 추가 쇼핑몰·그룹".
|
|
- **합계 기준**(2026-11-02) — 일 합계 = 카페24(실적) + 공동구매 + 나머지 쇼핑몰(카페24(전체)는 안 더함 — 공동구매가 들어 있어 중복). 일 합계·ROAS·KPI·추이·비중·월/연 누적 모두 `dashboard._summary_cells`(카페24 칸 = 실적, 그래프·누적의 카페24 줄 이름도 `summary_names` = 카페24(실적)), 표의 카페24(전체) 열만 원래 값. 광고비 탭 매출 대비 광고비·합계 ROAS = `total_sales_codes`(카페24 있으면 공동구매 코드 뺌, 같은 금액). **프로젝트 회의록 머리 카드는 아직 예전 합계**(`project/router.py` `total` — 공동구매 중복).
|
|
- **매출 실적 표 열 숨기기**(2026-11-02) — 실적 설정 "공통 보기 설정" 카드(관리자만, `PUT /api/hidden-marketplaces`, `perf_settings` key `hidden_marketplaces`, 011 미적용 503) → **모든 사용자에게 적용**. **열만** 숨김(`dashboard.load_hidden`) — 일 합계·KPI·그래프·누적은 그대로, 그룹 열 = 보이는 하위 합계(다 숨기면 그룹 열도 없음). 쇼핑몰 필터(합계까지 바뀜)와 다름. 광고비 탭은 적용 안 함.
|
|
- **일 합계 열 위치**(2026-11-02) — 매출 실적·광고비 표 모두 날짜 바로 오른쪽, 날짜 열과 함께 가로 고정(왼쪽 위치 `--perf-label-w` = 날짜 열 너비, `performance.js stickyHead`).
|
|
- **기간 이동**(2026-11-02, `_period_nav.html` 공통) — 날짜 바로 좌우 화살표 SVG(글자 높이, 진한 회색), 글자 버튼 없음.
|
|
- **매출 실적 표 모양(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(store, kind)` — 매출 탭 = 매출 일정, 광고비 탭 = 광고비 일정 → `performance.js initNextUpdate`·`nextScheduleSlot`, `auto_sync.next_slot` 과 같은 규칙으로 화면이 다음 회차 계산, 서버 시각으로 PC 시계 보정, 자동 업데이트(env·그 종류 일정) 꺼지면 숨김).
|
|
- **화면 자동 새로 고침**(2026-10-26) — 자동 업데이트(다른 사람이 누른 업데이트 포함)가 끝나면 매출 실적·광고비 화면이 20초 안에 reload.
|
|
화면 데이터 `update_watch`(`router._update_watch` = 그린 때 마지막으로 끝난 작업 id, 보는 사람 것 제외) ↔ `GET /api/update-status?kind=sales|ads`
|
|
(`jobs.last_finished` — 메모리 작업만, DB 안 읽음). 도는 중이면 끝날 때까지, 칸 입력·창(`.perf-modal`)·메뉴·확인 창이 열려 있으면 닫힐 때까지 기다림
|
|
(마지막 업데이트 옆 안내), 탭이 안 보이면 안 묻고 다시 보이면 바로. 보는 사람이 직접 누른 업데이트는 진행 창이 새로 그린다. `performance.js initUpdateWatch`.
|
|
|
|
- 일자별 표 매출 칸 아래 **광고비(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` 수수료 차감 매출 기준, 보기 기준에 따라 하나만). 광고비 표 없으면 줄 없음.
|
|
- **열 접기**(2026-11-06) — 매출 실적·광고비 일자별 표 머리글 위 작은 화살표 버튼(`.perf-cfold`, `performance.js initColFold`)으로 열 하나씩 접기/펴기(날짜 열 빼고, 일 합계·그룹 열 포함).
|
|
접은 열 = 26px 띠(`is-cfold`, 칸 내용 숨김·클릭/메모 안 됨, 너비는 JS `CFOLD_W` 와 CSS 같게, 수동 열 너비 표도 같음). **로그인한 사람 본인에게만** —
|
|
`PUT /api/my-col-fold {kind: sales|ads, cols}` → `perf_settings` key `col_fold:<이메일 sha1>`(key 64자 제한) = `{sales, ads}`, 화면은 표 `data-col-fold`(라우터 `_load_col_fold`). 011 미적용이면 다 펼침·저장 503.
|
|
버튼 위 말풍선 = 커서 바로 위를 따라다니는 `.perf-cfold-tip`(열 이름, 12px 굵게 = 제목 글자), 버튼 `title=""` 로 머리글 기본 말풍선 막음.
|
|
그룹 하위 열 접기(⊟, localStorage)와는 별개. 테스트 `tests/js/perf_colfold.browser.test.js`, `test_custom_groups.py::test_api_my_col_fold_per_user`.
|
|
- **표 열 너비 자동/수동**(2026-10-27) — 설정 "보기 설정" **표 열 너비** [자동(글자 길이)]·[수동 조절](누구나, 이 브라우저 쿠키 `perf_colw`, `router._colw_ctx` → 템플릿 `colw`).
|
|
수동 = 매출 실적·광고비 일자별 표에 `perf-colw-manual` → `performance.js initColWidths` 가 자동 너비를 잰 뒤 `table-layout:fixed`(`is-colw-fixed`, 넘치는 글자 …),
|
|
머리글 오른쪽 경계 `.perf-colw-grip` 드래그(최소 36px)·두 번 누르면 그 열만 자동. **날짜 열(`label`)은 조절 불가 — 늘 자동 너비, 손잡이 없음, 저장값 무시**. 너비 = localStorage `perf_colw_sales`/`perf_colw_ads`(th `data-col` = 쇼핑몰·채널 코드·`label`·`total`)에 계속 유지,
|
|
설정 [조절한 너비 초기화]가 둘 다 지움. 그룹 접기·펴기 때 열 너비도 함께 움직임(`colw.animate/settle`). 테스트 `tests/js/perf_colw.browser.test.js`.
|
|
- **매출 단위** 원·천원·백만원(2026-11-02 모든 사용자 공통) — 설정 "공통 보기 설정"(관리자, `PUT /api/display-unit`, `perf_settings` key `display_unit`, 저장 값 없음·011 미적용 = 원, 예전 쿠키 `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/tiktok`, 2026-11-05, 마이그레이션 없음)
|
|
|
|
- 광고비 탭 틀(기간 이동·KPI·표·그래프·연 누적), 표 열 = ROAS·광고비·매출. 값은 광고 API 만(읽기 전용, 칸 입력·메모 없음). 화면 데이터 `ad_spend.build_tiktok_dashboard`.
|
|
- **틱톡 탭에서만 보임** — 채널 코드 `tiktok` 은 `ad_sources` 에는 있지만 `ad_spend.CHANNELS` 에는 넣지 않는다(넣으면 광고비 탭 합계에 들어감). 쇼핑몰 표(`perf_marketplaces`)에도 없어 매출 실적 합계·열과 무관. 저장은 다른 광고 API 처럼 `perf_ad_spend`(`source='api'`), 매출 = `metrics["매출"]`.
|
|
- 설정 = 실적 설정 **광고 API 연동** 카드 → 틱톡 — 광고 계정 ID·장기 액세스 토큰·틱톡샵 ID(선택). [광고비 업데이트]·광고비 자동 업데이트에 함께 돈다.
|
|
- `ad_sources/tiktok_ads.py` — `report/integrated/get`(30일씩), 매출 = 웹 구매금액 + 틱톡샵 매출, 틱톡샵 ID 가 있으면 `gmv_max/report/get` 비용·매출도 더함(항목별 값은 metrics 에 따로 저장). 외화 계정은 그날 환율로 원화(`fx`). ROAS = 매출 ÷ 광고비.
|
|
**실제 토큰 대조 전**(2026-11-05) — 공식 문서를 읽지 못해 지표 이름은 이차 자료로 확인. 일반 보고서에 GMV Max 가 이미 들어 있으면 틱톡샵 ID 를 넣었을 때 중복되므로, 처음 쓸 때 광고 관리자 화면과 대조할 것.
|
|
|
|
## 광고비 (`/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 는 **한 줄**(2026-10-30, 매출 실적처럼 `.perf-kpi-line` — 항목 `.perf-kpi-item` 을 세로 선으로 나눔, 좁은 화면은 한 항목씩): 광고비(전 기간 대비) · 매출 대비 광고비 · 연 누적 광고비. 월 누적 광고비 카드는 뺐다.
|
|
- 광고 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`, 읽기 전용).
|