About-batch » History » Revision 6
Revision 5 (길호 원, 12/15/2025 03:22 PM) → Revision 6/15 (길호 원, 12/15/2025 03:28 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 # 배치 파일 정보 │ ├── 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 로컬 개발 환경 실행 ```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 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 **작성자**: 시스템