shared-dg05-coffeeQuokka/hgzero

Fork 0

mirror of https://github.com/hwanny1128/HGZero.git synced 2025-12-06 13:46:24 +00:00

djeon 16caafd7c8 notification 실행환경 설정

2025-10-24 09:38:26 +09:00

19 KiB

Raw Blame History

AI Service 백엔드 개발 결과서

1. 개요

1.1 서비스 정보

서비스명: AI Service
포트: 8083
역할: 회의록 AI 자동 작성 및 분석 서비스
아키텍처: Clean Architecture (Layered + UseCase 패턴)
언어/프레임워크: Java 21, Spring Boot 3.3.0

1.2 개발 범위

✅ Domain 엔티티 및 DTO 구현 (35개 파일)
✅ Repository 계층 구현 (1 Entity + 1 Repository)
✅ Service 계층 구현 (7 UseCase + 7 Service + 3 Gateway + 3 Gateway 구현체)
✅ Controller 계층 구현 (8개 REST API)
✅ Security 구현 (SecurityConfig, JWT 인증 처리)
✅ Swagger 설정 구현 (OpenAPI 문서화)
✅ 설정 파일 작성 (application.yml, 메인 클래스)
✅ 빌드 성공 (./gradlew ai:build)

2. 아키텍처 구조

2.1 Clean Architecture 계층

ai/
├── biz/                          # 비즈니스 계층
│   ├── domain/                   # Domain 모델 (5개)
│   │   ├── ProcessedTranscript.java
│   │   ├── ExtractedTodo.java
│   │   ├── RelatedMinutes.java
│   │   ├── Term.java
│   │   └── Suggestion.java
│   ├── usecase/                  # UseCase 인터페이스 (7개)
│   │   ├── TranscriptProcessUseCase.java
│   │   ├── TodoExtractionUseCase.java
│   │   ├── SectionSummaryUseCase.java
│   │   ├── RelatedTranscriptSearchUseCase.java
│   │   ├── TermDetectionUseCase.java
│   │   ├── TermExplanationUseCase.java
│   │   └── SuggestionUseCase.java
│   ├── service/                  # Service 구현체 (7개)
│   │   ├── TranscriptProcessService.java
│   │   ├── TodoExtractionService.java
│   │   ├── SectionSummaryService.java
│   │   ├── RelatedTranscriptSearchService.java
│   │   ├── TermDetectionService.java
│   │   ├── TermExplanationService.java
│   │   └── SuggestionService.java
│   └── gateway/                  # Gateway 인터페이스 (3개)
│       ├── LlmGateway.java
│       ├── SearchGateway.java
│       └── TranscriptGateway.java
└── infra/                        # 인프라 계층
    ├── controller/               # REST Controllers (7개 클래스, 8개 API)
    │   ├── TranscriptController.java
    │   ├── TodoController.java
    │   ├── SectionController.java
    │   ├── RelationController.java
    │   ├── TermController.java
    │   ├── ExplanationController.java
    │   └── SuggestionController.java
    ├── dto/                      # DTO (30개)
    │   ├── request/              # Request DTOs (6개)
    │   ├── response/             # Response DTOs (8개)
    │   └── common/               # Common DTOs (16개)
    ├── gateway/                  # Gateway 구현체 (4개)
    │   ├── entity/               # JPA Entity (1개)
    │   │   └── ProcessedTranscriptEntity.java
    │   ├── repository/           # JPA Repository (1개)
    │   │   └── ProcessedTranscriptJpaRepository.java
    │   └── TranscriptGatewayImpl.java
    ├── llm/                      # LLM 클라이언트 (1개)
    │   └── OpenAiLlmGateway.java
    └── search/                   # RAG 검색 클라이언트 (1개)
        └── AzureAiSearchGateway.java

2.2 패키지 구조 특징

biz/domain: 순수 비즈니스 Domain 객체 (외부 의존성 없음)
biz/usecase: 비즈니스 유스케이스 인터페이스 정의
biz/service: UseCase 인터페이스 구현체
biz/gateway: 외부 시스템 연동 추상화
infra/: 모든 외부 의존성 (Controller, DTO, Gateway 구현, 외부 API 클라이언트)

