hockey-blast-common-lib 0.1.65__py3-none-any.whl → 0.1.67__py3-none-any.whl

hockey_blast_common_lib/aggregate_team_skater_stats.py

@@ -0,0 +1,313 @@
+"""
+Aggregate skater statistics by team.
+
+This module aggregates player statistics for each team, counting only games
+where the player was on that specific team (using GameRoster.team_id).
+
+Key difference from regular aggregation:
+- Aggregates by (aggregation_id, team_id, human_id) instead of just (aggregation_id, human_id)
+- Filters to only games where GameRoster.team_id matches the target team
+- Stores results in OrgStatsSkaterTeam / DivisionStatsSkaterTeam
+
+"""
+import os
+import sys
+
+sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from datetime import datetime
+
+import sqlalchemy
+from sqlalchemy import and_, case, func
+
+from hockey_blast_common_lib.db_connection import create_session
+from hockey_blast_common_lib.models import (
+    Division,
+    Game,
+    GameRoster,
+    Goal,
+    Human,
+    Organization,
+    Penalty,
+    Team,
+)
+from hockey_blast_common_lib.options import (
+    MIN_GAMES_FOR_DIVISION_STATS,
+    MIN_GAMES_FOR_ORG_STATS,
+)
+from hockey_blast_common_lib.progress_utils import create_progress_tracker
+from hockey_blast_common_lib.stats_models import (
+    DivisionStatsSkaterTeam,
+    OrgStatsSkaterTeam,
+)
+from hockey_blast_common_lib.utils import (
+    calculate_percentile_value,
+    get_non_human_ids,
+    get_percentile_human,
+)
+
+# Import status constants for game filtering
+FINAL_STATUS = "Final"
+FINAL_SO_STATUS = "Final(SO)"
+FORFEIT_STATUS = "FORFEIT"
+NOEVENTS_STATUS = "NOEVENTS"
+
+
+def aggregate_team_skater_stats(session, aggregation_type, aggregation_id):
+    """
+    Aggregate skater stats by team for an organization or division.
+
+    For each team in the aggregation scope, calculates stats for all players
+    who played for that team, counting only games where they were on that team.
+
+    Args:
+        session: Database session
+        aggregation_type: "org" or "division"
+        aggregation_id: ID of the organization or division
+    """
+    # Capture start time for aggregation tracking
+    aggregation_start_time = datetime.utcnow()
+
+    human_ids_to_filter = get_non_human_ids(session)
+
+    # Determine aggregation details
+    if aggregation_type == "org":
+        StatsModel = OrgStatsSkaterTeam
+        min_games = MIN_GAMES_FOR_ORG_STATS
+        aggregation_name = (
+            session.query(Organization)
+            .filter(Organization.id == aggregation_id)
+            .first()
+            .organization_name
+        )
+        filter_condition = Game.org_id == aggregation_id
+    elif aggregation_type == "division":
+        StatsModel = DivisionStatsSkaterTeam
+        min_games = MIN_GAMES_FOR_DIVISION_STATS
+        aggregation_name = (
+            session.query(Division).filter(Division.id == aggregation_id).first().level
+        )
+        filter_condition = Game.division_id == aggregation_id
+    else:
+        raise ValueError(f"Invalid aggregation type: {aggregation_type}")
+
+    print(f"Aggregating team skater stats for {aggregation_name}...")
+
+    # Delete existing stats for this aggregation
+    session.query(StatsModel).filter(StatsModel.aggregation_id == aggregation_id).delete()
+    session.commit()
+
+    # Get all teams in this aggregation scope
+    if aggregation_type == "org":
+        teams_query = (
+            session.query(Team.id, Team.name)
+            .join(Game, (Game.home_team_id == Team.id) | (Game.visitor_team_id == Team.id))
+            .filter(Game.org_id == aggregation_id)
+            .distinct()
+        )
+    else:  # division
+        teams_query = (
+            session.query(Team.id, Team.name)
+            .join(Game, (Game.home_team_id == Team.id) | (Game.visitor_team_id == Team.id))
+            .filter(Game.division_id == aggregation_id)
+            .distinct()
+        )
+
+    teams = teams_query.all()
+    print(f"Found {len(teams)} teams in {aggregation_name}")
+
+    # Process each team
+    progress = create_progress_tracker(len(teams), description="Processing teams")
+    for team_id, team_name in teams:
+        progress.update(1)
+
+        # Aggregate stats for this team
+        # Filter to only games where players were on THIS team
+        games_played_query = (
+            session.query(
+                GameRoster.human_id,
+                func.count(Game.id).label("games_played"),
+                func.count(Game.id).label("games_participated"),
+                func.count(Game.id).label("games_with_stats"),
+                func.array_agg(Game.id).label("game_ids"),
+            )
+            .join(Game, Game.id == GameRoster.game_id)
+            .filter(
+                GameRoster.team_id == team_id,  # KEY: Filter by team
+                ~GameRoster.role.ilike("g"),  # Exclude goalies
+                GameRoster.human_id.notin_(human_ids_to_filter),
+                Game.status.in_([FINAL_STATUS, FINAL_SO_STATUS, FORFEIT_STATUS, NOEVENTS_STATUS]),
+                filter_condition,  # org_id or division_id filter
+            )
+            .group_by(GameRoster.human_id)
+            .having(func.count(Game.id) >= min_games)
+        )
+
+        games_played_data = games_played_query.all()
+        if not games_played_data:
+            continue  # No players met minimum games for this team
+
+        # Create stats dictionary
+        stats_dict = {}
+        for row in games_played_data:
+            stats_dict[row.human_id] = {
+                "games_played": row.games_played,
+                "games_participated": row.games_participated,
+                "games_with_stats": row.games_with_stats,
+                "game_ids": row.game_ids,
+                "first_game_id": row.game_ids[0] if row.game_ids else None,
+                "last_game_id": row.game_ids[-1] if row.game_ids else None,
+            }
+
+        # Aggregate goals, assists, points
+        goals_assists_query = (
+            session.query(
+                GameRoster.human_id,
+                func.count(func.distinct(case((Goal.goal_scorer_id == GameRoster.human_id, Goal.id)))).label("goals"),
+                func.count(
+                    func.distinct(
+                        case(
+                            (
+                                (Goal.assist_1_id == GameRoster.human_id) | (Goal.assist_2_id == GameRoster.human_id),
+                                Goal.id,
+                            )
+                        )
+                    )
+                ).label("assists"),
+            )
+            .join(Game, Game.id == GameRoster.game_id)
+            .outerjoin(Goal, Game.id == Goal.game_id)
+            .filter(
+                GameRoster.team_id == team_id,  # KEY: Filter by team
+                ~GameRoster.role.ilike("g"),
+                GameRoster.human_id.in_(stats_dict.keys()),
+                Game.status.in_([FINAL_STATUS, FINAL_SO_STATUS]),
+                filter_condition,
+            )
+            .group_by(GameRoster.human_id)
+        )
+
+        for row in goals_assists_query.all():
+            if row.human_id in stats_dict:
+                stats_dict[row.human_id]["goals"] = row.goals
+                stats_dict[row.human_id]["assists"] = row.assists
+                stats_dict[row.human_id]["points"] = row.goals + row.assists
+
+        # Aggregate penalties
+        penalties_query = (
+            session.query(
+                GameRoster.human_id,
+                func.count(Penalty.id).label("penalties"),
+                func.sum(case((Penalty.penalty_minutes == "GM", 1), else_=0)).label("gm_penalties"),
+            )
+            .join(Game, Game.id == GameRoster.game_id)
+            .outerjoin(Penalty, and_(Game.id == Penalty.game_id, Penalty.penalized_player_id == GameRoster.human_id))
+            .filter(
+                GameRoster.team_id == team_id,  # KEY: Filter by team
+                ~GameRoster.role.ilike("g"),
+                GameRoster.human_id.in_(stats_dict.keys()),
+                Game.status.in_([FINAL_STATUS, FINAL_SO_STATUS, FORFEIT_STATUS, NOEVENTS_STATUS]),
+                filter_condition,
+            )
+            .group_by(GameRoster.human_id)
+        )
+
+        for row in penalties_query.all():
+            if row.human_id in stats_dict:
+                stats_dict[row.human_id]["penalties"] = row.penalties
+                stats_dict[row.human_id]["gm_penalties"] = row.gm_penalties
+
+        # Calculate per-game averages
+        for human_id, stats in stats_dict.items():
+            games_with_stats = stats.get("games_with_stats", 0)
+            if games_with_stats > 0:
+                stats["goals_per_game"] = stats.get("goals", 0) / games_with_stats
+                stats["assists_per_game"] = stats.get("assists", 0) / games_with_stats
+                stats["points_per_game"] = stats.get("points", 0) / games_with_stats
+                stats["penalties_per_game"] = stats.get("penalties", 0) / games_with_stats
+                stats["gm_penalties_per_game"] = stats.get("gm_penalties", 0) / games_with_stats
+            else:
+                stats["goals_per_game"] = 0.0
+                stats["assists_per_game"] = 0.0
+                stats["points_per_game"] = 0.0
+                stats["penalties_per_game"] = 0.0
+                stats["gm_penalties_per_game"] = 0.0
+
+        # Insert stats for each player on this team
+        for human_id, stats in stats_dict.items():
+            skater_stat = StatsModel(
+                aggregation_id=aggregation_id,
+                team_id=team_id,
+                human_id=human_id,
+                games_played=stats.get("games_played", 0),
+                games_participated=stats.get("games_participated", 0),
+                games_with_stats=stats.get("games_with_stats", 0),
+                goals=stats.get("goals", 0),
+                assists=stats.get("assists", 0),
+                points=stats.get("points", 0),
+                penalties=stats.get("penalties", 0),
+                gm_penalties=stats.get("gm_penalties", 0),
+                goals_per_game=stats.get("goals_per_game", 0.0),
+                assists_per_game=stats.get("assists_per_game", 0.0),
+                points_per_game=stats.get("points_per_game", 0.0),
+                penalties_per_game=stats.get("penalties_per_game", 0.0),
+                gm_penalties_per_game=stats.get("gm_penalties_per_game", 0.0),
+                total_in_rank=len(stats_dict),
+                first_game_id=stats.get("first_game_id"),
+                last_game_id=stats.get("last_game_id"),
+                # Initialize streak fields to 0 (not calculated for team stats)
+                current_point_streak=0,
+                current_point_streak_avg_points=0.0,
+                # Ranks will be assigned later if needed
+                games_played_rank=0,
+                games_participated_rank=0,
+                games_with_stats_rank=0,
+                goals_rank=0,
+                assists_rank=0,
+                points_rank=0,
+                penalties_rank=0,
+                gm_penalties_rank=0,
+                goals_per_game_rank=0,
+                assists_per_game_rank=0,
+                points_per_game_rank=0,
+                penalties_per_game_rank=0,
+                gm_penalties_per_game_rank=0,
+                current_point_streak_rank=0,
+                current_point_streak_avg_points_rank=0,
+                aggregation_started_at=aggregation_start_time,
+            )
+            session.add(skater_stat)
+
+    session.commit()
+
+    # Update all records with completion timestamp
+    aggregation_end_time = datetime.utcnow()
+    session.query(StatsModel).filter(
+        StatsModel.aggregation_id == aggregation_id
+    ).update({StatsModel.aggregation_completed_at: aggregation_end_time})
+    session.commit()
+
+    progress.finish()
+    print(f"✓ Team skater stats aggregation complete for {aggregation_name}")
+
+
+def run_aggregate_team_skater_stats():
+    """
+    Run team skater stats aggregation for all organizations and divisions.
+    """
+    from hockey_blast_common_lib.utils import get_all_division_ids_for_org
+
+    session = create_session("boss")
+
+    # Get all org_id present in the Organization table
+    org_ids = session.query(Organization.id).all()
+    org_ids = [org_id[0] for org_id in org_ids]
+
+    for org_id in org_ids:
+        # Aggregate for organization level
+        aggregate_team_skater_stats(session, "org", org_id)
+
+        # Aggregate for all divisions in this organization
+        division_ids = get_all_division_ids_for_org(session, org_id)
+        for division_id in division_ids:
+            aggregate_team_skater_stats(session, "division", division_id)

