eapim-admin

제주은행(DJB) eLink EMS 관리 콘솔

개요

eapim-admin 은 eLink EMS(eLink Management System)의 웹 기반 관리 콘솔입니다. API 게이트웨이 구성, 실시간 모니터링/대시보드, 통계, 트랜잭션 로그 조회, 인터페이스·레이아웃·어댑터·라우팅 관리 기능을 제공합니다.

eLink EMS 는 세 가지 애플리케이션으로 구성됩니다.

애플리케이션	설명
eapim-admin	관리 콘솔 (이 저장소)
eapim-online	실시간 트랜잭션 처리 API 게이트웨이
eapim-portal	API 소비자용 개발자 포털 (Spring Boot)

패키지·클래스에 남아 있는 kjb / KJB 명칭은 초기 광주은행 커스터마이징에서 유래한 것으로, 현재 배포 대상은 제주은행(DJB)입니다. 제주은행 전용 코드는 com.eactive.eai.rms.ext.djb 하위에 있습니다.

기술 스택

구분	버전 / 내용
Java	8 (Gradle toolchain 으로 강제, JavaLanguageVersion.of(8))
빌드	Gradle 8.7 (wrapper), war 패키징
Spring Framework	5.3.27 (MVC / ORM / JDBC)
Spring Data JPA	2.5.2
Hibernate	5.6.15.Final
QueryDSL	5.0.0 (빌드 시 Q-class 생성)
iBATIS	2.3.4 (레거시 SQL 매핑)
Quartz	2.2.1 (스케줄링)
로깅	SLF4J + Logback 1.2.10 (모든 log4j 의존성 제외)
기타	Apache POI 3.17(Excel), Jackson 2.13.1, AWS SDK 2.x(S3), EhCache, Lombok, MapStruct

애플리케이션 프레임워크는 Spring Boot 가 아닌 전통적 Spring 5.3 WAR 이며 Tomcat / WebLogic 등에 배포됩니다. (Spring Boot 는 테스트 유틸리티 spring-boot-starter-test:2.6.15 에만 사용)

사전 요구사항

• JDK 8 - .envrc(direnv) 또는 셸 rc 에서 JAVA_HOME 을 JDK 8 위치로 export. Gradle 8 toolchain auto-detect 가 JAVA_HOME 도 후보로 인식합니다. gradle.properties 에 JDK 경로를 넣지 않습니다.
• Git
• Oracle 접근 (개발/테스트 환경에 따라). 테스트는 H2 인메모리 DB 사용.
• 형제 디렉토리 체크아웃 필요 - 멀티 모듈 프로젝트로 아래 저장소가 같은 부모 디렉토리에 있어야 합니다.

  <workspace>/
  ├── eapim-admin/            # 이 저장소
  ├── eapim-online/           # elink-online-* 모듈
  └── elink-portal-common/    # 포털 공통 JPA 엔티티
  

멀티 모듈 구조

settings.gradle 에서 형제 디렉토리의 소스 프로젝트를 참조합니다.

모듈	위치	설명
elink-online-core	../eapim-online/elink-online-core	핵심 인터페이스 / 도메인 모델
elink-online-core-jpa	../eapim-online/elink-online-core-jpa	JPA 엔티티 / 리포지토리
elink-online-transformer	../eapim-online/elink-online-transformer	메시지 변환 로직
elink-online-common	../eapim-online/elink-online-common	공통 유틸리티
elink-online-emsclient	../eapim-online/elink-online-emsclient	EMS 통신 클라이언트
elink-portal-common	../elink-portal-common	포털 공통 컴포넌트 (JPA 엔티티)

kjb-safedb, eapim-admin-djb 는 settings.gradle 에 주석 처리되어 있으며, 필요 시 주석을 해제하고 해당 디렉토리를 체크아웃합니다.

빌드 및 실행

프로젝트 루트의 Gradle wrapper(./gradlew) 를 사용합니다.

# 표준 빌드
./gradlew build

# 클린 빌드
./gradlew clean build

# WAR 빌드 (build/libs/eapim-admin.war)
./gradlew war

# WebLogic 배포용 빌드 (테스트 제외, weblogic-web.xml 사용)
./gradlew build -x test -Pprofile=weblogic

# 패키징 없이 컴파일만
./gradlew classes

# QueryDSL Q-class 등 생성 코드만 생성
./gradlew compileJava

# 전체 테스트
./gradlew test

# 특정 테스트
./gradlew test --tests "com.eactive.eai.rms.*"

