2021년 대한체육회 주관 전국체전 대진표 추첨 행사 생방송 추첨 집계 및 화면 송출용 프로그램 개발. 총 390여개 토너먼트 대회 추첨 운영

전국체육대회 토너먼트 조추첨 시스템 기술 소개서


1. 프로젝트 개요

전국체육대회 토너먼트 조추첨 시스템은 대한체육회 주관 전국체육대회의 종목별 대진 추첨 행사를
실시간으로 관리하고 표출하기 위한 웹 기반 애플리케이션이다. 3팀에서 19팀까지 다양한 참가 규모에
대응하는 토너먼트 대진표를 자동 생성하며, 추첨 과정과 결과를 대형 디스플레이를 통해 실시간으로
송출할 수 있도록 설계되었다. 관리자 화면에서는 종목 선택, 대진 배치, 데이터 관리 등 행사 운영에
필요한 전반적인 기능을 제공한다. 백엔드 API 서버와 프론트엔드 웹 애플리케이션의 분리된
클라이언트-서버 아키텍처로 구성되어 있다.


2. 시스템 구성

본 시스템은 백엔드 API 서버와 프론트엔드 웹 애플리케이션으로 구성된 클라이언트-서버
아키텍처를 채택하고 있다.

2.1 백엔드 API 서버
역할: RESTful API 제공, 비즈니스 로직 처리, 데이터베이스 관리, 세션 인증
기술: Spring Boot, Maven, MySQL
규모:
API 엔드포인트 수: 9개
데이터 엔티티 수: 3개 (종목, 지자체, 토너먼트 배치)
서비스 계층: 종목 서비스, 지자체 서비스, 토너먼트 서비스, 데이터 내보내기 서비스

2.2 프론트엔드 애플리케이션
역할: 토너먼트 대진표 표출, 결과 화면 렌더링, 관리자 기능 제공
기술: React, Material-UI, Webpack
규모:
소스 파일 수: 47개 (JavaScript/JSX)
총 코드 라인 수: 약 7,250줄
화면/라우트 수: 3개 주요 라우트
토너먼트 대진표 컴포넌트: 17개 (3팀~19팀 규모별)
결과 표시 컴포넌트: 15개 (3팀~17팀 규모별)
재사용 UI 컴포넌트: 8개


3. 핵심 기술 스택

3.1 백엔드

Java - 서버 애플리케이션 개발 언어
Spring Boot - 웹 애플리케이션 프레임워크 (내장 서버, 자동 설정)
Spring MVC - RESTful API 컨트롤러 계층 구현
Spring Data JPA - 데이터베이스 접근 및 ORM 매핑
Maven - 프로젝트 빌드 및 의존성 관리 도구
MySQL - 관계형 데이터베이스 관리 시스템

3.2 프론트엔드

React - UI 컴포넌트 기반 프론트엔드 프레임워크
React Router DOM - 클라이언트 사이드 SPA 라우팅
Material-UI - Google Material Design 기반 UI 컴포넌트 라이브러리
ag-Grid Community - 고성능 데이터 그리드 테이블 컴포넌트
Axios - HTTP 클라이언트 라이브러리 (API 통신)
react-papaparse - CSV 파일 파싱 및 업로드 처리
iconv-lite - 문자 인코딩 변환 (EUC-KR 지원)
react-device-detect - 클라이언트 디바이스 유형 감지 (모바일/태블릿/데스크톱)

3.3 빌드 및 개발 도구

Webpack - 프론트엔드 모듈 번들러 (개발 서버 및 프로덕션 빌드)
Babel - JavaScript 트랜스파일러 (최신 문법 하위 호환 변환)
Prettier - 코드 포맷팅 도구

3.4 스타일링

Material-UI makeStyles - CSS-in-JS 방식의 컴포넌트 스타일링
Spoqa Han Sans Neo - 한국어 최적화 웹폰트 (5가지 굵기)


4. 핵심 기능

4.1 비즈니스 기능

4.1.1 토너먼트 대진표 관리
3팀에서 19팀까지 17가지 규모의 대진표 포맷 지원
팀 수에 따른 자동 대진표 레이아웃 선택 및 렌더링
17개 시도 지자체별 참가팀 배치 및 표시
종목, 종별, 세부종목 단위의 대진 구성
지역별 아이콘 및 배경 이미지를 활용한 시각적 대진표 표현

4.1.2 추첨 결과 표시
대진표 모드와 결과 모드 간 실시간 전환
팀 규모별 최적화된 결과 레이아웃
종목명 및 참가팀 정보가 포함된 결과 화면

