Feature/analytics event logging

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

@@ -0,0 +1,81 @@
+package com.ject.vs.analytics;
+
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 행동 로그 한 건을 표현하는 값 객체. 이벤트 이름과 이벤트별 로그 변수를 담는다.
+ *
+ * <p>공통 로그 변수(user_id / anonymous_id / is_member / platform / occurred_at)는
+ * {@link AnalyticsEventLogger#log(AnalyticsEvent)} 시점에 채워지므로 여기서는 다루지 않는다.
+ *
+ * <p>로거에 의존하지 않는 순수 값 객체이므로, 로거를 목(mock)으로 주입한 테스트에서도
+ * {@code log(...)} 가 no-op이 되어 NPE 없이 안전하다.
+ *
+ * <pre>{@code
+ * analytics.log(AnalyticsEvent.of("vote_detail_viewed")
+ *         .put("vote_id", voteId)
+ *         .put("vote_status", status));
+ * }</pre>
+ */
+public final class AnalyticsEvent {
+
+    private final String name;
+    private final Map<String, Object> properties = new LinkedHashMap<>();
+    private Long userId;
+    private boolean userIdOverridden;
+    private String anonymousId;
+    private boolean anonymousIdOverridden;
+
+    private AnalyticsEvent(String name) {
+        this.name = name;
+    }
+
+    public static AnalyticsEvent of(String name) {
+        return new AnalyticsEvent(name);
+    }
+
+    /** 이벤트별 로그 변수 추가. null 값도 그대로 기록한다. */
+    public AnalyticsEvent put(String key, Object value) {
+        properties.put(key, value);
+        return this;
+    }
+
+    /** SecurityContext에서 user_id를 얻을 수 없는 흐름(예: OAuth 로그인 성공 핸들러)에서 직접 지정. */
+    public AnalyticsEvent userId(Long userId) {
+        this.userId = userId;
+        this.userIdOverridden = true;
+        return this;
+    }
+
+    /** 컨트롤러가 이미 보유한 anonymous_id를 직접 지정(쿠키 재파싱 생략). */
+    public AnalyticsEvent anonymousId(String anonymousId) {
+        this.anonymousId = anonymousId;
+        this.anonymousIdOverridden = true;
+        return this;
+    }
+
+    String name() {
+        return name;
+    }
+
+    Map<String, Object> properties() {
+        return properties;
+    }
+
+    boolean userIdOverridden() {
+        return userIdOverridden;
+    }
+
+    Long userId() {
+        return userId;
+    }
+
+    boolean anonymousIdOverridden() {
+        return anonymousIdOverridden;
+    }
+
+    String anonymousId() {
+        return anonymousId;
+    }
+}

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

@@ -0,0 +1,110 @@
+package com.ject.vs.analytics;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.servlet.http.Cookie;
+import jakarta.servlet.http.HttpServletRequest;
+import lombok.RequiredArgsConstructor;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.context.SecurityContextHolder;
+import org.springframework.stereotype.Component;
+import org.springframework.web.context.request.RequestContextHolder;
+import org.springframework.web.context.request.ServletRequestAttributes;
+
+import java.time.Clock;
+import java.time.Instant;
+import java.util.Arrays;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/**
+ * 행동 로그(analytics event)를 구조화된 JSON 한 줄로 남기는 컴포넌트.
+ *
+ * <p>공통 로그 변수(user_id / anonymous_id / is_member / platform / occurred_at)는
+ * 현재 HTTP 요청 컨텍스트에서 자동으로 채워진다. 이벤트별 변수는 {@link AnalyticsEvent}로 전달한다.
+ *
+ * <pre>{@code
+ * analytics.log(AnalyticsEvent.of("vote_detail_viewed")
+ *         .put("vote_id", voteId)
+ *         .put("vote_status", status));
+ * }</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;
+
+    public void log(AnalyticsEvent event) {
+        try {
+            HttpServletRequest request = currentRequest();
+
+            Long userId = event.userIdOverridden() ? event.userId() : resolveUserId();
+            String anonymousId = event.anonymousIdOverridden()
+                    ? 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());
+
+            AnalyticsEventLogger.log.info(objectMapper.writeValueAsString(payload));
+        } catch (Exception e) {
+            // 로깅 실패가 요청 처리에 영향을 주지 않도록 흡수
+            AnalyticsEventLogger.log.warn("analytics event logging failed for '{}': {}", event.name(), e.getMessage());
+        }
+    }
+
+    private HttpServletRequest currentRequest() {
+        var attributes = RequestContextHolder.getRequestAttributes();
+        if (attributes instanceof ServletRequestAttributes servletAttributes) {
+            return servletAttributes.getRequest();
+        }
+        return null;
+    }
+
+    private Long resolveUserId() {
+        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+        if (authentication == null) return null;
+        Object principal = authentication.getPrincipal();
+        return (principal instanceof Long userId) ? userId : null;
+    }
+
+    private String resolveAnonymousId(HttpServletRequest request) {
+        if (request == null || request.getCookies() == null) return null;
+        return Arrays.stream(request.getCookies())
+                .filter(c -> ANONYMOUS_COOKIE.equals(c.getName()))
+                .map(Cookie::getValue)
+                .findFirst()
+                .orElse(null);
+    }
+
+    /** User-Agent 기반 플랫폼 분류: ios / android / web. */
+    private String resolvePlatform(HttpServletRequest request) {
+        if (request == null) return "unknown";
+        String ua = request.getHeader("User-Agent");
+        if (ua == null || ua.isBlank()) return "unknown";
+        String lower = ua.toLowerCase();
+        if (lower.contains("android")) return "android";
+        if (lower.contains("iphone") || lower.contains("ipad") || lower.contains("ios")
+                || lower.contains("cfnetwork") || lower.contains("darwin")) {
+            return "ios";
+        }
+        return "web";
+    }
+}

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