# 의존성 트리 / 태스크 목록
./gradlew dependencies
./gradlew tasks --all

• WAR 파일명: eapim-admin.war, 컨텍스트 경로: /monitoring
• 프로필: -Pprofile=weblogic 지정 시 web.xml 대신 weblogic-web.xml 사용 (DefaultServlet 문제 회피)

로컬 개발 빠른 시작

1. 생성 코드 생성 - 최초 1회 및 pull 이후

   ./gradlew compileJava      # Q-class IDE 오류 시: ./gradlew clean compileJava
   

2. 빌드/테스트

   ./gradlew build
   

3. IDE 열기 - 아래 "IDE 설정" 참조
4. WAS(Tomcat 등) 실행 구성 에 eapim-admin 배포 + 아래 VM 옵션 추가 후 기동

로컬 Tomcat VM 옵션 예시

전체 목록과 설명은 CLAUDE.md 의 "필수 환경 변수 (Tomcat)" 를 참조하세요.

-Deai.datasource.type=DEV
-Dinst.Name=emsSvr11
-Deai.tableowner=EMSADM
-Deai.systemmode=D
-Dfile.encoding=utf-8
-Dlogin.mode=db
-DLOGBACK_LOG_LEVEL=DEBUG
-Ddamo-manager.enabled=true 
-Dlogging.log-path=/logs/prod/eapim/emsSvr11
-Dlogback.configurationFile=classpath:logback-dev.xml
-Dhibernate.dialect=org.hibernate.dialect.Oracle12cDialect

• inst.Name 은 클러스터 내에서 인스턴스마다 고유해야 합니다.
• eai.tableowner 는 Oracle 스키마 소유자.

프로젝트 구조

src/main/java/com/eactive/eai/
├── agent/command        - 커맨드 패턴 구현
├── common               - 공통 유틸리티, iBatis, JSON 직렬화
├── custom               - 고객사별 커스터마이제이션
├── rms                  - 메인 애플리케이션 코드
│   ├── bap              - 배치 처리(BAP): adaptor / manage / tansaction
│   ├── bat              - 추가 배치 기능
│   ├── common           - RMS 공통 (필터, 시작, 서비스)
│   ├── data             - 데이터 엔티티, 리포지토리
│   ├── env              - 환경 설정
│   ├── kakao            - 카카오 연동
│   ├── onl              - 온라인 트랜잭션 관리 (apim / manage / transaction)
│   ├── service          - 비즈니스 서비스
│   └── ext
│       ├── djb          - 제주은행(DJB) 확장 (webhook, UMS 연동, 통계 등)
│       └── kjb          - 광주은행(KJB) 유래 확장
└── (com.eactive.ext.kjb) - 통계 화면 등 일부 확장 코드

WebContent/
├── WEB-INF/
│   ├── applicationContext.xml   - Root Spring 설정
│   ├── springapp-servlet.xml    - Servlet Spring 설정
│   ├── web.xml / weblogic-web.xml
│   └── properties/              - env.D / env.T / env.P / env.L .properties
├── jsp/                         - 화면
└── guide/                       - 사용자 가이드(docsify)

데이터 액세스 (하이브리드 ORM)

JPA 와 iBATIS 를 함께 사용합니다.

• 신규 기능: JPA + Spring Data 리포지토리 (com.eactive.eai.rms.data.entity, elink-portal-common)
• 레거시: iBATIS SQL 매퍼 src/main/resources/com/eactive/eai/**/*.xml (Spring XML 설정, 점진적 마이그레이션 대상)
• 벤더별 매핑: Oracle *-oracle.xml, MariaDB *-mariadb.xml, PostgreSQL *-postgresql.xml

Multi-tenancy (런타임 스키마 전환)

Hibernate Multi-tenancy 로 요청 시점에 스키마를 전환합니다. DataSourceContextHolder(ThreadLocal) → TenantIdentifierResolver → ConfigurableMultiTenantConnectionProvider.setSchema(). 요청 파라미터 serviceType(예: APIGW) 를 DataSourceTypeInterceptor 가 읽어 자동 설정하거나, 컨트롤러에서 명시 설정합니다. 자세한 내용은 CLAUDE.md 의 "Multi-tenancy" 절 참조.

코드 생성

빌드 시 생성됩니다.

• QueryDSL Q-class - build/generated/java/ 에 생성, .gitignore 대상 (커밋 금지)
• Lombok - getter/setter/builder 등
• MapStruct - DTO ↔ 엔티티 매퍼

