📊 Java-Service-Tree-Framework-AI 프로젝트 분석 리포트
1. 프로젝트 개요
   1.1 기본 정보

프로젝트명: Java-Service-Tree-Framework-AI
그룹 ID: 313devgrp
버전: 25.11.x (자동 증가)
Java 버전: Java 21
Spring Boot: 3.4.4
빌드 도구: Gradle 8.13

1.2 프로젝트 목적
Spring AI 프레임워크 기반의 AI 통합 서비스로, RAG(Retrieval-Augmented Generation) 패턴을 활용한 문서 기반 Q&A 시스템입니다.

2. 기술 스택
   2.1 핵심 프레임워크
- Spring Boot 3.4.4 (WebFlux - 반응형)
- Spring AI 1.0.0-M6/M8
- Spring Cloud Config
- Spring Actuator
  2.2 AI/ML 라이브러리
  ✅ Spring AI Ollama (로컬 LLM)
  ✅ Vector Store (OpenSearch)
  ✅ Document Readers:
    - PDF (Apache PDFBox 기반)
    - Tika (다양한 문서 형식)
    - Markdown
      ✅ RAG Advisors (검색 증강 생성)
      2.3 인프라
- Docker (컨테이너화)
- Nexus (Maven Repository)
- Config Server (중앙 설정 관리)

3. 아키텍처 분석
   3.1 계층 구조
   ┌─────────────────────────────────────┐
   │      API Layer (REST)               │
   │   - SampleController                │
   └──────────────┬──────────────────────┘
   │
   ┌──────────────▼──────────────────────┐
   │      Service Layer                  │
   │   - MyPagePdfDocumentReader         │
   └──────────────┬──────────────────────┘
   │
   ┌──────────────▼──────────────────────┐
   │      AI Integration Layer           │
   │   - ChatModel (Ollama)              │
   │   - VectorStore (OpenSearch)        │
   │   - Advisors (Logging, SafeGuard)   │
   └─────────────────────────────────────┘
   3.2 주요 컴포넌트
   3.2.1 SampleController
   java역할: AI 채팅 및 문서 처리 API 제공
   주요 엔드포인트:
- GET /ai/generateStream : 스트리밍 채팅
- GET /ai/test : 벡터 유사도 검색
- GET /ai/my-page-pdf-document-reader : PDF 문서 로드
- GET /ai/stopStream : 스트림 중단
  3.2.2 MyPagePdfDocumentReader
  java역할: 다양한 문서 형식을 읽어 Vector Store에 저장
  지원 형식:
  ✅ PDF (Tika, PagePdf, ParagraphPdf)
  ✅ Markdown
  처리 흐름:
1. 문서 읽기 (DocumentReader)
2. 토큰 분할 (TokenTextSplitter)
3. 벡터 저장 (VectorStore.write)
   3.2.3 SimpleLogAdvisor
   java역할: 요청/응답 로깅
   기능:
- before(): 요청 전 로깅
- after(): 응답 후 로깅
- Order: 0 (최우선 실행)
  3.2.4 SafeGuardAdvisor ⭐
  java역할: 강력한 보안 필터링 시스템
  주요 기능:
1. 프롬프트 인젝션 방어
2. SQL Injection / XSS 탐지
3. 민감 정보 마스킹 (이메일, 전화번호, 주민번호 등)
4. 실시간 스트림 필터링
5. 심각도별 처리 (CRITICAL/HIGH/MEDIUM/LOW)

검증 항목:
- 프롬프트 인젝션
- 역할 조작 (Role Manipulation)
- SQL Injection
- XSS (Cross-Site Scripting)
- 경로 탐색 (Path Traversal)
- 명령어 삽입 (Command Injection)
- JWT 토큰/신용카드/주민번호 노출
```

---

## 4. RAG 구현 분석

### 4.1 RAG 파이프라인
```
┌──────────────┐
│ 1. 문서 로드  │  ← PDF/Markdown 읽기
└──────┬───────┘
│
┌──────▼───────┐
│ 2. 청킹       │  ← TokenTextSplitter
└──────┬───────┘
│
┌──────▼───────┐
│ 3. 임베딩     │  ← Vector Store 저장
└──────┬───────┘
│
┌──────▼───────┐
│ 4. 검색       │  ← 유사도 검색 (threshold: 0.5)
└──────┬───────┘
│
┌──────▼───────┐
│ 5. 증강       │  ← Context + Query 결합
└──────┬───────┘
│
┌──────▼───────┐
│ 6. 생성       │  ← LLM 응답 생성
└──────────────┘
```

### 4.2 프롬프트 템플릿
```
Context information is below.
---------------------
{context}
---------------------

Given the context information and no prior knowledge, answer the query.

Rules:
- 주어진 정보를 바탕으로 답변
- 그림/표 제외
- 문장 끝 개행
- 답변 없으면 한국어로 "답변할 수 없습니다" 응답

Query: {query}
Answer:

5. 배포 구조
   5.1 Docker 이미지 빌드
   gradle이미지명: 313.co.kr:5550/313devgrp/java-service-tree-framework-ai:25.11.x
   베이스 이미지: eclipse-temurin:21-jdk-jammy

