[Feat]#19 트래킹 GPS

AGENTS.md

@@ -0,0 +1,42 @@
+# AGENTS.md
+
+## Communication
+- Always reply in Korean unless the user explicitly asks for another language.
+- Keep answers direct and practical. Avoid repeating the same explanation after the user has already acknowledged it.
+- When the user asks "확인해줘", "봐줘", "어떻게 돼", "뭐가 문제야", or similar, treat it as analysis-only unless they explicitly ask for code changes.
+- Do not edit files unless the user clearly says something like "수정해줘", "고쳐줘", "반영해줘", "만들어줘", "추가해줘", or "삭제해줘".
+- If a fix is likely, explain the cause, affected files, and proposed patch first. Wait for explicit approval before applying it.
+- If you accidentally changed code without approval, say exactly which files changed and offer to revert only your own changes.
+
+## User Preferences
+- The user wants investigation before implementation.
+- The user dislikes unrequested code edits.
+- The user prefers concrete answers based on the current codebase, not generic guesses.
+- When diagnosing backend/frontend integration issues, clearly separate:
+  - what the backend currently expects
+  - what the frontend must send
+  - what environment/config values must match
+  - what is only an assumption
+- If sensitive values such as secrets, tokens, DB passwords, or JWT secrets appear in screenshots or logs, warn briefly and recommend rotation if they may have been shared.
+
+## Project
+- This is a Spring Boot backend project.
+- Use Java 21 and Gradle.
+- Follow the existing package structure, naming, and style.
+- Prefer existing services, repositories, DTOs, and response conventions over introducing new abstractions.
+
+## Commands
+- Use `rg` first for searching.
+- Run focused tests before broad tests when checking a narrow change.
+- Common commands:
+  - `./gradlew test --tests <fully.qualified.TestClass>`
+  - `./gradlew test`
+  - `./gradlew build`
+- If full tests fail because local infrastructure such as PostgreSQL or Redis is unavailable, report that clearly and distinguish it from failures caused by the code change.
+
+## Editing Rules
+- Never revert or overwrite user changes unless explicitly requested.
+- Keep changes narrowly scoped to the requested task.
+- Do not commit secrets, environment values, generated local files, or unrelated formatting churn.
+- Before editing, state what files will be touched and why.
+- After editing, summarize the exact files changed and verification performed.

build.gradle

@@ -53,9 +53,13 @@ dependencies {
 	// PostGIS (Hibernate Spatial + JTS)
 	implementation 'org.hibernate.orm:hibernate-spatial'
 
+	// WebSocket (트래킹 GPS 실시간 수집 — STOMP)
+	implementation 'org.springframework.boot:spring-boot-starter-websocket'
+
 	// Flyway
 	implementation 'org.flywaydb:flyway-core'
 	implementation 'org.flywaydb:flyway-database-postgresql'
+
 }
 
 jar { enabled = false }

k8s/kustomization.yaml

@@ -14,4 +14,4 @@ resources:
   - minio/service.yaml
 images:
   - name: ghcr.io/semosan/semosan_be
-    newTag: fb0eb2823ad7e4ee955bd3941443be46e88a22cf
+    newTag: 2408eb0c0f5fc413f174a8745cfd08f32d7a88ce

k8s/postgres/deployment.yaml

@@ -15,7 +15,7 @@ spec:
     spec:
       containers:
         - name: postgres
-          image: postgres:16-alpine
+          image: imresamu/postgis:16-3.4
           ports:
             - containerPort: 5432
           envFrom:
@@ -28,4 +28,4 @@ spec:
       volumes:
         - name: postgres-data
           persistentVolumeClaim:
-            claimName: postgres-pvc
+            claimName: postgres-pvc

src/main/java/com/semosan/api/common/config/SecurityConfig.java

@@ -49,6 +49,15 @@ public class SecurityConfig {
             "/api/auth/token/reissue"
     };
 
+    /**
+     * WebSocket(STOMP) 엔드포인트.
+     * 핸드셰이크는 HTTP JWT 필터로 인증하지 않고 통과시키고,
+     * STOMP CONNECT 프레임에서 StompAuthChannelInterceptor 가 JWT 를 검증한다.
+     */
+    public static final String[] WEBSOCKET_URIS = {
+            "/ws/tracking/**"
+    };
+
     @Bean
     public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
         http
