HOOPLY — 농구 동호회 팀 배정 서비스
매주 참석자가 바뀌고 실력을 모르는 게스트가 섞이는 농구 모임에서, 균형 잡힌 팀 나누기 3가지 안을 추천하고 그 팀에 맞는 전술까지 알려 주는 모바일 웹 서비스
대표 화면
| 홈 · 다가오는 일정 | 참석 응답 | AI 배정 설명 |
|---|
| | |
| 전술 추천 · 자리 배치 | 전술판 (단계별 재생) | 내 기록 · 쿼터 성적 |
| | |
5분 요약
- 문제 — 동호회 모임은 매주 12
14명이 오고, 인원이 모자라면 실력을 모르는 게스트를 24명 부릅니다. 팀은 매번 매니저의 감으로 나뉘고, 근거가 없어 불만이 쌓입니다.
- 누구를 위해 — 팀을 나누는 매니저(1차)와, 균형 잡힌 경기를 원하는 참가자(2차).
- 어떻게 — 참석자의 실력 · 포지션 · "같이 뛰고 싶은 사람"을 따져 팀 나누기 3가지 안(실력 우선 · 친화도 우선 · 종합)을 추천하고, 매니저가 고르거나 고쳐서 확정합니다.
- 기록 — 개인 기록 없이 쿼터마다 뛴 5명과 점수만 넣으면, "예상보다 얼마나 더 잘했나"를 쌓아 실력 지표가 스스로 보정됩니다.
- 검증 — 설계 판단마다 시뮬레이션 · 실측 · 자동 테스트로 확인했습니다 → 주요 의사결정 · 요구사항 추적표
핵심 원칙 3가지
| 원칙 | 뜻 | 근거 |
|---|
| 추천은 알고리즘, 결정은 매니저 | 알고리즘은 3가지 안을 내놓기만 합니다. 매니저가 고르고, 선수를 옮기거나 맞바꾸고, 확정해야 참석자에게 공개됩니다 | 기획서 1.4절 |
| 판단은 규칙, 문장은 AI | 누가 활약할지 · 어떤 전술과 자리가 맞는지는 서버의 계산 규칙이 정합니다. AI(LLM, 문장을 만들어 주는 대형 언어 모델)는 그 결과를 읽기 쉬운 문장으로만 바꿉니다. AI 가 실패하면 규칙 설명이 그대로 나옵니다 | AI 전술 요구사항 1.2절 |
| 최소 기록 | 쿼터별 출전 5명과 팀 점수만 입력합니다. 개인 득점 · 리바운드 같은 스탯은 받지 않습니다 | 기획서 1.4절 · 9장 |
기획 과정을 따라가는 법
코드보다 문제 정의 → 요구사항 → 설계 판단 → 검증을 보시려면 이 순서로 읽으세요.
| 단계 | 문서 | 여기서 볼 수 있는 것 |
|---|
| ① 문제 정의 | 서비스 정의 1~2장 | 페인포인트 8개(P1~P8)와 핵심 난제(게스트 콜드 스타트 — 데이터가 없는 사람을 어떻게 배정에 넣을까) |
| ② 요구사항 | 요구사항 추적표 | 문제 → 요구사항 → 구현된 기능 → 검증 방법 · 결과를 표 하나로 |
| ③ 설계 판단 | 주요 의사결정 | 선택지와 그 결정을 내린 근거 데이터 (시뮬레이션 수치 등) |
| ④ 검증 | AI 설명 검증 결과 · 자동 테스트 | 배포 서버에서 AI 설명 72건 점검, 역할 일치율, 테스트 300여 건 |
문서 지도
전체 목차와 읽는 순서는 docs/README.md에 있습니다.
데모 데이터 안내
- 데모와 테스트에 나오는 사람 이름은 실존 농구 선수의 이름을 빌린 것입니다. 실력 등급 · 점수 · 설문 응답 · 투표 · 경기 기록은 모두 임의로 만든 가상 데이터이고, 실제 선수와는 관계가 없습니다. 이메일도 가짜 주소(
@demo.com)입니다.
- 데모 데이터는 매주 월요일 새벽에 자동으로 다시 만들어집니다. 여러 사람이 함께 쓰므로 다른 분이 먼저 배정을 확정했을 수 있습니다 — 대신 쓸 방법은 데모 시나리오에 있습니다.
- 실제 동호회 팀의 데이터는 저장소에 없고, AI 평가에도 쓰지 않았습니다(검증 결과의 표본 출처).
기술 스택과 규모
| 영역 | 사용 기술 |
|---|
| 백엔드 (서버) | Python 3.12 · FastAPI · SQLAlchemy 2.0 · Alembic · Pydantic v2 · NumPy |
| 데이터베이스 | PostgreSQL (운영 Neon, 로컬 Docker) |
| AI | LangChain · Google Gemini |
| 프론트엔드 (화면) | React 19 · TypeScript · Vite · Tailwind CSS v4 · TanStack Query · Zustand |
| 인증 · 연동 | JWT · bcrypt · 카카오 로그인 · 카카오톡 공유 · Resend(메일) |
| 테스트 | pytest · Vitest · Testing Library · Playwright |
| 배포 · 자동화 | Render(서버) · Vercel(화면) · Neon(DB) · Docker Compose · GitHub Actions |
| 규모 | 수 |
|---|
| 화면 | 31개 (02 화면 설계) |
| API (화면과 서버가 주고받는 창구) | 110개, /health 포함 (04 API 명세) |
| DB 스키마 변경 이력(마이그레이션) | 27개 |
| 자동 테스트 | 서버 pytest 259건 · 화면 단위 Vitest 103건 · 브라우저로 화면을 눌러 보는 E2E(Playwright) 22건 — 모두 GitHub Actions 에서 푸시마다 실행 |
실행 방법, 폴더 구성, 구현 상태는 08 개발 · 실행 가이드에 있습니다.