hockey_blast_common_lib/models.py

@@ -53,7 +53,8 @@ class Game(db.Model):
     time = db.Column(db.Time)
     day_of_week = db.Column(db.Integer)  # 1 to 7 for Monday to Sunday
     period_length = db.Column(db.Integer)  # In minutes
-    location = db.Column(db.String(100))
+    location = db.Column(db.String(100))  # DEPRECATED: Use location_id instead
+    location_id = db.Column(db.Integer, db.ForeignKey("locations.id"), nullable=True)
     scorekeeper_id = db.Column(db.Integer, db.ForeignKey("humans.id"))
     referee_1_id = db.Column(db.Integer, db.ForeignKey("humans.id"))
     referee_2_id = db.Column(db.Integer, db.ForeignKey("humans.id"))
@@ -72,6 +73,7 @@ class Game(db.Model):
     home_ot_score = db.Column(db.Integer, default=0)
     visitor_ot_score = db.Column(db.Integer, default=0)
     game_type = db.Column(db.String(50))
+    live_time = db.Column(db.String(50), nullable=True)  # e.g., "Period 1, 1:10 left" for live games
     went_to_ot = db.Column(db.Boolean, default=False)
     home_period_1_shots = db.Column(db.Integer)
     home_period_2_shots = db.Column(db.Integer)
