eapim-admin/CLAUDE.md

CLAUDE.md

이 파일은 Claude Code (claude.ai/code)가 이 저장소의 코드를 작업할 때 참고할 가이드를 제공합니다.

프로젝트 개요

eLink EMS (eLink Management System)는 세 가지 주요 애플리케이션으로 구성된 엔터프라이즈 API 관리 플랫폼입니다:

• eapim-admin: 구성, 모니터링, 통계를 위한 관리 콘솔
• eapim-online: 실시간 트랜잭션 처리를 위한 API 게이트웨이
• eapim-portal: API 소비자를 위한 개발자 포털 (Spring Boot 기반)

이 디렉토리(eapim-admin)는 Spring 5.3과 하이브리드 ORM 방식(JPA + iBATIS)으로 구축된 관리 콘솔을 포함합니다.

빌드 및 개발 명령어

애플리케이션 빌드

eLink EMS (eLink Management System)는 eLink의 웹 기반 관리 서비스로, 구성, 모니터링 및 통계 기능을 제공합니다. Tomcat 또는 WebLogic에 배포되는 Spring 기반 Java 웹 애플리케이션입니다.

주요 기능

• 사용자 및 권한 관리
• 트랜잭션 로그 조회 (온라인/배치/대량)
• 통계 및 대시보드 모니터링
• 인터페이스, 레이아웃, 어댑터, 라우팅 관리
• 외부 시스템 연동 (UMS, EAI 배치)

빌드 및 개발 명령어

빌드 명령어

# 표준 빌드
gradle build

# Weblogic 배포용 빌드 (테스트 제외)
gradle build -x test -Pprofile=weblogic

# WAR 파일 빌드
gradle war

# 클린 빌드
gradle clean build

테스트 실행

# 모든 테스트 실행
gradle test

# 특정 테스트 클래스 실행
gradle test --tests "com.example.ClassName"

# 특정 테스트 패키지 실행 (JUnit 플랫폼 사용)
gradle test --tests "com.eactive.eai.rms.*"

개발 태스크

# 패키징 없이 클래스만 컴파일
gradle classes

# QueryDSL Q-classes 및 기타 애노테이션 생성
gradle compileJava

# 의존성 트리 보기
gradle dependencies

# 사용 가능한 모든 태스크 목록
gradle tasks --all

아키텍처 및 모듈 의존성

멀티 모듈 구조

eapim-admin은 settings.gradle을 통해 형제 디렉토리 eapim-online의 모듈들을 참조합니다:

eapim-admin (root project)
├── elink-online-core            # 핵심 인터페이스 및 도메인 모델
├── elink-online-core-jpa        # JPA 엔티티 및 리포지토리
├── elink-online-transformer     # 메시지 변환 로직
├── elink-online-common          # 공통 유틸리티
├── elink-online-emsclient       # EMS 클라이언트 통신
├── elink-online-adapter         # 통신 어댑터
├── elink-portal-common          # 포털 공통 컴포넌트 (JPA 엔티티)
├── kjb-safedb                   # 커스텀 암호화 라이브러리
└── eapim-admin-kjb              # KJB 은행 특화 커스터마이제이션

모든 모듈 프로젝트는 이 디렉토리 기준으로 ../eapim-online/, ../elink-portal-common/ 등에 위치합니다.

하이브리드 ORM 방식

이 애플리케이션은 JPA와 iBATIS 모두를 사용합니다:

• JPA/Hibernate: elink-portal-common을 통한 현대적인 데이터 액세스 (Spring Data repositories)
• iBATIS: 기존 코드를 위한 레거시 SQL 매핑 (점진적으로 마이그레이션 예정)

데이터 액세스 작업 시:

• 새로운 기능은 JPA와 Spring Data repositories를 사용해야 합니다
• 레거시 iBATIS 매퍼는 src/main/resources/com/eactive/eai/**/*.xml에 있으며 Spring XML을 통해 설정됩니다

코드 생성

빌드 프로세스에서 생성되는 것들:

