마비노기 경매장 거래 내역 조회 및 통계 서비스

마비노기 경매장 거래 내역을 수집하고 분석하여 사용자에게 시세 정보를 제공하는 마이크로서비스입니다.

주요 기능

경매장 거래 내역 수집

매 1시간마다 마비노기 경매장 거래 내역을 Nexon Open API를 통해 수집
약 70개의 아이템 카테고리에 대한 커서 기반 페이지네이션으로 데이터 수집
카테고리별 요청 간 딜레이 설정으로 API Rate Limit 준수

실시간 경매장 데이터 수집

10분 간격으로 현재 판매 중인 아이템 정보 수집
만료된 아이템 자동 삭제
거래 내역과 분리된 별도 테이블로 관리

뿔피리 데이터 수집

5분마다 거대한 외침의 뿔피리 내역 수집
4개 서버 지원 (류트, 만돌린, 하프, 울프)
지수 백오프 기반 재시도 로직 구현
Elasticsearch 연동: 한글 전문 검색 지원 (Ngram Parser)

통계 분석

일간 통계: 경매 데이터 수집 완료 시 자동 트리거 (이벤트 기반)
주간 통계: 매주 월요일 04:00에 집계
전일 통계: 매일 00:10에 전일 통계 확정

데이터 조회

아이템별 최저가, 최고가, 평균가, 거래량 등 시세 조회
서버별/전체 뿔피리 내역 조회
아이템 옵션 필터링 (무기 공격력, 방어구 방어력, 세공 옵션 등)

기술 스택

분류	기술
Backend	Java 21, Spring Boot 3.5.0, Spring Data JPA, QueryDSL
HTTP Client	Spring WebFlux (WebClient)
Database	MySQL 8, Flyway
Search Engine	Elasticsearch (한글 전문 검색)
Security	Spring Security, JWT
Test	JUnit5, Mockito, AssertJ, Testcontainers
Code Quality	Spotless (Google Java Format AOSP), Jacoco
Documentation	Swagger (Springdoc OpenAPI), Spring REST Docs
DevOps	Docker Compose, GitHub Actions
Deployment	Oracle Cloud

프로젝트 구조

src/main/java/until/the/eternity/
├── auctionhistory/          # 경매장 거래 내역 수집 및 검색
├── auctionrealtime/         # 실시간 경매장 데이터 수집 (10분 간격)
├── auctionitem/             # 경매장 아이템 엔티티
├── auctionitemoption/       # 아이템 옵션 정보 (세공 옵션 포함)
├── hornBugle/               # 뿔피리 내역 수집 및 검색 (Elasticsearch 연동)
├── statistics/              # 일간/주간 통계 집계
├── iteminfo/                # 아이템 메타데이터
├── itemoptioninfo/          # 아이템 옵션 정보
├── metalwareinfo/           # 금속류 아이템 정보
├── auctionsearchoption/     # 검색 옵션 메타데이터
├── common/                  # 공통 유틸리티, 예외, 필터
└── config/                  # 설정 (Security, QueryDSL, Web, OpenAPI)

아키텍처 (Clean Architecture)

interfaces/       # Controller, DTO, External API Client
  └── rest/       # REST API 엔드포인트
  └── external/   # 외부 API 연동 (Nexon Open API)
application/      # Service, Scheduler, Event
domain/           # Entity, Repository Port, Mapper
infrastructure/   # Repository 구현체, JPA

API 엔드포인트

경매장 거래 내역

Endpoint	Method	설명
`/auction-history/search`	GET	경매 내역 검색 (필터 및 페이징)
`/auction-history/{id}`	GET	단일 거래 내역 조회
`/auction-history/batch`	POST	배치 수동 실행

실시간 경매장

Endpoint	Method	설명
`/auction-realtime/search`	GET	현재 판매 중인 아이템 검색
`/auction-realtime/{id}`	GET	단일 아이템 조회

뿔피리

Endpoint	Method	설명
`/horn-bugle`	GET	뿔피리 내역 검색 (서버별/전체)
`/horn-bugle/batch`	POST	뿔피리 배치 수동 실행

