Ban:D Main Server

Ban:D Main Server는 패널 데이터 분석 플랫폼의 핵심 백엔드 서비스입니다.

Preview

Members

LEAD/FE	FE	BE	BE/DATA	BE/AI
구혁모	김예나	이가은	조주한	천성진

Tech Stack

• Java 21 - 런타임
• Spring Boot 3.5.6 - 웹 프레임워크
• Spring Data JPA - ORM
• Spring WebFlux - AI 서버 연동 (WebClient)
• PostgreSQL 17 - 데이터베이스
• Caffeine - 인메모리 캐시
• AWS S3 - 이미지 저장소
• Docker - 컨테이너
• OpenAI API - AI 모델 (gpt-4o-mini, gpt-image-1-mini)

Getting Started

Installation

# 저장소 클론
git clone https://github.com/hansung-sw-capstone-2025-2/2025_8_I_BE.git
cd 2025_8_I_BE

# 빌드
./gradlew clean build

Environment Variables

# PostgreSQL
spring.datasource.url=${DATABASE_URL}
spring.datasource.username=${DATABASE_USERNAME}
spring.datasource.password=${DATABASE_PASSWORD}
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA(Hibernate)
spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.properties.hibernate.format_sql=true
spring.jpa.hibernate.ddl-auto=update

# FastAPI Server URL
fastapi.base-url=${FASTAPI_BASE_URL}

# OpenAI
openai.api.key=${OPENAI_API_KEY}
openai.api.text-url=https://api.openai.com/v1/chat/completions
openai.api.image-url= https://api.openai.com/v1/images/generations

#S3
cloud.aws.credentials.accessKey=AKIA4LCCSPBFCHFYV67I
cloud.aws.credentials.secretKey=${AWS_SECRET_KEY}
cloud.aws.region.static=ap-northeast-2
cloud.aws.s3.bucket=thx-30k
spring.cloud.aws.s3.enabled=false

Run

./gradlew bootRun

# 또는
java -jar build/libs/back-end-0.0.1-SNAPSHOT.jar

Docker

# 이미지 빌드
./gradlew clean build
docker build -t difflens-main .

# 컨테이너 실행
docker run -p 8080:8080 --env-file .env difflens-main

Project Structure

Thx-30K/BE/
├── src/main/java/com/api/thx30k/
│   ├── Thx30KApplication.java   # 엔트리포인트
│   ├── domain/
│   │   ├── demographic/         # 인구통계 정보
│   │   ├── query/               # 검색 쿼리 처리
│   │   ├── scenario/            # 시나리오 생성 (AI)
│   │   ├── search/              # 하이브리드 검색 (Vector + BM25 RRF)
│   │   ├── searchdocs/          # 검색 문서
│   │   └── searchmapping/       # 검색 매핑
│   └── global/
│       ├── S3/                  # AWS S3 연동
│       ├── config/              # 설정 파일
│       ├── constant/            # 상수 정의
│       ├── entity/              # 공통 엔티티
│       ├── exception/           # 예외 처리
│       ├── integration/         # 외부 시스템 연동 (FastAPI)
│       └── response/            # API 응답 포맷
├── src/main/resources/
│   └── application.properties
├── build.gradle
└── Dockerfile

Key Features

• 자연어 패널 검색: 자연어 질의를 통한 패널 검색 및 추출
• AI 시나리오 생성: 검색된 패널 데이터 기반 시나리오 및 리포트 자동 생성
• 인구통계 분석: 검색 결과의 인구통계학적 통계 및 소득 분포 분석
• AI 이미지 생성: 시나리오에 맞는 이미지 자동 생성 (비동기 처리)
• 패널 상세 정보: 개별 패널의 응답 데이터 및 AI 기반 한 줄 소개

System Architecture

AI Integration

• FastAPI 서버 연동: WebClient를 통한 비동기 통신
• 자연어 쿼리 분석: 사용자 질의를 인구통계 필터 및 검색 조건으로 변환
• 벡터 검색: 임베딩 기반 의미적 유사도 검색

Async Image Generation

사용자 경험 최적화를 위해 이미지 생성은 비동기로 처리됩니다.

• ThreadPoolTaskExecutor: 커스텀 스레드 풀 (Max Pool Size: 5)
• 즉시 응답: 검색 결과는 즉시 반환, 이미지는 백그라운드 생성
• Batch 조회: batchId를 통한 생성 완료 이미지 조회

API Endpoints

Query API (/querys)

• GET /querys?query={text} - 자연어 기반 패널 검색 및 통계 조회
• GET /querys/{panelId} - 개별 패널 상세 정보 조회
• GET /querys/images?batchId={id} - 생성된 이미지 결과 조회

Scenario API (/scenario)

• POST /scenario - AI 시나리오 및 리포트 생성 요청

License

이 프로젝트는 한성대학교 기업연계 SW캡스톤디자인 수업에서 진행되었습니다.