• QueryDSL Q-classes: 타입 안전 쿼리 클래스
• Lombok: 애노테이션 프로세싱을 통한 Getters/setters/builders
• MapStruct: DTO와 엔티티 간의 객체 매퍼

이중 Q-Class 생성 (Gradle + Eclipse)

이 프로젝트는 Gradle과 Eclipse 애노테이션 프로세서 모두를 사용하므로, Q-classes가 두 위치에 생성됩니다:

1. build/generated/java/ - gradle compileJava 또는 gradle build 실행 시 Gradle이 생성
2. WebContent/generated/ - Eclipse IDE에서 빌드 시 Eclipse APT가 생성

이는 예상된 동작이며 의도적입니다. 두 디렉토리 모두 .gitignore에 포함되어 있으며 커밋해서는 안 됩니다.

생성된 코드 작업하기

• Gradle 빌드: build/generated/java/의 Q-classes가 자동으로 classpath에 포함됩니다
• Eclipse IDE: WebContent/generated/의 Q-classes가 자동으로 classpath에 포함됩니다
• 업데이트 pull 후: gradle compileJava를 실행하거나 Eclipse 프로젝트를 새로고침하여 Q-classes를 재생성합니다
• Q-classes IDE 오류 시: gradle clean compileJava 또는 Eclipse → Project → Clean으로 재생성합니다

중복이 문제를 일으키지 않는 이유:

• 두 도구 모두 동일한 JPA 엔티티에서 동일한 Q-classes를 생성합니다
• 두 출력 디렉토리 모두 gitignore됩니다
• 각 도구는 자체 생성 클래스를 사용합니다 (classpath 충돌 없음)

로컬 개발 환경 설정

필수 환경 변수 (Tomcat)

-Deai.datasource.type=DEV
-Dinst.Name=emsSvr99
-Deai.tableowner=EMSADM
-Deai.systemmode=D
-Dfile.encoding=utf-8
-Dlogin.mode=db
-DLOGBACK_LOG_LEVEL=DEBUG
-Dlogback.configurationFile=classpath:logback-dev.xml
-Dhibernate.dialect=org.hibernate.dialect.Oracle12cDialect
-Dkjb_safedb.mode=fake

개발 환경 설정

애플리케이션은 WebContent/WEB-INF/properties/의 환경별 프로퍼티 파일을 통해 설정됩니다:

• env.D.properties - 개발 환경
• env.T.properties - 테스트/스테이징 환경
• env.P.properties - 운영 환경

프로필 설정

• -Pprofile=weblogic: web.xml 대신 weblogic-web.xml을 사용 (DefaultServlet 문제 해결)

데이터베이스 설정

애플리케이션은 다음을 지원합니다:

• Oracle: 운영 데이터베이스 (주)
• PostgreSQL/MariaDB: 대체 운영 DB
• H2: 테스트용 인메모리 데이터베이스

데이터베이스 연결은 eai.datasource.type 시스템 프로퍼티(DEV/STG/PROD)를 통해 설정됩니다.

SafeDB 암호화 라이브러리

kjb-safedb 모듈은 세 가지 동작 모드를 제공합니다:

• REAL: 실제 SafeDB 네이티브 라이브러리 사용
• FAKE: SHA-256/AES-256을 사용하는 개발 모드 (SafeDB 설치 불필요)
• NONE: 암호화 우회 (테스트 전용)

개발 시 SafeDB가 로컬에 설치되지 않은 경우 FAKE 모드를 사용합니다.

주요 기능

관리 콘솔은 eLink 플랫폼의 모든 측면을 관리합니다:

기능	설명
사용자 관리	사용자 계정 및 권한
트랜잭션 로그	온라인/배치/대량 트랜잭션 이력 조회
통계 및 대시보드	실시간 모니터링 및 메트릭
인터페이스 관리	API 인터페이스 구성
레이아웃 관리	메시지 레이아웃 정의
변환 규칙	메시지 변환 로직
어댑터 설정	프로토콜 어댑터 (HTTP, TCP 등)
라우팅 규칙	요청 라우팅 및 로드 밸런싱
배치 처리	배치 인터페이스 및 어댑터 관리
스케줄러	Quartz 기반 작업 스케줄링

