Merge pull request #83 from YAPP-Github/feat/T3-210

Feat/t3 210

Author: yuseok0215

src/main/java/bitnagil/bitnagil_backend/BitnagilBackendApplication.java

@@ -4,10 +4,12 @@
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 import org.springframework.cloud.openfeign.EnableFeignClients;
 import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
+import org.springframework.scheduling.annotation.EnableScheduling;
 
 @SpringBootApplication
 @EnableFeignClients
 @EnableJpaAuditing
+@EnableScheduling
 public class BitnagilBackendApplication {
 
 	public static void main(String[] args) {

src/main/java/bitnagil/bitnagil_backend/emotionMarble/repository/EmotionMarbleRepository.java

@@ -1,18 +1,29 @@
 package bitnagil.bitnagil_backend.emotionMarble.repository;
 
 import bitnagil.bitnagil_backend.emotionMarble.domain.EmotionMarble;
-import bitnagil.bitnagil_backend.global.entity.HistoryPk;
+import bitnagil.bitnagil_backend.emotionMarble.domain.enums.EmotionMarbleType;
 import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
 import org.springframework.stereotype.Repository;
 
 import java.time.LocalDate;
-import java.util.UUID;
+import java.util.List;
 
 @Repository
-public interface EmotionMarbleRepository extends JpaRepository<EmotionMarble, HistoryPk> {
+public interface EmotionMarbleRepository extends JpaRepository<EmotionMarble, Long> {
     EmotionMarble findByUserId(Long userId);
 
     EmotionMarble findByUserIdAndDateIs(Long userId, LocalDate now);
 
     boolean existsByUserIdAndDate(Long userId, LocalDate nowDate);
+
+    @Query("SELECT COUNT(e) FROM EmotionMarble e WHERE e.date BETWEEN :start AND :end")
+    long countByDateBetween(@Param("start") LocalDate start, @Param("end") LocalDate end);
+
+    @Query("SELECT COUNT(e) FROM EmotionMarble e WHERE e.date BETWEEN :start AND :end AND e.emotionMarbleType IN :types")
+    long countByDateBetweenAndEmotionMarbleTypeIn(
+        @Param("start") LocalDate start,
+        @Param("end") LocalDate end,
+        @Param("types") List<EmotionMarbleType> types);
 }

src/main/java/bitnagil/bitnagil_backend/global/config/SecurityConfig.java

@@ -37,7 +37,8 @@ public class SecurityConfig {
         "/swagger-ui/**",
         "/v3/api-docs/**",
         "/api/v1/health-check",
-        "/api/v1/version/**"
+        "/api/v1/version/**",
+        "/api/v1/kpi/**"
     };
 
     private final JwtAuthenticationFilter jwtAuthenticationFilter;

src/main/java/bitnagil/bitnagil_backend/global/swagger/ApiTags.java

@@ -15,4 +15,5 @@ public class ApiTags {
     public static final String APP_VERSION = "앱 버전 API";
     public static final String REPORT = "제보 API";
     public static final String FILE = "파일 API";
+    public static final String KPI = "KPI API";
 }

src/main/java/bitnagil/bitnagil_backend/kpi/controller/KpiController.java

@@ -0,0 +1,24 @@
+package bitnagil.bitnagil_backend.kpi.controller;
+
+import bitnagil.bitnagil_backend.global.response.CustomResponseDto;
+import bitnagil.bitnagil_backend.kpi.controller.spec.KpiSpec;
+import bitnagil.bitnagil_backend.kpi.service.KpiService;
+import java.time.YearMonth;
+import lombok.RequiredArgsConstructor;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequiredArgsConstructor
+@RequestMapping("/api/v1/kpi")
+public class KpiController implements KpiSpec {
+
+    private final KpiService kpiService;
+
+    @Override
+    public CustomResponseDto<String> calculateAndSave(int year, int month) {
+        YearMonth targetMonth = YearMonth.of(year, month);
+        kpiService.calculateAndSave(targetMonth);
+        return CustomResponseDto.from(targetMonth + " KPI 저장 완료");
+    }
+}

src/main/java/bitnagil/bitnagil_backend/kpi/controller/spec/KpiSpec.java

@@ -0,0 +1,26 @@
+package bitnagil.bitnagil_backend.kpi.controller.spec;
+
+import bitnagil.bitnagil_backend.global.response.CustomResponseDto;
+import bitnagil.bitnagil_backend.global.swagger.ApiTags;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.Parameters;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+
+@Tag(name = ApiTags.KPI)
+public interface KpiSpec {
+
+    @Operation(summary = "월별 KPI 계산 및 저장",
+        description = "지정한 연·월의 KPI를 계산하여 DB에 저장합니다. 이미 해당 월 데이터가 있으면 저장하지 않습니다. (로컬/스웨거 테스트용)")
+    @Parameters({
+        @Parameter(name = "year", description = "연도", required = true, example = "2025"),
+        @Parameter(name = "month", description = "월 (1~12)", required = true, example = "2")
+    })
+    @PostMapping("/calculate")
+    CustomResponseDto<String> calculateAndSave(
+        @RequestParam int year,
+        @RequestParam int month
+    );
+}

src/main/java/bitnagil/bitnagil_backend/kpi/domain/MonthlyKpi.java

@@ -0,0 +1,85 @@
+package bitnagil.bitnagil_backend.kpi.domain;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.validation.constraints.NotNull;
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import lombok.AccessLevel;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+/**
+ * 월별 성과 KPI 집계 결과를 저장하는 엔티티입니다.
+ * 매월 1일 스케줄러가 전월 데이터를 집계하여 한 건 저장합니다.
+ */
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+@Entity
+public class MonthlyKpi {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    /**
+     * 집계 대상 월 (해당 월 1일)
+     */
+    @NotNull
+    @Column(name = "target_month", unique = true, nullable = false)
+    private LocalDate targetMonth;
+
+    /**
+     * 지표 1: 가입 후 7일 이내 루틴 1회 이상 완료 비율 (%)
+     * (7일 내 루틴 1회 이상 완료 유저 수 / 신규 가입자 수) × 100
+     */
+    @Column(precision = 5, scale = 2)
+    private BigDecimal routineCompletionWithinSevenDaysRate;
+
+    /**
+     * 지표 2: 월간 1회 이상 루틴 완료 사용자 비율 (%)
+     * (월 1회 이상 루틴 완료 유저 수 / 전체 가입자 수) × 100
+     */
+    @Column(precision = 5, scale = 2)
+    private BigDecimal monthlyRoutineActiveUserRate;
+
+    /**
+     * 지표 3: 앱 접속 후 루틴 1개 이상 등록 비율 (%)
+     * (루틴 1개 이상 등록 유저 수 / 월간 활성 사용자 수) × 100
+     */
+    @Column(precision = 5, scale = 2)
+    private BigDecimal routineRegistrationRate;
+
+    /**
+     * 지표 4: '나가봐요' 카테고리 루틴 1회 이상 완료 비율 (%)
+     * (외출 루틴 1회 이상 완료 유저 수 / 월간 활성 사용자 수) × 100
+     */
+    @Column(precision = 5, scale = 2)
+    private BigDecimal outingRoutineCompletionRate;
+
+    /**
+     * 지표 5: 긍정 감정 비율 (%)
+     * (긍정 감정 기록 수 / 전체 감정 기록 수) × 100 — 활기, 만족, 평온
+     */
+    @Column(precision = 5, scale = 2)
+    private BigDecimal positiveEmotionRate;
+
+    @Builder
+    public MonthlyKpi(LocalDate targetMonth,
+        BigDecimal routineCompletionWithinSevenDaysRate,
+        BigDecimal monthlyRoutineActiveUserRate,
+        BigDecimal routineRegistrationRate,
+        BigDecimal outingRoutineCompletionRate,
+        BigDecimal positiveEmotionRate) {
+        this.targetMonth = targetMonth;
+        this.routineCompletionWithinSevenDaysRate = routineCompletionWithinSevenDaysRate;
+        this.monthlyRoutineActiveUserRate = monthlyRoutineActiveUserRate;
+        this.routineRegistrationRate = routineRegistrationRate;
+        this.outingRoutineCompletionRate = outingRoutineCompletionRate;
+        this.positiveEmotionRate = positiveEmotionRate;
+    }
+}

src/main/java/bitnagil/bitnagil_backend/kpi/repository/KpiQueryRepository.java

@@ -0,0 +1,44 @@
+package bitnagil.bitnagil_backend.kpi.repository;
+
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.util.List;
+
+/**
+ * KPI 집계 전용 조회 쿼리를 모아둔 리포지토리 인터페이스입니다.
+ * 복합 집계(루틴 완료 유저 수, 7일 내 완료 유저 수 등)를 제공합니다.
+ */
+public interface KpiQueryRepository {
+
+    long countDistinctUsersWithRoutineCompletionV1InPeriod(LocalDate start, LocalDate end);
+
+    long countDistinctUsersWithRoutineCompletionV2InPeriod(LocalDate start, LocalDate end);
+
+    /**
+     * 전월 기간 내 V1 또는 V2 루틴 1회 이상 완료한 distinct user_id 수 (중복 제거)
+     */
+    long countDistinctUsersWithRoutineCompletionInPeriod(LocalDate start, LocalDate end);
+
+
+    long countDistinctUsersWithRoutineRegistrationInPeriod(LocalDateTime monthStart, LocalDateTime monthEnd);
+
+    long countDistinctUsersWithOutingCompletionInPeriod(LocalDate start, LocalDate end);
+
+    long countDistinctUsersWithEmotionInPeriod(LocalDate start, LocalDate end);
+
+    List<Long> findDistinctActiveUserIdsInPeriod(
+        LocalDate start,
+        LocalDate end,
+        LocalDateTime monthStart,
+        LocalDateTime monthEnd);
+
+    /**
+     * 전월 신규 가입자 중 가입 후 7일 이내 V1 루틴 1회 이상 완료한 user_id 목록 (중복 제거는 서비스에서 V2와 합쳐서 수행)
+     */
+    List<Long> findUserIdsWithRoutineCompletionWithin7DaysV1(LocalDateTime monthStart, LocalDateTime monthEnd);
+
+    /**
+     * 전월 신규 가입자 중 가입 후 7일 이내 V2 루틴 1회 이상 완료한 user_id 목록
+     */
+    List<Long> findUserIdsWithRoutineCompletionWithin7DaysV2(LocalDateTime monthStart, LocalDateTime monthEnd);
+}