HOOPLY — 농구 동호회 팀 배정 서비스

매주 참석자가 바뀌고 실력을 모르는 게스트가 섞이는 농구 모임에서, 균형 잡힌 팀 나누기 3가지 안을 추천하고 그 팀에 맞는 전술까지 알려 주는 모바일 웹 서비스

서비스	hooply-green.vercel.app (휴대폰 화면 기준. PC 에서는 창을 좁게)
데모 계정	매니저 [email protected] · 팀원 [email protected] · 비밀번호 모두 demo1234
5분 둘러보기	데모 시나리오의 "5분 코스: 팀 배정"
개발	1인 개발 (기획 · 설계 · 백엔드 · 프론트엔드 · 배포) · 2026-09-09 ~ 2026-09-30

대표 화면

홈 · 다가오는 일정	참석 응답	AI 배정 설명
전술 추천 · 자리 배치	전술판 (단계별 재생)	내 기록 · 쿼터 성적

5분 요약

1. 문제 — 동호회 모임은 매주 1214명이 오고, 인원이 모자라면 실력을 모르는 게스트를 24명 부릅니다. 팀은 매번 매니저의 감으로 나뉘고, 근거가 없어 불만이 쌓입니다.
2. 누구를 위해 — 팀을 나누는 매니저(1차)와, 균형 잡힌 경기를 원하는 참가자(2차).
3. 어떻게 — 참석자의 실력 · 포지션 · "같이 뛰고 싶은 사람"을 따져 팀 나누기 3가지 안(실력 우선 · 친화도 우선 · 종합)을 추천하고, 매니저가 고르거나 고쳐서 확정합니다.
4. 기록 — 개인 기록 없이 쿼터마다 뛴 5명과 점수만 넣으면, "예상보다 얼마나 더 잘했나"를 쌓아 실력 지표가 스스로 보정됩니다.
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에 있습니다.

문서	이 문서가 답하는 질문
요구사항 추적표	어떤 사용자 문제가 어떤 기능이 되었고, 어떻게 확인했나?
주요 의사결정	왜 이렇게 설계했나? 어떤 데이터로 정했나?
01 서비스 정의	누구의 어떤 문제를 풀고, 무엇을 요구하나? (기능 · 비기능 요구사항)
02 화면 설계	화면 31개는 무엇을 보여 주고 어떻게 이어지나?
03 데이터 모델	어떤 데이터를 어떤 구조로 저장하나?
04 API 명세	화면과 서버가 무엇을 주고받나?
05 데모 시나리오	데모 계정으로 무엇을 어떤 순서로 보면 되나?
06 배지	배지는 무엇을 하면 얻나?
07 AI 전술 요구사항	AI 설명과 전술 추천은 무엇을 어떤 규칙으로 하나?
AI 설명 검증 결과	AI 설명이 규칙의 판단을 벗어나지 않는지 어떻게 확인했나?
08 개발 · 실행 가이드

데모 데이터 안내

• 데모와 테스트에 나오는 사람 이름은 실존 농구 선수의 이름을 빌린 것입니다. 실력 등급 · 점수 · 설문 응답 · 투표 · 경기 기록은 모두 임의로 만든 가상 데이터이고, 실제 선수와는 관계가 없습니다. 이메일도 가짜 주소(@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 개발 · 실행 가이드에 있습니다.