Actions

History

About-batch » History » Revision 5

« Previous | Revision 5/15 (diff) | Next »
길호 원, 12/15/2025 03:22 PM

ESI NextGen Batch 시스템 인수인계 문서¶

1. 프로젝트 개요¶

1.1 프로젝트 정보¶

프로젝트명: ESI NextGen Batch
버전: 0.0.1-SNAPSHOT
프로젝트 타입: Spring Batch 기반 배치 처리 시스템
주요 목적: ESI(전자상거래 결제 시스템)의 다양한 배치 작업 자동화 처리

1.2 주요 기능¶

채권 발행 및 취소 처리 배치
장려금/수수료 정산 배치
원장 대사 파일 처리 배치
전문 재거래 처리 배치
알림톡 발송 배치
오류 알림 배치

2. 기술 스택¶

2.1 개발 환경¶

Java: 21
Build Tool: Gradle
Spring Boot: 3.4.4
Spring Batch: 5.x (Spring Boot Starter 포함)
Database: MySQL 8.0.33
ORM: MyBatis 3.0.4

2.2 주요 의존성¶

- Spring Boot Starter Batch
- Spring Boot Starter Web
- Spring Boot Starter WebFlux (WebClient)
- Spring Boot Starter Actuator (모니터링)
- Spring Boot Starter JDBC
- Spring Boot Starter Validation
- MyBatis Spring Boot Starter (3.0.4)
- MySQL Connector (8.0.33)
- Lombok
- Apache Commons Lang3 (3.12.0)
- Apache HttpClient5 (5.4.1)
- JSON (20190722)
- Micrometer Core (모니터링)
- Micrometer Observation (모니터링)

2.3 개발 도구¶

IDE: IntelliJ IDEA / Eclipse
Version Control: Git
Repository
- Git (http://192.168.245.41:9090/next-esi/batch)
Jenkins: http://192.168.245.41:8083

3. 프로젝트 구조¶

3.1 디렉토리 구조¶

src/main/java/com/esi/nextgen/batch/
├── BatchApplication.java          # 메인 애플리케이션 클래스
├── bizcom/                         # 비즈니스 공통 모듈
│   ├── constants/                  # 상수 정의
│   ├── mapper/                     # MyBatis Mapper 인터페이스
│   ├── model/                     # 도메인 모델
│   ├── service/                   # 비즈니스 서비스
│   ├── util/                      # 유틸리티
│   └── vo/                        # Value Object
├── common/                         # 공통 모듈
│   ├── annotation/                # 커스텀 어노테이션
│   ├── config/                     # 공통 설정
│   ├── constants/                  # 공통 상수
│   ├── listener/                   # 배치 리스너
│   ├── surem/                      # 알림톡/SMS 메시지 관련
│   └── util/                      # 공통 유틸리티
├── comp/                           # 원장 대사 관련
│   ├── config/                     # 대사 배치 설정
│   ├── controller/                 # 대사 컨트롤러
│   ├── mapper/                     # 대사 Mapper
│   ├── model/                      # 대사 모델
│   ├── scheduler/                  # 대사 스케줄러
│   ├── service/                    # 대사 서비스
│   └── vo/                         # 대사 VO
├── config/                         # 배치 설정 클래스
│   ├── BatchCronConfig.java        # Cron 표현식 설정
│   ├── BatchFnstProperties.java    # 금융기관 코드 설정
│   ├── DBBatchConfig.java          # DB 배치 설정
│   └── [각 배치별 Config 클래스들]
├── constants/                      # 상수 정의
│   ├── BatchFileInfo.java          # 배치 파일 정보
│   ├── BatchFileLayout.java        # 배치 파일 레이아웃
│   ├── CompChckArtc.java           # 대사 체크 아티클
│   └── PrcAppConstants.java        # 프로세스 앱 상수
├── controller/                     # REST API 컨트롤러
├── dbio/                           # DB I/O 모듈
│   ├── mapper/                     # DB Mapper 인터페이스
│   └── model/                      # DB 모델 (DTO)
├── mapper/                         # 비즈니스 Mapper
├── model/                          # 비즈니스 모델
├── scheduler/                      # 스케줄러 클래스
├── service/                        # 서비스 클래스
└── vo/                             # Value Object

3.2 리소스 구조¶

src/main/resources/
├── application.yml                 # 기본 설정 파일
├── application-local.yml           # 로컬 환경 설정
├── application-F218.yml            # F218 환경 설정
├── logback-spring.xml              # 로깅 설정
└── mapper/                         # MyBatis XML Mapper
    ├── bizcom/                     # 비즈니스 공통
    ├── bond/                       # 채권 관련
    ├── clcln/                      # 정산 관련
    ├── comp/                       # 대사 관련
    ├── dbio/                       # DB I/O
    ├── info/                       # 정보 관련
    ├── mp/                         # MP 관련
    ├── noti/                       # 알림 관련
    └── test/                       # 테스트

4. 주요 배치 작업 목록¶

4.1 전문 거래 내역 배치¶

배치명	Job 이름	설명	실행 주기
전문 재거래	telgmReDlngJob	실패한 전문 재전송 처리	매 2분마다 8시~23시 (F218) / 매월 1일 0시 (로컬)

4.2 채권 발행 배치¶

배치명	Job 이름	설명	실행 주기
외상매출채권발행처리	osbndPblcnRprcsScheduler01Job	외상매출채권 발행 처리	월~~금 8시~~21시 매 1분 (F218) / 매월 1일 0시 (로컬)
외상매출채권선결제처리	osbndAdvpayScheduler01Job	외상매출채권 선결제 처리	월~~금 8시~~18시 매 1분 (F218) / 매월 1일 0시 (로컬)
외매채 즉시취소	prcOsbndRtrcnDlngSe01Job	외상매출채권 즉시 취소	월~~금 8시~~20시 매 1분 30초 (F218) / 매월 1일 0시 (로컬)
외매채 취소요청	prcOsbndRtrcnDlngSe02Job	외상매출채권 취소 요청 처리	월~~금 8시~~20시 매 1분 30초 (F218) / 매월 1일 0시 (로컬)
상매채 즉시취소	wwSlsBndRtrcnDlngSe01Job	상생매출채권 즉시 취소	월~~금 8시~~20시 매 1분 30초 (F218) / 매월 1일 0시 (로컬)
상매채 취소요청	wwSlsBndRtrcnDlngSe02Job	상생매출채권 취소 요청 처리	월~~금 8시~~20시 매 1분 30초 (F218) / 매월 1일 0시 (로컬)
채권 수취 후 예약 발행	addrBfPblcnRsvtJob	채권 수취 후 예약 발행 처리	매일 8시~21시 매 정시 (F218) / 매월 1일 0시 (로컬)
수취채권 예약 발행	addrBndRsvtPblcnJob	수취채권 예약 발행	매일 8시~20시 59분 매 1분 (F218) / 매월 1일 0시 (로컬)
수취채권 즉시 발행	addrBndNowPblcnJob	수취채권 즉시 발행	매일 8시~20시 59분 매 1분 (F218) / 매월 1일 0시 (로컬)
수취채권 발행 전 결재선 내역 승인기한 체크	addrBfPblcnAplnJob	발행 전 결재선 승인기한 체크	매일 20시 (F218) / 매월 1일 0시 (로컬)
채권 수취전 발행 요청일 만료 처리	dmndExpryAddrBfPblcnRsvtJob	만료된 발행 신청 원장 처리	매일 22시 (F218) / 매월 1일 0시 (로컬)

4.3 정산 배치¶

배치명	Job 이름	설명	실행 주기
장려금배분	aprtSubsdJob	장려금 배분 처리	매 5분마다 (F218) / 매월 1일 0시 (로컬)
장려금정산이체처리	prcsSubsdClclnTrJob	장려금 정산 이체 처리	매 2분마다 (F218) / 매일 8시 (로컬)
운영수수료정산	operFeeClclnJob	운영 수수료 정산	매월 1일 20시 (F218) / 매월 1일 0시 (로컬)
MP수수료정산	mpFeeClclnJob	MP 수수료 정산	매월 1일 20시 (F218) / 매월 1일 0시 (로컬)

4.4 원장 대사 배치¶

배치명	Job 이름	설명	실행 주기
원장대사 전문거래내역관리	dlngCompFileAllRegJob	원장 대사 전문거래내역 관리	매일 1시 30분 (F218) / 매월 1일 0시 (로컬)
예치금잔액대사	dlngCompFile00Job	예치금 잔액 대사	매일 2시 (F218) / 매분 14초 (로컬)
구매기업원장_원장대사	dlngCompFile01Job	구매기업 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
구매기업지사정보_원장대사	dlngCompFile02Job	구매기업 지사정보 대사	매일 2시 (F218) / 매분 29초 (로컬)
협력기업원장_원장대사	dlngCompFile11Job	협력기업 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
거래선원장_원장대사	dlngCompFile12Job	거래선 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
외상매출채권원장_원장대사	dlngCompFile21Job	외상매출채권 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
상생매출채권원장_원장대사	dlngCompFile22Job	상생매출채권 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
대출약정원장_원장대사	dlngCompFile31Job	대출약정 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
대출실행원장_원장대사	dlngCompFile32Job	대출실행 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)
거래원장대사	dlngCompInsdGnlgrJob	거래 원장 대사	매일 2시 (F218) / 매분 29초 (로컬)

