Merge pull request #235 from JECT-Study/feature/analytics-events-db

feat: 행동 로그를 analytics_events 테이블에 적재 + 유입 전환율 추적

Author: Junhyukkkk

src/integrationTest/java/com/ject/vs/analytics/AnalyticsEventLoggerIntegrationTest.java

@@ -0,0 +1,64 @@
+package com.ject.vs.analytics;
+
+import com.ject.vs.support.BaseIntegrationTest;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * 행동 로그가 실제 PostgreSQL(analytics_events 테이블)에 한 행으로 적재되는지 검증한다.
+ *
+ * <p>V15 마이그레이션 적용 → 엔티티 매핑 → INSERT 까지 실제 DB로 확인한다.
+ * 적재 실패는 {@link AnalyticsEventLogger}가 예외를 삼키므로, 행이 안 생기는 것으로 드러난다.
+ */
+class AnalyticsEventLoggerIntegrationTest extends BaseIntegrationTest {
+
+    @Autowired
+    private AnalyticsEventLogger analytics;
+
+    @Autowired
+    private AnalyticsEventRepository analyticsEventRepository;
+
+    @Test
+    void 비회원_이벤트는_properties_JSON과_함께_한_행으로_저장된다() {
+        analytics.log(AnalyticsEvent.of("landing_visited")
+                .put("utm_source", "instagram")
+                .put("utm_campaign", "tangsuyuk"));
+
+        List<AnalyticsEventRecord> rows = analyticsEventRepository.findAll();
+        assertThat(rows).hasSize(1);
+
+        AnalyticsEventRecord row = rows.get(0);
+        assertThat(row.getEvent()).isEqualTo("landing_visited");
+        assertThat(row.isMember()).isFalse();
+        assertThat(row.getUserId()).isNull();
+        assertThat(row.getOccurredAt()).isEqualTo(FIXED_NOW);
+        assertThat(row.getProperties())
+                .contains("\"utm_source\":\"instagram\"")
+                .contains("\"utm_campaign\":\"tangsuyuk\"");
+    }
+
+    @Test
+    void userId가_지정되면_회원으로_저장된다() {
+        analytics.log(AnalyticsEvent.of("signup_completed")
+                .userId(1024L)
+                .put("method", "kakao"));
+
+        AnalyticsEventRecord row = analyticsEventRepository.findAll().get(0);
+        assertThat(row.getUserId()).isEqualTo(1024L);
+        assertThat(row.isMember()).isTrue();
+        assertThat(row.getProperties()).contains("\"method\":\"kakao\"");
+    }
+
+    @Test
+    void 속성이_없으면_properties는_null로_저장된다() {
+        analytics.log(AnalyticsEvent.of("simple_event"));
+
+        AnalyticsEventRecord row = analyticsEventRepository.findAll().get(0);
+        assertThat(row.getEvent()).isEqualTo("simple_event");
+        assertThat(row.getProperties()).isNull();
+    }
+}

src/integrationTest/java/com/ject/vs/support/BaseIntegrationTest.java

@@ -9,8 +9,6 @@
 import org.springframework.test.context.bean.override.mockito.MockitoBean;
 import org.springframework.transaction.annotation.Transactional;
 import org.testcontainers.containers.PostgreSQLContainer;
-import org.testcontainers.junit.jupiter.Container;
-import org.testcontainers.junit.jupiter.Testcontainers;
 
 import java.time.Clock;
 import java.time.Instant;
@@ -22,23 +20,32 @@
  * Integration Test의 공통 설정을 담당하는 추상 클래스.
  *
  * 통합 테스트는 Testcontainers 기반 실제 PostgreSQL 위에서 실행됩니다.
+ *
+ * <p>컨테이너는 JUnit({@code @Testcontainers}) 라이프사이클에 맡기지 않고
+ * 정적 초기화 블록에서 한 번만 시작하는 싱글톤 패턴을 사용합니다.
+ * Spring이 ApplicationContext를 캐싱해 여러 테스트 클래스에 재사용하는데,
+ * 클래스 단위로 컨테이너를 내리면 캐시된 컨텍스트가 이미 중지된 컨테이너를
+ * 가리켜 {@code ConnectException}이 발생하기 때문입니다. 한 번 시작한 컨테이너는
+ * JVM 종료 시 Ryuk가 정리합니다.
  */
 @SpringBootTest
 @ActiveProfiles("test")
 @Transactional
