IBA Scoring Machine

부산대 데이터분석 동아리 IBA의 중고차 가격 예측 회귀 프로젝트를 자동으로 채점하는 사이트다. 팀이 예측 결과 CSV를 올리면 RMSE와 R²를 바로 계산해 리더보드에 올린다. Vercel Hobby와 Neon Postgres Free 무료 티어로 운영해서 비용이 들지 않는다.

• 사이트: https://iba-scoring-machine.vercel.app
• 참가자용 사용법: 사이트의 사용법 페이지(/how-to-use.html)

읽는 순서

읽는 사람	먼저 볼 곳
대회에 참가하는 팀원	사이트의 사용법 페이지, 이 문서의 채점 규칙
이번 기수 대회를 여는 운영진	기수 운영, 문제 해결
사이트를 고치는 사람	기술 스택, 폴더 구조, 로컬 실행, 테스트, 작업 방식, 자주 고치는 곳
사이트를 처음부터 다시 세우는 사람	새로 배포하기

주요 기능

• 예측 CSV를 올리면 형식을 검사하고 몇 초 안에 RMSE와 R²를 보여 준다. 형식이 틀리면 헤더, 행 수, id 순서 중 무엇이 틀렸는지 알려 준다.
• 리더보드는 로그인 없이 볼 수 있고 팀마다 한 줄로 보여 준다. 대회 중에는 public 최고 점수만 보이고, 마감 뒤에는 최종 RMSE와 최종 순위가 함께 나온다.
• 팀당 하루 제출 횟수를 제한하고, 제출 페이지에 오늘 남은 횟수와 다 썼을 때의 초기화 시각을 보여 준다.
• 제출 페이지 아래에 우리 팀 제출 목록이 있고, 여기서 최종 순위에 쓸 제출을 마감 전까지 고를 수 있다.
• 관리자 페이지에서 대회 일정, 제출, 사용자, 기수 초기화를 코드 수정 없이 관리한다.
• 쉬는 시간용 미니게임 다섯 개와 게임별 개인 순위가 있다. 게임은 사과게임, 테트리스, 블록깨기, 슈팅게임, 스네이크다.
• 사이트를 소개할 때 쓰는 구경용 계정 iba_dev가 있다. 이 계정으로 낸 제출과 게임 점수는 기록하지 않고, 리더보드와 게임 순위에는 실제 기록 대신 목데이터가 보인다.

채점 규칙

• 제출 파일은 sample_submission.csv와 같은 id,price CSV다. 39,085행 전부를 test.csv와 같은 순서로 내야 한다.
• 채점은 id가 아니라 행 위치끼리 짝지어 한다. test.csv, sample_submission.csv, 정답의 id는 0부터 39,084까지의 행 번호다. 원본 데이터의 id는 서로 다른 차량이 같은 값을 쓰는 경우가 많아서 행 번호로 다시 매겼다.
• 순위는 RMSE로 매기고 R²는 참고용이다. RMSE가 같으면 R²가 높은 팀이, 그것도 같으면 먼저 제출한 팀이 위에 온다. 음수 예측은 0으로 바꿔 채점한다.
• 팀당 하루 3회까지 제출할 수 있고 한국 시간 자정에 초기화된다. 횟수는 관리자 페이지에서 바꿀 수 있다.
• 대회 중에는 test의 30%로 계산한 public 점수만 보인다. 마지막 날 다음 날 0시부터 제출이 막히고 리더보드에 전체 데이터 기준 최종 RMSE와 최종 순위가 나온다. 최종 순위에는 팀이 고른 제출 1건이 쓰이고, 고르지 않은 팀은 public 점수가 가장 좋았던 제출이 쓰인다.
• 참가자는 아이디, 비밀번호, 닉네임, 팀 번호로 가입한다. 팀 번호는 이번 기수 팀인 1-4만 받고, 같은 팀 번호를 적은 사람끼리 한 팀이 된다. 리더보드에는 제출 기록이 있는 팀만 보인다.
• 프로젝트에 참가하지 않는 동아리원은 팀 번호 0으로 가입한다. 0번 계정은 미니게임만 할 수 있고 제출은 서버에서 막으며, 화면에는 팀 번호 대신 Guest로 보인다.