배포 대상

애플리케이션은 다음 환경에 배포할 수 있습니다:

• Tomcat (기본, 개발)
• WebLogic 14.1.2 (운영, -Pprofile=weblogic 필요)
• JEUS (지원)
• JBoss/WildFly (descriptors와 함께 지원)

WebLogic 전용 빌드

WebLogic용 빌드 시, DefaultServlet 문제를 해결하기 위해 web.xml을 weblogic-web.xml로 교체하는 weblogic 프로필을 사용합니다:

gradle build -x test -Pprofile=weblogic

기술 스택

• Java 8: Gradle toolchain을 통해 강제
• Spring Framework 5.3.27: 코어 프레임워크 (MVC, Data JPA)
• Spring Data JPA 2.5.2: 리포지토리 추상화
• Hibernate 5.4.33/5.6.15: ORM 구현 (JPA/ORM)
• QueryDSL 5.0.0: 타입 안전 쿼리
• iBATIS 2.3.4: 레거시 SQL 매핑
• Quartz 2.2.1: 작업 스케줄링
• Apache POI 3.17: Excel 내보내기 기능
• Jackson 2.13.1: JSON 처리
• Logback 1.2.10: 로깅 프레임워크 (SLF4J와 함께)
• AWS SDK 2.20.142: S3 연동
• Kubernetes Client 18.0.1: K8s 관리
• EhCache: 캐싱, Lombok: 코드 생성, MapStruct: 객체 매핑

프로젝트 규칙

패키지 구조

com.eactive.eai
├── agent/command        - 커맨드 패턴 구현
├── common              - 공통 유틸리티, iBatis, JSON 직렬화
├── custom              - 고객사별 커스터마이제이션
├── rms                 - 메인 애플리케이션 코드
│   ├── bap             - 배치 처리 (BAP)
│   │   ├── adaptor     - 배치 어댑터
│   │   ├── manage      - 배치 관리 (메시지, 서버, 프로퍼티)
│   │   └── tansaction  - 배치 트랜잭션 추적
│   ├── bat             - 추가 배치 기능
│   ├── common          - RMS 공통 (필터, 시작, 서비스)
│   ├── data            - 데이터 엔티티, 리포지토리
│   ├── env             - 환경 설정
│   ├── kakao           - 카카오 연동
│   ├── onl             - 온라인 트랜잭션 관리
│   │   ├── apim        - API 관리 (포털 조직, 사용자, 승인)
│   │   ├── manage      - 리소스 관리
│   │   └── transaction - 트랜잭션 처리
│   └── service         - 비즈니스 서비스
└── ext.kjb             - 광주은행(KJB) 확장

Spring 설정

애플리케이션은 다음을 사용합니다:

• Root context: WebContent/WEB-INF/applicationContext.xml
• Servlet context: WebContent/WEB-INF/springapp-servlet.xml
• 환경별 설정: ${eai.systemmode} 시스템 프로퍼티 기반 로드
• 컴포넌트 스캔: 애노테이션 기반 설정 활성화

데이터 액세스 패턴

애플리케이션은 이중 퍼시스턴스를 사용합니다:

1. JPA/Hibernate - com.eactive.eai.rms.data.entity의 최신 엔티티 기반 코드용
2. iBatis - src/main/resources/com/eactive/eai/**/*.xml의 레거시 SQL 매핑용

리포지토리는 Spring Data JPA 규칙을 사용하며, 서비스는 @Service, 컨트롤러는 @RestController/@Controller를 사용합니다.

주요 초기화

• AppInitializer - 시스템 프로퍼티를 설정하는 메인 애플리케이션 시작 빈
• CustomizingAppInitializer - 고객사별 초기화
• 시스템 프로퍼티: inst.Name, eai.tableowner, eai.systemmode, theme.color

로깅

