[HSC-285] v0.0.12

.gitignore

@@ -15,4 +15,5 @@ yarn-error.log*
 .gradle-home/
 logs/*
 !logs/.gitkeep
+docs/private/
 .gradle-home/

src/main/java/site/holliverse/worker/batch/common/support/SqlFileLoader.java

@@ -0,0 +1,22 @@
+package site.holliverse.worker.batch.common.support;
+
+import org.springframework.core.io.ClassPathResource;
+import org.springframework.stereotype.Component;
+import org.springframework.util.StreamUtils;
+
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+@Component
+public class SqlFileLoader {
+
+    // classpath SQL 파일을 UTF-8 문자열로 읽어 Tasklet에서 재사용한다.
+    public String load(String classpathLocation) {
+        ClassPathResource resource = new ClassPathResource(classpathLocation);
+        try {
+            return StreamUtils.copyToString(resource.getInputStream(), StandardCharsets.UTF_8);
+        } catch (IOException e) {
+            throw new IllegalStateException("SQL 파일을 읽는 중 오류가 발생했습니다: " + classpathLocation, e);
+        }
+    }
+}

src/main/java/site/holliverse/worker/batch/jobs/index/WeeklyIndexJobConfig.java

@@ -0,0 +1,97 @@
+package site.holliverse.worker.batch.jobs.index;
+
+import lombok.RequiredArgsConstructor;
+import org.springframework.batch.core.Job;
+import org.springframework.batch.core.Step;
+import org.springframework.batch.core.job.builder.JobBuilder;
+import org.springframework.batch.core.repository.JobRepository;
+import org.springframework.batch.core.step.builder.StepBuilder;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.transaction.PlatformTransactionManager;
+import site.holliverse.worker.batch.jobs.index.tasklet.BuildPersonaWeeklyIndexTasklet;
+import site.holliverse.worker.batch.jobs.index.tasklet.BuildRawWeeklyIndexTasklet;
+import site.holliverse.worker.batch.jobs.index.tasklet.BuildTScoreWeeklyIndexTasklet;
+import site.holliverse.worker.batch.jobs.index.tasklet.GateWeeklyIndexTasklet;
+import site.holliverse.worker.batch.jobs.index.tasklet.VerifyWeeklyIndexTasklet;
+
+@Configuration
+@RequiredArgsConstructor
+public class WeeklyIndexJobConfig {
+
+    public static final String JOB_NAME = "weeklyIndexJob";
+
+    @Bean
+    public Job weeklyIndexJob(
+            JobRepository jobRepository,
+            Step gateStep,
+            Step buildRawStep,
+            Step buildTScoreStep,
+            Step buildPersonaStep,
+            Step verifyStep
+    ) {
+        // 주간 지수 배치 플로우: 준비 -> raw -> tscore -> persona -> 검증
+        return new JobBuilder(JOB_NAME, jobRepository)
+                .start(gateStep)
+                .next(buildRawStep)
+                .next(buildTScoreStep)
+                .next(buildPersonaStep)
+                .next(verifyStep)
+                .build();
+    }
+
+    @Bean
+    public Step gateStep(
+            JobRepository jobRepository,
+            PlatformTransactionManager tx,
+            GateWeeklyIndexTasklet tasklet
+    ) {
+        return new StepBuilder("Step00_Gate", jobRepository)
+                .tasklet(tasklet, tx)
+                .build();
+    }
+
+    @Bean
+    public Step buildRawStep(
+            JobRepository jobRepository,
+            PlatformTransactionManager tx,
+            BuildRawWeeklyIndexTasklet tasklet
+    ) {
+        return new StepBuilder("Step01_BuildRaw", jobRepository)
+                .tasklet(tasklet, tx)
+                .build();
+    }
+
+    @Bean
+    public Step buildTScoreStep(
+            JobRepository jobRepository,
+            PlatformTransactionManager tx,
+            BuildTScoreWeeklyIndexTasklet tasklet
+    ) {
+        return new StepBuilder("Step02_BuildTScore", jobRepository)
+                .tasklet(tasklet, tx)
+                .build();
+    }
+
+    @Bean
+    public Step buildPersonaStep(
+            JobRepository jobRepository,
+            PlatformTransactionManager tx,
+            BuildPersonaWeeklyIndexTasklet tasklet
+    ) {
+        return new StepBuilder("Step03_BuildPersona", jobRepository)
+                .tasklet(tasklet, tx)
+                .build();
+    }
+
+    @Bean
+    public Step verifyStep(
+            JobRepository jobRepository,
+            PlatformTransactionManager tx,
+            VerifyWeeklyIndexTasklet tasklet
+    ) {
+        return new StepBuilder("Step04_Verify", jobRepository)
+                .tasklet(tasklet, tx)
+                .build();
+    }
+}

src/main/java/site/holliverse/worker/batch/jobs/index/tasklet/BuildPersonaWeeklyIndexTasklet.java

@@ -0,0 +1,63 @@
+package site.holliverse.worker.batch.jobs.index.tasklet;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.batch.core.StepContribution;
+import org.springframework.batch.core.scope.context.ChunkContext;
+import org.springframework.batch.core.step.tasklet.Tasklet;
+import org.springframework.batch.repeat.RepeatStatus;
+import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.stereotype.Component;
+import site.holliverse.worker.batch.common.support.SqlFileLoader;
+
+/**
+ * 페르소나 스냅샷을 생성하는 Step.
+ *
+ * 처리 순서:
+ * 1) 동일 snapshotDate의 기존 persona 결과를 삭제
+ * 2) index_tscore_snapshot에서 회원별 최고 T-score 지수 1개 선택
+ * 3) 지수 코드 -> persona_code 매핑 후 index_persona_snapshot에 저장
+ *
+ * 동점 규칙:
+ * - SQL 내부 정렬 기준(Order By)에 따라 해소
+ * - 현재는 index_code 오름차순(사전순) 우선
+ */
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class BuildPersonaWeeklyIndexTasklet implements Tasklet {
+
+    private static final String DELETE_SQL_PATH = "sql/index/delete_persona_snapshot.sql";
+    private static final String INSERT_SQL_PATH = "sql/index/insert_persona_snapshot.sql";
+
+    private final NamedParameterJdbcTemplate namedParameterJdbcTemplate;
+    private final SqlFileLoader sqlFileLoader;
+
+    @Override
+    public RepeatStatus execute(StepContribution contribution, ChunkContext chunkContext) {
+        // 1) Gate Step에서 확정한 snapshotDate를 컨텍스트에서 읽는다.
+        String snapshotDate = chunkContext.getStepContext()
+                .getStepExecution()
+                .getJobExecution()
+                .getExecutionContext()
+                .getString("snapshotDate");
+
+        // 2) SQL 바인딩 파라미터를 준비한다.
+        MapSqlParameterSource params = new MapSqlParameterSource()
+                .addValue("snapshotDate", snapshotDate);
+
+        // 3) 실행할 SQL 파일(삭제/적재)을 로드한다.
+        String deleteSql = sqlFileLoader.load(DELETE_SQL_PATH);
+        String insertSql = sqlFileLoader.load(INSERT_SQL_PATH);
+
+        // 4) 멱등 실행을 위해 기존 데이터 삭제 후 재적재한다.
+        int deleted = namedParameterJdbcTemplate.update(deleteSql, params);
+        int inserted = namedParameterJdbcTemplate.update(insertSql, params);
+
+        /*log.info("BuildPersona 완료. snapshotDate={}, deleted={}, inserted={}",
+                snapshotDate, deleted, inserted);*/
+
+        return RepeatStatus.FINISHED;
+    }
+}

