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)

# Linux/Mac
./gradlew bootRun --args='--spring.profiles.active=dev'

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

운영 환경 (포트 8080)

# Linux/Mac
./gradlew bootRun --args='--spring.profiles.active=prd'

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

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

개발 환경

# 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

운영 환경 (환경변수 포함)

# 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 서버)

# 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 - 백그라운드 프로세스로 실행

# 개발 환경 (콘솔 출력을 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 사용 (콘솔 창 없이 실행)

# 개발 환경
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 명령어는 첫 번째 따옴표 문자열을 창 제목으로 인식하므로, 경로를 따옴표로 묶을 때는 앞에 빈 창제목 ""을 추가해야 합니다.

프로세스 관리

# 프로세스 확인
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
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 사양은 참고자료/인터페이스 정의서 디렉토리의 문서를 참조하세요.