djb-eapim/eapim-admin
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity
Files
d19a9eb593649b7e7945a062a777add57978a199
eapim-admin/readme.md
T
eastargh d19a9eb593
eapim-admin CI / build (push) Has been cancelled
Details
제주은행용 갱신
2026-09-04 11:31:15 +09:00

366 lines
15 KiB
Markdown
Raw Blame History

# 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`) 를 사용합니다.
```bash
# 표준 빌드
./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 이후
```bash
./gradlew compileJava # Q-class IDE 오류 시: ./gradlew clean compileJava
```
2. **빌드/테스트**
```bash
./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관리 > 모니터링 프라퍼티)
**계정관리**
- `rms.DUAL_LOGIN_ENABLED` - 중복 로그인 허용 여부
- `rms.auto.logout.timeout` - 자동 로그아웃 시간(분)
- `djb.sms_auth.enabled` - 로그인시 2-factor 인증 적용여부
- `djb.sms_auth.fixed_value` - sms_auth.mode=fixed일 경우 고정인증값
- `djb.sms_auth.mode` - 2-factor 인증 모드 (real:실제, fixed:고정값-개발환경에서 사용)
- `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 인증 여부
**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 상태 변화를 모니터링한다(서버수 만큼 등록)
- 실행간격(1분)이 짧아서 CLUSTERED는 적용을 못하고, 서버마다 번갈아 가면서 실행하도록 설정
- API 상태 변화 발생시 직원에게 메신저 및 제휴사에게 웹훅을 발송한다.
- `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를 발송한다 (서버수 만큼 등록)
- 실행간격(6초)이 짧아서 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` 로 교체).
```bash
# 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 경유)
```bash
./gradlew test
./gradlew test --tests "com.eactive.eai.rms.*"
```
## 문서
- **프로젝트 상세 지침**: `CLAUDE.md` (AI 어시스턴트 및 개발자용 마스터 문서, 한글)
- **사용자 가이드**: `WebContent/guide/` (docsify)
## 라이선스
사내 전용(proprietary). 제주은행 eLink EMS.
Reference in New Issue View Git Blame Copy Permalink