# Spring Batch 개발 가이드

## 목차
1. [프로젝트 개요](#1-프로젝트-개요)
2. [프로젝트 구조](#2-프로젝트-구조)
3. [추상 클래스 구조](#3-추상-클래스-구조)
4. [새로운 배치 Job 생성 가이드](#4-새로운-배치-job-생성-가이드)
5. [예제: 전체 구현 과정](#5-예제-전체-구현-과정)
6. [베스트 프랙티스](#6-베스트-프랙티스)
7. [트러블슈팅](#7-트러블슈팅)

---

## 1. 프로젝트 개요

### 1.1 기술 스택
- **Spring Boot**: 3.2.1
- **Spring Batch**: 5.1.0
- **Quartz Scheduler**: 2.5.0
- **PostgreSQL**: 42.7.4
- **WebClient**: REST API 호출
- **Thymeleaf**: 웹 UI
- **Bootstrap 5**: 프론트엔드

### 1.2 주요 기능
- REST API 기반 데이터 수집 배치
- Quartz 기반 스케줄링 관리 (DB 영속화)
- 웹 UI를 통한 배치 모니터링
- 타임라인 차트 (일/주/월 단위)
- 대시보드 및 실행 이력 조회
- 통일된 추상화 구조 (Reader/Processor/Writer)
- REST API 표준 응답 형식

### 1.3 아키텍처 패턴

#### 배치 처리 패턴
```
External API → Reader → Processor → Writer → Database
                ↓          ↓           ↓
           (API Call)  (Transform)  (Batch Insert)
```

#### 계층 구조
```
Controller (REST API)
    ↓
Service (비즈니스 로직)
    ↓
Repository (데이터 액세스)
    ↓
Database (PostgreSQL)
```

#### 추상화 구조
```
com.snp.batch/
├── SnpBatchApplication.java      # Spring Boot 메인 클래스
│
├── common/                        # 공통 추상화 모듈
│   ├── batch/                     # 배치 작업 추상화
│   │   ├── config/
│   │   │   └── BaseJobConfig     # Job/Step 설정 템플릿
│   │   ├── entity/
│   │   │   └── BaseEntity         # Entity 공통 감사 필드
│   │   ├── processor/
│   │   │   └── BaseProcessor      # Processor 템플릿
│   │   ├── reader/
│   │   │   └── BaseApiReader      # API Reader 템플릿
│   │   ├── repository/
│   │   │   └── BaseJdbcRepository # JDBC Repository 템플릿
│   │   └── writer/
│   │       └── BaseWriter         # Writer 템플릿
│   │
│   └── web/                       # 웹 API 추상화
│       ├── controller/
│       │   └── BaseController     # 컨트롤러 템플릿
│       ├── dto/
│       │   └── BaseDto            # 공통 DTO 필드
│       ├── service/
│       │   ├── BaseService        # 서비스 인터페이스
│       │   ├── BaseServiceImpl    # 서비스 구현 템플릿 (JDBC)
│       │   ├── BaseProxyService   # 프록시 서비스 템플릿
│       │   └── BaseHybridService  # 하이브리드 서비스 템플릿
│       └── ApiResponse            # 공통 API 응답 래퍼
│
├── global/                        # 전역 클래스 (애플리케이션 레벨)
│   ├── config/                    # 전역 설정 (Quartz, Swagger 등)
│   ├── controller/                # 전역 컨트롤러 (Batch, Web UI)
│   ├── dto/                       # 전역 DTO (Job 실행, 스케줄 등)
│   ├── model/                     # 전역 Entity (스케줄 정보 등) - JPA 허용
│   └── repository/                # 전역 Repository - JPA 허용
│
├── jobs/                          # 배치 Job 구현 (도메인별, JDBC 전용)
│   ├── sample/                    # 샘플 제품 데이터 Job
│   │   ├── batch/                 # 배치 작업
│   │   └── web/                   # 웹 API (선택)
│   └── shipimport/                # 선박 데이터 Import Job
│       └── batch/                 # 배치 작업만
│
├── service/                       # 전역 서비스
└── scheduler/                     # 스케줄러 (Quartz Job, Initializer)
```

---

## 2. 프로젝트 구조

```
src/main/java/com/snp/batch/
├── SnpBatchApplication.java      # Spring Boot 메인 클래스
│
├── common/                        # 공통 추상화 모듈
│   ├── batch/                     # 배치 작업 공통 Base 클래스
│   │   ├── config/
│   │   │   └── BaseJobConfig.java        # Job/Step 설정 템플릿
│   │   ├── entity/
│   │   │   └── BaseEntity.java           # 공통 감사 필드 (JPA 제거)
│   │   ├── processor/
│   │   │   └── BaseProcessor.java        # Processor 템플릿
│   │   ├── reader/
│   │   │   └── BaseApiReader.java        # API Reader 템플릿
│   │   ├── repository/
│   │   │   └── BaseJdbcRepository.java   # JDBC Repository 템플릿
│   │   └── writer/
│   │       └── BaseWriter.java           # Writer 템플릿
│   │
│   └── web/                       # 웹 API 공통 Base 클래스
│       ├── controller/
│       │   └── BaseController.java       # 컨트롤러 템플릿
│       ├── dto/
│       │   └── BaseDto.java              # 공통 DTO 필드
│       ├── service/
│       │   ├── BaseService.java          # 서비스 인터페이스
│       │   ├── BaseServiceImpl.java      # 서비스 구현 템플릿 (JDBC)
│       │   ├── BaseProxyService.java     # 프록시 서비스 템플릿
│       │   └── BaseHybridService.java    # 하이브리드 서비스 템플릿
│       └── ApiResponse.java              # 공통 API 응답 래퍼
│
├── global/                        # 전역 클래스 (JPA 허용)
│   ├── config/                    # 전역 설정
│   │   ├── QuartzConfig.java            # Quartz 스케줄러 설정
│   │   └── SwaggerConfig.java           # Swagger 설정
│   │
│   ├── controller/                # 전역 컨트롤러
│   │   ├── BatchController.java         # 배치 관리 REST API
│   │   └── WebViewController.java       # Thymeleaf 뷰 컨트롤러
│   │
│   ├── dto/                       # 전역 DTO
│   │   ├── DashboardResponse.java       # 대시보드 응답
│   │   ├── JobExecutionDetailDto.java   # 실행 상세 정보
│   │   ├── JobExecutionDto.java         # 실행 이력 DTO
│   │   ├── ScheduleRequest.java         # 스케줄 등록/수정 요청
│   │   ├── ScheduleResponse.java        # 스케줄 조회 응답
│   │   └── TimelineResponse.java        # 타임라인 응답
│   │
│   ├── model/                     # 전역 Entity (JPA)
│   │   └── JobScheduleEntity.java       # 스케줄 Entity (JPA)
│   │
│   └── repository/                # 전역 Repository (JPA)
│       ├── JobScheduleRepository.java   # JpaRepository (JPA)
│       └── TimelineRepository.java      # 타임라인 Repository
│
├── jobs/                          # 도메인별 배치 Job (JDBC 전용)
│   │
│   ├── sample/                    # 샘플 제품 데이터 Job
│   │   ├── batch/                 # 배치 작업
│   │   │   ├── config/
│   │   │   │   └── ProductDataImportJobConfig.java
│   │   │   ├── dto/
│   │   │   │   ├── ProductApiResponse.java
│   │   │   │   └── ProductDto.java
│   │   │   ├── entity/
│   │   │   │   └── ProductEntity.java    # extends BaseEntity (JPA 제거)
│   │   │   ├── processor/
│   │   │   │   └── ProductDataProcessor.java
│   │   │   ├── reader/
│   │   │   │   └── ProductDataReader.java
│   │   │   ├── repository/
│   │   │   │   ├── ProductRepository.java
│   │   │   │   └── ProductRepositoryImpl.java  # extends BaseJdbcRepository
│   │   │   └── writer/
│   │   │       └── ProductDataWriter.java
│   │   │
│   │   └── web/                   # 웹 API
│   │       ├── controller/
│   │       │   └── ProductWebController.java
│   │       ├── dto/
│   │       │   └── ProductWebDto.java
│   │       └── service/
│   │           └── ProductWebService.java
│   │
│   └── shipimport/                # 선박 데이터 Import Job
│       └── batch/                 # 배치 작업 (웹 API 없음)
│           ├── config/
│           │   └── ShipImportJobConfig.java
│           ├── dto/
│           │   ├── ShipApiResponse.java
│           │   └── ShipDto.java
│           ├── entity/
│           │   └── ShipEntity.java       # extends BaseEntity (JPA 제거)
│           ├── processor/
│           │   └── ShipDataProcessor.java
│           ├── reader/
│           │   └── ShipDataReader.java
│           ├── repository/
│           │   ├── ShipRepository.java
│           │   └── ShipRepositoryImpl.java  # extends BaseJdbcRepository
│           └── writer/
│               └── ShipDataWriter.java
│
├── service/                       # 전역 서비스
│   ├── BatchService.java              # 배치 실행 관리
│   ├── QuartzJobService.java          # Quartz-Batch 연동
│   └── ScheduleService.java           # 스케줄 DB 영속화
│
└── scheduler/                     # 스케줄러
    ├── QuartzBatchJob.java            # Quartz Job 구현체
    └── SchedulerInitializer.java      # 스케줄 자동 로드
```

**주요 특징**:
- `common/batch/`: 배치 작업 전용 Base 클래스 (JDBC 기반)
- `common/web/`: 웹 API 전용 Base 클래스 (JDBC 기반)
- `global/`: JPA 사용 허용 (간단한 CRUD만)
- `jobs/`: 모든 Job은 JDBC 전용 (성능 최적화)

---

## 3. 추상 클래스 구조

### 3.0 공통 베이스 클래스

#### 3.0.1 BaseEntity

**목적**: 모든 Entity의 공통 감사(Audit) 필드 관리

**위치**: `com.snp.batch.common.batch.entity.BaseEntity`

**제공 필드**:
```java
@CreatedDate
private LocalDateTime createdAt;      // 생성 일시 (자동 설정)

@LastModifiedDate
private LocalDateTime updatedAt;      // 수정 일시 (자동 업데이트)

private String createdBy;             // 생성자 (기본값: "SYSTEM")
private String updatedBy;             // 수정자 (기본값: "SYSTEM")
```

**사용 방법 (jobs 패키지 - JDBC 전용)**:
```java
/**
 * Ship Entity - JDBC Template 기반
 * JPA 어노테이션 사용 금지
 * 컬럼 매핑은 주석으로 명시
 */
@Data
@SuperBuilder
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
public class ShipEntity extends BaseEntity {
    /**
     * 기본 키 (자동 생성)
     * 컬럼: id (BIGSERIAL)
     */
    private Long id;

    /**
     * 선박 이름
     * 컬럼: ship_name (VARCHAR(100))
     */
    private String shipName;

    // createdAt, updatedAt, createdBy, updatedBy는 BaseEntity에서 상속
}
```

**사용 방법 (global 패키지 - JPA 허용)**:
```java
@Entity
@Table(name = "job_schedule")
@Data
@SuperBuilder
@NoArgsConstructor
@AllArgsConstructor
public class JobScheduleEntity extends BaseEntity {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(name = "job_name", unique = true, nullable = false)
    private String jobName;
    // createdAt, updatedAt, createdBy, updatedBy는 자동 관리됨
}
```

**주요 기능**:
- jobs 패키지: JDBC 기반, JPA 어노테이션 없음, RowMapper로 수동 매핑
- global 패키지: JPA 기반, @PrePersist/@PreUpdate로 자동 관리
- 공통 감사 필드: createdAt, updatedAt, createdBy, updatedBy

---

#### 3.0.2 BaseDto

**목적**: 모든 DTO의 공통 감사 필드 제공

**위치**: `com.snp.batch.common.web.dto.BaseDto`

**제공 필드**:
```java
private LocalDateTime createdAt;
private LocalDateTime updatedAt;
private String createdBy;
private String updatedBy;
```

**사용 방법**:
```java
@Data
@EqualsAndHashCode(callSuper = true)
public class ShipDto extends BaseDto {
    private String shipName;
    private String shipType;
    // 부모 클래스의 감사 필드 자동 상속
}
```

---

#### 3.0.3 BaseService<T, D, ID>

**목적**: Service 계층의 공통 CRUD 인터페이스 정의

**위치**: `com.snp.batch.common.web.service.BaseService`

**제공 메서드**:
```java
D create(D dto);                      // 생성
Optional<D> findById(ID id);          // 단건 조회
List<D> findAll();                    // 전체 조회
Page<D> findAll(Pageable pageable);   // 페이징 조회
D update(ID id, D dto);               // 수정
void deleteById(ID id);               // 삭제
boolean existsById(ID id);            // 존재 여부 확인
D toDto(T entity);                    // Entity → DTO 변환
T toEntity(D dto);                    // DTO → Entity 변환
```

---

#### 3.0.4 BaseServiceImpl<T, D, ID>

**목적**: BaseService의 기본 구현 제공

**위치**: `com.snp.batch.common.web.service.BaseServiceImpl`

**필수 구현 메서드**:
```java
protected abstract BaseJdbcRepository<T, ID> getRepository();  // Repository 반환
protected abstract String getEntityName();                     // Entity 이름 (로깅용)
protected abstract void updateEntity(T entity, D dto);         // Entity 업데이트 로직
protected abstract ID extractId(T entity);                     // Entity에서 ID 추출
```

**참고**: jobs 패키지에서는 JDBC 기반 Repository를 사용합니다 (BaseJdbcRepository 상속).

**사용 예제**:
```java
@Service
@RequiredArgsConstructor
public class ProductWebService extends BaseServiceImpl<ProductEntity, ProductWebDto, Long> {

    private final ProductRepository productRepository;

    @Override
    protected BaseJdbcRepository<ProductEntity, Long> getRepository() {
        return productRepository;
    }

    @Override
    protected String getEntityName() {
        return "Product";
    }

    @Override
    protected void updateEntity(ProductEntity entity, ProductWebDto dto) {
        entity.setProductName(dto.getProductName());
        entity.setCategory(dto.getCategory());
        entity.setPrice(dto.getPrice());
    }

    @Override
    protected Long extractId(ProductEntity entity) {
        return entity.getId();
    }

    @Override
    public ProductWebDto toDto(ProductEntity entity) {
        return ProductWebDto.builder()
                .productId(entity.getProductId())
                .productName(entity.getProductName())
                .category(entity.getCategory())
                .price(entity.getPrice())
                .build();
    }

    @Override
    public ProductEntity toEntity(ProductWebDto dto) {
        return ProductEntity.builder()
                .productId(dto.getProductId())
                .productName(dto.getProductName())
                .category(dto.getCategory())
                .price(dto.getPrice())
                .build();
    }
}
```

---

#### 3.0.5 BaseController<D, ID>

**목적**: REST Controller의 공통 CRUD API 제공

**위치**: `com.snp.batch.common.web.controller.BaseController`

**필수 구현 메서드**:
```java
protected abstract BaseService<?, D, ID> getService();  // Service 반환
protected abstract String getResourceName();            // 리소스 이름 (로깅용)
```

**제공 API**:
```java
POST   /                 → create(D dto)              # 생성
GET    /{id}             → getById(ID id)             # 단건 조회
GET    /                 → getAll()                   # 전체 조회
GET    /page             → getPage(Pageable)          # 페이징 조회
PUT    /{id}             → update(ID id, D dto)       # 수정
DELETE /{id}             → delete(ID id)              # 삭제
GET    /{id}/exists      → exists(ID id)              # 존재 여부
```

**사용 예제**:
```java
@RestController
@RequestMapping("/api/ships")
@RequiredArgsConstructor
public class ShipController extends BaseController<ShipDto, Long> {

    private final ShipService shipService;

    @Override
    protected BaseService<?, ShipDto, Long> getService() {
        return shipService;
    }

    @Override
    protected String getResourceName() {
        return "Ship";
    }

    // 추가 커스텀 API가 필요한 경우 여기에 정의
}
```

---

#### 3.0.6 ApiResponse<T>

**목적**: 통일된 API 응답 형식 제공

**위치**: `com.snp.batch.common.web.ApiResponse`

**필드 구조**:
```java
private boolean success;      // 성공 여부
private String message;       // 메시지
private T data;              // 응답 데이터
private String errorCode;    // 에러 코드 (실패 시)
```

**사용 방법**:
```java
// 성공 응답
ApiResponse<ShipDto> response = ApiResponse.success(shipDto);
ApiResponse<ShipDto> response = ApiResponse.success("Ship created", shipDto);

// 실패 응답
ApiResponse<Void> response = ApiResponse.error("Ship not found");
ApiResponse<Void> response = ApiResponse.error("Validation failed", "ERR_001");
```

**응답 예제**:
```json
{
  "success": true,
  "message": "Success",
  "data": {
    "shipName": "Titanic",
    "shipType": "Passenger"
  },
  "errorCode": null
}
```

---

### 3.1 BaseApiReader<T>

**목적**: REST API에서 데이터를 읽어오는 ItemReader 구현 패턴 제공

**위치**: `com.snp.batch.common.batch.reader.BaseApiReader`

**필수 구현 메소드**:
```java
protected abstract String getApiPath();                    // API 경로
protected abstract List<T> extractDataFromResponse(Object response);  // 응답 파싱
protected abstract Class<?> getResponseType();             // 응답 클래스
protected abstract String getReaderName();                 // Reader 이름
```

**선택적 오버라이드 메소드**:
```java
protected void addQueryParams(UriBuilder uriBuilder) {}    // 쿼리 파라미터 추가
protected void beforeApiCall() {}                          // API 호출 전처리
protected void afterApiCall(List<T> data) {}               // API 호출 후처리
protected void handleApiError(Exception e) {}              // 에러 처리
```

**제공되는 기능**:
- API 호출 및 데이터 캐싱 (한 번만 호출)
- 순차적 데이터 반환 (read() 메소드)
- 자동 로깅 및 에러 핸들링

**사용 예제**:
```java
@Component
public class ShipDataReader extends BaseApiReader<ShipDto> {

    public ShipDataReader(WebClient webClient) {
        super(webClient);
    }

    @Override
    protected String getApiPath() {
        return "/api/v1/ships";
    }

    @Override
    protected List<ShipDto> extractDataFromResponse(Object response) {
        ShipApiResponse apiResponse = (ShipApiResponse) response;
        return apiResponse.getData();
    }

    @Override
    protected Class<?> getResponseType() {
        return ShipApiResponse.class;
    }

    @Override
    protected String getReaderName() {
        return "ShipDataReader";
    }
}
```

---

### 3.2 BaseProcessor<I, O>

**목적**: 데이터 변환 및 처리 로직의 템플릿 제공

**위치**: `com.snp.batch.common.batch.processor.BaseProcessor`

**필수 구현 메소드**:
```java
protected abstract O transform(I item) throws Exception;   // 데이터 변환
protected abstract boolean shouldProcess(I item);          // 처리 여부 판단
protected abstract String getProcessorName();              // Processor 이름
```

**선택적 오버라이드 메소드**:
```java
protected void beforeProcess(I item) {}                    // 전처리
protected void afterProcess(I input, O output) {}          // 후처리
protected void handleProcessError(I item, Exception e) {}  // 에러 처리
protected void onItemFiltered(I item) {}                   // 필터링 로깅
```

**제공되는 기능**:
- DTO → Entity 변환 패턴
- 데이터 필터링 (shouldProcess 기반)
- 자동 로깅 및 에러 핸들링

**사용 예제**:
```java
@Component
public class ShipDataProcessor extends BaseProcessor<ShipDto, ShipEntity> {

    @Override
    protected ShipEntity transform(ShipDto dto) {
        return ShipEntity.builder()
                .shipId(dto.getShipId())
                .shipName(dto.getShipName())
                .shipType(dto.getShipType())
                .build();
    }

    @Override
    protected boolean shouldProcess(ShipDto dto) {
        // 유효성 검사: shipId가 있는 경우만 처리
        return dto.getShipId() != null && !dto.getShipId().isEmpty();
    }

    @Override
    protected String getProcessorName() {
        return "ShipDataProcessor";
    }

    @Override
    protected void onItemFiltered(ShipDto dto) {
        log.warn("Ship ID가 없어 필터링됨: {}", dto);
    }
}
```

---

### 3.3 BaseWriter<T>

**목적**: 데이터베이스 저장 로직의 템플릿 제공

**위치**: `com.snp.batch.common.batch.writer.BaseWriter`

**필수 구현 메소드**:
```java
protected abstract void writeItems(List<T> items) throws Exception;  // 저장 로직
protected abstract String getWriterName();                           // Writer 이름
```

**선택적 오버라이드 메소드**:
```java
protected void beforeWrite(List<T> items) {}               // 저장 전처리
protected void afterWrite(List<T> items) {}                // 저장 후처리
protected void handleWriteError(List<T> items, Exception e) {}  // 에러 처리
protected List<T> filterItems(List<T> items) {}            // 아이템 필터링
protected void validateBatchSize(List<T> items) {}         // 배치 크기 검증
```

**제공되는 기능**:
- 배치 저장 패턴 (Chunk 단위)
- Null 아이템 자동 필터링
- 배치 크기 검증 및 경고
- 자동 로깅 및 에러 핸들링

**사용 예제**:
```java
@Component
@RequiredArgsConstructor
public class ShipDataWriter extends BaseWriter<ShipEntity> {

    private final ShipRepository shipRepository;

    @Override
    protected void writeItems(List<ShipEntity> items) {
        shipRepository.saveAll(items);
    }

    @Override
    protected String getWriterName() {
        return "ShipDataWriter";
    }

    @Override
    protected void afterWrite(List<ShipEntity> items) {
        log.info("Ship 데이터 저장 완료: {} 건", items.size());
    }
}
```

---

### 3.4 BaseJobConfig<I, O>

**목적**: Batch Job 설정의 표준 템플릿 제공

**위치**: `com.snp.batch.common.batch.config.BaseJobConfig`

**필수 구현 메소드**:
```java
protected abstract String getJobName();                    // Job 이름
protected abstract ItemReader<I> createReader();           // Reader 생성
protected abstract ItemProcessor<I, O> createProcessor();  // Processor 생성
protected abstract ItemWriter<O> createWriter();           // Writer 생성
```

**선택적 오버라이드 메소드**:
```java
protected String getStepName() {}                          // Step 이름 (기본: {jobName}Step)
protected int getChunkSize() {}                            // Chunk 크기 (기본: 100)
protected void configureJob(JobBuilder jobBuilder) {}      // Job 커스터마이징
protected void configureStep(StepBuilder stepBuilder) {}   // Step 커스터마이징
```

**제공되는 기능**:
- Job 및 Step 자동 생성
- Chunk 기반 처리 설정
- Processor가 없는 경우도 지원

**사용 예제**:
```java
@Configuration
@RequiredArgsConstructor
public class ShipDataImportJobConfig extends BaseJobConfig<ShipDto, ShipEntity> {

    private final ShipDataReader shipDataReader;
    private final ShipDataProcessor shipDataProcessor;
    private final ShipDataWriter shipDataWriter;

    public ShipDataImportJobConfig(
            JobRepository jobRepository,
            PlatformTransactionManager transactionManager,
            ShipDataReader shipDataReader,
            ShipDataProcessor shipDataProcessor,
            ShipDataWriter shipDataWriter) {
        super(jobRepository, transactionManager);
        this.shipDataReader = shipDataReader;
        this.shipDataProcessor = shipDataProcessor;
        this.shipDataWriter = shipDataWriter;
    }

    @Override
    protected String getJobName() {
        return "shipDataImportJob";
    }

    @Override
    protected ItemReader<ShipDto> createReader() {
        return shipDataReader;
    }

    @Override
    protected ItemProcessor<ShipDto, ShipEntity> createProcessor() {
        return shipDataProcessor;
    }

    @Override
    protected ItemWriter<ShipEntity> createWriter() {
        return shipDataWriter;
    }

    @Override
    protected int getChunkSize() {
        return 50;  // 커스텀 Chunk 크기
    }

    @Bean(name = "shipDataImportJob")
    public Job shipDataImportJob() {
        return job();
    }

    @Bean(name = "shipDataImportStep")
    public Step shipDataImportStep() {
        return step();
    }
}
```

---

### 3.5 BaseJdbcRepository<T, ID>

**목적**: JDBC 기반 Repository의 CRUD 템플릿 제공

**위치**: `com.snp.batch.common.batch.repository.BaseJdbcRepository`

**필수 구현 메소드**:
```java
protected abstract String getTableName();                  // 테이블 이름
protected abstract RowMapper<T> getRowMapper();            // RowMapper
protected abstract ID extractId(T entity);                 // ID 추출
protected abstract String getInsertSql();                  // INSERT SQL
protected abstract String getUpdateSql();                  // UPDATE SQL
protected abstract void setInsertParameters(PreparedStatement ps, T entity);
protected abstract void setUpdateParameters(PreparedStatement ps, T entity);
protected abstract String getEntityName();                 // Entity 이름 (로깅용)
```

**제공되는 기능**:
- findById, findAll, count, existsById
- save, insert, update
- batchInsert, batchUpdate, saveAll
- deleteById, deleteAll
- 자동 트랜잭션 처리

**사용 예제**:
```java
@Repository
public class ShipRepository extends BaseJdbcRepository<ShipEntity, String> {

    public ShipRepository(JdbcTemplate jdbcTemplate) {
        super(jdbcTemplate);
    }

    @Override
    protected String getTableName() {
        return "ships";
    }

    @Override
    protected RowMapper<ShipEntity> getRowMapper() {
        return (rs, rowNum) -> ShipEntity.builder()
                .shipId(rs.getString("ship_id"))
                .shipName(rs.getString("ship_name"))
                .shipType(rs.getString("ship_type"))
                .build();
    }

    @Override
    protected String extractId(ShipEntity entity) {
        return entity.getShipId();
    }

    @Override
    protected String getInsertSql() {
        return "INSERT INTO ships (ship_id, ship_name, ship_type) VALUES (?, ?, ?)";
    }

    @Override
    protected String getUpdateSql() {
        return "UPDATE ships SET ship_name = ?, ship_type = ? WHERE ship_id = ?";
    }

    @Override
    protected void setInsertParameters(PreparedStatement ps, ShipEntity entity) throws SQLException {
        ps.setString(1, entity.getShipId());
        ps.setString(2, entity.getShipName());
        ps.setString(3, entity.getShipType());
    }

    @Override
    protected void setUpdateParameters(PreparedStatement ps, ShipEntity entity) throws SQLException {
        ps.setString(1, entity.getShipName());
        ps.setString(2, entity.getShipType());
        ps.setString(3, entity.getShipId());
    }

    @Override
    protected String getEntityName() {
        return "Ship";
    }
}
```

---

## 4. 새로운 배치 Job 생성 가이드

### 4.1 사전 준비

1. **도메인 파악**
   - 어떤 데이터를 수집할 것인가? (예: 선박 데이터, 사용자 데이터 등)
   - API 엔드포인트는 무엇인가?
   - 데이터 구조는 어떻게 되는가?

2. **데이터베이스 테이블 생성**
   ```sql
   CREATE TABLE ships (
       ship_id VARCHAR(50) PRIMARY KEY,
       ship_name VARCHAR(100) NOT NULL,
       ship_type VARCHAR(50),
       created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
   );
   ```

### 4.2 단계별 구현

#### Step 1: DTO 클래스 생성 (jobs/{domain}/batch/dto 패키지)

**API 응답 DTO**:
```java
@Data
public class ShipApiResponse {
    private List<ShipDto> data;
    private int totalCount;
}
```

**데이터 DTO**:
```java
@Data
@Builder
public class ShipDto {
    private String imoNumber;
    private String coreShipInd;
    private String datasetVersion;
}
```

#### Step 2: Entity 클래스 생성 (jobs/{domain}/batch/entity 패키지)

**JDBC 기반 Entity (JPA 어노테이션 없음)**:
```java
/**
 * Ship Entity - JDBC Template 기반
 * JPA 어노테이션 사용 금지
 */
@Data
@SuperBuilder
@NoArgsConstructor
@AllArgsConstructor
@EqualsAndHashCode(callSuper = true)
public class ShipEntity extends BaseEntity {
    /**
     * 기본 키
     * 컬럼: id (BIGSERIAL)
     */
    private Long id;

    /**
     * IMO 번호
     * 컬럼: imo_number (VARCHAR(20), UNIQUE)
     */
    private String imoNumber;

    /**
     * Core Ship Indicator
     * 컬럼: core_ship_ind (VARCHAR(10))
     */
    private String coreShipInd;

    // createdAt, updatedAt, createdBy, updatedBy는 BaseEntity에서 상속
}
```

#### Step 3: Repository 구현 (jobs/{domain}/batch/repository 패키지)

```java
@Repository
public class ShipRepository extends BaseJdbcRepository<ShipEntity, String> {

    public ShipRepository(JdbcTemplate jdbcTemplate) {
        super(jdbcTemplate);
    }

    // 추상 메소드 구현 (위의 3.5 예제 참고)
}
```

#### Step 4: Reader 구현 (jobs/{domain}/batch/reader 패키지)

```java
@Component
public class ShipDataReader extends BaseApiReader<ShipDto> {

    public ShipDataReader(WebClient webClient) {
        super(webClient);
    }

    // 추상 메소드 구현 (위의 3.1 예제 참고)
}
```

#### Step 5: Processor 구현 (jobs/{domain}/batch/processor 패키지)

```java
@Component
public class ShipDataProcessor extends BaseProcessor<ShipDto, ShipEntity> {

    // 추상 메소드 구현 (위의 3.2 예제 참고)
}
```

#### Step 6: Writer 구현 (jobs/{domain}/batch/writer 패키지)

```java
@Component
@RequiredArgsConstructor
public class ShipDataWriter extends BaseWriter<ShipEntity> {

    private final ShipRepository shipRepository;

    // 추상 메소드 구현 (위의 3.3 예제 참고)
}
```

#### Step 7: JobConfig 구현 (jobs/{domain}/batch/config 패키지)

```java
@Configuration
@RequiredArgsConstructor
public class ShipDataImportJobConfig extends BaseJobConfig<ShipDto, ShipEntity> {

    private final ShipDataReader shipDataReader;
    private final ShipDataProcessor shipDataProcessor;
    private final ShipDataWriter shipDataWriter;

    public ShipDataImportJobConfig(
            JobRepository jobRepository,
            PlatformTransactionManager transactionManager,
            ShipDataReader shipDataReader,
            ShipDataProcessor shipDataProcessor,
            ShipDataWriter shipDataWriter) {
        super(jobRepository, transactionManager);
        this.shipDataReader = shipDataReader;
        this.shipDataProcessor = shipDataProcessor;
        this.shipDataWriter = shipDataWriter;
    }

    // 추상 메소드 구현 (위의 3.4 예제 참고)

    @Bean(name = "shipDataImportJob")
    public Job shipDataImportJob() {
        return job();
    }

    @Bean(name = "shipDataImportStep")
    public Step shipDataImportStep() {
        return step();
    }
}
```

#### Step 8: 테스트 및 실행

1. **애플리케이션 시작**
   ```bash
   mvn spring-boot:run
   ```

2. **웹 UI에서 확인**
   - http://localhost:8080
   - "shipDataImportJob" 확인
   - "즉시 실행" 버튼 클릭

3. **로그 확인**
   ```
   ShipDataReader API 호출 시작
   ShipDataReader API 응답 성공: 100 건
   ShipDataReader 데이터 100건 조회 완료
   ShipDataWriter 데이터 저장 시작: 50 건
   ShipDataWriter 데이터 저장 완료: 50 건
   ```

---

## 5. 예제: 전체 구현 과정

### 5.1 시나리오
- **목적**: 외부 API에서 사용자 데이터를 수집하여 데이터베이스에 저장
- **API**: `GET /api/v1/users?status=active`
- **필터링**: 이메일이 있는 사용자만 저장

### 5.2 파일 구조
```
src/main/java/com/snp/batch/
└── jobs/user/
    └── batch/                           # 배치 작업
        ├── config/
        │   └── UserDataImportJobConfig.java
        ├── dto/
        │   ├── UserDto.java
        │   └── UserApiResponse.java
        ├── entity/
        │   └── UserEntity.java          # extends BaseEntity (JPA 제거)
        ├── processor/
        │   └── UserDataProcessor.java   # extends BaseProcessor
        ├── reader/
        │   └── UserDataReader.java      # extends BaseApiReader
        ├── repository/
        │   ├── UserRepository.java      # 인터페이스
        │   └── UserRepositoryImpl.java  # extends BaseJdbcRepository
        └── writer/
            └── UserDataWriter.java      # extends BaseWriter
```

### 5.3 테이블 생성 SQL
```sql
CREATE TABLE users (
    user_id BIGINT PRIMARY KEY,
    username VARCHAR(100) NOT NULL,
    email VARCHAR(255),
    status VARCHAR(50),
    imported_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

### 5.4 코드 구현

각 클래스의 전체 구현 코드는 섹션 3의 추상 클래스 사용 예제를 참고하세요.

---

## 6. 베스트 프랙티스

### 6.1 네이밍 컨벤션

| 구분 | 패턴 | 예제 |
|------|------|------|
| Job 이름 | `{domain}DataImportJob` | `shipDataImportJob` |
| Step 이름 | `{domain}DataImportStep` | `shipDataImportStep` |
| Reader | `{Domain}DataReader` | `ShipDataReader` |
| Processor | `{Domain}DataProcessor` | `ShipDataProcessor` |
| Writer | `{Domain}DataWriter` | `ShipDataWriter` |
| JobConfig | `{Domain}DataImportJobConfig` | `ShipDataImportJobConfig` |
| Repository | `{Domain}Repository` | `ShipRepository` |
| Entity | `{Domain}Entity` | `ShipEntity` |
| DTO | `{Domain}Dto` | `ShipDto` |

### 6.2 패키지 구조

**배치 전용 Job** (예: shipimport):
```
com.snp.batch.jobs.{domain}/
└── batch/
    ├── config/
    │   └── {Domain}DataImportJobConfig.java  # extends BaseJobConfig
    ├── dto/
    │   ├── {Domain}Dto.java
    │   └── {Domain}ApiResponse.java
    ├── entity/
    │   └── {Domain}Entity.java               # extends BaseEntity (JPA 제거)
    ├── processor/
    │   └── {Domain}DataProcessor.java        # extends BaseProcessor
    ├── reader/
    │   └── {Domain}DataReader.java           # extends BaseApiReader
    ├── repository/
    │   ├── {Domain}Repository.java           # 인터페이스
    │   └── {Domain}RepositoryImpl.java       # extends BaseJdbcRepository
    └── writer/
        └── {Domain}DataWriter.java           # extends BaseWriter
```

**배치 + 웹 API Job** (예: sample):
```
com.snp.batch.jobs.{domain}/
├── batch/                                    # 배치 작업
│   ├── config/
│   ├── dto/
│   ├── entity/
│   ├── processor/
│   ├── reader/
│   ├── repository/
│   └── writer/
└── web/                                      # 웹 API
    ├── controller/
    │   └── {Domain}WebController.java        # extends BaseController
    ├── dto/
    │   └── {Domain}WebDto.java               # extends BaseDto
    └── service/
        └── {Domain}WebService.java           # extends BaseServiceImpl (JDBC)
```

### 6.3 Chunk 크기 선택 가이드

| 데이터 크기 | Chunk 크기 | 사용 시나리오 |
|-------------|-----------|--------------|
| 소량 (< 1,000) | 50-100 | 간단한 API 데이터 |
| 중량 (1,000-10,000) | 100-500 | 일반적인 배치 작업 |
| 대량 (> 10,000) | 500-1,000 | 대용량 데이터 처리 |

### 6.4 에러 처리 전략

1. **API 호출 실패**
   - `BaseApiReader.handleApiError()` 오버라이드
   - 빈 리스트 반환 (Job 실패 방지) 또는 예외 던지기

2. **데이터 변환 실패**
   - `BaseProcessor.handleProcessError()` 오버라이드
   - 문제 데이터 로깅 후 null 반환 (다음 데이터 계속 처리)

3. **저장 실패**
   - `BaseWriter.handleWriteError()` 오버라이드
   - 재시도 로직 또는 부분 저장 구현

### 6.5 로깅 전략

```java
// Reader에서
@Override
protected void afterApiCall(List<ShipDto> data) {
    log.info("API 호출 성공: {} 건 조회", data.size());
}

// Processor에서
@Override
protected void onItemFiltered(ShipDto dto) {
    log.debug("필터링됨: {}", dto);
}

// Writer에서
@Override
protected void afterWrite(List<ShipEntity> items) {
    log.info("저장 완료: {} 건", items.size());
}
```

### 6.6 성능 최적화

1. **배치 Insert 사용**
   ```java
   @Override
   protected void writeItems(List<ShipEntity> items) {
       shipRepository.batchInsert(items);  // saveAll() 대신
   }
   ```

2. **API 페이징 처리**
   ```java
   @Override
   protected void addQueryParams(UriBuilder uriBuilder) {
       uriBuilder.queryParam("page", 1);
       uriBuilder.queryParam("size", 1000);
   }
   ```

3. **경량 쿼리 사용**
   - 불필요한 JOIN 제거
   - 필요한 컬럼만 SELECT

---

## 7. 트러블슈팅

### 7.1 일반적인 문제

#### 문제 1: Job이 실행되지 않음
**증상**: 웹 UI에서 Job 목록이 보이지 않음

**해결 방법**:
1. `@Bean` 어노테이션 확인
   ```java
   @Bean(name = "shipDataImportJob")
   public Job shipDataImportJob() {
       return job();
   }
   ```

2. JobConfig 클래스에 `@Configuration` 어노테이션 확인

3. 로그 확인: "Job 생성: shipDataImportJob" 메시지 확인

---

#### 문제 2: API 호출 실패
**증상**: "API 호출 실패" 로그, 데이터 0건

**해결 방법**:
1. WebClient 설정 확인 (`application.yml`)
   ```yaml
   api:
     base-url: http://api.example.com
   ```

2. API 경로 확인
   ```java
   @Override
   protected String getApiPath() {
       return "/api/v1/ships";  // 슬래시 확인
   }
   ```

3. 네트워크 연결 테스트
   ```bash
   curl http://api.example.com/api/v1/ships
   ```

---

#### 문제 3: 데이터가 저장되지 않음
**증상**: "저장 완료" 로그는 있지만 DB에 데이터 없음

**해결 방법**:
1. 트랜잭션 확인
   ```java
   @Override
   protected void writeItems(List<ShipEntity> items) {
       shipRepository.saveAll(items);  // 트랜잭션 내에서 실행되는지 확인
   }
   ```

2. SQL 로그 활성화 (`application.yml`)
   ```yaml
   logging:
     level:
       org.springframework.jdbc.core: DEBUG
   ```

3. 데이터베이스 연결 확인
   ```bash
   psql -U postgres -d batch_db
   SELECT * FROM ships;
   ```

---

#### 문제 4: Chunk 처리 중 일부만 저장됨
**증상**: 100건 조회 중 50건만 저장됨

**해결 방법**:
1. Processor의 `shouldProcess()` 확인
   ```java
   @Override
   protected boolean shouldProcess(ShipDto dto) {
       // false 반환 시 필터링됨
       return dto.getShipId() != null;
   }
   ```

2. 필터링 로그 확인
   ```java
   @Override
   protected void onItemFiltered(ShipDto dto) {
       log.warn("필터링됨: {}", dto);  // 로그 추가
   }
   ```

---

#### 문제 5: 메모리 부족 오류 (OutOfMemoryError)
**증상**: 대량 데이터 처리 중 OOM 발생

**해결 방법**:
1. Chunk 크기 줄이기
   ```java
   @Override
   protected int getChunkSize() {
       return 50;  // 기본 100에서 감소
   }
   ```

2. JVM 힙 메모리 증가
   ```bash
   java -Xmx2g -jar snp-batch.jar
   ```

3. API 페이징 처리 구현

---

### 7.2 로그 레벨 설정

**application.yml**:
```yaml
logging:
  level:
    com.snp.batch: DEBUG                          # 배치 애플리케이션
    com.snp.batch.common.batch: INFO             # 배치 추상 클래스 (INFO)
    com.snp.batch.common.web: INFO               # 웹 추상 클래스 (INFO)
    org.springframework.batch: INFO              # Spring Batch
    org.springframework.jdbc.core: DEBUG         # SQL 쿼리
    org.springframework.web.reactive: DEBUG      # WebClient
```

---

### 7.3 디버깅 팁

1. **Step 실행 상태 확인**
   ```sql
   SELECT * FROM BATCH_STEP_EXECUTION
   WHERE JOB_EXECUTION_ID = {executionId};
   ```

2. **Step Context 확인**
   ```sql
   SELECT * FROM BATCH_STEP_EXECUTION_CONTEXT
   WHERE STEP_EXECUTION_ID = {stepExecutionId};
   ```

3. **Job Parameter 확인**
   ```sql
   SELECT * FROM BATCH_JOB_EXECUTION_PARAMS
   WHERE JOB_EXECUTION_ID = {executionId};
   ```

---

## 8. 자주 묻는 질문 (FAQ)

### Q1: Processor 없이 Reader → Writer만 사용할 수 있나요?
**A**: 네, 가능합니다. `createProcessor()`에서 `null`을 반환하면 됩니다.

```java
@Override
protected ItemProcessor<ShipDto, ShipDto> createProcessor() {
    return null;  // Processor 없이 Reader → Writer
}
```

---

### Q2: 여러 개의 Writer를 사용할 수 있나요?
**A**: `CompositeItemWriter`를 사용하면 가능합니다.

```java
@Override
protected ItemWriter<ShipEntity> createWriter() {
    CompositeItemWriter<ShipEntity> compositeWriter = new CompositeItemWriter<>();
    compositeWriter.setDelegates(Arrays.asList(
        shipDataWriter,
        auditLogWriter
    ));
    return compositeWriter;
}
```

---

### Q3: API 페이징을 지원하나요?
**A**: 현재 `BaseApiReader`는 단일 호출만 지원합니다. 페이징이 필요한 경우 커스텀 Reader를 구현하세요.

---

### Q4: 스케줄 등록은 어떻게 하나요?
**A**: 웹 UI에서 "스케줄 등록" 버튼을 클릭하여 Cron 표현식을 입력하면 됩니다.

```
예제 Cron 표현식:
- 매일 오전 2시: 0 0 2 * * ?
- 매시간: 0 0 * * * ?
- 매주 월요일 오전 9시: 0 0 9 ? * MON
```

---

### Q5: Job 실행 이력은 어디서 확인하나요?
**A**: 웹 UI의 다음 위치에서 확인할 수 있습니다:
1. 대시보드: 최근 실행 이력 (최근 10건)
2. Job 상세 페이지: 특정 Job의 모든 실행 이력
3. 타임라인 차트: 일/주/월 단위 시각화

---

## 9. 추가 리소스

### 9.1 공식 문서
- [Spring Batch 공식 문서](https://docs.spring.io/spring-batch/docs/current/reference/html/)
- [Spring Boot 공식 문서](https://docs.spring.io/spring-boot/docs/current/reference/html/)
- [Quartz Scheduler](http://www.quartz-scheduler.org/documentation/)

### 9.2 프로젝트 파일
- `application.yml`: 애플리케이션 설정
- `schema-postgresql.sql`: 데이터베이스 스키마
- `BaseApiReader.java`: API Reader 추상 클래스 (src/main/java/com/snp/batch/common/batch/reader/BaseApiReader.java:1)
- `BaseJobConfig.java`: Job Config 추상 클래스 (src/main/java/com/snp/batch/common/batch/config/BaseJobConfig.java:1)
- `BaseJdbcRepository.java`: JDBC Repository 추상 클래스 (src/main/java/com/snp/batch/common/batch/repository/BaseJdbcRepository.java:1)

---

---

## 10. 추상화 클래스 체크리스트

새로운 배치 Job을 만들 때 다음 체크리스트를 참고하세요.

### 10.1 필수 구현 항목

- [ ] **패키지 구조 생성**
  - [ ] `jobs/{domain}/batch/` 디렉토리 생성 (배치 작업)
  - [ ] `jobs/{domain}/web/` 디렉토리 생성 (웹 API 필요 시)

- [ ] **DTO 생성** (`jobs/{domain}/batch/dto/` 패키지)
  - [ ] API 응답 DTO (예: `ShipApiResponse`)
  - [ ] 데이터 DTO (예: `ShipDto`)

- [ ] **Entity 생성** (`jobs/{domain}/batch/entity/` 패키지)
  - [ ] `BaseEntity` 상속
  - [ ] `@SuperBuilder`, `@NoArgsConstructor`, `@AllArgsConstructor` 추가
  - [ ] `@EqualsAndHashCode(callSuper = true)` 추가
  - [ ] **JPA 어노테이션 사용 금지** (@Entity, @Table, @Column 등)
  - [ ] 컬럼 매핑 정보는 주석으로 명시

- [ ] **Repository 구현** (`jobs/{domain}/batch/repository/` 패키지)
  - [ ] 인터페이스 생성 (예: `ShipRepository`)
  - [ ] 구현체 생성 (예: `ShipRepositoryImpl`)
  - [ ] `BaseJdbcRepository` 상속 (JDBC 전용)
  - [ ] `getTableName()`, `getInsertSql()`, `getUpdateSql()` 구현
  - [ ] `setInsertParameters()`, `setUpdateParameters()` 구현
  - [ ] `getRowMapper()` 구현 (RowMapper 클래스 생성)
  - [ ] 커스텀 쿼리 메서드 정의

- [ ] **Reader 구현** (`jobs/{domain}/batch/reader/` 패키지)
  - [ ] `BaseApiReader` 상속
  - [ ] `getApiPath()` 구현
  - [ ] `extractDataFromResponse()` 구현
  - [ ] `getResponseType()` 구현
  - [ ] `getReaderName()` 구현

- [ ] **Processor 구현** (`jobs/{domain}/batch/processor/` 패키지)
  - [ ] `BaseProcessor` 상속
  - [ ] `transform()` 구현 (DTO → Entity 변환)
  - [ ] `shouldProcess()` 구현 (필터링 로직)
  - [ ] `getProcessorName()` 구현

- [ ] **Writer 구현** (`jobs/{domain}/batch/writer/` 패키지)
  - [ ] `BaseWriter` 상속
  - [ ] `writeItems()` 구현 (Repository 호출)
  - [ ] `getWriterName()` 구현

- [ ] **JobConfig 구현** (`jobs/{domain}/batch/config/` 패키지)
  - [ ] `BaseJobConfig` 상속
  - [ ] `getJobName()` 구현
  - [ ] `createReader()` 구현
  - [ ] `createProcessor()` 구현
  - [ ] `createWriter()` 구현
  - [ ] `getChunkSize()` 구현 (선택사항, 기본값: 100)
  - [ ] `@Bean` 메서드로 Job과 Step 등록

### 10.2 선택 구현 항목

- [ ] **웹 API 구현** (REST API 제공 시)
  - [ ] **DTO 생성** (`jobs/{domain}/web/dto/` 패키지)
    - [ ] `BaseDto` 상속 (웹 전용 DTO)
  - [ ] **Service 구현** (`jobs/{domain}/web/service/` 패키지)
    - [ ] `BaseServiceImpl` 상속 (JDBC 기반)
    - [ ] `getRepository()` 구현 (배치 Repository 재사용)
    - [ ] `toDto()`, `toEntity()` 구현
    - [ ] CRUD 메서드 오버라이드 (필요 시)
  - [ ] **Controller 구현** (`jobs/{domain}/web/controller/` 패키지)
    - [ ] `BaseController` 상속
    - [ ] `@RequestMapping` 설정
    - [ ] 커스텀 API 추가 (필요 시)

- [ ] **에러 핸들링**
  - [ ] `BaseApiReader.handleApiError()` 오버라이드
  - [ ] `BaseProcessor.handleProcessError()` 오버라이드
  - [ ] `BaseWriter.handleWriteError()` 오버라이드

- [ ] **로깅 강화**
  - [ ] `beforeApiCall()`, `afterApiCall()` 구현
  - [ ] `beforeProcess()`, `afterProcess()` 구현
  - [ ] `beforeWrite()`, `afterWrite()` 구현

### 10.3 테스트 항목

- [ ] **단위 테스트**
  - [ ] Reader 테스트 (API 모킹)
  - [ ] Processor 테스트 (변환 로직 검증)
  - [ ] Writer 테스트 (Repository 모킹)

- [ ] **통합 테스트**
  - [ ] Job 실행 테스트
  - [ ] 데이터베이스 저장 검증

- [ ] **성능 테스트**
  - [ ] 대용량 데이터 처리 테스트
  - [ ] Chunk 크기 최적화

---

---

## 📚 관련 문서

### 핵심 문서
- **[README.md](README.md)** - 프로젝트 개요 및 빠른 시작 가이드
- **[CLAUDE.md](CLAUDE.md)** - 프로젝트 형상관리 문서 (세션 연속성)
- **[SWAGGER_GUIDE.md](SWAGGER_GUIDE.md)** - Swagger API 문서 사용 가이드

### 아키텍처 문서
- **[docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)** - 프로젝트 아키텍처 상세 설계
- **[docs/architecture/PROJECT_STRUCTURE.md](docs/architecture/PROJECT_STRUCTURE.md)** - Job 중심 패키지 구조 가이드

### 구현 가이드
- **[docs/guides/PROXY_SERVICE_GUIDE.md](docs/guides/PROXY_SERVICE_GUIDE.md)** - 외부 API 프록시 패턴 구현 가이드
- **[docs/guides/SHIP_API_EXAMPLE.md](docs/guides/SHIP_API_EXAMPLE.md)** - Maritime API 연동 실전 예제

### 보안 문서
- **[docs/security/README.md](docs/security/README.md)** - 보안 전략 개요 (계획 단계)

---

**마지막 업데이트**: 2025-10-16
**버전**: 1.3.0

---

## 변경 이력

### v1.3.0 (2025-10-16)
- ✅ 프로젝트 구조를 현행화: `common/batch/`와 `common/web/` 분리 반영
- ✅ jobs 패키지 구조 업데이트: `batch/`와 `web/` 서브패키지 구조 반영
- ✅ 모든 Base 클래스 위치 경로 수정 (common.base → common.batch/web)
- ✅ JDBC vs JPA 사용 구분 명확화 (jobs는 JDBC 전용, global은 JPA 허용)
- ✅ Entity 예제 업데이트: JPA 어노테이션 제거, 주석 기반 매핑 설명 추가
- ✅ 체크리스트 강화: 패키지 구조, Repository 구현, 웹 API 구현 세분화

### v1.2.0 (2025-10-15)
- 문서 간 상호 참조 링크 추가
- 관련 문서 섹션 추가

### v1.1.0 (2025-10-14)
- 추상화 클래스 체크리스트 추가
- 예제 코드 개선

### v1.0.0 (2025-10-13)
- 초기 버전 작성