refactor: extract MatchFilterQuery, cache invalidation, and security audit fixes

  - Extract match filters/sorting to MatchFilterQuery (app/queries/)
  - Add invalidate_cache helper to Cacheable concern
  - Add after_action cache invalidation on update/destroy in matches, players, tournaments controllers
  - Move paginate inside cache block in MatchesController to avoid unnecessary query on cache hit
  - Fix ScoutingPlayersController N+1: replace global includes with scoped org query after pagination
  - Standardize 6 analytics controllers with before_action :set_player
  - Decompose CompetitiveController#build_role_performance into 3 helpers, remove rubocop:disable
  - Move PERFORMANCE_ROLES constant before private section
  - Fix Semgrep nosemgrep placement in 3 email templates (password_reset x2, welcome)
  - Update README and PRD with 2026-04-21 security audit results (Brakeman 0, Semgrep 0, pentest 0 real
  findings

Author: Bulletdev

README.md

@@ -1013,7 +1013,7 @@ All cached responses include `X-Cache-Hit: true/false` header.
 
 ### Security Status
 
-**Last Audit**: 2026-03-11
+**Last Audit**: 2026-04-21
 **Overall Grade**: A (all application security tests passing)
 **Status**: Production-ready
 

app/controllers/concerns/cacheable.rb

@@ -42,6 +42,14 @@ def cache_response(key, expires_in: 5.minutes, &block)
     Rails.cache.fetch(cache_key, expires_in: expires_in, &block)
   end
 
+  # Deletes one or more org-scoped cache keys.
+  # Use in after_action callbacks on mutating actions.
+  #
+  # @param keys [Array<String>] keys to invalidate (same identifiers passed to cache_response)
+  def invalidate_cache(*keys)
+    keys.each { |key| Rails.cache.delete(build_cache_key(key)) }
+  end
+
   private
 
   # Builds an organisation-scoped cache key to prevent cross-tenant leakage.

app/modules/analytics/controllers/champions_controller.rb

@@ -17,24 +17,24 @@ module Controllers
     # Main endpoints:
     # - GET show: Returns comprehensive champion statistics including mastery grades and diversity metrics
     class ChampionsController < Api::V1::BaseController
+      before_action :set_player, only: %i[show details]
+
       def show
-        player = organization_scoped(Player).find(params[:player_id])
-        stats = fetch_champion_stats(player)
+        stats = fetch_champion_stats(@player)
         champion_stats = build_champion_stats(stats)
 
-        render_success(build_champion_data(player, champion_stats))
+        render_success(build_champion_data(@player, champion_stats))
       end
 
       def details
-        player = organization_scoped(Player).find(params[:player_id])
         champion = params[:champion]
 
         if champion.blank?
           return render_error(message: 'Champion name is required', code: 'CHAMPION_REQUIRED',
                               status: :bad_request)
         end
 
-        matches = fetch_champion_matches(player, champion)
+        matches = fetch_champion_matches(@player, champion)
 
         if matches.empty?
           return render_error(message: "No matches found for champion #{champion}", code: 'NO_MATCHES',
@@ -45,14 +45,12 @@ def details
         matches_array = matches.to_a
 
         render_success({
-                         player: PlayerSerializer.render_as_hash(player),
+                         player: PlayerSerializer.render_as_hash(@player),
                          champion: champion,
                          icon_url: riot_service.champion_icon_url(champion),
                          aggregate_stats: build_aggregate_stats(matches, matches_array),
                          matches: serialize_champion_matches(matches_array, riot_service)
                        })
-      rescue ActiveRecord::RecordNotFound
-        render_error(message: 'Player not found', code: 'PLAYER_NOT_FOUND', status: :not_found)
       rescue StandardError => e
         Rails.logger.error("Error in champions#details: #{e.message}")
         Rails.logger.error(e.backtrace.join("\n"))
@@ -254,6 +252,10 @@ def round_or_default(value, precision, default = 0)
         value&.round(precision) || default
       end
 
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
+
       def build_champion_data(player, champion_stats)
         {
           player: PlayerSerializer.render_as_hash(player),

app/modules/analytics/controllers/competitive_controller.rb

@@ -84,6 +84,8 @@ def opponents
                      status: :internal_server_error)
       end
 
+      PERFORMANCE_ROLES = %w[top jungle mid adc support].freeze
+
       # ── Private helpers ────────────────────────────────────────────
       private
 
@@ -165,38 +167,41 @@ def build_side_performance(rows)
         end
       end
 
-      def build_role_performance(rows) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        roles      = %w[top jungle mid adc support]
-        role_stats = roles.each_with_object({}) do |r, h|
-          h[r] = { games: 0, wins: 0, champions: Hash.new(0) }
-        end
+      def build_role_performance(rows)
+        role_stats = initial_role_stats
+        rows.each { |match| accumulate_match_picks(role_stats, match) }
+        role_stats.map { |role, stats| format_role_stat(role, stats) }
+      end
 
-        rows.each do |match|
-          won = match.victory
-          (match.our_picks || []).each do |pick|
-            role  = pick['role']&.downcase
-            champ = pick['champion']
-            next unless role_stats.key?(role) && champ.present?
+      def initial_role_stats
+        PERFORMANCE_ROLES.each_with_object({}) { |r, h| h[r] = { games: 0, wins: 0, champions: Hash.new(0) } }
+      end
 
-            role_stats[role][:games]          += 1
-            role_stats[role][:wins]           += 1 if won
-            role_stats[role][:champions][champ] += 1
-          end
-        end
+      def accumulate_match_picks(role_stats, match)
+        won = match.victory
+        (match.our_picks || []).each do |pick|
+          role  = pick['role']&.downcase
+          champ = pick['champion']
+          next unless role_stats.key?(role) && champ.present?
 
-        role_stats.map do |role, s|
-          most_played = s[:champions].max_by { |_, c| c }&.first || 'N/A'
-          {
-            role: role,
-            games: s[:games],
-            wins: s[:wins],
-            win_rate: s[:games].positive? ? (s[:wins].to_f / s[:games] * 100).round(1) : 0,
-            most_played_champion: most_played,
-            champion_pool_size: s[:champions].size
-          }
+          role_stats[role][:games]            += 1
+          role_stats[role][:wins]             += 1 if won
+          role_stats[role][:champions][champ] += 1
         end
       end
 
+      def format_role_stat(role, stats)
+        most_played = stats[:champions].max_by { |_, c| c }&.first || 'N/A'
+        {
+          role: role,
+          games: stats[:games],
+          wins: stats[:wins],
+          win_rate: stats[:games].positive? ? (stats[:wins].to_f / stats[:games] * 100).round(1) : 0,
+          most_played_champion: most_played,
+          champion_pool_size: stats[:champions].size
+        }
+      end
+
       def extract_meta_champions(matches)
         matches.where.not(meta_champions: nil)
                .pluck(:meta_champions)

app/modules/analytics/controllers/kda_trend_controller.rb

@@ -16,20 +16,20 @@ module Controllers
     # Main endpoints:
     # - GET show: Returns KDA trends for the last 50 matches with rolling averages
     class KdaTrendController < Api::V1::BaseController
-      def show
-        player = organization_scoped(Player).find(params[:player_id])
+      before_action :set_player, only: %i[show]
 
+      def show
         # Get recent matches for the player
         stats = PlayerMatchStat.joins(:match)
-                               .where(player: player, matches: { organization_id: current_organization.id })
+                               .where(player: @player, matches: { organization_id: current_organization.id })
                                .order('matches.game_start DESC')
                                .limit(50)
                                .includes(:match)
 
         stats_array = stats.to_a
 
         trend_data = {
-          player: PlayerSerializer.render_as_hash(player),
+          player: PlayerSerializer.render_as_hash(@player),
           kda_by_match: stats_array.map do |stat|
             kda = if stat.deaths.zero?
                     (stat.kills + stat.assists).to_f
@@ -59,6 +59,10 @@ def show
 
       private
 
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
+
       def calculate_kda_average(stats)
         return 0 if stats.empty?
 

app/modules/analytics/controllers/laning_controller.rb

@@ -9,20 +9,20 @@ module Controllers
     # so those fields are omitted (nil) and the frontend falls back gracefully.
     #
     class LaningController < Api::V1::BaseController
-      def show
-        player = organization_scoped(Player).find(params[:player_id])
+      before_action :set_player, only: %i[show]
 
+      def show
         stats = PlayerMatchStat.joins(:match)
                                .includes(:match)
-                               .where(player: player, match: { organization: current_organization })
+                               .where(player: @player, match: { organization: current_organization })
                                .order('"match"."game_start" DESC')
                                .limit(20)
 
         games = stats.count
         wins  = stats.where(match: { victory: true }).count
 
         laning_data = {
-          player: PlayerSerializer.render_as_hash(player),
+          player: PlayerSerializer.render_as_hash(@player),
           avg_cs_per_min: stats.average(:cs_per_min)&.round(1) || calculate_avg_cs_per_min(stats),
           avg_cs_total: stats.average(:cs)&.round(1) || 0,
           lane_win_rate: games.zero? ? nil : ((wins.to_f / games) * 100).round(1),
@@ -43,6 +43,10 @@ def show
 
       private
 
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
+
       def build_laning_trend(stats)
         stats.map do |stat|
           next unless stat.match.game_start

app/modules/analytics/controllers/ping_profile_controller.rb

@@ -11,17 +11,24 @@ module Controllers
     #   GET /api/v1/analytics/players/:player_id/ping-profile
     #   GET /api/v1/analytics/players/:player_id/ping-profile?games=30
     class PingProfileController < Api::V1::BaseController
+      before_action :set_player, only: %i[show]
+
       def show
-        player = organization_scoped(Player).find(params[:player_id])
         games = [params.fetch(:games, 20).to_i, 50].min
 
-        profile = PingProfileService.new(player, matches_limit: games).calculate
+        profile = PingProfileService.new(@player, matches_limit: games).calculate
 
         render_success({
-                         player: PlayerSerializer.render_as_hash(player),
+                         player: PlayerSerializer.render_as_hash(@player),
                          ping_profile: profile
                        })
       end
+
+      private
+
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
     end
   end
 end

app/modules/analytics/controllers/teamfights_controller.rb

@@ -16,18 +16,18 @@ module Controllers
     # Main endpoints:
     # - GET show: Returns teamfight statistics for the last 20 matches including damage and multikills
     class TeamfightsController < Api::V1::BaseController
-      def show
-        player = organization_scoped(Player).find(params[:player_id])
+      before_action :set_player, only: %i[show]
 
+      def show
         stats = PlayerMatchStat.joins(:match)
-                               .where(player: player)
+                               .where(player: @player)
                                .where('matches.organization_id = ?', current_organization.id)
                                .order('matches.game_start DESC')
                                .preload(:match)
                                .limit(20)
 
         teamfight_data = {
-          player: PlayerSerializer.render_as_hash(player),
+          player: PlayerSerializer.render_as_hash(@player),
           damage_performance: {
             avg_damage_dealt: stats.average(:damage_dealt_total)&.round(0),
             avg_damage_taken: stats.average(:damage_taken)&.round(0),
@@ -68,6 +68,10 @@ def show
 
       private
 
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
+
       def calculate_avg_damage_per_min(stats)
         total_damage = 0
         total_minutes = 0

app/modules/analytics/controllers/vision_controller.rb

@@ -8,17 +8,17 @@ module Controllers
     # without unpacking nested keys.
     #
     class VisionController < Api::V1::BaseController
-      def show # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
-        player = organization_scoped(Player).find(params[:player_id])
+      before_action :set_player, only: %i[show]
 
+      def show # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
         stats = PlayerMatchStat.joins(:match)
                                .includes(:match)
-                               .where(player: player, match: { organization: current_organization })
+                               .where(player: @player, match: { organization: current_organization })
                                .order('"match"."game_start" DESC')
                                .limit(20)
 
         vision_data = {
-          player: PlayerSerializer.render_as_hash(player),
+          player: PlayerSerializer.render_as_hash(@player),
           avg_vision_score: stats.average(:vision_score)&.round(1) || 0,
           avg_wards_placed: stats.average(:wards_placed)&.round(1) || 0,
           avg_wards_destroyed: stats.average(:wards_destroyed)&.round(1) || 0,
@@ -27,7 +27,7 @@ def show # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComple
           total_wards_placed: stats.sum(:wards_placed) || 0,
           total_wards_destroyed: stats.sum(:wards_destroyed) || 0,
           vision_per_min: calculate_avg_vision_per_min(stats),
-          role_comparison: calculate_role_comparison(player),
+          role_comparison: calculate_role_comparison(@player),
           vision_trend: build_vision_trend(stats)
         }
 
@@ -36,6 +36,10 @@ def show # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComple
 
       private
 
+      def set_player
+        @player = organization_scoped(Player).find(params[:player_id])
+      end
+
       def build_vision_trend(stats)
         stats.map do |stat|
           next unless stat.match.game_start