4.5 기타 배치¶

배치명	Job 이름	설명	실행 주기
만기결제집계정보	mtryStlmTotInfoJob	만기결제 집계 정보 처리	월~금 7시 (F218) / 매월 1일 0시 (로컬)
(구매기업)결재기한 만료 처리	aprvnTermExpSchedulerJob01	결재기한 만료 처리	매일 21시 30분 (F218) / 매월 1일 0시 (로컬)
관리자MP관리	adminMpMngScheduler01Job	관리자 MP 관리 처리	매 정시 (F218) / 매월 1일 0시 (로컬)
대출연장안내	loanPrlgGdJob	대출연장 안내 알림톡 발송	월~금 9시 (F218) / 매월 1일 0시 (로컬)
고객확인재등록안내	custIdntyRrgGdJob	고객확인재등록 안내 알림톡 발송	월~금 9시 (F218) / 매월 1일 0시 (로컬)
오류알림	errorNotificationJob	전문/대사 오류 알림 발송	평일 08~22시 매 5분

5. 설정 파일 설명¶

5.1 application.yml¶

주요 설정 항목:

데이터베이스 연결 정보: MySQL 연결 설정
HikariCP 커넥션 풀: 최대 60개 연결, 최소 5개 유휴 연결
서버 포트: 8090
Context Path: /batch
MyBatis 설정: Mapper 위치, Type Handler 패키지
클라이언트 서비스 URL: 각 마이크로서비스 엔드포인트
대사파일 경로: /data1/adapter/files/
백업 설정: 날짜별 폴더 사용

5.2 application-local.yml¶

로컬 개발 환경 설정:

배치 금융기관 코드: 218
대사파일 경로: D:/Documents/ESI/batch/
배치 Cron 표현식: 각 배치별 실행 주기 설정

5.3 배치 Cron 설정 위치¶

모든 배치의 Cron 표현식은 application-local.yml 또는 환경별 설정 파일(application-F218.yml 등)의 batch.cron 섹션에 정의되어 있습니다.

주의사항:

로컬 환경과 운영 환경(F218)의 Cron 설정이 다를 수 있습니다.
로컬 환경은 개발/테스트를 위해 더 자주 실행되도록 설정되어 있습니다.
실제 운영 환경의 실행 주기는 application-F218.yml을 참조하세요.

6. 실행 방법¶

6.1 로컬 개발 환경 실행¶

# Gradle Wrapper를 사용한 실행
./gradlew bootRun

# 또는 특정 프로파일 지정
./gradlew bootRun --args='--spring.profiles.active=local'

# 특정 배치 작업 실행
java -jar build/libs/batch-0.0.1-SNAPSHOT.jar --job.name=218_telgmReDlngJob

6.2 빌드¶

# JAR 파일 빌드
./gradlew build

# 빌드된 JAR 파일 위치
build/libs/batch-0.0.1-SNAPSHOT.jar

6.3 프로덕션 실행¶

# 프로파일 지정하여 실행
java -jar batch-0.0.1-SNAPSHOT.jar --spring.profiles.active=F218

# 특정 배치 작업 실행
java -jar batch-0.0.1-SNAPSHOT.jar --spring.profiles.active=F218 --job.name=218_telgmReDlngJob

6.4 IDE에서 특정 Job 실행¶

TestJobRunner
- profile 설정 필요
  - 환경변수: SPRING_PROFILES_ACTIVE=local
- Job name 설정 후 실행

  @Qualifier("dlngCompFile00Job") Job runJob

6.4 REST API를 통한 배치 실행¶

각 배치 작업은 REST API를 통해 수동 실행 가능합니다.

컨트롤러 위치: src/main/java/com/esi/nextgen/batch/controller/
예시: POST /batch/api/subsd-clcln/execute

7. 주요 기능 상세 설명¶

7.1 배치 작업 구조¶

각 배치 작업은 다음 구조로 구성됩니다:

Scheduler: Cron 스케줄러로 배치 실행 트리거
Config: Spring Batch Job/Step 설정
Service: 실제 비즈니스 로직 처리
Mapper: 데이터베이스 쿼리 실행

7.2 금융기관 코드 관리¶

각 배치 작업은 금융기관 코드를 포함한 고유한 Job 이름을 가집니다.
예: 218_telgmReDlngJob (218은 금융기관 코드)
BatchJobNameUtil을 통해 Job 이름 생성 및 관리

7.3 원장 대사 파일 처리¶

대사 파일은 base_path + 금융기관코드 경로에서 읽습니다.
처리 완료된 파일은 백업 폴더로 이동됩니다.
대사 파일 레이아웃은 BatchFileLayout에 정의되어 있습니다.

7.4 전문 재거래 처리¶

실패한 전문은 telgm.re-dlng-codes에 정의된 전문 코드만 재처리됩니다.
재처리 대상 전문 코드는 application.yml에서 설정 가능합니다.

7.5 오류 알림¶

ErrorNotificationService가 전문 오류를 감지하여 운영자에게 알림을 발송합니다.
대사 오류는 대사 배치에서 진행합니다.
알림톡 발송은 Surem API를 통해 처리됩니다.

8. 데이터베이스¶

8.1 데이터베이스 정보¶

데이터베이스: MySQL 8.0.33
연결 정보: application.yml 참조
스키마: nextesi

8.2 Spring Batch 메타데이터¶

Spring Batch는 자동으로 메타데이터 테이블을 생성합니다 (spring.batch.jdbc.initialize-schema: always 설정).