빌드 프로세스:
1. bootJar 생성
2. Docker 컨텍스트 준비 (jar + entrypoint)
3. Docker 이미지 빌드
4. Private Registry 푸시 (313.co.kr:5550)
   5.2 버전 관리
   gradle자동 버전 증가:
- majorVersion: 25 (수동)
- minorVersion: 11 (수동)
- patchVersion: Nexus에서 자동 계산 (latest + 1)

예시: 25.11.0 → 25.11.1 → 25.11.2
```

---

## 6. 보안 분석 (SafeGuardAdvisor)

### 6.1 보안 등급

| 등급 | 설명 | 처리 |
|------|------|------|
| **CRITICAL** | 프롬프트 인젝션, 명령어 삽입 | 전체 차단 |
| **HIGH** | SQL Injection, XSS | 부분 필터링 |
| **MEDIUM** | SQL 주석, 의심 키워드 | 부분 필터링 |
| **LOW** | 경미한 위반 | 경고만 |

### 6.2 보호 기능
```
✅ 요청 검증 (before)
- 프롬프트 인젝션 차단
- SQL Injection 탐지
- XSS 패턴 필터링

✅ 응답 필터링 (after)
- 민감 정보 마스킹
- 안전성 점수 계산

✅ 스트림 보안 (aroundStream)
- 실시간 청크 검증
- 위험 청크 [BLOCKED]
  6.3 통계 수집
  javaSafeGuardStats {
  총요청: 1000
  차단: 50
  필터링: 30
  차단율: 5.0%
  위반통계: {PROMPT_INJECTION: 20, XSS: 15, ...}
  }

7. API 명세
   7.1 스트리밍 채팅
   httpGET /ai/generateStream?message={질문}&streamId={ID}

Parameters:
- message: 사용자 질문
- streamId: 스트림 식별자

Response: text/event-stream
- 실시간 텍스트 스트림
- SafeGuard 필터링 적용
- 중단 가능 (stopStream API)
  7.2 문서 로드
  httpGET /ai/my-page-pdf-document-reader

Response: List<Document>
- PDF 문서를 읽어 Vector Store에 저장
- PMBOK 4th Edition (한글판) 예시
  7.3 벡터 검색
  httpGET /ai/test?message={검색어}

Response: List<Document>
- 유사도 기반 문서 검색
- OpenSearch Vector Store 활용

8. 설정 관리
   8.1 Config Server 연동
   yamlspring:
   cloud:
   config:
   uri: http://www.313.co.kr:33133  # Config Server
   watch:
   enabled: true
   initialDelay: 5000
   delay: 5000
```

### 8.2 프로파일
```
- application.yml (기본)
- application-dev.yml (개발)
- application-stg.yml (스테이징)
- application-live.yml (운영)
```

---

## 9. 강점 및 특징

### ✅ 강점

1. **강력한 보안**: SafeGuardAdvisor의 다층 보안 필터링
2. **RAG 구현**: 문서 기반 정확한 답변 생성
3. **반응형 아키텍처**: WebFlux 기반 비동기 처리
4. **스트리밍 지원**: 실시간 응답 스트리밍
5. **다양한 문서 형식**: PDF, Markdown, Tika
6. **자동화된 배포**: Docker + Nexus + 자동 버전 관리

### 📌 특징

1. **Advisor 패턴**: 로깅, 보안, RAG를 Advisor로 모듈화
2. **민감정보 보호**: 자동 마스킹 (이메일, 전화, 카드번호 등)
3. **유연한 설정**: Config Server 기반 중앙 관리
4. **통계 수집**: 보안 위협 통계 실시간 추적

---

## 10. 개선 제안

### 🔧 기술적 개선

1. **테스트 코드 부재**
```
추천: Spring AI Test, WebTestClient 기반 통합 테스트
```

2. **README 문서 없음**
```
추천: 설치/실행/API 가이드 작성
```

3. **에러 핸들링**
```
추천: @ControllerAdvice 기반 글로벌 예외 처리
```

4. **모니터링**
```
추천: Prometheus + Grafana 메트릭 수집
```

### 📚 기능적 개선

1. **다국어 지원**
```
현재: 한국어 프롬프트 고정
개선: 다국어 템플릿 지원
```

2. **벡터 DB 선택**
```
현재: OpenSearch 고정
개선: Chroma, Pinecone 등 선택 가능
```

3. **문서 업데이트**
```
현재: 수동 로드
개선: 자동 동기화 스케줄러

11. 결론
    종합 평가
    이 프로젝트는 Spring AI 기반의 엔터프라이즈급 RAG 시스템으로, 특히 SafeGuardAdvisor의 보안 기능이 매우 인상적입니다.
    핵심 가치:

✅ 프로덕션 레벨의 보안 필터링
✅ 문서 기반 정확한 AI 응답
✅ 스트리밍 + 반응형 아키텍처
✅ 모듈화된 Advisor 패턴

적합한 사용 사례:

사내 문서 Q&A 시스템
고객 지원 챗봇 (RAG 기반)
규제가 있는 산업의 AI 서비스 (금융, 의료 등)

다음 단계 권장:

테스트 코드 작성 (커버리지 80% 이상)
API 문서화 (Swagger/OpenAPI)
모니터링 대시보드 구축
성능 벤치마크 (응답 시간, 처리량)