VMIS-interface/README.md

# VMIS-interface

시군구 시스템이 도로교통공단(차세대교통안전공단) Open API와 연계하여 자동차 기본사항 조회와 자동차 등록원부(갑) 조회 기능을 제공하는 Spring Boot 애플리케이션입니다. 모든 요청/응답은 공통 래퍼 `Envelope<T>` 형태를 사용하며, 기본사항 조회의 경우 요청과 응답(또는 오류)을 로그 테이블에 적재합니다.

최종 업데이트: 2025-11-05 14:00

---

## 개요
- 목적
  - 자동차 기본사항 조회
  - 자동차 등록원부(갑) 조회
  - 요청/응답 로그 적재(기본사항 조회 도메인)
- 주요 특징
  - `Envelope<T>` 공통 래퍼 구조 사용
  - 환경 프로파일 분리: `dev`, `prd`
  - GPKI 연계: 운영은 실서명(`RealGpkiService`), 개발은 `NoopGpkiService`
  - MyBatis + MariaDB를 통한 로깅 및 조회 이력 관리(기본사항)
- 추후 기능 개발 사항
  - request data[] 배열과 response data[] 배열을 별도로 처리하는 기능 추가, 현재 1건의 차량번호와 1건의 response 만 처리하도록 되어있음
  - response.getRecord().get(0); || response.getBody().getData().get(0); 으로 모두 처리함, 단건이 아닌 배열처리 기능 필요함
  - 배열에 따른 로깅기능도 같이 수정되어야함, 배열만큼 rows insert(그룹해줄수 있는 tx id 컬럼 추가) or 마스터->디테일 테이블 구조로 변경

---

## 기술 스택
- 언어: Java 17
- 프레임워크: Spring Boot 3.3.x (Web, Validation, JDBC)
- 퍼시스턴스: MyBatis, MariaDB JDBC
- HTTP 클라이언트: Apache HttpClient5
- 문서화: springdoc-openapi (Swagger UI)
- 로깅: Logback
- 빌드 도구: Gradle(Wrapper 포함)
- GPKI: JNI 라이브러리(`lib/libgpkiapi_jni_1.5.jar`)

---

## 진입점(Entry Points)
- 애플리케이션 메인 클래스
  - `src/main/java/com/vmis/interfaceapp/VmisInterfaceApplication.java`
- REST 컨트롤러
  - `src/main/java/com/vmis/interfaceapp/controller/VehicleInterfaceController.java`
  - 기본 경로: `/api/v1/vehicles`
    - 기본사항 조회: `POST /api/v1/vehicles/basic`
    - 등록원부(갑) 조회: `POST /api/v1/vehicles/ledger`

---

## 시스템 요구 사항
- JDK 17 이상
- Gradle Wrapper 사용(별도 설치 불필요)
- MariaDB 인스턴스(개발/운영 DB)
- (운영) GPKI 인증서/개인키 및 네이티브 라이브러리 로딩 환경

---

## 설정 파일 및 프로파일
- 기본 설정: `src/main/resources/application.yml`
  - 서버 포트 기본값: `8081`
  - 전역 DB 타입 변수: `Globals.DbType: maria`
- 개발: `src/main/resources/application-dev.yml`
- 운영: `src/main/resources/application-prd.yml`

프로파일 활성화 방법
- JVM 옵션: `-Dspring.profiles.active=dev` 또는 `prd`
- 환경변수: `SPRING_PROFILES_ACTIVE=dev` 또는 `prd`

중요: 예시 설정 파일에 포함된 계정/키 값은 샘플이거나 개발용입니다. 실제 운영 환경에서는 반드시 환경변수/비밀 관리(예: Vault, KMS)로 주입하고, 파일에는 값을 남기지 마세요.

### 주요 설정 키(요약)
- Spring DataSource (`spring.datasource.*`)
  - `url`, `username`, `password`, `hikari.*`
- MyBatis (`mybatis.*`)
  - `config-location`, `mapper-locations`, `type-aliases-package`
- 로깅(`logging.*`)
  - `config`, `file.path`, `level.*`
- 서비스 도메인(`vmis.*`)
  - `vmis.system.*`: 시스템/담당자 식별 정보
  - `vmis.gpki.*`: GPKI 사용 여부, 경로, 패스워드 등
  - `vmis.gov.*`: 외부 API 엔드포인트, 타임아웃, 서비스 경로/키