4.1.3 종목 관리
종목 목록 조회 및 선택
종목별 참가 지자체 설정
현재 진행 종목 지정 및 전환
전체 데이터 초기화 기능

4.1.4 대진 배치 관리
지자체를 토너먼트 배치 위치에 순차적으로 할당
개별 배치 위치 취소 및 재배치
종목 단위 전체 배치 초기화
최대 17개 배치 슬롯 관리 (1번 및 A~P번 위치)

4.1.5 데이터 관리
CSV 파일 업로드를 통한 대량 데이터 입력 (EUC-KR 인코딩 지원)
대진 결과 CSV 파일 다운로드 (EUC-KR 인코딩 변환)
ag-Grid 기반 데이터 테이블을 통한 조회, 정렬, 필터링
전체 종목 배치 현황 일괄 내보내기

4.2 기술 기능

4.2.1 실시간 데이터 동기화
800밀리초 주기의 폴링 기반 실시간 데이터 갱신
서버 상태 변경 감지 시 자동 화면 모드 전환
종목 변경 시 자동 대진표 갱신

4.2.2 키보드 단축키 제어
스페이스바를 통한 대진표와 결과 화면 간 토글
방향키(위/아래)를 통한 명시적 모드 전환
대형 디스플레이 송출 환경에 최적화된 키보드 컨트롤

4.2.3 반응형 디자인
데스크톱, 태블릿, 모바일 디바이스 감지 및 대응
커스텀 브레이크포인트 설정 (태블릿 760px, 모바일 480px)
대형 디스플레이 송출용 고정 해상도(1920x1080) 레이아웃 지원

4.2.4 다국어 인코딩 처리
EUC-KR 인코딩 CSV 파일 읽기 및 쓰기 지원
한국어 데이터 처리를 위한 문자 인코딩 변환


5. 아키텍처 설계

5.1 백엔드 구조

Spring Boot 기반의 계층형 아키텍처를 채택하여 관심사를 명확히 분리하였다.

5.1.1 계층 구조
컨트롤러 계층: REST API 엔드포인트 정의 및 요청/응답 처리
서비스 계층: 비즈니스 로직 구현 (종목 관리, 배치 처리, 데이터 내보내기)
리포지토리 계층: Spring Data JPA 기반 데이터베이스 접근
엔티티 계층: JPA 엔티티 매핑 및 데이터 모델 정의

5.1.2 API 설계
모든 API는 POST 방식으로 통일하여 JSON 기반 요청/응답을 처리한다.
총 9개의 API 엔드포인트로 구성되며, 기능별로 분류하면 다음과 같다.

조회 API: 종목 목록 조회, 지자체 목록 조회, 화면 데이터 조회, 내보내기 데이터 조회
설정 API: 현재 종목 설정, 토너먼트 배치 설정, 참가 데이터 설정
초기화 API: 개별 배치 초기화, 전체 배치 초기화

5.1.3 서비스 구성
종목 서비스: 종목 목록 관리, 현재 종목 상태 관리
지자체 서비스: 17개 시도 지자체 정보 관리
토너먼트 서비스: 대진 배치 할당, 배치 초기화, 화면 데이터 통합 조회
데이터 내보내기 서비스: 전체 종목 배치 현황 데이터 추출

5.2 프론트엔드 구조

컴포넌트 기반 아키텍처를 채택하여 각 화면과 기능을 독립적인 React 컴포넌트로 분리하였다.

5.2.1 계층 구조
진입점 계층: 애플리케이션 초기화, 테마 설정, 전역 상태 프로바이더 구성
라우팅 계층: 경로별 페이지 컴포넌트 분기 처리
페이지 계층: 메인 화면, 관리자 화면, 종목 관리 화면
프레젠테이션 계층: 토너먼트 대진표, 결과 표시, 데이터 카드 등 UI 컴포넌트

5.2.2 컴포넌트 설계 패턴
팀 규모별 전용 컴포넌트 방식으로 3팀~19팀 대진표를 각각 독립 구현
팩토리 패턴을 활용한 동적 컴포넌트 선택 (팀 수 기반 대진표 자동 매칭)
공통 데이터 카드 컴포넌트를 통한 지자체 정보 표시 재사용

5.3 상태 관리

5.3.1 서버 상태
모든 핵심 데이터는 백엔드 데이터베이스에서 관리
프론트엔드는 폴링을 통해 서버 상태를 지속적으로 동기화
데이터 변경은 반드시 API를 통해 서버에서 처리