pull 이후 또는 Q-class IDE 오류 시 ./gradlew compileJava (또는 clean compileJava) 로 재생성합니다.

환경 설정

시스템 모드

-Deai.systemmode 로 지정하며 해당 프로퍼티 파일을 로드합니다.

값	환경	파일
D	개발	env.D.properties
T	테스트 / 스테이징	env.T.properties
P	운영	env.P.properties
L	로컬	env.L.properties

데이터베이스

• Oracle: 운영 주 DB (hibernate.dialect=org.hibernate.dialect.Oracle12cDialect)
• MariaDB / PostgreSQL: 벤더별 SQL 매핑으로 지원 (JDBC 의존성은 필요 시 활성화)
• H2: 테스트용 인메모리 DB (src/test/resources)
• 연결 타입은 -Deai.datasource.type(DEV/STG/PROD) 로 선택

DB 암호화

damo-manager.jar 모듈은 환경에 따라 다른 암호화로직을 제공한다.

환경	설명
운영	실제 D'amo 네이티브 라이브러리
개발	SHA-256

로컬 개발 시 -Ddamo-manager.enabled=false

DJB (제주은행) 전용 설정

DJB 전용 프로퍼티는 DB 테이블 TSEAIRM24 에 그룹명 'Monitoring' 과 DB 테이블 PTL_PROPERTY 에 그룹명 'Portal' 로 저장된다.

Monitoring 프라퍼티 (환경정보 > EMS관리 > 모니터링 프라퍼티)

계정관리

• djb.sms_auth.enabled - 로그인시 2-factor 인증 적용여부
• djb.sms_auth.fixed_value - sms_auth.mode=fixed일 경우 고정인증값
• djb.sms_auth.mode - 2-factor 인증 모드 (real:실제, fixed:고정값-개발환경에서 사용)
• rms.DUAL_LOGIN_ENABLED - 중복 로그인 허용 여부
• rms.auto.logout.timeout - 자동 로그아웃 시간(분)
• rms.password.combi.check - 비밀번호 영문/숫자/특수문자 조합 종류수
• rms.password.fail.count - 비밀번호 실패 허용 횟수(이 값 이상 실패시 계정 잠김)
• rms.password.history.count - 이전 비밀번호 변경 불가 횟수
• rms.password.init.subfix - 관리자가 비밀번호 초기화시 추가 문자 ex) 행번@!
• rms.password.length.check - 비밀번호 최소 자리수
• rms.password.repeat.check - 비밀번호 동일문자,연속문자 반복 불가 횟수
• rms.password.sms_auth.enabled - 비밀번호 변경시 2-factor 인증 여부

인터페이스 배포

• iomap.download.path - 인터페이스.json 파일 다운로드 서버 경로
• iomap.upload.path - 인터페이스.json 파일 업로드 서버 경로

UMS(공통) 연동

• djb.ums.was_ip_address - 관리자포탈 WAS IP 주소 (UMS 연동시 필요)
• djb.ums.was_mac_address - 관리자포탈 WAS MAC 주소 (UMS 연동 시 필요)

UMS(이메일) 연동

• djb.ums.email.url - 이메일 API 엔드포인트 (EAI)
• djb.ums.email.cstno - 고객번호
• djb.ums.email.ums_evnt_id - UMS이벤트 ID

UMS(사내메신저) 연동

• djb.ums.messenger.url - 사내메신저 API 앤드포인트 (FEP)
• djb.ums.messenger.client_id - 사내메신저 클라이언트 아이디
• djb.ums.messenger.client_secret - 사내메신저 클라이언트 시크릿
• djb.ums.messenger.api-monitor.enabled - API 상태변화시 직원에게 사내메신저 발송 여부

UMS(SMS) 연동

• djb.ums.sms.url - SMS API 엔드포인트 (EAI)
• djb.ums.sms.almtk_snd_prtl_key.intra - 카톡 알림톡 채널 ID (제주은행 임직원)
• djb.ums.sms.almtk_snd_prtl_key.public - 카톡 알림톡 채널 ID (제주은행)

Webhook 발송

• rms.webhook.enabled - 웹훅 발송 여부
• rms.webhook.retry_count - 웹훅 재발송 횟수
• rms.webhook.retry_time - 웹훅 재발송 시간간격
• rms.webhook.reverse_proxy.url - 리버스 프록시 경로

Portal 프라퍼티 (파트너포탈 > 포탈관리 > Property관리)

UMS 연동