public 점수와 최종 점수를 나누는 것은 과적합을 막기 위해서다. 보이는 점수만 보고 모델을 고르면 그 30% 구간에만 잘 맞는 모델이 나오기 쉬워서, 최종 순위에는 대회 중에 본 적 없는 행을 섞는다. Kaggle의 public과 private 리더보드와 같은 방식이다.

기술 스택

역할	도구	고른 이유
백엔드	Python 3.12, FastAPI	동아리원 대부분이 Python을 쓰고, 채점 로직을 pandas 없이 표준 라이브러리로 짤 수 있다
프론트엔드	HTML, CSS, 바닐라 JavaScript	빌드 단계가 없어서 파일을 고치면 그대로 반영된다
배포	Vercel Hobby	main에 push하면 자동 배포되고, Python 함수와 정적 파일을 한 저장소에서 같이 올린다
DB	Neon Postgres Free	신용카드 없이 쓸 수 있는 무료 Postgres다

사이트는 PC 브라우저에서 쓰는 것을 전제로 만들었고 모바일 화면과 터치 입력은 지원하지 않는다. 미니게임도 마우스와 키보드로만 조작한다.

Vercel Hobby는 비상업 용도로만 쓸 수 있다. 광고나 유료 기능을 붙이면 요금제를 바꿔야 한다. 플랫폼을 고른 과정과 무료 티어 한도는 docs/tech-stack-research.md에 있다.

