Skip to content

spec.md

Latest commit

 

History

History
135 lines (100 loc) · 6.38 KB

spec.md

File metadata and controls

135 lines (100 loc) · 6.38 KB

선수 타율 예측 웹 페이지 명세서 (Draft)

상태: Draft 마지막 업데이트: 2025-08-18 문서 소유자: (이름/닉네임)

1. 개요

  • 문제 정의: 사용자가 선수 이름을 입력하면 현재 시즌 기록을 기준으로 시즌 최종 타율(AVG)을 예측
  • 제품 목표: (예: 간단하고 신뢰 가능한 타율 예측 제공)
  • 주요 사용자: (예: 야구 팬, 기자, 판타지 베이스볼 유저 등)
  • 성공 지표: (예: 월간 활성 사용자, 예측 클릭수, 예측 정확도 등)

2. 범위

  • 포함: KBO 리그, 시즌 최종 타율(AVG) 예측, 타격 지표 중심
  • 제외: MLB/기타 리그, 수비/주루 지표 예측, 투수 지표, 단일 경기 단기 예측

3. 사용자 시나리오(Persona & User Stories)

  • Persona-1: (설명)
    • User Story: "(누구로서) (무엇)을 하고 싶다, 그래서 (가치)"
  • Persona-2: (설명)
    • User Story: ...

4. 기능 요구사항 (Functional Requirements)

  • FR-1: 초기 화면에서 선수 입력창 표시, 입력창 오른쪽에 확인 버튼 배치
  • FR-2: 확인 버튼 클릭 시, 선수의 “당일 기준” 필수 컬럼을 즉시 하단에 표시
  • FR-3: 동시에 현재까지의 기록을 바탕으로 팀 기준 144경기 완료 시점의 시즌 최종 타율(AVG) 예측 표시
  • FR-4: 단일 페이지로 동작(페이지 전환 없음)
  • FR-5: 데이터는 내부 JSON 파일로 제공/사용(외부 API 호출 없음)
  • FR-6: 구현은 순수 HTML/CSS/JS로 작성(프레임워크 미사용)
  • FR-7: Chrome 브라우저 최적화(최소 지원 버전 TBD)
  • FR-8: 다국어/한국어 우선

초보자 메모: 자동완성은 제외합니다. 선수 ID 또는 정확한 이름을 입력한 뒤 확인 버튼을 누르면 결과가 나타납니다.

세부 동작 규칙(TBD): 입력 유효성, 예외 처리, 로딩/에러 상태, 캐싱 정책 등

5. 비기능 요구사항 (Non-Functional Requirements)

  • 성능: (예: p95 응답 < 500ms, 오토완성 < 200ms)
  • 가용성: (예: 99.9%/월)
  • 보안/개인정보: (예: API 키 관리, 로그 마스킹)
  • 확장성: (예: 선수/리그 확장 용이)
  • 접근성: (예: 키보드 네비게이션, 명도 대비)
  • 브라우저 호환성: Chrome 우선 최적화(기타 브라우저는 비보장)

6. 데이터 & 지표 정의

  • 데이터 소스: 내부 JSON 데이터(빌드/배치 시 생성), 필요 시 KBO 공개 페이지 크롤링으로 갱신
  • 필수 컬럼: (선수ID, 이름, 시즌, PA, AB, H, 2B, 3B, HR, BB, SO, BABIP, wOBA, 등)
  • 데이터 신선도: 매일(자정 기준)
  • 품질 규칙: (결측치 처리, 이상치 제거)
  • 선수 목록 검증: KBO 로스터 사용(최신 시즌 기준, 필요 시 과거 선수 병합 옵션)
  • 초보자 메모: "선수ID"는 중복 없는 고유 값입니다. 이름이 같을 수 있어도 ID는 다릅니다.
  • 당일 기준 기록 정의: KST(UTC+9) 자정 이후 수집된 최신 스냅샷을 “당일”로 간주
  • 예측 정의(144경기 기준): 현재까지의 누적 스탯을 바탕으로 시즌 최종 타율(AVG)을 추정
    • 베이스라인: 현재 AVG를 시즌 최종 AVG의 점 추정으로 사용(초기버전)
    • 확장: 이후 95% CI 추가(표준 오차 근사 또는 베이지안 베타-바이노미얼)

