snp-batch-validation/CLAUDE.md

SNP-Batch-1 (snp-batch-validation)

해양 데이터 통합 배치 시스템. 외부 Maritime API에서 선박/항만/사건 데이터를 수집하여 PostgreSQL에 저장하고, AIS 실시간 위치정보를 캐시 기반으로 서비스.

기술 스택

• Java 17, Spring Boot 3.2.1, Spring Batch 5.1.0
• PostgreSQL (스키마: t_std_snp_data)
• Quartz Scheduler (JDBC Store)
• Spring Kafka (AIS Target → Kafka 파이프라인)
• WebFlux WebClient (외부 API 호출)
• Thymeleaf (배치 관리 Web GUI)
• Springdoc OpenAPI 2.3.0 (Swagger)
• Caffeine Cache, JTS (공간 연산)
• Lombok, Jackson

빌드 & 실행

# 빌드
sdk use java 17.0.18-amzn
mvn clean package -DskipTests

# 실행
mvn spring-boot:run

# 테스트
mvn test

서버 설정

• 포트: 8041
• Context Path: /snp-api
• Swagger UI: http://localhost:8041/snp-api/swagger-ui/index.html

디렉토리 구조

src/main/java/com/snp/batch/
├── SnpBatchApplication.java        # 메인 애플리케이션
├── common/                         # 공통 프레임워크
│   ├── batch/                      # 배치 베이스 클래스 (config, entity, processor, reader, writer)
│   ├── util/                       # 유틸 (JsonChangeDetector, SafeGetDataUtil)
│   └── web/                        # Web 베이스 (ApiResponse, BaseController, BaseService)
├── global/                         # 글로벌 설정 & 배치 관리
│   ├── config/                     # AsyncConfig, QuartzConfig, SwaggerConfig, WebClientConfig
│   ├── controller/                 # BatchController (/api/batch), WebViewController
│   ├── dto/                        # Dashboard, JobExecution, Schedule DTO
│   ├── model/                      # BatchLastExecution, JobScheduleEntity
│   ├── partition/                  # 파티션 관리 (PartitionManagerTasklet)
│   ├── projection/                 # DateRangeProjection
│   └── repository/                 # BatchApiLog, BatchLastExecution, JobSchedule, Timeline
├── jobs/                           # 배치 Job 모듈 (도메인별)
│   ├── aistarget/                  # AIS Target (실시간 위치 + 캐시 + REST API + Kafka 발행)
│   ├── aistargetdbsync/            # AIS Target DB Sync (캐시→DB)
│   ├── common/                     # 공통코드 (FlagCode, Stat5Code)
│   ├── compliance/                 # 규정준수 (Compliance, CompanyCompliance)
│   ├── event/                      # 해양사건 (Event, EventDetail, Cargo, HumanCasualty)
│   ├── movements/                  # 선박이동 (다수 하위 Job)
│   ├── psc/                        # PSC 검사
│   ├── risk/                       # 리스크 분석
│   └── ship*/                      # 선박정보 (ship001~ship028, 30+ 테이블)
└── service/                        # BatchService, ScheduleService

배치 Job 패턴

각 Job은 common/batch/ 베이스 클래스를 상속:

• BaseJobConfig → Job/Step 설정 (chunk-oriented)
• BaseApiReader → 외부 Maritime API 호출 (WebClient)
• BaseProcessor → DTO→Entity 변환
• BaseWriter → PostgreSQL Upsert
• BaseEntity → 공통 필드 (dataHash, lastModifiedDate 등)

주요 API 경로 (context-path: /snp-api)

Batch Management (/api/batch)

메서드	경로	설명
POST	/jobs/{jobName}/execute	배치 작업 실행
GET	/jobs	작업 목록
GET	/jobs/{jobName}/executions	실행 이력
GET	/executions/{id}/detail	실행 상세 (Step 포함)
POST	/executions/{id}/stop	실행 중지
GET/POST	/schedules	스케줄 관리 (CRUD)
GET	/dashboard	대시보드
GET	/timeline	타임라인

AIS Target (/api/ais-target)

메서드	경로	설명
GET	/{mmsi}	MMSI로 최신 위치
POST	/batch	다건 MMSI 조회
GET/POST	/search	시간/공간 범위 검색
POST	/search/filter	조건 필터 검색 (SOG, COG 등)
POST	/search/polygon	폴리곤 범위 검색
POST	/search/wkt	WKT 형식 검색
GET	/search/with-distance	거리 포함 원형 검색
GET	/{mmsi}/track	항적 조회
GET	/cache/stats	캐시 통계
DELETE	/cache	캐시 초기화

Lint/Format

• 별도 lint 도구 미설정 (checkstyle, spotless 없음)
• IDE 기본 포매터 사용