통계

Endpoint	Method	설명
`/statistics/daily/items`	GET	일간 아이템 통계
`/statistics/daily/subcategories`	GET	일간 서브카테고리 통계
`/statistics/daily/top-categories`	GET	일간 상위카테고리 통계
`/statistics/weekly/items`	GET	주간 아이템 통계
`/statistics/weekly/subcategories`	GET	주간 서브카테고리 통계
`/statistics/weekly/top-categories`	GET	주간 상위카테고리 통계

메타데이터

Endpoint	Method	설명
`/api/item-infos`	GET	아이템 메타데이터
`/api/v1/item-option-infos`	GET	아이템 옵션 정보
`/api/auction-search-options`	GET	검색 옵션 메타데이터

시스템

Endpoint	Method	설명
`/actuator/health`	GET	헬스체크
`/swagger-ui/index.html`	-	API 문서

스케줄러

스케줄러	Cron 표현식	설명
경매 내역 수집	`0 0 * * * *`	매 시 정각
실시간 경매장 수집	`0 0/10 * * * *`	10분마다
뿔피리 수집	`0 /5 * * *`	5분마다
전일 통계 확정	`0 10 0 * * *`	매일 00:10
주간 통계 집계	`5 0 4 * * MON`	매주 월요일 04:00

환경 변수

필수 환경 변수

# 서버
SERVER_PORT=8080

# 데이터베이스
DB_IP=localhost
DB_PORT=3306
DB_SCHEMA=devnogi
DB_USER=username
DB_PASSWORD=password

# JWT
JWT_SECRET_KEY=your-secret-key
JWT_ACCESS_TOKEN_VALIDITY=3600000
JWT_REFRESH_TOKEN_VALIDITY=86400000

# Nexon Open API
NEXON_OPEN_API_KEY=your-api-key

# Elasticsearch
ELASTICSEARCH_URIS=http://localhost:9200
ELASTICSEARCH_USERNAME=
ELASTICSEARCH_PASSWORD=

선택 환경 변수

# 경매 내역 배치
AUCTION_HISTORY_CRON=0 0 * * * *
AUCTION_HISTORY_DELAY_MS=1000

# 실시간 경매장 배치
AUCTION_REALTIME_CRON=0 0/10 * * * *
AUCTION_REALTIME_DELAY_MS=500

# 뿔피리 배치
HORN_BUGLE_CRON=0 */5 * * * *
HORN_BUGLE_MAX_RETRIES=3
HORN_BUGLE_RETRY_DELAY_MS=2000

# Elasticsearch 기능
ELASTICSEARCH_ENABLED=true
ELASTICSEARCH_INDEX_ENABLED=true

# 통계
STATISTICS_PREVIOUS_DAY_CRON=0 10 0 * * *
STATISTICS_WEEKLY_CRON=5 0 4 * * MON

로컬 개발 환경 (Docker)

1. 환경 설정

# .env.local.sample을 복사하여 .env.local 생성
cp .env.local.sample .env.local

# .env.local 파일 수정
# - NEXON_OPEN_API_KEY: Nexon Open API 키
# - DB_PASSWORD: 로컬 MySQL 비밀번호

2. Docker로 실행

# 빌드 및 실행
docker-compose -f docker-compose-local.yml --env-file .env.local up --build

# 백그라운드 실행
docker-compose -f docker-compose-local.yml --env-file .env.local up -d --build

# 로그 확인
docker-compose -f docker-compose-local.yml logs -f spring-app

# 중지
docker-compose -f docker-compose-local.yml down

3. 환경별 Docker Compose 파일

환경	파일	설명
로컬 개발	`docker-compose-local.yml`	로컬 빌드, MySQL, Elasticsearch 포함
개발 서버	`docker-compose-dev.yml`	개발 환경 배포, Autoheal 컨테이너 포함
운영 서버	`docker-compose-prod.yml`	운영 환경 배포, 높은 리소스 할당

빌드 및 테스트

# 빌드
./gradlew clean build

# 테스트
./gradlew test