7. 모델 설계(ML/통계)

  • 문제 유형: 회귀 (타율 = H/AB 예측) 또는 변형(로지스틱/베이지안 등)
  • 후보 접근: {{ ... }}
  • 평가 지표: MAE/RMSE, MAPE, 스피어만 상관 등
  • 검증전략: (k-겹, 시계열 분리, 최근 시즌 홀드아웃)
  • 운영 전략: 모델 재학습 주기, 모델 모니터링(드리프트)

8. 시스템 아키텍처

  • 클라이언트: 단일 페이지(Static) - 순수 HTML/CSS/JS
  • 서버/API: 초기 버전은 별도 서버 없음(정적 호스팅). 데이터는 내부 JSON 파일로 로드
  • 모델 서빙: 클라이언트 측 계산(간단 추정). 고도화 시 별도 서비스 고려
  • 저장소: 내부 JSON/정적 파일. 배치로 생성(원천은 KBO 페이지 크롤링/정리)
  • 배포: 정적 호스팅(Netlify/GitHub Pages/CloudFront 등)
  • 관측성: (간단 로그/웹 분석)
  • 초보자 메모: 서버 없이 파일만 배포해도 동작합니다(크롬에서 테스트 권장).

9. UI/UX 요구사항

  • 핵심 화면:
    • 홈: 상단 입력창 + 오른쪽 확인 버튼(인라인)
  • 결과 섹션: 입력 영역 바로 아래에 “당일 기준 필수 컬럼” 표 형태로 표시
  • 예측 섹션: 결과 섹션 하단에 “144경기 기준 시즌 최종 타율(AVG) 예측” 카드 표시
  • 비교 화면(선택): 두 선수 나란히(추후)
  • 컴포넌트: 검색바, 결과 카드, 로딩 스켈레톤, 에러 토스트
  • 디자인 가이드: (폰트, 컬러, 반응형 그리드)
  • 접근성 체크리스트: (키보드 포커스, ARIA 레이블)

10. API 명세(초안)

  • 초기 버전: 별도 서버 API 없음. 정적 JSON 파일을 fetch하여 클라이언트에서 처리
    • 데이터 파일 예시: /data/players.json, /data/stats_YYYYMMDD.json
    • 요청 파라미터: 없음(클라이언트 단에서 입력값에 따라 필터링)
    • 응답 형식: JSON 스키마는 ## 11. 데이터 스키마 참조

향후 서버/API가 필요할 때 이전 초안을 참조하여 재도입(예: /api/players/{id}, /api/players/{id}/predict).

인증/요금제/레이트리밋: (내부/공개 선택 후 정의)

11. 데이터 스키마(초안)

{{ ... }}

  • M3: 베이스라인 모델
  • M4: UI 프로토타입
  • M5: 통합/배포

16. 수용 기준(Acceptance Criteria)

  • 사용자는 사이트 접속 시 입력창과 오른쪽 확인 버튼을 볼 수 있다
  • 사용자가 선수 ID 또는 정확한 이름을 입력하고 확인을 누르면, “당일 기준” 필수 컬럼이 바로 아래에 표시된다(1.5초 내)
  • 동시에 “144경기 기준 시즌 최종 타율(AVG)” 예측 카드가 표시된다(1.5초 내)
  • 데이터 최신성은 매일 자정(KST) 기준으로 보장된다
  • 문서화/스펙 완비(초보자도 이해 가능한 설명 포함)

17. 오픈 이슈/결정 필요 사항

  • 리그 범위(KBO/MLB/둘 다?)
  • 예측 목표(시즌 전체/남은 경기/다음 경기?) {{ ... }}
  • 데이터 출처 및 라이선스

18. 변경 이력(Change Log)

  • v0.1 (초안): 구조 생성, 항목 템플릿 배치

부록 A. 용어집(Glossary)

  • 타율(AVG) = H/AB
  • (추가 용어)