Add multiplayer system, backend server, CI/CD pipeline

[bnbong]

Summary

실시간 멀티플레이 시스템을 추가합니다. 백엔드 서버, 클라이언트 네트워크 계층, CI/CD 파이프라인을 모두 포함합니다.

Backend Server (backend/)

• FastAPI + WebSocket 기반 실시간 게임 서버
• 인증: JWT 기반 등록 유저 + 게스트 로그인
• 방 시스템: 방 생성/참가/퇴장, 준비 상태, 매치 시작
• 서버 권위적 매치 엔진: GameRules 기반 턴 처리, 라운드 정산, 탈락/승리 판정
• 빠른 대전 (Quick Match): MMR 기반 매칭(내부 지표용으로 사용, beta 단계에서는 유저에게 보여지는 지표가 아님), 대기 시간 초과 시 봇 채움
• 재접속: 등록 유저 한정, 동일 라운드 내, grace timer 기반
• 감정 표현 (Emote): 쿨다운 + 버스트 캡 레이트 리밋
• 신고 시스템: 유저 신고 접수 및 관리자 조회
• 관리자 API: 서버 상태 조회, 유저 관리, 매치 강제 종료
• 구조화 로깅: JSON 형식, 레벨별 분류

Multiplayer Hardening (PR-9)

• 게임 나가기: 활성 플레이어는 수당 미획득 경고 후 조기 퇴장, 관전자는 간단 확인 후 퇴장
• 봇 전환 + 탈락 처리: 나가기/연결 끊김 시 봇 전환 후 라운드 종료 시 탈락 처리
• 단독 생존자 자동 승리: 다른 모든 플레이어가 나간 경우, 남은 1명은 66점 초과해도 승리
• 빠른 대전 매칭 수정: 클라이언트 MATCH_START 핸들러 누락 버그 수정

Client Networking (src/fall_in/net/, src/fall_in/multiplayer/)

• WebSocket 클라이언트: asyncio 기반, heartbeat, 자동 재연결
• RemoteGameAdapter: 서버 상태 스냅샷 캐싱, GameScene에 주입
• LocalGameAdapter: 싱글플레이 GameRules 래핑, 동일 인터페이스 제공
• 상태 직렬화/역직렬화: PublicMatchState, PrivatePlayerState 변환

New Scenes

• AccountGateScene: 로그인/게스트 진입 화면
• GameModeSelectScene: 싱글/멀티 모드 선택
• MultiplayerMenuScene: 방 만들기/참가/빠른 대전 메뉴
• RoomLobbyScene: 대기실 UI, 준비 상태, 매치 시작

Server Optimization & Infrastructure

• CORS 미들웨어: 게임 클라이언트(데스크톱, 웹) 접근 허용
• /healthz 개선: DB 연결 상태 확인 포함
• DB 커넥션 풀: pool_pre_ping, pool_size, pool_timeout 설정
• MMR 업데이트 예외 처리: DB 실패 시 로깅 추가 (기존: 조용한 유실)
• 재접속 실패 구조화 로깅: 모든 실패 경로에 로그 추가
• EmoteService 메모리 누수 수정: 연결 종료 시 rate-limit 상태 정리
• Dockerfile: 멀티스테이지 빌드, ARM64 호환, uv 기반
• Backend CI (backend-test.yaml): backend/ 변경 시 ruff + pytest
• 배포 워크플로우 (deploy-backend.yaml): SSH → rsync → Docker build → health check

Tests

• Backend: 321 tests (auth, room, match, reconnect, matchmaking, emote, report, collection, nickname)
• Client: 148 tests (rules regression, adapters, state projection, scene integration)

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds a full real-time multiplayer stack (backend + client networking/UI) with supporting infrastructure for local beta and automated CI/CD.

Changes:

• Implemented FastAPI WebSocket backend with auth, rooms, matchmaking, presence/reconnect, emotes, reports/admin, and DB migrations/tests.
• Added client networking layer (WS client, serializers/projection) plus new multiplayer scenes and UI popups.
• Introduced CI workflows and a Docker-based deployment pipeline for the backend.

Reviewed changes

