HYOJIN 1ffb1bff78 refactor: 구 프로젝트명 snp-batch-validation 잔여 참조를 snp-collector로 변경

- application-dev.yml: spring.application.name 변경
- application-prod.yml: spring.application.name 변경
- useTheme.ts: localStorage 키 snp-batch-theme → snp-collector-theme
- CLAUDE.md: 배포 경로 /deploy/snp-batch → /deploy/snp-collector

2026-04-07 15:23:07 +09:00

3.8 KiB

Raw Blame 히스토리

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

프로젝트 개요

S&P Maritime API에서 선박/항만/사건 데이터를 수집하여 PostgreSQL에 저장하는 배치 시스템. React 기반 관리 UI 포함.

빌드 & 실행

# Java 버전 설정
sdk use java 17.0.18-amzn

# 프론트엔드 빌드 (src/main/resources/static/으로 출력)
cd frontend && npm install && npm run build && cd ..

# 백엔드 빌드 (프론트 빌드 후 실행)
mvn clean package -DskipTests -Dskip.npm -Dskip.installnodenpm

# 로컬 실행
mvn spring-boot:run

# 테스트
mvn test

# 프론트엔드 개발 서버 (localhost:5173, API는 8041로 프록시)
cd frontend && npm run dev

서버 설정

포트: 8041, Context Path: /snp-collector
Swagger UI: http://localhost:8041/snp-collector/swagger-ui/index.html
프론트엔드 vite base: /snp-collector/ (context-path와 일치해야 함)
프론트엔드 빌드 출력: frontend/ → src/main/resources/static/ (emptyOutDir: true)

배치 Job 아키텍처

베이스 클래스 계층 (`common/batch/`)

BaseJobConfig<I, O>                    # 단일 Step chunk-oriented Job
  └── BaseMultiStepJobConfig<I, O>     # 다중 Step Job (createJobFlow() 오버라이드)
        └── BasePartitionedJobConfig<I, O>  # 파티셔닝 병렬 처리 Job

BaseApiReader: WebClient 기반 Maritime API 호출. GET/POST 지원. BatchApiLog 자동 기록.
BaseProcessor<I, O>: DTO→Entity 변환. processItem() 구현.
BaseWriter: writeItems() 구현. BaseJdbcRepository의 saveAll() 사용 (기존 ID 조회 → insert/update 분리 → PreparedStatement 배치).
BaseEntity: 공통 감사 필드 (createdAt, updatedAt, jobExecutionId).

새 Job 추가 패턴

각 Job은 jobs/batch/{도메인}/ 하위에 config, dto, entity, reader, processor, writer, repository 구성:

*JobConfig extends BaseJobConfig (또는 BaseMultiStepJobConfig/BasePartitionedJobConfig)
*Reader extends BaseApiReader — fetchDataFromApi() 또는 fetchNextBatch() 구현
*Processor extends BaseProcessor — processItem() 구현
*Writer extends BaseWriter — writeItems() 구현
*Repository extends BaseJdbcRepository — SQL insert/update 구현

Job 실행 흐름

스케줄: Quartz JDBC Store → QuartzBatchJob → QuartzJobService → Spring Batch Job 실행
수동 실행: BatchController.POST /api/batch/jobs/{jobName}/execute
재수집: 실패 레코드 자동 재시도 (AutoRetryJobExecutionListener, 최대 3회)
스케줄 초기화: SchedulerInitializer가 앱 시작 시 DB의 JobScheduleEntity를 Quartz에 등록

주요 API 경로 (/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	타임라인

프론트엔드

React 19 + TypeScript + Vite + Tailwind CSS
라우팅: React Router (basename /snp-collector)
페이지: Dashboard, Jobs, Executions, ExecutionDetail, Recollects, RecollectDetail, Schedules, Timeline
API 클라이언트: frontend/src/api/batchApi.ts
전역 상태: ToastContext, ThemeContext

Lint/Format

백엔드: 별도 lint 도구 미설정 (checkstyle, spotless 없음). IDE 기본 포매터 사용.
프론트엔드: cd frontend && npm run lint (ESLint)

배포

Gitea Actions (.gitea/workflows/deploy.yml)
Maven Docker 이미지 (maven:3.9-eclipse-temurin-17)
빌드 산출물: /deploy/snp-collector/app.jar

3.8 KiB Raw Blame 히스토리