[PR-9] hardening multiplayer logics

Author: bnbong

.gitignore

@@ -45,4 +45,10 @@ Thumbs.db
 ingame_base.png
 
 # Logs
-*.log
+*.log
+
+# DB
+*.db
+
+# env
+.env

backend/app/api/me.py

@@ -11,8 +11,16 @@
 from app.database import get_db
 from app.dependencies import get_current_user, require_registered
 from app.models.db import User
-from app.repositories import collection_repo
+from app.repositories import collection_repo, profile_repo
 from app.schemas.profile import CollectionEntry, CollectionResponse, ProfileResponse
+from app.schemas.progress import (
+    CollectionUnlockRequest,
+    CollectionUnlockResponse,
+    CurrencyUpdateRequest,
+    CurrencyUpdateResponse,
+    ProgressMergeRequest,
+    ProgressMergeResponse,
+)
 
 router = APIRouter(prefix="/me", tags=["me"])
 
@@ -58,3 +66,82 @@ def get_collection(
         for row in rows
     ]
     return CollectionResponse(items=items, total=len(items))
+
+
+@router.post("/progress/merge", response_model=ProgressMergeResponse)
+def merge_progress(
+    req: ProgressMergeRequest,
+    user: User = Depends(require_registered),
+    db: Session = Depends(get_db),
+) -> ProgressMergeResponse:
+    """
+    Merge local single-player progress into the registered server account.
+
+    Merge strategy is intentionally conservative for beta:
+      - currency keeps the larger of {server, local}
+      - collection becomes the union of {server, local}
+
+    This protects the common "old local save + new online account" case
+    without forcing the client to reconcile multiple sources first.
+    """
+    current_rows = collection_repo.get_for_user(db, user.id)
+    current_ids = {row.soldier_id for row in current_rows}
+    merged_ids = current_ids | set(req.collected_soldier_ids)
+
+    for soldier_id in sorted(merged_ids - current_ids):
+        collection_repo.add_soldier(
+            db,
+            user.id,
+            soldier_id,
+            source="client_merge",
+        )
+
+    merged_currency = max(user.profile.currency, req.currency)
+    if user.profile.currency != merged_currency:
+        profile_repo.set_currency(db, user.profile, merged_currency)
+
+    return ProgressMergeResponse(
+        currency=merged_currency,
+        collected_soldier_ids=sorted(merged_ids),
+        total_collected=len(merged_ids),
+    )
+
+
+@router.put("/currency", response_model=CurrencyUpdateResponse)
+def update_currency(
+    req: CurrencyUpdateRequest,
+    user: User = Depends(require_registered),
+    db: Session = Depends(get_db),
+) -> CurrencyUpdateResponse:
+    """
+    Persist the exact wallet amount for the authenticated registered user.
+    """
+    profile_repo.set_currency(db, user.profile, req.currency)
+    return CurrencyUpdateResponse(currency=req.currency)
+
+
+@router.post("/collection/unlock", response_model=CollectionUnlockResponse)
+def unlock_collection_entry(
+    req: CollectionUnlockRequest,
+    user: User = Depends(require_registered),
+    db: Session = Depends(get_db),
+) -> CollectionUnlockResponse:
+    """
+    Idempotently unlock a collected soldier for the authenticated user.
+    """
+    added = False
+    if not collection_repo.has_soldier(db, user.id, req.soldier_id):
+        collection_repo.add_soldier(
+            db,
+            user.id,
+            req.soldier_id,
+            source="client_unlock",
+        )
+        added = True
+
+    total = len(collection_repo.get_for_user(db, user.id))
+    return CollectionUnlockResponse(
+        soldier_id=req.soldier_id,
+        added=added,
+        total_collected=total,
+    )

backend/app/config.py

@@ -44,6 +44,7 @@ class Settings(BaseSettings):
     #   select a card before auto-playing with bot logic.
     RECONNECT_GRACE_SECONDS: int = 45
     CARD_SELECTION_TIMEOUT_SECONDS: int = 30
+    ROUND_SETTLEMENT_TIMEOUT_SECONDS: int = 8
 
     # Quick-match matchmaking (PR-06).
     # QUICK_MATCH_FILL_SECONDS: how long to wait for a full 4-player lobby

backend/app/logging_config.py

@@ -70,9 +70,12 @@ class _JsonFormatter(logging.Formatter):
 
     def format(self, record: logging.LogRecord) -> str:
         record.message = record.getMessage()