-@Testcontainers(disabledWithoutDocker = true)
 public abstract class BaseIntegrationTest {
 
     protected static final Instant FIXED_NOW = Instant.parse("2025-06-01T12:00:00Z");
 
-    @Container
     @ServiceConnection
     static final PostgreSQLContainer<?> POSTGRES =
             new PostgreSQLContainer<>("postgres:16-alpine")
                     .withDatabaseName("vs_integration_test")
                     .withUsername("test")
                     .withPassword("test");
 
+    static {
+        POSTGRES.start();
+    }
+
     @Autowired
     protected EntityManager entityManager;
 

src/main/java/com/ject/vs/analytics/AnalyticsEventLogger.java

@@ -15,14 +15,13 @@
 import java.time.Clock;
 import java.time.Instant;
 import java.util.Arrays;
-import java.util.LinkedHashMap;
-import java.util.Map;
 
 /**
- * 행동 로그(analytics event)를 구조화된 JSON 한 줄로 남기는 컴포넌트.
+ * 행동 로그(analytics event)를 RDB(analytics_events 테이블)에 한 건씩 적재하는 컴포넌트.
  *
  * <p>공통 로그 변수(user_id / anonymous_id / is_member / platform / occurred_at)는
- * 현재 HTTP 요청 컨텍스트에서 자동으로 채워진다. 이벤트별 변수는 {@link AnalyticsEvent}로 전달한다.
+ * 현재 HTTP 요청 컨텍스트에서 자동으로 채워지고, 이벤트별 가변 변수는 JSON 문자열로
+ * 직렬화해 properties 컬럼에 담는다. 이벤트별 변수는 {@link AnalyticsEvent}로 전달한다.
  *
  * <pre>{@code
  * analytics.log(AnalyticsEvent.of("vote_detail_viewed")
@@ -31,19 +30,20 @@
  * }</pre>
  *
  * <p>유일한 진입점이 void {@code log(AnalyticsEvent)}이므로 테스트에서 목(mock)으로 주입해도
- * 부수효과 없이 동작한다. 로그 적재 실패가 비즈니스 로직에 영향을 주지 않도록 모든 예외를 삼킨다.
+ * 부수효과 없이 동작한다. 적재 실패가 비즈니스 로직에 영향을 주지 않도록 모든 예외를 삼킨다.
  */
 @Component
 @RequiredArgsConstructor
 public class AnalyticsEventLogger {
 
-    /** 별도 로거 이름으로 분리하여 수집/필터링이 쉽도록 한다. */
+    /** 적재 실패 경고 등 내부 진단용 로거. */
     private static final Logger log = LoggerFactory.getLogger("analytics");
 
     private static final String ANONYMOUS_COOKIE = "anonymous_id";
 
     private final ObjectMapper objectMapper;
     private final Clock clock;
+    private final AnalyticsEventRepository analyticsEventRepository;
 
     public void log(AnalyticsEvent event) {
         try {
@@ -54,16 +54,19 @@ public void log(AnalyticsEvent event) {
                     ? event.anonymousId()
                     : resolveAnonymousId(request);
 
-            Map<String, Object> payload = new LinkedHashMap<>();
-            payload.put("event", event.name());
-            payload.put("user_id", userId);
-            payload.put("anonymous_id", anonymousId);
-            payload.put("is_member", userId != null);
-            payload.put("platform", resolvePlatform(request));
-            payload.put("occurred_at", Instant.now(clock).toString());
-            payload.putAll(event.properties());
+            // 이벤트별 가변 속성은 JSON 문자열로 직렬화해 properties 컬럼에 담는다.
+            String properties = event.properties().isEmpty()
+                    ? null
+                    : objectMapper.writeValueAsString(event.properties());
 
-            AnalyticsEventLogger.log.info(objectMapper.writeValueAsString(payload));
+            analyticsEventRepository.save(new AnalyticsEventRecord(
+                    event.name(),
+                    userId,
+                    anonymousId,
+                    userId != null,
+                    resolvePlatform(request),
+                    Instant.now(clock),
+                    properties));
         } catch (Exception e) {
             // 로깅 실패가 요청 처리에 영향을 주지 않도록 흡수
             AnalyticsEventLogger.log.warn("analytics event logging failed for '{}': {}", event.name(), e.getMessage());

src/main/java/com/ject/vs/analytics/AnalyticsEventRecord.java

@@ -0,0 +1,62 @@
+package com.ject.vs.analytics;
+
+import jakarta.persistence.Column;
+import jakarta.persistence.Entity;
+import jakarta.persistence.GeneratedValue;
+import jakarta.persistence.GenerationType;
+import jakarta.persistence.Id;
+import jakarta.persistence.Table;
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+
+import java.time.Instant;
+
+/**
+ * 행동 로그 한 건을 RDB(analytics_events)에 적재하기 위한 엔티티.
+ *
+ * <p>공통 필드는 컬럼으로, 이벤트별 가변 속성은 {@code properties}(JSON 문자열)에 담는다.
+ * 마이그레이션 {@code V15__add_analytics_events.sql} 과 1:1로 대응한다.
+ */
+@Entity
+@Table(name = "analytics_events")
+@Getter
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class AnalyticsEventRecord {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @Column(nullable = false, length = 100)
+    private String event;
+
+    private Long userId;
+
+    @Column(length = 64)
+    private String anonymousId;
+
+    @Column(name = "is_member", nullable = false)
+    private boolean member;
+
+    @Column(length = 20)
+    private String platform;
+
+    @Column(nullable = false)
+    private Instant occurredAt;
+
+    /** 이벤트별 속성을 직렬화한 JSON 문자열. 속성이 없으면 null. */
+    @Column(columnDefinition = "text")
+    private String properties;
+
+    public AnalyticsEventRecord(String event, Long userId, String anonymousId,
+                                boolean member, String platform, Instant occurredAt, String properties) {
+        this.event = event;
+        this.userId = userId;
+        this.anonymousId = anonymousId;
+        this.member = member;
+        this.platform = platform;
+        this.occurredAt = occurredAt;
+        this.properties = properties;
+    }
+}

src/main/java/com/ject/vs/analytics/AnalyticsEventRepository.java

@@ -0,0 +1,6 @@
+package com.ject.vs.analytics;
+
+import org.springframework.data.jpa.repository.JpaRepository;
+
+public interface AnalyticsEventRepository extends JpaRepository<AnalyticsEventRecord, Long> {
+}

src/main/java/com/ject/vs/analytics/TrackingController.java

@@ -24,6 +24,7 @@
 public class TrackingController {
 
     private final UtmCookie utmCookie;
+    private final AnalyticsEventLogger analytics;
 
     @GetMapping("/visit")
     public ResponseEntity<Void> visit(
@@ -34,7 +35,16 @@ public ResponseEntity<Void> visit(
             HttpServletRequest request,
             HttpServletResponse response) {
 
-        utmCookie.writeFirstTouch(request, response, UtmAttribution.of(source, medium, campaign, content));
+        UtmAttribution utm = UtmAttribution.of(source, medium, campaign, content);
+        utmCookie.writeFirstTouch(request, response, utm);
+
+        // 클릭(유입) 자체를 1건의 로그로 적재한다. signup_completed(가입)와 짝지어 전환율을 계산한다.
+        analytics.log(AnalyticsEvent.of("landing_visited")
+                .put("utm_source", utm.source())
+                .put("utm_medium", utm.medium())
+                .put("utm_campaign", utm.campaign())
+                .put("utm_content", utm.content()));
+
         return ResponseEntity.noContent().build();
     }
 }

src/main/resources/db/migration/V15__add_analytics_events.sql

@@ -0,0 +1,19 @@
+-- 행동 로그(analytics event)를 RDB에 직접 적재하기 위한 append-only 테이블.
+-- 공통 필드(event/user_id/anonymous_id/is_member/platform/occurred_at)는 컬럼으로,
+-- 이벤트마다 달라지는 속성은 properties(JSON 문자열)에 담는다.
+-- user_id는 비회원이면 null이며, 로그 적재가 users 존재에 묶이지 않도록 FK를 두지 않는다.
+CREATE TABLE analytics_events (
+    id           BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
+    event        VARCHAR(100) NOT NULL,
+    user_id      BIGINT,
+    anonymous_id VARCHAR(64),
+    is_member    BOOLEAN NOT NULL,
+    platform     VARCHAR(20),
+    occurred_at  TIMESTAMP NOT NULL,
+    properties   TEXT
+);
+
+-- 이벤트별 기간 집계(event 카운트, 전환율 등)에 사용.
+CREATE INDEX idx_analytics_event_time ON analytics_events (event, occurred_at);
+-- 전체 기간 스캔용.
+CREATE INDEX idx_analytics_time ON analytics_events (occurred_at);