From 0836d6a9268c4e238cd1a211fa3e2e412d383ebd Mon Sep 17 00:00:00 2001 From: king Date: Fri, 16 Oct 2026 13:59:49 +0900 Subject: [PATCH] =?UTF-8?q?feat(performance):=20=EB=A9=94=ED=83=80=20?= =?UTF-8?q?=EC=99=B8=ED=99=94(USD)=20=EA=B4=91=EA=B3=A0=20=EA=B3=84?= =?UTF-8?q?=EC=A0=95=20=E2=80=94=20=EA=B7=B8=EB=82=A0=20=ED=99=98=EC=9C=A8?= =?UTF-8?q?=EB=A1=9C=20=EC=9B=90=ED=99=94=20=ED=99=98=EC=82=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 예전엔 원화가 아닌 계정이면 "원화 계정만" 오류로 저장 안 함 → 이제 지출 금액·구매 전환값을 그날 환율로 원화 환산해 다른 계정과 합산(광고비 = 지출 × 환율 × 1.1, ROAS 는 비율이라 그대로). - fx.py: Frankfurter v2(키 없음, 중앙은행 고시 환율 종합, 매일)에서 기간 환율 한 번에, 빈 날은 앞 가장 가까운 날, 못 구하면 그 회차 저장 안 함, 지난 날 환율은 프로세스 캐시. - 계정 탭에 지출 금액(USD)·적용 환율(원)(합계 = 광고비 가중 평균), 연결 테스트·설정 안내 문구 갱신. - 테스트: 혼합 계정 환산·빈 날 환율·환율 장애·캐시·환율 합계, 실제 Frankfurter 응답으로 파싱 확인. Co-Authored-By: Claude Opus 5.5 --- CLAUDE.md | 2 +- .../performance/ad_sources/meta_ads.py | 46 +++++--- app/modules/performance/ad_spend.py | 5 + app/modules/performance/fx.py | 90 +++++++++++++++ .../templates/performance/settings.html | 2 +- .../performance/tests/test_meta_ads.py | 105 +++++++++++++++++- docs/PERFORMANCE_MODULE.md | 7 +- 7 files changed, 236 insertions(+), 21 deletions(-) create mode 100644 app/modules/performance/fx.py diff --git a/CLAUDE.md b/CLAUDE.md index eaf9ea8..043c0ea 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 값만 지움). **메타 = 메타 마케팅 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/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), USD 등 외화 계정은 그날 환율로 원화 환산(`fx.py`, Frankfurter 중앙은행 고시 환율 종합, 키 없음), 상세보기 [합계 | 계정별] 탭, [메타 광고 불러오기]·자동 업데이트 회차. 상세는 `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 index c52b30b..086207a 100644 --- a/app/modules/performance/ad_sources/meta_ads.py +++ b/app/modules/performance/ad_sources/meta_ads.py @@ -9,7 +9,9 @@ 조회(GET /{버전}/act_{계정}/insights) level=account · time_increment=1(하루씩) · time_range={since, until} · fields=spend·노출·클릭·구매 전환 등. - - 날짜는 광고 계정 시간대 기준. 광고가 없던 날은 행이 없다. 여러 계정은 날짜별로 더한다(계정 통화는 모두 KRW 여야 함). + - 날짜는 광고 계정 시간대 기준. 광고가 없던 날은 행이 없다. 여러 계정은 날짜별로 더한다. + - 원화가 아닌 계정(USD 등, 2026-10-16)은 지출 금액·구매 전환값을 그날 환율로 원화 환산(fx.krw_rates — Frankfurter 중앙은행 고시 환율 종합, + 그날 값이 없으면 앞 가장 가까운 날). 계정 탭에 원래 통화 지출·적용 환율. ROAS 는 비율이라 환율과 무관. - 기여(어트리뷰션)는 메타가 광고 관리자 설정을 그대로 따른다(2025-06 부터 API 의 기여 매개변수는 무시됨) — 화면 값과 같다. - 구매 전환값·구매수 = action_values·actions 의 구매 항목 하나(omni_purchase → purchase → 픽셀 구매 순서로 처음 있는 것). 메타는 같은 구매를 여러 action_type 에 같은 값으로 겹쳐 주므로 더하지 않는다. @@ -32,6 +34,7 @@ from typing import Any import httpx from ..adapters.base import AdapterContext, AdapterError, ApiError, AuthFailed, CredentialField, NotConfigured, TokenExpired +from .. import fx from .base import ACCOUNTS_KEY, AdDay, AdSource API_BASE = "https://graph.facebook.com" @@ -47,6 +50,7 @@ INSIGHT_FIELDS = "date_start,account_id,account_name,account_currency,spend,impr M_SPEND, M_COST = "광고비(부가세 포함)", "지출 금액(부가세 별도)" M_IMPR, M_CLICKS, M_CTR, M_LINK = "노출수", "클릭수", "클릭률(%)", "링크 클릭" M_PURCHASES, M_VALUE, M_ROAS = "구매수", "구매 전환값", "ROAS(%)" +M_FX = "적용 환율(원)" # 외화 계정 탭에만 — 그날 1 계정 통화 = ? 원(fx.krw_rates) # 메타 오류 코드 → 고칠 곳 안내(오류 문구 뒤에 붙임). 권한 오류는 연결 테스트가 원인을 진단한다(_diagnose) — # 불러오기에서 난 오류엔 그 안내를 붙이고, 연결 테스트 자체에서는 진단 결과로 바꿔 쓴다. @@ -284,7 +288,7 @@ class MetaAdsSource(AdSource): 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 += " (원화가 아닌 계정이 있어 광고비를 가져올 수 없습니다)" + msg += f" (원화가 아닌 계정은 날마다 그날 환율로 원화로 바꿔 넣습니다 — {fx.SOURCE_LABEL})" return msg def fetch_days(self, ctx: AdapterContext, start: date, end: date) -> list[AdDay]: @@ -295,8 +299,7 @@ class MetaAdsSource(AdSource): 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()})} - sums: dict[date, dict[str, Decimal]] = {} # 날짜 → 모든 계정 합 - per_acc: dict[date, dict[str, dict[str, Decimal]]] = {} # 날짜 → 계정 → 그 계정 값(상세보기 계정별 탭) + raw: list[tuple[str, date, str, dict[str, Any]]] = [] # (계정, 날짜, 통화, insights 한 줄) names: dict[str, str] = {} with _http(ctx) as client: for acc in accounts: @@ -305,18 +308,13 @@ class MetaAdsSource(AdSource): 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 if r.get("account_name"): names[acc] = str(r["account_name"])[:100] - one = per_acc.setdefault(day, {}).setdefault(acc, _zero()) - _add(one, r) - _add(sums.setdefault(day, _zero()), r) + raw.append((acc, day, str(r.get("account_currency") or "KRW").upper(), r)) nxt = ((body.get("paging") or {}).get("next") or "").strip() if not nxt: break @@ -325,6 +323,23 @@ class MetaAdsSource(AdSource): url, page_params = nxt, None # next 주소에 매개변수(토큰 포함)가 다 들어 있다 else: raise ApiError("메타 API 응답 쪽수가 너무 많습니다. 기간을 줄여 다시 시도하세요.") + # 원화가 아닌 계정(USD 등) — 그날 환율로 원화 환산(2026-10-16). 통화마다 기간 환율을 한 번에. + rates: dict[str, dict[date, Decimal]] = {} + for cur in sorted({c for _a, _d, c, _r in raw if c != "KRW"}): + if not re.fullmatch(r"[A-Z]{3}", cur): + raise ApiError(f"광고 계정 통화({cur[:10]})를 알 수 없습니다.") + try: + rates[cur] = fx.krw_rates(client, cur, start, end) + except fx.FxError as exc: + raise ApiError(f"{cur} 광고 계정을 원화로 바꿀 환율을 가져오지 못했습니다 — {exc}") from None + sums: dict[date, dict[str, Decimal]] = {} # 날짜 → 모든 계정 합(원화) + per_acc: dict[date, dict[str, dict[str, Any]]] = {} # 날짜 → 계정 → 그 계정 값(상세보기 계정별 탭) + for acc, day, cur, r in raw: + rate = Decimal(1) if cur == "KRW" else rates[cur][day] + one = per_acc.setdefault(day, {}).setdefault(acc, {**_zero(), "cur": cur, "rate": rate, "orig": Decimal(0)}) + _add(one, r, rate) + one["orig"] += _num(r.get("spend")) # 그 계정 통화 그대로의 지출 금액 + _add(sums.setdefault(day, _zero()), r, rate) out: list[AdDay] = [] for day in sorted(sums): amount, roas, metrics = _convert(sums[day]) @@ -333,6 +348,9 @@ class MetaAdsSource(AdSource): accounts_out: dict[str, Any] = {} for acc, a in per_acc.get(day, {}).items(): a_amount, a_roas, a_metrics = _convert(a) + if a["cur"] != "KRW": # 외화 계정 — 원래 통화 지출과 적용 환율도 보여 준다(계정 탭) + a_metrics[f"지출 금액({a['cur']})"] = float(a["orig"].quantize(Decimal("0.01"), rounding=ROUND_HALF_UP)) + a_metrics[M_FX] = float(a["rate"]) accounts_out[acc] = {"name": names.get(acc) or f"act_{acc}", "amount": a_amount, "roas": float(a_roas) if a_roas is not None else None, "metrics": a_metrics} metrics[ACCOUNTS_KEY] = accounts_out @@ -344,14 +362,14 @@ def _zero() -> dict[str, Decimal]: return {k: Decimal(0) for k in ("spend", "impr", "clicks", "link", "purchases", "value")} -def _add(acc: dict[str, Decimal], r: dict[str, Any]) -> None: - """insights 한 줄(계정 하나·하루)을 더한다.""" - acc["spend"] += _num(r.get("spend")) +def _add(acc: dict[str, Any], r: dict[str, Any], rate: Decimal = Decimal(1)) -> None: + """insights 한 줄(계정 하나·하루)을 더한다 — 금액(지출·구매 전환값)은 × rate(그날 1 계정 통화 = ? 원)로 원화.""" + acc["spend"] += _num(r.get("spend")) * rate acc["impr"] += _num(r.get("impressions")) acc["clicks"] += _num(r.get("clicks")) acc["link"] += _num(r.get("inline_link_clicks")) acc["purchases"] += _purchase(r.get("actions")) - acc["value"] += _purchase(r.get("action_values")) + acc["value"] += _purchase(r.get("action_values")) * rate def _convert(a: dict[str, Decimal]) -> tuple[int, Decimal | None, dict[str, Any]]: diff --git a/app/modules/performance/ad_spend.py b/app/modules/performance/ad_spend.py index e9b7de9..a160aac 100644 --- a/app/modules/performance/ad_spend.py +++ b/app/modules/performance/ad_spend.py @@ -370,6 +370,11 @@ def detail_table(rows: list[dict[str, Any]]) -> dict[str, Any]: rev = sum(Decimal(str(r["roas"])) * int(r.get("amount") or 0) for r in rows if r.get("roas") is not None and int(r.get("amount") or 0) > 0) total[k] = float(round(rev / spend, 2)) if spend else None + elif "환율" in k: # 외화 광고 계정 적용 환율(메타 USD 계정, 2026-10-16) — 더하지 않고 광고비 가중 평균 + pairs = [(Decimal(str((r.get("metrics") or {})[k])), int(r.get("amount") or 0)) for r in rows + if isinstance((r.get("metrics") or {}).get(k), (int, float)) and int(r.get("amount") or 0) > 0] + weight = sum(w for _v, w in pairs) + total[k] = float(round(sum(v * w for v, w in pairs) / weight, 2)) if weight else None out_rows = [{"date": r["date"], "amount": int(r.get("amount") or 0), "roas": float(r["roas"]) if r.get("roas") is not None else None, "values": {k: v for k, v in (r.get("metrics") or {}).items() if not k.startswith("_")}} for r in rows] diff --git a/app/modules/performance/fx.py b/app/modules/performance/fx.py new file mode 100644 index 0000000..1313520 --- /dev/null +++ b/app/modules/performance/fx.py @@ -0,0 +1,90 @@ +"""외화 → 원화 날짜별 환율(2026-10-16 사용자 요청: 메타 USD 광고 계정 — "그날 환율로 원화 환산"). + +출처: Frankfurter(https://frankfurter.dev, API 키 없음) v2 `GET /v2/rates?base=USD"es=KRW&from=&to=` + — 여러 나라 중앙은행 고시 환율을 합친 값(blended)이고 주말·공휴일 포함 매일 있다. 서울외국환중개 매매기준율과는 + 조금(보통 0.5% 안쪽) 다를 수 있다. 응답: [{"date": "2026-10-01", "base": "USD", "quote": "KRW", "rate": 1357.92}, …] +그날 값이 없으면(오늘처럼 아직 안 나온 날 등) 그 앞 가장 가까운 날 값을 쓴다(LOOKBACK_DAYS 안). +지난 날(2일 이상 지난) 환율은 프로세스 안에 기억해 30분마다 도는 자동 업데이트가 같은 날을 다시 묻지 않게 한다. +""" + +from __future__ import annotations + +import threading +from datetime import date, timedelta +from decimal import Decimal, InvalidOperation + +import httpx + +from app.timezone import today_kst + +FX_API = "https://api.frankfurter.dev/v2/rates" +SOURCE_LABEL = "Frankfurter(중앙은행 고시 환율 종합)" +LOOKBACK_DAYS = 10 # 그날 환율이 없으면 이만큼 앞까지 찾는다 +_SETTLED_AFTER = 2 # 오늘에서 이만큼 지난 날 환율만 기억(최근 값은 나중에 고시될 수 있음) + +_cache_lock = threading.Lock() +_cache: dict[tuple[str, date], Decimal] = {} + + +class FxError(Exception): + """환율을 가져오지 못함 — 문구는 화면에 그대로 보인다.""" + + +def krw_rates(client: httpx.Client, currency: str, start: date, end: date, *, today: date | None = None) -> dict[date, Decimal]: + """start~end(양 끝 포함) 날마다 1 {currency} = ? 원. 하루라도 못 정하면 FxError(일부만 환산해 저장하지 않게).""" + cur = (currency or "").upper() + if cur == "KRW": + return {start + timedelta(days=i): Decimal(1) for i in range((end - start).days + 1)} + days = [start + timedelta(days=i) for i in range((end - start).days + 1)] + with _cache_lock: + known = {d: _cache[(cur, d)] for d in days if (cur, d) in _cache} + if len(known) == len(days): + return known + fetched = _fetch(client, cur, start - timedelta(days=LOOKBACK_DAYS), end) + today = today or today_kst() + out: dict[date, Decimal] = {} + for d in days: + rate = next((fetched[d - timedelta(days=k)] for k in range(LOOKBACK_DAYS + 1) if d - timedelta(days=k) in fetched), None) + if rate is None: + raise FxError(f"{d.isoformat()} 의 {cur}→KRW 환율을 찾지 못했습니다({SOURCE_LABEL}).") + out[d] = rate + with _cache_lock: + for d, rate in out.items(): + if d in fetched and (today - d).days >= _SETTLED_AFTER: + _cache[(cur, d)] = rate + return out + + +def _fetch(client: httpx.Client, cur: str, start: date, end: date) -> dict[date, Decimal]: + try: + resp = client.get(FX_API, params={"base": cur, "quotes": "KRW", "from": start.isoformat(), "to": end.isoformat()}) + except httpx.HTTPError as exc: + raise FxError(f"환율 서버({SOURCE_LABEL})에 연결하지 못했습니다({type(exc).__name__}).") from None + if resp.status_code != 200: + try: + msg = str((resp.json() or {}).get("message") or "") + except ValueError: + msg = "" + raise FxError(f"환율을 가져오지 못했습니다(HTTP {resp.status_code}{': ' + msg[:120] if msg else ''}).") + try: + rows = resp.json() + except ValueError: + raise FxError("환율 서버 응답을 읽을 수 없습니다.") from None + out: dict[date, Decimal] = {} + for r in rows if isinstance(rows, list) else []: + if not isinstance(r, dict) or str(r.get("quote") or "").upper() != "KRW": + continue + try: + d = date.fromisoformat(str(r.get("date"))) + rate = Decimal(str(r.get("rate"))) + except (ValueError, InvalidOperation): + continue + if rate > 0: + out[d] = rate + return out + + +def clear_cache() -> None: + """테스트용.""" + with _cache_lock: + _cache.clear() diff --git a/app/modules/performance/templates/performance/settings.html b/app/modules/performance/templates/performance/settings.html index b1b1e5b..592610f 100644 --- a/app/modules/performance/templates/performance/settings.html +++ b/app/modules/performance/templates/performance/settings.html @@ -143,7 +143,7 @@

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