# 코드 포맷팅
./gradlew spotlessApply

# 테스트 커버리지 리포트
./gradlew jacocoTestReport

# REST Docs 생성
./gradlew asciidoctor

# 로컬 실행
./gradlew bootRun

데이터베이스 스키마

Flyway를 통한 마이그레이션 관리 (17개 버전)

주요 테이블

테이블	설명
`auction_history`	경매장 거래 내역
`auction_realtime_item`	현재 판매 중인 아이템
`auction_history_item_option`	거래 아이템 옵션 (세공 포함)
`auction_realtime_item_option`	실시간 아이템 옵션
`horn_bugle_world_history`	뿔피리 내역 (FULLTEXT 인덱스)
`item_daily_statistics`	일간 아이템 통계
`item_weekly_statistics`	주간 아이템 통계
`subcategory_daily_statistics`	일간 서브카테고리 통계
`subcategory_weekly_statistics`	주간 서브카테고리 통계
`top_category_daily_statistics`	일간 상위카테고리 통계
`top_category_weekly_statistics`	주간 상위카테고리 통계
`item_info`	아이템 메타데이터
`item_option_value_info`	아이템 옵션 정보
`metalware_info`	금속류 정보

API 응답 형식

{
  "success": true,
  "code": "string",
  "message": "string",
  "data": {},
  "timestamp": "2025-01-01T12:00:00Z"
}

개발자 문서

실행 방법: Notion - How to run
API 명세서: Notion - API 명세서
Git branch 전략: Git-flow (관련 블로그)

지원 아이템 카테고리

약 70개의 마비노기 아이템 카테고리 지원:

전투 장비: 한손/양손 무기, 검, 도끼, 둔기, 랜스 등
원거리 장비: 활, 석궁, 총, 수리검, 아틀라틀
마법 장비: 실린더, 스태프, 완드, 마법서, 오브
방어구: 중갑/경갑/천옷, 장갑, 신발, 모자, 방패, 로브
악세서리: 얼굴 장식, 날개, 꼬리, 일반 악세서리
특수 장비: 악기, 라이프 도구, 마리오네트, 에코스톤, 유물
소모품: 물약, 음식, 허브, 던전 통행증, 보석, 염료
강화 재료: 인챈트 스크롤, 마법 가루, 설계도, 악마 스크롤
서적: 책, 페이지, 마비노벨
구조물: 의자, 팜 아일랜드 아이템

Name		Name	Last commit message	Last commit date
Latest commit History 52 Commits
.claude		.claude
.github		.github
badges		badges
docs		docs
gradle/wrapper		gradle/wrapper
src		src
.dockerignore		.dockerignore
.env.local.sample		.env.local.sample
.env.prod.sample		.env.prod.sample
.gitignore		.gitignore
Dockerfile		Dockerfile
HELP.md		HELP.md
README.md		README.md
build.gradle.kts		build.gradle.kts
docker-compose-dev.yml		docker-compose-dev.yml
docker-compose-local.yml		docker-compose-local.yml
docker-compose-prod.yml		docker-compose-prod.yml
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts
setup-swap.sh		setup-swap.sh
setup.sh		setup.sh

devnogi/open-api-batch-server

Folders and files

Latest commit

History

Repository files navigation

마비노기 경매장 거래 내역 조회 및 통계 서비스

주요 기능

경매장 거래 내역 수집

실시간 경매장 데이터 수집

뿔피리 데이터 수집

통계 분석

데이터 조회

기술 스택

프로젝트 구조

아키텍처 (Clean Architecture)

API 엔드포인트

경매장 거래 내역

실시간 경매장

뿔피리

통계

메타데이터

시스템

스케줄러

환경 변수

필수 환경 변수

선택 환경 변수

로컬 개발 환경 (Docker)

1. 환경 설정

2. Docker로 실행

3. 환경별 Docker Compose 파일

빌드 및 테스트

데이터베이스 스키마

주요 테이블

API 응답 형식

개발자 문서

지원 아이템 카테고리

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 4

Uh oh!

Languages

Packages