diff --git a/CLAUDE.md b/CLAUDE.md
index c89c281..352a46b 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). 패널(`/project/p/{pid}?task=&embed=1`, `html.pj-embed`). 상단 바 화면 배율 토글(`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` — 매출 업데이트에서 빠지고 인증 설정·연결 테스트 없음, 수동 입력 늘 켜짐). 상세는 `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`) — 구글·메타·쿠팡(윙)·쿠팡(로켓) 일 광고비를 연·월·일로, 날짜 칸 직접 입력 + 쿠팡(로켓) 광고 보고서 업로드(1열 날짜·19열 청구금액(+부가가치세)), 매출 대비 광고비 KPI. 상세는 `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_spend.py b/app/modules/performance/ad_spend.py
new file mode 100644
index 0000000..56a264e
--- /dev/null
+++ b/app/modules/performance/ad_spend.py
@@ -0,0 +1,235 @@
+"""광고비 — 채널(구글·메타·쿠팡(윙)·쿠팡(로켓))별 일 광고비 + 업로드 파일 읽기 + 화면 데이터 조립.
+
+저장: performance_db `perf_ad_spend`(마이그레이션 005) — 채널 × 날짜 하나에 금액 하나(원 단위 정수).
+ - 화면 날짜 칸을 눌러 직접 입력(source=manual), 업로드 파일로 한 번에 입력(source=upload, 같은 날 덮어씀).
+ - 구글·메타는 지금은 직접 입력만(API 연동은 다음 단계).
+
+쿠팡(로켓) 업로드 양식(2026-10-13 사용자 제공 — 쿠팡 광고 보고서 CSV/엑셀):
+ 1행 머리글, 1열 = 날짜("2026년 10월 01일"), 19열 = 청구금액(+부가가치세) → 그날 광고비.
+ 날짜 줄 아래 캠페인 줄(1열 빈 칸)과 맨 위 "전체" 합계 줄은 건너뛴다.
+
+HTTP·DB 와 무관한 순수 함수(읽기·조립) — 라우터가 파일 바이트와 저장소를 넘긴다.
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any, Callable, Mapping, Sequence
+
+from . import calc
+from .manual_upload import MAX_AMOUNT, MAX_DATA_ROWS, MAX_ERRORS, MAX_FILE_BYTES, UploadError, parse_amount, parse_date
+
+# 채널 — 표 열 순서. upload = 업로드 양식이 정해진 채널(파일 읽기 함수가 있는 채널).
+CHANNELS: tuple[tuple[str, str], ...] = (
+ ("google", "구글"),
+ ("meta", "메타"),
+ ("coupang_wing", "쿠팡(윙)"),
+ ("coupang_rocket", "쿠팡(로켓)"),
+)
+CHANNEL_NAMES = dict(CHANNELS)
+CHANNEL_CODES = tuple(c for c, _ in CHANNELS)
+
+ROCKET_DATE_COL = 0 # 1열 날짜
+ROCKET_AMOUNT_COL = 18 # 19열 청구금액(+부가가치세)
+SKIP_LABELS = frozenset({"전체", "합계", "총계", "날짜"})
+
+
+class AdMigrationNeeded(Exception):
+ """광고비 표(마이그레이션 005: perf_ad_spend)가 아직 없음."""
+
+
+@dataclass
+class ParseResult:
+ entries: list[tuple[date, int]] = field(default_factory=list) # (날짜, 금액)
+ errors: list[str] = field(default_factory=list)
+ skipped: int = 0 # 건너뛴 줄(캠페인 줄·합계 줄)
+
+
+# ════════════════════════════════════════════════════════════
+# 파일 읽기
+# ════════════════════════════════════════════════════════════
+def _decode_csv(content: bytes) -> str:
+ for enc in ("utf-8-sig", "cp949"):
+ try:
+ return content.decode(enc)
+ except UnicodeDecodeError:
+ continue
+ raise UploadError("CSV 글자 인코딩을 읽을 수 없습니다(UTF-8 또는 CP949 로 저장해 주세요).")
+
+
+def read_rows(content: bytes, filename: str = "") -> list[tuple[Any, ...]]:
+ """CSV 또는 엑셀(.xlsx) 첫 시트 → 줄 목록(값 그대로)."""
+ if not content:
+ raise UploadError("빈 파일입니다.")
+ if len(content) > MAX_FILE_BYTES:
+ raise UploadError("파일이 너무 큽니다(5MB 이하).")
+ is_xlsx = content[:2] == b"PK" or filename.lower().endswith(".xlsx")
+ if not is_xlsx:
+ return [tuple(r) for r in csv.reader(io.StringIO(_decode_csv(content)))]
+ try:
+ import openpyxl # noqa: WPS433
+
+ wb = openpyxl.load_workbook(io.BytesIO(content), read_only=True, data_only=True)
+ except Exception: # noqa: BLE001 — 형식이 다르면 어떤 오류든 같은 안내
+ raise UploadError("파일을 읽을 수 없습니다. 쿠팡 광고 보고서 CSV 또는 엑셀(.xlsx) 파일을 올려 주세요.") from None
+ try:
+ return [tuple(r or ()) for r in wb.worksheets[0].iter_rows(values_only=True)]
+ finally:
+ wb.close()
+
+
+def parse_coupang_rocket(content: bytes, *, today: date, filename: str = "") -> ParseResult:
+ """쿠팡(로켓) 광고 보고서 → (날짜, 청구금액(+부가가치세)). 잘못된 줄이 있으면 errors 에 담는다(저장은 라우터가 막음)."""
+ rows = read_rows(content, filename)
+ res = ParseResult()
+ seen: dict[date, int] = {}
+ for r, row in enumerate(rows, start=1):
+ raw_day = row[ROCKET_DATE_COL] if len(row) > ROCKET_DATE_COL else None
+ text = str(raw_day or "").strip()
+ if not text or text.replace(" ", "") in SKIP_LABELS:
+ res.skipped += 1
+ continue
+ try:
+ day = parse_date(raw_day)
+ except ValueError:
+ if r == 1: # 머리글
+ res.skipped += 1
+ continue
+ res.errors.append(f"{r}행 1열: 날짜를 읽을 수 없습니다({text[:30]}).")
+ continue
+ if day is None:
+ res.skipped += 1
+ continue
+ raw_amt = row[ROCKET_AMOUNT_COL] if len(row) > ROCKET_AMOUNT_COL else None
+ try:
+ amt = parse_amount(raw_amt)
+ except ValueError:
+ res.errors.append(f"{r}행 19열: 금액이 숫자가 아닙니다({str(raw_amt)[:30]}).")
+ continue
+ if amt is None:
+ res.errors.append(f"{r}행 19열: {day.isoformat()} 청구금액이 비어 있습니다.")
+ elif abs(amt) > MAX_AMOUNT:
+ res.errors.append(f"{r}행 19열: 금액이 너무 큽니다.")
+ elif day > today:
+ res.errors.append(f"{r}행: 앞으로의 날짜({day.isoformat()})는 입력할 수 없습니다.")
+ elif day in seen:
+ res.errors.append(f"{r}행: {day.isoformat()} 이 {seen[day]}행과 겹칩니다.")
+ else:
+ seen[day] = r
+ res.entries.append((day, amt))
+ if len(res.entries) > MAX_DATA_ROWS:
+ raise UploadError(f"한 번에 {MAX_DATA_ROWS:,}일까지 올릴 수 있습니다.")
+ if len(res.errors) > MAX_ERRORS:
+ break
+ if not res.entries and not res.errors:
+ raise UploadError("광고비 날짜 줄이 없습니다. 1열 날짜(예: 2026년 10월 01일), 19열 청구금액(+부가가치세) 양식인지 확인하세요.")
+ return res
+
+
+# 업로드 양식이 정해진 채널 → 파일 읽기 함수
+PARSERS: dict[str, Callable[..., ParseResult]] = {"coupang_rocket": parse_coupang_rocket}
+UPLOAD_HELP = {
+ "coupang_rocket": "쿠팡 광고 보고서(CSV 또는 엑셀) — 1열 날짜, 19열 청구금액(+부가가치세)을 그날 광고비로 넣습니다.",
+}
+
+
+# ════════════════════════════════════════════════════════════
+# 화면 데이터
+# ════════════════════════════════════════════════════════════
+def build_ad_dashboard(store: Any, *, kind: str, anchor: date, today: date,
+ custom_from: date | None = None, custom_to: date | None = None,
+ holidays: Mapping[str, str] | None = None,
+ sales_codes: Sequence[str] = ()) -> dict[str, Any]:
+ """광고비 화면 — 매출 실적과 같은 기간 이동·표(일자 × 채널, 연간은 월)·그래프·월/연 누적.
+ sales_codes 가 있으면 같은 기간 매출(총매출) 대비 광고비 비율도 보여 준다."""
+ codes = list(CHANNEL_CODES)
+ period = calc.resolve_period(kind, anchor, custom_from=custom_from, custom_to=custom_to)
+ cmp_start, cmp_end, cmp_label = period.compare_range(today)
+ ref = period.end if period.end < today else today if period.start <= today else period.start
+ month_period = calc.resolve_period("month", ref)
+ year_period = calc.resolve_period("year", ref)
+ m_cmp_start, m_cmp_end, m_cmp_label = month_period.compare_range(today)
+ y_cmp_start, y_cmp_end, y_cmp_label = year_period.compare_range(today)
+ q_start = min(period.start, cmp_start, m_cmp_start, y_cmp_start)
+ q_end = max(period.end, year_period.end)
+
+ migration_needed = False
+ try:
+ amounts, sources = store.ad_amounts(q_start, q_end)
+ except AdMigrationNeeded:
+ amounts, sources, migration_needed = {}, {}, True
+ cells = {k: calc.Money(gross=int(v)) for k, v in amounts.items()}
+
+ cur = calc.sum_range(cells, codes, period.start, period.end)
+ prev = calc.sum_range(cells, codes, cmp_start, cmp_end)
+ mtd = calc.sum_range(cells, codes, month_period.start, month_period.end)
+ m_prev = calc.sum_range(cells, codes, m_cmp_start, m_cmp_end)
+ ytd = calc.sum_range(cells, codes, year_period.start, year_period.end)
+ y_prev = calc.sum_range(cells, codes, y_cmp_start, y_cmp_end)
+
+ sales_total = None
+ if sales_codes:
+ daily = store.daily_amounts(period.start, period.end, list(sales_codes))
+ sales_total = sum(int(v) for v in daily.values())
+ ratio = round(cur.gross / sales_total * 100, 1) if sales_total and sales_total > 0 else None
+
+ word = {"day": "오늘" if period.start == today else "해당일",
+ "week": "이번주" if period.start <= today <= period.end else "해당 주",
+ "month": "이번달" if period.start <= today <= period.end else "해당 월",
+ "year": "올해" if period.start <= today <= period.end else "해당 연도",
+ "custom": "선택 기간"}[period.kind]
+ kpis = [
+ {"key": "spend", "label": f"{word} 광고비", "value": cur.gross, "primary": True,
+ "delta": calc.pct_change(cur.gross, prev.gross), "cmp": cmp_label, "invert": True},
+ {"key": "ratio", "label": f"{word} 매출 대비 광고비", "pct": ratio,
+ "note": f"총매출 ₩{sales_total:,}" if sales_total else "매출 없음"},
+ {"key": "mtd", "label": f"{month_period.label} 누적 광고비", "value": mtd.gross,
+ "delta": calc.pct_change(mtd.gross, m_prev.gross), "cmp": m_cmp_label, "invert": True},
+ {"key": "ytd", "label": f"{year_period.label} 누적 광고비", "value": ytd.gross,
+ "delta": calc.pct_change(ytd.gross, y_prev.gross), "cmp": y_cmp_label, "invert": True},
+ ]
+
+ def url(k: str, anchor_d: date | None = None, start: date | None = None, end: date | None = None) -> str:
+ if k == "custom":
+ return f"?period=custom&from={start.isoformat()}&to={end.isoformat()}"
+ return f"?period={k}&d={anchor_d.isoformat()}"
+
+ if period.kind == "custom":
+ from datetime import timedelta # noqa: WPS433
+
+ length = timedelta(days=period.days)
+ prev_url = url("custom", start=period.start - length, end=period.start - timedelta(days=1))
+ next_url = url("custom", start=period.end + timedelta(days=1), end=period.end + length)
+ else:
+ prev_url, next_url = url(period.kind, period.prev_anchor), url(period.kind, period.next_anchor)
+ nav = {"prev": prev_url, "next": next_url, "quick": [
+ {"label": "오늘", "url": url("day", today), "active": period.kind == "day" and period.start == today},
+ {"label": "이번주", "url": url("week", today), "active": period.kind == "week" and period.start <= today <= period.end},
+ {"label": "이번달", "url": url("month", today), "active": period.kind == "month" and period.start <= today <= period.end},
+ {"label": "올해", "url": url("year", today), "active": period.kind == "year" and period.start <= today <= period.end},
+ ]}
+
+ share = calc.by_code(cells, codes, period.start, period.end)
+ month = calc.month_summary(month_period.start.year, month_period.start.month, codes, cells)
+ return {
+ "nav": nav,
+ "period": period,
+ "period_kind": period.kind,
+ "today": today.isoformat(),
+ "codes": codes,
+ "names": dict(CHANNEL_NAMES),
+ "kpis": kpis,
+ "table": calc.main_table(period, codes, cells, today=today, holidays=holidays),
+ "month": month,
+ "year": calc.year_months(year_period.start.year, codes, cells, today=today),
+ "chart_daily": calc.daily_series(period, codes, cells),
+ "chart_share": [{"code": c, "name": CHANNEL_NAMES[c], **share[c].as_dict()} for c in codes],
+ # 업로드로 들어온 칸(표시용) — "날짜|채널"
+ "upload_cells": sorted(f"{d.isoformat()}|{c}" for (d, c), s in sources.items()
+ if s == "upload" and period.start <= d <= period.end),
+ "upload_channels": [{"code": c, "name": CHANNEL_NAMES[c], "help": UPLOAD_HELP.get(c, "")} for c in PARSERS],
+ "migration_needed": migration_needed,
+ }
diff --git a/app/modules/performance/db.py b/app/modules/performance/db.py
index 88eb0aa..80b8f2b 100644
--- a/app/modules/performance/db.py
+++ b/app/modules/performance/db.py
@@ -373,6 +373,54 @@ class PerformanceDBStore:
raise ManualMigrationNeeded() from None
return len(entries)
+ # ════════════════════════════════════════════════════════════
+ # 광고비(마이그레이션 005)
+ # ════════════════════════════════════════════════════════════
+ def ad_amounts(self, start: date, end: date) -> tuple[dict[tuple[date, str], int], dict[tuple[date, str], str]]:
+ """(날짜, 채널) → 금액, (날짜, 채널) → 입력 방식(manual/upload/api). 005 미적용이면 AdMigrationNeeded."""
+ from .ad_spend import AdMigrationNeeded # noqa: WPS433
+
+ try:
+ with self._pool.connection() as conn:
+ rows = conn.execute(
+ "SELECT spend_date, channel_code, amount, source FROM perf_ad_spend "
+ "WHERE spend_date BETWEEN %s AND %s", (start, end),
+ ).fetchall()
+ except pg_errors.UndefinedTable:
+ raise AdMigrationNeeded() from None
+ return ({(r["spend_date"], r["channel_code"]): int(r["amount"]) for r in rows},
+ {(r["spend_date"], r["channel_code"]): r["source"] for r in rows})
+
+ def set_ad_spend(self, code: str, day: date, amount: int | None, *, source: str = "manual", user: str = "") -> None:
+ """광고비 한 칸 저장(amount None = 지움)."""
+ self.set_ad_spend_bulk(code, [(day, amount)], source=source, user=user)
+
+ def set_ad_spend_bulk(self, code: str, entries: list[tuple[date, int | None]], *, source: str = "manual",
+ user: str = "") -> int:
+ """여러 날을 한 트랜잭션으로(같은 날은 덮어씀, 금액 None 은 지움). 하나라도 실패하면 모두 취소."""
+ from .ad_spend import AdMigrationNeeded # noqa: WPS433
+
+ if not entries:
+ return 0
+ try:
+ with self._pool.connection() as conn:
+ with conn.transaction():
+ with conn.cursor() as cur:
+ gone = [(code, d) for d, a in entries if a is None]
+ keep = [(code, d, int(a), source, user) for d, a in entries if a is not None]
+ if gone:
+ cur.executemany("DELETE FROM perf_ad_spend WHERE channel_code = %s AND spend_date = %s", gone)
+ if keep:
+ cur.executemany(
+ "INSERT INTO perf_ad_spend (channel_code, spend_date, amount, source, updated_by) "
+ "VALUES (%s, %s, %s, %s, %s) ON CONFLICT (channel_code, spend_date) DO UPDATE "
+ "SET amount = EXCLUDED.amount, source = EXCLUDED.source, updated_by = EXCLUDED.updated_by",
+ keep,
+ )
+ except pg_errors.UndefinedTable:
+ raise AdMigrationNeeded() from None
+ return len(entries)
+
def daily_breakdown(self, code: str, start: date, end: date, *, id_prefix: str = "") -> list[dict[str, Any]]:
"""쇼핑몰 화면(일별 매출내역) 대조용 — 날짜별 결제(SALE 합·건수)·환불(그 밖, 양수)·마지막 수집 시각.
id_prefix 가 있으면 이 어댑터가 다른 쇼핑몰 열로 보낸 사건까지 합친다(카페24 화면 합계와 같은 범위)."""
diff --git a/app/modules/performance/router.py b/app/modules/performance/router.py
index 6d566da..65c1c1a 100644
--- a/app/modules/performance/router.py
+++ b/app/modules/performance/router.py
@@ -2,6 +2,7 @@
화면
GET /performance/ 대시보드(모듈 권한)
+ GET /performance/ads 광고비(모듈 권한) — 구글·메타·쿠팡(윙)·쿠팡(로켓) 연·월·일
GET /performance/settings 실적 설정(관리자)
JSON API — 모듈 권한
POST /performance/api/sync 매출 업데이트(사용 중인 쇼핑몰 전부, 쇼핑몰별 실패 격리)
@@ -13,6 +14,8 @@ JSON API — 모듈 권한
PUT /performance/api/manual-sales/{code}/{day} 수동 입력 매출 저장/지움(그 쇼핑몰 수동 입력이 켜져 있을 때, 오늘까지)
GET /performance/api/manual-sales/sample.xlsx 수동 입력 엑셀 업로드 샘플(모듈 폴더 upload_sample.xlsx)
POST /performance/api/manual-sales/upload 수동 입력 엑셀 업로드(1열 날짜, 2열부터 쇼핑몰 이름 머리글)
+ PUT /performance/api/ad-spend/{channel}/{day} 광고비 한 칸 저장/지움(오늘까지)
+ POST /performance/api/ad-spend/upload?channel= 광고비 파일 업로드(쿠팡(로켓) 광고 보고서 — 1열 날짜, 19열 청구금액)
JSON API — 관리자
PUT /performance/api/marketplaces/{code} 사용/매출 집계/수동 입력 여부
POST /performance/api/marketplaces/{code}/rates 수수료율(적용 시작일)
@@ -50,6 +53,8 @@ MAX_BACKFILL_DAYS = 366
MAX_USER_SYNC_DAYS = 92 # 관리자가 아니어도 가져올 수 있는 기간(이번달·직접선택 짧은 기간)
MAX_MANUAL_AMOUNT = 10 ** 12 # 수동 입력 한 칸 상한(원)
MANUAL_SAMPLE_PATH = Path(__file__).resolve().parent / "upload_sample.xlsx"
+AD_MIGRATION_HELP = ("광고비를 쓰려면 performance_db 마이그레이션 005(scripts/sql/performance_db_005_ad_spend.sql)를 "
+ "먼저 적용해야 합니다.")
MANUAL_MIGRATION_HELP = ("수동 입력을 쓰려면 performance_db 마이그레이션 002(scripts/sql/performance_db_002_manual_sales.sql)를 "
"먼저 적용해야 합니다.")
@@ -119,6 +124,33 @@ def dashboard_page(
return render_template(request, "performance/index.html", {**common.base_ctx(user, active_tab="dashboard"), **ctx})
+@router.get("/ads", response_class=HTMLResponse)
+def ads_page(
+ request: Request,
+ period: str = "month",
+ d: str | None = None,
+ from_: str | None = Query(None, alias="from"),
+ to: str | None = None,
+):
+ from app.main import render_template # noqa: WPS433
+
+ g = common.guard(request)
+ if not isinstance(g, tuple):
+ return g
+ store, user = g
+ from .ad_spend import build_ad_dashboard # noqa: WPS433
+ from .dashboard import _sales_marketplaces # noqa: WPS433
+
+ today = today_kst()
+ ctx = build_ad_dashboard(
+ store, kind=period, anchor=_parse_date(d) or today, today=today,
+ custom_from=_parse_date(from_), custom_to=_parse_date(to), holidays=_holidays(),
+ sales_codes=[m["code"] for m in _sales_marketplaces(store)],
+ )
+ return render_template(request, "performance/ads.html",
+ {**common.base_ctx(user, active_tab="ads", page_title="광고비"), **ctx})
+
+
@router.get("/settings", response_class=HTMLResponse)
def settings_page(request: Request):
from app.main import render_template # noqa: WPS433
@@ -358,6 +390,77 @@ def api_manual_upload(request: Request, file: UploadFile = File(...)) -> JSONRes
})
+# ════════════════════════════════════════════════════════════
+# JSON API — 광고비(모듈 권한자 누구나)
+# ════════════════════════════════════════════════════════════
+def _ad_channel(channel: str) -> str:
+ from .ad_spend import CHANNEL_NAMES # noqa: WPS433
+
+ if channel not in CHANNEL_NAMES:
+ raise HTTPException(status_code=404, detail="알 수 없는 광고 채널입니다.")
+ return channel
+
+
+@router.put("/api/ad-spend/{channel}/{day}")
+def api_ad_spend(request: Request, channel: str, day: str, payload: dict[str, Any] = Body(...)) -> JSONResponse:
+ from .ad_spend import AdMigrationNeeded # noqa: WPS433
+
+ store, user = common.require_store(request)
+ _ad_channel(channel)
+ d = _parse_date(day)
+ if d is None:
+ raise HTTPException(status_code=400, detail="날짜가 필요합니다.")
+ if d > today_kst():
+ raise HTTPException(status_code=400, detail="앞으로의 날짜는 입력할 수 없습니다.")
+ raw = payload.get("amount")
+ amount: int | None
+ if raw in (None, ""):
+ amount = None
+ else:
+ try:
+ amount = int(Decimal(str(raw).replace(",", "").strip()))
+ except (InvalidOperation, ValueError):
+ raise HTTPException(status_code=400, detail="금액은 숫자(원)로 입력하세요.") from None
+ if abs(amount) > MAX_MANUAL_AMOUNT:
+ raise HTTPException(status_code=400, detail="금액이 너무 큽니다.")
+ try:
+ store.set_ad_spend(channel, d, amount, source="manual", user=user.get("email", ""))
+ except AdMigrationNeeded:
+ raise HTTPException(status_code=503, detail=AD_MIGRATION_HELP) from None
+ return JSONResponse({"ok": True, "channel": channel, "date": d.isoformat(), "manual": amount,
+ "amount": amount or 0})
+
+
+@router.post("/api/ad-spend/upload")
+def api_ad_spend_upload(request: Request, channel: str = Query(...), file: UploadFile = File(...)) -> JSONResponse:
+ """광고비 파일 업로드 — 파일에 있는 날만 덮어쓴다. 잘못된 줄이 있으면 아무것도 저장하지 않는다."""
+ from . import ad_spend # noqa: WPS433
+ from .manual_upload import MAX_FILE_BYTES, UploadError # noqa: WPS433
+
+ store, user = common.require_store(request)
+ _ad_channel(channel)
+ parser = ad_spend.PARSERS.get(channel)
+ if parser is None:
+ raise HTTPException(status_code=400, detail=f"{ad_spend.CHANNEL_NAMES[channel]} 업로드 양식은 아직 정해지지 않았습니다.")
+ content = file.file.read(MAX_FILE_BYTES + 1)
+ try:
+ res = parser(content, today=today_kst(), filename=file.filename or "")
+ except UploadError as exc:
+ raise HTTPException(status_code=400, detail=str(exc)) from None
+ if res.errors:
+ return JSONResponse(status_code=400, content={
+ "detail": f"잘못된 줄이 {len(res.errors)}개 있어 아무것도 저장하지 않았습니다. 고친 뒤 다시 올려 주세요.",
+ "errors": res.errors})
+ try:
+ saved = store.set_ad_spend_bulk(channel, list(res.entries), source="upload", user=user.get("email", ""))
+ except ad_spend.AdMigrationNeeded:
+ raise HTTPException(status_code=503, detail=AD_MIGRATION_HELP) from None
+ days = sorted(d for d, _ in res.entries)
+ return JSONResponse({"ok": True, "saved": saved, "channel": channel, "name": ad_spend.CHANNEL_NAMES[channel],
+ "total": sum(a for _, a in res.entries), "skipped": res.skipped,
+ "from": days[0].isoformat() if days else None, "to": days[-1].isoformat() if days else None})
+
+
# ════════════════════════════════════════════════════════════
# JSON API — 설정(수수료율은 모듈 권한자 누구나, 나머지는 관리자)
# ════════════════════════════════════════════════════════════
diff --git a/app/modules/performance/templates/performance/_tabs.html b/app/modules/performance/templates/performance/_tabs.html
index eb98526..9fc886e 100644
--- a/app/modules/performance/templates/performance/_tabs.html
+++ b/app/modules/performance/templates/performance/_tabs.html
@@ -1,5 +1,16 @@
-{# 실적 모듈 탭 — 설정 탭은 모듈 권한자 모두(일반 사용자 화면은 수수료율만, 나머지는 관리자). #}
+{# 실적 모듈 탭 — [매출 실적] [광고비] 큰 탭 둘(아이콘 + 색으로 구분) + 맨 오른쪽 설정 톱니(프로젝트 모듈과 같은 아이콘).
+ 설정은 모듈 권한자 모두(일반 사용자 화면은 수수료율만, 나머지는 관리자). #}
+
diff --git a/app/modules/performance/templates/performance/ads.html b/app/modules/performance/templates/performance/ads.html
new file mode 100644
index 0000000..99f9df9
--- /dev/null
+++ b/app/modules/performance/templates/performance/ads.html
@@ -0,0 +1,204 @@
+{% extends "erp_base.html" %}
+
+{% block head_extra %}{% endblock %}
+
+{%- macro won(v) -%}
+ {%- if v is none -%}
+ {%- elif v == 0 -%}–
+ {%- else -%}{{ "{:,}".format(v) }}{%- endif -%}
+{%- endmacro -%}
+
+{% block content %}
+{#- 광고비 — 매출 실적과 같은 기간 이동·표·그래프. 날짜 칸을 눌러 직접 입력(파란 숫자), 업로드로 들어온 값은 주황 숫자. -#}
+ 날짜 칸을 눌러 그날 광고비를 직접 입력합니다 — Enter 저장 후 아래 칸, Esc 취소, 비우고 저장하면 지움.
+ 파란 숫자 = 직접 입력, 주황 숫자 = 파일 업로드 값. 쿠팡(로켓)은 [파일 업로드]로 광고 보고서를 올리면 날짜별로 한 번에 들어갑니다.
+ 광고비 기준: 쿠팡(로켓)은 광고 보고서의 청구금액(+부가가치세). 매출 대비 광고비 = 같은 기간 광고비 ÷ 매출 실적 총매출.
+ 구글·메타·쿠팡(윙)은 지금은 직접 입력합니다.
+ {% if period_kind == 'year' %}월별 × 광고 채널{% else %}일자별 × 광고 채널{% endif %}
+ {% if upload_channels %}
+
+ {% endif %}
+
+
+
+
+
+
+
+ {% for r in table %}
+ {% if period_kind == 'year' %}월{% else %}날짜{% endif %}
+ {% for c in codes %}{{ names[c] }} {% endfor %}
+ {% if period_kind == 'year' %}월 합계{% else %}일 합계{% endif %}
+
+
+ {% endfor %}
+
+
+ {{ r.label }}{% if r.holiday %}{{ r.holiday }}{% endif %}
+
+ {% for c in codes %}
+ {% set v = r.cells[c].gross %}
+ {% if r.kind == 'day' and not r.future and not migration_needed %}
+ {% set up = (r.date ~ '|' ~ c) in upload_cells %}
+ {{ won(v) }}
+ {% else %}
+ {{ won(v) }}
+ {% endif %}
+ {% endfor %}
+ {{ won(r.total.gross) }}
+ {% if period_kind == 'year' %}월별{% else %}일별{% endif %} 광고비 추이
채널별 비중
+ {{ period.label }}{{ month.label }} 채널별 광고비
+
+
+
+ {% for r in month.rows %}
+ 채널 광고비 비중
+
+ {% endfor %}
+
+
+ {{ names[r.code] }}
+ {{ won(r.gross) }}
+
+ {% if r.share is not none %}{{ "%.1f" | format(r.share) }}%{% else %}–{% endif %}
+
+
+
+
+ 합계
+ {{ won(month.total.gross) }}
+ {% if month.total.share is not none %}100%{% else %}–{% endif %}
+ {{ year.year }}년 누적 광고비
+
+
+
+ {% for r in year.rows %}
+ 월 광고비
+
+ {% endfor %}
+
+
+ {{ r.label }}
+ {{ won(r.gross) }}
+
+
+
+ 합계
+ {{ won(year.total.gross) }}
+
파일을 고르세요.
'; return; } + go.disabled = true; + out.innerHTML = '올리는 중…
'; + const fd = new FormData(); + fd.append("file", f); + let res, body = null; + try { + res = await fetch("/performance/api/ad-spend/upload?channel=" + encodeURIComponent(sel.value), + { method: "POST", credentials: "same-origin", body: fd }); + try { body = await res.json(); } catch (_) { body = null; } + } catch (err) { + out.innerHTML = '업로드 실패: ' + esc(err.message) + "
"; + go.disabled = false; + return; + } + go.disabled = false; + if (!res.ok) { + const detail = body && typeof body.detail === "string" ? body.detail : "업로드 실패 (" + res.status + ")"; + const errs = body && body.errors && body.errors.length + ? '' + esc(detail) + "
" + errs; + return; + } + saved = body.saved > 0; + out.innerHTML = '' + esc(body.name) + " " + fmt(body.saved) + "일 반영 (" + + esc(body.from === body.to ? body.from : body.from + " ~ " + body.to) + ") · 합계 " + fmt(body.total) + "원
" + + '창을 닫으면 표·합계·그래프가 다시 계산됩니다.
'; + fileInput.value = ""; + }); + }); + // 직접선택 / 쇼핑몰 필터 const customBtn = document.getElementById("perf-custom-btn"); const customForm = document.getElementById("perf-custom"); @@ -413,13 +481,15 @@ if (raw !== "" && !/^-?\d+$/.test(raw)) return Promise.reject(new Error("숫자(원)만 입력하세요.")); if (raw === was) return Promise.resolve(false); // 바뀐 것 없음(빈 칸 그대로 포함) const job = manualChain.then(function () { - return api("PUT", "/performance/api/manual-sales/" + encodeURIComponent(td.dataset.manualCode) + "/" + + return api("PUT", MANUAL_API + encodeURIComponent(td.dataset.manualCode) + "/" + encodeURIComponent(td.dataset.date), { amount: raw === "" ? null : Number(raw) }); }).then(function (res) { const manual = res.manual == null ? "" : String(res.manual); td.dataset.manualValue = manual; td.classList.toggle("is-manual", manual !== ""); - td.title = manual !== "" ? "수동 입력값 — 눌러 고치기(비우고 저장하면 API 값)" : "눌러 총매출 직접 입력"; + td.classList.remove("is-upload"); + td.title = manual !== "" ? "직접 입력값 — 눌러 고치기(비우고 저장하면 " + (FIXED_METRIC ? "지움" : "API 값") + ")" + : "눌러 " + MANUAL_WORD + " 직접 입력"; const g = td.querySelector(".v-gross"); if (g) g.innerHTML = won(res.amount); td.classList.add("is-stale"); // 수수료·차감 매출은 새로고침 때 다시 계산 @@ -432,10 +502,10 @@ function editManual(td) { if (td.querySelector(".perf-manual-input")) return; const input = el("input", { type: "text", inputmode: "numeric", class: "perf-manual-input", - "aria-label": ((data.names || {})[td.dataset.manualCode] || "") + " " + td.dataset.date + " 총매출" }); + "aria-label": ((data.names || {})[td.dataset.manualCode] || "") + " " + td.dataset.date + " " + MANUAL_WORD }); input.value = digitsOf(td); const g = td.querySelector(".v-gross"); - input.placeholder = digitsOf(td) ? "" : (g ? g.textContent.trim().replace(/[–-]/, "") : "") || "총매출"; + input.placeholder = digitsOf(td) ? "" : (g ? g.textContent.trim().replace(/[–-]/, "") : "") || MANUAL_WORD; td.classList.add("is-editing"); td.appendChild(input); input.focus(); @@ -529,7 +599,7 @@ const pts = data.daily || []; const vals = pts.map(function (p) { return p[metric] || 0; }); if (!pts.length || vals.every(function (v) { return !v; })) { - box.innerHTML = '