From aa691e4dc12dd414cfb8512821aba7b049369529 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=B0=95=EC=84=B1=EC=98=81?= Date: Wed, 19 Nov 2025 18:42:06 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20MD=20=ED=8C=8C=EC=9D=BC=20=EC=9E=AC?= =?UTF-8?q?=EC=A0=95=EC=9D=98=20=ED=95=84=EC=9A=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- BUILD-RUN.md | 203 +++++++++++++++++++++++++++++ README.md | 355 +-------------------------------------------------- 2 files changed, 204 insertions(+), 354 deletions(-) create mode 100644 BUILD-RUN.md diff --git a/BUILD-RUN.md b/BUILD-RUN.md new file mode 100644 index 0000000..a192593 --- /dev/null +++ b/BUILD-RUN.md @@ -0,0 +1,203 @@ + +--- + +## 설치 및 실행 + +### 1) 소스 가져오기 +``` +git clone +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 +``` + +**참고:** `/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: +cd 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 -Force + +# 또는 taskkill 사용 +taskkill /F /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:18080/swagger-ui/index.html` + +--- + +## 실행 스크립트/명령(Gradle) +- 테스트 실행: `./gradlew test` +- 애플리케이션 실행(bootRun): `./gradlew bootRun --args='--spring.profiles.active=dev'` +- 의존성 갱신: `./gradlew --refresh-dependencies` +- +--- + +## 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 정책 확인 + +--- diff --git a/README.md b/README.md index 5717972..ec45afa 100644 --- a/README.md +++ b/README.md @@ -15,366 +15,13 @@ - `Envelope` 공통 래퍼 구조 사용 - 환경 프로파일 분리: `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 +- 언어: Java 1.8 - 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 -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 -``` - -**참고:** `/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: -cd 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 -Force - -# 또는 taskkill 사용 -taskkill /F /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` 구조(JSON) -- 컨트롤러: `VehicleInterfaceController#basic` - -### 2) 자동차 등록원부(갑) 조회 -- `POST /api/v1/vehicles/ledger` -- 요청/응답은 `Envelope` 구조(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 사양은 `참고자료/인터페이스 정의서` 디렉토리의 문서를 참조하세요.