arena/context/server.md

Context: Server & API

1. 모듈별 상세 역할

• server/index.js:
  • Fastify 서버 진입점입니다.
  • 개발 모드에서는 @fastify/middie로 Vite 미들웨어를 붙이고, /api/* 요청은 Vite SPA fallback이 가로채지 않도록 Fastify 라우트로 통과시킵니다.
  • 운영 모드(npm start)에서는 @fastify/static으로 dist/를 서빙하고, HTML 요청은 index.html로 fallback합니다.
• server/config.js:
  • config.json을 읽어 서버 포트, MongoDB host/port/db/user/pass, 쿠키 보안 옵션을 정규화합니다.
  • MONGODB_URI가 직접 있으면 우선 사용하고, 없으면 MONGODB_HOST/MONGODB_PORT 기반으로 URI를 조립합니다.
  • 전투 사망 통계 컬렉션(MONGODB_DAILY_DEATH_COLLECTION)과 집계 기준 타임존(DEATH_STATS_TIME_ZONE) 기본값을 제공합니다.
• server/db.js:
  • MongoClient를 한 번 생성한 뒤 재사용하여 MongoDB 커넥션 풀을 유지합니다.
  • 종료 시 closeMongoConnection()으로 커넥션을 닫습니다.
• server/deathStats.js:
  • GET /api/death-stats/today: DEATH_STATS_TIME_ZONE 기준 오늘 일자의 종족별 사망 집계와 총 사망 수를 반환합니다.
  • POST /api/death-stats/today: 전투 종료 시 전달된 deathsBySpecies를 오늘 일자별 누적 문서의 deathsBySpecies, totalDeaths, battles에 바로 더합니다.
  • 집계 대상 종족은 human, orc, skeleton, slime, wolf, bear로 제한합니다.
• server/visitors.js:
  • POST /api/visitors/check: arena_visitor_id HttpOnly 쿠키를 확인하고 없으면 UUID를 발급합니다.
  • MongoDB visitors 컬렉션에 _id = visitorId로 upsert해 방문자 1명당 1개 문서를 유지합니다.
  • GET /api/visitors/stats: 전체 유니크 방문자 수를 반환합니다.

2. 주요 로직 구현 세부 사항

유니크 방문자 체크

브라우저가 직접 MongoDB에 연결하지 않고, Fastify API가 MongoDB 커넥션 풀을 유지합니다.

1. 프론트엔드가 앱 로드 시 POST /api/visitors/check를 호출합니다.
2. 서버가 arena_visitor_id 쿠키를 검사합니다.
3. 쿠키가 없거나 유효하지 않으면 crypto.randomUUID()로 새 방문자 ID를 만들고 HttpOnly 쿠키로 내려줍니다.
4. MongoDB에는 _id, firstSeenAt, lastSeenAt, visits, firstUserAgent, lastUserAgent를 저장합니다.
5. countDocuments()로 전체 유니크 방문자 수를 계산해 반환합니다.

전투 사망 통계

프리뷰 전투는 통계에서 제외하고, 사용자가 시작한 실제 전투만 저장합니다.

1. fighterManifest.js의 모든 스킨은 species를 가집니다.
2. combat.js의 처치 흐름이 ArenaScene.recordKill()을 호출하면, ArenaScene은 피처치자의 skin.species를 현재 전투의 battleDeathCounts에 누적합니다.
3. 전투가 5초 이상 이어지면 GET /api/death-stats/today로 가져온 오늘 집계와 현재 전투의 사망 수를 합산해 #battle-notice에 표시합니다.
4. 전투 종료 시 POST /api/death-stats/today로 deathsBySpecies만 보냅니다.
5. 서버는 daily_death_stats 컬렉션에서 오늘 일자의 battles, totalDeaths, deathsBySpecies.* 값을 $inc로 갱신합니다.

3. 설정 규칙

• 서버 설정: .env 대신 config.json을 사용합니다. 로컬 전용 파일이며, 저장소에는 config.json.sample만 공유합니다.
• MongoDB 연결: 접속 정보는 config.json의 MONGODB_HOST, MONGODB_PORT, MONGODB_DB 등으로 관리합니다.
• API 변경: /api/* 경로는 Fastify 라우트가 담당하며, 개발 모드에서 Vite 미들웨어보다 우선순위를 가집니다.