@@ -245,6 +247,7 @@ class Level(db.Model):
     org_id = db.Column(db.Integer, db.ForeignKey("organizations.id"), nullable=False)
     skill_value = db.Column(db.Float)  # A number from 0 (NHL) to 100 (pedestrian)
     level_name = db.Column(db.String(100))
+    short_name = db.Column(db.String(50))  # Shortened display name (e.g., "D-7B-W" for "Adult Division 7B West")
     level_alternative_name = db.Column(db.String(100))
     is_seed = db.Column(db.Boolean, nullable=True, default=False)  # New field
     skill_propagation_sequence = db.Column(db.Integer, nullable=True, default=-1)
@@ -253,6 +256,17 @@ class Level(db.Model):
     )
 
 
+class Location(db.Model):
+    __tablename__ = "locations"
+    id = db.Column(db.Integer, primary_key=True)
+    location_in_game_source = db.Column(db.String(200), nullable=False, unique=True)  # Raw string from Game.location, e.g., "San Jose Orange (N)"
+    location_name = db.Column(db.String(200), nullable=True)  # Optional: Facility name, e.g., "Sharks Ice At San Jose"
+    rink_name = db.Column(db.String(200), nullable=True)  # Optional: Specific rink, e.g., "Orange (N)"
+    address = db.Column(db.String(500), nullable=True)
+    google_maps_link = db.Column(db.String(500), nullable=True)
+    master_location_id = db.Column(db.Integer, db.ForeignKey("locations.id"), nullable=True)  # Points to the canonical location for this rink
+
+
 class LevelsMonthly(db.Model):
     __tablename__ = "levels_monthly"
     id = db.Column(db.Integer, primary_key=True)
