QMatch

게임 플레이어를 위한 실시간 매칭 및 커뮤니케이션 데스크톱 플랫폼

25년 유한대학교 졸업작품 프로젝트 | 팀 프로젝트 (4인) | 원본 팀 레포지토리 →

---

목차

• 소개
• 담당 파트
• 주요 기능
• 기술 스택
• 실행 화면
• 설치 및 실행
• 라이선스

---

소개

QMatch는 게임 플레이어들이 쉽게 팀원을 찾고, 실시간으로 소통할 수 있는 데스크톱 애플리케이션입니다.
다양한 게임 카테고리별 채팅방 생성, 음성 채팅, 실제 게임 전적 연동까지 지원합니다.

---

담당 파트

역할	담당 내용
Neople API 연동, 관리자 페이지, 유저 프로필, 인증 시스템

---

Neople API 연동 (던전앤파이터 전적 조회)

Neople 공식 Open API를 활용해 던파 캐릭터 장비 및 스펙 조회

구현 내용

• 사용자가 입력한 한글 서버명을 API 서버 코드로 변환 (카인, 시로코, 바칼 등 8개 서버 지원)
• 닉네임으로 캐릭터 ID를 먼저 조회한 뒤, 해당 ID로 장착 장비를 조회하는 2단계 API 호출 구조
• 캐릭터명, 레벨, 직업명, 길드명, 모험단 명성, 장착 장비 목록(강화/증폭 수치 포함) 반환
• Spring의 HTTP 클라이언트로 외부 API를 호출하고 JSON 응답을 파싱하여 DTO로 가공

GET /dnf/stats/by-gamecode?gameCode=카인-캐릭터닉네임

---

관리자 페이지

Spring Security의 역할 기반 접근 제어를 적용해 관리자만 접근 가능하도록 구현

구현 내용

• 전체 유저 목록 조회 및 유저 상세 정보 조회 (소속 채팅방 포함)
• 신고 접수 유저 임시 정지 (정지 기간 직접 지정 가능)
• 신고 접수 유저 영구 정지 및 정지 해제
• 제재 처리 시 해당 유저의 모든 로그인 세션을 즉시 강제 만료
• 세션 만료와 동시에 WebSocket으로 강제 로그아웃 메시지를 실시간 전송해 즉각 반영
• 신고 내용 검증을 위한 채팅방별 채팅 로그 조회 기능

제재 흐름

신고 접수 → 채팅 로그 확인 → 정지 기간 선택 후 제재 처리
→ DB 상태 변경 + 세션 강제 만료 + 강제 로그아웃 알림 동시 처리

---

유저 프로필

구현 내용

• 프로필 사진 업로드 및 변경
• 상태 메시지 설정
• 커스텀 태그로 자신을 간단히 소개하는 기능
• 자주 하는 게임 등록 — 실제 존재하는 게임 ID를 등록해야 플랫폼 핵심 서비스 이용 가능
• 길게 자기소개를 작성할 수 있는 소개란

---

인증 시스템 (자동로그인 / 중복로그인 처리)

자동로그인

• Spring Security의 Remember-Me 기능을 Persistent Token 방식으로 구현
• 로그인 시 자동로그인 토큰을 발급하고 DB에 저장
• 재접속 시 저장된 토큰을 대조해 자동 로그인 처리

중복 로그인 방지

• 동일 계정의 동시 로그인을 1개로 제한
• 다른 기기에서 로그인하면 기존 세션이 자동 만료되고 새 로그인이 우선권을 가짐
• 로그인 시 세션 ID를 새로 발급해 세션 고정 공격 방어

---

주요 기능

인증 및 사용자 관리

• 로그인 / 회원가입 (이메일 인증 포함)
• 아이디 찾기 / 비밀번호 찾기
• 자동 로그인 / 중복 로그인 방지
• 프로필 관리, 친구 시스템 (추가 / 삭제 / 초대)

실시간 채팅

• 게임 카테고리별 채팅방 생성 및 관리
• 실시간 메시지 전송 / 수신, 이미지 메시지, 링크 미리보기, 이모지 지원

음성 채팅

• Agora SDK 기반 실시간 음성 통화
• 음성 채널 생성 / 관리, 마이크 음소거

게임 연동

• 게임 실행 상태 자동 감지
• 리그 오브 레전드 / 메이플스토리 / 로스트아크 / 던전앤파이터 전적 연동

검색 및 매칭

• 사용자 검색, 게임별 매칭 서비스

관리자 기능

• 유저 관리, 신고 처리, 제재 / 해제

---

기술 스택

Backend

기술	용도
Java 21	메인 언어
Spring Boot 3.4.5	웹 프레임워크
Spring Security	인증 / 인가 / 세션 관리
Spring WebSocket (STOMP)	실시간 통신
Spring Data JPA	DB 연동
MySQL	데이터베이스
Agora SDK	음성 채팅

Frontend

기술	용도
React	UI 프레임워크
Vite	빌드 도구
Electron	데스크톱 앱 패키징
STOMP.js	WebSocket 클라이언트
React Router	라우팅

외부 API

• Riot Games API
• Neople API (던전앤파이터)
• 로스트아크 API
• 메이플스토리 API

---

실행 화면

로비 페이지

프로필

서치 페이지

방 입장

음성 채팅

관리자 페이지

---

설치 및 실행

Windows 설치

1. 최신 릴리스 다운로드

   • GitHub Releases에서 QMatch Setup X.X.X.exe 다운로드

2. 설치 실행

   • 설치 파일 실행 후 마법사 안내에 따라 진행

3. 애플리케이션 실행

   • 바탕화면 QMatch 아이콘 클릭 또는 시작 메뉴에서 QMatch 검색

첫 실행 시

1. 회원가입 또는 로그인
2. 프로필 설정 (게임 ID 등록 필수)
3. 원하는 게임 카테고리 채팅방 참여

---

라이선스

GPL-3.0 License — 졸업작품 프로젝트

---

원본 레포지토리

팀 전체 기여 내역은 원본 레포지토리에서 확인할 수 있습니다.
https://github.com/MianShang/QMatch