3. 구현 상세

3.1 Domain 모델 (5개)

Domain	설명	주요 필드
ProcessedTranscript	처리된 회의록	transcriptId, meetingId, summary, discussions, decisions, pendingItems
ExtractedTodo	추출된 Todo	content, assignee, dueDate, priority, sectionReference
RelatedMinutes	관련 회의록	transcriptId, title, date, participants, relevanceScore, commonKeywords
Term	전문용어	term, position, confidence, category, highlight
Suggestion	AI 제안사항	id, type (DISCUSSION/DECISION), content, priority, reason, confidence

3.2 UseCase 및 Service (7개)

3.2.1 TranscriptProcessService ⭐️

역할: 회의록 자동 작성 (핵심 기능)

주요 메서드:

processTranscript(): STT 텍스트 → LLM 회의록 생성 → DB 저장 → RAG 인덱싱
getTranscript(): 회의록 ID로 조회
getTranscriptByMeetingId(): 회의 ID로 조회

구현 로직:

LLM Gateway를 통한 회의록 생성 (OpenAI GPT-4)
JSON 응답 파싱 및 Domain 객체 변환
Transaction 내에서 DB 저장
Azure AI Search 인덱싱 (비동기 처리 고려)

3.2.2 TodoExtractionService

역할: 회의록에서 Todo 자동 추출

주요 메서드:

extractTodos(): 회의록 내용 → LLM Todo 추출 → Todo 목록 반환

3.2.3 SectionSummaryService

역할: 섹션 AI 요약 재생성

주요 메서드:

regenerateSummary(): 섹션 내용 → LLM 요약 생성 (2-3문장)

3.2.4 RelatedTranscriptSearchService

역할: RAG 기반 관련 회의록 검색

주요 메서드:

findRelatedTranscripts(): 벡터 유사도 검색 → 관련 회의록 반환

3.2.5 TermDetectionService

역할: 전문용어 자동 감지

주요 메서드:

detectTerms(): 텍스트 분석 → 전문용어 목록 반환

3.2.6 TermExplanationService

역할: RAG 기반 용어 설명 생성

주요 메서드:

explainTerm(): 용어 + 맥락 → RAG 검색 → 상세 설명 반환

3.2.7 SuggestionService

역할: 논의사항/결정사항 실시간 제안

주요 메서드:

suggestDiscussions(): 현재 회의록 → 추가 논의 주제 제안
suggestDecisions(): 현재 회의록 → 결정사항 패턴 감지 및 제안

3.3 Gateway 구현 (3개)

3.3.1 TranscriptGatewayImpl

역할: 회의록 데이터 영속성 관리

구현: ProcessedTranscriptJpaRepository 래핑

주요 메서드: save, findById, findByMeetingId, findByMeetingIds, findByStatus, existsByMeetingId, delete

3.3.2 OpenAiLlmGateway

역할: OpenAI API 연동

구현 상태: 스켈레톤 (Mock 응답 반환)

TODO: 실제 OpenAI API 호출 로직 구현 필요

주요 메서드: generateTranscript, extractTodos, generateSummary, detectTerms, suggestDiscussions, suggestDecisions

3.3.3 AzureAiSearchGateway

역할: Azure AI Search RAG 연동

구현 상태: 스켈레톤 (Mock 응답 반환)

TODO: 실제 Azure AI Search API 호출 로직 구현 필요

주요 메서드: searchRelatedTranscripts, searchTermExplanation, indexTranscript

3.4 REST API (8개)

