[UPLUS-121] feat : Cloud Function API 로직 수정 및 DTO 수정

build.gradle

@@ -22,6 +22,8 @@ def coverageExcludePackages = [
     '**/batch/**',       // Batch 제외
     '**/invoice/**',
     '**/notification/**',
+    '**/usage/**',
+    '**/util/**',
 ]
 
 // JaCoCo용 제외 패턴 (클래스 파일)
@@ -96,6 +98,9 @@ dependencies {
     // RestTemplate
     implementation "org.apache.httpcomponents.client5:httpclient5"
 
+    // Cron
+    implementation "com.cronutils:cron-utils:9.2.1"
+
 }
 
 // ============================================================================

src/main/java/com/project/core/controller/InvoiceBatchAdminController.java

@@ -9,28 +9,28 @@
 
 import com.project.core.controller.dto.request.BatchTriggerRequest;
 import com.project.core.controller.dto.request.UpdateBatchScheduleRequest;
-import com.project.core.service.BatchScheduleService;
 import com.project.core.util.BatchTriggerClient;
 
 import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
 
 @RestController
 @RequestMapping("/admin/batch/invoice")
 @RequiredArgsConstructor
+@Slf4j
 public class InvoiceBatchAdminController {
 
     private final BatchTriggerClient batchTriggerClient;
-    private final BatchScheduleService scheduleService;
 
     @PostMapping("/run-now")
     public ResponseEntity<Void> runNow(@RequestBody BatchTriggerRequest request) {
+        log.info("[run-now] called. job={}, invMonth={}", request.job(), request.invMonth());
         batchTriggerClient.trigger(request.job(), request.invMonth());
         return ResponseEntity.accepted().build();
     }
 
     @PutMapping("/schedule")
     public ResponseEntity<Void> updateSchedule(@RequestBody UpdateBatchScheduleRequest request) {
-        scheduleService.updateSchedule(request.job(), request.cron());
         batchTriggerClient.schedule(request.job(), request.cron());
         return ResponseEntity.ok().build();
     }

src/main/java/com/project/core/controller/dto/BatchSummaryDto.java

@@ -3,15 +3,24 @@
 import java.time.LocalDateTime;
 
 import lombok.AllArgsConstructor;
+import lombok.Builder;
 import lombok.Getter;
+import lombok.NoArgsConstructor;
 
 @Getter
+@Builder(toBuilder = true)
+@NoArgsConstructor
 @AllArgsConstructor
 public class BatchSummaryDto {
     private String jobName;
     private String status;
     private String exitCode;
     private String exitMessage;
+
+    private String cronExpression; // 0 0 2 * * *
+    private String cronDescription; // 매일 오전 2시
+    private LocalDateTime nextFireTime; // 다음 실행 시각
+
     private LocalDateTime startTime;
     private LocalDateTime endTime;
     private long durationMs;

src/main/java/com/project/core/controller/dto/response/BatchScheduleResponse.java

@@ -0,0 +1,21 @@
+package com.project.core.controller.dto.response;
+
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+@Getter
+@NoArgsConstructor
+public class BatchScheduleResponse {
+
+    private String jobType; // INVOICE
+    private String scheduleName; // projects/.../jobs/...
+    private String cron; // 15 12 26 1 *
+    private String invMonth; // null 가능
+    private String description; // Auto-created/Updated via Batch Control API
+    private String state; // ENABLED / DISABLED
+    private String timeZone; // Asia/Seoul
+
+    public boolean isEnabled() {
+        return "ENABLED".equalsIgnoreCase(state);
+    }
+}

src/main/java/com/project/core/infra/entity/batch/BatchJobType.java

@@ -8,8 +8,8 @@
 @Getter
 @RequiredArgsConstructor
 public enum BatchJobType {
-    INVOICE_ITEM_JOB("invoiceItemJob", "청구 내역 생성"),
-    INVOICE_JOB("invoiceJob", "청구서 생성");
+    INVOICE_ITEM_JOB("invoiceItemJob", "INVOICE_ITEM"),
+    INVOICE_JOB("invoiceJob", "INVOICE");
 
     private final String jobName;
     private final String title;

src/main/java/com/project/core/infra/repository/invoice/BatchFailureQueryRepositoryImpl.java

@@ -30,6 +30,7 @@ public List<BatchFailureLogDto> findRecentFailures(int limit) {
                     JOIN BATCH_JOB_EXECUTION je
                       ON ji.JOB_INSTANCE_ID = je.JOB_INSTANCE_ID
                     WHERE je.STATUS = 'FAILED'
+                      AND ji.JOB_NAME IN ('invoiceJob', 'invoiceItemJob')
                     ORDER BY je.END_TIME DESC
                     LIMIT ?
                 """;

src/main/java/com/project/core/infra/repository/invoice/BatchJobQueryRepositoryImpl.java

@@ -1,5 +1,6 @@
 package com.project.core.infra.repository.invoice;
 
+import java.time.LocalDateTime;
 import java.util.List;
 
 import org.springframework.jdbc.core.JdbcTemplate;
@@ -46,16 +47,25 @@ WHERE ji2.JOB_NAME IN ('invoiceJob', 'invoiceItemJob')
         return jdbcTemplate.query(
                 sql,
                 (rs, rowNum) -> {
-                    var startTimeStamp = rs.getTimestamp("START_TIME");
-                    var endTimeStamp = rs.getTimestamp("END_TIME");
-                    return new BatchSummaryDto(
-                            rs.getString("JOB_NAME"),
-                            rs.getString("STATUS"),
-                            rs.getString("EXIT_CODE"),
-                            rs.getString("EXIT_MESSAGE"),
-                            startTimeStamp != null ? startTimeStamp.toLocalDateTime() : null,
-                            endTimeStamp != null ? endTimeStamp.toLocalDateTime() : null,
-                            rs.getLong("DURATION_MS"));
+                    var startTimestamp = rs.getTimestamp("START_TIME");
+                    var endTimestamp = rs.getTimestamp("END_TIME");
+
+                    LocalDateTime startTime =
+                            startTimestamp != null ? startTimestamp.toLocalDateTime() : null;
+
+                    LocalDateTime endTime =
+                            endTimestamp != null ? endTimestamp.toLocalDateTime() : null;
+
+                    return BatchSummaryDto.builder()
+                            .jobName(rs.getString("JOB_NAME"))
+                            .status(rs.getString("STATUS"))
+                            .exitCode(rs.getString("EXIT_CODE"))
+                            .exitMessage(rs.getString("EXIT_MESSAGE"))
+                            .startTime(startTime)
+                            .endTime(endTime)
+                            .durationMs(rs.getLong("DURATION_MS"))
+                            // cron 관련 필드는 Service에서 채움
+                            .build();
                 });
     }
 }

src/main/java/com/project/core/service/InvoiceService.java

@@ -1,11 +1,25 @@
 package com.project.core.service;
 
+import java.time.ZoneId;
+import java.time.ZonedDateTime;
+import java.util.List;
+import java.util.Locale;
+
+import org.springframework.scheduling.support.CronExpression;
 import org.springframework.stereotype.Service;
 
+import com.cronutils.descriptor.CronDescriptor;
+import com.cronutils.model.Cron;
+import com.cronutils.model.CronType;
+import com.cronutils.model.definition.CronDefinitionBuilder;
+import com.cronutils.parser.CronParser;
+import com.project.core.controller.dto.BatchSummaryDto;
 import com.project.core.controller.dto.GrafanaInfoDto;
+import com.project.core.controller.dto.response.BatchScheduleResponse;
 import com.project.core.controller.dto.response.BillingDashboardResponse;
 import com.project.core.infra.repository.invoice.BatchFailureQueryRepository;
 import com.project.core.infra.repository.invoice.BatchJobQueryRepository;
+import com.project.core.util.BatchScheduleClient;
 import com.project.global.config.BillingProperties;
 import com.project.global.exception.code.domain.core.CoreErrorCode;
 import com.project.global.exception.core.EntityNotFoundException;
@@ -20,13 +34,21 @@ public class InvoiceService {
 
     private final BatchJobQueryRepository batchJobQueryRepository;
     private final BatchFailureQueryRepository batchFailureQueryRepository;
+    private final BatchScheduleClient batchScheduleClient;
     private final BillingProperties billingProperties;
 
     public BillingDashboardResponse getDashboard() {
 
         try {
+            // 1️⃣ 최신 배치 실행 요약 조회
+            List<BatchSummaryDto> jobs = batchJobQueryRepository.findLatestJobSummaries();
+
+            // 2️⃣ Cloud Function 스케줄 정보 결합
+            List<BatchSummaryDto> enrichedJobs =
+                    jobs.stream().map(this::enrichWithSchedule).toList();
+
             return BillingDashboardResponse.builder()
-                    .batchJobs(batchJobQueryRepository.findLatestJobSummaries())
+                    .batchJobs(enrichedJobs)
                     .grafana(
                             GrafanaInfoDto.builder()
                                     .iframeUrl(billingProperties.getIframeUrl())
@@ -36,8 +58,62 @@ public BillingDashboardResponse getDashboard() {
                     .build();
 
         } catch (Exception e) {
-            log.error("[BillingDashboard] 대시보드 빌딩에 실패했습니다.", e);
+            log.error("[BillingDashboard] 대시보드 빌딩 실패", e);
             throw new EntityNotFoundException(CoreErrorCode.DASHBOARD_NOT_FOUND);
         }
     }
+
+    /** 배치 실행 요약 + Cloud Function 스케줄 정보 결합 */
+    private BatchSummaryDto enrichWithSchedule(BatchSummaryDto job) {
+
+        return batchScheduleClient
+                .getSchedule(job.getJobName())
+                .map(schedule -> applySchedule(job, schedule))
+                .orElseGet(() -> job.toBuilder().cronDescription("수동 실행").build());
+    }
+
+    /** cron / 설명 / 다음 실행 시각 계산 (최종) */
+    private BatchSummaryDto applySchedule(BatchSummaryDto job, BatchScheduleResponse schedule) {
+
+        // 1️⃣ 비활성화 스케줄
+        if (!schedule.isEnabled() || schedule.getCron() == null) {
+            return job.toBuilder().cronDescription("비활성화").build();
+        }
+
+        String cronStr = schedule.getCron();
+        String timeZone = schedule.getTimeZone(); // ex) Asia/Seoul
+
+        try {
+            // 2️⃣ 타임존 (Cloud Function 기준)
+            ZoneId zoneId = ZoneId.of(timeZone);
+
+            // ✅ Spring용 크론 보정 (6필드)
+            String springCronStr = cronStr;
+            if (cronStr.split(" ").length == 5) {
+                springCronStr = "0 " + cronStr;
+            }
+
+            CronExpression springCron = CronExpression.parse(springCronStr);
+
+            ZonedDateTime nextFire = springCron.next(ZonedDateTime.now(zoneId));
+
+            // ✅ cron-utils (UNIX)
+            CronParser parser =
+                    new CronParser(CronDefinitionBuilder.instanceDefinitionFor(CronType.UNIX));
+            Cron cron = parser.parse(cronStr);
+
+            String cronDescription = CronDescriptor.instance(Locale.KOREAN).describe(cron);
+
+            return job.toBuilder()
+                    .cronExpression(cronStr)
+                    .cronDescription(cronDescription)
+                    .nextFireTime(nextFire != null ? nextFire.toLocalDateTime() : null)
+                    .build();
+
+        } catch (Exception e) {
+            log.warn("[BillingDashboard] cron 처리 실패 job={}, cron={}", job.getJobName(), cronStr, e);
+
+            return job.toBuilder().cronExpression(cronStr).cronDescription("잘못된 크론식").build();
+        }
+    }
 }

src/main/java/com/project/core/util/BatchScheduleClient.java

@@ -0,0 +1,49 @@
+package com.project.core.util;
+
+import java.util.Optional;
+
+import org.springframework.http.ResponseEntity;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.HttpStatusCodeException;
+import org.springframework.web.client.RestTemplate;
+
+import com.project.core.controller.dto.response.BatchScheduleResponse;
+import com.project.core.infra.entity.batch.BatchJobType;
+import com.project.global.config.CloudFunctionProperties;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class BatchScheduleClient {
+
+    private final RestTemplate restTemplate;
+    private final CloudFunctionProperties properties;
+
+    public Optional<BatchScheduleResponse> getSchedule(String jobName) {
+
+        String title = BatchJobType.getTitleByJobName(jobName);
+        String url = properties.getBaseUrl() + "/schedule?job=" + title;
+
+        try {
+            ResponseEntity<BatchScheduleResponse> response =
+                    restTemplate.getForEntity(url, BatchScheduleResponse.class);
+
+            return Optional.ofNullable(response.getBody());
+
+        } catch (HttpStatusCodeException e) {
+            log.warn(
+                    "[BatchSchedule] 조회 실패 job={}, status={}, body={}",
+                    jobName,
+                    e.getStatusCode(),
+                    e.getResponseBodyAsString());
+            return Optional.empty();
+
+        } catch (Exception e) {
+            log.error("[BatchSchedule] 조회 중 오류 job={}", jobName, e);
+            return Optional.empty();
+        }
+    }
+}

src/main/java/com/project/core/util/BatchTriggerClient.java

@@ -28,6 +28,7 @@ public class BatchTriggerClient {
     public void trigger(String job, String invMonth) {
 
         String url = properties.getBaseUrl() + "/run-now";
+        log.info("[BatchTrigger] calling url={}", url);
 
         HttpHeaders headers = new HttpHeaders();
         headers.setContentType(MediaType.APPLICATION_JSON);