2026-04-07 15:48:03 +09:00
--- 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          # 리스크·규정준수 스크리닝 데이터 조회
+```