[Feat]#19 트래킹 GPS

build.gradle

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

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/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);
+    }
+}

src/main/java/com/semosan/api/domain/tracking/controller/TrackingGpsWebSocketController.java

@@ -0,0 +1,43 @@
+package com.semosan.api.domain.tracking.controller;
+
+import com.semosan.api.domain.tracking.dto.message.GpsPointMessage;
+import com.semosan.api.domain.tracking.service.TrackingGpsPublisher;
+import com.semosan.api.domain.tracking.websocket.UserIdPrincipal;
+import jakarta.validation.Valid;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.messaging.handler.annotation.DestinationVariable;
+import org.springframework.messaging.handler.annotation.MessageMapping;
+import org.springframework.messaging.handler.annotation.Payload;
+import org.springframework.stereotype.Controller;
+
+import java.security.Principal;
+
+/**
+ * 클라이언트 STOMP SEND: /app/tracking/{sessionId}/gps
+ * 인증된 사용자만 도달 (CONNECT 시 JWT 검증 완료). userId 는 Principal 에서 추출.
+ */
+@Slf4j
+@Controller
+@RequiredArgsConstructor
+public class TrackingGpsWebSocketController {
+
+    private final TrackingGpsPublisher trackingGpsPublisher;
+
+    @MessageMapping("/tracking/{sessionId}/gps")
+    public void receiveGps(
+            @DestinationVariable Long sessionId,
+            @Valid @Payload GpsPointMessage message,
+            Principal principal
+    ) {
+        Long userId = resolveUserId(principal);
+        trackingGpsPublisher.publish(userId, sessionId, message);
+    }
+
+    private Long resolveUserId(Principal principal) {
+        if (principal instanceof UserIdPrincipal userPrincipal) {
+            return userPrincipal.getUserId();
+        }
+        throw new IllegalStateException("Unauthenticated WebSocket message");
+    }
+}

src/main/java/com/semosan/api/domain/tracking/dto/message/GpsPointMessage.java

@@ -0,0 +1,24 @@
+package com.semosan.api.domain.tracking.dto.message;
+
+import jakarta.validation.constraints.NotNull;
+
+import java.time.LocalDateTime;
+
+/**
+ * 프론트 → 서버 (STOMP SEND /app/tracking/{sessionId}/gps).
+ * 좌표만 받는다 — 리버스 지오코딩 결과는 받지 않음.
+ */
+public record GpsPointMessage(
+        @NotNull(message = "위도(lat)는 필수입니다.")
+        Double lat,
+
+        @NotNull(message = "경도(lng)는 필수입니다.")
+        Double lng,
+
+        /** 디바이스가 보고한 고도(m). 일부 디바이스에서 누락 가능. */
+        Double altitude,
+
+        @NotNull(message = "측정 시각(recordedAt)은 필수입니다.")
+        LocalDateTime recordedAt
+) {
+}

src/main/java/com/semosan/api/domain/tracking/entity/TrackingPoint.java

@@ -0,0 +1,57 @@
+package com.semosan.api.domain.tracking.entity;
+
+import com.semosan.api.common.base.BaseEntity;
+import jakarta.persistence.*;
+import lombok.AccessLevel;
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import org.locationtech.jts.geom.Point;
+
+import java.time.LocalDateTime;
+
+@Table(
+        name = "tracking_points",
+        indexes = {
+                @Index(name = "idx_tracking_points_session_recorded", columnList = "tracking_session_id, recorded_at")
+        }
+)
+@Getter
+@Entity
+@Builder(access = AccessLevel.PROTECTED)
+@AllArgsConstructor(access = AccessLevel.PROTECTED)
+@NoArgsConstructor(access = AccessLevel.PROTECTED)
+public class TrackingPoint extends BaseEntity {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    @ManyToOne(fetch = FetchType.LAZY)
+    @JoinColumn(name = "tracking_session_id", nullable = false)
+    private TrackingSession trackingSession;
+
+    /**
+     * 좌표 (PostGIS geography(Point, 4326)).
+     * Haversine 직접 계산보다 ST_Distance(geography) 가 정확 (구 좌표계 기반).
+     */
+    @Column(name = "location", columnDefinition = "geography(Point, 4326)", nullable = false)
+    private Point location;
+
+    /** 디바이스가 보고한 고도(m). null 가능 — 일부 디바이스/실내에선 누락. */
+    @Column(name = "altitude")
+    private Double altitude;
+
+    @Column(name = "recorded_at", nullable = false)
+    private LocalDateTime recordedAt;
+
+    public static TrackingPoint create(TrackingSession session, Point location, Double altitude, LocalDateTime recordedAt) {
+        return TrackingPoint.builder()
+                .trackingSession(session)
+                .location(location)
+                .altitude(altitude)
+                .recordedAt(recordedAt)
+                .build();
+    }
+}