@@ -427,6 +441,7 @@ class Season(db.Model):
     id = db.Column(db.Integer, primary_key=True)
     season_number = db.Column(db.Integer)
     season_name = db.Column(db.String(100))
+    base_season_name = db.Column(db.String(100))  # Static prefix for season name (e.g., "Silver Stick", "Over", etc.)
     start_date = db.Column(db.Date)
     end_date = db.Column(db.Date)
     league_number = db.Column(

hockey_blast_common_lib/stats_models.py

@@ -4,7 +4,13 @@ from sqlalchemy.orm import synonym
 from hockey_blast_common_lib.models import db
 
 
-class BaseStatsHuman(db.Model):
+class AggregationTimestampMixin:
+    """Mixin to add aggregation timestamp tracking to all stats models."""
+    aggregation_started_at = db.Column(db.DateTime, nullable=True)
+    aggregation_completed_at = db.Column(db.DateTime, nullable=True)
+
+
+class BaseStatsHuman(AggregationTimestampMixin, db.Model):
     __abstract__ = True
     id = db.Column(db.Integer, primary_key=True)
     human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False)
@@ -92,7 +98,7 @@ class BaseStatsHuman(db.Model):
         )
 
 
-class BaseStatsSkater(db.Model):
+class BaseStatsSkater(AggregationTimestampMixin, db.Model):
     __abstract__ = True
     id = db.Column(db.Integer, primary_key=True)
     human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False)
@@ -193,7 +199,7 @@ class BaseStatsSkater(db.Model):
         )
 
 
-class BaseStatsGoalie(db.Model):
+class BaseStatsGoalie(AggregationTimestampMixin, db.Model):
     __abstract__ = True
     id = db.Column(db.Integer, primary_key=True)
     human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False)
@@ -261,7 +267,7 @@ class BaseStatsGoalie(db.Model):
         )
 
 
-class BaseStatsReferee(db.Model):
+class BaseStatsReferee(AggregationTimestampMixin, db.Model):
     __abstract__ = True
     id = db.Column(db.Integer, primary_key=True)
     human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False)