-        ts = datetime.fromtimestamp(record.created, tz=timezone.utc).strftime(
-            "%Y-%m-%dT%H:%M:%S.%f"
-        )[:-3] + "Z"
+        ts = (
+            datetime.fromtimestamp(record.created, tz=timezone.utc).strftime(
+                "%Y-%m-%dT%H:%M:%S.%f"
+            )[:-3]
+            + "Z"
+        )
 
         payload: dict[str, Any] = {
             "ts": ts,

backend/app/models/match.py

@@ -60,6 +60,7 @@ class TurnStep:
     penalty_score: int
     had_to_take_row: bool
     order: int  # 1-based placement order
+    penalty_card_count: int = 0  # number of penalty cards taken in this placement
 
 
 @dataclass
@@ -99,3 +100,13 @@ class ActiveMatch:
     # Determines whether MMR updates are applied after the game ends.
     # Custom-room matches always have is_ranked=False.
     is_ranked: bool = False
+
+    # Round-settlement coordination (client result screen before continuing).
+    round_settlement_pending: bool = False
+    round_settlement_ready_seats: set[int] = field(default_factory=set)
+    round_summary_pending: Optional[RoundSummary] = None
+
+    # Seats that voluntarily left mid-match (MATCH_LEAVE).
+    # They are converted to bot immediately but marked as eliminated
+    # at the end of the current round in finalize_round().
+    voluntarily_left_seats: set[int] = field(default_factory=set)

backend/app/models/room.py

@@ -31,6 +31,7 @@ class RoomParticipant:
     display_name: str
     controller_type: SeatControllerType
     is_ready: bool = False
+    account_type: str = "guest"  # "registered" | "guest" | "bot"
     user_id: Optional[str] = None  # None for guests and bots
     connection_id: Optional[str] = None  # None for bots
 

backend/app/repositories/profile_repo.py

@@ -0,0 +1,22 @@
+"""
+Database operations for Profile rows.
+"""
+
+from datetime import datetime, timezone
+
+from sqlalchemy.orm import Session
+
+from app.models.db import Profile
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc).replace(tzinfo=None)
+
+
+def set_currency(db: Session, profile: Profile, currency: int) -> Profile:
+    """Persist the exact wallet amount for the profile."""
+    profile.currency = currency
+    profile.updated_at = _utcnow()
+    db.commit()
+    db.refresh(profile)
+    return profile

backend/app/schemas/progress.py

@@ -0,0 +1,39 @@
+"""
+Schemas for client progress synchronisation.
+
+These endpoints are intentionally narrow:
+  - initial merge of local single-player progress into a registered account
+  - exact currency updates after in-game earn/spend events
+  - idempotent soldier unlock writes
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ProgressMergeRequest(BaseModel):
+    currency: int = Field(ge=0)
+    collected_soldier_ids: list[int] = Field(default_factory=list)
+
+
+class ProgressMergeResponse(BaseModel):
+    currency: int
+    collected_soldier_ids: list[int]
+    total_collected: int
+
+
+class CurrencyUpdateRequest(BaseModel):
+    currency: int = Field(ge=0)
+
+
+class CurrencyUpdateResponse(BaseModel):
+    currency: int
+
+
+class CollectionUnlockRequest(BaseModel):
+    soldier_id: int = Field(ge=1)
+
+
+class CollectionUnlockResponse(BaseModel):
+    soldier_id: int
+    added: bool
+    total_collected: int

backend/app/services/match_service.py

@@ -79,14 +79,7 @@ def create_match(self, room: Room) -> ActiveMatch:
 
             ai_ctrl: Optional[AIPlayer] = AIPlayer(player) if is_bot else None
 
-            # Derive account_type from the seat's identity:
-            # bots are "bot"; registered users have a user_id; guests do not.
-            if is_bot:
-                account_type = "bot"
-            elif participant.user_id is not None:
-                account_type = "registered"
-            else:
-                account_type = "guest"
+            account_type = participant.account_type if not is_bot else "bot"
 
             seats[seat_idx] = MatchSeat(
                 seat_index=seat_idx,
@@ -146,6 +139,47 @@ def start_next_round(self, match: ActiveMatch) -> None:
         """Start the next round (used after ROUND_RESULT is broadcast)."""
         self._start_round(match)
 
+    def begin_round_settlement(self, match: ActiveMatch, summary: RoundSummary) -> None:
+        """Mark the match as waiting on the round-settlement screen."""
+        match.round_settlement_pending = True
+        match.round_settlement_ready_seats.clear()
+        match.round_summary_pending = summary
+
+    def has_round_settlement_pending(self, match: ActiveMatch) -> bool:
+        return match.round_settlement_pending and match.round_summary_pending is not None
+
+    def mark_round_ready(self, match: ActiveMatch, seat_index: int) -> bool:
+        """
+        Record one human seat's acknowledgement of the round-settlement screen.
+
+        Returns True once every human seat still controlled by a REMOTE player
+        has acknowledged.
+        """
+        if not self.has_round_settlement_pending(match):
+            raise MatchError("Round settlement is not active")
+
+        seat = match.seats.get(seat_index)
+        if seat is None:
+            raise MatchError(f"Seat {seat_index} not found in match")
+        if seat.controller_type != SeatControllerType.REMOTE:
+            raise MatchError("Only human (REMOTE) seats can acknowledge settlement")
+
+        match.round_settlement_ready_seats.add(seat_index)
+        required = {
+            s.seat_index
+            for s in match.seats.values()
+            if s.controller_type == SeatControllerType.REMOTE and not s.player.is_eliminated  # type: ignore[union-attr]
+        }
+        return required.issubset(match.round_settlement_ready_seats)
+
+    def clear_round_settlement(self, match: ActiveMatch) -> Optional[RoundSummary]:
+        """Clear the active round-settlement state and return its summary."""
+        summary = match.round_summary_pending
+        match.round_settlement_pending = False
+        match.round_settlement_ready_seats.clear()
+        match.round_summary_pending = None
+        return summary
+
     def reselect_bots(self, match: ActiveMatch) -> None:
         """
         Auto-select cards for all non-eliminated bot seats.
