RV Badminton App

#spring-boot#flutter#fastapi#duckdb#system-design

제가 실제로 다니는 배드민턴 모임을 위해 만든 운영 플랫폼입니다. 회원은 Flutter 앱으로 경기를 기록하고 실시간 리더보드와 개인 기록을 확인하며, Spring Boot 백엔드·운영진 대시보드·Python 포인트 계산 서비스가 이를 뒷받침합니다. App Store와 Google Play에 출시해 모임이 매주 사용하고 있습니다.

문제

모임은 단톡방 100명 이상, 정모마다 30–40명이 모이는 규모로 커졌고, 모든 경기 점수를 개인 포인트로 환산해 시즌마다 시상하는 것이 모임의 핵심 문화였습니다. 그런데 그 기록과 정산은 2년 동안 사람 손에 의존했습니다.

• 수작업 정산. 경기 결과는 “이름 네 개와 점수 두 개” 한 줄로 단톡방에 올라갔고, 모임장이 매주 몇 시간씩 메시지를 복사하고 오타를 고쳐 개인 C# 프로그램에 붙여 넣었습니다. 그 프로그램은 매번 첫 경기부터 전부 다시 계산했습니다.
• 늦은 리더보드. 정모 중에는 누구도 자기 순위를 몰랐고, 결과는 자정 무렵에야 공지됐습니다.
• 알림 공해. 경기하지 않은 회원까지 경기마다 알림을 받아, 결국 단톡방을 음소거하고 중요한 공지를 놓쳤습니다.
• 접근할 수 없는 데이터. “오늘 몇 게임 쳤지?”, “석 달 전보다 나아졌나?”에 답하려면 채팅을 거슬러 올라가야 했습니다.

해결

모임장에게 “규칙은 정해 주세요. 기록하고 계산하고 보여주는 일은 앱으로 만들겠습니다” 라고 제안했고, 한 달짜리 사이드 프로젝트로 시작한 일이 18개월의 개발로 이어졌습니다.

• 경기 기록과 알림의 분리. 회원이 앱에서 경기를 바로 기록하면 점수가 자동 계산되고, 알림은 경기에 참여한 사람에게만 갑니다. 공지·사진·건의는 앱의 커뮤니티로 옮겼습니다.
• 포인트 계산 엔진 분리. 점수 규칙은 거의 매달 바뀌는, 시스템에서 가장 불안정한 부분이었습니다. 이를 Spring Boot에서 떼어내 Python/FastAPI 서비스로 만들고 배포 단위를 분리했습니다. 저장소 소유권도 나눴습니다 — 원본 기록은 PostgreSQL, 재연 캐시는 DuckDB, 리더보드는 Redis. Java 쪽은 Redis 계약만 지키면 규칙이 어떻게 바뀌든 영향이 없습니다.
• 필요한 만큼만 재연. 리그포인트는 이전 경기 결과가 다음 계산의 입력이 되는 순차 체인이라, 지난 경기 하나를 고치면 그 뒤 전부를 다시 굴려야 합니다. 매번 처음부터 계산하는 대신 직전 스냅샷부터 재연하고, 재시작 시 원본과 캐시를 대조해 스스로 맞추도록 했습니다.
• 규칙 개편을 계기로 구조 재설계. 세 개의 리그포인트가 회원당 MMR 하나로, 다섯 단계 공식이 세 문장짜리 제로섬 정산으로 바뀌었습니다. 이때 MMR을 컬럼에 저장하지 않고 델타를 append-only 원장에 쌓아 합으로 구하도록 바꿨습니다. 출석 보정이 다음 정모의 시작 MMR이 되면서 재연 단위도 경기 순에서 하루 순으로 옮겼고, 재계산 요청은 1.5초 창으로 모아 가장 이른 날짜 하나로 합칩니다.

결과

• 정모 중 실시간 리더보드, 참가자 대상 알림, 회원별 경기·승률·포인트 이력을 제공해 모임장의 매주 수작업 정산을 없앴습니다.
• 약 1,000개의 커밋, 3개 언어로 만든 4개 서비스를 App Store·Google Play로 출시해 프로덕션에서 운영 중입니다.
• 매일 새벽 처음부터 전체 재연을 돌려 랭킹과 대조하는 검증을 도입했습니다. 이를 위해 DuckDB Postgres 스캐너의 N+1을 걷어내 1만 2천여 경기 전체 재연을 약 20분에서 80초 미만으로 줄였습니다.
• 원장 구조 덕분에 “경계일부터 부분 재연한 결과 == 처음부터 전체 재연한 결과”를 무작위 경계일 5개에 대해 바이트 단위로 검증하는 테스트를 쓸 수 있게 됐습니다.
• 경기별 정산 내역 API는 저장값이 아니라 원장에서 그 시점 상태를 복원해 다시 계산하고, 원장과의 일치 여부를 함께 돌려줍니다. 정모 단위 게임포인트 사전 집계로 리더보드 읽기를 31–33배 빠르게 했습니다.
• 개편은 Python 서비스 안에서 끝났고, Java 백엔드에서 바뀐 것은 큐 시그니처와 캐시 키 몇 개뿐이었습니다. 엔진을 분리한 결정이 여기서 값을 했습니다.

배운 것

• 가장 자주 바뀌는 부분을 독립된 배포 단위로. 서비스 분리의 이유는 기술 스택이 아니라 변경 빈도였고, 그 판단은 규칙 개편 때 그대로 회수됐습니다.
• 파생할 수 있는 값은 저장하지 않습니다. 덮어쓰는 지점이 없으면 낡아질 값도 없고, 재연이 순수 함수가 되어 테스트할 수 있게 됩니다. 파생 저장소는 언제 지워도 되는 캐시로 둡니다.
• 규칙은 코트에서 말로 설명할 수 있어야 합니다. 다섯 단계 공식은 정확했지만 “왜 5점밖에 안 올랐냐”에 답할 수 없었습니다. 사용자가 이해할 수 있는 규칙이 시스템의 요구사항이었습니다.
• 실사용자에게 먼저 배포하면 부채도 함께 옵니다. 테스트 커버리지는 고르지 않고 CI/CD와 API 문서는 남은 과제입니다. 대신 오류를 바로 알려 주는 사용자가 있었고, 그게 18개월을 이어 간 이유였습니다.

더 읽기

설계 결정의 근거와 구현 과정은 개발 일지에 챕터별로 기록했습니다.

• Chapter 1 — 프로젝트 소개
• Chapter 2 — PointCalculator
• Chapter 3 — PointCalculator, 두 번째

Flutter · Spring Boot · Java · Python · FastAPI · PostgreSQL · DuckDB · Redis