운영 관리자에서 AdFit 수익과 ROI를 확인하도록 지원

AdFit 수익과 비용을 기록해 관리자 ROI를 확인하도록 지원

Constraint: AdFit 수익은 콘솔 수동 입력값이며 자동 동기화가 아니다
Tested: AdFit 계산 및 권한과 기존 광고 회귀 테스트 28건
Confidence: high
Scope-risk: narrow

Author: Roy-wonji

docs/api-specs/adfit-api.md

@@ -0,0 +1,16 @@
+# 관리자 AdFit 광고와 ROI
+
+- `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}`.
+- `unit`: NATIVE_WIDE(홈·큐레이션·마이페이지 공유), BANNER(탐색), APP_TRANSITION(앱 시작).
+- `costBasis`: AD_OPERATIONS(광고 운영비), ACQUISITION(유입 광고비), SERVICE_OPERATIONS(서비스 운영비).
+- KRW 금액, 소수 둘째 자리까지, 음수 불가. 같은 날짜·단위는 수정. 미래 날짜 입력 불가.
+- source=MANUAL_CONSOLE: AdFit 콘솔에서 확인한 예상 수익을 관리자가 입력한다. 자동 연동·확정 정산액이 아니다.
+- 광고 단위는 로컬 Picke-iOS의 SDK 연결 기준이다. 개별 사용자에게 SDK가 선택한 이미지·광고주 소재를 재현하거나 실시간 노출을 보증하지 않는다.
+- 같은 단위를 여러 화면에서 사용하더라도 수익은 한 번만 합산한다. 비용도 단위별 배분액으로 입력하며 전체 운영비를 각 단위에 중복 입력하지 않는다.
+- 수익과 비용은 입력된 날짜들의 합계다. reportedDays/expectedDays로 부분 입력을 표시한다. 미입력은 null이며 0원이 아니다.
+- ROI = (수익 - 비용) / 비용 × 100. 모든 날짜가 입력되고 같은 비용 기준이며 비용이 양수일 때만 계산한다. 그 외 null.
+- 수익 0, 비용 양수인 정상 입력은 ROI -100%다. 미입력과 구분한다.
+- 공식 공개 보고서 REST API는 확인하지 못했으므로 비공개 API를 추측하거나 관리자 브라우저에 인증 정보를 저장하지 않는다.
+- 공식 참고: https://adfit.kakao.com/ , https://adfit.github.io/
+- DB: `docs/db/20260910_create_adfit_daily_reports.sql`. 현재 프로젝트는 Hibernate ddl-auto=update를 사용한다.

docs/db/20260910_create_adfit_daily_reports.sql

@@ -0,0 +1,11 @@
+CREATE TABLE IF NOT EXISTS adfit_daily_reports (
+    id BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    created_at TIMESTAMP,
+    updated_at TIMESTAMP,
+    report_date DATE NOT NULL,
+    ad_unit VARCHAR(30) NOT NULL,
+    revenue NUMERIC(16, 2) NOT NULL CHECK (revenue >= 0),
+    cost NUMERIC(16, 2) NOT NULL CHECK (cost >= 0),
+    cost_basis VARCHAR(30) NOT NULL,
+    CONSTRAINT uk_adfit_daily_date_unit UNIQUE (report_date, ad_unit)
+);

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

@@ -0,0 +1,5 @@
+package com.swyp.picke.domain.admin.adfit;
+
+public enum AdfitCostBasis {
+    AD_OPERATIONS, ACQUISITION, SERVICE_OPERATIONS
+}

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

@@ -0,0 +1,40 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import com.swyp.picke.global.common.BaseEntity;
+import jakarta.persistence.*;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.AccessLevel;
+
+@Entity
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Table(name = "adfit_daily_reports", uniqueConstraints = @UniqueConstraint(
+        name = "uk_adfit_daily_date_unit", columnNames = {"report_date", "ad_unit"}))
+public class AdfitDaily extends BaseEntity {
+    @Column(name = "report_date", nullable = false)
+    private LocalDate date;
+    @Enumerated(EnumType.STRING)
+    @Column(name = "ad_unit", nullable = false, length = 30)
+    private AdfitUnit unit;
+    @Column(nullable = false, precision = 16, scale = 2)
+    private BigDecimal revenue;
+    @Column(nullable = false, precision = 16, scale = 2)
+    private BigDecimal cost;
+    @Enumerated(EnumType.STRING)
+    @Column(nullable = false, length = 30)
+    private AdfitCostBasis costBasis;
+
+    public AdfitDaily(LocalDate date, AdfitUnit unit) {
+        this.date = date;
+        this.unit = unit;
+    }
+
+    public void update(BigDecimal revenue, BigDecimal cost, AdfitCostBasis costBasis) {
+        this.revenue = revenue;
+        this.cost = cost;
+        this.costBasis = costBasis;
+    }
+}

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

@@ -0,0 +1,11 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import java.time.LocalDate;
+import java.util.List;
+import java.util.Optional;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AdfitDailyRepository extends JpaRepository<AdfitDaily, Long> {
+    Optional<AdfitDaily> findByDateAndUnit(LocalDate date, AdfitUnit unit);
+    List<AdfitDaily> findAllByDateBetweenOrderByDateDesc(LocalDate from, LocalDate to);
+}

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

@@ -0,0 +1,13 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import jakarta.validation.constraints.*;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+
+public record AdfitDailyRequest(
+        @NotNull LocalDate date,
+        @NotNull AdfitUnit unit,
+        @NotNull @DecimalMin("0") @Digits(integer = 14, fraction = 2) BigDecimal revenue,
+        @NotNull @DecimalMin("0") @Digits(integer = 14, fraction = 2) BigDecimal cost,
+        @NotNull AdfitCostBasis costBasis
+) {}

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