flowchart LR
  B[브라우저] -->|HTML, CSS, JS, 데이터셋| CDN[Vercel CDN<br/>public/]
  B -->|/api/*| F[Vercel Python 함수<br/>app.py]
  F --> S[scoring/<br/>CSV 검증, RMSE, R²]
  F --> DB[(Neon Postgres<br/>정답, 계정, 제출, 게임 점수, 설정)]

페이지와 데이터셋은 Vercel CDN이 public/에서 그대로 내려보내고, /api/로 시작하는 요청만 Python 함수가 처리한다. 정답은 Neon DB에만 있어서 브라우저에서는 정답을 받을 수 없고, 채점할 때 함수만 정답을 읽는다.

폴더 구조

app.py               # FastAPI 앱, /api/* 엔드포인트 (Vercel Python 런타임 진입점)
auth.py              # 비밀번호 해시(PBKDF2), 서명 쿠키 세션
store.py             # 저장소 계층: PostgresStore(Neon) / MemoryStore(테스트, 로컬)
scoring/             # 채점 로직
  parse.py           #   제출 CSV 검증
  metrics.py         #   RMSE, R²
  split.py           #   public 구간 선택 (30%)
  teams.py           #   팀 번호와 닉네임 정규화, 이번 기수 팀 목록
  clock.py           #   한국 시간 기준 일정과 제출 횟수 초기화 시각
public/              # 정적 사이트 (Vercel CDN이 그대로 서빙)
  *.html             #   홈, 채점, 리더보드, 사용법, 미니게임, 로그인, 관리자, About, Thanks
  assets/            #   페이지별 CSS, JS, 이미지
  games/             #   미니게임
  data/              #   참가자 배포용 CSV 네 개와 baseline 노트북, 이 다섯 개를 묶은 dataset.zip,
                     #   구경용 계정이 쓰는 demo_submission.csv, 채점 화면이 읽는 lyrics-*.txt
scripts/             # schema.sql, load_answers.py(정답 적재), grant_admin.py(첫 관리자 지정)
tests/               # pytest (API 레벨)
docs/                # 개발 문서: 구현 스펙, 구현 전 결정 기록, 기술 스택 조사
.github/workflows/   # push와 PR마다 pytest를 돌리는 GitHub Actions
vercel.json          # 배포 지역(싱가포르)과 함수 번들에서 뺄 폴더

로컬 실행

Python 패키지 관리는 uv를 쓴다. uv가 없으면 https://docs.astral.sh/uv/ 에서 먼저 설치한다.

uv venv --python 3.12 .venv
source .venv/bin/activate          # Windows PowerShell: .venv\Scripts\Activate.ps1
uv pip install -r requirements-dev.txt

DB 없이 돌리려면 정답 CSV 경로만 넘긴다. 제출 기록은 메모리에만 남고 재시작하면 사라진다.

# macOS, Linux
DEV_ANSWER_CSV=answer.csv SESSION_SECRET=dev uvicorn app:app --port 8765

# Windows PowerShell
$env:DEV_ANSWER_CSV="answer.csv"; $env:SESSION_SECRET="dev"; uvicorn app:app --port 8765

브라우저에서 http://localhost:8765 를 연다. 이 모드에서는 아무 아이디와 비밀번호로나 로그인되고, 아이디 admin으로 로그인하면 관리자 계정이 된다. 실제 배포에서는 이 기능이 꺼져 있다.

정답 파일 없이 화면만 보고 싶으면 public/을 8791 포트로 띄운다. 이 포트에서는 public/assets/local-preview.js가 API 응답을 흉내 내서 로그인한 화면을 볼 수 있다. 리더보드 기록은 흉내 내지 않으므로 리더보드는 8765 포트에서 확인한다.

python -m http.server 8791 -d public

테스트

pytest

실제 정답 파일로 기준값 테스트까지 하려면 ANSWER_CSV에 정답 경로를 넣고 pytest tests/test_real_data.py를 실행한다. sample_submission을 그대로 내면 전체 데이터 RMSE가 13,189.79로 나와야 한다. 채점 로직을 고쳤다면 push하기 전에 이 테스트까지 돌린다.

GitHub Actions도 main에 push하거나 PR을 올릴 때마다 pytest를 돌린다. 저장소에는 정답 파일이 없어서 Actions에서는 실제 정답 테스트를 건너뛰고 합성 정답으로 만든 테스트만 실행한다.

작업 방식

지금까지는 대부분의 수정을 main에 바로 push했고, 화면을 크게 바꾸는 작업 11건은 feat/나 fix/ 브랜치에서 PR로 올려 병합했다. main에 push하면 바로 실제 사이트에 배포되므로, 앞으로는 아래처럼 PR로 올리기를 권한다.

1. main에서 feat/나 fix/로 시작하는 브랜치를 만든다.
2. push하기 전에 pytest를 돌리고, 채점 로직을 고쳤다면 실제 정답 테스트까지 돌린다.
3. GitHub에 PR을 올리고, 화면을 바꿨다면 Vercel이 만든 미리보기 주소에서 확인한다.
4. GitHub Actions의 테스트가 통과하면 main에 병합한다.

scripts/schema.sql을 고친 PR은 병합하기 전에 psql "$DATABASE_URL" -f scripts/schema.sql을 운영 DB에 먼저 실행한다. 새 코드가 DB에 없는 컬럼이나 테이블을 읽으면 리더보드와 제출이 500 오류로 멈춘다.

미리보기 주소도 실제 사이트와 같은 DB를 쓴다. 미리보기에서 가입하거나 제출하면 실제 기록에 남으므로 화면 확인은 구경용 계정 iba_dev로 한다.

배포

저장소는 GitHub 조직 pnu-iba의 https://github.com/pnu-iba/iba_scoring_machine 이다. Vercel 팀 pnu-iba와 Neon DB는 동아리 공용 구글 계정으로 관리하고, Vercel은 동아리 GitHub 계정 pnuiba와 연결되어 있다. 계정 정보는 운영진끼리 따로 전달한다.

main 브랜치에 push하면 Vercel이 자동으로 배포한다. 다른 브랜치에 push하면 미리보기 주소가 따로 만들어진다. 미리보기가 같은 DB를 쓴다는 점은 작업 방식 절에 적었다.

This is the beginning of the README. Read the rest at the original. Read the full README ↗