Implement leaderboard service and POC HTTP handlers with Swagger documentation

server/internal/races/service.go

@@ -685,6 +685,61 @@ func (s *Service) DeletePlan(ctx context.Context, id string) error {
 	return s.pg.DeletePlan(ctx, id)
 }
 
+// GetLeaderboard retrieves the leaderboard page and current driver position.
+func (s *Service) GetLeaderboard(ctx context.Context, trackID string, year int, limit, offset int, currentDriverID string) (*LeaderboardResult, error) {
+	if year == 0 {
+		year = s.now().Year()
+	}
+
+	var items []LeaderboardEntry
+	var total int
+	var err error
+
+	if trackID != "" {
+		items, total, err = s.pg.GetTrackLeaderboard(ctx, trackID, year, limit, offset)
+	} else {
+		items, total, err = s.pg.GetOverallLeaderboard(ctx, year, limit, offset)
+	}
+	if err != nil {
+		return nil, err
+	}
+
+	var currentDriver *LeaderboardEntry
+	if currentDriverID != "" {
+		if trackID != "" {
+			currentDriver, err = s.pg.GetTrackLeaderboardDriver(ctx, trackID, year, currentDriverID)
+		} else {
+			currentDriver, err = s.pg.GetOverallLeaderboardDriver(ctx, year, currentDriverID)
+		}
+		if err != nil {
+			return nil, err
+		}
+
+		if currentDriver == nil {
+			// fallback: get profile from drivers table
+			currentDriver, err = s.pg.GetDriverLeaderboardProfile(ctx, currentDriverID)
+			if err != nil {
+				return nil, err
+			}
+			// if driver exists but has no points, set points/rank to 0
+			if currentDriver != nil {
+				currentDriver.Points = 0
+				currentDriver.Rank = 0
+			}
+		}
+	}
+
+	if items == nil {
+		items = []LeaderboardEntry{}
+	}
+
+	return &LeaderboardResult{
+		Items:         items,
+		Total:         total,
+		CurrentDriver: currentDriver,
+	}, nil
+}
+
 // ---------------------------------------------------------------------------
 // Scheduler
 // ---------------------------------------------------------------------------