@@ -0,0 +1,40 @@
+package com.ject.vs.analytics;
+
+import com.ject.vs.config.UtmCookie;
+import com.ject.vs.user.domain.UtmAttribution;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import lombok.RequiredArgsConstructor;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+
+/**
+ * 유입 추적 엔드포인트.
+ *
+ * <p>UTM 파라미터는 프론트 SPA URL(예: {@code /vote/123?utm_source=instagram})에 붙어 들어오므로
+ * 백엔드는 직접 볼 수 없다. 프론트가 랜딩 시 이 엔드포인트를 1회 호출해 UTM을 넘겨주면,
+ * 백엔드는 first-touch 출처를 쿠키에 박제하고 이후 가입 완료 시 users 테이블에 기록한다.
+ */
+@RestController
+@RequestMapping("/api/track")
+@RequiredArgsConstructor
+public class TrackingController {
+
+    private final UtmCookie utmCookie;
+
+    @GetMapping("/visit")
+    public ResponseEntity<Void> visit(
+            @RequestParam(value = "utm_source", required = false) String source,
+            @RequestParam(value = "utm_medium", required = false) String medium,
+            @RequestParam(value = "utm_campaign", required = false) String campaign,
+            @RequestParam(value = "utm_content", required = false) String content,
+            HttpServletRequest request,
+            HttpServletResponse response) {
+
+        utmCookie.writeFirstTouch(request, response, UtmAttribution.of(source, medium, campaign, content));
+        return ResponseEntity.noContent().build();
+    }
+}

src/main/java/com/ject/vs/auth/port/AuthService.java

@@ -11,6 +11,7 @@
 import com.ject.vs.common.exception.BusinessException;
 import com.ject.vs.user.domain.User;
 import com.ject.vs.user.domain.UserRepository;
+import com.ject.vs.user.domain.UtmAttribution;
 import com.ject.vs.user.exception.UserErrorCode;
 import com.ject.vs.user.port.UserService;
 import com.ject.vs.util.JwtProvider;