### 권장 환경변수 매핑(예)
- `SPRING_PROFILES_ACTIVE=dev`
- `DB_URL`, `DB_USERNAME`, `DB_PASSWORD`
- `VMIS_SYSTEM_INFO_SYS_ID`, `VMIS_SYSTEM_INFO_SYS_IP`, `VMIS_SYSTEM_SIGUNGU_CODE` 등
- `VMIS_GPKI_ENABLED`, `VMIS_GPKI_ENV_PRIVATE_KEY_PASSWD`, `VMIS_GPKI_SIG_PRIVATE_KEY_PASSWD`
- `VMIS_GOV_HOST`, `VMIS_GOV_SERVICES_BASIC_APIKEY`, `VMIS_GOV_SERVICES_LEDGER_APIKEY`

프로퍼티 바인딩 클래스: `com.vmis.interfaceapp.config.properties.VmisProperties`

---

## 설치 및 실행

### 1) 소스 가져오기
```
git clone <repo-url>
cd VMIS-interface
```

### 2) 빌드
```
# 테스트 포함 빌드
./gradlew build

# 테스트 제외 빌드(필요 시)
./gradlew clean build -x test
```
Windows PowerShell에서는 `./gradlew.bat` 사용 가능합니다.

### 3) 실행

#### 방법 1: Gradle bootRun 사용 (개발 권장)

**개발 환경 (포트 8081)**
```bash
# Linux/Mac
./gradlew bootRun --args='--spring.profiles.active=dev'

# Windows
gradlew.bat bootRun --args='--spring.profiles.active=dev'
```

**운영 환경 (포트 8080)**
```bash
# Linux/Mac
./gradlew bootRun --args='--spring.profiles.active=prd'

# Windows
gradlew.bat bootRun --args='--spring.profiles.active=prd'
```

#### 방법 2: JAR 파일 실행 (배포 권장)

**개발 환경**
```bash
# Linux/Mac
java -Dspring.profiles.active=dev -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar

# Windows PowerShell
java -Dspring.profiles.active=dev -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar

# 또는 환경변수 사용 (Windows PowerShell)
$env:SPRING_PROFILES_ACTIVE = "dev"
java -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar
```

**운영 환경 (환경변수 포함)**
```bash
# Linux/Mac
export SPRING_PROFILES_ACTIVE=prd
export VMIS_SYSTEM_INFO_SYS_ID="41-345"
export VMIS_SYSTEM_SIGUNGU_CODE="41460"
java -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar

# Windows PowerShell
$env:SPRING_PROFILES_ACTIVE = "prd"
$env:VMIS_SYSTEM_INFO_SYS_ID = "41-345"
$env:VMIS_SYSTEM_SIGUNGU_CODE = "41460"
java -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar
```

#### 백그라운드 실행 (Linux 서버)
```bash
# nohup 사용 (기본 java 경로, 콘솔 출력을 app.log에 저장)
nohup java -Dspring.profiles.active=prd -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar > app.log 2>&1 &

# Java 경로를 직접 지정하는 방법 (Java 17 이상)
nohup /usr/bin/java -Dspring.profiles.active=prd -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar > app.log 2>&1 &

# 또는 사용자 지정 Java 경로 사용
nohup /opt/jdk-17/bin/java -Dspring.profiles.active=prd -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar > app.log 2>&1 &

# 콘솔 출력을 남기지 않을 때 (애플리케이션 자체 로그는 logback-spring.xml 설정에 따라 별도 저장됨)
# 개발 환경
nohup /usr/bin/java -Dspring.profiles.active=dev -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar > /dev/null 2>&1 &

# 운영 환경 (애플리케이션 로그: d:/data/VMIS-interface/logs/vmis-interface.log)
nohup /usr/bin/java -Dspring.profiles.active=prd -jar build/libs/VMIS-interface-0.0.1-SNAPSHOT.jar > /dev/null 2>&1 &

# Java 경로 확인 방법
which java
# 또는
readlink -f $(which java)

# 프로세스 확인
ps aux | grep VMIS-interface

# 종료
kill -9 <PID>
```

**참고:** `/dev/null` 사용 시 콘솔 출력만 버려지며, 애플리케이션 자체 로그는 `logging.file.path` 설정에 따라 정상적으로 기록됩니다.
- 개발: `d:/data/VMIS-interface/logs/vmis-interface.log`
- 운영: `d:/data/VMIS-interface/logs/vmis-interface.log`

#### 백그라운드 실행 (Windows 서버)

