API 패키지 구조, Internal/External 패턴, 데이터 흐름 상세 설명
## 문서 내용
- API 패키지 전체 구조 및 각 구성요소 설명
- Strategy Pattern을 통한 Internal/External 모드 전환
- 각 모드별 상세 동작 원리 및 데이터 흐름
- 설정 가이드 및 사용 예제
- 트러블슈팅 및 성능 최적화 가이드
## 주요 섹션
1. 개요 및 설계 원칙
2. 패키지 구조 (디렉토리 트리)
3. 아키텍처 패턴 (Strategy, DI, 계층화)
4. Internal Mode 상세 (GPKI, 정부 API 연동)
5. External Mode 상세 (REST API 호출)
6. 공통 구성요소 (VO, Properties, Config)
7. 데이터 흐름 다이어그램
8. 설정 가이드 (개발/운영 환경)
9. 사용 예제 (Controller, Service)
10. 모드 전환 시나리오
11. 트러블슈팅
12. 성능 최적화
13. 보안 고려사항
14. 확장 가능성
## 파일 위치
docs/API_ARCHITECTURE.md
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Mapper 중복 스캔 경고 해결 및 용도별 명확한 분리
## 문제
- DatabaseConfig에서 중복 패턴으로 Mapper 스캔
- "Bean already defined with the same name!" 경고 발생
- go.kr.project.**.mapper가 api.internal.mapper 포함하여 중복
## 해결
- DatabaseConfig → ApiMapperConfig로 변경 (API 전용)
- ProjectMapperConfig 신규 생성 (일반 프로젝트용)
## 변경사항
- ApiMapperConfig: go.kr.project.api.internal.mapper만 스캔
- ProjectMapperConfig: 일반 프로젝트 및 egovframework mapper 스캔
- carInspectionPenalty.**.mapper
- common.mapper
- login.mapper
- system.**.mapper
- egovframework.**.mapper
## 최종 구조
- API 전용: ApiMapperConfig
- 일반 프로젝트: ProjectMapperConfig
- 중복 없이 명확하게 분리
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
DatabaseConfig에서 중복 TransactionManager Bean 제거
## 문제
- DatabaseConfig.transactionManager와 EgovConfigTransaction.txManager 충돌
- "expected single matching bean but found 2" 에러 발생
## 해결
- DatabaseConfig에서 transactionManager Bean 제거
- egovframework의 txManager Bean 사용
- DatabaseConfig는 MapperScan만 담당
## 최종 설정
- DataSource: egovframework.config.DataSourceProxyConfig
- TransactionManager: egovframework.config.EgovConfigTransaction.txManager
- MapperScan: DatabaseConfig
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
패키지 리팩토링 후 Mapper 스캔 경로 수정
## 변경사항
- @MapperScan 경로 업데이트
- 기존: go.kr.project.vmis.mapper
- 변경: go.kr.project.api.internal.mapper 포함 전체 mapper 패키지
## 수정 파일
- DatabaseConfig.java
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
VO 중복 해결 및 패키지 구조 명확화
## 주요 변경사항
### 패키지 구조 재구성
- `go.kr.project.vmis` → `go.kr.project.api.internal`
- `go.kr.project.externalApi` → `go.kr.project.api.external`
- 공통 모델: `go.kr.project.api.model`
- 공통 VO: `go.kr.project.api.vo`
- 공통 설정: `go.kr.project.api.config`
### 새로운 구조
```
go.kr.project.api/
├── model/ # 공통 모델
│ ├── basic/ (BasicRequest, BasicResponse)
│ ├── ledger/ (LedgerRequest, LedgerResponse)
│ └── common/ (Envelope)
├── vo/ # 공통 API 응답 VO
│ ├── VehicleApiResponseVO
│ ├── VehicleBasicInfoVO
│ └── VehicleLedgerVO 등
├── config/ # 공통 설정
│ ├── properties/ (VmisProperties)
│ ├── ApiConstant
│ ├── VmisIntegrationConfig
│ └── DatabaseConfig
├── VehicleInfoService # 공통 인터페이스
├── internal/ # 내부 모드 (기존 vmis)
│ ├── client/
│ ├── config/
│ ├── controller/
│ ├── gpki/
│ ├── mapper/
│ ├── model/ # 내부 전용 DB VO
│ ├── service/
│ └── util/
└── external/ # 외부 모드 (기존 externalApi)
└── service/
```
### VO 중복 제거
- ✅ history 패키지와 api.internal 패키지의 VO 명확히 구분
- ✅ 공통 모델은 api.model에서 공유
- ✅ Bean 충돌 완전 해결
### MyBatis 업데이트
- mapper 디렉토리: `mybatis/mapper/vmis` → `mybatis/mapper/api-internal`
- namespace: `go.kr.project.vmis` → `go.kr.project.api.internal`
### application.yml 업데이트
- mapper-locations: `api-internal/**/*_maria.xml`
## 장점
✅ 패키지 구조 명확화 (internal/external 구분)
✅ 공통 모델 공유로 중복 제거
✅ 더 나은 아키텍처
✅ 모드별 책임 명확
## 빌드 성공 확인 ✅🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
VO, Service, Mapper 클래스 이름 충돌 문제 해결
## 문제
- history 패키지와 vmis 패키지에 동일한 이름의 VO 클래스 존재
- CarBassMatterInqireVO, CarLedgerFrmbkVO, CarLedgerFrmbkDtlVO 충돌
- Bean 생성 오류 발생
## 해결
모든 VMIS 패키지 클래스에 Vmis prefix 추가:
### VO 클래스 (충돌 해결)
- CarBassMatterInqireVO → VmisCarBassMatterInqireVO
- CarLedgerFrmbkVO → VmisCarLedgerFrmbkVO
- CarLedgerFrmbkDtlVO → VmisCarLedgerFrmbkDtlVO
### Service 클래스
- CarBassMatterInqireService → VmisCarBassMatterInqireService
- CarBassMatterInqireLogService → VmisCarBassMatterInqireLogService
- CarLedgerFrmbkService → VmisCarLedgerFrmbkService
- CarLedgerFrmbkLogService → VmisCarLedgerFrmbkLogService
- RequestEnricher → VmisRequestEnricher
### Mapper 클래스
- CarBassMatterInqireMapper → VmisCarBassMatterInqireMapper
- CarLedgerFrmbkMapper → VmisCarLedgerFrmbkMapper
### MyBatis XML 업데이트
- mapper namespace 및 resultType 변경
- CarBassMatterInqireMapper_maria.xml
- CarLedgerFrmbkMapper_maria.xml
## 빌드 성공 확인 ✅
- Bean 충돌 완전 해결
- 전체 컴파일 성공
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
내부/외부 API 호출을 YAML 설정으로 전환할 수 있는 Strategy Pattern 구현
## 주요 변경사항
### 1. Strategy Pattern 구현
- VehicleInfoService 인터페이스 생성 (공통 추상화)
- InternalVehicleInfoServiceImpl: 내부 VMIS 모듈 직접 호출
- ExternalVehicleInfoServiceImpl: 외부 REST API 호출
- @ConditionalOnProperty로 mode에 따라 Bean 자동 선택
### 2. Bean 충돌 해결
- HttpClientConfig의 restTemplate → vmisRestTemplate으로 변경
- GovernmentApiClient에 @Qualifier("vmisRestTemplate") 추가
- 기존 RestTemplateConfig와 충돌 방지
### 3. 설정 확장
- VmisProperties에 integration, external 속성 추가
- vmis.integration.mode: internal/external 설정 지원
- vmis.external.api.url: 외부 API 서버 URL 설정
### 4. 모델 변환 유틸리티
- VehicleResponseMapper 생성
- 내부 모델(BasicResponse, LedgerResponse) → 외부 VO 변환
### 5. 모니터링 및 로깅
- VmisIntegrationConfig: 시작 시 활성 모드 출력
- 각 구현체에 [Internal Mode]/[External Mode] 로그 추가
## 사용 방법
### Internal Mode (내부 모듈 직접 호출)
```yaml
vmis:
integration:
mode: internal
```
### External Mode (외부 REST API 호출)
```yaml
vmis:
integration:
mode: external
external:
api:
url: http://localhost:8081/api/v1/vehicles
```
## 빌드 성공 확인 ✅
- Bean 충돌 해결 완료
- 전체 컴파일 성공
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- 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 설정 통합
- MyBatis 매퍼 경로 추가
빌드 성공 확인 ✅
Co-Authored-By: Claude <noreply@anthropic.com>
박성영