@@ -32,7 +33,11 @@ public class AuthService {
     private final JwtProvider jwtProvider;
 
     public LoginTokenResponse socialLogin(String email) {
-        User user = userService.findOrCreate(email);
+        return socialLogin(email, UtmAttribution.empty());
+    }
+
+    public LoginTokenResponse socialLogin(String email, UtmAttribution utm) {
+        User user = userService.findOrCreate(email, utm);
 
         TokenInfo accessTokenInfo = jwtProvider.createAccessToken(user.getId());
         TokenInfo refreshTokenInfo = jwtProvider.createRefreshToken(user.getId());

src/main/java/com/ject/vs/chat/adapter/event/ChatMessageEventListener.java

@@ -45,6 +45,7 @@ public void handle(ChatMessageSentEvent event) {
                 sender.getNickname(),
                 sender.getImageColor(),
                 voteOptionCode,
+                false,
                 false
         );
 

src/main/java/com/ject/vs/chat/adapter/web/ChatController.java

@@ -1,5 +1,7 @@
 package com.ject.vs.chat.adapter.web;
 
+import com.ject.vs.analytics.AnalyticsEvent;
+import com.ject.vs.analytics.AnalyticsEventLogger;
 import com.ject.vs.chat.adapter.web.dto.*;
 import com.ject.vs.chat.port.in.*;
 import com.ject.vs.chat.port.in.dto.*;
@@ -10,30 +12,51 @@
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.web.bind.annotation.*;
 
+import java.util.List;
+
 @RestController
 @RequestMapping("/api/chats")
 @RequiredArgsConstructor
 public class ChatController implements ChatDocs {
 
     private final ChatQueryUseCase chatQueryUseCase;
     private final ChatCommandUseCase chatCommandUseCase;
+    private final AnalyticsEventLogger analytics;
 
     @GetMapping
     @Override
     public ChatListResponse getChatList(@AuthenticationPrincipal Long userId,
                                         @RequestParam VoteStatus status) {
-        return new ChatListResponse(
-                chatQueryUseCase.getChatList(userId, status).stream()
-                        .map(ChatListItemResponse::from)
-                        .toList()
-        );
+        List<ChatListItemResponse> chats = chatQueryUseCase.getChatList(userId, status).stream()
+                .map(ChatListItemResponse::from)
+                .toList();
+
+        // unread_total_count: 각 채팅방의 안 읽은 메시지 수를 서버에서 합산(SUM)
+        long unreadTotalCount = chats.stream()
+                .mapToLong(ChatListItemResponse::unreadCount)
+                .sum();
+
+        analytics.log(AnalyticsEvent.of("chat_list_viewed")
+                .put("status", status)
+                .put("chat_count", chats.size())
+                .put("unread_total_count", unreadTotalCount));
+
+        return new ChatListResponse(chats);
     }
 
     @GetMapping("/{voteId}")
     @Override
     public ChatRoomResponse getChatRoom(@AuthenticationPrincipal Long userId,
                                         @PathVariable Long voteId) {
-        return ChatRoomResponse.from(chatQueryUseCase.getChatRoom(voteId));
+        ChatRoomResponse response = ChatRoomResponse.from(chatQueryUseCase.getChatRoom(voteId));
+
+        analytics.log(AnalyticsEvent.of("chat_room_entered")
+                .put("vote_id", response.voteId())
+                .put("vote_status", response.status())
+                .put("participant_count", response.participantCount())
+                .put("end_at", response.endAt()));
+
+        return response;
     }
 
     @GetMapping("/{voteId}/gauge")
@@ -48,7 +71,15 @@ public MessagePageResponse getMessages(@PathVariable Long voteId,
                                            @AuthenticationPrincipal Long userId,
                                            @RequestParam(required = false) Long cursor,
                                            @RequestParam(defaultValue = "30") int size) {
-        return MessagePageResponse.from(chatQueryUseCase.getMessages(voteId, userId, cursor, size));
+        MessagePageResponse response = MessagePageResponse.from(chatQueryUseCase.getMessages(voteId, userId, cursor, size));
+
+        analytics.log(AnalyticsEvent.of("chat_messages_viewed")
+                .put("vote_id", voteId)
+                .put("message_count", response.messages().size())
+                .put("next_cursor", response.nextCursor())
+                .put("has_next", response.hasNext()));
+
+        return response;
     }
 
     @PostMapping("/{voteId}/messages")
@@ -58,7 +89,17 @@ public MessageResponse sendMessage(@PathVariable Long voteId,
                                        @AuthenticationPrincipal Long userId,
                                        @RequestBody @Valid SendMessageRequest request) {
         SendMessageCommand command = new SendMessageCommand(voteId, userId, request.content());
-        return MessageResponse.from(chatCommandUseCase.sendMessage(command));
+        MessageResult result = chatCommandUseCase.sendMessage(command);
+
+        analytics.log(AnalyticsEvent.of("chat_message_sent")
+                .put("vote_id", voteId)
+                .put("message_id", result.messageId())
+                .put("message_length", request.content() != null ? request.content().length() : 0)
+                .put("sender_vote_option", result.senderVoteOption())
+                .put("is_mine", result.isMine())
+                .put("is_first_message", result.isFirstMessage()));
+
+        return MessageResponse.from(result);
     }
 
     @PostMapping("/{voteId}/read")
@@ -68,5 +109,9 @@ public void markAsRead(@PathVariable Long voteId,
                            @AuthenticationPrincipal Long userId,
                            @RequestBody @Valid MarkAsReadRequest request) {
         chatCommandUseCase.markAsRead(new MarkAsReadCommand(voteId, userId, request.lastReadMessageId()));
+
+        analytics.log(AnalyticsEvent.of("chat_read_updated")
+                .put("vote_id", voteId)
+                .put("last_read_message_id", request.lastReadMessageId()));
     }
 }