@@ -0,0 +1,14 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+
+public record AdfitReport(LocalDate from, LocalDate to, String source,
+                          List<UnitReport> units, List<Day> days) {
+    public record UnitReport(AdfitUnit unit, String name, List<String> placements, String format,
+                             long reportedDays, long expectedDays, BigDecimal revenue,
+                             BigDecimal cost, BigDecimal roi) {}
+    public record Day(LocalDate date, AdfitUnit unit, BigDecimal revenue, BigDecimal cost,
+                      AdfitCostBasis costBasis) {}
+}

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

@@ -0,0 +1,56 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import java.math.BigDecimal;
+import java.math.RoundingMode;
+import java.time.LocalDate;
+import java.time.ZoneId;
+import java.time.temporal.ChronoUnit;
+import java.util.Arrays;
+import java.util.List;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+@Service
+@RequiredArgsConstructor
+public class AdfitReportService {
+    private final AdfitDailyRepository repository;
+
+    @Transactional
+    public void save(AdfitDailyRequest request) {
+        if (request.date().isAfter(LocalDate.now(ZoneId.of("Asia/Seoul")))) {
+            throw new IllegalArgumentException("미래 날짜의 수익은 입력할 수 없습니다.");
+        }
+        AdfitDaily daily = repository.findByDateAndUnit(request.date(), request.unit())
+                .orElseGet(() -> new AdfitDaily(request.date(), request.unit()));
+        daily.update(request.revenue(), request.cost(), request.costBasis());
+        repository.save(daily);
+    }
+
+    @Transactional(readOnly = true)
+    public AdfitReport report(LocalDate from, LocalDate to) {
+        long expected = ChronoUnit.DAYS.between(from, to) + 1;
+        if (expected < 1 || expected > 366) {
+            throw new IllegalArgumentException("조회 기간은 1일부터 366일까지입니다.");
+        }
+        List<AdfitDaily> days = repository.findAllByDateBetweenOrderByDateDesc(from, to);
+        List<AdfitReport.UnitReport> units = Arrays.stream(AdfitUnit.values()).map(unit -> {
+            List<AdfitDaily> entries = days.stream().filter(day -> day.getUnit() == unit).toList();
+            BigDecimal revenue = entries.isEmpty() ? null : entries.stream().map(AdfitDaily::getRevenue)
+                    .reduce(BigDecimal.ZERO, BigDecimal::add);
+            BigDecimal cost = entries.isEmpty() ? null : entries.stream().map(AdfitDaily::getCost)
+                    .reduce(BigDecimal.ZERO, BigDecimal::add);
+            // 기간이 빠졌거나 비용 기준이 섞이면 비교 가능한 ROI가 아니다.
+            boolean complete = entries.size() == expected
+                    && entries.stream().map(AdfitDaily::getCostBasis).distinct().count() == 1;
+            BigDecimal roi = complete && cost != null && cost.signum() > 0
+                    ? revenue.subtract(cost).multiply(BigDecimal.valueOf(100))
+                        .divide(cost, 2, RoundingMode.HALF_UP) : null;
+            return new AdfitReport.UnitReport(unit, unit.getDisplayName(), unit.getPlacements(),
+                    unit.getFormat(), entries.size(), expected, revenue, cost, roi);
+        }).toList();
+        return new AdfitReport(from, to, "MANUAL_CONSOLE", units, days.stream().map(day ->
+                new AdfitReport.Day(day.getDate(), day.getUnit(), day.getRevenue(), day.getCost(),
+                        day.getCostBasis())).toList());
+    }
+}

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

@@ -0,0 +1,17 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import java.util.List;
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+
+@Getter
+@RequiredArgsConstructor
+public enum AdfitUnit {
+    NATIVE_WIDE("네이티브 광고", List.of("홈", "큐레이션", "마이페이지"), "네이티브 2:1"),
+    BANNER("탐색 배너", List.of("탐색"), "배너 320×100"),
+    APP_TRANSITION("앱 시작 팝업", List.of("앱 시작"), "전면 팝업");
+
+    private final String displayName;
+    private final List<String> placements;
+    private final String format;
+}

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

@@ -0,0 +1,35 @@
+package com.swyp.picke.domain.admin.adfit;
+
+import com.swyp.picke.global.common.response.ApiResponse;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.validation.Valid;
+import java.time.LocalDate;
+import lombok.RequiredArgsConstructor;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.bind.annotation.*;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v1/admin/adfit")
+@PreAuthorize("hasRole('ADMIN')")
+@Tag(name = "관리자 AdFit", description = "iOS 광고 단위 및 콘솔 수동 입력 수익·비용·ROI")
+public class AdminAdfitController {
+    private final AdfitReportService service;
+
+    @GetMapping
+    @Operation(summary = "AdFit 광고 단위와 기간별 수익·ROI", description = "미입력 금액 및 계산 불가 ROI는 null")
+    public ApiResponse<AdfitReport> report(
+            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate from,
+            @RequestParam @DateTimeFormat(iso = DateTimeFormat.ISO.DATE) LocalDate to) {
+        return ApiResponse.onSuccess(service.report(from, to));
+    }
+
+    @PutMapping("/daily")
+    @Operation(summary = "광고 단위별 일일 수익·배분 비용 저장", description = "같은 날짜·광고 단위는 수정한다. 비용을 여러 단위에 중복 입력하지 않는다.")
+    public ApiResponse<Void> save(@Valid @RequestBody AdfitDailyRequest request) {
+        service.save(request);
+        return ApiResponse.onSuccess(null);
+    }
+}