diff --git a/README.md b/README.md index 5b31905..57ef0c5 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,18 @@ -# SNP-Batch (snp-batch-validation) +# SNP-Global (snp-global) -해양 데이터 통합 배치 시스템. Maritime API에서 선박/항만/사건 데이터를 수집하여 PostgreSQL에 저장하고, AIS 실시간 위치정보를 캐시 기반으로 서비스합니다. +S&P Global Maritime API Gateway 및 Risk & Compliance Screening 시스템. 외부 Maritime API를 인증 기반으로 프록시(Bypass)하고, 선박/회사의 리스크·규정준수 스크리닝 데이터를 서비스합니다. ## 기술 스택 -- Java 17, Spring Boot 3.2.1, Spring Batch 5.1.0 -- PostgreSQL, Quartz Scheduler, Caffeine Cache -- React 19 + Vite + Tailwind CSS 4 (관리 UI) -- frontend-maven-plugin (프론트엔드 빌드 통합) +- Java 17, Spring Boot 3.2.1 +- Spring Security (Basic Auth) +- PostgreSQL (스키마: std_snp_data) +- WebFlux WebClient (외부 Maritime API 호출) +- Spring Data JPA, JdbcTemplate +- Thymeleaf (이메일 템플릿) +- Springdoc OpenAPI 2.3.0 (Swagger) +- Lombok, Jackson +- React 19, TypeScript, Vite, Tailwind CSS (프론트엔드) ## 사전 요구사항 @@ -20,86 +25,112 @@ ## 빌드 -> **주의**: frontend-maven-plugin의 Node 호환성 문제로, 프론트엔드와 백엔드를 분리하여 빌드합니다. - -### 터미널 +> **참고**: frontend-maven-plugin이 Node.js 설치 및 프론트엔드 빌드를 자동으로 수행합니다. ```bash -# 1. 프론트엔드 빌드 -cd frontend && npm install && npm run build && cd .. +# JDK 설정 +sdk use java 17.0.18-amzn -# 2. Maven 패키징 (프론트엔드 빌드 스킵) -mvn clean package -DskipTests -Dskip.npm -Dskip.installnodenpm +# 전체 빌드 (프론트엔드 포함) +mvn clean package -DskipTests + +# 프론트엔드만 별도 빌드 +cd frontend && npm install && npm run build ``` -빌드 결과: `target/snp-batch-validation-1.0.0.jar` - -### VSCode - -`Cmd+Shift+B` (기본 빌드 태스크) → 프론트엔드 빌드 + Maven 패키징 순차 실행 - -개별 태스크: `Cmd+Shift+P` → "Tasks: Run Task" → 태스크 선택 - -> 태스크 설정: [.vscode/tasks.json](.vscode/tasks.json) - -### IntelliJ IDEA - -1. **프론트엔드 빌드**: Terminal 탭에서 `cd frontend && npm run build` -2. **Maven 패키징**: Maven 패널 → Lifecycle → `package` - - VM Options: `-DskipTests -Dskip.npm -Dskip.installnodenpm` - - 또는 Run Configuration → Maven → Command line에 `clean package -DskipTests -Dskip.npm -Dskip.installnodenpm` - ## 로컬 실행 -### 터미널 - ```bash -mvn spring-boot:run -Dspring-boot.run.profiles=local +# Spring Boot 실행 (기본 프로파일) +mvn spring-boot:run + +# 프론트엔드 개발 서버 +cd frontend && npm run dev ``` -### VSCode +## 서버 설정 -Run/Debug 패널(F5) → "SNP-Batch (local)" 선택 - -> 실행 설정: [.vscode/launch.json](.vscode/launch.json) - -### IntelliJ IDEA - -Run Configuration → Spring Boot: -- Main class: `com.snp.batch.SnpBatchApplication` -- Active profiles: `local` - -## 서버 배포 - -```bash -# 1. 빌드 (위 빌드 절차 수행) - -# 2. JAR 전송 -scp target/snp-batch-validation-1.0.0.jar {서버}:{경로}/ - -# 3. 실행 -java -jar snp-batch-validation-1.0.0.jar --spring.profiles.active=dev -``` +| 프로파일 | 포트 | Context Path | +|----------|------|--------------| +| default (로컬) | 8031 | /snp-global | +| dev / prod | 8041 | /snp-api | ## 접속 정보 | 항목 | URL | |------|-----| -| 관리 UI | `http://localhost:8041/snp-api/` | -| Swagger | `http://localhost:8041/snp-api/swagger-ui/index.html` | +| 관리 UI (로컬) | http://localhost:8031/snp-global/ | +| Swagger (로컬) | http://localhost:8031/snp-global/swagger-ui/index.html | -## 프로파일 +## 주요 API -| 프로파일 | 용도 | DB | -|----------|------|----| -| `local` | 로컬 개발 | 개발 DB | -| `dev` | 개발 서버 | 개발 DB | -| `prod` | 운영 서버 | 운영 DB | +### Bypass Account 관리 (`/api/bypass-account`) -## Maven 빌드 플래그 요약 +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | /accounts | 계정 목록 (페이징) | +| GET/PUT/DELETE | /accounts/{id} | 계정 상세/수정/삭제 | +| POST | /accounts/{id}/reset-password | 비밀번호 초기화 | +| POST | /requests | API 접근 요청 (공개) | +| GET | /requests | 요청 목록 | +| POST | /requests/{id}/approve | 승인 (계정 자동 생성) | +| POST | /requests/{id}/reject | 거부 | -| 플래그 | 용도 | -|--------|------| -| `-DskipTests` | 테스트 스킵 | -| `-Dskip.npm` | npm install/build 스킵 | -| `-Dskip.installnodenpm` | Node/npm 자동 설치 스킵 | +### Bypass Config 관리 (`/api/bypass-config`) + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET/POST | / | 설정 목록/생성 | +| GET/PUT/DELETE | /{id} | 설정 상세/수정/삭제 | +| POST | /{id}/generate | 서비스·컨트롤러 코드 생성 | + +### S&P API Bypass (`/api/compliance`, `/api/risk`) — Basic Auth 필요 + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | /compliance/CompliancesByImos | IMO별 규정준수 데이터 | +| GET | /risk/RisksByImos | IMO별 리스크 데이터 | +| GET | /risk/UpdatedComplianceList | 기간별 업데이트 목록 | + +### Screening Guide (`/api/screening-guide`) + +| 메서드 | 경로 | 설명 | +|--------|------|------| +| GET | /risk-indicators | 리스크 지표 (카테고리별) | +| GET | /compliance-indicators | 규정준수 지표 | +| GET | /methodology-history | 방법론 변경 이력 | +| GET | /history/ship-risk | 선박 리스크 변경 이력 | +| GET | /history/ship-compliance | 선박 규정준수 변경 이력 | +| GET | /history/company-compliance | 회사 규정준수 변경 이력 | +| GET | /ship-info, /company-info | 기본 정보 조회 | +| GET | /ship-risk-status | 선박 리스크 현황 | +| GET | /ship-compliance-status | 선박 규정준수 현황 | +| GET | /company-compliance-status | 회사 규정준수 현황 | + +## 디렉토리 구조 + +``` +src/main/java/com/snp/batch/ +├── SnpGlobalApplication.java # 메인 애플리케이션 +├── api/logging/ # API 접근 로깅 필터 +├── common/web/ # 공통 프레임워크 +│ ├── ApiResponse.java # 통합 API 응답 래퍼 +│ ├── controller/BaseBypassController # Bypass 컨트롤러 베이스 +│ └── service/BaseBypassService # Bypass 서비스 베이스 (WebClient) +├── global/ +│ ├── config/ # Security, Swagger, WebClient, Auth 설정 +│ ├── controller/ # Bypass 계정/설정 관리, Screening Guide, SPA 라우터 +│ ├── dto/ # bypass/, screening/ DTO +│ ├── model/ # bypass 엔티티, screening/ 다국어 엔티티 +│ └── repository/ # bypass, screening/ 리포지토리 +├── jobs/web/ # S&P API Bypass 엔드포인트 +│ ├── compliance/ # CompliancesByImos +│ └── risk/ # RisksByImos, UpdatedComplianceList +└── service/ # 핵심 비즈니스 서비스 + ├── BypassApiAccountService # 계정 CRUD + ├── BypassApiRequestService # 접근 요청 관리 (승인/거부) + ├── BypassCodeGenerator # 서비스/컨트롤러 코드 자동 생성 + ├── BypassConfigService # Bypass API 설정 CRUD + ├── EmailService # 이메일 발송 (승인/거부 알림) + └── ScreeningGuideService # 리스크·규정준수 스크리닝 데이터 조회 +``` diff --git a/docs/RELEASE-NOTES.md b/docs/RELEASE-NOTES.md new file mode 100644 index 0000000..d44b432 --- /dev/null +++ b/docs/RELEASE-NOTES.md @@ -0,0 +1,8 @@ +# Release Notes + +이 문서는 [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/) 형식을 따릅니다. + +## [Unreleased] + +### 문서 +- README.md를 snp-global 프로젝트에 맞게 재작성