테이블명	역할	주요 컬럼	설명
`BATCH_JOB_INSTANCE`	Job 인스턴스 정보 저장	JOB_INSTANCE_ID, JOB_NAME, JOB_KEY, VERSION	Job의 논리적 실행 단위를 나타냄. 동일한 Job 이름과 파라미터 조합은 하나의 인스턴스로 관리
`BATCH_JOB_EXECUTION`	Job 실행 정보 저장	JOB_EXECUTION_ID, JOB_INSTANCE_ID, START_TIME, END_TIME, STATUS, EXIT_CODE, EXIT_MESSAGE	Job의 실제 실행 이력을 저장. 시작/종료 시간, 상태, 종료 코드 등 기록
`BATCH_JOB_EXECUTION_PARAMS`	Job 실행 파라미터 저장	JOB_EXECUTION_ID, TYPE_CD, KEY_NAME, STRING_VAL, DATE_VAL, LONG_VAL, DOUBLE_VAL, IDENTIFYING	Job 실행 시 전달된 파라미터 정보 저장
`BATCH_STEP_EXECUTION`	Step 실행 정보 저장	STEP_EXECUTION_ID, VERSION, STEP_NAME, JOB_EXECUTION_ID, START_TIME, END_TIME, STATUS, COMMIT_COUNT, READ_COUNT, FILTER_COUNT, WRITE_COUNT, READ_SKIP_COUNT, WRITE_SKIP_COUNT, PROCESS_SKIP_COUNT, ROLLBACK_COUNT, EXIT_CODE, EXIT_MESSAGE, LAST_UPDATED	Step의 실행 이력 저장. 읽기/쓰기 건수, 스킵 건수, 롤백 건수 등 상세 정보 기록
`BATCH_STEP_EXECUTION_CONTEXT`	Step 실행 컨텍스트 저장	STEP_EXECUTION_ID, SHORT_CONTEXT, SERIALIZED_CONTEXT	Step 실행 중 사용되는 컨텍스트 데이터 저장 (상태 정보, 중간 데이터 등)
`BATCH_JOB_EXECUTION_CONTEXT`	Job 실행 컨텍스트 저장	JOB_EXECUTION_ID, SHORT_CONTEXT, SERIALIZED_CONTEXT	Job 실행 중 사용되는 컨텍스트 데이터 저장 (Step 간 공유 데이터 등)
`BATCH_JOB_SEQ`	Job 인스턴스 시퀀스	ID	Job 인스턴스 ID 생성용 시퀀스
`BATCH_JOB_EXECUTION_SEQ`	Job 실행 시퀀스	ID	Job 실행 ID 생성용 시퀀스
`BATCH_STEP_EXECUTION_SEQ`	Step 실행 시퀀스	ID	Step 실행 ID 생성용 시퀀스

참고사항:

모든 메타데이터 테이블은 Spring Batch가 자동으로 생성 및 관리합니다.
Job 재실행 시 동일한 Job 인스턴스는 재사용되며, 새로운 Job Execution이 생성됩니다.
컨텍스트 테이블은 직렬화된 객체를 저장하므로 대용량 데이터 저장 시 주의가 필요합니다.

8.3 배치 Job별 관련 테이블 및 CRUD 작업¶

8.3.1 전문 거래 내역 배치¶

