docs: VMIS 통합 완료 가이드 문서 추가
완료된 작업 요약 및 사용 가이드 문서 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>internalApi
박성영
1 month ago
parent
be4c926029
commit
a2dc40a0d7
@ -0,0 +1,349 @@
|
||||
# VMIS 통합 완료 및 사용 가이드
|
||||
|
||||
## 📋 작업 완료 요약
|
||||
|
||||
VMIS-interface 프로젝트의 모든 코드를 VIPS 내부로 통합하고, YAML 설정을 통해 내부/외부 모드를 자유롭게 전환할 수 있는 기능을 구현했습니다.
|
||||
|
||||
### ✅ 완료된 작업
|
||||
|
||||
#### 1단계: 코드 마이그레이션 (완료)
|
||||
- ✅ VMIS-interface 전체 코드 이식 (33개 Java 파일, 2개 XML)
|
||||
- ✅ 패키지 변경: `com.vmis.interfaceapp` → `go.kr.project.vmis`
|
||||
- ✅ Spring Boot 3 → 2 호환: `jakarta` → `javax`
|
||||
- ✅ Java 17 → 8 호환: Text Blocks, List.of() 제거
|
||||
- ✅ HttpClient 5 → 4 변환
|
||||
- ✅ GPKI 라이브러리 추가
|
||||
- ✅ application.yml에 VMIS 설정 통합
|
||||
|
||||
#### 2단계: Strategy Pattern 구현 (완료)
|
||||
- ✅ VehicleInfoService 인터페이스 생성
|
||||
- ✅ InternalVehicleInfoServiceImpl: 내부 VMIS 모듈 직접 호출
|
||||
- ✅ ExternalVehicleInfoServiceImpl: 외부 REST API 호출
|
||||
- ✅ VmisIntegrationConfig: 모드 모니터링 및 로깅
|
||||
- ✅ VehicleResponseMapper: 모델 변환 유틸리티
|
||||
|
||||
#### 3단계: Bean 충돌 해결 (완료)
|
||||
- ✅ `restTemplate` → `vmisRestTemplate`으로 변경
|
||||
- ✅ @Qualifier 어노테이션 추가
|
||||
- ✅ 빌드 성공 확인
|
||||
|
||||
---
|
||||
|
||||
## 🎯 주요 기능
|
||||
|
||||
### 1. 모드 전환 (YAML 설정)
|
||||
|
||||
**Internal Mode: 내부 VMIS 모듈 직접 호출**
|
||||
```yaml
|
||||
# application.yml
|
||||
vmis:
|
||||
integration:
|
||||
mode: internal # 내부 모듈 사용
|
||||
```
|
||||
|
||||
**External Mode: 외부 REST API 호출**
|
||||
```yaml
|
||||
# application.yml
|
||||
vmis:
|
||||
integration:
|
||||
mode: external # 외부 API 사용
|
||||
external:
|
||||
api:
|
||||
url: http://localhost:8081/api/v1/vehicles
|
||||
```
|
||||
|
||||
### 2. 자동 Bean 선택
|
||||
|
||||
Spring Boot의 `@ConditionalOnProperty` 어노테이션을 사용하여 설정에 따라 자동으로 적절한 구현체를 선택합니다:
|
||||
|
||||
- **mode: internal** → `InternalVehicleInfoServiceImpl` 활성화
|
||||
- **mode: external** → `ExternalVehicleInfoServiceImpl` 활성화 (기본값)
|
||||
|
||||
### 3. 통합 인터페이스
|
||||
|
||||
```java
|
||||
@Autowired
|
||||
private VehicleInfoService vehicleInfoService;
|
||||
|
||||
// 단일 차량 조회
|
||||
VehicleApiResponseVO response = vehicleInfoService.getVehicleInfo("12가3456");
|
||||
|
||||
// 여러 차량 일괄 조회
|
||||
List<VehicleApiResponseVO> responses = vehicleInfoService.getVehiclesInfo(
|
||||
Arrays.asList("12가3456", "34나5678")
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 생성/수정된 파일
|
||||
|
||||
### 새로 생성된 파일
|
||||
1. **공통 인터페이스**
|
||||
- `src/main/java/go/kr/project/common/service/VehicleInfoService.java`
|
||||
|
||||
2. **Strategy Pattern 구현체**
|
||||
- `src/main/java/go/kr/project/vmis/service/InternalVehicleInfoServiceImpl.java`
|
||||
- `src/main/java/go/kr/project/externalApi/service/ExternalVehicleInfoServiceImpl.java`
|
||||
|
||||
3. **설정 및 유틸리티**
|
||||
- `src/main/java/go/kr/project/vmis/config/VmisIntegrationConfig.java`
|
||||
- `src/main/java/go/kr/project/vmis/util/VehicleResponseMapper.java`
|
||||
|
||||
### 수정된 파일
|
||||
1. `src/main/java/go/kr/project/vmis/config/HttpClientConfig.java`
|
||||
- Bean 이름 변경: `restTemplate` → `vmisRestTemplate`
|
||||
|
||||
2. `src/main/java/go/kr/project/vmis/client/GovernmentApiClient.java`
|
||||
- @Qualifier 추가: `@Qualifier("vmisRestTemplate")`
|
||||
|
||||
3. `src/main/java/go/kr/project/vmis/config/properties/VmisProperties.java`
|
||||
- IntegrationProps, ExternalProps 추가
|
||||
|
||||
---
|
||||
|
||||
## 🔧 설정 상세
|
||||
|
||||
### application.yml 전체 구조
|
||||
|
||||
```yaml
|
||||
vmis:
|
||||
# ===== 모드 선택 =====
|
||||
integration:
|
||||
mode: internal # internal 또는 external
|
||||
|
||||
# ===== Internal Mode 설정 =====
|
||||
system:
|
||||
infoSysId: "41-345"
|
||||
infoSysIp: "${SERVER_IP:105.19.10.135}"
|
||||
regionCode: "41460"
|
||||
departmentCode: ""
|
||||
chargerId: ""
|
||||
chargerIp: ""
|
||||
chargerNm: ""
|
||||
|
||||
gpki:
|
||||
enabled: "N" # Y: 암호화 사용, N: 암호화 미사용
|
||||
useSign: true
|
||||
charset: "UTF-8"
|
||||
certServerId: "SVR5640020001"
|
||||
targetServerId: "SVR1500000015"
|
||||
# ... (기타 GPKI 설정)
|
||||
|
||||
gov:
|
||||
scheme: "http"
|
||||
host: "10.188.225.94:29001"
|
||||
basePath: "/piss/api/molit"
|
||||
connectTimeoutMillis: 5000
|
||||
readTimeoutMillis: 10000
|
||||
services:
|
||||
basic:
|
||||
path: "/SignguCarBassMatterInqireService"
|
||||
cntcInfoCode: "AC1_FD11_01"
|
||||
apiKey: "${GOV_API_KEY_BASIC:...}"
|
||||
cvmisApikey: "${GOV_CVMIS_API_KEY_BASIC:...}"
|
||||
ledger:
|
||||
path: "/SignguCarLedgerFrmbkService"
|
||||
cntcInfoCode: "AC1_FD11_02"
|
||||
apiKey: "${GOV_API_KEY_LEDGER:...}"
|
||||
cvmisApikey: "${GOV_CVMIS_API_KEY_LEDGER:...}"
|
||||
|
||||
# ===== External Mode 설정 =====
|
||||
external:
|
||||
api:
|
||||
url: "http://localhost:8081/api/v1/vehicles"
|
||||
connectTimeoutMillis: 5000
|
||||
readTimeoutMillis: 10000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 모드별 특징
|
||||
|
||||
### Internal Mode (내부 모듈 직접 호출)
|
||||
|
||||
**장점:**
|
||||
- ✅ 네트워크 오버헤드 없음 (더 빠른 성능)
|
||||
- ✅ 외부 서버 불필요
|
||||
- ✅ 단일 애플리케이션 배포
|
||||
- ✅ 직접 정부 시스템과 통신
|
||||
|
||||
**요구사항:**
|
||||
- 정부 API 접근 권한 필요
|
||||
- GPKI 인증서 설정 (운영 환경)
|
||||
- 방화벽 정책 설정
|
||||
|
||||
**사용 시나리오:**
|
||||
- 운영 환경 배포
|
||||
- 단일 서버 구성
|
||||
- 높은 성능이 요구되는 경우
|
||||
|
||||
### External Mode (외부 REST API 호출)
|
||||
|
||||
**장점:**
|
||||
- ✅ 마이크로서비스 아키텍처 지원
|
||||
- ✅ VMIS 모듈 독립 배포 가능
|
||||
- ✅ 여러 시스템에서 공유 가능
|
||||
- ✅ 부하 분산 가능
|
||||
|
||||
**요구사항:**
|
||||
- VMIS-interface 서버가 실행 중이어야 함
|
||||
- 네트워크 연결 필요
|
||||
|
||||
**사용 시나리오:**
|
||||
- 개발 환경 (VMIS-interface 서버 별도 실행)
|
||||
- 마이크로서비스 구조
|
||||
- 여러 클라이언트가 VMIS 기능을 공유하는 경우
|
||||
|
||||
---
|
||||
|
||||
## 🚀 시작 로그 예시
|
||||
|
||||
### Internal Mode 시작 시
|
||||
|
||||
```
|
||||
========================================
|
||||
VMIS Integration Mode: internal
|
||||
Active Implementation: InternalVehicleInfoServiceImpl
|
||||
========================================
|
||||
[Internal Mode] 내부 VMIS 모듈을 직접 사용합니다
|
||||
- 정부 API 호스트: http://10.188.225.94:29001
|
||||
- 기본사항 조회 경로: /SignguCarBassMatterInqireService
|
||||
- 등록원부 조회 경로: /SignguCarLedgerFrmbkService
|
||||
- GPKI 암호화: N
|
||||
- 연결 타임아웃: 5000ms
|
||||
- 읽기 타임아웃: 10000ms
|
||||
- GPKI 암호화가 비활성화되어 있습니다. 개발 환경에서만 사용하세요.
|
||||
```
|
||||
|
||||
### External Mode 시작 시
|
||||
|
||||
```
|
||||
========================================
|
||||
VMIS Integration Mode: external
|
||||
Active Implementation: ExternalVehicleInfoServiceImpl
|
||||
========================================
|
||||
[External Mode] 외부 REST API를 사용합니다
|
||||
- 외부 API URL: http://localhost:8081/api/v1/vehicles
|
||||
- 연결 타임아웃: 5000ms
|
||||
- 읽기 타임아웃: 10000ms
|
||||
- 외부 VMIS-interface 서버가 실행 중이어야 합니다.
|
||||
- 기본사항 조회: POST http://localhost:8081/api/v1/vehicles/basic
|
||||
- 등록원부 조회: POST http://localhost:8081/api/v1/vehicles/ledger
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 테스트 방법
|
||||
|
||||
### 1. Internal Mode 테스트
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
vmis:
|
||||
integration:
|
||||
mode: internal
|
||||
```
|
||||
|
||||
```bash
|
||||
# 애플리케이션 시작
|
||||
./gradlew bootRun
|
||||
|
||||
# 로그에서 "VMIS Integration Mode: internal" 확인
|
||||
```
|
||||
|
||||
### 2. External Mode 테스트
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
vmis:
|
||||
integration:
|
||||
mode: external
|
||||
```
|
||||
|
||||
```bash
|
||||
# 1. VMIS-interface 서버 시작 (별도 터미널)
|
||||
cd D:\workspace\git\VMIS-interface
|
||||
./gradlew bootRun
|
||||
|
||||
# 2. VIPS 애플리케이션 시작
|
||||
cd D:\workspace\git\VIPS
|
||||
./gradlew bootRun
|
||||
|
||||
# 로그에서 "VMIS Integration Mode: external" 확인
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 코드 사용 예시
|
||||
|
||||
### 기존 코드 수정 불필요
|
||||
|
||||
기존에 `ExternalVehicleApiService`를 사용하던 코드는 수정 없이 `VehicleInfoService`로 변경하면 됩니다:
|
||||
|
||||
**변경 전:**
|
||||
```java
|
||||
@Autowired
|
||||
private ExternalVehicleApiService externalVehicleApiService;
|
||||
|
||||
VehicleApiResponseVO response = externalVehicleApiService.getVehicleInfo("12가3456");
|
||||
```
|
||||
|
||||
**변경 후:**
|
||||
```java
|
||||
@Autowired
|
||||
private VehicleInfoService vehicleInfoService;
|
||||
|
||||
VehicleApiResponseVO response = vehicleInfoService.getVehicleInfo("12가3456");
|
||||
```
|
||||
|
||||
설정 파일만 변경하면 자동으로 내부/외부 모드가 전환됩니다!
|
||||
|
||||
---
|
||||
|
||||
## 📝 커밋 내역
|
||||
|
||||
### 1차 커밋: 기본 통합
|
||||
```
|
||||
feat: VMIS-interface 통합 (Spring Boot 2.7 호환)
|
||||
- VMIS-interface 전체 코드 이식 (33개 Java 파일, 2개 XML)
|
||||
- 패키지 변경, Spring Boot 호환, Java 호환
|
||||
- 빌드 성공 확인 ✅
|
||||
```
|
||||
|
||||
### 2차 커밋: Strategy Pattern
|
||||
```
|
||||
feat: VMIS 통합 모드 전환 기능 구현 (Strategy Pattern)
|
||||
- VehicleInfoService 인터페이스 및 구현체
|
||||
- Bean 충돌 해결
|
||||
- 설정 확장 및 모니터링
|
||||
- 빌드 성공 확인 ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 주의사항
|
||||
|
||||
### Bean 이름 변경
|
||||
- 기존 `restTemplate` → 새로 추가된 `vmisRestTemplate`
|
||||
- 기존 RestTemplateConfig의 restTemplate은 그대로 유지
|
||||
- VMIS 내부 모듈은 vmisRestTemplate 사용
|
||||
|
||||
### 기본 모드
|
||||
- 설정이 없거나 `mode`가 지정되지 않으면 **external 모드**가 기본값
|
||||
- Internal 모드를 사용하려면 명시적으로 `mode: internal` 설정 필요
|
||||
|
||||
### GPKI 인증서
|
||||
- 운영 환경에서는 반드시 `gpki.enabled: Y` 설정
|
||||
- 개발 환경에서는 `gpki.enabled: N` 사용 가능
|
||||
|
||||
---
|
||||
|
||||
## 🎉 완료!
|
||||
|
||||
모든 작업이 성공적으로 완료되었습니다. YAML 설정만으로 내부/외부 모드를 자유롭게 전환할 수 있습니다.
|
||||
|
||||
**질문이나 문제가 있으면 다음 문서를 참조하세요:**
|
||||
- `VMIS_INTERFACE_INTEGRATION_ANALYSIS.md`: 통합 분석 문서
|
||||
- `VMIS_INTERFACE_MIGRATION_PLAN.md`: 마이그레이션 계획
|
||||
- `VMIS_INTEGRATION_STRATEGY_DESIGN.md`: Strategy Pattern 설계
|
||||
Loading…
Reference in New Issue