diff --git a/app/modules/performance/tests/test_meta_ads.py b/app/modules/performance/tests/test_meta_ads.py index bf29fc2..c1150fc 100644 --- a/app/modules/performance/tests/test_meta_ads.py +++ b/app/modules/performance/tests/test_meta_ads.py @@ -153,10 +153,8 @@ def test_app_secret_proof_and_version(monkeypatch): 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)) +def test_limits(monkeypatch): + _install(monkeypatch, lambda req: httpx.Response(200, json={"data": []})) with pytest.raises(ApiError, match="366"): ma.MetaAdsSource().fetch_days(_ctx(), date(2025, 1, 1), date(2026, 10, 1)) with pytest.raises(NotConfigured): @@ -402,3 +400,102 @@ def test_details_endpoint_returns_tabs(monkeypatch): d = TestClient(app).get("/performance/api/ad-spend/meta/details?from=2026-10-01&to=2026-10-31").json() assert d["columns"] == ["광고비(부가세 포함)"] and [t["label"] for t in d["tabs"]] == ["합계", "본계정"] assert d["accounts_missing"] == 0 + + +# ── 외화(USD) 광고 계정 — 그날 환율로 원화 환산(2026-10-16) ── +from app.modules.performance import fx # noqa: E402 + +FX_ROWS = [{"date": "2026-10-01", "base": "USD", "quote": "KRW", "rate": 1350.0}, + {"date": "2026-10-02", "base": "USD", "quote": "KRW", "rate": 1360.5}] # 10-03 은 없음 → 10-02 값 + + +def _fx_and_meta(insights_by_account, fx_rows=FX_ROWS, fx_status=200): + calls = {"fx": []} + + def handler(req: httpx.Request) -> httpx.Response: + if req.url.host == "api.frankfurter.dev": + calls["fx"].append(req) + return httpx.Response(fx_status, json=fx_rows if fx_status == 200 else {"status": fx_status, "message": "down"}) + acc = req.url.path.split("/act_")[1].split("/")[0] + return httpx.Response(200, json={"data": insights_by_account.get(acc, [])}) + return handler, calls + + +def _usd(day, spend, value, **extra): + return {**_row(day, spend, account_currency="USD", account_name="US 계정", + action_values=[{"action_type": "omni_purchase", "value": value}]), **extra} + + +def test_usd_account_converted_with_daily_rate(monkeypatch): + fx.clear_cache() + handler, calls = _fx_and_meta({ + "333333": [_usd("2026-10-01", "100", "400"), _usd("2026-10-03", "10.5", "0")], + "444444": [_row("2026-10-01", "50000", account_name="원화 계정")], + }) + _install(monkeypatch, handler) + d1, d3 = ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333,444444"), date(2026, 10, 1), date(2026, 10, 3)) + q = calls["fx"][0].url.params + assert (q["base"], q["quotes"], q["to"]) == ("USD", "KRW", "2026-10-03") and q["from"] <= "2026-10-01" + assert len(calls["fx"]) == 1 # 통화마다 기간 한 번 + # 10-01: USD 100 × 1,350 = 135,000원 + 원화 50,000 = 185,000 → 부가세 포함 203,500 + # 구매 전환값 USD 400 × 1,350 = 540,000 → ROAS = 540,000 ÷ 185,000 = 291.89% + assert (d1.amount, d1.roas) == (203500, Decimal("291.89")) + assert d1.metrics["지출 금액(부가세 별도)"] == 185000 and d1.metrics["구매 전환값"] == 540000 + us = d1.metrics["_accounts"]["333333"] + assert (us["amount"], us["roas"]) == (148500, 400.0) # 135,000 × 1.1, ROAS 는 환율과 무관(400 ÷ 100) + assert us["metrics"]["지출 금액(USD)"] == 100.0 and us["metrics"]["적용 환율(원)"] == 1350.0 + assert "적용 환율(원)" not in d1.metrics["_accounts"]["444444"]["metrics"] # 원화 계정엔 없음 + assert "적용 환율(원)" not in d1.metrics # 합계 표에도 없음 + # 10-03: 그날 환율 없음 → 10-02 값(1,360.5). 10.5 × 1,360.5 = 14,285.25 → 부가세 포함 15,713.775 → 15,714 + assert d3.day == date(2026, 10, 3) and d3.amount == 15714 + assert d3.metrics["_accounts"]["333333"]["metrics"]["적용 환율(원)"] == 1360.5 + + +def test_usd_rate_unavailable_saves_nothing(monkeypatch): + fx.clear_cache() + handler, _calls = _fx_and_meta({"333333": [_usd("2026-10-01", "100", "0")]}, fx_status=503) + _install(monkeypatch, handler) + with pytest.raises(ApiError) as info: + ma.MetaAdsSource().fetch_days(_ctx(account_ids="333333"), date(2026, 10, 1), date(2026, 10, 1)) + assert "USD 광고 계정을 원화로 바꿀 환율" in str(info.value) and "503" in str(info.value) and TOKEN not in str(info.value) + + +def test_krw_rates_fill_cache_and_errors(): + fx.clear_cache() + seen = [] + + def route(req): + seen.append(req) + return httpx.Response(200, json=FX_ROWS + [{"date": "x", "quote": "KRW", "rate": 1}, {"date": "2026-10-02", "quote": "JPY", "rate": 9}]) + + client = httpx.Client(transport=httpx.MockTransport(route)) + rates = fx.krw_rates(client, "usd", date(2026, 10, 1), date(2026, 10, 4), today=date(2026, 10, 10)) + assert rates == {date(2026, 10, 1): Decimal("1350.0"), date(2026, 10, 2): Decimal("1360.5"), + date(2026, 10, 3): Decimal("1360.5"), date(2026, 10, 4): Decimal("1360.5")} # 빈 날 = 앞 날 값 + # 실제로 고시된 지난 날(10-01·10-02)만 기억 — 그 두 날만 다시 물으면 서버에 묻지 않는다 + assert fx.krw_rates(client, "USD", date(2026, 10, 1), date(2026, 10, 2), today=date(2026, 10, 10))[date(2026, 10, 2)] == Decimal("1360.5") + assert len(seen) == 1 + fx.krw_rates(client, "USD", date(2026, 10, 1), date(2026, 10, 3), today=date(2026, 10, 10)) # 10-03 은 앞 날 값이라 기억 안 함 + assert len(seen) == 2 + assert fx.krw_rates(client, "KRW", date(2026, 10, 1), date(2026, 10, 2)) == {date(2026, 10, 1): 1, date(2026, 10, 2): 1} + with pytest.raises(fx.FxError, match="찾지 못했습니다"): # 앞 열흘에도 없음 + fx.krw_rates(client, "USD", date(2026, 11, 1), date(2026, 11, 1), today=date(2026, 11, 5)) + + def down(req): + raise httpx.ConnectError("boom") + with pytest.raises(fx.FxError, match="ConnectError"): + fx.krw_rates(httpx.Client(transport=httpx.MockTransport(down)), "EUR", date(2026, 10, 1), date(2026, 10, 1)) + + +def test_detail_table_rate_total_is_weighted_average(): + rows = [_stored("2026-10-01", 1000, None, {"적용 환율(원)": 1300.0}), + _stored("2026-10-02", 3000, None, {"적용 환율(원)": 1400.0}), + _stored("2026-10-03", 0, None, {"적용 환율(원)": 9999.0})] # 광고비 0 인 날은 빼고 + assert ad_spend.detail_table(rows)["total"]["적용 환율(원)"] == 1375.0 # (1300×1000 + 1400×3000) ÷ 4000 + + +def test_connection_mentions_conversion(monkeypatch): + _install(monkeypatch, lambda req: httpx.Response(200, json={"name": "US", "currency": "USD", "timezone_name": "America/Los_Angeles", + "account_status": 1})) + msg = ma.MetaAdsSource().test_connection(_ctx(account_ids="333333")) + assert "그날 환율로 원화로 바꿔 넣습니다" in msg and "가져올 수 없습니다" not in msg diff --git a/docs/PERFORMANCE_MODULE.md b/docs/PERFORMANCE_MODULE.md index 210ba33..d3574c4 100644 --- a/docs/PERFORMANCE_MODULE.md +++ b/docs/PERFORMANCE_MODULE.md @@ -408,7 +408,12 @@ (= 광고 관리자 "구매 ROAS"). 구매 전환값·구매수 = `action_values`·`actions` 에서 `omni_purchase` → `purchase` → 픽셀 구매 순서로 처음 있는 것 하나 (메타가 같은 구매를 여러 종류에 같은 값으로 겹쳐 주므로 더하지 않음). 항목 `metrics` = 광고비(부가세 포함)·지출 금액(부가세 별도)·노출수·클릭수· 클릭률(%)·링크 클릭·구매수·구매 전환값·ROAS(%) → 메타 머리글 클릭 = 일자별 표(`DETAIL_CHANNELS`). - 원화(KRW)가 아닌 계정이 있으면 저장 안 함. 오류 코드 안내(`_HINTS`): 190 = 토큰 만료·무효(상태 "Token 만료"), 200·10 = 권한(ads_read·계정 배정), + **외화 계정**(2026-10-16, 사용자 요청 — USD 계정 1314634672357695): 원화가 아닌 계정은 지출 금액·구매 전환값을 **그날 환율로 원화 환산**한 뒤 + 다른 계정과 더한다(`fx.py` `krw_rates` — Frankfurter v2 `https://api.frankfurter.dev/v2/rates?base=USD"es=KRW&from=&to=`, API 키 없음, + 여러 중앙은행 고시 환율 종합(blended)이라 주말 포함 매일 있음, 서울외국환중개 매매기준율과는 조금 다를 수 있음). 그날 값이 없으면 앞 10일 안 가장 가까운 날 값, + 그래도 없거나 환율 서버 장애면 그 회차는 저장하지 않음(일부만 환산 금지, 오류 안내). 통화마다 기간 한 번 요청, 2일 이상 지난 날 환율은 프로세스 안 캐시. + 광고비 = 지출 × 환율 × 1.1(부가세), ROAS 는 비율이라 환율과 무관. 계정 탭에 `지출 금액(USD)`·`적용 환율(원)`(합계 줄 = 광고비 가중 평균). + 오류 코드 안내(`_HINTS`): 190 = 토큰 만료·무효(상태 "Token 만료"), 200·10 = 권한(ads_read·계정 배정), 100·803 = 계정 ID, 4·17·613·80000·80004 = 호출 한도, 2635 = 버전 종료. 연결 테스트 = 계정마다 이름·통화·시간대·상태. **권한 오류 진단**(2026-10-16, 실제로 `(#200) Ad account owner has NOT grant ads_management or ads_read permission` 발생): 연결 테스트가 권한 오류를 받으면 메타에 ① `debug_token`(같은 토큰 — 앱·만료·`scopes`·`granular_scopes.target_ids`, 안 되면 `me/permissions`)