170 lines (136 loc) · 7.38 KB

🎲 BoardBuddy – MVP PRD (Full Context Master Version)

보드게임 모임에서의 게임 플레이를 간단하게 기록하고, 모임 단위로 스코어와 랭킹을 확인할 수 있는 소규모 웹 서비스

1. 프로젝트 목표 및 범위 (Goals & Scope)

1.1 목표 (Goals)

보드게임 모임에서의 게임 결과를 빠르고 단순하게 기록
모임 단위 누적 스코어 / 랭킹 제공
개인별 플레이 이력 대시보드 제공
소규모 모임 기준으로 복잡도 최소화

1.2 범위 (Scope - MVP 기준)

포함 (Included)

❌ 네이버 OAuth 로그인 → 이메일/비밀번호 로그인으로 대체 구현
✅ 개발자 생성 테스트 계정
✅ 모임 생성 및 초대
✅ 게임 종류 선택 + 기본 룰 프리셋
✅ 게임 결과 기록
✅ 모임 내 랭킹
❌ 개인 게임 기록 대시보드

제외 (Excluded - MVP 이후)

모임 아카이브, 관리자 UI, 공개 커뮤니티, 실시간 게임 보조 기능

2. 핵심 도메인 및 데이터 구조 (Core Domains)

2.1 도메인 요약

User: 사용자 정보 및 인증
Group (모임): 게임이 이루어지는 단위
GroupMember: 모임에 소속된 유저
GameType: 게임 종류 및 기본 룰 프리셋
GameSession (게임 기록): 실제 플레이된 한 판의 세션
GameResult: 유저별 결과 (스코어/순위)
RankingPolicy: 랭킹 산정 정책

2.2 기술적 데이터 모델 (ERD)

테이블	주요 필드	비고
User	`id`, `email`, `nickname`, `discriminator`	이메일 불변
Group	`id`, `name`, `owner_id`, `created_at`	불변 정책
GameSession	`group_id`, `game_type_id`, `played_at`	특정 모임에 소속
GameResult	`session_id`, `user_id`, `score`, `rank`	세션 결과 상세

3. 도메인별 상세 Task 및 정책 (우선순위 포함)

3.1 User 도메인

정책: 네이버 OAuth 기반, 이메일 불변, 닉네임#discriminator 구조 (닉네임 변경 시에도 고유 식별자 유지)
❌ [P0] 네이버 OAuth 로그인 연동 → 이메일/비밀번호 방식으로 대체 구현됨
✅ [P0] User 생성 및 조회
✅ [P0] 이메일 불변 정책 적용
❌ [P1] 닉네임 변경 기능
✅ [P1] discriminator 생성 및 고정 정책
✅ [P2] 닉네임#discriminator 검색 API (초대용) → 이메일 검색도 함께 지원

3.2 Group (모임) 도메인

정책: 모임은 불변(Immutable). 멤버 변경 시 새 모임 생성
✅ [P0] 모임 생성
✅ [P0] 모임 멤버 초대
✅ [P0] 모임 멤버 조회
✅ [P1] 모임 상세 조회
✅ [P1] 모임 생성 시 초대 인원은 PENDING 상태로 표시
✅ [P1] 초대 취소 기능
✅ [P1] 모임 삭제 시 초대장 정리 (삭제 또는 미노출)

3.3 GameType (게임 종류)

정책: 기본 룰 프리셋 제공 및 기록자의 커스텀 허용
✅ [P0] 게임 종류 목록 제공
✅ [P0] 게임별 기본 룰 프리셋 정의
✅ [P1] 게임별 커스텀 룰 설정 → 모임별 커스텀 게임으로 구현됨

3.4 GameSession (게임 기록)

정책: 특정 모임 소속 필수 및 게임 종류 선택 필수
✅ [P0] 게임 세션 생성
✅ [P0] 참여 유저 선택
✅ [P0] 스코어 입력 (HIGH_WIN / LOW_WIN / RANK_ONLY / WIN_LOSE / COOPERATIVE)
❌ [P1] 게임 결과 수정

3.5 Ranking & Score

