djb-eapim/eapim-admin

Fork 0

Files

T

Rinjae 6e1e077ac6 claude

2025-12-05 17:28:47 +09:00

17 KiB

Raw Blame History

AI-Assisted Development Guide

이 문서는 AI 어시스턴트가 이 저장소의 코드를 이해하고 기여하는 데 필요한 가이드를 제공합니다.

프로젝트 주요 특징

AI 어시스턴트가 작업을 시작하기 전에 반드시 이해해야 할 핵심적인 특징들입니다.

하이브리드 데이터 액세스: 이 프로젝트는 JPA(Hibernate)와 iBATIS를 함께 사용합니다.
- 신규 기능: 항상 JPA와 Spring Data 리포지토리를 사용해야 합니다.
- 레거시 코드: 기존 iBATIS (*.xml 매퍼) 코드를 수정할 때는 해당 패턴을 따라야 합니다.
멀티 모듈 Gradle 프로젝트: settings.gradle에 정의된 것처럼 여러 하위 모듈(elink-online-*, kjb-* 등)로 구성되어 있습니다. 특정 기능은 다른 모듈에 위치할 수 있습니다.
QueryDSL 코드 생성: 빌드 시 QueryDSL을 사용하여 Q-class가 자동으로 생성됩니다. IDE에서 엔티티를 찾을 수 없다고 표시되면, kjb-gradle.sh compileJava를 먼저 실행하여 코드를 생성해야 합니다.
고객사별 커스터마이징: ext.kjb 또는 custom 패키지는 특정 고객사(광주은행)를 위한 코드를 포함하므로, 일반적인 기능 수정 시에는 주의가 필요합니다.

프로젝트 개요

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 대신 kjb-gradle.sh 스크립트를 사용해야 합니다.

스크립트 위치: /c/eactive/workspaces/shell-scripts/kjb-gradle.sh
PATH에 등록되어 있으므로 바로 kjb-gradle.sh 명령어 사용 가능

# 표준 빌드
kjb-gradle.sh build

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

# WAR 파일 빌드
kjb-gradle.sh war

# 클린 빌드
kjb-gradle.sh clean build

테스트 실행

# 모든 테스트 실행
kjb-gradle.sh test

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

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

개발 태스크

# 패키징 없이 클래스만 컴파일
kjb-gradle.sh classes

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

# 의존성 트리 보기
kjb-gradle.sh dependencies

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

로컬 개발 빠른 시작

새로운 환경에서 프로젝트를 처음 설정하고 실행하는 권장 절차입니다.

IDE 설정 파일 생성 (최초 1회)

# IntelliJ IDEA 사용 시
kjb-gradle.sh idea

# Eclipse 사용 시
kjb-gradle.sh eclipse

QueryDSL 등 소스 코드 생성
```
kjb-gradle.sh compileJava
```
전체 빌드 및 테스트 실행
```
kjb-gradle.sh build
```
IDE에서 프로젝트 열기
- kjb-gradle.sh idea 또는 kjb-gradle.sh eclipse 실행 후, IDE에서 프로젝트를 엽니다.
실행 구성(Run Configuration) 설정
- 사용하는 WAS(Tomcat 등)에 eapim-admin 프로젝트를 배포하도록 설정합니다.
- VM Options에 위에 명시된 "필수 환경 변수 (Tomcat)"를 모두 추가합니다.
서버 실행
- IDE에서 설정한 실행 구성을 시작하여 서버를 실행합니다.

아키텍처 및 모듈 의존성

멀티 모듈 구조

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가 두 위치에 생성됩니다:

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

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

생성된 코드 작업하기

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

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

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

로컬 개발 환경 설정

필수 환경 변수 (Tomcat)

다음은 로컬 Tomcat 환경에서 개발 시 필요한 시스템 프로퍼티(-D)입니다. 설정 방법: IntelliJ, Eclipse 등 IDE의 실행 구성(Run Configuration)에서 'VM options'에 추가하거나, 사용하는 Tomcat의 bin 폴더에 setenv.bat (Windows) 또는 setenv.sh (Linux/macOS) 파일을 생성하여 아래 내용들을 CATALINA_OPTS 또는 JAVA_OPTS 환경 변수에 추가합니다.

-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 프로필을 사용합니다:

kjb-gradle.sh 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} 시스템 프로퍼티 기반 로드
컴포넌트 스캔: 애노테이션 기반 설정 활성화

데이터 액세스 패턴

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

JPA/Hibernate - com.eactive.eai.rms.data.entity의 최신 엔티티 기반 코드용
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

kjb-gradle.sh eclipse

다음을 생성합니다:

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

IntelliJ IDEA

kjb-gradle.sh 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
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 프로퍼티를 통해 지정됩니다.

17 KiB Raw Blame History

AI-Assisted Development Guide

프로젝트 주요 특징

프로젝트 개요

빌드 및 개발 명령어

애플리케이션 빌드

주요 기능

빌드 및 개발 명령어

빌드 명령어

테스트 실행

개발 태스크

로컬 개발 빠른 시작

아키텍처 및 모듈 의존성

멀티 모듈 구조

하이브리드 ORM 방식

코드 생성

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

생성된 코드 작업하기

로컬 개발 환경 설정

필수 환경 변수 (Tomcat)

개발 환경 설정

데이터베이스 설정

SafeDB 암호화 라이브러리

주요 기능

배포 대상

WebLogic 전용 빌드

기술 스택

프로젝트 규칙

패키지 구조

Spring 설정

데이터 액세스 패턴

주요 초기화

로깅

IDE 설정

Eclipse

IntelliJ IDEA

테스트

KJB (광주은행) 전용 설정

프로퍼티 관리

보안

데이터베이스 벤더 지원

WAR 배포

중요 사항

17 KiB

Raw Blame History