엔드포인트	Method	Controller	설명
`/api/transcripts/process`	POST	TranscriptController	회의록 자동 작성
`/api/todos/extract`	POST	TodoController	Todo 자동 추출
`/api/sections/{sectionId}/regenerate-summary`	POST	SectionController	섹션 요약 재생성
`/api/transcripts/{meetingId}/related`	GET	RelationController	관련 회의록 조회
`/api/terms/detect`	POST	TermController	전문용어 감지
`/api/terms/{term}/explain`	GET	ExplanationController	용어 설명
`/api/suggestions/discussion`	POST	SuggestionController	논의사항 제안
`/api/suggestions/decision`	POST	SuggestionController	결정사항 제안

3.5 Repository 및 Entity

ProcessedTranscriptEntity

테이블명: processed_transcripts

주요 컬럼:

transcript_id (PK, VARCHAR(50))
meeting_id (VARCHAR(50), NOT NULL)
summary (TEXT)
discussions (TEXT, JSON 형식)
decisions (TEXT, JSON 형식)
pending_items (TEXT, 콤마 구분)
status (VARCHAR(20), DEFAULT 'DRAFT')
created_at, updated_at (BaseTimeEntity 상속)

특징:

Jackson ObjectMapper를 사용한 JSON 직렬화/역직렬화
toDomain(), fromDomain() 메서드로 Entity ↔ Domain 변환
BaseTimeEntity 상속으로 생성일시/수정일시 자동 관리

ProcessedTranscriptJpaRepository

타입: JpaRepository<ProcessedTranscriptEntity, String>

Custom 쿼리:

findByMeetingId(String meetingId)
findByMeetingIdIn(List<String> meetingIds)
findByStatus(String status)
findByMeetingIdAndStatus(String meetingId, String status)
existsByMeetingId(String meetingId)

4. 설정 및 의존성

4.1 application.yml 주요 설정

# Server
server.port: 8083

# Database
spring.datasource.url: jdbc:postgresql://20.249.153.213:5432/aidb

# Redis
spring.data.redis.host: 20.249.177.114
spring.data.redis.database: 4

# OpenAI
azure.openai.deployment-name: gpt-4o
azure.openai.embedding-deployment: text-embedding-3-large
azure.openai.max-tokens: 2000
azure.openai.temperature: 0.3

# Azure AI Search
external.ai-search.index-name: meeting-transcripts

# Event Hub (Kafka 대체)
external.eventhub.eventhub-name: hgzero-eventhub-name
external.eventhub.consumer-group.transcript: ai-transcript-group

4.2 주요 의존성 (build.gradle)

dependencies {
    // Common 모듈
    implementation project(':common')

    // Spring Boot
    implementation 'org.springframework.boot:spring-boot-starter-web'
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-data-redis'
    implementation 'org.springframework.boot:spring-boot-starter-validation'

    // Database
    runtimeOnly 'org.postgresql:postgresql'

    // OpenAI
    implementation 'com.azure:azure-ai-openai:1.0.0-beta.6'

    // Azure AI Search
    implementation 'com.azure:azure-search-documents:11.5.0'

    // Jackson
    implementation 'com.fasterxml.jackson.core:jackson-databind'

    // Lombok
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

    // Swagger
    implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.2.0'
}

5. 개발 현황 및 TODO

5.1 완료된 작업 ✅

✅ 패키지 구조 설계 및 문서화
✅ Domain 엔티티 5개 구현
✅ DTO 35개 구현 (Request 6개 + Response 8개 + Common 16개 + Error 1개)
✅ Repository 계층 구현 (Entity 1개 + Repository 1개)
✅ UseCase 인터페이스 7개 정의
✅ Service 구현체 7개 작성
✅ Gateway 인터페이스 3개 정의
✅ Gateway 구현체 3개 작성 (TranscriptGateway 완성, LLM/Search 스켈레톤)
✅ Controller 7개 클래스 구현 (8개 REST API)
✅ 메인 클래스 작성 (AiServiceApplication.java)
✅ 설정 파일 완성 (application.yml)

5.2 미완성 작업 (TODO)

5.2.1 OpenAI LLM 연동 🔧

파일: ai/infra/llm/OpenAiLlmGateway.java

현재 상태: Mock 응답 반환

필요 작업:

