# XIT 배치 시스템 구조 및 가이드 (2025 최신)

## 1. 전체 아키텍처

```
┌──────────────────────────────────────────────┐
│                REST API (Controller)        │
│                └─ BatchJobController        │
├──────────────────────────────────────────────┤
│           Service Layer (비즈니스 로직)       │
│   ├─ BatchJobService (Interface)            │
│   └─ BatchJobServiceImpl (구현)             │
├──────────────────────────────────────────────┤
│           Data Access Layer                  │
│   └─ BatchJobMapper (MyBatis Mapper)         │
│   └─ BatchJobMapper_maria.xml (SQL)          │
├──────────────────────────────────────────────┤
│           Model Layer                        │
│   ├─ BatchJobInfoVO (작업 정보)              │
│   ├─ BatchJobExecutionVO (실행 결과)         │
│   ├─ BatchJobLogVO (실행 로그)               │
│   └─ BatchJobResult (실행 결과 Enum/VO)      │
├──────────────────────────────────────────────┤
│           Job Layer (실제 배치 작업)          │
│   └─ SampleBatchJob 등 (Quartz Job)          │
├──────────────────────────────────────────────┤
│           Listener/Util Layer                │
│   ├─ QuartzJobListener (실행 추적)           │
│   └─ BatchJobLogUtil (로그 기록)             │
├──────────────────────────────────────────────┤
│           Configuration Layer                │
│   ├─ BatchJobInitializer (초기화)            │
│   ├─ QuartzConfig, QuartzListenerConfig      │
└──────────────────────────────────────────────┘
```

---

## 2. 주요 디렉토리/파일 구조