5.3.2 클라이언트 전역 상태
React Context API를 활용한 전역 상태 관리
로그인 상태 및 사용자 데이터 관리

5.3.3 클라이언트 로컬 상태
화면 모드 상태 (대진표/결과 전환)
토너먼트 데이터 (팀 수, 종목명, 배치 정보)
관리 화면 데이터 (종목 목록, 지자체 목록, 선택 상태)

5.4 데이터 통신 계층

중앙화된 API 요청 함수를 통해 모든 서버 통신을 일원화하였다.

5.4.1 일반 JSON 통신 함수
POST 방식의 JSON 데이터 송수신
세션 기반 인증 헤더 자동 첨부
Promise 기반 비동기 처리

5.4.2 멀티파트 폼 데이터 통신 함수
파일 업로드 등 바이너리 데이터 처리
멀티파트 인코딩 자동 설정

5.5 라우팅 설계

SPA(Single Page Application) 아키텍처 기반의 클라이언트 사이드 라우팅을 구현하였다.

메인 화면: 토너먼트 대진표 및 결과 표출 화면
관리자 화면: 대진 배치 설정 및 데이터 관리
종목 관리 화면: 종목별 참가팀 설정 및 CSV 데이터 관리


6. 인증 및 보안 아키텍처

6.1 인증 방식

세션 기반 인증 체계를 채택하여 관리자 접근을 제어한다.

6.1.1 세션 관리
서버 측 세션 관리를 통한 사용자 인증 상태 유지
세션 식별자를 API 요청 헤더에 자동 첨부
브라우저 세션 스토리지를 활용한 클라이언트 측 세션 정보 보관
하위 브라우저 호환성을 위한 대체 저장소 구현 (팝업 창 환경 지원)

6.1.2 관리자 인증
비밀번호 기반 관리자 접근 제어
인증 성공 시 관리 기능 활성화

6.2 접근 제어

6.2.1 공개 영역
메인 대진표 표출 화면은 인증 없이 접근 가능
실시간 데이터 폴링을 통한 자동 갱신

6.2.2 관리 영역
관리자 화면 및 종목 관리 화면은 인증 후 접근 가능
컴포넌트 내부 조건부 렌더링 방식의 접근 제어

6.3 API 보안

모든 API 요청에 인증 헤더를 포함하여 서버 측에서 세션 유효성을 검증한다.
CORS(Cross-Origin Resource Sharing) 설정을 통해 허용된 출처의 요청만 처리한다.


7. 데이터 관리

7.1 데이터베이스 설계

MySQL 관계형 데이터베이스를 사용하여 핵심 데이터를 영속적으로 관리한다.

7.1.1 종목 테이블
종목 고유 식별자, 종목명, 종별, 세부종목, 참가팀 수 관리
각 종목의 배치 슬롯 정보 포함 (최대 17개 위치)

7.1.2 지자체 테이블
17개 시도 지자체 정보 관리
지자체 고유 식별자 및 지자체명 저장

7.1.3 토너먼트 배치 테이블
종목과 지자체 간의 배치 관계 관리
종목 외래키, 지자체 외래키, 배치 위치 정보 저장
종목-지자체 간 다대다 관계를 배치 위치와 함께 관리

7.2 데이터 동기화

폴링 기반 실시간 동기화 방식을 채택하여 서버의 최신 상태를 지속적으로 반영한다.
주기적인 API 호출을 통해 종목 변경, 대진 배치 변경 등의 상태 변화를 감지하고
화면을 자동 갱신한다.

7.3 데이터 입출력

7.3.1 CSV 파일 입력
드래그 앤 드롭 방식의 CSV 파일 업로드
EUC-KR 인코딩 파일 자동 인식 및 처리
헤더 기반 데이터 파싱 및 빈 줄 자동 제거

7.3.2 CSV 파일 출력
대진 결과 데이터를 CSV 형식으로 변환
EUC-KR 인코딩으로 변환하여 한글 호환성 보장
날짜 기반 자동 파일명 생성 및 브라우저 다운로드

7.4 그리드 데이터 관리

ag-Grid 데이터 테이블을 활용하여 종목 목록, 참가팀 정보 등을 관리한다.
다중 행 선택, 컬럼별 정렬, API 기반 선택 데이터 접근 등의 기능을 제공한다.


8. 테스트 전략

