문서 목적 · 범위
본 문서는 볼토피아의 논리 데이터 모델과 API 개요를 정의합니다. 물리 데이터베이스 스키마 · 인덱스 · 성능 파라미터 · 인프라 구성은 본 문서 범위가 아니며 개발 단계 산출물에서 확정합니다. 모든 개인정보는 암호화 또는 토큰화 저장을 전제로 합니다.
확정 — 본 문서가 다루는 8개 논리 개체 · API 그룹은 모두 진승과의 계약 딜리버리 대상입니다.
논리 데이터 모델 (개념)
볼토피아는 8개 운영 영역에 대응하는 아래 개념 개체(entity)로 구성됩니다.
개념 데이터 모델 — 실제 테이블 구조가 아닙니다. 점선 = 진승 외부 연동 지점.
| 개체 | 설명 | 주요 속성 개요 |
|---|---|---|
| 회원 · 등급 (Member & Grade) | 회원 신원과 등급을 관리 | 상태(활성 · 휴면 · 탈퇴) · 등급(최근 1년 게임 수 기준) · 등급별 조건 · 혜택 설정. 민감 정보는 암호화 · 토큰화 보관 |
| 이벤트 · 접수 (Event Entry) | 대회 · 이벤트 접수와 진행 상태를 관리 | 접수 유형(개인 · 클럽 · 프로암) · 대기열 순번 · 접수~결제 진행 단계 · 성적 제출 · 확정 상태(확정 — 리그 · BMT는 참가자 제출 → 관리자 확정 2단계, 일반(GAME) 대회는 관리자 직접 입력) |
| 클럽 · 리그 (Club & League) | 클럽 구성과 리그 참여를 관리 | 정기 모임 반복 일정 · 클럽 간 리그 참여 · 강퇴(차단) 이력 · 리더보드 집계 대상 |
| 예약 (Reservation) | 레인 · 락커 예약 상태를 관리 | 시간대별 가용 · 예약 · 임대 상태 · 레인-정원 정합성 검증 결과 |
| 볼 등록 (Ball Registration) | 참가자 사용구 신고와 공인구 대조 결과를 관리 | 브랜드 · 모델 · 무게 · 시리얼 · 비고 · 공인구 원장 대조 결과("확인됨" · "미확인") |
| 성적 · 통계 (Score & Stats) | 경기 성적과 회원 통계를 관리 | 경기별 성적 기록 · 등급 산정용 누적 통계 · 명예의 전당 등재 기록 |
| 게시판 · 알림 (Board & Notification) | 게시글과 알림을 관리 | 공지 · FAQ · 문의 게시글 및 댓글 · 알림 카테고리(이벤트 · 결제 · 시스템) · 회원별 수신 설정 |
| 결제 (Payment) | 결제 · 환불 처리 결과를 관리 | 결제 처리 결과 · 환불 내역 · 결제 수단 상세 |
데이터 보호 저장 원칙
저장 데이터는 유출을 전제로 무력화합니다.
| 원칙 | 내용 |
|---|---|
| 인증정보 · 개인정보 분리 | 로그인 정보와 회원 개인정보를 분리 저장하여 한쪽 유출이 즉시 결합되지 않게 함 |
| 암호화 · 토큰화 | 저장 개인정보를 암호화하고, 연락처 등 민감 항목은 토큰화해 원문 비노출 |
| 성적 제출 잠금 | 확정된 대회 성적은 선수 본인이 직접 수정할 수 없도록 저장 단계에서 잠그며, 변경은 관리자 경유로만 남김 |
| 단일 세션 보장 | 회원 계정의 활성 로그인 세션은 항상 1개만 유지되도록 저장 구조가 보장 |
| 최소 보유 | 각 기능에 필요한 최소한의 정보만 보유하고, 사용하지 않는 항목은 제거 |
API 개요
아래는 기능 그룹 수준의 개요이며, 상세 규격(엔드포인트 경로 · 파라미터 · 응답 스키마)은 개발 단계에서 확정합니다.
| API 그룹 | 역할 | 대표 기능 | 인증 방식 |
|---|---|---|---|
| 인증 (Authentication) | 로그인 세션 관리 | 로그인 · 로그아웃 · 세션 갱신(현행 진승 인증 연동) | 진승 인증 연동 |
| 회원 (Member) | 회원 정보 · 등급 관리 | 등급 조회/변경 · 등급별 조건 · 혜택 설정 | 세션 인증 |
| 이벤트 접수 (Event Entry) | 대회 · 이벤트 접수 처리 | 접수 · 대기열 · 성적 제출/확정(리그 · BMT) 또는 관리자 직접 입력(일반 GAME) | 세션 인증 |
| 클럽 · 리그 (Club & League) | 클럽 · 리그 운영 | 클럽 운영 · 정기 모임 · 리그/리더보드 관리 | 세션 인증 |
| 예약 (Reservation) | 레인 · 락커 예약 처리 | 예약 · 임대 · 예약 현황 캘린더 | 세션 인증 |
| 볼 등록 (Ball Registration) | 사용구 등록 · 공인구 확인 | 사전 신고 · 진승 연동 대조 | 세션 인증 + 진승 연동 |
| 성적 · 통계 (Score & Stats) | 성적 · 등급 · 통계 처리 | 성적 일괄 반영 · 등급 재계산 · 통계 조회 | 세션 인증 |
| 게시판 · 알림 (Board & Notification) | 게시판 · 알림 처리 | 게시글 · 댓글 · 알림 목록/수신 설정 | 세션 인증 |
| 결제 (Payment) | 결제 처리 | 결제 처리 · 내역/정산 조회 | 토스페이먼츠(TossPayments) 연동 |
진승 고유 연동(인증 · 공인구 확인)은 서버 간 인증으로만 접근하며, 모든 접근을 전량 기록합니다.
확정
인증 API는 현재 진승 인증 연동을 전제로 합니다. 향후 진승 통합 인증(JS-AUTH/SSO) 완료 시 연동 방향이 그쪽으로 전환될 예정입니다.
연동 방식 (진승 공인구 확인)
볼 등록 시 신고된 시리얼을 진승 공인구 원장과 실시간 대조하는 단일 연동 지점입니다.
| 항목 | 내용 |
|---|---|
| 시리얼 대조 | 등록된 시리얼을 진승 공인구 원장과 실시간 대조하여 "확인됨" 여부를 자동 표시. 무게 · 브랜드 · 모델은 대조 대상 아님 |
| 장애 시 폴백 | 연동 장애 시에도 볼 등록 접수는 계속되며, 확인 여부만 "미확인"으로 남아 장애 해소 후 보정 |
| 최종 판정 | 시스템의 확인 결과는 참고용이며, 규정 위반 여부의 최종 판정은 관리자의 현장 검수를 거침 |
| 단계적 활성화 | 진승 측 연동 준비 이전에는 검증을 끈 상태로 운영 가능(이 경우 모든 등록은 "미확인"으로 접수, 등록 흐름 자체는 영향 없음) |
확정 대기
아래는 현시점 미확정 항목으로, 물리 스키마 · 상세 API 규격과 함께 개발 단계에서 확정합니다.
물리 스키마 · API 상세 규격
테이블 구조 · 인덱스 · 엔드포인트 경로 · 파라미터 · 응답 스키마는 개발 단계 산출물에서 확정합니다.
진승 연동 응답시간 · 재시도 정책
공인구 확인 연동의 세부 파라미터(응답시간 목표 · 재시도 · 폴백 조건)는 확정 대기입니다.
알림 · 결제 API의 세부 연동 규격
실시간 푸시 알림 발송 방식과 결제 수단별 상세 데이터 규격은 개발 단계에서 확정합니다.
본 문서는 초안(v0.3)이며 검수 대기 상태입니다. 본 문서는 논리 설계 개요이며, 물리 스키마 · 상세 API 규격은 개발 단계 산출물에서 제공됩니다.