Copilot reviewed 92 out of 106 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
tests/multiplayer/test_account_entry_flow.py	Adds regression coverage for intro → account gate transition.
src/fall_in/ui/settings_popup.py	Adds “exit match” UX + confirmation state to settings modal.
src/fall_in/ui/emote_popup.py	Introduces client-side emote palette UI with optional asset fallback.
src/fall_in/scenes/title_scene.py	Routes “start game” into mode selection scene.
src/fall_in/scenes/room_lobby_scene.py	Adds multiplayer lobby scene with room state + match start bootstrap.
src/fall_in/scenes/result_scene.py	Extends result scene to support remote (server-authoritative) round settlement flow.
src/fall_in/scenes/intro_cutscene_scene.py	Updates intro transition target to account gate.
src/fall_in/scenes/game_over_scene.py	Adds early-exit game-over path (no rewards/medals).
src/fall_in/scenes/game_mode_select_scene.py	Adds single vs multi selection UX and navigation.
src/fall_in/net/ws_client.py	Adds threaded asyncio WebSocket client for pygame main loop integration.
src/fall_in/net/state_projection.py	Adds pure functions for client-side cosmetic projection of public card state.
src/fall_in/net/serializers.py	Adds wire-safe serializers enforcing “no private card fields” boundary.
src/fall_in/net/messages.py	Adds protocol message type enums for client/server.
src/fall_in/net/backend_api.py	Adds minimal REST helpers for profile/progress sync.
src/fall_in/net/init.py	Documents package purpose/contracts.
src/fall_in/multiplayer/models.py	Adds multiplayer DTOs (public/private state, seat identity, public card DTO).
src/fall_in/multiplayer/local_adapter.py	Adds single-player adapter that exposes a multiplayer-like snapshot API.
src/fall_in/multiplayer/bootstrap.py	Adds shared bootstrap to wire WS → RemoteGameAdapter → GameScene.
src/fall_in/multiplayer/init.py	Documents multiplayer adapter/model package.
src/fall_in/data/soldier_data.py	Adds replace snapshot + triggers registered sync after local collection unlock.
src/fall_in/core/rules.py	Adds human_seat to support multiplayer game-over semantics.
src/fall_in/core/game_manager.py	Adds auth/progress state, progress sync helpers, and reconnect token persistence.
pyproject.toml	Adds runtime dependency for client WebSocket transport.
docs/local-beta-setup.md	Adds local backend setup and smoke-test guide for beta operations.
backend/tests/test_nickname.py	Adds unit/integration tests for nickname policy.
backend/tests/conftest.py	Adds isolated DB + singleton reset fixtures for backend test stability.
backend/pyproject.toml	Adds backend packaging + dev/prod deps + pytest/ruff config.
backend/migrations/versions/002_add_reports.py	Adds reports table migration.
backend/migrations/versions/001_initial_schema.py	Adds initial users/profiles/collection schema migration.
backend/migrations/script.py.mako	Adds Alembic template for new migrations.
backend/migrations/env.py	Adds Alembic environment loading DATABASE_URL from app settings.
backend/app/ws/session.py	Adds per-connection WS session state.
backend/app/ws/presence.py	Adds reconnect tokens + grace/selection/settlement timers.
backend/app/ws/endpoint.py	Adds WS endpoint with heartbeat and match-aware disconnect handling.
backend/app/ws/connection_manager.py	Adds in-memory connection + room membership tracking for WS fanout.
backend/app/services/room_service.py	Adds room lifecycle/ready/start/reconnect/bot-takeover sync logic.
backend/app/services/report_service.py	Adds report validation + dedup + structured logging.
backend/app/services/nickname_service.py	Adds nickname normalization/validation logic.
backend/app/services/mmr_service.py	Adds hidden MMR bucket mapping + delta persistence rules.
backend/app/services/matchmaking_service.py	Adds quick-match queue + fill timer (AI fallback) scaffolding.
backend/app/services/emote_service.py	Adds emote catalog validation + per-connection rate limiting.
backend/app/services/auth_service.py	Adds centralized email/password authentication logic.
backend/app/schemas/progress.py	Adds progress/currency/collection request/response schemas.
backend/app/schemas/profile.py	Adds profile + collection response schemas (MMR excluded).
backend/app/schemas/auth.py	Adds auth request/response schemas with nickname validation hook.
backend/app/repositories/user_repo.py	Adds user/profile persistence helpers (registered + guest).
backend/app/repositories/room_repo.py	Adds in-memory room storage + code generation.
backend/app/repositories/report_repo.py	Adds report CRUD + filtering + dedup query.
backend/app/repositories/reconnect_repo.py	Adds reconnect token store (in-mem + optional Redis).
backend/app/repositories/queue_repo.py	Adds quick-match queue store (in-mem + optional Redis).
backend/app/repositories/profile_repo.py	Adds currency persistence helper.
backend/app/repositories/match_repo.py	Adds in-memory active match store with room secondary index.
backend/app/repositories/collection_repo.py	Adds user_collection persistence helpers.
backend/app/models/room.py	Adds in-memory room datamodel + wire dict representation.
backend/app/models/match.py	Adds active match/seat/turn/round summary models.
backend/app/models/db.py	Adds SQLAlchemy ORM models + enums for auth/progress/reporting.
backend/app/main.py	Adds FastAPI app, CORS, routers, and health/version endpoints.
backend/app/logging_config.py	Adds JSON structured logging formatter/configuration.
backend/app/dependencies.py	Adds JWT auth dependencies + “require registered” guard.
backend/app/database.py	Adds DB engine/session/base + get_db dependency with rollback handling.
backend/app/config.py	Adds env-driven settings for JWT, WS, matchmaking, emotes, ops, CORS.
backend/app/auth/password.py	Adds bcrypt hashing/verification helpers.
backend/app/auth/jwt.py	Adds JWT creation/verification helpers for access/refresh/guest tokens.
backend/app/api/report.py	Adds authenticated report submission endpoint.
backend/app/api/me.py	Adds profile/collection/progress merge/currency/collection unlock endpoints.
backend/app/api/auth.py	Adds register/login/guest/refresh/logout endpoints.
backend/app/api/admin.py	Adds static-token admin endpoints for report review flow.
backend/app/init.py	Marks backend package.
backend/alembic.ini	Adds Alembic config (DB URL sourced from settings).
backend/Dockerfile	Adds multi-stage build and container entrypoint for migrations + uvicorn.
backend/.env.example	Adds documented environment template for local dev/beta.
backend/.dockerignore	Adds docker ignore rules to reduce build context.
.github/workflows/deploy-backend.yaml	Adds backend deploy pipeline (test → rsync → docker build/run → healthcheck).
.github/workflows/backend-test.yaml	Adds backend PR/push CI (ruff + pytest w/ coverage).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 113 changed files in this pull request and generated 9 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 98 out of 113 changed files in this pull request and generated 10 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.