현재 프로젝트에는 자동화된 테스트 체계가 구축되어 있지 않다.
단위 테스트, 통합 테스트, E2E 테스트 등의 테스트 코드가 미작성 상태이며,
수동 테스트를 통해 기능 검증을 수행하고 있다.


9. 배포 환경

9.1 백엔드 배포

Spring Boot의 내장 서버를 활용하여 독립 실행형 JAR 파일로 배포한다.
Maven을 통해 프로젝트를 빌드하고, 실행 가능한 JAR 파일을 생성하여 서버에 배포한다.
MySQL 데이터베이스 서버와 연동하여 데이터를 관리한다.

9.2 프론트엔드 빌드

Webpack 번들러를 통한 프로덕션 빌드를 수행한다.
Babel 트랜스파일러를 통해 최신 JavaScript 문법을 하위 브라우저 호환 코드로 변환하며,
한국 내 점유율 5% 이상 브라우저의 최근 2개 버전을 지원 대상으로 설정하였다.

9.3 개발 환경

백엔드: Spring Boot 내장 서버를 통한 로컬 개발 환경 구동
프론트엔드: Webpack 개발 서버를 통한 로컬 개발 환경 제공
Hot Module Replacement를 지원하여 프론트엔드 코드 변경 시 실시간 반영이 가능하며,
SPA 라우팅을 위한 History API Fallback이 설정되어 있다.

9.4 빌드 산출물

백엔드: Maven 빌드를 통한 실행 가능 JAR 파일 생성
프론트엔드: 정적 파일(HTML, JavaScript 번들, CSS, 이미지, 폰트) 생성


10. 기술적 우수성

10.1 클라이언트-서버 분리 아키텍처

백엔드 API 서버와 프론트엔드 웹 애플리케이션을 완전히 분리하여 독립적인 개발,
배포, 확장이 가능하다. Spring Boot 기반의 안정적인 서버 아키텍처와 React 기반의
동적 클라이언트를 조합하여 각 계층의 장점을 극대화하였다.

10.2 체계적인 백엔드 설계

Spring Boot의 계층형 아키텍처(Controller-Service-Repository)를 적용하여
비즈니스 로직과 데이터 접근을 명확히 분리하였다. Spring Data JPA를 통한 ORM
매핑으로 데이터베이스 접근의 생산성과 유지보수성을 확보하였으며, MySQL 관계형
데이터베이스를 통해 종목, 지자체, 토너먼트 배치 간의 관계를 체계적으로 관리한다.

10.3 다양한 대진 포맷 대응

3팀부터 19팀까지 17가지 규모의 토너먼트 대진표를 각각 최적화된 레이아웃으로
지원한다. 팀 수에 따라 자동으로 적절한 대진표 컴포넌트를 선택하여 렌더링하며,
각 포맷별로 경기 흐름과 승자 진출 구조를 시각적으로 명확하게 표현한다.

10.4 실시간 행사 운영 지원

800밀리초 주기의 데이터 동기화를 통해 관리자의 조작이 즉시 표출 화면에 반영된다.
종목 변경 시 자동 모드 전환 기능으로 행사 진행자가 별도의 화면 조작 없이도
원활한 행사 진행이 가능하다. 키보드 단축키를 통한 빠른 화면 전환으로
대형 디스플레이 송출 환경에서의 운영 편의성을 제공한다.

10.5 데이터 호환성

EUC-KR 인코딩 CSV 파일의 읽기 및 쓰기를 지원하여 기존 업무 시스템과의
데이터 호환성을 확보하였다. 드래그 앤 드롭 방식의 직관적인 파일 업로드와
자동 인코딩 변환을 통해 사용자 편의성을 높였다.

10.6 일관된 UI/UX 설계

Material Design 기반의 통일된 디자인 시스템을 적용하여 시각적 일관성을 유지한다.
커스텀 색상 팔레트(진한 파랑, 빨강, 갈색 계열)와 한국어 최적화 웹폰트(Spoqa Han
Sans Neo)를 활용하여 공식 행사에 적합한 격식 있는 화면을 구현하였다.

10.7 확장 가능한 구조

컴포넌트 기반 프론트엔드 아키텍처를 통해 새로운 규모의 토너먼트 포맷 추가가 용이하며,
Spring Boot의 계층형 백엔드 구조를 통해 신규 API 및 비즈니스 로직의 추가가 용이하다.
중앙화된 API 통신 계층과 전역/로컬 상태 분리를 통해 시스템 복잡도를 적절히 통제하고 있다.