OpenAI API 클라이언트 주입 설정
각 기능별 프롬프트 엔지니어링:
- 회의록 자동 작성 프롬프트
- Todo 추출 프롬프트
- 섹션 요약 프롬프트
- 전문용어 감지 프롬프트
- 논의사항 제안 프롬프트
- 결정사항 제안 프롬프트
GPT-4 API 호출 및 응답 처리
에러 핸들링 및 재시도 로직

5.2.2 Azure AI Search RAG 연동 🔧

파일: ai/infra/search/AzureAiSearchGateway.java

현재 상태: Mock 응답 반환

필요 작업:

Azure AI Search 클라이언트 설정
벡터 임베딩 생성 (text-embedding-3-large)
인덱스 스키마 정의 및 생성
벡터 검색 쿼리 구현
검색 결과 파싱 및 Domain 변환

5.2.3 MQ 이벤트 소비 🔧

필요 작업:

Meeting Service로부터 회의 종료 이벤트 수신
회의록 자동 생성 트리거
Todo 추출 후 Meeting Service로 발행
Event Hub (Kafka) Consumer 구현

5.2.4 SecurityConfig 및 JWT ✅ 완료

구현 완료:

✅ JWT 검증 필터 구현 (JwtAuthenticationFilter)
✅ JWT 토큰 제공자 구현 (JwtTokenProvider)
✅ 사용자 Principal 구현 (UserPrincipal)
✅ SecurityConfig 작성 (인증/인가 규칙)
✅ CORS 설정 적용
✅ SwaggerConfig 작성 (OpenAPI 문서화)

5.2.5 Service 로직 완성 🔧

현재 상태: 스켈레톤 구현 (Mock 데이터 반환)

필요 작업:

TodoExtractionService: LLM JSON 파싱 로직 구현
RelatedTranscriptSearchService: RAG JSON 파싱 로직 구현
TermDetectionService: LLM JSON 파싱 로직 구현
TermExplanationService: RAG JSON 파싱 로직 구현
SuggestionService: LLM JSON 파싱 로직 구현

6. 빌드 및 실행

6.1 로컬 빌드

cd /Users/daewoong/home/workspace/HGZero/ai
./gradlew clean build

6.2 실행

java -jar build/libs/ai-0.0.1-SNAPSHOT.jar

6.3 환경 변수 설정

export DB_HOST=20.249.153.213
export DB_PORT=5432
export DB_NAME=aidb
export DB_USERNAME=hgzerouser
export DB_PASSWORD=Hi5Jessica!

export REDIS_HOST=20.249.177.114
export REDIS_PORT=6379
export REDIS_PASSWORD=Hi5Jessica!

export AZURE_OPENAI_API_KEY=your-openai-key
export AZURE_OPENAI_ENDPOINT=your-openai-endpoint

export AZURE_AI_SEARCH_ENDPOINT=your-search-endpoint
export AZURE_AI_SEARCH_API_KEY=your-search-key

6.4 Swagger UI

URL: http://localhost:8083/swagger-ui.html
API Docs: http://localhost:8083/v3/api-docs

6.5 Security 및 Swagger 상세 구현

6.5.1 JWT 인증 처리 (Common 모듈)

파일 위치: common/src/main/java/com/unicorn/hgzero/common/security/

JwtTokenProvider (JwtTokenProvider.java)

JWT 토큰 검증 및 파싱
사용자 ID, 사용자명, 권한 정보 추출
토큰 만료 시간 확인
HMAC-SHA256 알고리즘 사용

JwtAuthenticationFilter (filter/JwtAuthenticationFilter.java)

HTTP 요청에서 JWT 토큰 추출 (Authorization: Bearer {token})
토큰 유효성 검증 후 SecurityContext에 인증 정보 설정
Actuator, Swagger 경로는 인증 제외 처리

UserPrincipal (UserPrincipal.java)

인증된 사용자 정보 담는 Principal 객체
userId, username, authority 정보 보유
관리자/사용자 권한 확인 메서드 제공

6.5.2 Security 설정 (AI 서비스)