@@ -63,6 +72,7 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Excepti
                         .requestMatchers(SWAGGER_URIS).permitAll()
                         .requestMatchers(OAUTH_URIS).permitAll()
                         .requestMatchers(AUTH_URIS).permitAll()
+                        .requestMatchers(WEBSOCKET_URIS).permitAll()
                         .anyRequest().authenticated()
                 )
                 .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class);
@@ -78,7 +88,17 @@ public CorsConfigurationSource corsConfigurationSource() {
         config.setAllowedHeaders(List.of("*"));
         config.setAllowCredentials(true);
 
+        // WebSocket(STOMP) 핸드셰이크는 다양한 origin(모바일/로컬 테스트 페이지 등)에서 들어옴.
+        // /ws/** 만 별도 정책으로 풀어준다.
+        // TODO: production 에서는 모바일 앱 origin 만 명시적으로 허용하도록 좁힐 것.
+        CorsConfiguration wsConfig = new CorsConfiguration();
+        wsConfig.setAllowedOriginPatterns(List.of("*"));
+        wsConfig.setAllowedMethods(List.of("GET"));
+        wsConfig.setAllowedHeaders(List.of("*"));
+        wsConfig.setAllowCredentials(true);
+
         UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+        source.registerCorsConfiguration("/ws/**", wsConfig);
         source.registerCorsConfiguration("/**", config);
         return source;
     }

src/main/java/com/semosan/api/common/config/WebClientConfig.java

