feat: 통계 조회 시 기간 필터 기능 추가 (#253)

시작일과 종료일을 입력받아 해당 기간에 해당하는 통계 데이터를 조회할 수 있도록 개선.
기간 형식 검증 로직 추가로 안전성 확보.

Author: soonduck-dreams

src/main/java/org/devkor/apu/saerok_server/domain/stat/api/AdminStatController.java

@@ -46,12 +46,14 @@ public class AdminStatController {
             }
     )
     public StatSeriesResponse getSeries(
-            @Parameter(description = "반복 지정 가능") @RequestParam List<String> metric
+            @Parameter(description = "반복 지정 가능") @RequestParam List<String> metric,
+            @Parameter(description = "조회 기간 (시작일,종료일)", example = "2024-01-01,2024-01-31")
+            @RequestParam(required = false) String period
     ) {
         List<StatMetric> metrics = metric.stream()
                 .map(s -> EnumParser.fromString(StatMetric.class, s))
                 .toList();
-        return queryService.getSeries(metrics);
+        return queryService.getSeries(metrics, period);
     }
 
     @PostMapping("/aggregate-yesterday")

src/main/java/org/devkor/apu/saerok_server/domain/stat/application/StatQueryService.java

@@ -5,9 +5,12 @@
 import org.devkor.apu.saerok_server.domain.stat.core.entity.DailyStat;
 import org.devkor.apu.saerok_server.domain.stat.core.entity.StatMetric;
 import org.devkor.apu.saerok_server.domain.stat.core.repository.DailyStatRepository;
+import org.devkor.apu.saerok_server.global.shared.exception.BadRequestException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 
+import java.time.LocalDate;
+import java.time.format.DateTimeParseException;
 import java.util.*;
 
 @Service
@@ -17,12 +20,13 @@ public class StatQueryService {
 
     private final DailyStatRepository dailyRepo;
 
-    public StatSeriesResponse getSeries(List<StatMetric> metrics) {
+    public StatSeriesResponse getSeries(List<StatMetric> metrics, String period) {
         if (metrics == null || metrics.isEmpty()) return StatSeriesResponse.empty();
 
+        LocalDateRange range = parsePeriod(period);
         List<StatSeriesResponse.Series> out = new ArrayList<>();
         for (StatMetric m : metrics) {
-            List<DailyStat> rows = dailyRepo.findSeriesByMetric(m);
+            List<DailyStat> rows = dailyRepo.findSeriesByMetric(m, range.startDate(), range.endDate());
 
             if (m == StatMetric.BIRD_ID_RESOLUTION_STATS_28D) {
                 var minSeries = new StatSeriesResponse.ComponentSeries(
@@ -60,4 +64,41 @@ public StatSeriesResponse getSeries(List<StatMetric> metrics) {
     private static Number numberOrNull(Object o) {
         return (o instanceof Number n) ? n : null;
     }
+
+    private LocalDateRange parsePeriod(String period) {
+        if (period == null || period.isBlank()) {
+            return LocalDateRange.empty();
+        }
+
+        String[] tokens = period.split(",");
+        if (tokens.length != 2) {
+            throw new BadRequestException("period 파라미터는 '시작일,종료일' 형식이어야 합니다.");
+        }
+
+        LocalDate start = parseDate(tokens[0].trim(), "시작일");
+        LocalDate end = parseDate(tokens[1].trim(), "종료일");
+
+        if (start != null && end != null && end.isBefore(start)) {
+            throw new BadRequestException("period 파라미터는 종료일이 시작일보다 빠를 수 없습니다.");
+        }
+
+        return new LocalDateRange(start, end);
+    }
+
+    private LocalDate parseDate(String value, String label) {
+        if (value == null || value.isBlank()) {
+            return null;
+        }
+        try {
+            return LocalDate.parse(value);
+        } catch (DateTimeParseException e) {
+            throw new BadRequestException(label + "은 yyyy-MM-dd 형식이어야 합니다.");
+        }
+    }
+
+    private record LocalDateRange(LocalDate startDate, LocalDate endDate) {
+        private static LocalDateRange empty() {
+            return new LocalDateRange(null, null);
+        }
+    }
 }

src/main/java/org/devkor/apu/saerok_server/domain/stat/core/repository/DailyStatRepository.java

@@ -45,10 +45,28 @@ public void upsertValue(StatMetric metric, LocalDate date, Number value) {
         }
     }
 
-    public List<DailyStat> findSeriesByMetric(StatMetric metric) {
-        return em.createQuery("SELECT s FROM DailyStat s WHERE s.metric = :m ORDER BY s.date", DailyStat.class)
-                .setParameter("m", metric)
-                .getResultList();
+    public List<DailyStat> findSeriesByMetric(StatMetric metric, LocalDate startDate, LocalDate endDate) {
+        StringBuilder jpql = new StringBuilder("SELECT s FROM DailyStat s WHERE s.metric = :m");
+
+        if (startDate != null) {
+            jpql.append(" AND s.date >= :start");
+        }
+        if (endDate != null) {
+            jpql.append(" AND s.date <= :end");
+        }
+        jpql.append(" ORDER BY s.date");
+
+        var query = em.createQuery(jpql.toString(), DailyStat.class)
+                .setParameter("m", metric);
+
+        if (startDate != null) {
+            query.setParameter("start", startDate);
+        }
+        if (endDate != null) {
+            query.setParameter("end", endDate);
+        }
+
+        return query.getResultList();
     }
 
     public Optional<LocalDate> findLastDateOf(StatMetric metric) {