clean-parking/README_BATCH.md

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)

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 기반의 표준적이면서도 확장성/안정성이 뛰어난 배치 관리 시스템입니다.
각 계층별 상세 코드/쿼리/설정은 소스 내 각 파일을 참고하세요.

---

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