src/main/java/site/holliverse/worker/batch/jobs/index/tasklet/BuildRawWeeklyIndexTasklet.java

@@ -0,0 +1,68 @@
+package site.holliverse.worker.batch.jobs.index.tasklet;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.batch.core.StepContribution;
+import org.springframework.batch.core.scope.context.ChunkContext;
+import org.springframework.batch.core.step.tasklet.Tasklet;
+import org.springframework.batch.repeat.RepeatStatus;
+import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.stereotype.Component;
+import site.holliverse.worker.batch.common.support.SqlFileLoader;
+
+/**
+ * raw 지수 스냅샷을 생성하는 Step.
+ *
+ * 처리 방식:
+ * - 동일 snapshotDate 기존 결과 삭제
+ * - 같은 기준으로 raw 결과 전체 재적재
+ *
+ * 목적:
+ * - 재실행 시에도 결과를 안정적으로 덮어써 멱등성을 보장한다.
+ */
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class BuildRawWeeklyIndexTasklet implements Tasklet {
+
+    private static final String DELETE_SQL_PATH = "sql/index/delete_raw_snapshot.sql";
+    private static final String INSERT_SQL_PATH = "sql/index/insert_raw_snapshot.sql";
+
+    private final NamedParameterJdbcTemplate namedParameterJdbcTemplate;
+    private final SqlFileLoader sqlFileLoader;
+
+    @Override
+    public RepeatStatus execute(StepContribution contribution, ChunkContext chunkContext) {
+        // 1) Gate Step에서 저장한 기준 값을 읽는다.
+        String snapshotDate = chunkContext.getStepContext()
+                .getStepExecution()
+                .getJobExecution()
+                .getExecutionContext()
+                .getString("snapshotDate");
+
+        String yyyymm = chunkContext.getStepContext()
+                .getStepExecution()
+                .getJobExecution()
+                .getExecutionContext()
+                .getString("yyyymm");
+
+        // 2) SQL 파라미터를 구성한다.
+        MapSqlParameterSource params = new MapSqlParameterSource()
+                .addValue("snapshotDate", snapshotDate)
+                .addValue("yyyymm", yyyymm);
+
+        // 3) 클래스패스 SQL 파일을 읽는다.
+        String deleteSql = sqlFileLoader.load(DELETE_SQL_PATH);
+        String insertSql = sqlFileLoader.load(INSERT_SQL_PATH);
+
+        // 4) 기존 데이터 삭제 후 재계산 결과를 적재한다.
+        int deleted = namedParameterJdbcTemplate.update(deleteSql, params);
+        int inserted = namedParameterJdbcTemplate.update(insertSql, params);
+
+        /*log.info("BuildRaw 완료. snapshotDate={}, yyyymm={}, deleted={}, inserted={}",
+                snapshotDate, yyyymm, deleted, inserted);*/
+
+        return RepeatStatus.FINISHED;
+    }
+}

