About-batch » History » Revision 9
Revision 8 (길호 원, 12/15/2025 03:31 PM) → Revision 9/15 (길호 원, 12/15/2025 03:31 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 주요 의존성
```gradle
- 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) / 매월 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 로컬 개발 환경 실행
```bash
# 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 빌드
```bash
# JAR 파일 빌드
./gradlew build
# 빌드된 JAR 파일 위치
build/libs/batch-0.0.1-SNAPSHOT.jar
```
### 6.3 프로덕션 실행
```bash
# 프로파일 지정하여 실행
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 설정 후 실행
```java
@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)
**로그 확인 방법:**
```bash
# 실시간 로그 확인
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 실행 모니터링
**메타데이터 테이블을 통한 조회:**
```sql
-- 최근 실행된 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을 통한 확인**
```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을 통한 수동 처리**
```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**
- 실제 비즈니스 로직 처리
- 데이터 조회, 가공, 저장 등 수행
**예시 코드 흐름:**
```java
// 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 설정 후 실행
```java
@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 중요 사항
1. **금융기관 코드**: 각 환경별로 올바른 금융기관 코드 설정 필요
2. **대사 파일 경로**: 운영 환경과 개발 환경의 경로가 다를 수 있음
3. **데이터베이스 연결**: 프로덕션 환경의 연결 정보는 별도 관리 필요
4. **Cron 표현식**: 배치 실행 시간은 비즈니스 요구사항에 맞게 조정 필요
5. **파일 권한**: 대사 파일 읽기/쓰기 권한 확인 필요
### 16.2 보안
- 데이터베이스 비밀번호는 환경 변수나 별도 설정 파일로 관리 권장
---
## 부록 A: 배치 작업 실행 명령어 예시
```bash
# 전문 재거래 배치 실행
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
**작성자**: 원길호 시스템