@@ -331,7 +337,7 @@ class BaseStatsReferee(db.Model):
         )
 
 
-class BaseStatsScorekeeper(db.Model):
+class BaseStatsScorekeeper(AggregationTimestampMixin, db.Model):
     __abstract__ = True
     id = db.Column(db.Integer, primary_key=True)
     human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False)
@@ -922,3 +928,203 @@ class SkillValuePPGRatio(db.Model):
             "from_skill_value", "to_skill_value", name="_from_to_skill_value_uc"
         ),
     )
+
+
+# Team-based statistics models (inherit from existing bases, add team_id field)
+class OrgStatsSkaterTeam(BaseStatsSkater):
+    __tablename__ = "org_stats_skater_team"
+    org_id = db.Column(db.Integer, db.ForeignKey("organizations.id"), nullable=False)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False)
+    aggregation_id = synonym("org_id")
+
+    @declared_attr
+    def aggregation_type(cls):
+        return "org_team"
+
+    @classmethod
+    def get_aggregation_column(cls):
+        return "org_id"
+
+    @declared_attr
+    def __table_args__(cls):
+        return (
+            db.UniqueConstraint(
+                "org_id",
+                "team_id",
+                "human_id",
+                name="_org_team_human_uc_skater_team1",
+            ),
+            db.Index("idx_org_team_team_id", "team_id"),
+            db.Index("idx_org_team_human_id", "human_id"),
+            db.Index("idx_org_team_goals_per_game", "org_id", "goals_per_game"),
+            db.Index("idx_org_team_points_per_game", "org_id", "points_per_game"),
+            db.Index("idx_org_team_assists_per_game", "org_id", "assists_per_game"),
+        )
+
+
+class DivisionStatsSkaterTeam(BaseStatsSkater):
+    __tablename__ = "division_stats_skater_team"
+    division_id = db.Column(db.Integer, db.ForeignKey("divisions.id"), nullable=False)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False)
+    aggregation_id = synonym("division_id")
+
+    @declared_attr
+    def aggregation_type(cls):
+        return "division_team"
+
+    @classmethod
+    def get_aggregation_column(cls):
+        return "division_id"
+
+    @declared_attr
+    def __table_args__(cls):
+        return (
+            db.UniqueConstraint(
+                "division_id",
+                "team_id",
+                "human_id",
+                name="_division_team_human_uc_skater_team1",
+            ),
+            db.Index("idx_division_team_team_id", "team_id"),
+            db.Index("idx_division_team_human_id", "human_id"),
+            db.Index("idx_division_team_goals_per_game", "division_id", "goals_per_game"),
+            db.Index("idx_division_team_points_per_game", "division_id", "points_per_game"),
+            db.Index("idx_division_team_assists_per_game", "division_id", "assists_per_game"),
+        )
+
+
+class OrgStatsGoalieTeam(BaseStatsGoalie):
+    __tablename__ = "org_stats_goalie_team"
+    org_id = db.Column(db.Integer, db.ForeignKey("organizations.id"), nullable=False)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False)
+    aggregation_id = synonym("org_id")
+
+    @declared_attr
+    def aggregation_type(cls):
+        return "org_team"
+
+    @classmethod
+    def get_aggregation_column(cls):
+        return "org_id"
+
+    @declared_attr
+    def __table_args__(cls):
+        return (
+            db.UniqueConstraint(
+                "org_id",
+                "team_id",
+                "human_id",
+                name="_org_team_human_uc_goalie_team1",
+            ),
+            db.Index("idx_org_team_goalie_team_id", "team_id"),
+            db.Index("idx_org_team_goalie_human_id", "human_id"),
+            db.Index("idx_org_team_goalie_save_pct", "org_id", "save_percentage"),
+            db.Index("idx_org_team_goalie_gaa", "org_id", "goals_allowed_per_game"),
+        )
+
+
+class DivisionStatsGoalieTeam(BaseStatsGoalie):
+    __tablename__ = "division_stats_goalie_team"
+    division_id = db.Column(db.Integer, db.ForeignKey("divisions.id"), nullable=False)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False)
+    aggregation_id = synonym("division_id")
+
+    @declared_attr
+    def aggregation_type(cls):
+        return "division_team"
+
+    @classmethod
+    def get_aggregation_column(cls):
+        return "division_id"
+
+    @declared_attr
+    def __table_args__(cls):
+        return (
+            db.UniqueConstraint(
+                "division_id",
+                "team_id",
+                "human_id",
+                name="_division_team_human_uc_goalie_team1",
+            ),
+            db.Index("idx_division_team_goalie_team_id", "team_id"),
+            db.Index("idx_division_team_goalie_human_id", "human_id"),
+            db.Index("idx_division_team_goalie_save_pct", "division_id", "save_percentage"),
+            db.Index("idx_division_team_goalie_gaa", "division_id", "goals_allowed_per_game"),
+        )
+
+
+# Per-Game Statistics Models (for RAG system)
+# These models store individual game performance data for each player/goalie
+# CRITICAL: Only non-zero rows are saved (games where player recorded stats)
+
+
+class GameStatsSkater(db.Model):
+    """Per-game skater statistics.
+
+    Stores individual game performance for skaters.
+    Only records where player had non-zero stats are saved.
+    Optimized for queries like "show me top N games by points for player X".
+    """
+    __tablename__ = "game_stats_skater"
+
+    id = db.Column(db.Integer, primary_key=True)
+    game_id = db.Column(db.Integer, db.ForeignKey("games.id"), nullable=False, index=True)
+    human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False, index=True)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False, index=True)
+    org_id = db.Column(db.Integer, db.ForeignKey("organizations.id"), nullable=False, index=True)
+    level_id = db.Column(db.Integer, db.ForeignKey("levels.id"), nullable=False, index=True)
+
+    # Denormalized game metadata for sorting/filtering
+    game_date = db.Column(db.Date, nullable=False, index=True)
+    game_time = db.Column(db.Time, nullable=False)
+
+    # Performance stats
+    goals = db.Column(db.Integer, default=0, nullable=False)
+    assists = db.Column(db.Integer, default=0, nullable=False)
+    points = db.Column(db.Integer, default=0, nullable=False)
+    penalty_minutes = db.Column(db.Integer, default=0, nullable=False)
+
+    # Tracking
+    created_at = db.Column(db.DateTime, nullable=False, default=db.func.current_timestamp())
+
+    __table_args__ = (
+        db.UniqueConstraint("game_id", "human_id", name="_game_human_uc_skater"),
+        db.Index("idx_game_stats_skater_human_date", "human_id", "game_date", postgresql_using="btree"),
+        db.Index("idx_game_stats_skater_human_team_date", "human_id", "team_id", "game_date", postgresql_using="btree"),
+    )
+
+
+class GameStatsGoalie(db.Model):
+    """Per-game goalie statistics.
+
+    Stores individual game performance for goalies.
+    Only records where goalie faced shots are saved.
+    Optimized for queries like "show me top N games by save% for goalie X".
+    """
+    __tablename__ = "game_stats_goalie"
+
+    id = db.Column(db.Integer, primary_key=True)
+    game_id = db.Column(db.Integer, db.ForeignKey("games.id"), nullable=False, index=True)
+    human_id = db.Column(db.Integer, db.ForeignKey("humans.id"), nullable=False, index=True)
+    team_id = db.Column(db.Integer, db.ForeignKey("teams.id"), nullable=False, index=True)
+    org_id = db.Column(db.Integer, db.ForeignKey("organizations.id"), nullable=False, index=True)
+    level_id = db.Column(db.Integer, db.ForeignKey("levels.id"), nullable=False, index=True)
+
+    # Denormalized game metadata for sorting/filtering
+    game_date = db.Column(db.Date, nullable=False, index=True)
+    game_time = db.Column(db.Time, nullable=False)
+
+    # Performance stats
+    goals_allowed = db.Column(db.Integer, default=0, nullable=False)
+    shots_faced = db.Column(db.Integer, default=0, nullable=False)
+    saves = db.Column(db.Integer, default=0, nullable=False)  # Computed: shots_faced - goals_allowed
+    save_percentage = db.Column(db.Float, default=0.0, nullable=False)  # Computed: saves / shots_faced
+
+    # Tracking
+    created_at = db.Column(db.DateTime, nullable=False, default=db.func.current_timestamp())
+
+    __table_args__ = (
+        db.UniqueConstraint("game_id", "human_id", "team_id", name="_game_human_uc_goalie"),
+        db.Index("idx_game_stats_goalie_human_date", "human_id", "game_date", postgresql_using="btree"),
+        db.Index("idx_game_stats_goalie_human_team_date", "human_id", "team_id", "game_date", postgresql_using="btree"),
+    )