파일 위치: ai/src/main/java/com/unicorn/hgzero/ai/infra/config/SecurityConfig.java

주요 기능:

CSRF 비활성화 (Stateless API)
CORS 설정 (환경변수 기반)
Stateless 세션 관리
JWT 필터 적용 (UsernamePasswordAuthenticationFilter 이전)
인증 제외 경로: /actuator/**, /swagger-ui/**, /v3/api-docs/**, /health
기타 모든 요청: 인증 필수

6.5.3 Swagger 설정 (AI 서비스)

파일 위치: ai/src/main/java/com/unicorn/hgzero/ai/infra/config/SwaggerConfig.java

주요 기능:

OpenAPI 3.0 문서 생성
Bearer Authentication 보안 스킴 설정
서버 URL 설정 (로컬: http://localhost:8083)
커스텀 서버 URL 변수 지원 (protocol, host, port)
API 정보: 제목, 설명, 버전, 연락처

6.5.4 빌드 결과

$ ./gradlew ai:build

BUILD SUCCESSFUL in 2s
10 actionable tasks: 6 executed, 4 up-to-date

생성된 JAR 파일:

ai/build/libs/ai.jar (실행 가능한 JAR)

7. 테스트 시나리오

7.1 회의록 자동 작성 테스트

curl -X POST http://localhost:8083/api/transcripts/process \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user123" \
  -H "X-User-Name: 김철수" \
  -d '{
    "meetingId": "meeting-001",
    "transcriptText": "안녕하세요. 오늘 회의는 신규 프로젝트 킥오프 미팅입니다...",
    "context": {
      "title": "신규 프로젝트 킥오프",
      "participants": ["김철수", "이영희", "박민수"],
      "agenda": ["프로젝트 개요", "일정 논의", "역할 분담"]
    }
  }'

7.2 Todo 추출 테스트

curl -X POST http://localhost:8083/api/todos/extract \
  -H "Content-Type: application/json" \
  -H "X-User-Id: user123" \
  -d '{
    "meetingId": "meeting-001",
    "minutesContent": "## 결정사항\n1. API 설계서는 박민수님이 1월 30일까지 작성..."
  }'

8. 주요 특징 및 기술적 의사결정

8.1 Clean Architecture 적용

비즈니스 로직 독립성: biz 계층은 외부 의존성 없음
의존성 역전: UseCase 인터페이스를 통한 의존성 역전
테스트 용이성: Mock Gateway를 통한 단위 테스트 가능

8.2 JSON 데이터 저장 전략

복잡한 구조 (discussions, decisions): JSON TEXT 컬럼 저장
Jackson ObjectMapper: 직렬화/역직렬화 자동 처리
이점: 스키마 변경 유연성, 복잡한 조인 회피

8.3 Gateway 패턴

LlmGateway: OpenAI API 추상화
SearchGateway: Azure AI Search 추상화
TranscriptGateway: 데이터 영속성 추상화
이점: 외부 의존성 교체 용이, 테스트 Mock 작성 간편

8.4 스켈레톤 구현 전략

핵심 로직만 우선 구현: TranscriptProcessService 상세 구현
나머지 스켈레톤 작성: 인터페이스 정의 완료, Mock 데이터 반환
이점: 전체 구조 파악 가능, 점진적 구현 가능

9. 다음 단계 권장사항

9.1 우선순위 1 (즉시)

OpenAI API 연동 완성: OpenAiLlmGateway 실제 API 호출 구현
Service JSON 파싱: Mock 데이터 대신 실제 LLM/RAG 응답 파싱
컴파일 테스트: Gradle 빌드 및 에러 수정 ✅ 완료

9.2 우선순위 2 (단기)

Azure AI Search 연동: RAG 기능 구현
MQ Event Consumer: Meeting Service 연동
SecurityConfig: JWT 인증/인가 ✅ 완료

9.3 우선순위 3 (중기)

통합 테스트: API 엔드포인트 테스트
성능 최적화: LLM 호출 최적화, 캐싱
모니터링: 로깅, Actuator 메트릭

10. 결론

10.1 개발 성과

총 작성 파일 수: 약 86개 (Domain 5 + DTO 35 + Service/Gateway 23 + Controller 7 + Entity/Repository 2 + Security 4 + Config 2 + 기타)
API 엔드포인트: 8개 (모두 Swagger 문서화 완료)
코드 라인 수: 약 4,500 라인
아키텍처 준수: Clean Architecture 완전 적용
빌드 상태: ✅ 성공 (./gradlew ai:build)
Security: ✅ JWT 인증/인가 구현 완료

10.2 핵심 가치

확장 가능한 구조: Clean Architecture로 비즈니스 로직 독립성 확보
AI 연동 준비: LLM/RAG Gateway 추상화로 다양한 AI 엔진 교체 가능
테스트 용이성: Interface 기반 설계로 Mock 테스트 간편
표준화: OpenAPI 3.0 명세 완벽 준수

10.3 개발 시 주의사항

LLM 비용: OpenAI API 호출 비용 고려 필요 (캐싱 전략 필수)
RAG 인덱싱: 대용량 회의록 처리 시 비동기 인덱싱 필수
토큰 제한: GPT-4 토큰 제한 (8K/32K) 고려한 회의록 분할 전략
실시간 성능: LLM 응답 시간 3-10초 고려한 UX 설계

개발 완료일: 2025-10-24 개발자: AI Backend Team 버전: v1.0.0 (MVP)

19 KiB Raw Blame History Unescape Escape

AI Service 백엔드 개발 결과서

1. 개요

1.1 서비스 정보

1.2 개발 범위

2. 아키텍처 구조

2.1 Clean Architecture 계층

2.2 패키지 구조 특징

3. 구현 상세

3.1 Domain 모델 (5개)

3.2 UseCase 및 Service (7개)

3.2.1 TranscriptProcessService ⭐️

3.2.2 TodoExtractionService

3.2.3 SectionSummaryService

3.2.4 RelatedTranscriptSearchService

3.2.5 TermDetectionService

3.2.6 TermExplanationService

3.2.7 SuggestionService

3.3 Gateway 구현 (3개)

3.3.1 TranscriptGatewayImpl

3.3.2 OpenAiLlmGateway

3.3.3 AzureAiSearchGateway

3.4 REST API (8개)

3.5 Repository 및 Entity

ProcessedTranscriptEntity

ProcessedTranscriptJpaRepository

4. 설정 및 의존성

4.1 application.yml 주요 설정

4.2 주요 의존성 (build.gradle)

5. 개발 현황 및 TODO

5.1 완료된 작업 ✅

5.2 미완성 작업 (TODO)

5.2.1 OpenAI LLM 연동 🔧

5.2.2 Azure AI Search RAG 연동 🔧

5.2.3 MQ 이벤트 소비 🔧

5.2.4 SecurityConfig 및 JWT ✅ 완료

5.2.5 Service 로직 완성 🔧

6. 빌드 및 실행

6.1 로컬 빌드

6.2 실행

6.3 환경 변수 설정

6.4 Swagger UI

6.5 Security 및 Swagger 상세 구현

6.5.1 JWT 인증 처리 (Common 모듈)

6.5.2 Security 설정 (AI 서비스)

6.5.3 Swagger 설정 (AI 서비스)

6.5.4 빌드 결과

7. 테스트 시나리오

7.1 회의록 자동 작성 테스트

7.2 Todo 추출 테스트

8. 주요 특징 및 기술적 의사결정

8.1 Clean Architecture 적용

8.2 JSON 데이터 저장 전략

8.3 Gateway 패턴

8.4 스켈레톤 구현 전략

9. 다음 단계 권장사항

9.1 우선순위 1 (즉시)

9.2 우선순위 2 (단기)

9.3 우선순위 3 (중기)

10. 결론

10.1 개발 성과

10.2 핵심 가치

10.3 개발 시 주의사항

19 KiB

Raw Blame History