**PowerShell - 백그라운드 프로세스로 실행**
```powershell
# 개발 환경 (콘솔 출력을 app.log에 저장)
Start-Process -NoNewWindow -FilePath "java" -ArgumentList "-Dspring.profiles.active=dev","-jar","build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar" -RedirectStandardOutput "app.log" -RedirectStandardError "app.log"

# 운영 환경 (콘솔 출력을 app.log에 저장)
Start-Process -NoNewWindow -FilePath "java" -ArgumentList "-Dspring.profiles.active=prd","-jar","build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar" -RedirectStandardOutput "app.log" -RedirectStandardError "app.log"

# Java 경로를 직접 지정하는 방법
Start-Process -NoNewWindow -FilePath "C:\Program Files\Java\jdk-17\bin\java.exe" -ArgumentList "-Dspring.profiles.active=prd","-jar","build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar" -RedirectStandardOutput "app.log" -RedirectStandardError "app.log"

# 콘솔 출력을 남기지 않을 때 (NUL로 리다이렉트)
Start-Process -NoNewWindow -FilePath "java" -ArgumentList "-Dspring.profiles.active=prd","-jar","build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar" -RedirectStandardOutput "NUL" -RedirectStandardError "NUL"
```

**CMD - javaw 사용 (콘솔 창 없이 실행)**
```cmd
# 개발 환경
start /B javaw -Dspring.profiles.active=dev -jar build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar

# 운영 환경
start /B javaw -Dspring.profiles.active=prd -jar build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar

# Java 경로를 직접 지정 (경로에 공백이 있을 경우 빈 창제목 "" 필요)
start "" /B "C:\Program Files\Java\jdk-17\bin\javaw.exe" -Dspring.profiles.active=prd -jar build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar

# 또는 절대 경로 사용
start "" /B "D:\DEV\.jdks\azul-17.0.14\bin\javaw.exe" -Dspring.profiles.active=prd -jar D:\workspace\git\VMIS-interface\build\libs\VMIS-interface-0.0.1-SNAPSHOT.jar


cd /d d:
D:\VMIS-interface\azul-17.0.14\bin

java -Dspring.profiles.active=prd -jar D:\VMIS-interface\VMIS-interface-0.0.1-SNAPSHOT.jar

"D:\VMIS-interface\azul-17.0.14\bin\javaw.exe" -Dspring.profiles.active=prd -jar D:\VMIS-interface\VMIS-interface-0.0.1-SNAPSHOT.jar

start "" /B "D:\VMIS-interface\azul-17.0.14\bin\javaw.exe" -Dspring.profiles.active=prd -jar D:\VMIS-interface\VMIS-interface-0.0.1-SNAPSHOT.jar
```

**참고:** `start` 명령어는 첫 번째 따옴표 문자열을 창 제목으로 인식하므로, 경로를 따옴표로 묶을 때는 앞에 빈 창제목 `""`을 추가해야 합니다.

**프로세스 관리**
```powershell
# 프로세스 확인
Get-Process | Where-Object {$_.ProcessName -like "*java*"} | Select-Object Id, ProcessName, Path

# 또는 특정 포트로 확인
netstat -ano | findstr :18080

# 프로세스 종료 (PID로)
Stop-Process -Id <PID> -Force

# 또는 taskkill 사용
taskkill /F /PID <PID>
```

**Java 경로 확인 (Windows)**
```powershell
# PowerShell
where.exe java

# 또는
(Get-Command java).Source

# Java 버전 확인
java -version
```

**참고:** Windows 환경에서도 콘솔 출력을 `NUL`로 리다이렉트하면, 애플리케이션 자체 로그는 `d:/data/VMIS-interface/logs/vmis-interface.log`에 정상적으로 기록됩니다.

### 4) API 문서(Swagger UI)
- 개발 환경: `http://localhost:8081/swagger-ui/index.html`
- 운영 환경: `http://localhost:8080/swagger-ui/index.html`

---

## 사용 방법(엔드포인트)
- 기본 경로: `/api/v1/vehicles`

### 1) 자동차 기본사항 조회
- `POST /api/v1/vehicles/basic`
- 요청/응답은 `Envelope<BasicRequest|BasicResponse>` 구조(JSON)
- 컨트롤러: `VehicleInterfaceController#basic`

### 2) 자동차 등록원부(갑) 조회
- `POST /api/v1/vehicles/ledger`
- 요청/응답은 `Envelope<LedgerRequest|LedgerResponse>` 구조(JSON)
- 컨트롤러: `VehicleInterfaceController#ledger`