src/main/java/com/semosan/api/domain/tracking/repository/TrackingPointRepository.java

@@ -0,0 +1,11 @@
+package com.semosan.api.domain.tracking.repository;
+
+import com.semosan.api.domain.tracking.entity.TrackingPoint;
+import org.springframework.data.jpa.repository.JpaRepository;
+
+import java.util.List;
+
+public interface TrackingPointRepository extends JpaRepository<TrackingPoint, Long> {
+
+    List<TrackingPoint> findByTrackingSession_IdOrderByRecordedAtAsc(Long sessionId);
+}

src/main/java/com/semosan/api/domain/tracking/service/TrackingGpsPublisher.java

@@ -0,0 +1,65 @@
+package com.semosan.api.domain.tracking.service;
+
+import com.semosan.api.common.config.TrackingProperties;
+import com.semosan.api.common.exception.GeneralException;
+import com.semosan.api.common.status.ErrorStatus;
+import com.semosan.api.domain.tracking.dto.message.GpsPointMessage;
+import com.semosan.api.domain.tracking.entity.TrackingSession;
+import com.semosan.api.domain.tracking.enums.TrackingSessionStatus;
+import com.semosan.api.domain.tracking.repository.TrackingSessionRepository;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.data.redis.connection.stream.RecordId;
+import org.springframework.data.redis.connection.stream.StringRecord;
+import org.springframework.data.redis.core.StringRedisTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.Map;
+
+/**
+ * 트래킹 GPS 점을 Redis Stream 으로 발행하기 전, 세션 소유자/상태를 검증한다.
+ *  - 세션 존재 + 본인 소유 검증은 강제 (위반 시 throw → WebSocket 연결 강제 종료 효과)
+ *  - PAUSED/COMPLETED/ABANDONED 상태에서는 silent drop (예외 X) — 클라이언트 race 흡수
+ */
+@Slf4j
+@Service
+@RequiredArgsConstructor
+public class TrackingGpsPublisher {
+
+    private static final String FIELD_SESSION_ID = "sessionId";
+    private static final String FIELD_USER_ID = "userId";
+    private static final String FIELD_LAT = "lat";
+    private static final String FIELD_LNG = "lng";
+    private static final String FIELD_ALTITUDE = "altitude";
+    private static final String FIELD_RECORDED_AT = "recordedAt";
+
+    private final StringRedisTemplate redisTemplate;
+    private final TrackingProperties trackingProperties;
+    private final TrackingSessionRepository trackingSessionRepository;
+
+    @Transactional(readOnly = true)
+    public void publish(Long userId, Long sessionId, GpsPointMessage message) {
+        TrackingSession session = trackingSessionRepository.findById(sessionId)
+                .orElseThrow(() -> new GeneralException(ErrorStatus.TRACKING_SESSION_NOT_FOUND));
+        if (!session.isOwnedBy(userId)) {
+            throw new GeneralException(ErrorStatus.TRACKING_SESSION_FORBIDDEN);
+        }
+        if (session.getStatus() != TrackingSessionStatus.IN_PROGRESS) {
+            log.debug("Dropping GPS point: sessionId={} status={}", sessionId, session.getStatus());
+            return;
+        }
+
+        Map<String, String> body = Map.of(
+                FIELD_SESSION_ID, String.valueOf(sessionId),
+                FIELD_USER_ID, String.valueOf(userId),
+                FIELD_LAT, String.valueOf(message.lat()),
+                FIELD_LNG, String.valueOf(message.lng()),
+                FIELD_ALTITUDE, message.altitude() == null ? "" : String.valueOf(message.altitude()),
+                FIELD_RECORDED_AT, message.recordedAt().toString()
+        );
+        StringRecord record = StringRecord.of(body).withStreamKey(trackingProperties.getStreamKey());
+        RecordId id = redisTemplate.opsForStream().add(record);
+        log.trace("Published GPS point: sessionId={} streamId={}", sessionId, id);
+    }
+}