feat(performance): 광고비 탭(구글·메타·쿠팡 윙/로켓) + 탭 개편·설정 톱니

- 탭: [매출 실적](검정) · [광고비](주황) 큰 탭 + 맨 오른쪽 설정 톱니(Material Symbols settings)
- /performance/ads: 연·월·일 표(채널 × 날짜)·추이·비중·월/연 누적, 매출 대비 광고비 KPI
- 날짜 칸 직접 입력(PUT /api/ad-spend/{channel}/{day}), 쿠팡(로켓) 광고 보고서 업로드
  (CSV/엑셀, 1열 날짜·19열 청구금액(+부가가치세), 잘못된 줄 있으면 전부 거절)
- performance_db 마이그레이션 005 perf_ad_spend
- 설정 화면 쇼핑몰 순서 jsdom 기대값을 003 열 순서로 갱신(기존 실패)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-13 18:20:44 +09:00
parent 099271fdb2
commit ef38140673
16 changed files with 1026 additions and 26 deletions
+103
View File
@@ -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 — 설정(수수료율은 모듈 권한자 누구나, 나머지는 관리자)
# ════════════════════════════════════════════════════════════