참고: 요청은 서비스 계층에서 `RequestEnricher`를 통해 공통 헤더/추적정보가 보강되며, 외부 시스템 호출은 `GovernmentApiClient`가 수행합니다.

---

## 실행 스크립트/명령(Gradle)
- 테스트 실행: `./gradlew test`
- 애플리케이션 실행(bootRun): `./gradlew bootRun --args='--spring.profiles.active=dev'`
- 의존성 갱신: `./gradlew --refresh-dependencies`

---

## DB/로깅
- 기본사항 조회 최초 요청/응답 로그 적재
  - 서비스: `CarBassMatterInqireService`
  - 매퍼: `CarBassMatterInqireMapper`, XML: `resources/mybatis/mapper/CarBassMatterInqireMapper_maria.xml`
  - DDL: `ddl/vips/tb_car_bass_matter_inqire.sql`, `ddl/vips/seq_car_bass_matter_inqire.sql`
- 로그 태그 예시
  - `[BASIC-REQ-LOG]` 최초 요청 저장 완료
  - `[BASIC-RES-LOG]` 응답 저장 완료
  - `[BASIC-ERR-LOG]` 외부 호출 오류 저장

---

## GPKI 연계
- 구현: `gpki/GpkiService.java`, `gpki/RealGpkiService.java`, `gpki/NoopGpkiService.java`
- 인증서/키 위치(예): `src/GPKI/certs/*`
- 운영에서는 `RealGpkiService` 사용 및 JNI 라이브러리 로딩 필요(`lib/libgpkiapi_jni_1.5.jar`)
- 유틸: `util/GpkiCryptoUtil.java`, `util/NewGpkiUtil.java`
- 주의사항
  - 운영 키/패스워드 노출 금지, 파일 권한/경로 점검
  - 네이티브 라이브러리 로딩 경로와 JCE 정책 확인

---

## 프로젝트 구조(요약)
```
VMIS-interface/
├─ build.gradle, settings.gradle
├─ gradlew, gradlew.bat, gradle/wrapper/*
├─ lib/libgpkiapi_jni_1.5.jar
├─ ddl/vips/*.sql
├─ src/
│  ├─ main/java/com/vmis/interfaceapp/
│  │  ├─ VmisInterfaceApplication.java
│  │  ├─ controller/VehicleInterfaceController.java
│  │  ├─ service/* (VehicleInterfaceService, RequestEnricher, CarBassMatterInqireService)
│  │  ├─ client/* (GovernmentApi, GovernmentApiClient)
│  │  ├─ gpki/* (GpkiService, RealGpkiService, NoopGpkiService)
│  │  ├─ mapper/* (CarBassMatterInqireMapper)
│  │  ├─ model/* (common/Envelope, basic/*, ledger/*)
│  │  ├─ config/* (DatabaseConfig, HttpClientConfig, OpenApiConfig, PropertiesConfig, ...)
│  │  └─ util/* (TxIdUtil, GpkiCryptoUtil, NewGpkiUtil)
│  ├─ main/resources/
│  │  ├─ application.yml, application-dev.yml, application-prd.yml
│  │  ├─ logback-spring.xml
│  │  └─ mybatis/*
│  └─ GPKI/certs/*
├─ 참고자료/* (규격서/원시 샘플)
└─ README.md
```

---

## 테스트
- JUnit 기반 테스트 의존성 포함
  - `testImplementation 'org.springframework.boot:spring-boot-starter-test'`
- 현재 저장소에 도메인별 테스트 코드가 별도로 포함되어 있지 않을 수 있습니다.
- 실행 방법: `./gradlew test`
- TODO: 통합 테스트(외부 API 목업), 서비스 단위 테스트, 매퍼 테스트 추가

---

## 환경 변수 및 보안
- 프로파일: `SPRING_PROFILES_ACTIVE`(`dev`/`prd`)
- DB/외부 API 키/패스워드는 환경변수나 보안 비밀 관리 도구로 주입하세요.
- 저장소/로그에 민감정보를 남기지 말 것(PII 마스킹 권장)

---

## 라이선스
- TODO: 라이선스 파일(`LICENSE`)을 추가하고 본 섹션을 갱신하세요.

---

## 변경 이력
- 2025-11-05: 초기 README 작성 및 최신 설정 반영

---

## 참고
- OpenAPI/Swagger UI는 `springdoc-openapi`를 사용합니다.
- 외부 API 사양은 `참고자료/인터페이스 정의서` 디렉토리의 문서를 참조하세요.