• SLF4J와 Logback 구현 사용
• LOGBACK_LOG_LEVEL 시스템 프로퍼티를 통한 로그 레벨 제어
• 모든 log4j 의존성 제외 (build.gradle에 설정)

IDE 설정

Eclipse

gradle eclipse

다음을 생성합니다:

• .project 및 .classpath 파일
• Eclipse WTP 설정 (context path: /monitoring)
• UTF-8 인코딩 설정
• QueryDSL/Lombok을 위한 애노테이션 프로세서 설정

IntelliJ IDEA

gradle idea

또는 IntelliJ에서 직접 "Import Gradle Project"를 사용합니다.

테스트

테스트에 사용되는 것들:

• JUnit 5 (Jupiter): 테스트 프레임워크
• Spring Boot Test 2.6.15: 통합 테스트 유틸리티
• H2 Database: 테스트용 인메모리 데이터베이스
• Mockito: 모킹 프레임워크 (Spring Boot Test를 통해)

테스트 리소스는 H2 호환 설정과 함께 src/test/resources에 있습니다.

KJB (광주은행) 전용 설정

프로퍼티 관리

KJB 전용 프로퍼티는 데이터베이스 테이블 TSEAIRM24에 그룹명 'Monitoring'으로 저장됩니다. com.eactive.ext.kjb.common.KjbProperty에서 관리하는 주요 프로퍼티:

이메일 알림 (EAI Batch를 통해)

• kjb.eai_batch.url - 이메일 발송을 위한 EAI 배치 서버 URL
  • Dev: http://172.31.32.111:10230/BATAppWeb/EaiBatCall
  • QA: http://172.31.33.111:10430/BATAppWeb/EaiBatCall
  • Prod: http://172.21.1.40:10860/BATAppWeb/EaiBatCall
• kjb.ums.eai_batch.send_dir - 이메일 파일 발송 디렉토리 (기본값: /Data/eapim/portal/sendmail/snd)
• kjb.ums.eai_batch.backup_dir - 이메일 백업 디렉토리 (기본값: /Data/eapim/portal/sendmail/bak)
• kjb.ums.eai_batch.interface_id - 고객 이메일용 인터페이스 ID (예: UAGFF00001UIE)

UMS (SMS/LMS/카카오톡) 연동

• kjb.ums.host_url - UMS API 엔드포인트
• kjb.ums.api_key - UMS API 인증 키
• kjb.ums.connection_timeout - 연결 타임아웃 (초 단위)
• kjb.ums.response_timeout - 응답 타임아웃 (초 단위)

보안

• 커스텀 패스워드 인코더: SafeDB 연동을 위한 KjbSafedbPasswordEncoder
• SafeDB 없이 로컬 개발 시 -Dkjb_safedb.mode=fake 설정

데이터베이스 벤더 지원

애플리케이션은 벤더별 SQL 매핑 파일을 통해 여러 데이터베이스를 지원합니다:

• Oracle: *-oracle.xml
• MariaDB: *-mariadb.xml
• PostgreSQL: *-postgresql.xml

데이터베이스 벤더는 프로퍼티 파일의 db.vendor와 hibernate.dialect를 통해 설정됩니다.

WAR 배포

WAR 파일은 context path /monitoring으로 eapim-admin.war로 빌드됩니다.

Weblogic 배포: weblogic-web.xml 설정을 포함하려면 -Pprofile=weblogic를 사용합니다.

중요 사항

• 인코딩: 시스템은 UTF-8을 사용합니다. CharacterEncodingFilter는 *.excel 패턴을 제외한 모든 요청에 UTF-8을 적용합니다.
• XSS 보호: CrossScriptingFilter가 com.eactive.eai.rms.common.filter.CrossScriptingFilter를 통해 모든 요청에 적용됩니다.
• 실시간 업데이트: 모든 관리 변경사항은 DB와 메모리 모두에 즉시 반영됩니다.
• 인스턴스 이름: 클러스터링을 위해 각 배포는 고유한 inst.Name을 가져야 합니다.
• 테이블 소유자: Oracle 스키마 소유자는 eai.tableowner 프로퍼티를 통해 지정됩니다.