정책: 스코어 기반 랭킹. 게임별 정책(승자 승점, 1등 승점 등) 확장 가능 구조
✅ [P0] 게임 세션 결과 기반 스코어 계산
✅ [P0] 모임 내 누적 랭킹 조회 (가장 많이 플레이 / 최다 승리 / 승률 / 누적 점수 / 인기 게임)
✅ [P1] 랭킹 정책 확장 구조 설계 → WIN_LOSE / COOPERATIVE에서 승점/패점 직접 설정 가능

3.6 Dashboard

❌ [P0] 개인 게임 기록 조회 (개인 대시보드 페이지 미구현)
✅ [P1] 게임별 플레이 횟수 → 모임 대시보드의 "인기 게임" 섹션으로 구현됨
✅ [P2] 승률 / 평균 순위 → 모임 대시보드의 "승률 랭킹" 섹션으로 구현됨

4. 상세 기술 설계 (Implementation Detail)

4.1 핵심 API 리스트

기능	Method	Endpoint	상태
로그인	`POST`	`/api/v1/auth/login`	✅ (이메일/비밀번호)
회원가입	`POST`	`/api/v1/auth/register`	✅
모임 생성	`POST`	`/api/v1/groups`	✅
모임 초대	`POST`	`/api/v1/groups/{id}/invitations`	✅
초대 수락/거절	`POST`	`/api/v1/invitations/{id}/accept	reject`
초대 취소	`POST`	`/api/v1/invitations/{id}/cancel`	✅
유저 검색	`GET`	`/api/v1/users/search?keyword=`	✅
기록 저장	`POST`	`/api/v1/groups/{id}/sessions`	✅
모임 통계 조회	`GET`	`/api/v1/groups/{id}/stats`	✅
내역 조회	`GET`	`/api/v1/users/me/history`	❌ 미구현
네이버 OAuth	`GET`	`/api/v1/auth/naver`	❌ 미구현

4.2 랭킹 산정 알고리즘

동점자: 동일 순위 부여 후 다음 순위는 건너뜀 (예: 공동 1위가 2명이면 다음 사람은 3위).
점수 방식: 높은 점수 승리(High Win) / 낮은 점수 승리(Low Win) 구분 필드 포함.

5. UX 흐름 및 엣지 케이스

5.1 게임 기록 UX 흐름

모임 선택 -> 2. 게임 종류 선택 -> 3. 기본 룰 프리셋 확인 / 수정 -> 4. 참여 멤버 선택 -> 5. 스코어 입력 -> 6. 결과 저장 -> 7. 랭킹 반영

5.2 엣지 케이스

동일 닉네임 사용자 존재 (Discriminator로 구분)
일부 멤버만 참여한 게임 (선택된 멤버만 결과 생성)
스코어 없이 순위만 존재하는 게임 기록 지원
기록 중 취소 시 데이터 미저장
모임 생성 시 초대된 사용자는 PENDING 상태로 표시되고 게임 참여 불가
모임 삭제 시 해당 모임의 초대장은 삭제되거나 유저에게 노출되지 않음
초대 취소 기능 제공 (초대자가 또는 모임 오너가 취소 가능)
초대자에게 초대 상태(대기/수락/거절) 노출

6. 개발 원칙 (Principles)

API / DB 설계는 점진적으로
단순한 정책 우선
소규모 모임 최적화
불변 도메인 적극 활용

7. 구현 현황 요약

도메인	항목	상태
인증	이메일/비밀번호 로그인 & 회원가입	✅
인증	네이버 OAuth 로그인	❌
인증	테스트 계정 자동 시딩	✅
User	회원가입 / 조회 / 삭제	✅
User	이메일 불변 정책	✅
User	discriminator 자동 생성	✅
User	닉네임#태그 / 이메일 검색	✅
User	닉네임 변경	❌
Group	모임 생성 / 조회 / 멤버 목록	✅
Group	모임 초대 (발송 / 수락 / 거절)	✅
Group	모임 목록 순서 변경 (D&D)	✅
GameType	공식 게임 목록 / 프리셋	✅
GameType	모임별 커스텀 게임	✅
GameSession	세션 생성 (5가지 점수 전략)	✅
GameSession	세션 상세 조회	✅
GameSession	세션 결과 수정	❌
Ranking	모임 대시보드 (5개 랭킹 섹션)	✅
Dashboard	개인 게임 기록 대시보드	❌