@@ -287,6 +321,7 @@ def resolve_turn_stepwise(
                 penalty_score=placement.penalty_score,
                 had_to_take_row=placement.had_to_take_row,
                 order=order_idx + 1,
+                penalty_card_count=len(placement.penalty_cards),
             )
             accumulated.append(step)
             # Temporarily set last_turn_steps so build_public_state reflects
@@ -307,12 +342,36 @@ def finalize_round(self, match: ActiveMatch) -> RoundSummary:
         Commit round scores and determine if the game is over.
 
         Must be called after resolve_turn() confirms is_round_over().
+        Players who voluntarily left mid-match are force-eliminated here.
         """
         rules: GameRules = match.rules  # type: ignore[assignment]
 
+        # Force-eliminate players who left voluntarily during this round.
+        for seat_idx in match.voluntarily_left_seats:
+            seat = match.seats.get(seat_idx)
+            if seat is not None and not seat.player.is_eliminated:  # type: ignore[union-attr]
+                seat.player.is_eliminated = True  # type: ignore[union-attr]
+        match.voluntarily_left_seats.clear()
+
+        # Sole-survivor check: if only one active player remains after
+        # voluntary eliminations, declare them the winner immediately
+        # — their score doesn't matter (they outlasted everyone else).
+        active_before_commit = [p for p in rules.players if not p.is_eliminated]
+        sole_survivor_win = len(active_before_commit) == 1
+
         # {player_id: (round_danger, new_total)}
         score_results = rules.commit_round_scores()
 
+        # Override game-end result for the sole-survivor case: the last
+        # remaining player wins even if commit_round_scores() would have
+        # eliminated them for exceeding 66 danger.
+        if sole_survivor_win:
+            survivor = active_before_commit[0]
+            rules.game_over = True
+            rules.winner = survivor
+            # Undo the elimination that commit_round_scores may have set.
+            survivor.is_eliminated = False
+
         round_danger: dict[int, int] = {}
         total_scores: dict[int, int] = {}
         for player_id, (rd, total) in score_results.items():
@@ -438,6 +497,7 @@ def build_private_state(self, match: ActiveMatch, seat_index: int) -> PrivatePla
             seat_index=seat_index,
             hand=hand,
             has_selected=seat.player.selected_card is not None,  # type: ignore[union-attr]
+            is_eliminated=seat.player.is_eliminated,  # type: ignore[union-attr]
         )
 
     # ------------------------------------------------------------------

backend/app/services/matchmaking_service.py

@@ -202,6 +202,7 @@ def build_quick_match_room(
                 display_name=entry.display_name,
                 controller_type=SeatControllerType.REMOTE,
                 is_ready=True,
+                account_type=entry.account_type,
                 user_id=entry.user_id,
                 connection_id=entry.connection_id,
             )
@@ -213,6 +214,7 @@ def build_quick_match_room(
                 display_name=f"AI Bot {seat_idx + 1}",
                 controller_type=SeatControllerType.BOT,
                 is_ready=True,
+                account_type="bot",
                 user_id=None,
                 connection_id=None,
             )