- **src/main/java/go/kr/project/batch/**
  - **controller/**: `BatchJobController.java` (화면)
  - **service/**: `BatchJobService.java` (interface), `impl/BatchJobServiceImpl.java` (구현)
  - **mapper/**: `BatchJobMapper.java` (MyBatis interface)
  - **model/**: `BatchJobInfoVO.java`, `BatchJobExecutionVO.java`, `BatchJobLogVO.java`, `BatchJobResult.java`
  - **job/**: `SampleBatchJob.java` 등 (Quartz Job 구현)
  - **config/**: `BatchJobInitializer.java`, `QuartzConfig.java`, `QuartzListenerConfig.java`
  - **util/**: `BatchJobLogUtil.java`, `ServerInfoUtil.java`
- **src/main/resources/mybatis/mapper/batch/**
  - `BatchJobMapper_maria.xml` (MyBatis SQL)
- **src/main/resources/**
  - `application-local.yml`, `application-dev.yml`, `application-prd.yml` (환경별 설정)
- **src/main/webapp/WEB-INF/views/batch/**
  - `list.jsp`, `execution.jsp`, `log.jsp`, `batchJobForm_layerPop.jsp` (화면 JSP)

---

## 3. 데이터 모델

### BatchJobInfoVO (배치 작업 정보)
- jobId (UUID)
- jobName, jobGroup, jobClass
- cronExpression, description
- status (ACTIVE, PAUSED, DELETED)
- lastExecutionId
- regDt, mdfcnDt

### BatchJobExecutionVO (실행 결과)
- executionId (UUID)
- jobName, jobGroup
- startTime, endTime
- status (STARTED, COMPLETED, FAILED, VETOED)
- exitCode (COMPLETED, FAILED, UNKNOWN)
- exitMessage
- regDt

### BatchJobLogVO (실행 로그)
- logId
- executionId
- logTime
- logLevel (INFO, WARN, ERROR)
- logMessage
- regDt

---

## 4. 주요 테이블

- **TB_BATCH_JOB_INFO**: 배치 작업 메타데이터 (cron, 상태, 설명 등)
- **TB_BATCH_JOB_EXECUTION**: 각 배치 작업의 실행 결과 (시작/종료, 상태, 메시지 등)
- **TB_BATCH_JOB_LOG**: 실행 로그 (레벨, 메시지 등)

---

## 5. 주요 컴포넌트 및 역할

### Controller
- **BatchJobController**: 배치 작업/실행/로그 관리 REST API 및 화면 제공

### Service
- **BatchJobService**: 배치 작업 등록/수정/삭제/실행/일시중지/재개/목록/실행결과/로그 등 비즈니스 로직
- **BatchJobServiceImpl**: Quartz Scheduler, Mapper 연동, 트랜잭션 처리

### Mapper
- **BatchJobMapper**: 작업/실행/로그 CRUD, 상태/마지막 실행ID 관리 (MyBatis)
- **BatchJobMapper_maria.xml**: 실제 SQL 정의

### Listener/Util
- **QuartzJobListener**: Job 실행 전후 DB 기록, 상태 갱신, 로그 기록
- **BatchJobLogUtil**: Job 실행 중 로그 기록 (INFO/WARN/ERROR)

### Job
- **SampleBatchJob 등**: 실제 배치 로직 구현, 동시 실행 방지(@DisallowConcurrentExecution)

### Config
- **BatchJobInitializer**: 애플리케이션 시작 시 DB에서 작업 목록을 읽어 Quartz에 등록
- **QuartzConfig, QuartzListenerConfig**: Quartz 및 리스너 설정

---

## 6. 주요 API (BatchJobController)

- `GET /batch/list.do` : 배치 작업 목록 화면
- `POST /batch/list.ajax` : 배치 작업 목록 데이터
- `POST /batch/register.ajax` : 배치 작업 등록
- `POST /batch/trigger.ajax` : 작업 즉시 실행
- `POST /batch/pause.ajax` : 작업 일시 중지
- `POST /batch/resume.ajax` : 작업 재개
- `POST /batch/delete.ajax` : 작업 삭제
- `GET /batch/execution.do` : 실행 결과 화면
- `POST /batch/execution.ajax` : 실행 결과 목록
- `GET /batch/log.do` : 실행 로그 화면
- `POST /batch/log.ajax` : 실행 로그 목록

---

## 7. 배치 작업 등록/실행/관리 흐름

### 배치 작업 등록
1. Controller → Service.scheduleJob()
2. Service → Quartz Scheduler.scheduleJob()
3. Service → Mapper.insertBatchJobInfo()
4. (Quartz) → Job.execute() (스케줄에 따라 실행)

### 배치 작업 실행
1. Quartz Scheduler → Job.execute()
2. Job → 비즈니스 로직 수행
3. Listener/Util → Mapper.insertBatchJobExecution() (시작)
4. Listener/Util → Mapper.updateBatchJobExecution() (완료)
5. Listener/Util → Mapper.insertBatchJobLog() (로그)

### 배치 작업 상태/삭제/일시중지/재개
- Service에서 Quartz Scheduler와 DB 상태를 동기화하며 처리

---

## 8. 설정 예시 (application-*.yml)

```yaml
spring:
  quartz:
    job-store-type: jdbc
    jdbc:
      initialize-schema: never
    properties:
      org.quartz.scheduler.instanceName: XitClusteredScheduler
      org.quartz.scheduler.instanceId: AUTO
      org.quartz.jobStore.class: org.quartz.impl.jdbcjobstore.JobStoreTX
      org.quartz.jobStore.isClustered: true
      org.quartz.jobStore.tablePrefix: QRTZ_
      org.quartz.threadPool.threadCount: 10
mybatis:
  config-location: classpath:mybatis/mybatis-config.xml
  mapper-locations: classpath:mybatis/mapper/**/*_${Globals.DbType}.xml
```
- DB, 로그, 파일업로드 등 환경별로 `application-local.yml`, `application-dev.yml`, `application-prd.yml`에서 관리

---

## 9. 화면(JSP) 구성

- **list.jsp**: 배치 작업 목록 및 관리
- **execution.jsp**: 작업 실행 결과 조회
- **log.jsp**: 실행 로그 상세 조회
- **batchJobForm_layerPop.jsp**: 작업 등록/수정 팝업

---

## 10. 확장/운영 팁

- 신규 배치 작업은 `job/` 패키지에 Job 구현체 추가 후 등록
- Cron 표현식, 상태 등은 DB/화면에서 동적으로 관리
- 실행 결과/로그는 화면 및 API로 실시간 모니터링 가능
- 클러스터 환경 지원(Quartz + JDBC JobStore)
- 동시 실행 방지, 예외처리, 실행 로그 추적 등 안정성 확보

---

본 시스템은 Spring Boot + Quartz + MyBatis 기반의 표준적이면서도 확장성/안정성이 뛰어난 배치 관리 시스템입니다.  
각 계층별 상세 코드/쿼리/설정은 소스 내 각 파일을 참고하세요.

---

필요시, 각 계층별 상세 예시/코드/쿼리/설정 추가 가능합니다.  
추가 요청 시 구체적으로 말씀해 주세요!