From b397bdf83bae1eb0eb5ea52f40307574ace34583 Mon Sep 17 00:00:00 2001 From: king Date: Fri, 16 Oct 2026 13:09:43 +0900 Subject: [PATCH] =?UTF-8?q?feat(performance):=20=EB=A9=94=ED=83=80=20?= =?UTF-8?q?=EA=B4=91=EA=B3=A0=20API=20=EC=97=B0=EB=8F=99=20=E2=80=94=20?= =?UTF-8?q?=EA=B4=91=EA=B3=A0=EB=B9=84=C2=B7=EA=B5=AC=EB=A7=A4=20ROAS=20?= =?UTF-8?q?=EC=9E=90=EB=8F=99=20=EA=B0=80=EC=A0=B8=EC=98=A4=EA=B8=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - ad_sources/meta_ads.py + registry 한 줄: Meta Marketing API Insights(기본 v26.0), level=account·하루 단위, 광고 계정 여러 개를 날짜별로 합산, paging.next 따라감(graph.facebook.com 밖 주소 거부). - 설정(실적 설정 → 광고 API 연동): 광고 계정 ID(여러 개)·액세스 토큰(암호화)·앱 시크릿(선택, appsecret_proof)·API 버전. - 광고비 = 지출 금액 × 1.1(부가세 포함, 구글과 같은 기준), ROAS = 구매 전환값 ÷ 지출 금액(광고 관리자 구매 ROAS). 구매 값은 omni_purchase → purchase → 픽셀 구매 중 처음 있는 것 하나(겹친 값 더하지 않음). 원화 계정만. - 메타 오류 코드 안내(토큰 만료 190·권한 200·계정 ID 100·호출 한도), 오류 문구에 토큰·주소 미포함. - 메타 머리글 = 일자별 보고서 표(DETAIL_CHANNELS), 화면 안내 문구·문서 갱신. 새 마이그레이션·환경변수 없음. - 테스트: test_meta_ads.py(가짜 메타 서버, 실제 fetch_days → AdSyncService), 메타 연동 반영해 기존 테스트 기대값 갱신. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- .../performance/ad_sources/meta_ads.py | 280 ++++++++++++++++++ .../performance/ad_sources/registry.py | 3 +- app/modules/performance/ad_spend.py | 4 +- app/modules/performance/router.py | 4 +- .../templates/performance/ads.html | 12 +- .../templates/performance/settings.html | 7 +- .../performance/tests/test_ad_spend.py | 2 +- .../performance/tests/test_google_ads.py | 4 +- .../performance/tests/test_meta_ads.py | 226 ++++++++++++++ docs/PERFORMANCE_MODULE.md | 20 +- tests/js/perf_manual.test.js | 2 +- 12 files changed, 546 insertions(+), 20 deletions(-) create mode 100644 app/modules/performance/ad_sources/meta_ads.py create mode 100644 app/modules/performance/tests/test_meta_ads.py diff --git a/CLAUDE.md b/CLAUDE.md index b069d5c..eaf9ea8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -38,7 +38,7 @@ Claude Code는 이 저장소에서 작업을 시작하기 전에 **반드시 아 - 카페24 상품관리 (`app/modules/cafe24/`, `cafe24_db`) — 카페24 관리자에 들어가지 않고 상품 상세페이지(description HTML) 조회·편집·즉시적용·예약적용·버전 이력. 3분할 화면(목록 | HTML 편집기 | 상품 정보 패널). 정보 패널(`routes_product_info.py`, `_side.html`)에서 상품명·판매가·공급가·소비자가, 대표이미지(`POST /admin/products/{no}/images` 에 base64 data URI + `image_upload_type=A` — NNEditor 업로드 경로를 PUT `detail_image` 에 넣는 방식은 적용 안 됨), 옵션(생성/이름·썸네일·표시방식 수정/삭제)·품목(자체코드·추가금액·진열·판매)을 수정. 카페24 OAuth/API 클라이언트는 향후 주문관리와 공유하기 위해 **공통 계층 `app/integrations/cafe24/`** 에 둔다 — 라우터에서 `httpx`/`requests` 직접 호출 금지. 토큰은 Fernet 암호화 저장(`CAFE24_TOKEN_SECRET`), 로그/화면에 토큰·시크릿 절대 미출력. 쓰기 직전 항상 카페24 현재 HTML 을 다시 읽어 `BACKUP` revision 생성(로컬 값을 현재값으로 가정 금지). **카페24 관리자 API 는 PUT 뒤 한동안 GET 에서 예전 값을 돌려준다(읽기 지연)** — 우리 캐시 문제가 아니다. 그래서 "마지막 쓰기가 권위": 상세설명은 카페24 값이 최근 revision 중 하나와 같으면 지연으로 보고 마지막 MANUAL/SCHEDULED 를 표시·지문 기준으로 쓰고(`store.resolve_description`), 스칼라(상품명·가격·이미지·진열/판매)는 PUT 응답 스냅샷(`cafe24_products.last_write_snapshot`, 마이그레이션 004)과 GET 의 `updated_date` 를 비교해 덮어씌운다(`store.overlay_recent_write`). 유예시간 `CAFE24_READ_LAG_GRACE_MIN`(기본 360분). 쓰기 후 화면은 PUT 응답으로 그리고 다시 GET 하지 않는다. 예약은 DB 저장 + 별도 worker(`app/modules/cafe24/worker.py`, compose 서비스 `dbx-cafe24-worker`)가 처리 — 웹 프로세스에서 대기하지 않는다. 권한키 `cafe24`(연결/해제는 admin 전용). 상세는 `docs/CAFE24_MODULE.md` - 프로젝트 관리 (`app/modules/project/`, `project_db`) — 아사나식. 프로젝트/서브프로젝트(self-FK `parent_id`, CASCADE)·프로젝트 색상(32색 — 아사나 16색 + 진한 16색, 수정 창 12열)·아이콘(`projects.icon`, Material Symbols 42종, 마이그레이션 011 + [아사나 아이콘] 탭 33종 `"asana:"+이름`, 채워진 모양 전용 부분 글꼴 `material-symbols-asana.woff2`)·작업(`tasks`: 담당자·우선순위·시작/마감)·진행단계(`project_stages` 칸반, 새 프로젝트는 섹션 없이 시작 — `create_project(seed_stages=True)` 일 때만 기본 4단계, 섹션 머리는 모두 `#f3f3f3` — 섹션별 색 지정 없음, 섹션 이름 굵게, 섹션 기본 담당자 `default_assignee_email` — 담당자 빈 작업을 그 섹션에 만들거나 옮기면 자동 배정, 마이그레이션 009)·멤버 배정(`project_members`)·활동이력(`project_activity`). 첫 화면(`/project/`)은 **내 작업 목록**(프로젝트 홈 카드 화면은 폐지). 프로젝트 화면은 캘린더(FullCalendar)/타임라인(vis-timeline)/보드/목록/대시보드 뷰 토글. 좌측 사이드바는 수신함·내 작업·휴지통·프로젝트 화면 공용(`templates/project/_side.html` + 프로젝트 목록 동작 `initSideTree`, 새 프로젝트/수정 모달 `_side_modals.html`) — 프로젝트 목록(순서 변경·✎·×)은 어느 화면에서나 같다. 보드는 아사나처럼 섹션이 가로로 계속 늘어나고(넘치면 가로 스크롤) 카드의 담당자·마감일을 클릭해 그 자리에서 바꾼다. 좌측 사이드바에 수신함·전체 보기(Pro user 이상 — 예전 오른쪽 위 "전체 프로젝트" 토글, `?scope=all`)·내 작업(접이식) 메뉴. 설명란 서식 도구에 글자 색·크기(서버는 span style 의 color·font-size 만 허용, `desc_inline_style`). 설명란은 주소 붙여넣기 시 자동 링크, 설명란·댓글에서 @로 멤버를 태그하면 (`task_mentions`, 마이그레이션 006) 수신함에 그 작업이 쌓인다. 진입 권한키 `project`(관리자 페이지 토글로 직원별 부여, admin 자동). **관리자 등급 4단계(2026-10-12) — 수퍼관리자(`SUPER_ADMIN_EMAIL` 한 명 고정, 추가 불가) > Admin(`role=admin`) > Pro user(`role=pro`) > User** — 판단은 `access.is_pro`(Pro user 이상)·`access.is_project_admin`(Admin 이상), 라우터 `_require_pro`, 화면 `pj_pro`·`pj_admin`(`_role_ctx`, `is_admin` 은 ERP 상단 관리자 메뉴용 그대로). pro 는 프로젝트 모듈 밖에서는 user 와 같다. 새 프로젝트·프로젝트 이름/색/아이콘/소유자 수정·멤버 배정(자기가 멤버인 프로젝트)·사이드바 순서·남의 댓글 수정/삭제·휴지통·전체 보기·담당자별 합계·전체 멤버 = Pro user 이상, 프로젝트·섹션 삭제 = Admin 이상 또는 만든 사람, 작업 삭제·서브프로젝트 = 멤버 누구나(표는 docs/PROJECT_MODULE.md 6-14). 배정 멤버(또는 owner)만 그 프로젝트를 조회 — **관리자도 멤버가 아니면 안 보임, 예외는 슈퍼관리자뿐**(2026-10-07, `access.sees_all_projects`; 사이드바 목록·검색·휴지통·알림도 같은 기준, 화면·API 모두 비멤버 403)하고 서브프로젝트/작업/단계 CRUD — URL 의 섹션·부모 작업이 그 프로젝트 것인지 서버가 검증. 실시간 반영은 `project_live_version` 카운터(마이그레이션 007, 미적용 시 MAX 폴백). 사이드바 전체 검색(`/api/search`, 제목·설명·댓글, pg_trgm) + 프로젝트/내 작업 필터 바(찾기·상태·담당자·마감·우선순위·정렬, 클라이언트 필터). 협업자(`task_followers`, 자동 팔로우: 만든 사람·담당자·댓글·@태그) — 완료·댓글 알림은 담당자+협업자에게만. 나를 태그하거나 작업이 배정되면 프로젝트 화면 가운데 아래에 깜박이는 큰 팝업(닫기 전까지, `initTaskAlerts` + `GET /api/notifications/alerts`). 작업 삭제는 휴지통(`project_trash`, 마이그레이션 010) — 삭제 직전 스냅샷 3개월 보관, Pro user 이상만 보기·복구(`/project/trash`). 권한은 **지금 기준 공통 모듈 `access.py`**(목록·배지·알림·멘션·메일 수신자·삭제·댓글 수정까지 — 멤버에서 빠지면 기록이 있어도 안 보이고 알림도 없음), 소유자 변경은 Pro user 이상, 연결(멀티호밍)된 작업은 연결된 프로젝트 멤버에게 읽기 전용(docs/PROJECT_MODULE.md 6-10). 연간 목표(마이그레이션 013, `goal_*` 테이블) — 사이드바 "목표" → 연도 펼침 → `/project/goals/{연도}` 에 매출(목표·실적·달성)·로아스 월별 숫자 + 업무 영역(상품·마케팅·컨텐츠·유통 등)별 연간·월별 글, 조회는 전원·입력(주차별 목표·연도 추가/삭제 포함)은 Pro user 이상. 3·6·9·12월 오른쪽 1~4분기 칸(글 칸 13=1분기·15=2분기·14=3분기·16=4분기 — 예전 반기 칸 번호 재사용, 15·16 은 마이그레이션 017) + 분기 월 칸 접기 애니메이션(localStorage `pj_goal_fold_q`, 표는 `width:1px`+`table-layout:fixed`), 영역·줄 이름 클릭 바로 수정, **엑셀식 칸 병합**(마우스로 끌어 사각형 선택 → 우클릭 셀 병합/병합 해제, 같은 영역 안 세로 `row_span` + 같은 분기 월 칸 가로, 글은 왼쪽 위 칸 — `goal_cell_merges`, 마이그레이션 014·015·017), 3열 줄 추가는 같은 항목 칸(2열) 안에(`goal_rows.label_cont`, 마이그레이션 016), 구조 변경은 새로고침 없이 제자리 다시 그리기(`refreshTable`)+애니메이션, 로아스는 % 표기. 월 머리 → **주간 회의록**(`/project/goals/{연도}/meetings/{월}`, 프로젝트 권한자 **누구나 수정** — Pro user 이상 [회의 완료](`completed_at`, 마이그레이션 022)면 잠금(지난주 결과는 다음 주 회의록이 열려 있는 동안 허용), 삭제·완료·완료 해제는 Pro user 이상, 표 첫 열 머리 글자 "구분", 주차 탭 — **주차는 그 달 안**(`store.month_weeks`: 1일이 월~금이면 1일~일요일이 1주차, 토·일이면 1일~다음 주 일요일, 그 뒤 월~일, 말일이 월·화면 앞 주차에 붙음, 회의록 `week_start` = 주차 시작일, 마이그레이션 020), `goal_meetings`·`goal_meeting_items` 마이그레이션 015 — 지난주 = **바로 앞 주차**(`store.prev_week_period`) 회의록의 같은 연결키 줄(`line_key`, 마이그레이션 018 — 생성 순서·이름 변경과 무관, 이름 추정 연결 금지)로 리뷰(열: 주요 업무·정량 목표 ‖ 전주 업무·결과(글, `result_note` 020)·전주 목표·결과 — 정량 목표·결과는 숫자면 원 정수 칸, 아니면 글 칸 `target_text`·`result_text`(예: 20개, 021)), 실적 조회 장애는 0원이 아니라 "미확인", 위에 목표 표 그 달 열 글을 영역별 "N월 계획" 카드로, 참석자 옆 [회의록 보드] = 그 주차의 빈 Google 슬라이드를 독립 창으로(오른쪽 🔗 아이콘 = 그 보드 링크 복사)(공유 드라이브 `MEETING_BOARD_FOLDER_ID`, 없으면 만듦, `app/integrations/google_slides.py`, Drive appProperties 로 주차 연결 — Drive·Slides 권한 토큰 필요), 표를 스크롤해도 보이는 머리 영역 3칸 = ① 월 계획 + 머리 줄에 숫자 4개 작게 1행(월 목표 매출·월 누적 목표 매출(목표 표 **주차별 매출 목표** `goal_week_targets` 1주차~이 주차 합 — 목표 표 매출 목표 월 칸을 누르면 입력 창 — 월 전체 목표는 직접 입력(주차 합계와 별개), 맨 아래 차이 = 월 목표 − 주차 합계)·월 누적 실적(1일~오늘)·누적 목표 대비 차액·%) | ② 결정 사항·메모 | ③ "N주차 작업 등록" 표(제목·담당자·프로젝트·섹션 → [적용] = 서버가 그 프로젝트에 작업 생성, `initMeetQuickTasks` — 주차별 서버 표 `goal_meeting_tasks`(마이그레이션 025)라 모두가 같이 보고, 남의 프로젝트 이름은 가림, 완료 프로젝트·섹션은 목록에서 뺌, 작업 칸(마이그레이션 026 `parent_task_id`) = 이미 있는 작업을 고르면 그 작업의 세부 작업으로 등록, 등록된 줄 제목 = 오른쪽 작업 창(편집, 저장 대기), [크게 열기] = 같은 표를 넓은 창으로), 실적 모듈 `performance_store` 매출은 머리 카드에만 읽기 전용 — 줄(쇼핑몰)별 자동 결과·이번주 실적·연결 배지·쇼핑몰 연결 메뉴는 폐지, 지난주 결과는 늘 직접 입력). 모든 열 너비 끌어서 조절(localStorage `pj_goal_col_w`), 세로 스크롤 틀 고정은 머리 줄+매출·로아스 줄까지, 항목 칸 +·우클릭으로 줄 위/아래 추가·삭제, 회의록 "주요 업무" 칸 우클릭 위/아래 줄 추가 = 항목 칸은 그대로 그 항목 안에(마이그레이션 027 `label_cont`, 항목 칸 나누기), 회의록 줄 작업은 새로고침 없이 제자리 다시 그리기(`refreshMeeting`)+애니메이션, 구분(구역) 칸 우클릭·⋯ = 구역 통째로 위/아래(`move-section`). 마감 알림(`reminders.py` 데몬 스레드, 영업일 09시, D-1/당일/지연, `task_reminders` 로 중복 방지, `PROJECT_REMINDER_*` env) — 마이그레이션 008. 라우터 핸들러는 동기 DB 라 `def` 로 둔다(`async def` 금지). 말풍선은 전부 아사나식 공용 말풍선(`.pj-hovertip`) — 새 기능도 `title=`/`data-tip=` 만 달고 별도 툴팁 구현 금지. 멤버 배정 후보는 `project` 권한 보유 등록 사용자에서 자동 목록(`GET /project/api/assignable-users`). 작업 배정·완료 시 관리자에게 메일(`app/mail.py` stdlib smtplib, `SMTP_*`+`PROJECT_NOTIFY_EMAIL` env, 미설정 시 조용히 skip, `BackgroundTasks` 비동기). 목표 표·회의록 칸 저장은 공용 `createFieldSaver`(같은 칸 요청 직렬화·보낸 값만 저장됨·실패 시 초안 유지·localStorage 초안 백업, 저장 실패면 구조 변경 중단 — docs/PROJECT_MODULE.md 6-9-3), 구역·항목 메뉴는 우클릭 + ⋮ 버튼(키보드·터치). ERP 메뉴 이름은 "Project"(`app/main.py` 모듈 목록 title). **PC 알림 프로그램**(`desktop/notifier/`, C# .NET Framework 4.8 WinForms exe 하나·트레이 상주, 마이그레이션 023 `notifier_links`·`notifier_tokens`) — 브라우저가 뒤에 있어도 태그·배정 알림을 웹 팝업과 같은 모양으로 화면 위에. 브라우저 `/project/notifier?code=` 승인으로 PC별 토큰(서버는 SHA-256 만, PC 는 DPAPI), `GET /project/api/notifier/alerts`(Bearer)는 웹 알림과 같은 `_alerts_payload`, 토큰마다 지금 사용자·권한 재확인. 프로그램이 돌고 있으면(최근 3분 확인, `notifier_active`) 웹 큰 팝업은 쉰다(`desktop: true`). 압축·난독화 금지(백신 오탐), 빌드 `desktop/notifier/build.ps1`, 상세 docs/PROJECT_MODULE.md 6-11. 댓글·답글 입력칸은 Enter 등록·Shift+Enter 줄바꿈(textarea), 설명란 이미지 더블클릭 = 별도 창 이미지 보기(확대·축소·끌어 이동). 작업 창은 **저장 버튼 없이 실시간 저장**(칸별 PUT, `saveField`/`saveChain`, 새 작업은 제목이 생기는 순간 생성). 댓글 답글·이모티콘 반응(마이그레이션 012 `task_comments.parent_id`·`task_comment_reactions`, 미적용 시 버튼 숨김·API 503), 완료 이력 줄은 `project_activity` completed 를 댓글 사이에 표시(댓글 수 제외), 댓글 `@아이디` 는 아이콘+이름 칩. 수신함은 확인 안 한 태그·읽지 않은 알림만(2026-10-08) — [확인] 버튼 없이 줄을 누르면 읽음·확인 처리(같은 작업 줄 함께) + 페이지 이동 없이 오른쪽 iframe 패널, 다른 줄을 고르거나 패널을 닫으면 그 줄은 목록에서 빠짐. 용어는 **"업무"**(2026-10-13 "작업"에서 다시 통일 — 화면·메시지·알림 제목, 코드·DB 는 그대로)·"세부 업무"·"메인 업무 추가". 섹션 제목 오른쪽 담당자 아이콘 = 그 자리에서 기본 담당자 지정, 업무 창 세부 업무 줄 담당자 오른쪽 = 협업자 지정, 댓글 이모티콘 반응 = 댓글 쓴 사람에게 알림(`type=reaction`), 왼쪽 전체 보기 = 기본 대시보드, 대시보드 업무 목록 패널에서 연 업무 창은 패널 왼쪽에(docs/PROJECT_MODULE.md 6-16). 세부 업무를 만들 때(업무 창 추가 칸·보드 카드 새 줄) 협업자도 같이(`POST …/tasks` 의 `followers`, 비멤버 400), 보드 카드 세부 업무 줄에도 협업자 아이콘, 대시보드 "업무 합계(프로젝트별)" 카드, **마감 지난 내 업무 위쪽 알림**(`static/erp-overdue.js`, ERP 모든 화면, `GET /project/api/my-overdue`, 닫으면 1시간 뒤 다시 — 새로 지난 업무는 바로)(6-17). **업무를 다른 프로젝트로 이동** — 보드 카드를 왼쪽 프로젝트 목록에 끌어 놓으면 섹션 선택 창 → `POST /project/api/tasks/{id}/move-project`(세부 업무 함께, 원 소속 권한 + 대상 프로젝트 멤버)(6-18). **담당자는 협업자가 아니다**(협업자 = 담당자 외의 멤버, `db.add_followers` 가 거르고 담당자 지정 시 협업자에서 뺌, 기존 겹친 행은 마이그레이션 028), 세부 업무 추가 칸은 동그라미 아이콘 버튼, 내 업무 화면 줄 클릭 = 오른쪽 업무 창(iframe), 대시보드 섹션별 카드 삭제(6-19). 세부 업무는 만든 사람을 자동 협업자로 넣지 않음(고른 사람만), 세부 업무 줄 빈 마감일 아이콘 늘 옅게, 담당자별 패널 날짜 mm/dd(요일)·지난 마감 빨강(6-20). 패널(`/project/p/{pid}?task=&embed=1`, `html.pj-embed`). 상단 톱니 = Project 옵션 창(2026-10-16, 왼쪽 분류 | 오른쪽 설정 — 폰트 = 누구나·이 브라우저(localStorage `pj_font`), 처음 여는 탭·보드 카드 표지 = **수퍼관리자·Admin 만 수정·모든 사용자에게 적용**(서버 `project_options` 마이그레이션 029, `GET/PUT /project/api/options`, `store.normalize_project_options`), 긴급 공지 = 수퍼관리자만, 새 옵션도 이 창에. 모달 대화창 안 말풍선은 popover(top layer)). 상단 바 화면 배율 토글(`html.pj-ui-scale` → `.erp-app` zoom .75, 2880×1620·200%용) — **팝업은 반드시 `document.body` 에 붙인다**(배율 안의 fixed 좌표는 어긋남). 상세는 `docs/PROJECT_MODULE.md` -- 실적 (`app/modules/performance/`, `performance_db`) — 쇼핑몰 통합 매출. 네 영역 분리: ① 수집 `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`. 매출 업데이트 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로). **자동 업데이트**(`auto_sync.py`, 웹 프로세스 데몬 스레드) — 매일 09~19시 정각·30분마다 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀, env `PERFORMANCE_AUTO_SYNC`·`_DAYS`·`_HOURS`. 카페24 어댑터는 기존 `app/integrations/cafe24` 토큰 재사용. 1단계는 모의 데이터(`is_sample`)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(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` — 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐). 탭은 [매출 실적]·[광고비] + 맨 오른쪽 설정 톱니. **광고비**(`/performance/ads`, `ad_spend.py`, 마이그레이션 005 `perf_ad_spend`) — 구글·메타·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 일 광고비를 연·월·일로, 칸 = "광고비(ROAS%)"(ROAS = 그 쇼핑몰 매출 ÷ 광고비, 구글·메타·네이버는 계산 안 함 — 광고 보고서 ROAS, 마이그레이션 006 `roas`·`metrics`), 날짜 칸 직접 입력 + 쿠팡(윙)·쿠팡(로켓)·네이버 광고 보고서 업로드(네이버 = 3열 기간·4열 총비용·12열 ROAS, 머리글 클릭 = 일자별 보고서 항목)(1열 날짜·19열 청구금액(+부가가치세)), 매출 대비 광고비 KPI. **구글 = Google Ads API**(2026-10-15, 마이그레이션 007 `perf_ad_credentials`·`perf_ad_source_status`) — 실적 설정 **광고 API 연동** 카드에서 고객 ID·(MCC)·서비스 계정 JSON·API 버전(기본 v26) 입력(개발자 토큰은 2026-09-09 구글 폐지 — 접근 등급은 서비스 계정의 Cloud 프로젝트, 머리글 안 보냄) → 쇼핑몰과 같은 마스터 키로 암호화(AAD `perf:ad:…`), `ad_sources/`(채널 하나 = 파일 하나)+`ad_sync.py`, 광고비 탭 [구글 광고 불러오기](보는 기간)·매출 자동 업데이트 회차에 함께, 광고비 = 비용 × 1.1(부가세 포함)·ROAS(전환 가치÷비용, 구글 값 그대로)·항목 → `perf_ad_spend` `source='api'`(초록 숫자, API 가 안 준 날은 예전 API 값만 지움). 상세는 `docs/PERFORMANCE_MODULE.md` +- 실적 (`app/modules/performance/`, `performance_db`) — 쇼핑몰 통합 매출. 네 영역 분리: ① 수집 `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`. 매출 업데이트 진행 창에서 쇼핑몰별 [중지](그 쇼핑몰만 멈추고 다음 쇼핑몰로). **자동 업데이트**(`auto_sync.py`, 웹 프로세스 데몬 스레드) — 매일 09~19시 정각·30분마다 오늘 포함 최근 10일, 진행 창 작업으로 돌고 다른 업데이트 중이면 그 회차 건너뜀, env `PERFORMANCE_AUTO_SYNC`·`_DAYS`·`_HOURS`. 카페24 어댑터는 기존 `app/integrations/cafe24` 토큰 재사용. 1단계는 모의 데이터(`is_sample`)·구조까지, 실제 수집은 쇼핑몰별로 공식 문서 확인 후 순차 구현. 쿠팡은 판매자배송 발주서 + 로켓그로스 주문을 결제일로 합산(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` — 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐). 탭은 [매출 실적]·[광고비] + 맨 오른쪽 설정 톱니. **광고비**(`/performance/ads`, `ad_spend.py`, 마이그레이션 005 `perf_ad_spend`) — 구글·메타·네이버·쿠팡(윙)·쿠팡(로켓)·오늘의집·G마켓·카카오·GS샵·11번가·롯데ON·토스·애터미아자몰 일 광고비를 연·월·일로, 칸 = "광고비(ROAS%)"(ROAS = 그 쇼핑몰 매출 ÷ 광고비, 구글·메타·네이버는 계산 안 함 — 광고 보고서 ROAS, 마이그레이션 006 `roas`·`metrics`), 날짜 칸 직접 입력 + 쿠팡(윙)·쿠팡(로켓)·네이버 광고 보고서 업로드(네이버 = 3열 기간·4열 총비용·12열 ROAS, 머리글 클릭 = 일자별 보고서 항목)(1열 날짜·19열 청구금액(+부가가치세)), 매출 대비 광고비 KPI. **구글 = Google Ads API**(2026-10-15, 마이그레이션 007 `perf_ad_credentials`·`perf_ad_source_status`) — 실적 설정 **광고 API 연동** 카드에서 고객 ID·(MCC)·서비스 계정 JSON·API 버전(기본 v26) 입력(개발자 토큰은 2026-09-09 구글 폐지 — 접근 등급은 서비스 계정의 Cloud 프로젝트, 머리글 안 보냄) → 쇼핑몰과 같은 마스터 키로 암호화(AAD `perf:ad:…`), `ad_sources/`(채널 하나 = 파일 하나)+`ad_sync.py`, 광고비 탭 [구글 광고 불러오기](보는 기간)·매출 자동 업데이트 회차에 함께, 광고비 = 비용 × 1.1(부가세 포함)·ROAS(전환 가치÷비용, 구글 값 그대로)·항목 → `perf_ad_spend` `source='api'`(초록 숫자, API 가 안 준 날은 예전 API 값만 지움). **메타 = 메타 마케팅 API**(2026-10-16, `ad_sources/meta_ads.py`, 새 마이그레이션 없음) — 같은 광고 API 연동 카드에서 광고 계정 ID(여러 개, 날짜별 합산)·액세스 토큰(ads_read, 시스템 사용자 토큰 권장)·앱 시크릿(선택)·API 버전(기본 v26.0), 광고비 = 지출 금액 × 1.1(부가세 포함)·ROAS = 구매 전환값 ÷ 지출 금액(광고 관리자 구매 ROAS), [메타 광고 불러오기]·자동 업데이트 회차. 상세는 `docs/PERFORMANCE_MODULE.md` - 긴급 공지 (`app/modules/notice/`, `project_db` 마이그레이션 024 `urgent_notice*`) — 수퍼관리자만 작성(`/notice/`, ERP 왼쪽 아래·Project ⚙ 옵션). 제목·내용(이미지 bytea)·띄울 시각·전체/고른 사람 → ERP 모든 화면(`erp_base.html`·`main.html`·`admin.html` 의 `static/erp-notice.js`) 가로·세로 정가운데에 [확인] 누를 때까지(Esc·바깥 클릭 무시), 확인 기록. 연결 풀은 `ProjectStore.pool` 공유, 새 환경변수 없음. PC 알림 프로그램은 아직 미지원. 상세는 `docs/NOTICE_MODULE.md` diff --git a/app/modules/performance/ad_sources/meta_ads.py b/app/modules/performance/ad_sources/meta_ads.py new file mode 100644 index 0000000..4dc5d9e --- /dev/null +++ b/app/modules/performance/ad_sources/meta_ads.py @@ -0,0 +1,280 @@ +"""메타 광고(Meta Marketing API — Insights) — 날짜별 광고비·ROAS·보고서 항목. + +인증(2026-10-16 사용자: 토큰·광고 계정 ID 준비 완료) + - 액세스 토큰 하나(시스템 사용자 토큰 권장 — 만료 없음. 사용자 토큰은 약 60일 뒤 만료) + 광고 계정 ID 여러 개. + 토큰에 ads_read 권한이 있어야 하고, 토큰 주인(시스템 사용자 등)이 각 광고 계정에 배정돼 있어야 한다. + - 메타 문서대로 토큰은 access_token 매개변수로 보낸다. 앱 설정에서 "앱 시크릿 필요"를 켰다면 앱 시크릿을 넣어 + appsecret_proof(HMAC-SHA256)를 같이 보낸다. 토큰은 오류 문구에 넣지 않고(주소도 넣지 않음), + ad_sync 가 저장된 비밀값을 다시 한 번 가린다. httpx 요청 로그(INFO)는 주소에 토큰이 들어가므로 켜지 않는다. + +조회(GET /{버전}/act_{계정}/insights) + level=account · time_increment=1(하루씩) · time_range={since, until} · fields=spend·노출·클릭·구매 전환 등. + - 날짜는 광고 계정 시간대 기준. 광고가 없던 날은 행이 없다. 여러 계정은 날짜별로 더한다(계정 통화는 모두 KRW 여야 함). + - 기여(어트리뷰션)는 메타가 광고 관리자 설정을 그대로 따른다(2025-06 부터 API 의 기여 매개변수는 무시됨) — 화면 값과 같다. + - 구매 전환값·구매수 = action_values·actions 의 구매 항목 하나(omni_purchase → purchase → 픽셀 구매 순서로 처음 있는 것). + 메타는 같은 구매를 여러 action_type 에 같은 값으로 겹쳐 주므로 더하지 않는다. + - 금액(광고비) = **부가세 포함**(구글과 같은 기준 — 2026-10-15 사용자 요청: 쿠팡 청구금액처럼 부가세 포함) = 지출 금액 × 1.1 원 반올림. + - ROAS(%) = 구매 전환값 ÷ 지출 금액(부가세 별도) × 100 — 광고 관리자 "구매 ROAS" 와 같은 값, 지출 0 이면 없음. + - 나머지 항목(노출수·클릭수·클릭률·링크 클릭·구매수·구매 전환값)은 광고비 탭 메타 머리글 → 일자별 표. +API 버전은 설정 칸(기본 DEFAULT_VERSION) — 메타는 버전을 약 2년 뒤 종료하므로 종료 안내가 오면 설정에서 올린다. +""" + +from __future__ import annotations + +import hashlib +import hmac +import json +import re +from datetime import date +from decimal import ROUND_HALF_UP, Decimal +from typing import Any + +import httpx + +from ..adapters.base import AdapterContext, ApiError, AuthFailed, CredentialField, NotConfigured, TokenExpired +from .base import AdDay, AdSource + +API_BASE = "https://graph.facebook.com" +DEFAULT_VERSION = "v26.0" # 2026-07-29 출시(2026-10 기준 최신) +MAX_DAYS = 366 +MAX_ACCOUNTS = 30 +MAX_PAGES = 50 # 계정 하나 페이지 상한(하루 한 줄이라 366일도 몇 쪽) +VAT = Decimal("1.1") # 광고비 = 메타 지출 금액 + 부가세 10% +PURCHASE_TYPES = ("omni_purchase", "purchase", "offsite_conversion.fb_pixel_purchase") +INSIGHT_FIELDS = "date_start,account_currency,spend,impressions,clicks,inline_link_clicks,actions,action_values" + +# 일자별 표(광고비 탭 메타 머리글) 항목 — 순서 = 열 순서. 클릭률·ROAS 합계는 ad_spend.detail_table 이 이름으로 다시 계산. +M_SPEND, M_COST = "광고비(부가세 포함)", "지출 금액(부가세 별도)" +M_IMPR, M_CLICKS, M_CTR, M_LINK = "노출수", "클릭수", "클릭률(%)", "링크 클릭" +M_PURCHASES, M_VALUE, M_ROAS = "구매수", "구매 전환값", "ROAS(%)" + +# 메타 오류 코드 → 고칠 곳 안내(오류 문구 뒤에 붙임) +_HINTS = { + 190: "토큰이 만료됐거나 무효입니다. 비즈니스 설정 → 시스템 사용자에서 토큰을 다시 만들어 [액세스 토큰]에 넣으세요(시스템 사용자 토큰은 만료 없음).", + 102: "토큰을 읽을 수 없습니다. 토큰을 다시 복사해 넣으세요.", + 200: "토큰에 권한이 없습니다. 토큰을 만들 때 ads_read 권한을 고르고, 토큰 주인(시스템 사용자)을 이 광고 계정에 배정했는지 확인하세요.", + 10: "토큰에 권한이 없습니다(ads_read). 앱·토큰 권한을 확인하세요.", + 100: "요청 값이 올바르지 않습니다 — 광고 계정 ID 가 맞는지, 토큰 주인이 그 계정을 볼 수 있는지 확인하세요.", + 803: "광고 계정 ID 를 찾을 수 없습니다(숫자만, act_ 는 있어도 됨).", + 4: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", + 17: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", + 613: "메타 API 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", + 80000: "광고 계정 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", + 80004: "광고 계정 호출 한도에 걸렸습니다. 잠시 뒤 다시 누르세요.", + 2635: "API 버전이 종료됐습니다 — 실적 설정에서 API 버전을 최신으로 바꾸세요.", +} +_RATE_LIMIT = {4, 17, 613, 80000, 80004} +_AUTH = {10, 102, 200} +_ACCOUNT_STATUS = {1: "운영 중", 2: "사용 중지", 3: "미결제", 7: "검토 대기", 8: "결제 대기", 9: "유예 기간", 100: "종료 대기", 101: "종료"} + + +def _http(ctx: AdapterContext) -> httpx.Client: + """HTTP 클라이언트 — 테스트가 바꿔 끼운다.""" + return httpx.Client(timeout=ctx.timeout_sec) + + +def parse_account_ids(raw: str) -> list[str]: + """'act_123, 456\\n789' → ['123', '456', '789'](순서 유지·중복 제거). 형식이 틀리면 ValueError.""" + out: list[str] = [] + for part in re.split(r"[\s,;]+", raw or ""): + if not part: + continue + v = part[4:] if part.lower().startswith("act_") else part + if not re.fullmatch(r"\d{5,20}", v): + raise ValueError("광고 계정 ID 는 숫자여야 합니다(act_ 는 있어도 됨, 여러 개는 쉼표나 줄바꿈으로 구분).") + if v not in out: + out.append(v) + if len(out) > MAX_ACCOUNTS: + raise ValueError(f"광고 계정은 {MAX_ACCOUNTS}개까지 넣을 수 있습니다.") + return out + + +def _num(v: Any) -> Decimal: + """메타 응답 숫자(문자열로 옴, 0 이면 빠지기도 함) → Decimal.""" + if v is None or v == "": + return Decimal(0) + try: + return Decimal(str(v)) + except ArithmeticError: + return Decimal(0) + + +def _won(v: Decimal) -> int: + return int(v.quantize(Decimal(1), rounding=ROUND_HALF_UP)) + + +def _purchase(items: Any) -> Decimal: + """actions / action_values 목록에서 구매 값 하나(PURCHASE_TYPES 순서로 처음 있는 것 — 겹친 값을 더하지 않는다).""" + by_type = {str((i or {}).get("action_type")): (i or {}).get("value") for i in (items or []) if isinstance(i, dict)} + for t in PURCHASE_TYPES: + if t in by_type: + return _num(by_type[t]) + return Decimal(0) + + +def _meta_error(resp: httpx.Response) -> tuple[int, str]: + """메타 오류 응답 {"error": {"message", "code", "error_subcode", ...}} → (코드, 문구).""" + try: + err = (resp.json() or {}).get("error") or {} + except ValueError: + return 0, f"HTTP {resp.status_code}" + if not isinstance(err, dict): + return 0, f"HTTP {resp.status_code}" + msg = str(err.get("error_user_msg") or err.get("message") or f"HTTP {resp.status_code}") + try: + code = int(err.get("code") or 0) + except (TypeError, ValueError): + code = 0 + return code, msg + + +class MetaAdsSource(AdSource): + code = "meta" + name = "메타 광고" + docs_url = "https://developers.facebook.com/docs/marketing-api/insights" + note = ("메타 마케팅 API(Insights)로 광고 계정별 날짜별 지출 금액·구매 ROAS·노출수·클릭수·구매를 가져와 계정을 합칩니다. " + "준비: ① ads_read 권한이 있는 액세스 토큰(비즈니스 설정 → 시스템 사용자 토큰 권장 — 만료 없음) " + "② 토큰 주인을 각 광고 계정에 배정. 광고비는 지출 금액 + 부가세 10%(구글과 같은 기준)입니다.") + + def credential_fields(self) -> list[CredentialField]: + return [ + CredentialField("account_ids", "광고 계정 ID", multiline=True, placeholder="act_1234567890\nact_9876543210", + help="광고비를 가져올 광고 계정 번호(광고 관리자 주소의 act= 뒤 숫자). 여러 개면 줄바꿈이나 쉼표로 — " + "날짜별로 합쳐서 메타 한 칸에 들어갑니다."), + CredentialField("access_token", "액세스 토큰", secret=True, + help="ads_read 권한이 있는 토큰. 저장 후에는 화면에 다시 보이지 않습니다."), + CredentialField("app_secret", "앱 시크릿", secret=True, required=False, placeholder="앱에서 '앱 시크릿 필요'를 켰을 때만", + help="메타 앱 설정 → 고급에서 'API 호출에 앱 시크릿 필요'를 켰다면 넣습니다(appsecret_proof). 아니면 비워 둡니다."), + CredentialField("api_version", "API 버전", required=False, placeholder=DEFAULT_VERSION, + help=f"비워 두면 {DEFAULT_VERSION}. 메타가 버전 종료를 알리면 새 버전(예: v27.0)으로 바꿉니다."), + ] + + def validate_credentials(self, values: dict[str, str]) -> list[str]: + errors = super().validate_credentials(values) + ids = (values.get("account_ids") or "").strip() + if ids and ids != "__stored__": + try: + parse_account_ids(ids) + except ValueError as exc: + errors.append(str(exc)) + token = (values.get("access_token") or "").strip() + if token and token != "__stored__" and (len(token) < 20 or re.search(r"\s", token)): + errors.append("액세스 토큰 형식이 아닙니다(공백 없이 통째로 붙여 넣으세요).") + ver = (values.get("api_version") or "").strip() + if ver and ver != "__stored__" and not re.fullmatch(r"v\d{2,3}\.0", ver): + errors.append("API 버전은 v26.0 처럼 입력하세요.") + return errors + + # ── 요청 ────────────────────────────────────────────── + def _setup(self, ctx: AdapterContext) -> tuple[list[str], str, dict[str, str]]: + self.require_configured(ctx) + try: + accounts = parse_account_ids(ctx.credentials.get("account_ids")) + except ValueError as exc: + raise NotConfigured(str(exc)) from None + if not accounts: + raise NotConfigured("광고 계정 ID 를 입력하세요.") + token = (ctx.credentials.get("access_token") or "").strip() + auth = {"access_token": token} + secret = (ctx.credentials.get("app_secret") or "").strip() + if secret: + auth["appsecret_proof"] = hmac.new(secret.encode(), token.encode(), hashlib.sha256).hexdigest() + version = (ctx.credentials.get("api_version") or "").strip() or DEFAULT_VERSION + return accounts, version, auth + + def _get(self, ctx: AdapterContext, client: httpx.Client, url: str, params: dict[str, Any] | None) -> dict[str, Any]: + ctx.progress.check() + try: + resp = client.get(url, params=params) + except httpx.HTTPError as exc: + raise ApiError(f"메타 API 에 연결하지 못했습니다({type(exc).__name__}).") from None # 주소(토큰 포함)는 넣지 않는다 + if resp.status_code != 200: + code, msg = _meta_error(resp) + hint = _HINTS.get(code, "") + text = f"메타 API 오류({code or resp.status_code}): {msg[:200]}" + (f" — {hint}" if hint else "") + if code == 190: + raise TokenExpired(text) + auth_problem = code in _AUTH or (resp.status_code in (401, 403) and code not in _RATE_LIMIT) + raise (AuthFailed if auth_problem else ApiError)(text) + try: + body = resp.json() + except ValueError: + raise ApiError("메타 API 응답을 읽을 수 없습니다.") from None + return body if isinstance(body, dict) else {} + + # ── 연결 테스트 · 가져오기 ───────────────────────────── + def test_connection(self, ctx: AdapterContext) -> str: + accounts, version, auth = self._setup(ctx) + parts: list[str] = [] + not_krw = False + with _http(ctx) as client: + for acc in accounts: + info = self._get(ctx, client, f"{API_BASE}/{version}/act_{acc}", + {**auth, "fields": "name,currency,timezone_name,account_status"}) + cur = str(info.get("currency") or "?") + not_krw = not_krw or cur != "KRW" + status = _ACCOUNT_STATUS.get(info.get("account_status"), "") + parts.append(f"{info.get('name') or acc}({cur}·{info.get('timezone_name') or '?'}{'·' + status if status else ''})") + msg = f"연결됨 — 광고 계정 {len(accounts)}개: " + ", ".join(parts) + if not_krw: + msg += " (원화가 아닌 계정이 있어 광고비를 가져올 수 없습니다)" + return msg + + def fetch_days(self, ctx: AdapterContext, start: date, end: date) -> list[AdDay]: + if end < start: + start, end = end, start + if (end - start).days + 1 > MAX_DAYS: + raise ApiError(f"한 번에 {MAX_DAYS}일까지 가져올 수 있습니다.") + accounts, version, auth = self._setup(ctx) + params = {**auth, "level": "account", "time_increment": 1, "limit": 100, "fields": INSIGHT_FIELDS, + "time_range": json.dumps({"since": start.isoformat(), "until": end.isoformat()})} + keys = ("spend", "impr", "clicks", "link", "purchases", "value") + sums: dict[date, dict[str, Decimal]] = {} + with _http(ctx) as client: + for acc in accounts: + url: str | None = f"{API_BASE}/{version}/act_{acc}/insights" + page_params: dict[str, Any] | None = params + for _ in range(MAX_PAGES): + body = self._get(ctx, client, url, page_params) + for r in body.get("data") or []: + cur = str(r.get("account_currency") or "").upper() + if cur and cur != "KRW": + raise ApiError(f"광고 계정 {acc} 의 통화가 {cur} 입니다 — 원화(KRW) 계정만 광고비로 가져옵니다.") + try: + day = date.fromisoformat(str(r.get("date_start"))) + except ValueError: + continue + acc_sum = sums.setdefault(day, {k: Decimal(0) for k in keys}) + acc_sum["spend"] += _num(r.get("spend")) + acc_sum["impr"] += _num(r.get("impressions")) + acc_sum["clicks"] += _num(r.get("clicks")) + acc_sum["link"] += _num(r.get("inline_link_clicks")) + acc_sum["purchases"] += _purchase(r.get("actions")) + acc_sum["value"] += _purchase(r.get("action_values")) + nxt = ((body.get("paging") or {}).get("next") or "").strip() + if not nxt: + break + if not nxt.startswith(API_BASE + "/"): + raise ApiError("메타 API 다음 쪽 주소가 올바르지 않습니다.") + url, page_params = nxt, None # next 주소에 매개변수(토큰 포함)가 다 들어 있다 + else: + raise ApiError("메타 API 응답 쪽수가 너무 많습니다. 기간을 줄여 다시 시도하세요.") + out: list[AdDay] = [] + for day in sorted(sums): + a = sums[day] + amount = _won(a["spend"] * VAT) # 광고비 = 부가세 포함 + roas = (a["value"] / a["spend"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["spend"] > 0 else None + ctr = (a["clicks"] / a["impr"] * 100).quantize(Decimal("0.01"), rounding=ROUND_HALF_UP) if a["impr"] > 0 else None + metrics = { + M_SPEND: amount, + M_COST: _won(a["spend"]), + M_IMPR: int(a["impr"]), + M_CLICKS: int(a["clicks"]), + M_CTR: float(ctr) if ctr is not None else None, + M_LINK: int(a["link"]), + M_PURCHASES: int(a["purchases"]), + M_VALUE: _won(a["value"]), + M_ROAS: float(roas) if roas is not None else None, + } + out.append(AdDay(day=day, amount=amount, roas=roas, metrics=metrics)) + return out diff --git a/app/modules/performance/ad_sources/registry.py b/app/modules/performance/ad_sources/registry.py index 05ef267..d5d9a18 100644 --- a/app/modules/performance/ad_sources/registry.py +++ b/app/modules/performance/ad_sources/registry.py @@ -4,8 +4,9 @@ from __future__ import annotations from .base import AdSource from .google_ads import GoogleAdsSource +from .meta_ads import MetaAdsSource -_SOURCES: tuple[AdSource, ...] = (GoogleAdsSource(),) +_SOURCES: tuple[AdSource, ...] = (GoogleAdsSource(), MetaAdsSource()) _BY_CODE = {s.code: s for s in _SOURCES} diff --git a/app/modules/performance/ad_spend.py b/app/modules/performance/ad_spend.py index 098c47c..10764ca 100644 --- a/app/modules/performance/ad_spend.py +++ b/app/modules/performance/ad_spend.py @@ -341,8 +341,8 @@ def merge_results(parsed: list[tuple[str, float, ParseResult]]) -> tuple[ParseRe return merged, sorted(overlap) -# 머리글을 누르면 일자별 상세 표가 열리는 채널(보고서 항목을 보관하는 채널) — 구글은 광고 API 로 가져온 항목(2026-10-15) -DETAIL_CHANNELS = frozenset({"naver", "google"}) +# 머리글을 누르면 일자별 상세 표가 열리는 채널(보고서 항목을 보관하는 채널) — 구글(2026-10-15)·메타(2026-10-16)는 광고 API 로 가져온 항목 +DETAIL_CHANNELS = frozenset({"naver", "google", "meta"}) def detail_table(rows: list[dict[str, Any]]) -> dict[str, Any]: diff --git a/app/modules/performance/router.py b/app/modules/performance/router.py index ac85216..577bcc2 100644 --- a/app/modules/performance/router.py +++ b/app/modules/performance/router.py @@ -17,8 +17,8 @@ JSON API — 모듈 권한 PUT /performance/api/ad-spend/{channel}/{day} 광고비 한 칸 저장/지움(오늘까지) POST /performance/api/ad-spend/upload?channel= 광고비 파일 업로드(쿠팡 윙·로켓 광고 보고서 1열 날짜·19열 청구금액, 네이버 광고 보고서 3열 기간·4열 총비용·12열 ROAS + 나머지 항목) - GET /performance/api/ad-spend/{channel}/details?from=&to= 일자별 보고서 항목(네이버·구글 머리글 클릭) - POST /performance/api/ad-sources/{code}/sync 광고 API(구글 광고) 가져오기 — 보는 기간(오늘까지), 92일 넘으면 관리자 + GET /performance/api/ad-spend/{channel}/details?from=&to= 일자별 보고서 항목(네이버·구글·메타 머리글 클릭) + POST /performance/api/ad-sources/{code}/sync 광고 API(구글·메타 광고) 가져오기 — 보는 기간(오늘까지), 92일 넘으면 관리자 JSON API — 관리자 GET|PUT /performance/api/ad-sources/{code}/credentials 광고 API 인증정보(마이그레이션 007, 암호화 저장·비밀 원문 없음) POST /performance/api/ad-sources/{code}/test 광고 API 연결 테스트(저장값 또는 새 입력값) diff --git a/app/modules/performance/templates/performance/ads.html b/app/modules/performance/templates/performance/ads.html index d05a257..82f8955 100644 --- a/app/modules/performance/templates/performance/ads.html +++ b/app/modules/performance/templates/performance/ads.html @@ -89,7 +89,7 @@ {% if period_kind == 'year' %}월{% else %}날짜{% endif %} - {% for c in codes %}{% if c in detail_channels %}{% else %}{{ names[c] }} {% endif %}{% endfor %} + {% for c in codes %}{% if c in detail_channels %}{% else %}{{ names[c] }} {% endif %}{% endfor %} {% if period_kind == 'year' %}월 합계{% else %}일 합계{% endif %} @@ -119,10 +119,10 @@ {% if period_kind != 'year' %}

날짜 칸을 눌러 그날 광고비를 직접 입력합니다 — Enter 저장 후 아래 칸, Esc 취소, 비우고 저장하면 지움. - 칸은 광고비(ROAS%) — ROAS = 그 쇼핑몰 매출 실적 총매출 ÷ 광고비(합계 열은 전체 매출). 메타는 ROAS 를 계산하지 않고, - 네이버는 광고 보고서의 ROAS(구매완료 광고수익률), 구글은 구글 광고 API 의 ROAS(전환 가치 ÷ 비용)를 씁니다 — 네이버·구글 머리글을 누르면 일자별 보고서 항목. + 칸은 광고비(ROAS%) — ROAS = 그 쇼핑몰 매출 실적 총매출 ÷ 광고비(합계 열은 전체 매출). 메타는 메타 광고 API 의 구매 ROAS(구매 전환값 ÷ 지출 금액), + 네이버는 광고 보고서의 ROAS(구매완료 광고수익률), 구글은 구글 광고 API 의 ROAS(전환 가치 ÷ 비용)를 씁니다 — 네이버·구글·메타 머리글을 누르면 일자별 보고서 항목. 파란 숫자 = 직접 입력, 주황 숫자 = 파일 업로드 값, 초록 숫자 = 광고 API 값. 쿠팡(윙)·쿠팡(로켓)·네이버는 [파일 업로드]로 광고 보고서를 올리면 날짜별로 한 번에 들어갑니다. - 구글은 [구글 광고 불러오기](관리자가 실적 설정 → 광고 API 연동을 마친 뒤) 또는 매출 자동 업데이트 때 들어옵니다.

+ 구글·메타는 [구글 광고 불러오기]·[메타 광고 불러오기](관리자가 실적 설정 → 광고 API 연동을 마친 뒤) 또는 매출 자동 업데이트 때 들어옵니다.

{% endif %} @@ -200,8 +200,8 @@

- 광고비 기준: 쿠팡(윙)·쿠팡(로켓)은 광고 보고서의 청구금액(+부가가치세), 구글은 구글 광고 비용 + 부가세 10%(부가세 포함). - ROAS = 그 쇼핑몰 매출 ÷ 광고비 × 100(메타는 계산 안 함, 네이버·구글은 광고 쪽 값). + 광고비 기준: 쿠팡(윙)·쿠팡(로켓)은 광고 보고서의 청구금액(+부가가치세), 구글·메타는 광고 API 비용(메타 = 지출 금액) + 부가세 10%(부가세 포함). + ROAS = 그 쇼핑몰 매출 ÷ 광고비 × 100(네이버·구글·메타는 광고 쪽 값). 매출 대비 광고비 = 같은 기간 광고비 ÷ 매출 실적 총매출. 메타는 지금은 직접 입력합니다.

diff --git a/app/modules/performance/templates/performance/settings.html b/app/modules/performance/templates/performance/settings.html index 850b975..bcf8d5a 100644 --- a/app/modules/performance/templates/performance/settings.html +++ b/app/modules/performance/templates/performance/settings.html @@ -103,13 +103,13 @@ {% if is_admin %} - {# 광고 API 연동(2026-10-15, 마이그레이션 007) — 구글 광고 등. 인증정보는 쇼핑몰과 같은 마스터 키로 암호화 저장. + {# 광고 API 연동(2026-10-15, 마이그레이션 007) — 구글 광고·메타 광고(2026-10-16). 인증정보는 쇼핑몰과 같은 마스터 키로 암호화 저장. 가져온 광고비·ROAS 는 광고비 탭(초록 숫자). [설정]·[연결 테스트]는 쇼핑몰 표와 같은 창(/api/ad-sources/…). #}

광고 API 연동

광고비 탭의 광고비·ROAS 를 광고 API 로 가져옵니다. 인증정보는 [설정]에서 입력하면 암호화해 저장합니다. - 설정이 끝나면 광고비 탭 [구글 광고 불러오기]와 매출 자동 업데이트(30분마다 최근 며칠) 때 함께 가져옵니다. + 설정이 끝나면 광고비 탭 [구글 광고 불러오기]·[메타 광고 불러오기]와 매출 자동 업데이트(30분마다 최근 며칠) 때 함께 가져옵니다.
{% if not ad_api_ready %}
광고 API 인증정보 저장 표가 아직 없습니다. performance_db 마이그레이션 007 @@ -142,7 +142,8 @@

- 구글 광고: 광고비 = 구글 광고 화면의 "비용" + 부가세 10%(부가세 포함), ROAS = 전환 가치 ÷ 비용(구글 화면 값 그대로). 날짜는 광고 계정 시간대 기준이며 원화(KRW) 계정만 가져옵니다. + 구글 광고: 광고비 = 구글 광고 화면의 "비용" + 부가세 10%(부가세 포함), ROAS = 전환 가치 ÷ 비용(구글 화면 값 그대로). 날짜는 광고 계정 시간대 기준이며 원화(KRW) 계정만 가져옵니다.
+ 메타 광고: 광고비 = 광고 관리자의 "지출 금액" + 부가세 10%(부가세 포함), ROAS = 구매 전환값 ÷ 지출 금액(광고 관리자 "구매 ROAS"). 광고 계정이 여러 개면 날짜별로 합칩니다. 날짜는 광고 계정 시간대 기준이며 원화(KRW) 계정만 가져옵니다. 가져온 날은 직접 입력·업로드 값보다 우선해 덮어씁니다.

diff --git a/app/modules/performance/tests/test_ad_spend.py b/app/modules/performance/tests/test_ad_spend.py index 4287834..e494327 100644 --- a/app/modules/performance/tests/test_ad_spend.py +++ b/app/modules/performance/tests/test_ad_spend.py @@ -126,7 +126,7 @@ def test_ad_dashboard_month(): assert k["ytd"]["value"] == 370000 and k["mtd"]["value"] == 270000 assert ctx["upload_cells"] == ["2026-10-01|coupang_rocket"] assert [c["code"] for c in ctx["upload_channels"]] == ["naver", "coupang_wing", "coupang_rocket"] - assert ctx["detail_channels"] == ["google", "naver"] # 구글 = 광고 API 로 가져온 항목(2026-10-15) + assert ctx["detail_channels"] == ["google", "meta", "naver"] # 구글(2026-10-15)·메타(2026-10-16) = 광고 API 로 가져온 항목 assert ctx["api_cells"] == [] day1 = next(r for r in ctx["table"] if r.get("date") == "2026-10-01") assert day1["cells"]["coupang_rocket"]["gross"] == 220000 and day1["total"]["gross"] == 220000 diff --git a/app/modules/performance/tests/test_google_ads.py b/app/modules/performance/tests/test_google_ads.py index 81ab358..6c6dd6a 100644 --- a/app/modules/performance/tests/test_google_ads.py +++ b/app/modules/performance/tests/test_google_ads.py @@ -306,7 +306,9 @@ def test_sync_endpoint(monkeypatch): assert r.status_code == 403 # 92일 넘으면 관리자만 admin["v"] = True assert client.post("/performance/api/ad-sources/google/sync", json={"from": "2026-01-01", "to": "2026-10-15"}).status_code == 200 - assert client.post("/performance/api/ad-sources/meta/sync", json={}).status_code == 404 + assert client.post("/performance/api/ad-sources/kakao/sync", json={}).status_code == 404 # 광고 API 연동이 없는 채널 + r = client.post("/performance/api/ad-sources/meta/sync", json={}) # 메타(2026-10-16) — 연동은 있으나 미설정 + assert r.status_code == 400 and "설정되지 않았습니다" in r.json()["detail"] svc.result = {"ok": False, "code": "google", "name": "구글 광고", "status": "auth_failed", "message": "권한 없음"} r = client.post("/performance/api/ad-sources/google/sync", json={}) assert r.status_code == 502 and "권한 없음" in r.json()["detail"] diff --git a/app/modules/performance/tests/test_meta_ads.py b/app/modules/performance/tests/test_meta_ads.py new file mode 100644 index 0000000..434b6af --- /dev/null +++ b/app/modules/performance/tests/test_meta_ads.py @@ -0,0 +1,226 @@ +"""메타 광고 API 연동(2026-10-16) — 입력 검사·요청 매개변수·여러 계정 합산·쪽 넘김·구매 값·부가세·ROAS·오류 안내·저장 서비스. +메타 서버는 가짜(httpx MockTransport).""" + +from __future__ import annotations + +import hashlib +import hmac +import json +from datetime import date +from decimal import Decimal + +import httpx +import pytest + +from app.modules.performance import ad_spend, ad_sync +from app.modules.performance.ad_sources import meta_ads as ma +from app.modules.performance.ad_sources.registry import get_source +from app.modules.performance.adapters.base import AdapterContext, ApiError, AuthFailed, NotConfigured, TokenExpired +from app.modules.performance.credentials import CredentialService + +TOKEN = "EAAGtesttoken0123456789abcdefSECRET" + + +class Creds: + def __init__(self, values): + self.values = values + + def get(self, key): + return self.values.get(key, "") + + def has(self, key): + return bool(self.values.get(key)) + + def set(self, key, value): + self.values[key] = value + + def known_secrets(self): + return [v for k, v in self.values.items() if v and k in ("access_token", "app_secret")] + + +def _ctx(**over): + values = {"account_ids": "act_1111111111\n2222222222", "access_token": TOKEN} + values.update(over) + return AdapterContext(code="meta", credentials=Creds(values)) + + +def _install(monkeypatch, handler): + """가짜 메타 서버 — handler(request) 가 응답을 만든다. 보낸 요청을 돌려준다.""" + seen = [] + + def route(request: httpx.Request) -> httpx.Response: + seen.append(request) + return handler(request) + + monkeypatch.setattr(ma, "_http", lambda ctx: httpx.Client(transport=httpx.MockTransport(route))) + return seen + + +def _row(day, spend, **extra): + r = {"date_start": day, "date_stop": day, "account_currency": "KRW", "spend": spend} + r.update(extra) + return r + + +# 계정 1: 두 쪽(paging.next), 계정 2: 한 쪽. 10-01 은 두 계정 모두 있음 → 날짜별 합산. +PAGE1 = {"data": [_row("2026-10-01", "100000", impressions="20000", clicks="400", inline_link_clicks="300", + actions=[{"action_type": "omni_purchase", "value": "10"}, {"action_type": "purchase", "value": "10"}, + {"action_type": "offsite_conversion.fb_pixel_purchase", "value": "10"}, + {"action_type": "link_click", "value": "300"}], + action_values=[{"action_type": "omni_purchase", "value": "450000"}, + {"action_type": "purchase", "value": "450000"}, + {"action_type": "offsite_conversion.fb_pixel_purchase", "value": "450000"}])], + "paging": {"next": "https://graph.facebook.com/v26.0/act_1111111111/insights?after=CUR&access_token=" + TOKEN}} +PAGE2 = {"data": [_row("2026-10-02", "0", impressions="10")], "paging": {}} +ACC2 = {"data": [_row("2026-10-01", "50000.5", impressions="5000", clicks="100", inline_link_clicks="80", + actions=[{"action_type": "offsite_conversion.fb_pixel_purchase", "value": "2"}], + action_values=[{"action_type": "offsite_conversion.fb_pixel_purchase", "value": "150000"}])]} + + +def _insights_server(request: httpx.Request) -> httpx.Response: + path, q = request.url.path, request.url.params + if path == "/v26.0/act_1111111111/insights": + return httpx.Response(200, json=PAGE2 if q.get("after") == "CUR" else PAGE1) + if path == "/v26.0/act_2222222222/insights": + return httpx.Response(200, json=ACC2) + return httpx.Response(404, json={"error": {"message": "unknown path", "code": 100}}) + + +def test_registered_and_detail_channel(): + assert get_source("meta").name == "메타 광고" + assert "meta" in ad_spend.DETAIL_CHANNELS and "meta" in ad_spend.FILE_ROAS # 머리글 → 일자별 표, ROAS 는 광고 쪽 값 + + +def test_parse_account_ids(): + assert ma.parse_account_ids("act_123456, 654321\n\nACT_123456;777777") == ["123456", "654321", "777777"] + assert ma.parse_account_ids("") == [] + for bad in ("act_abc", "12-34", "act_"): + with pytest.raises(ValueError): + ma.parse_account_ids(bad) + with pytest.raises(ValueError): + ma.parse_account_ids(",".join(str(100000 + i) for i in range(ma.MAX_ACCOUNTS + 1))) + + +def test_validate_credentials(): + src = ma.MetaAdsSource() + ok = {"account_ids": "act_1111111111", "access_token": TOKEN} + assert src.validate_credentials(ok) == [] + assert src.validate_credentials({**ok, "access_token": "__stored__"}) == [] + assert {f.key for f in src.visible_fields()} == {"account_ids", "access_token", "app_secret", "api_version"} + assert {f.key for f in src.visible_fields() if f.secret} == {"access_token", "app_secret"} + errs = src.validate_credentials({"account_ids": "act_x", "access_token": "short token", "api_version": "26"}) + assert len(errs) == 3 and not any("short token" in e for e in errs) # 토큰 값은 문구에 없음 + assert "입력하세요" in " ".join(src.validate_credentials({})) + + +def test_fetch_days_sums_accounts_pages_and_converts(monkeypatch): + seen = _install(monkeypatch, _insights_server) + days = ma.MetaAdsSource().fetch_days(_ctx(), date(2026, 10, 1), date(2026, 10, 2)) + first = seen[0] + assert first.url.path == "/v26.0/act_1111111111/insights" + q = first.url.params + assert q["access_token"] == TOKEN and "appsecret_proof" not in q + assert (q["level"], q["time_increment"]) == ("account", "1") + assert json.loads(q["time_range"]) == {"since": "2026-10-01", "until": "2026-10-02"} + assert {"spend", "action_values", "actions", "account_currency", "date_start"} <= set(q["fields"].split(",")) + assert [r.url.params.get("after") for r in seen] == [None, "CUR", None] # 계정 1 두 쪽 → 계정 2 + d1, d2 = days + # 10-01: 지출 100,000 + 50,000.5 = 150,000.5 → 광고비(부가세 포함) 165,000.55 → 165,001 + # 구매 전환값 = 계정1 omni_purchase 450,000(겹친 purchase·픽셀 값은 더하지 않음) + 계정2 픽셀 150,000 = 600,000 + # ROAS = 600,000 ÷ 150,000.5 × 100 = 399.998... → 400.00 + assert (d1.day, d1.amount, d1.roas) == (date(2026, 10, 1), 165001, Decimal("400.00")) + assert d1.metrics == {"광고비(부가세 포함)": 165001, "지출 금액(부가세 별도)": 150001, "노출수": 25000, "클릭수": 500, + "클릭률(%)": 2.0, "링크 클릭": 380, "구매수": 12, "구매 전환값": 600000, "ROAS(%)": 400.0} + assert list(d1.metrics)[:2] == ["광고비(부가세 포함)", "지출 금액(부가세 별도)"] # 일자별 표 열 순서 + assert (d2.day, d2.amount, d2.roas, d2.metrics["클릭률(%)"]) == (date(2026, 10, 2), 0, None, 0.0) # 지출 0 → ROAS 없음 + + +def test_app_secret_proof_and_version(monkeypatch): + seen = _install(monkeypatch, lambda req: httpx.Response(200, json={"data": []})) + out = ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333", app_secret="appsecret", api_version="v27.0"), + date(2026, 10, 1), date(2026, 10, 1)) + assert out == [] + assert seen[0].url.path == "/v27.0/act_333333/insights" + expected = hmac.new(b"appsecret", TOKEN.encode(), hashlib.sha256).hexdigest() + assert seen[0].url.params["appsecret_proof"] == expected + + +def test_non_krw_and_limits(monkeypatch): + _install(monkeypatch, lambda req: httpx.Response(200, json={"data": [{**_row("2026-10-01", "10"), "account_currency": "USD"}]})) + with pytest.raises(ApiError, match="USD"): + ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333"), date(2026, 10, 1), date(2026, 10, 1)) + with pytest.raises(ApiError, match="366"): + ma.MetaAdsSource().fetch_days(_ctx(), date(2025, 1, 1), date(2026, 10, 1)) + with pytest.raises(NotConfigured): + ma.MetaAdsSource().fetch_days(_ctx(access_token=""), date(2026, 10, 1), date(2026, 10, 1)) + # 다음 쪽 주소가 메타가 아니면 따라가지 않는다(토큰을 다른 곳에 보내지 않게) + _install(monkeypatch, lambda req: httpx.Response(200, json={"data": [], "paging": {"next": "https://evil.example/x"}})) + with pytest.raises(ApiError, match="다음 쪽"): + ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333"), date(2026, 10, 1), date(2026, 10, 1)) + + +@pytest.mark.parametrize("code,status,exc,hint", [ + (190, 400, TokenExpired, "시스템 사용자"), + (200, 403, AuthFailed, "ads_read"), + (100, 400, ApiError, "광고 계정 ID"), + (17, 400, ApiError, "호출 한도"), + (80004, 403, ApiError, "호출 한도"), # 403 이어도 호출 한도는 인증 실패가 아님 +]) +def test_errors_are_explained(monkeypatch, code, status, exc, hint): + _install(monkeypatch, lambda req: httpx.Response(status, json={"error": {"message": "meta says no", "code": code}})) + with pytest.raises(exc) as info: + ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333"), date(2026, 10, 1), date(2026, 10, 1)) + assert hint in str(info.value) and f"({code})" in str(info.value) and TOKEN not in str(info.value) + + +def test_network_error_has_no_token(monkeypatch): + def boom(req): + raise httpx.ConnectError("connect failed for " + str(req.url)) + + _install(monkeypatch, boom) + with pytest.raises(ApiError) as info: + ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333"), date(2026, 10, 1), date(2026, 10, 1)) + assert "ConnectError" in str(info.value) and TOKEN not in str(info.value) + + +def test_connection_message(monkeypatch): + accounts = {"/v26.0/act_1111111111": {"name": "본계정", "currency": "KRW", "timezone_name": "Asia/Seoul", "account_status": 1}, + "/v26.0/act_2222222222": {"name": "해외", "currency": "USD", "timezone_name": "America/Los_Angeles", "account_status": 2}} + seen = _install(monkeypatch, lambda req: httpx.Response(200, json=accounts[req.url.path])) + msg = ma.MetaAdsSource().test_connection(_ctx()) + assert "광고 계정 2개" in msg and "본계정(KRW·Asia/Seoul·운영 중)" in msg and "해외(USD" in msg and "사용 중지" in msg + assert "원화가 아닌 계정" in msg + assert seen[0].url.params["fields"] == "name,currency,timezone_name,account_status" + + +class FakeStore: + def __init__(self): + self.replaced, self.status = [], [] + + def replace_ad_api_range(self, code, start, end, days, *, user=""): + self.replaced.append((code, start, end, days, user)) + return len(days) + + def record_ad_status(self, code, *, status, ok, error="", kind="test"): + self.status.append((code, status, ok, error, kind)) + + +def test_sync_service_end_to_end(monkeypatch): + """실제 MetaAdsSource.fetch_days → AdSyncService 저장·상태. 실패 문구에서 토큰은 가린다.""" + _install(monkeypatch, _insights_server) + store = FakeStore() + svc = ad_sync.AdSyncService(store, CredentialService(None, lambda: None)) + svc._ctx = lambda code, values=None, user="", cleared=None: _ctx() + res = svc.sync("meta", date(2026, 10, 1), date(2026, 10, 2), user="king@x") + assert res["ok"] and res["days"] == 2 and res["total"] == 165001 and res["name"] == "메타 광고" + code, start, end, days, user = store.replaced[0] + assert (code, start, end, user) == ("meta", date(2026, 10, 1), date(2026, 10, 2), "king@x") + assert [(d, amt, roas) for d, amt, roas, _m in days] == [(date(2026, 10, 1), 165001, Decimal("400.00")), + (date(2026, 10, 2), 0, None)] + assert store.status[-1] == ("meta", "ok", True, "", "sync") + + # 메타가 오류 문구에 토큰을 되돌려 줘도 저장·화면 문구에서는 가린다 + _install(monkeypatch, lambda req: httpx.Response(400, json={"error": {"message": "bad token " + TOKEN, "code": 190}})) + res = svc.sync("meta", date(2026, 10, 1), date(2026, 10, 1)) + assert not res["ok"] and res["status"] == "token_expired" and TOKEN not in res["message"] + assert len(store.replaced) == 1 and store.status[-1][1:3] == ("token_expired", False) and TOKEN not in store.status[-1][3] diff --git a/docs/PERFORMANCE_MODULE.md b/docs/PERFORMANCE_MODULE.md index a8bf7e2..99c3f0d 100644 --- a/docs/PERFORMANCE_MODULE.md +++ b/docs/PERFORMANCE_MODULE.md @@ -378,7 +378,7 @@ 머리글 이름 그대로 `metrics`(JSONB). 광고 계정 이름·ID 는 넣지 않음. 직접 입력으로 광고비를 고쳐도 ROAS·상세는 그대로. - **네이버 머리글 클릭** → 지금 보는 기간의 일자별 보고서 표(`GET /api/ad-spend/naver/details?from=&to=`, `ad_spend.detail_table`): 열 = 파일 머리글 순서, 맨 아래 합계(숫자 항목은 합, 클릭률 = 클릭수 ÷ 노출수, 광고수익률 = 총비용 가중 평균). `DETAIL_CHANNELS`. - - **구글 = 구글 광고 API**(2026-10-15, 마이그레이션 007) — 아래 "광고 API 연동". 메타는 아직 직접 입력. + - **구글 = 구글 광고 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, 표만 따로 @@ -397,6 +397,19 @@ 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`) × 1.1 원 반올림 — **부가세 포함**(구글과 같은 기준), ROAS = 구매 전환값 ÷ 지출 금액(부가세 별도) × 100 + (= 광고 관리자 "구매 ROAS"). 구매 전환값·구매수 = `action_values`·`actions` 에서 `omni_purchase` → `purchase` → 픽셀 구매 순서로 처음 있는 것 하나 + (메타가 같은 구매를 여러 종류에 같은 값으로 겹쳐 주므로 더하지 않음). 항목 `metrics` = 광고비(부가세 포함)·지출 금액(부가세 별도)·노출수·클릭수· + 클릭률(%)·링크 클릭·구매수·구매 전환값·ROAS(%) → 메타 머리글 클릭 = 일자별 표(`DETAIL_CHANNELS`). + 원화(KRW)가 아닌 계정이 있으면 저장 안 함. 오류 코드 안내(`_HINTS`): 190 = 토큰 만료·무효(상태 "Token 만료"), 200·10 = 권한(ads_read·계정 배정), + 100·803 = 계정 ID, 4·17·613·80000·80004 = 호출 한도, 2635 = 버전 종료. 연결 테스트 = 계정마다 이름·통화·시간대·상태. - **저장**(`db.replace_ad_api_range`, 한 트랜잭션): API 가 준 날은 `source='api'` 로 덮어씀(직접 입력·업로드 값이 있던 날도), 기간 안에서 API 가 안 준 날(광고 없음)은 **예전 API 값만** 지움 — 직접 입력·업로드 값은 그대로. 화면 초록 숫자 = API 값. - **언제**: 광고비 탭 **[구글 광고 불러오기]**(설정된 연동만 보임, 지금 보는 기간 → 오늘까지, 모듈 권한자 92일·관리자 366일, @@ -408,7 +421,7 @@ [총매출|수수료|수수료 차감 매출] 전환(서버가 세 값을 다 그리고 CSS 로 전환, 선택은 localStorage), 일별 추이·쇼핑몰 비중(SVG), 월 누적(비중), 연간 누적(월별, 지나지 않은 달 빈칸). 금액 클릭 → 주문 상세(`GET /api/events`, 31일 이내). - **설정** `/performance/settings` — 사용/매출 집계 토글, 수수료율(적용 시작일·이력), API 설정 창, 연결 상태 - (정상/미설정/인증 실패/Token 만료/API 오류/연동 준비 중/사용 중지, 마지막 테스트·동기화, 최근 오류), **광고 API 연동**(구글 광고 — + (정상/미설정/인증 실패/Token 만료/API 오류/연동 준비 중/사용 중지, 마지막 테스트·동기화, 최근 오류), **광고 API 연동**(구글 광고·메타 광고 — 설정·연결 테스트·연결 상태·마지막 가져오기, 관리자), 마스터 키 상태·재암호화, 테스트 데이터 생성/삭제(`is_sample`). ## 8. 테스트 @@ -421,3 +434,6 @@ python -m app.modules.performance.tests.test_performance # 또는 pytest 동기화 격리·가리기·중복 방지·매출 기준일, 모의 데이터를 DB/네트워크 없이 검증한다. `tests/test_google_ads.py` — 구글 광고 입력 검사, 토큰 교환·머리글·GAQL 기간·버전, 금액 반올림·ROAS·항목 변환, 오류 안내(권한·버전·통화·키), 광고 인증정보 AAD 이름 공간, 가져오기 저장·상태·비밀값 가림·동시 실행 차단, 불러오기 API(오늘까지 자름·92일 권한·미설정)를 가짜 구글 서버로 검증. +`tests/test_meta_ads.py` — 메타 광고 입력 검사(계정 ID 여러 개·토큰·버전), 요청 매개변수(기간·level·appsecret_proof·버전), 여러 계정 날짜별 합산· +쪽 넘김(메타 밖 주소 거부), 구매 값 겹침 처리·부가세·ROAS·항목, 원화 아님·366일, 오류 코드 안내·토큰 미노출, 연결 테스트 문구, +실제 fetch_days → AdSyncService 저장·상태·토큰 가림을 가짜 메타 서버로 검증. diff --git a/tests/js/perf_manual.test.js b/tests/js/perf_manual.test.js index 07d1586..26cba73 100644 --- a/tests/js/perf_manual.test.js +++ b/tests/js/perf_manual.test.js @@ -225,7 +225,7 @@ function gross(td) { return td.querySelector(".v-gross").textContent.trim(); } const hb = e.d.querySelector('.perf-main thead [data-detail-channel="naver"]'); const detailChans = Array.from(e.d.querySelectorAll(".perf-main thead [data-detail-channel]")).map(function (b) { return b.dataset.detailChannel; }); // 구글도 광고 API 로 가져온 보고서 항목이 있어 상세 보기(2026-10-15) — 그 밖의 채널은 아님 - check("[네이버] 머리글 = 상세 보기 버튼(네이버·구글만)", !!hb && detailChans.sort().join(",") === "google,naver", detailChans); + check("[네이버] 머리글 = 상세 보기 버튼(네이버·구글·메타만)", !!hb && detailChans.sort().join(",") === "google,meta,naver", detailChans); hb.click(); await settle(); const call = e.calls.find(function (c) { return /\/details/.test(c.url); }); check("[네이버] 지금 기간으로 상세 요청", call && call.url === "/performance/api/ad-spend/naver/details?from=2026-10-01&to=2026-10-31", e.calls);