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          # 배치 파일 정보
│   ├── 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)
예치금잔액대사	dlngCompFile00Job	예치금 잔액 대사	매일 2시 (F218)
구매기업원장_원장대사	dlngCompFile01Job	구매기업 원장 대사	매일 2시 (F218)
구매기업지사정보_원장대사	dlngCompFile02Job	구매기업 지사정보 대사	매일 2시 (F218)
협력기업원장_원장대사	dlngCompFile11Job	협력기업 원장 대사	매일 2시 (F218)
거래선원장_원장대사	dlngCompFile12Job	거래선 원장 대사	매일 2시 (F218)
외상매출채권원장_원장대사	dlngCompFile21Job	외상매출채권 원장 대사	매일 2시 (F218)
상생매출채권원장_원장대사	dlngCompFile22Job	상생매출채권 원장 대사	매일 2시 (F218)
대출약정원장_원장대사	dlngCompFile31Job	대출약정 원장 대사	매일 2시 (F218)
대출실행원장_원장대사	dlngCompFile32Job	대출실행 원장 대사	매일 2시 (F218)
(대내)거래원장대사	dlngCompInsdGnlgrJob	대내 거래 원장 대사	매일 2시 (F218)

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-F218.yml¶

주요 설정 항목:

• 서버 포트/콘텍스트: 8091 / /batch
• 금융기관 코드: 218
• 로그 경로/파일명: /usr/local/tomcat-batch/logs / esisync-batch-F218.log
• 배치 Cron: 운영 주기 설정 (batch.cron.*, 예: osbndPblcnRprcs 월금 0821시 매 1분)
• 대사파일 경로: /data1/adapter/files/
• 알림톡 사용 여부: batchAlimtalk=false (운영 기본값)

5.2 application-local.yml¶

로컬 개발 환경 설정:

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

5.3 배치 Cron 설정 위치¶

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

주의사항:

• 운영 환경(F218)의 설정파일이 분리되어 있지 않습니다.(추후 분리 필요)
• 금융기관 추가 시 금융기관별 설정파일(application-F{금융기관코드}.yml)이 추가되고 별도의 instance로 배치 application이 실행됩니다.
  • batch_fnst_cd 설정값에 금융기관 코드가 설정되고, 각 배치 job에서는 코드를 읽어 해당 금융기관에 해당하는 데이터만 처리하도록 되어 있습니다.
• 실제 운영 환경의 실행 주기는 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 배치 작업 구조¶

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

1. Scheduler: Cron 스케줄러로 배치 실행 트리거
2. Config: Spring Batch Job/Step 설정
3. Service: 실제 비즈니스 로직 처리
4. 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 배치 작업이 실행되지 않는 경우¶

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

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

문제 상황:

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

확인 방법:

1. 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;

처리 방법:

1. 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'
  );

3. 예방 방법

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

주의사항:

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

11.2 대사 파일 처리 오류¶

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

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

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

11.4 전문 재거래 실패¶

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

---

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 새로운 배치 작업 추가 방법¶

1. Service 클래스 생성: service/ 패키지에 비즈니스 로직 구현
   • 필요 시 Mapper 인터페이스 생성: mapper/ 패키지에 Mapper 인터페이스 생성
   • 필요 시 Mapper XML 생성: resources/mapper/에 XML 파일 생성
2. Config 클래스 생성: config/ 패키지에 *BatchConfig.java 생성
   • Job, Step 설정
   • Tasklet 정의
3. Scheduler 클래스 생성: scheduler/ 패키지에 @Scheduled 메서드 추가
   • 또는 기존 Scheduler 클래스에 메서드 추가
4. Cron 설정 추가: application-local.yml 또는 환경별 설정 파일에 Cron 표현식 추가
   • 형식: batch.cron.{배치명}: 'cron 표현식'
5. BatchCronConfig에 Bean 추가: Cron Bean 등록
   • @Bean("{배치명}Cron") 메서드 추가
   • @Value("${batch.cron.{배치명}}") 사용
6. 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() 메서드 실행
   └─ 비즈니스 로직 처리

주요 구성 요소:

1. Cron 설정 파일 (application.yml 또는 application-local.yml)

   • batch.cron.{배치명} 형식으로 cron 표현식 정의
   • 예: batch.cron.osbndPblcnRprcs: '0 0 0 1 * *'

2. BatchCronConfig (@Configuration)

   • @Value("${batch.cron.{배치명}}")로 cron 값 읽기
   • @Bean("{배치명}Cron")으로 Bean 등록
   • Spring Expression Language(SpEL)에서 참조 가능하도록 함

3. Scheduler 클래스 (@Component)

   • @Scheduled(cron = "#{@{배치명}Cron}")로 Bean 참조
   • Spring의 @EnableScheduling 활성화 필요
   • cron 표현식에 따라 메서드 자동 실행

4. JobLauncher

   • Spring Batch의 Job 실행 인터페이스
   • Job과 JobParameters를 받아 실행
   • JobRepository에 실행 이력 저장

5. Job Config (@Configuration)

   • @Bean으로 Job 정의
   • JobBuilder로 Job 생성
   • Step 연결 및 Listener 설정

6. Step

   • Job의 실행 단위
   • StepBuilder로 Step 생성
   • Tasklet 또는 Chunk 방식 선택

7. Tasklet

   • Step의 실행 로직
   • execute() 메서드에서 실제 비즈니스 로직 호출

8. 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 추가 필요
• 프로파일은 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 중요 사항¶

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

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–59)
│ ┌─ 분 (0–59)
│ │ ┌─ 시 (0–23)
│ │ │ ┌─ 일 (1–31)
│ │ │ │ ┌─ 월 (1–12)
│ │ │ │ │ ┌─ 요일 (0–7, 0·7=일요일)
│ │ │ │ │ │
* * * * * *

필드	의미	값 범위
초	Seconds	0–59
분	Minutes	0–59
시	Hours	0–23
일	Day of Month	1–31
월	Month	1–12
요일	Day of Week	0–7 (0,7 = SUN)

표현식	의미
0 0 0 1 * *	매월 1일 0시 0분 0초
0 30 * * * *	매일 매시 30분 0초
0 */5 8-22 * * MON-FRI	평일 08~22시 매 5분(0, 5, 10 ...)
0 0 10 * * MON-FRI	평일 10시
0 * 8-21 * * *	매일 08~21시 매 1분(매분 0초)
0 */2 * * * *	매 2분마다(매분 0초)
30 * 8-20 * * MON-FRI	평일 08~20시 매분 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
작성자: 원길호