• djb.ums.email.if_id - 이메일 연동 인터페이스 ID
• djb.ums.email.tx_id - 이메일 거래 ID
• djb.ums.messenger.if_id - 사내메신저 인터페이스 ID
• djb.ums.messenger.tx_id - 사내메신저 거래 ID
• djb.ums.sms.if_id - SMS 인터페이스 ID
• djb.ums.sms.tx_id - SMS 거래 ID

스케쥴러

API 상태 모니터링

• ApiStatusMonitorJob11, ApiStatusMonitorJob21 - API 상태 변화를 모니터링한다. API 상태 변화 발생시 직원에게 메신저 및 제휴사에게 웹훅을 발송한다.
• 실행간격(1분)이 짧아서 CLUSTERED는 적용을 못하고, 서버수만큼 등록하여 번갈아 가면서 실행하도록 설정
• api.status.error.range_minute - API 장애 판단을 위한 로그 구간(분)
• api.status.error.rate - API 장애판단을 위한 오류율 (ex : 10분동안 90% 이상 오류 발생시 장애로 판단)
• api.status.delay.range_minute - API 지연 상태 판단을 위한 로그 구간(분)
• api.status.delay.avg_resp_time - API 지연 상태 판단을 위한 평균 응답속도 (ex: 10분동안 평균 응답속도가 10초이상이면 지연으로 판단)

유량제어토큰실패감시

• InflowTokenMonitorJob - 유량제어 토큰 획득 실패(TSEAIFR11) 발생시 직원에게 메신저를 발송한다
• api.inflow.fail.range_minute - 최근 몇분동안 감시하는지 설정

API 통계

• ApiStatsHourlyAggregationJob - 당일 API 로그 정보를 시간별로 집계 (TSEAILG00 > API_STATS_HOUR)
• APISTATSDAILYJOB - API 사용통계 일집계 (API_STATS_HOUR > API_STATS_DAY)
• APISTATSMONTHLYJOB - API 사용통계 월집계 (API_STATS_DAY > API_STATS_MONTH)
• APISTATSYEARLYJOB - API 사용통계 년집계 (API_STATS_MONTH > API_STATS_YEAR)

UMS발송

• UMSDISPATCHJOB11, UMSDISPATCHJOB21 - UMS를 발송한다.
• 실행간격(5초)이 짧아서 CLUSTERED는 적용을 못하고, 서버수만큼 등록하여 번갈아 가면서 실행하도록 설정

게시글종료

• PortalInquiryClosingJob - 답변완료 이후 일정기간 댓글이 없는 경우 게시글을 종료한다
• inquiry.comment.closing_day - 게시글 종료 대기일수

메모리초기화

• MEMORYTRINIT - 관리자포탈 서버 메모리 초기화(G/W에서 받은 거래현황)

토큰발급이력삭제

• TOKENISSUANCELOGCLEANUPJOB - 7일이 지난 토큰 발급내역을 삭제한다

배포

대상	비고
Tomcat	기본, 개발
WebLogic 14.1.2	운영, -Pprofile=weblogic 필요
JEUS	지원
JBoss / WildFly	descriptor 포함 지원

• 모든 관리 변경사항은 DB 와 메모리에 즉시 반영됩니다.
• 인코딩은 UTF-8. CharacterEncodingFilter 가 *.excel 을 제외한 모든 요청에 적용.
• XSS 보호: com.eactive.eai.rms.common.filter.CrossScriptingFilter 전역 적용.

IDE 설정

build.gradle 은 eclipse / eclipse-wtp / idea 플러그인을 모두 포함합니다. IntelliJ 전용 변형은 build.gradle.intellij 로 별도 관리합니다 (필요 시 build.gradle 로 교체).

# Eclipse
./gradlew eclipse       # .project / .classpath, WTP(context path: /monitoring), APT 설정 생성

# IntelliJ IDEA
./gradlew idea          # 또는 IDE 에서 "Import Gradle Project"

테스트

• JUnit 5 (Jupiter) - 테스트 프레임워크
• Spring Boot Test 2.6.15 - 통합 테스트 유틸리티
• H2 - 인메모리 DB (src/test/resources)
• Mockito - 모킹 (Spring Boot Test 경유)

./gradlew test
./gradlew test --tests "com.eactive.eai.rms.*"

문서

• 프로젝트 상세 지침: CLAUDE.md (AI 어시스턴트 및 개발자용 마스터 문서, 한글)
• 사용자 가이드: WebContent/guide/ (docsify)

라이선스

사내 전용(proprietary). 제주은행 eLink EMS.