src/main/java/site/holliverse/worker/batch/jobs/index/tasklet/BuildTScoreWeeklyIndexTasklet.java

@@ -0,0 +1,58 @@
+package site.holliverse.worker.batch.jobs.index.tasklet;
+
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.batch.core.StepContribution;
+import org.springframework.batch.core.scope.context.ChunkContext;
+import org.springframework.batch.core.step.tasklet.Tasklet;
+import org.springframework.batch.repeat.RepeatStatus;
+import org.springframework.jdbc.core.namedparam.MapSqlParameterSource;
+import org.springframework.jdbc.core.namedparam.NamedParameterJdbcTemplate;
+import org.springframework.stereotype.Component;
+import site.holliverse.worker.batch.common.support.SqlFileLoader;
+
+/**
+ * T-score 스냅샷을 생성하는 Step.
+ *
+ * 처리 방식:
+ * - 동일 snapshotDate 기존 tscore 결과 삭제
+ * - raw 분포(avg/stddev) 기반으로 tscore 재계산 후 적재
+ */
+@Component
+@RequiredArgsConstructor
+@Slf4j
+public class BuildTScoreWeeklyIndexTasklet implements Tasklet {
+
+    private static final String DELETE_SQL_PATH = "sql/index/delete_tscore_snapshot.sql";
+    private static final String INSERT_SQL_PATH = "sql/index/insert_tscore_snapshot.sql";
+
+    private final NamedParameterJdbcTemplate namedParameterJdbcTemplate;
+    private final SqlFileLoader sqlFileLoader;
+
+    @Override
+    public RepeatStatus execute(StepContribution contribution, ChunkContext chunkContext) {
+        // 1) 현재 스냅샷 날짜를 컨텍스트에서 읽는다.
+        String snapshotDate = chunkContext.getStepContext()
+                .getStepExecution()
+                .getJobExecution()
+                .getExecutionContext()
+                .getString("snapshotDate");
+
+        // 2) SQL 파라미터를 구성한다.
+        MapSqlParameterSource params = new MapSqlParameterSource()
+                .addValue("snapshotDate", snapshotDate);
+
+        // 3) SQL 파일을 로드한다.
+        String deleteSql = sqlFileLoader.load(DELETE_SQL_PATH);
+        String insertSql = sqlFileLoader.load(INSERT_SQL_PATH);
+
+        // 4) 기존 결과를 초기화하고 새 결과를 적재한다.
+        int deleted = namedParameterJdbcTemplate.update(deleteSql, params);
+        int inserted = namedParameterJdbcTemplate.update(insertSql, params);
+
+        /*log.info("BuildTScore 완료. snapshotDate={}, deleted={}, inserted={}",
+                snapshotDate, deleted, inserted);*/
+
+        return RepeatStatus.FINISHED;
+    }
+}