전문 재거래 (telgmReDlngJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_TELGM_DLNG_DTL_BC`	전문거래내역	✅	-	-	-

8.3.2 채권 발행 배치¶

외상매출채권발행처리 (osbndPblcnRprcsScheduler01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_OSBND_PBAPLY_GL_BC`	외상매출채권발행신청원장	✅	-	✅	-
`TB_PRC_OSBND_PBAPLY_DTL_TR`	외상매출채권발행신청내역	✅	-	✅	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-

외상매출채권선결제처리 (osbndAdvpayScheduler01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_MTRY_STLM_TOT_SM`	만기결제집계정보	✅	-	✅	-
`TB_PRC_OSBND_STLM_DTL_TR`	외상매출채권결제내역	✅	-	✅	-

외매채 즉시취소 (prcOsbndRtrcnDlngSe01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_OSBND_RCNAPLY_GL_BC`	외상매출채권발행취소신청원장	✅	-	✅	-
`TB_PRC_OSBND_RCNAPLY_DTL_TR`	외상매출채권발행취소신청내역	✅	-	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	✅	-

외매채 취소요청 (prcOsbndRtrcnDlngSe02Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_OSBND_RCNAPLY_GL_BC`	외상매출채권발행취소신청원장	✅	-	✅	-
`TB_PRC_OSBND_RCNAPLY_DTL_TR`	외상매출채권발행취소신청내역	✅	-	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	✅	-

상매채 즉시취소 (wwSlsBndRtrcnDlngSe01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_RCNAPLY_GL_BC`	상생매출채권발행취소신청원장	✅	-	✅	-
`TB_CLB_WSBND_RCNAPLY_DTL_TR`	상생매출채권발행취소신청내역	✅	-	✅	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	✅	-

상매채 취소요청 (wwSlsBndRtrcnDlngSe02Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_RCNAPLY_GL_BC`	상생매출채권발행취소신청원장	✅	-	✅	-
`TB_CLB_WSBND_RCNAPLY_DTL_TR`	상생매출채권발행취소신청내역	✅	-	✅	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	✅	-

채권 수취 후 예약 발행 (addrBfPblcnRsvtJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_PBAPLY_GL_BC`	상생매출채권발행신청원장	✅	-	✅	-
`TB_CLB_WSBND_PBAPLY_DTL_TR`	상생매출채권발행신청내역	✅	-	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-

수취채권 예약 발행 (addrBndRsvtPblcnJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_PBAPLY_GL_BC`	상생매출채권발행신청원장	✅	-	✅	-
`TB_CLB_WSBND_PBAPLY_DTL_TR`	상생매출채권발행신청내역	✅	-	✅	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-

수취채권 즉시 발행 (addrBndNowPblcnJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_PBAPLY_GL_BC`	상생매출채권발행신청원장	✅	-	✅	-
`TB_CLB_WSBND_PBAPLY_DTL_TR`	상생매출채권발행신청내역	✅	-	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	-	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-
`TB_CLB_NTSL_ENT_BROF_BC`	협력기업지사정보	✅	-	-	-
`TB_COM_TASK_CTRL_INFO_BC`	업무제어정보	✅	-	-	-
`TB_PRC_PRCHS_ENT_GL_BC`	구매기업원장	✅	-	-	-
`TB_CLB_CUST_GL_BC`	고객원장	✅	-	-	-

수취채권 발행 전 결재선 내역 승인기한 체크 (addrBfPblcnAplnJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_PBAPLY_GL_BC`	상생매출채권발행신청원장	✅	-	✅	-
`TB_CLB_WSBND_PBAPLY_DTL_TR`	상생매출채권발행신청내역	✅	-	✅	-
`TB_COM_MP_APLN_LIST_BC`	MP결재선목록	✅	-	-	-

채권 수취전 발행 요청일 만료 처리 (dmndExpryAddrBfPblcnRsvtJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_WSBND_PBAPLY_GL_BC`	상생매출채권발행신청원장	✅	-	✅	-
`TB_CLB_WSBND_PBAPLY_DTL_TR`	상생매출채권발행신청내역	✅	-	✅	-

(구매기업)결재기한 만료 처리 (aprvnTermExpSchedulerJob01)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_OSBND_PBAPLY_GL_BC`	외상매출채권발행신청원장	✅	-	✅	-
`TB_PRC_OSBND_PBAPLY_DTL_TR`	외상매출채권발행신청내역	✅	-	-	-
`TB_COM_MP_APLN_LIST_BC`	MP결재선목록	✅	-	✅	-

8.3.3 정산 배치¶

장려금배분 (aprtSubsdJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_MNG_SUBSD_DEDTL_TR`	장려금세부내역	✅	✅	✅	-
`TB_MNG_CLCLN_GL_BC`	정산원장	✅	-	-	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	-	-
`TB_CLB_WW_SLS_BND_PBLCN_TRGT`	상생매출채권발행장려금대상	✅	-	-	-
`TB_CLB_WW_SLS_BND_DSCNT_TRGT`	상생매출채권할인장려금대상	✅	-	-	-
`TB_CLB_WW_SLS_BND_SLCTN_MTN_TRGT`	상생매출채권선정산장려금대상	✅	-	-	-
`TB_CLB_LOAN_EXCN_GL_BC`	대출실행원장	✅	-	-	-
`TB_CLB_PCALL_DLNG_DTL_TR`	선정산거래내역	✅	-	-	-
`TB_CLB_LOAN_DLNG_DTL_TR`	대출거래내역	✅	-	-	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-
`TB_MNG_CLCLN_DTL_TR`	정산내역	✅	-	-	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-

장려금정산이체처리 (prcsSubsdClclnTrJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_MNG_CLCLN_GL_BC`	정산원장	✅	-	✅	-
`TB_MNG_CLCLN_DTL_TR`	정산내역	✅	-	✅	-
`TB_COM_BACNT_INFO_BC`	금융기관용도별계좌정보	✅	-	-	-

운영수수료정산 (operFeeClclnJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_MNG_CLCLN_GL_BC`	정산원장	✅	-	✅	-
`TB_MNG_CLCLN_DTL_TR`	정산내역	✅	✅	✅	-
`TB_COM_FEE_INFO_BC`	수수료정보	✅	-	-	-

MP수수료정산 (mpFeeClclnJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_MNG_CLCLN_GL_BC`	정산원장	✅	-	✅	-
`TB_MNG_CLCLN_DTL_TR`	정산내역	✅	✅	✅	-
`TB_COM_FEE_INFO_BC`	수수료정보	✅	-	-	-

8.3.4 원장 대사 배치¶

원장대사 전문거래내역관리 (dlngCompFileAllRegJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_TELGM_DLNG_DTL_BC`	전문거래내역	✅	-	-	✅

예치금잔액대사 (dlngCompFile00Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_PRC_PRCHS_ENT_STLM_ACT_BC`	구매기업결제계좌	✅	-	-	-

구매기업원장_원장대사 (dlngCompFile01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_PRC_PRCHS_ENT_GL_BC`	구매기업원장	✅	-	-	-

구매기업지사정보_원장대사 (dlngCompFile02Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_PRC_PRCHS_ENT_BROF_BC`	구매기업지사정보	✅	-	-	-

협력기업원장_원장대사 (dlngCompFile11Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-

거래선원장_원장대사 (dlngCompFile12Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-

외상매출채권원장_원장대사 (dlngCompFile21Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-

상생매출채권원장_원장대사 (dlngCompFile22Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	-	-

대출약정원장_원장대사 (dlngCompFile31Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_CLB_LOAN_STPL_GL_BC`	대출약정원장	✅	-	-	-

대출실행원장_원장대사 (dlngCompFile32Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	✅
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	✅	✅	-
`TB_CLB_LOAN_EXCN_GL_BC`	대출실행원장	✅	-	-	-

거래원장대사 (dlngCompInsdGnlgrJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_COMP_DSCTN_TR`	대사내역	✅	✅	✅	-
`TB_PRC_PRCHS_ENT_GL_BC`	구매기업원장	✅	-	-	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	-	-
`TB_CLB_LOAN_STPL_GL_BC`	대출약정원장	✅	-	-	-
`TB_CLB_LOAN_EXCN_GL_BC`	대출실행원장	✅	-	-	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-
`TB_PRC_PRCHS_ENT_BROF_BC`	구매기업지사정보	✅	-	-	-
`TB_PRC_PRCHS_ENT_STLM_ACT_BC`	구매기업결제계좌	✅	-	-	-
`TB_CLB_TXIV_APRT_DTL_TR`	세금계산서배분내역	✅	-	-	-
`TB_CLB_PCALL_DLNG_DTL_TR`	선정산거래내역	✅	-	-	-
`TB_CLB_LOAN_DLNG_DTL_TR`	대출거래내역	✅	-	-	-
`base_calendar`	기준일력	✅	-	-	-

8.3.5 기타 배치¶

만기결제집계정보 (mtryStlmTotInfoJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_PRC_MTRY_STLM_TOT_SM`	만기결제집계정보	✅	✅	✅	-
`TB_PRC_OSBND_STLM_DTL_TR`	외상매출채권결제내역	✅	-	✅	-
`TB_PRC_OSBND_GL_BC`	외상매출채권원장	✅	-	-	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-
`TB_CLB_LOAN_EXCN_GL_BC`	대출실행원장	✅	-	-	-
`TB_CLB_WW_SLS_BND_GL_BC`	상생매출채권원장	✅	-	-	-

관리자MP관리 (adminMpMngScheduler01Job)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_MP_NTC_TR`	MP공지사항	✅	-	✅	-
`TB_COM_MP_POPUP_MNG`	MP팝업관리	✅	-	✅	-
`TB_COM_UTZTN_TRMS_INFO_BC`	이용약관정보	✅	-	✅	-
`TB_COM_PRVC_TRMS_INFO_BC`	개인정보처리방침정보	✅	-	✅	-
`TB_COM_MKT_TRMS_INFO_BC`	마케팅정보수신동의정보	✅	-	✅	-
`TB_COM_STPLDOC_BC`	약정서	✅	-	✅	-

대출연장안내 (loanPrlgGdJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_LOAN_STPL_GL_BC`	대출약정원장	✅	-	-	-
`TB_CLB_LOAN_EXCN_GL_BC`	대출실행원장	✅	-	-	-
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-
`TB_COM_MP_MBR_BC`	MP회원	✅	-	-	-
`TB_COM_FNST_CD_BC`	금융기관코드	✅	-	-	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-

고객확인재등록안내 (custIdntyRrgGdJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_CLB_NTSL_ENT_GL_BC`	협력기업원장	✅	-	-	-
`TB_COM_MP_MBR_BC`	MP회원	✅	-	-	-
`TB_COM_HLDY_INFO_BC`	휴일정보	✅	-	-	-

오류알림 (errorNotificationJob)

테이블명	논리명	SELECT	INSERT	UPDATE	DELETE
`TB_COM_TELGM_DLNG_DTL_BC`	전문거래내역	✅	-	-	-
`TB_COM_COMP_GNLGR_BC`	대사원장	✅	-	-	-
`TB_COM_OPER_AVTSMT_INFO`	운영자 통지 정보	✅	-	-	-
`TB_COM_USER_INFO_BC`	사용자정보	✅	-	-	-
`TB_COM_CD_DSCTN_BC`	코드상세	✅	-	-	-

9. Logging & Monitoring¶

9.1 로그 설정¶

로그 파일 위치:

기본 경로: /usr/local/tomcat-batch/logs (또는 logging.file.dir 설정값)
로그 파일명: esisync-batch.log (또는 logging.file.name-base 설정값)
롤링 파일: esisync-batch-{yyyy-MM-dd}.{i}.log 형식으로 날짜별/크기별 롤링
로컬 환경: 파일 로그 없이 콘솔만 사용 (springProfile="local")
기타 환경: 콘솔 + 파일 로그 모두 사용

로그 설정 파일: logback-spring.xml

로그 파일 설정:

최대 파일 크기: 100MB
최대 보관 기간: 30일
전체 로그 크기 제한: 10GB
롤링 정책: 크기 + 시간 기반 (SizeAndTimeBasedRollingPolicy)

로그 확인 방법:

# 실시간 로그 확인
tail -f /usr/local/tomcat-batch/logs/esisync-batch.log

# 에러 로그만 확인
grep ERROR /usr/local/tomcat-batch/logs/esisync-batch.log

# 특정 배치 Job 로그 확인
grep "osbndPblcnRprcsScheduler01Job" /usr/local/tomcat-batch/logs/esisync-batch.log

# 최근 100줄 확인
tail -n 100 /usr/local/tomcat-batch/logs/esisync-batch.log

9.2 로그 레벨¶

기본 로그 레벨:

Root 로그 레벨: logging.level.root 설정값 (기본값: INFO)
애플리케이션 로그: com.esi.nextgen.batch 패키지
MyBatis 로그: org.mybatis, org.apache.ibatis 패키지

MyBatis SQL 로그:

application.yml에서 mybatis.configuration.log-impl 설정
기본값: org.apache.ibatis.logging.stdout.StdOutImpl (콘솔 출력)

로컬 환경 특수 설정:

상세 로그 레벨: com.esi.nextgen.batch 패키지 DEBUG 레벨
간단한 콘솔 패턴 사용 (날짜, thread, traceId 제거)
파일 로그 없음 (콘솔만)

9.3 모니터링¶

9.3.1 Spring Boot Actuator¶

의존성:

spring-boot-starter-actuator (build.gradle에 포함)
micrometer-core, micrometer-observation (메트릭 수집용)

기본 Actuator 엔드포인트 URL:

Base URL: http://localhost:8090/batch/actuator
Health Check: http://localhost:8090/batch/actuator/health
Info: http://localhost:8090/batch/actuator/info
Metrics: http://localhost:8090/batch/actuator/metrics
특정 메트릭 조회: http://localhost:8090/batch/actuator/metrics/{metricName}
- 예: http://localhost:8090/batch/actuator/metrics/jvm.memory.used
Prometheus (설정 시): http://localhost:8090/batch/actuator/prometheus

주요 메트릭:

JVM 메모리: jvm.memory.used, jvm.memory.max
JVM GC: jvm.gc.pause
HTTP 요청: http.server.requests
데이터베이스 연결 풀: hikari.connections.*
Spring Batch: spring.batch.*

9.3.2 Spring Batch Job 실행 모니터링¶

메타데이터 테이블을 통한 조회:

-- 최근 실행된 Job 목록
SELECT 
    JOB_EXECUTION_ID,
    JOB_NAME,
    STATUS,
    START_TIME,
    END_TIME,
    EXIT_CODE,
    EXIT_MESSAGE
FROM BATCH_JOB_EXECUTION
ORDER BY START_TIME DESC
LIMIT 10;

-- 특정 Job의 실행 이력
SELECT 
    JOB_EXECUTION_ID,
    STATUS,
    START_TIME,
    END_TIME,
    EXIT_CODE
FROM BATCH_JOB_EXECUTION
WHERE JOB_NAME = '218_telgmReDlngJob'
ORDER BY START_TIME DESC;

9.3.3 데이터베이스 연결 풀 모니터링¶

HikariCP 설정:

최대 연결 수: 60
최소 유휴 연결: 5
연결 타임아웃: 60초
유휴 연결 타임아웃: 10분
연결 최대 수명: 30분
메모리 누수 감지: 60초

모니터링 방법:

Actuator 메트릭: hikari.connections.active, hikari.connections.idle
로그: HikariCP DEBUG 레벨 로그 확인

9.3.4 외부 모니터링 도구¶

[Dev] http://192.168.245.41:9000/

10. 외부 연동¶

10.1 마이크로서비스 연동¶

다음 서비스들과 HTTP 통신:

adapter: 어댑터 서비스 (전문 송신용)

10.2 배치별 외부 연동 현황¶

10.2.1 Adapter 서비스 연동 (전문 송신)¶

배치명	Job 이름	연동 서비스	연동 경로	전문 코드	비고
전문 재거래	telgmReDlngJob	adapter	`/api/sendMsg`	재처리 대상 전문 코드	실패한 전문 재전송 (GatewayApiCall 사용)
외상매출채권발행처리	osbndPblcnRprcsScheduler01Job	adapter	`/api/sendMsg`	6010	외상매출채권발행 전문 (MessageHelper 사용)
외상매출채권선결제처리	osbndAdvpayScheduler01Job	adapter	`/api/sendMsg`	6030	외상매출채권선결제신청 전문 (MessageHelper 사용)
외매채 즉시취소	prcOsbndRtrcnDlngSe01Job	adapter	`/api/sendMsg`	6011	외상매출채권발행취소 전문 (GatewayApiCall 사용)
외매채 취소요청	prcOsbndRtrcnDlngSe02Job	adapter	`/api/sendMsg`	6011	외상매출채권발행취소 전문 (GatewayApiCall 사용)
상매채 즉시취소	wwSlsBndRtrcnDlngSe01Job	adapter	`/api/sendMsg`	6021	상생매출채권발행취소 전문 (GatewayApiCall 사용)
상매채 취소요청	wwSlsBndRtrcnDlngSe02Job	adapter	`/api/sendMsg`	6021	상생매출채권발행취소 전문 (GatewayApiCall 사용)
수취채권 예약 발행	addrBndRsvtPblcnJob	adapter	`/api/sendMsg`	6020	상생매출채권발행 전문 (GatewayApiCall 사용)
수취채권 즉시 발행	addrBndNowPblcnJob	adapter	`/api/sendMsg`	6020	상생매출채권발행 전문 (GatewayApiCall 사용)
장려금정산이체처리	prcsSubsdClclnTrJob	adapter	`/api/sendMsg`	7020	자금이체 전문 (GatewayApiCall 사용)

참고사항:

Adapter 서비스는 금융기관과의 전문 송수신을 담당합니다.
GatewayApiCall 유틸리티를 통해 호출됩니다.
전문 코드는 PrcAppConstants.TELGM_CD에 정의되어 있습니다.

10.2.2 Surem API 연동 (알림톡/SMS 발송)¶

배치명	Job 이름	연동 유형	템플릿 코드	비고
대출연장안내	loanPrlgGdJob	알림톡	ESI_SYNC_018	대출 만기 30일 전 안내
고객확인재등록안내	custIdntyRrgGdJob	알림톡	ESI_SYNC_019	고객확인 만기 30일 전 안내
(구매기업)결재기한 만료 처리	aprvnTermExpSchedulerJob01	알림톡	ESI_SYNC_003, ESI_SYNC_006	결재기한 만료 시 결재권자(003), 요청자(006)에게 알림톡 발송
수취채권 발행 전 결재선 내역 승인기한 체크	addrBfPblcnAplnJob	알림톡	ESI_SYNC_003, ESI_SYNC_006	승인기한 지난 결재미완료건에 대해 결재권자(003), 요청자(006)에게 알림톡 발송
오류알림	errorNotificationJob	SMS	-	전문 오류 발생 시 운영자에게 SMS 발송
대내원장대사 오류알림	(대사 배치 내부 호출)	SMS	-	대내원장대사 불일치 발생 시 운영자에게 SMS 발송
대외원장대사 오류알림	(대사 배치 내부 호출)	SMS	-	대외원장대사 불일치 발생 시 운영자에게 SMS 발송

참고사항:

알림톡 발송은 batchAlimtalk 설정이 true일 때만 동작합니다.
설정: application.yml의 surem 섹션
서비스: com.esi.nextgen.batch.common.surem.service.SuremServiceImpl
SMS 발송은 suremMMSSetting 메서드를 통해 처리됩니다.
Surem API는 수렴(Surem) 서비스를 통해 알림톡/SMS를 발송합니다.
주요 설정 항목:
- surem.usercode: 사용자 코드
- surem.deptcode: 부서 코드
- surem.yellowidkey: 카카오톡 비즈니스 채널 키 (알림톡용)
- surem.reqphone: 발신 전화번호 (SMS용)

11. 트러블슈팅¶

11.1 배치 작업이 실행되지 않는 경우¶

profile 설정 확인
Cron 표현식 확인 (application-local.yml 또는 환경별 설정)
데이터베이스 연결 확인
로그 파일 확인
비정상 종료 Job 존재 확인

11.1.1 비정상 종료로 인한 Job 실행 중 상태 확인 및 처리¶

문제 상황:

애플리케이션이 강제 종료되거나 비정상 종료되어 Job이 STARTED 상태로 남아있음
다음 스케줄 실행 시 "JobExecutionAlreadyRunningException" 발생하거나 실행되지 않음

확인 방법:

SQL을 통한 확인

-- 실행 중인 Job 목록 확인
SELECT 
    JOB_EXECUTION_ID,
    JOB_INSTANCE_ID,
    JOB_NAME,
    STATUS,
    START_TIME,
    LAST_UPDATED,
    EXIT_CODE,
    EXIT_MESSAGE
FROM BATCH_JOB_EXECUTION
WHERE STATUS = 'STARTED'
ORDER BY START_TIME DESC;

-- 특정 Job의 실행 중 상태 확인
SELECT 
    JOB_EXECUTION_ID,
    JOB_NAME,
    STATUS,
    START_TIME,
    LAST_UPDATED
FROM BATCH_JOB_EXECUTION
WHERE JOB_NAME = '218_osbndPblcnRprcsScheduler01Job'
  AND STATUS = 'STARTED'
ORDER BY START_TIME DESC;

-- 실행 중인 Step 확인
SELECT 
    STEP_EXECUTION_ID,
    STEP_NAME,
    JOB_EXECUTION_ID,
    STATUS,
    START_TIME,
    LAST_UPDATED
FROM BATCH_STEP_EXECUTION
WHERE STATUS = 'STARTED'
ORDER BY START_TIME DESC;

처리 방법:

SQL을 통한 수동 처리

-- 실행 중인 Job을 FAILED 상태로 변경
UPDATE BATCH_JOB_EXECUTION
SET STATUS = 'FAILED',
    EXIT_CODE = 'FAILED',
    EXIT_MESSAGE = '애플리케이션 비정상 종료로 인한 수동 처리',
    END_TIME = NOW(),
    LAST_UPDATED = NOW()
WHERE STATUS = 'STARTED'
  AND JOB_NAME = '218_osbndPblcnRprcsScheduler01Job'
  AND START_TIME < DATE_SUB(NOW(), INTERVAL 1 HOUR);  -- 1시간 이상 실행 중인 경우만

-- 실행 중인 Step도 함께 처리
UPDATE BATCH_STEP_EXECUTION
SET STATUS = 'FAILED',
    EXIT_CODE = 'FAILED',
    END_TIME = NOW(),
    LAST_UPDATED = NOW()
WHERE STATUS = 'STARTED'
  AND JOB_EXECUTION_ID IN (
      SELECT JOB_EXECUTION_ID 
      FROM BATCH_JOB_EXECUTION 
      WHERE STATUS = 'FAILED' 
        AND JOB_NAME = '218_osbndPblcnRprcsScheduler01Job'
  );

예방 방법

일부 Scheduler에서는 이미 isRunning() 체크를 통해 실행 중인 Job이 있으면 스킵하는 로직이 구현되어 있음
예시: AddrBndPblcnScheduler, PrcOsbndRtrcnScheduler, MtryStlmTotInfoScheduler 등

주의사항:

Job 상태를 변경하기 전에 해당 Job이 실제로 실행 중이 아닌지 확인 필요
LAST_UPDATED 시간을 확인하여 오래된 실행 중 상태만 처리하는 것을 권장
상태 변경 후 다음 스케줄 실행 시 정상적으로 실행되는지 확인 필요

11.2 대사 파일 처리 오류¶

대사 파일 경로 확인 (base_path 설정)
파일 권한 확인
파일 형식 및 레이아웃 확인
로그에서 구체적인 오류 메시지 확인

11.3 데이터베이스 연결 오류¶

HikariCP 연결 풀 설정 확인
데이터베이스 서버 상태 확인
네트워크 연결 확인
연결 타임아웃 설정 확인

11.4 전문 재거래 실패¶

재처리 대상 전문 코드 확인 (telgm.re-dlng-codes)
어댑터 서비스 상태 확인
네트워크 연결 확인
전문 형식 확인

12. 주요 상수 및 코드¶

12.1 금융기관 코드¶

ESI: 결제전산원
218 (KBSEC): KB증권

12.2 채권 상태 코드¶

01: 정상
02: 완제
03: 취소요청
09: 취소

12.3 발행 구분 코드¶

1: 즉시발행
2: 예약발행

12.4 대사 원장 구분 코드¶

00: 예치금잔액대사
01: 구매기업원장_원장대사
02: 구매기업지사정보_원장대사
11: 협력기업원장_원장대사
12: 거래선원장_원장대사
21: 외상매출채권원장_원장대사
22: 상생매출채권원장_원장대사
31: 대출약정원장_원장대사
32: 대출실행원장_원장대사
99: 대내 대사

상세한 상수는 PrcAppConstants.java 참조

13. 개발 가이드¶

13.1 새로운 배치 작업 추가 방법¶

Service 클래스 생성: service/ 패키지에 비즈니스 로직 구현
- 필요 시 Mapper 인터페이스 생성: mapper/ 패키지에 Mapper 인터페이스 생성
- 필요 시 Mapper XML 생성: resources/mapper/에 XML 파일 생성
Config 클래스 생성: config/ 패키지에 *BatchConfig.java 생성
- Job, Step 설정
- Tasklet 정의
Scheduler 클래스 생성: scheduler/ 패키지에 @Scheduled 메서드 추가
- 또는 기존 Scheduler 클래스에 메서드 추가
Cron 설정 추가: application-local.yml 또는 환경별 설정 파일에 Cron 표현식 추가
- 형식: batch.cron.{배치명}: 'cron 표현식'
BatchCronConfig에 Bean 추가: Cron Bean 등록
- @Bean("{배치명}Cron") 메서드 추가
- @Value("${batch.cron.{배치명}}") 사용
BatchJobNameMapper에 매핑 추가: Job 이름 한글명 매핑 (선택사항)

13.2 Job 실행 흐름¶

Spring Batch Job이 실행되는 전체 흐름은 다음과 같습니다:

1. application.yml (또는 application-local.yml)
   └─ batch.cron.osbndPblcnRprcs: '0 0 0 1 * *'
      ↓
2. BatchCronConfig (@Configuration)
   └─ @Bean("osbndPblcnRprcsCron")
      └─ @Value("${batch.cron.osbndPblcnRprcs}") String cron
      └─ Bean으로 등록: "osbndPblcnRprcsCron"
      ↓
3. Scheduler 클래스 (@Component)
   └─ @Scheduled(cron = "#{@osbndPblcnRprcsCron}")
   └─ Spring의 스케줄러가 cron 표현식에 따라 메서드 실행
      ↓
4. Scheduler.runOsbndPblcnRprcsScheduler01Job()
   └─ JobParameters 생성 (timestamp 등)
   └─ jobLauncher.run(osbndPblcnRprcsScheduler01Job, jobParameters)
      ↓
5. JobLauncher (Spring Batch)
   └─ Job 실행 시작
   └─ JobRepository에 실행 정보 저장
      ↓
6. Job Config (예: OsbndPblcnRprcsBatchConfig)
   └─ @Bean osbndPblcnRprcsScheduler01Job()
   └─ JobBuilder로 Job 생성
   └─ Step 연결
      ↓
7. Step (예: osbndPblcnRprcsScheduler01Step)
   └─ StepBuilder로 Step 생성
   └─ Tasklet 연결
      ↓
8. Tasklet (예: osbndPblcnRprcsSe01Tasklet)
   └─ execute() 메서드 실행
   └─ 실제 비즈니스 로직 호출
      ↓
9. Service (예: OsbndPblcnService)
   └─ prcsOsbndPblcn() 메서드 실행
   └─ 비즈니스 로직 처리

주요 구성 요소:

Cron 설정 파일 (application.yml 또는 application-local.yml)
- batch.cron.{배치명} 형식으로 cron 표현식 정의
- 예: batch.cron.osbndPblcnRprcs: '0 0 0 1 * *'
BatchCronConfig (@Configuration)
- @Value("${batch.cron.{배치명}}")로 cron 값 읽기
- @Bean("{배치명}Cron")으로 Bean 등록
- Spring Expression Language(SpEL)에서 참조 가능하도록 함
Scheduler 클래스 (@Component)
- @Scheduled(cron = "#{@{배치명}Cron}")로 Bean 참조
- Spring의 @EnableScheduling 활성화 필요
- cron 표현식에 따라 메서드 자동 실행
JobLauncher
- Spring Batch의 Job 실행 인터페이스
- Job과 JobParameters를 받아 실행
- JobRepository에 실행 이력 저장
Job Config (@Configuration)
- @Bean으로 Job 정의
- JobBuilder로 Job 생성
- Step 연결 및 Listener 설정
Step
- Job의 실행 단위
- StepBuilder로 Step 생성
- Tasklet 또는 Chunk 방식 선택
Tasklet
- Step의 실행 로직
- execute() 메서드에서 실제 비즈니스 로직 호출
Service
- 실제 비즈니스 로직 처리
- 데이터 조회, 가공, 저장 등 수행

예시 코드 흐름:

// 1. application-local.yml
batch:
  cron:
    osbndPblcnRprcs: '0 0 0 1 * *'

// 2. BatchCronConfig.java
@Bean("osbndPblcnRprcsCron")
public String osbndPblcnRprcsCron(@Value("${batch.cron.osbndPblcnRprcs}") String cron) {
    return cron;
}

// 3. OsbndPblcnRprcsScheduler.java
@Scheduled(cron = "#{@osbndPblcnRprcsCron}")
public void runOsbndPblcnRprcsScheduler01Job() {
    jobLauncher.run(osbndPblcnRprcsScheduler01Job, jobParameters);
}

// 4. OsbndPblcnRprcsBatchConfig.java
@Bean
public Job osbndPblcnRprcsScheduler01Job(...) {
    return new JobBuilder(...)
        .start(osbndPblcnRprcsScheduler01Step(...))
        .build();
}

// 5. Tasklet
public Tasklet osbndPblcnRprcsSe01Tasklet() {
    return (contribution, chunkContext) -> {
        osbndPblcnService.prcsOsbndPblcn(); // Service 호출
        return RepeatStatus.FINISHED;
    };
}

13.3 코딩 컨벤션¶

의존성 주입: Lombok의 @RequiredArgsConstructor 사용
함수 구현: 정적 메서드로 구현 (가능한 경우)
로깅: SLF4J 사용 (@Slf4j)

13.4 테스트¶

테스트 코드 위치: src/test/java/
Spring Batch 테스트: spring-batch-test 의존성 사용
TestJobRunner
- profile 설정 필요
  - 환경변수: SPRING_PROFILES_ACTIVE=local
- Job name 설정 후 실행

  @Qualifier("dlngCompFile00Job") Job runJob

13.5 Batch project 실행¶

Gradle bootRun 실행
- profile 설정 필요
  - 환경변수: SPRING_PROFILES_ACTIVE=local
BatchApplication
- Active profiles 지정

14. 배포 및 운영¶

14.1 배포 환경¶

로컬: application-local.yml
F218: application-F218.yml
- 금융기관 추가 시 금융기관별 profile 추가 필요
- (주의) 현재 개발/운영 profile 분리되어 있지 않음!!
프로파일은 spring.profiles.active로 지정

14.2 모니터링¶

자세한 모니터링 설정 및 방법은 9.3 모니터링 섹션을 참조하세요.

14.3 백업¶

대사 파일 백업: backup 폴더에 날짜별로 저장
데이터베이스 백업: 별도 정책에 따라 수행

15. 참고 자료¶

15.1 주요 클래스 참조¶

메인 애플리케이션: BatchApplication.java
배치 작업 매퍼: BatchJobNameMapper.java
상수 정의: PrcAppConstants.java
배치 Cron 설정: BatchCronConfig.java

15.2 MessageHelper¶

클래스 위치: com.esi.nextgen.batch.common.util.MessageHelper

주요 기능:

전문(Telegram) 생성 및 송신: FieldSpec 어노테이션 기반으로 전문 자동 생성 및 변환
전문 파싱: 고정 길이 전문을 VO 객체로 파싱
필드 자동 처리: 길이, 패딩, 정렬 자동 처리 (EUC-KR 바이트 길이 기준)
검증: Bean Validation + FieldSpec 길이 검증
대사 파일 읽기: H/D/T 레코드 타입 파일 파싱

주요 메서드:

createTelegram(): 전문 생성 (공통부 포함, Supplier 패턴 지원)
sendMessage(): 전문 송신 및 전문거래내역 테이블 자동 등록
parseMessage(): 전문 문자열을 VO 객체로 파싱
readFile(): 대사 파일 읽기 및 파싱
validateAll(): Bean Validation + FieldSpec 검증

사용 배치:

외상매출채권발행처리 (OsBondIssueService)
외상매출채권선결제처리 (OsbndAdvpayService)
원장 대사 파일 처리 (DlngCompFileRegService)

특징:

@FieldSpec 어노테이션으로 필드 메타데이터 정의
EUC-KR 인코딩 기준 바이트 길이 처리 (한글 2바이트)
전문 공통부 자동 생성 및 전문거래내역 자동 로깅
GatewayApiCall을 통한 Adapter 서비스 연동 (/api/sendMsg)

15.3 GatewayApiCall¶

클래스 위치: com.esi.nextgen.batch.common.util.GatewayApiCall

주요 기능:

게이트웨이 전문 호출: Adapter 서비스로 전문(Telegram) 송신
Flat 전문 변환: VO 객체를 Flat 전문 형식으로 자동 변환
동기식 호출: GenericWebClient를 통한 HTTP 통신

주요 메서드:

callGatewayTelgm(): 게이트웨이 전문 호출 (Flat 전문 송신)
- 파라미터: serviceName (서비스명), uri (호출 경로), requestVo (전문 요청 객체)
- 반환값: true (성공), false (실패)

사용 배치:

전문 재거래 (TelgmReDlngSingleService)
외매채 즉시취소/취소요청 (PrcOsbndRtrcnProcessService)
상매채 즉시취소/취소요청 (ClbWwSlsBndRtrcnProcessService)
수취채권 예약/즉시 발행 (ApiClbWwSlsBndPblcnService)
장려금정산이체처리 (PrcsSubsdClclnTrService)

특징:

FlatMessageConverter를 통한 VO → Flat 전문 변환
application.yml의 api.gateway.send-message-url 설정 사용 (기본값: /api/sendMsg)
Form Data 형식으로 전송 (msg 키에 Flat 전문 포함)
GenericWebClient를 통한 마이크로서비스 간 통신

MessageHelper와의 차이점:

GatewayApiCall: 직접적인 전문 송신 (Flat 전문 변환 후 전송)
MessageHelper: 전문 생성, 검증, 로깅 등 추가 기능 포함 (내부적으로 GatewayApiCall 사용)

15.4 문서화¶

각 클래스에는 JavaDoc 주석이 포함되어 있습니다.
주요 메서드에는 설명이 포함되어 있습니다.

16. 주의사항¶

16.1 중요 사항¶

금융기관 코드: 각 환경별로 올바른 금융기관 코드 설정 필요
대사 파일 경로: 운영 환경과 개발 환경의 경로가 다를 수 있음
데이터베이스 연결: 프로덕션 환경의 연결 정보는 별도 관리 필요
Cron 표현식: 배치 실행 시간은 비즈니스 요구사항에 맞게 조정 필요
파일 권한: 대사 파일 읽기/쓰기 권한 확인 필요

16.2 보안¶

데이터베이스 비밀번호는 환경 변수나 별도 설정 파일로 관리 권장

부록 A: 배치 작업 실행 명령어 예시¶

# 전문 재거래 배치 실행
java -jar batch-0.0.1-SNAPSHOT.jar --spring.profiles.active=F218 --job.name=218_telgmReDlngJob

# 원장 대사 파일 처리 배치 실행
java -jar batch-0.0.1-SNAPSHOT.jar --spring.profiles.active=F218 --job.name=218_dlngCompFile00Job

# 장려금 배분 배치 실행
java -jar batch-0.0.1-SNAPSHOT.jar --spring.profiles.active=F218 --job.name=218_aprtSubsdJob

부록 B: Cron 표현식 참고¶

표현식	의미
`0 0 0 1 * *`	매월 1일 0시 0분 0초
`0 29 * * * *`	매분 29초
`0 /5 8-22 * MON-FRI`	평일 08~22시 매 5분
`0 0 10 * * MON-FRI`	평일 10시
`0 * 8-21 * * *`	매일 08~21시 매 1분
`0 /2 * * *`	매 2분마다
`30 * 8-20 * * MON-FRI`	평일 08~20시 매 1분 30초(초=30)
`0 0 2 * * ?`	매일 02:00
`0 0 9 * * MON-FRI`	평일 09:00
`0 0 20 1 * ?`	매월 1일 20:00

참고: Spring의 cron 표현식은 초 분 시 일 월 요일(6필드) 형식이며, ?는 “특정 값 없음”을 의미합니다. 운영/로컬 프로필마다 값이 다를 수 있으니 실제 주기는 application-F218.yml, application-local.yml의 batch.cron을 확인하세요.

문서 작성일: 2025-12-09
문서 버전: 1.0
작성자: 시스템

Files (0)

Updated by 길호 원 9 months ago · 15 revisions

Project

General

Profile

상생결제 차세대 프로젝트

Wiki

About-batch » History » Revision 5

ESI NextGen Batch 시스템 인수인계 문서¶

1. 프로젝트 개요¶

1.1 프로젝트 정보¶

1.2 주요 기능¶

2. 기술 스택¶

2.1 개발 환경¶

2.2 주요 의존성¶

2.3 개발 도구¶

3. 프로젝트 구조¶

3.1 디렉토리 구조¶

3.2 리소스 구조¶

4. 주요 배치 작업 목록¶

4.1 전문 거래 내역 배치¶

4.2 채권 발행 배치¶

4.3 정산 배치¶

4.4 원장 대사 배치¶

4.5 기타 배치¶

5. 설정 파일 설명¶

5.1 application.yml¶

5.2 application-local.yml¶

5.3 배치 Cron 설정 위치¶

6. 실행 방법¶

6.1 로컬 개발 환경 실행¶

6.2 빌드¶

6.3 프로덕션 실행¶

6.4 IDE에서 특정 Job 실행¶

6.4 REST API를 통한 배치 실행¶

7. 주요 기능 상세 설명¶

7.1 배치 작업 구조¶

7.2 금융기관 코드 관리¶

7.3 원장 대사 파일 처리¶

7.4 전문 재거래 처리¶

7.5 오류 알림¶

8. 데이터베이스¶

8.1 데이터베이스 정보¶

8.2 Spring Batch 메타데이터¶

8.3 배치 Job별 관련 테이블 및 CRUD 작업¶

8.3.1 전문 거래 내역 배치¶

8.3.2 채권 발행 배치¶

8.3.3 정산 배치¶

8.3.4 원장 대사 배치¶

8.3.5 기타 배치¶

9. Logging & Monitoring¶

9.1 로그 설정¶

9.2 로그 레벨¶

9.3 모니터링¶

9.3.1 Spring Boot Actuator¶

9.3.2 Spring Batch Job 실행 모니터링¶

9.3.3 데이터베이스 연결 풀 모니터링¶

9.3.4 외부 모니터링 도구¶

10. 외부 연동¶

10.1 마이크로서비스 연동¶

10.2 배치별 외부 연동 현황¶

10.2.1 Adapter 서비스 연동 (전문 송신)¶

10.2.2 Surem API 연동 (알림톡/SMS 발송)¶

11. 트러블슈팅¶

11.1 배치 작업이 실행되지 않는 경우¶

11.1.1 비정상 종료로 인한 Job 실행 중 상태 확인 및 처리¶

11.2 대사 파일 처리 오류¶

11.3 데이터베이스 연결 오류¶

11.4 전문 재거래 실패¶

12. 주요 상수 및 코드¶

12.1 금융기관 코드¶

12.2 채권 상태 코드¶

12.3 발행 구분 코드¶

12.4 대사 원장 구분 코드¶

13. 개발 가이드¶

13.1 새로운 배치 작업 추가 방법¶

13.2 Job 실행 흐름¶

13.3 코딩 컨벤션¶

13.4 테스트¶

13.5 Batch project 실행¶

14. 배포 및 운영¶

14.1 배포 환경¶