@@ -7,13 +7,6 @@
 @Configuration
 public class WebClientConfig {
 
-    @Bean
-    public WebClient kakaoAuthWebClient() {
-        return WebClient.builder()
-                .baseUrl("https://kauth.kakao.com")
-                .build();
-    }
-
     @Bean
     public WebClient kakaoApiWebClient() {
         return WebClient.builder()

src/main/java/com/semosan/api/common/exception/GeneralExceptionAdvice.java

@@ -55,16 +55,20 @@ public ResponseEntity<ApiResponse<Void>> handleConstraintViolation(
     }
 
     // Spring 6.1+ HandlerMethodValidationException (컨트롤러 메서드 파라미터 검증 실패 표준 경로)
-    @ExceptionHandler(HandlerMethodValidationException.class)
-    public ResponseEntity<ApiResponse<Void>> handleHandlerMethodValidation(
-            HandlerMethodValidationException e
+    @Override
+    protected ResponseEntity<Object> handleHandlerMethodValidationException(
+            HandlerMethodValidationException ex,
+            HttpHeaders headers,
+            HttpStatusCode status,
+            WebRequest request
     ) {
-        String message = e.getAllErrors().stream()
+        String message = ex.getAllErrors().stream()
                 .findFirst()
                 .map(error -> error.getDefaultMessage() != null ? error.getDefaultMessage() : ErrorStatus.BAD_REQUEST.getMessage())
                 .orElse(ErrorStatus.BAD_REQUEST.getMessage());
         log.warn("[*] HandlerMethodValidationException : {}", message);
-        return ApiResponse.error(ErrorStatus.BAD_REQUEST, message);
+        ApiResponse<Void> body = createApiResponse(ErrorStatus.BAD_REQUEST, message);
+        return handleExceptionInternal(ex, body, headers, status, request);
     }
 
     // null 참조로 발생한 서버 오류를 500 에러로 응답

src/main/java/com/semosan/api/domain/oauth/client/OAuthKakaoClient.java

@@ -3,15 +3,11 @@
 import com.semosan.api.common.exception.GeneralException;
 import com.semosan.api.domain.oauth.properties.KakaoProperties;
 import com.semosan.api.common.status.ErrorStatus;
-import com.semosan.api.domain.oauth.dto.KakaoTokenResponse;
 import com.semosan.api.domain.oauth.dto.KakaoUserInfoResponse;
 import lombok.RequiredArgsConstructor;
 import lombok.extern.slf4j.Slf4j;
 import org.springframework.http.HttpStatusCode;
 import org.springframework.stereotype.Component;
-import org.springframework.util.LinkedMultiValueMap;
-import org.springframework.util.MultiValueMap;
-import org.springframework.util.StringUtils;
 import org.springframework.web.reactive.function.BodyInserters;
 import org.springframework.web.reactive.function.client.WebClient;
 import org.springframework.web.reactive.function.client.WebClientResponseException;
@@ -22,44 +18,9 @@
 @RequiredArgsConstructor
 public class OAuthKakaoClient {
 
-    private final WebClient kakaoAuthWebClient;
     private final WebClient kakaoApiWebClient;
     private final KakaoProperties kakaoProperties;
 
-    // 인가 코드 -> 카카오 액세스 토큰
-    public KakaoTokenResponse getKakaoToken(String code) {
-        MultiValueMap<String, String> form = new LinkedMultiValueMap<>();
-        form.add("grant_type", "authorization_code");
-        form.add("client_id", kakaoProperties.clientId());
-        form.add("redirect_uri", kakaoProperties.redirectUri());
-        form.add("code", code);
-        if (StringUtils.hasText(kakaoProperties.clientSecret())) {
-            form.add("client_secret", kakaoProperties.clientSecret());
-        }
-
-        try {
-            KakaoTokenResponse response = kakaoAuthWebClient.post()
-                    .uri("/oauth/token")
-                    .body(BodyInserters.fromFormData(form))
-                    .retrieve()
-                    .onStatus(
-                            HttpStatusCode::isError,
-                            r -> r.bodyToMono(String.class)
-                                    .flatMap(body -> handleError(r.statusCode(), body, "토큰 발급"))
-                    )
-                    .bodyToMono(KakaoTokenResponse.class)
-                    .block();
-
-            if (response == null || !StringUtils.hasText(response.accessToken())) {
-                throw new GeneralException(ErrorStatus.KAKAO_TOKEN_REQUEST_FAILED);
-            }
-            return response;
-        } catch (WebClientResponseException e) {
-            log.error("[*] 카카오 토큰 발급 실패 status={}, body={}", e.getStatusCode(), e.getResponseBodyAsString());
-            throw new GeneralException(ErrorStatus.KAKAO_TOKEN_REQUEST_FAILED);
-        }
-    }
-
     // 카카오 액세스 토큰 -> 사용자 정보
     public KakaoUserInfoResponse getKakaoUserInfo(String kakaoAccessToken) {
         try {

src/main/java/com/semosan/api/domain/oauth/controller/docs/OAuthControllerDocs.java

@@ -18,7 +18,7 @@ public interface OAuthControllerDocs {
 
     @Operation(
             summary = "카카오 소셜 로그인",
-            description = "프론트엔드에서 전달받은 카카오 인가 코드(code)로 로그인 또는 회원가입을 처리하고 서비스 JWT를 발급합니다."
+            description = "프론트엔드에서 전달받은 카카오 액세스 토큰(accessToken)으로 로그인 또는 회원가입을 처리하고 서비스 JWT를 발급합니다."
     )
     @ApiResponses({
             @io.swagger.v3.oas.annotations.responses.ApiResponse(
@@ -28,7 +28,7 @@ public interface OAuthControllerDocs {
             ),
             @io.swagger.v3.oas.annotations.responses.ApiResponse(
                     responseCode = "400",
-                    description = "잘못된 요청 (인가 코드 또는 디바이스 타입 누락)",
+                    description = "잘못된 요청 (카카오 액세스 토큰 또는 디바이스 타입 누락)",
                     content = @Content(schema = @Schema(implementation = ApiResponse.class))
             ),
             @io.swagger.v3.oas.annotations.responses.ApiResponse(

src/main/java/com/semosan/api/domain/oauth/dto/request/OAuthKakaoLoginRequest.java

@@ -6,8 +6,8 @@
 
 public record OAuthKakaoLoginRequest(
 
-        @NotBlank(message = "인가 코드는 필수입니다.")
-        String code,
+        @NotBlank(message = "카카오 액세스 토큰은 필수입니다.")
+        String accessToken,
 
         @NotNull(message = "디바이스 타입은 필수입니다.")
         DeviceType deviceType

src/main/java/com/semosan/api/domain/oauth/service/OAuthService.java

@@ -4,7 +4,6 @@
 import com.semosan.api.common.jwt.TokenIssuance;
 import com.semosan.api.domain.oauth.client.OAuthAppleClient;
 import com.semosan.api.domain.oauth.client.OAuthKakaoClient;
-import com.semosan.api.domain.oauth.dto.KakaoTokenResponse;
 import com.semosan.api.domain.oauth.dto.KakaoUserInfoResponse;
 import com.semosan.api.domain.oauth.dto.request.OAuthAppleLoginRequest;
 import com.semosan.api.domain.oauth.dto.request.OAuthKakaoLoginRequest;
@@ -29,8 +28,7 @@ public class OAuthService {
 
     @Transactional
     public OAuthLoginResponse kakaoLogin(OAuthKakaoLoginRequest request) {
-        KakaoTokenResponse kakaoToken = oAuthKakaoClient.getKakaoToken(request.code());
-        KakaoUserInfoResponse userInfo = oAuthKakaoClient.getKakaoUserInfo(kakaoToken.accessToken());
+        KakaoUserInfoResponse userInfo = oAuthKakaoClient.getKakaoUserInfo(request.accessToken());
 
         // DTO 파싱은 oauth 레이어에서 처리 후 순수 값만 UserService로 전달
         KakaoUserInfoResponse.KakaoAccount account = userInfo.kakaoAccount();

src/main/java/com/semosan/api/domain/tracking/config/TrackingStreamListenerConfig.java

@@ -0,0 +1,75 @@
+package com.semosan.api.domain.tracking.config;
+
+import com.semosan.api.common.config.TrackingProperties;
+import com.semosan.api.domain.tracking.service.TrackingStreamConsumer;
+import jakarta.annotation.PreDestroy;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.beans.factory.InitializingBean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.data.redis.connection.RedisConnectionFactory;
+import org.springframework.data.redis.connection.stream.Consumer;
+import org.springframework.data.redis.connection.stream.MapRecord;
+import org.springframework.data.redis.connection.stream.ReadOffset;
+import org.springframework.data.redis.connection.stream.StreamOffset;
+import org.springframework.data.redis.stream.StreamMessageListenerContainer;
+
+import java.net.InetAddress;
+import java.net.UnknownHostException;
+import java.time.Duration;
+import java.util.UUID;
+
+/**
+ * Redis Stream(tracking:gps) 의 GPS 점을 소비하는 컨테이너를 부트업한다.
+ *  - Consumer group 자체는 RedisStreamConfig 에서 사전 생성됨.
+ *  - 본 클래스는 그룹의 이 인스턴스를 위한 consumer 등록 + listener container 시작.
+ *  - consumer 이름은 호스트명 + UUID prefix 로 인스턴스별 유일성 확보 (다중 인스턴스 대비).
+ */
+@Slf4j
+@Configuration
+@RequiredArgsConstructor
+public class TrackingStreamListenerConfig implements InitializingBean {
+
+    private final RedisConnectionFactory redisConnectionFactory;
+    private final TrackingProperties trackingProperties;
+    private final TrackingStreamConsumer trackingStreamConsumer;
+
+    private StreamMessageListenerContainer<String, MapRecord<String, String, String>> container;
+
+    @Override
+    public void afterPropertiesSet() {
+        var options = StreamMessageListenerContainer
+                .StreamMessageListenerContainerOptions.builder()
+                .pollTimeout(Duration.ofSeconds(1))
+                .build();
+
+        container = StreamMessageListenerContainer.create(redisConnectionFactory, options);
+
+        container.receiveAutoAck(
+                Consumer.from(trackingProperties.getConsumerGroup(), buildConsumerName()),
+                StreamOffset.create(trackingProperties.getStreamKey(), ReadOffset.lastConsumed()),
+                trackingStreamConsumer
+        );
+        container.start();
+        log.info("Started Redis Stream listener: stream={} group={}",
+                trackingProperties.getStreamKey(),
+                trackingProperties.getConsumerGroup());
+    }
+
+    @PreDestroy
+    public void stop() {
+        if (container != null) {
+            container.stop();
+        }
+    }
+
+    private static String buildConsumerName() {
+        String host;
+        try {
+            host = InetAddress.getLocalHost().getHostName();
+        } catch (UnknownHostException e) {
+            host = "unknown";
+        }
+        return host + "-" + UUID.randomUUID().toString().substring(0, 8);
+    }
+}