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 %}
@@ -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);