feat: 애드픽 쇼핑 재고 확대 + AdFit 세션 갱신 + Mixpanel·Sentry 지표 (#487)

Author: Roy-wonji

docs/api-specs/adfit-api.md

@@ -2,13 +2,17 @@
 
 - `GET /api/v1/admin/adfit?from=YYYY-MM-DD&to=YYYY-MM-DD`: ADMIN 전용. 최대 366일.
 - `PUT /api/v1/admin/adfit/daily`: ADMIN 전용. `{date, unit, revenue, cost, costBasis}`.
+- `GET /api/v1/admin/adfit/session-cookie`: ADMIN 전용. `{configured, source, updatedAt}`. 쿠키 값은 응답에 담지 않는다.
+- `PUT /api/v1/admin/adfit/session-cookie`: ADMIN 전용. `{cookie}`. AdFit 콘솔에 로그인한 브라우저의 Cookie 헤더 전체를 넣는다.
 - `GET` 응답에는 기존 수동 입력 단위 리포트(`source`, `units`, `days`)와 별도로 `account`가 포함된다.
 - `account.status`: `NOT_CONFIGURED`, `CONNECTED`, `RECONNECT_REQUIRED`, `UNAVAILABLE`.
 - `account.days[]`: `{date, revenue, ctr, ecpm, fillRate, winFillRate}`. AdFit 콘솔에 값이 없거나 누락된 날짜는 `null`이며 0으로 대체하지 않는다.
 - `account.fetchedAt`: `CONNECTED`일 때 이번 관리자 조회에서 AdFit 응답을 성공적으로 파싱한 시각이다. 원천 데이터의 최종 집계 시각이나 배치 동기화 시각이 아니다.
 - `account.revenue`: 조회 기간 중 실제 내려온 일별 수익 합계. 수익 데이터가 전부 `null`이면 `null`.
 - `account.cost`, `account.roi`: AdFit 계정 자동 보고서가 광고 비용을 제공하지 않으므로 항상 `null`.
-- 자동 보고서는 `ADFIT_SESSION_COOKIE` 또는 `picke.adfit.session-cookie`가 있을 때 AdFit 콘솔 계정 종합 일별 API를 조회한다.
+- 자동 보고서는 세션 쿠키가 있을 때 AdFit 콘솔 계정 종합 일별 API를 조회한다. 쿠키는 매 조회 시점에 다시 읽는다.
+- 쿠키 우선순위: 관리자 화면 입력값(`adfit_session_cookies` 테이블, `source=ADMIN_CONSOLE`) > 환경변수 `ADFIT_SESSION_COOKIE`·`picke.adfit.session-cookie`(`source=ENVIRONMENT`). 둘 다 없으면 `source=NONE`.
+- 세션이 만료되면 `RECONNECT_REQUIRED`가 된다. 재배포 없이 `PUT /session-cookie`로 새 쿠키를 넣어 복구한다.
 - 세션 쿠키가 없으면 `NOT_CONFIGURED`, 로그인 만료·리다이렉트·HTML 로그인 응답이면 `RECONNECT_REQUIRED`, API 장애·스키마 불일치면 `UNAVAILABLE`.
 - `unit`: NATIVE_WIDE(홈·큐레이션·마이페이지 공유), BANNER(탐색), APP_TRANSITION(앱 시작).
 - `costBasis`: AD_OPERATIONS(광고 운영비), ACQUISITION(유입 광고비), SERVICE_OPERATIONS(서비스 운영비).
@@ -21,4 +25,5 @@
 - 수익 0, 비용 양수인 정상 입력은 ROI -100%다. 미입력과 구분한다.
 - AdFit 계정 자동 보고서는 콘솔 내부 API(`accountTotal/periodicIndicators`)를 사용한다. 공개 파트너 REST API가 아니므로 세션 만료 시 재연결이 필요하다.
 - 공식 참고: https://adfit.kakao.com/ , https://adfit.github.io/
-- DB: `docs/db/20260910_create_adfit_daily_reports.sql`. 현재 프로젝트는 Hibernate ddl-auto=update를 사용한다.
+- 카카오 REST API 키(`Authorization: KakaoAK ...`)로는 조회할 수 없다. 애드핏 매체주 수익용 공개 REST API가 없다. 카카오 디벨로퍼스 REST API 레퍼런스에 해당 엔드포인트가 없고, AdX Report API는 RTB 연동 DSP 전용, 카카오모먼트 리포트 API는 광고주 집행 측이다.
+- DB: `docs/db/20260910_create_adfit_daily_reports.sql`, `docs/db/20260913_create_adfit_session_cookies.sql`. 현재 프로젝트는 Hibernate ddl-auto=update를 사용한다.

docs/api-specs/admin-analytics-api.md

@@ -0,0 +1,49 @@
+# 관리자 지표 (Mixpanel · Sentry)
+
+- `GET /api/v1/admin/analytics/mixpanel?from=YYYY-MM-DD&to=YYYY-MM-DD&events=A,B`: ADMIN 전용. 최대 366일.
+- `GET /api/v1/admin/analytics/sentry?from=YYYY-MM-DD&to=YYYY-MM-DD`: ADMIN 전용. 최대 366일.
+- 두 응답의 `status`: `NOT_CONFIGURED`, `CONNECTED`, `UNAVAILABLE`. 조회 실패를 0으로 대체하지 않는다.
+- `NOT_CONFIGURED`는 오류가 아니다. 토큰을 넣기 전 상태이므로 화면은 지면을 비우고 안내만 띄운다.
+
+## Mixpanel
+
+집계 API가 아니라 **원본 이벤트를 내려받아 서버가 직접 센다.**
+
+- `GET https://data.mixpanel.com/api/2.0/export?from_date&to_date`. 응답은 한 줄에 이벤트 하나인 NDJSON.
+- 인증은 프로젝트 API 비밀을 Basic 사용자명 자리에 넣고 비밀번호를 비우는 레거시 방식이다. 이 방식에 `project_id`를 넣으면 400이 된다. 비밀이 이미 프로젝트를 특정한다.
+- `events[].days[]`: `{date, count}`. 최신 날짜부터. 원본을 전부 받아 세므로 이벤트가 없던 날짜는 미집계가 아니라 **0**이다.
+- `events`를 비우면 기간에 나타난 이벤트 전부를 발생 수 내림차순으로 준다. 이벤트 이름을 미리 설정해 둘 필요가 없다.
+- 원본을 전부 받으므로 기간은 **31일까지**다(`MixpanelClient.MAX_DAYS`). 4일치가 약 2MB다.
+- `properties.time`은 프로젝트 타임존 기준 epoch 초이고 `from_date`·`to_date` 경계도 같은 타임존을 따른다. 둘을 같은 타임존으로 묶어야 Mixpanel 화면 숫자와 맞는다. `picke.analytics.mixpanel.project-zone`(기본 `UTC`)로 맞춘다. 이 프로젝트는 UTC로 실측 확인했다.
+- 경계 하루가 타임존 차이로 걸쳐 들어올 수 있어 요청 기간 밖 이벤트는 버린다.
+
+### 왜 집계 API를 안 쓰는가
+
+- **현재 Picke의 Mixpanel 플랜은 Query API를 허용하지 않는다.** 2026-09-14 실측: `/api/query/segmentation`·`/api/query/insights` 모두 `HTTP 402 Your plan does not allow API calls`. 인증은 통과하므로 자격 문제가 아니다.
+- 같은 플랜에서 Raw Export는 **200으로 열려 있다.** 그래서 이쪽으로 붙였다. Mixpanel MCP나 다른 클라이언트를 붙여도 Query API를 호출하는 한 같은 402를 받는다.
+- 서비스 계정 방식(`username:secret`)은 이 프로젝트에서 401이다. 프로젝트 토큰(`project_token`)은 이벤트 수집용이라 조회 인증에 쓰이지 않는다(401).
+- 실측(2026-09-14, 09-10~09-13): 16종 이벤트, `screen_view` 644 · `network_request` 561 · `ui_action` 172 · `onboarding_step` 65 · `battle_step` 44 · `sign_up` 3 등.
+
+### 환경변수
+
+- `MIXPANEL_API_SECRET` 하나면 된다. 설정 키는 `picke.analytics.mixpanel.*`.
+- EU·인도 데이터 거주 프로젝트는 호스트가 다르다. `picke.analytics.mixpanel.base-url`로 바꾼다.
+- `ad_click` 이벤트에 `unit`·`placement`·`format` 속성이 붙어 온다. AdFit 클릭은 `unit` 없이 `format=popup`·`placement=app_start`로 들어온다. 광고 클릭을 매체별로 나누려면 이 속성을 쓴다.
+
+## Sentry
+
+- `GET /api/0/projects/{org}/{project}/issues/?query=is:unresolved&sort=freq`. 조직 인증 토큰 `Authorization: Bearer`.
+- 절대 기간을 쓰려면 `statsPeriod`를 빈 값으로 함께 보낸다. 생략하면 Sentry 기본 기간이 적용된다.
+- iOS·Android를 각각 호출해 `projects[]`로 나눠 준다. `projects[]`: `{project, status, totalEvents, issues[]}`.
+- 한 프로젝트가 막혀도 다른 프로젝트는 살린다. 대신 최상위 `status`는 `UNAVAILABLE`, 최상위 `totalEvents`는 `null`이다. 일부만 더한 값을 전체 합계처럼 보여주지 않는다.
+- 프로젝트별 최대 20건. `projects[].totalEvents`는 그 20건의 합계이며 프로젝트 전체 이벤트 수가 아니다.
+- `sort=freq`는 절대 기간에서 이벤트 수 내림차순을 보장하지 않는다(실측 확인). 응답 순서를 믿지 않고 서버가 다시 정렬한다.
+- `issues[].events`는 Sentry가 문자열로 주기도 한다. 숫자·문자열 모두 읽는다.
+- 환경변수: `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`(기본 `picke`), `SENTRY_PROJECTS`(기본 `picke-ios,picke-android`). 설정 키는 `picke.analytics.sentry.*`.
+- 앱은 이미 같은 org·project로 Sentry에 리포트한다. 토큰만 서버에 넣으면 같은 데이터를 읽는다.
+- 실측(2026-09-14, 최근 30일): `picke-ios` 미해결 2건·1,765 이벤트, `picke-android` 9건·181 이벤트.
+
+## 공통
+
+- 외부 호출 실패가 관리자 화면 전체를 500으로 만들지 않는다. 타임아웃은 연결 3초, 요청 10초다.
+- 토큰은 응답에 담지 않는다. 서버 설정에만 둔다.

docs/db/20260913_create_adfit_session_cookies.sql

@@ -0,0 +1,8 @@
+-- AdFit 콘솔 세션 쿠키 보관용. 관리자 화면에서 갱신해 재배포 없이 자동 수익 조회를 복구한다.
+-- 한 행만 두고 쓴다. 조회는 id 역순 첫 행을 읽으므로 행이 늘어도 마지막 값이 이긴다.
+CREATE TABLE IF NOT EXISTS adfit_session_cookies (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    cookie_value VARCHAR(4096) NOT NULL
+);

src/main/java/com/swyp/picke/domain/ad/service/AdpickCampaignSyncService.java

@@ -105,6 +105,10 @@ public int sync() {
      * <p>앱 캠페인과 같은 {@code ADPICK_API} 소스를 쓰되 식별자에 접두사를 둬서 섞이지 않게 한다.
      * 소스를 새로 만들면 {@code ck_ad_creatives_source} 제약을 배포 때 사람이 직접 ALTER 해야 한다.
      * 상품 하나 늘리자고 그 절차를 얹지 않는다.
+     *
+     * <p>상품 하나를 지면 하나에만 두면 지면당 재고가 전체의 1/지면수로 쪼개진다.
+     * 쇼핑 상품은 지면을 가릴 이유가 없으므로 모든 쇼핑 지면에 각각 등록해 지면마다 전량을 쓴다.
+     * 노출·클릭 집계는 소재 단위라, 지면별로 따로 세려면 소재도 지면별로 나뉘어 있어야 한다.
      */
     private int syncShopping(Map<String, AdCreative> existing, Set<String> seen) {
         if (!adpickShoppingClient.isConfigured() || shoppingSlots.isEmpty()) {
@@ -115,19 +119,25 @@ private int syncShopping(Map<String, AdCreative> existing, Set<String> seen) {
                 .filter(AdpickShoppingResponse::isRenderable)
                 .toList();
 
+        Set<String> buyUrls = new HashSet<>();
+        int synced = 0;
         for (AdpickShoppingResponse product : products) {
-            String externalId = shoppingIdOf(product.buyUrl());
-            if (!seen.add(externalId)) {
+            if (!buyUrls.add(product.buyUrl())) {
                 // 쇼핑과 핫딜에 같은 상품이 함께 실릴 수 있다. 먼저 담은 쪽만 남긴다.
                 continue;
             }
-            upsertShopping(existing.get(externalId), externalId, product);
+            for (AdSlotCode target : shoppingSlots) {
+                String externalId = shoppingIdOf(product.buyUrl(), target);
+                seen.add(externalId);
+                upsertShopping(existing.get(externalId), externalId, target, product);
+                synced++;
+            }
         }
-        return products.size();
+        return synced;
     }
 
-    private void upsertShopping(AdCreative found, String externalId, AdpickShoppingResponse product) {
-        AdSlotCode target = slotOf(externalId);
+    private void upsertShopping(
+            AdCreative found, String externalId, AdSlotCode target, AdpickShoppingResponse product) {
         if (found != null) {
             found.syncFromAdpick(
                     truncate(product.productName(), TITLE_MAX_LENGTH),
@@ -162,11 +172,14 @@ private void upsertShopping(AdCreative found, String externalId, AdpickShoppingR
     /**
      * 상품에는 애드픽이 주는 코드가 없어 구매 링크에서 식별자를 만든다.
      * 링크가 그대로면 같은 소재로 갱신되고, 바뀌면 새 소재가 된다.
+     *
+     * <p>같은 상품이 지면마다 따로 등록되므로 지면까지 해시에 넣는다.
+     * 길이와 모양({@code sh} + 16진수 10자)은 그대로 둔다. 조회 쪽이 이 형태로 쇼핑 소재를 가려낸다.
      */
-    private String shoppingIdOf(String buyUrl) {
+    private String shoppingIdOf(String buyUrl, AdSlotCode slot) {
         try {
             byte[] digest = MessageDigest.getInstance("SHA-256")
-                    .digest(buyUrl.getBytes(StandardCharsets.UTF_8));
+                    .digest((buyUrl + "|" + slot.name()).getBytes(StandardCharsets.UTF_8));
             StringBuilder hex = new StringBuilder(SHOPPING_ID_PREFIX);
             for (int i = 0; hex.length() < SHOPPING_ID_PREFIX.length() + SHOPPING_ID_LENGTH; i++) {
                 hex.append(String.format("%02x", digest[i]));
@@ -177,15 +190,6 @@ private String shoppingIdOf(String buyUrl) {
         }
     }
 
-    /**
-     * 지면은 식별자로 정한다. 매 동기화마다 다시 뽑으면 같은 상품이 지면을 옮겨 다녀
-     * 노출 집계가 지면별로 흩어진다.
-     */
-    private AdSlotCode slotOf(String externalId) {
-        int index = Math.floorMod(externalId.hashCode(), shoppingSlots.size());
-        return shoppingSlots.get(index);
-    }
-
     private void upsert(AdCreative found, AdpickCampaignResponse campaign) {
         if (found != null) {
             found.syncFromAdpick(

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitAccountReportClient.java

@@ -11,8 +11,8 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.function.Supplier;
 import lombok.extern.slf4j.Slf4j;
-import org.springframework.beans.factory.annotation.Value;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Component;
 import org.springframework.util.StringUtils;
@@ -24,26 +24,27 @@ public class AdfitAccountReportClient {
     private static final String REPORT_URL =
             "https://adfit.kakao.com/api/v2/report/accountTotal/periodicIndicators";
 
-    private final String sessionCookie;
+    /** 쿠키는 조회할 때마다 다시 읽는다. 관리자가 만료된 값을 갈아끼우면 재배포 없이 바로 반영돼야 한다. */
+    private final Supplier<String> sessionCookieSupplier;
     private final AdfitHttpTransport transport;
     private final ObjectMapper objectMapper;
 
     @Autowired
-    public AdfitAccountReportClient(
-            @Value("${picke.adfit.session-cookie:${ADFIT_SESSION_COOKIE:}}") String sessionCookie,
-            AdfitHttpTransport transport) {
-        this(sessionCookie, transport, new ObjectMapper());
+    public AdfitAccountReportClient(AdfitSessionCookieStore cookieStore, AdfitHttpTransport transport) {
+        this(cookieStore::current, transport, new ObjectMapper());
     }
 
-    AdfitAccountReportClient(String sessionCookie, AdfitHttpTransport transport, ObjectMapper objectMapper) {
-        this.sessionCookie = sessionCookie;
+    AdfitAccountReportClient(Supplier<String> sessionCookieSupplier, AdfitHttpTransport transport,
+                             ObjectMapper objectMapper) {
+        this.sessionCookieSupplier = sessionCookieSupplier;
         this.transport = transport;
         this.objectMapper = objectMapper;
     }
 
     public AdfitReport.AccountReport fetch(LocalDate from, LocalDate to, long expectedDays) {
         validateRange(from, to);
         List<AdfitReport.AccountDay> emptyDays = nullDays(from, to);
+        String sessionCookie = sessionCookieSupplier.get();
         if (!StringUtils.hasText(sessionCookie)) {
             return report(AdfitAccountReportStatus.NOT_CONFIGURED, null, expectedDays, null, emptyDays);
         }

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitReportService.java

@@ -16,6 +16,15 @@
 public class AdfitReportService {
     private final AdfitDailyRepository repository;
     private final AdfitAccountReportClient accountReportClient;
+    private final AdfitSessionCookieStore sessionCookieStore;
+
+    public AdfitSessionCookieStatus sessionCookieStatus() {
+        return sessionCookieStore.status();
+    }
+
+    public void updateSessionCookie(AdfitSessionCookieRequest request) {
+        sessionCookieStore.update(request.cookie());
+    }
 
     @Transactional
     public void save(AdfitDailyRequest request) {

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitSessionCookie.java

@@ -0,0 +1,34 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import com.swyp.picke.global.common.BaseEntity;
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.Table;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * AdFit 콘솔 세션 쿠키.
+ *
+ * <p>AdFit은 매체주 수익을 읽는 공개 REST API가 없어 콘솔 내부 API를 세션 쿠키로 호출한다.
+ * 이 쿠키는 수시로 만료되는데 값이 환경변수에만 있으면 만료마다 재배포를 해야 한다.
+ * 관리자가 화면에서 갈아끼울 수 있도록 한 행으로 보관한다.
+ */
+@Entity
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Table(name = "adfit_session_cookies")
+public class AdfitSessionCookie extends BaseEntity {
+
+    @Column(name = "cookie_value", nullable = false, length = 4096)
+    private String value;
+
+    public AdfitSessionCookie(String value) {
+        this.value = value;
+    }
+
+    public void update(String value) {
+        this.value = value;
+    }
+}

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitSessionCookieRepository.java

@@ -0,0 +1,9 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AdfitSessionCookieRepository extends JpaRepository<AdfitSessionCookie, Long> {
+    /** 한 행만 두고 쓰지만, 저장이 겹쳐 행이 늘어도 마지막 값이 이기게 한다. */
+    Optional<AdfitSessionCookie> findTopByOrderByIdDesc();
+}

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitSessionCookieRequest.java

@@ -0,0 +1,11 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.Size;
+
+/**
+ * @param cookie AdFit 콘솔에 로그인한 브라우저의 Cookie 헤더 전체. {@code name=value; name2=value2} 형태.
+ */
+public record AdfitSessionCookieRequest(
+        @NotBlank @Size(max = 4096) String cookie) {
+}

src/main/java/com/swyp/picke/domain/admin/adfit/AdfitSessionCookieSource.java

@@ -0,0 +1,10 @@
+package com.swyp.picke.domain.admin.adfit;
+
+public enum AdfitSessionCookieSource {
+    /** 관리자가 화면에서 넣은 값. 환경변수보다 앞선다. */
+    ADMIN_CONSOLE,
+    /** 배포 시 주입한 환경변수 값. */
+    ENVIRONMENT,
+    /** 양쪽 모두 없음. 자동 수익 조회가 NOT_CONFIGURED 가 된다. */
+    NONE
+}