Add HPG game engine API — models, controllers, serializers, and specs (Phases 0–3)

Implements the full HousePriceGuess backend integration:
- Phase 0: CORS for housepriceguess.com, hpg integration category
- Phase 1: 5 new tables (realty_games, game_listings, game_sessions, game_estimates, access_codes) with models, validations, scopes, and callbacks
- Phase 2: 7 API endpoints under api_public/v1/hpg/ (games, estimates, results, leaderboards, access_codes, listings) with 4 serializers/services
- Phase 3: Provisioning rake tasks (hpg:provision, hpg:provision_batch, hpg:create_sample_game)

103 specs passing (57 model + 46 request) including cross-tenant isolation tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: etewiah

app/controllers/api_public/v1/hpg/access_codes_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class AccessCodesController < BaseController
+        # POST /api_public/v1/hpg/access_codes/check
+        def check
+          disable_cache!
+
+          code = params[:code].to_s.strip
+          valid = current_website.access_codes.valid.exists?(code: code)
+
+          render json: { valid: valid, code: code }
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/base_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class BaseController < ApiPublic::V1::BaseController
+        private
+
+        # Override: shorter default cache for game data
+        def set_api_public_cache_headers
+          expires_in 5.minutes, public: true
+          response.headers["Vary"] = "X-Website-Slug"
+        end
+
+        def disable_cache!
+          response.headers["Cache-Control"] = "no-store"
+        end
+
+        def find_game!
+          @game = current_website.realty_games.find_by!(slug: params[:slug])
+        end
+
+        def require_website!
+          return if current_website.present?
+
+          render json: {
+            error: { code: 'WEBSITE_REQUIRED', message: 'Unable to determine website from request.' }
+          }, status: :bad_request
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/estimates_controller.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class EstimatesController < BaseController
+        before_action :find_game!
+
+        # POST /api_public/v1/hpg/games/:slug/estimates
+        def create
+          disable_cache!
+
+          result = Pwb::Hpg::EstimateProcessor.call(
+            game: @game,
+            website: current_website,
+            params: estimate_params
+          )
+
+          if result[:error]
+            render json: { error: result[:error] }, status: result[:status]
+          else
+            render json: result[:data], status: :created
+          end
+        end
+
+        private
+
+        def estimate_params
+          params.require(:price_estimate).permit(
+            :game_listing_id, :estimated_price, :currency,
+            :visitor_token, :guest_name, :property_index, :session_id
+          )
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/games_controller.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class GamesController < BaseController
+        before_action :find_game!, only: :show
+
+        # GET /api_public/v1/hpg/games
+        def index
+          expires_in 1.hour, public: true
+
+          games = current_website.realty_games.visible_on_landing.currently_available
+          data = games.map { |g| Pwb::Hpg::GameSerializer.call(g) }
+
+          render json: { data: data, meta: { total: data.size } }
+        end
+
+        # GET /api_public/v1/hpg/games/:slug
+        def show
+          render json: Pwb::Hpg::GameSummarySerializer.call(@game)
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/leaderboards_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class LeaderboardsController < BaseController
+        # GET /api_public/v1/hpg/leaderboards
+        def index
+          expires_in 1.minute, public: true
+
+          sessions = current_website.game_sessions.for_leaderboard
+          sessions = filter_by_game(sessions)
+          sessions = filter_by_period(sessions)
+
+          limit = [(params[:limit] || 20).to_i, 100].min
+          data = sessions.limit(limit).includes(:realty_game).map do |s|
+            {
+              rank: nil, # computed below
+              guest_name: s.guest_name,
+              total_score: s.total_score,
+              estimates_count: s.estimates_count,
+              game_slug: s.realty_game.slug,
+              game_title: s.realty_game.title,
+              created_at: s.created_at.iso8601
+            }
+          end
+
+          data.each_with_index { |entry, i| entry[:rank] = i + 1 }
+
+          render json: {
+            data: data,
+            meta: {
+              total: sessions.count,
+              period: params[:period] || 'all_time',
+              game_slug: params[:game_slug]
+            }
+          }
+        end
+
+        private
+
+        def filter_by_game(sessions)
+          return sessions if params[:game_slug].blank?
+
+          sessions.joins(:realty_game)
+                  .where(pwb_realty_games: { slug: params[:game_slug] })
+        end
+
+        def filter_by_period(sessions)
+          case params[:period]
+          when 'daily'   then sessions.where('pwb_game_sessions.created_at >= ?', 1.day.ago)
+          when 'weekly'  then sessions.where('pwb_game_sessions.created_at >= ?', 1.week.ago)
+          when 'monthly' then sessions.where('pwb_game_sessions.created_at >= ?', 1.month.ago)
+          else sessions
+          end
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/listings_controller.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class ListingsController < BaseController
+        # GET /api_public/v1/hpg/listings/:uuid
+        def show
+          expires_in 1.hour, public: true
+
+          asset = current_website.realty_assets.find(params[:uuid])
+          photos = asset.prop_photos.limit(10)
+
+          render json: {
+            uuid: asset.id,
+            reference: asset.reference,
+            title: asset.title,
+            street_address: asset.street_address,
+            city: asset.city,
+            country: asset.country,
+            postal_code: asset.postal_code,
+            bedrooms: asset.count_bedrooms,
+            bathrooms: asset.count_bathrooms,
+            area_sqm: asset.constructed_area,
+            latitude: asset.latitude,
+            longitude: asset.longitude,
+            prop_type: asset.prop_type_key,
+            photos: photos.map { |p| { id: p.id, url: p.image_url, thumbnail_url: p.thumbnail_url } }
+          }
+        end
+      end
+    end
+  end
+end

app/controllers/api_public/v1/hpg/results_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module ApiPublic
+  module V1
+    module Hpg
+      class ResultsController < BaseController
+        before_action :find_game!
+
+        # GET /api_public/v1/hpg/games/:slug/results/:session_id
+        def show
+          expires_in 1.minute, public: true
+
+          session = @game.game_sessions.find(params[:session_id])
+          render json: Pwb::Hpg::ResultBoardSerializer.call(session, @game)
+        end
+      end
+    end
+  end
+end

app/models/pwb/access_code.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: pwb_access_codes
+# Database name: primary
+#
+#  id         :uuid             not null, primary key
+#  active     :boolean          default(TRUE), not null
+#  code       :string           not null
+#  expires_at :datetime
+#  max_uses   :integer
+#  uses_count :integer          default(0), not null
+#  created_at :datetime         not null
+#  updated_at :datetime         not null
+#  website_id :bigint           not null
+#
+# Indexes
+#
+#  index_pwb_access_codes_on_website_id           (website_id)
+#  index_pwb_access_codes_on_website_id_and_code  (website_id,code) UNIQUE
+#
+# Foreign Keys
+#
+#  fk_rails_...  (website_id => pwb_websites.id)
+#
+module Pwb
+  class AccessCode < ApplicationRecord
+    self.table_name = 'pwb_access_codes'
+
+    belongs_to :website
+
+    validates :code, presence: true, uniqueness: { scope: :website_id }
+
+    scope :active, -> { where(active: true) }
+    scope :not_expired, -> { where('expires_at IS NULL OR expires_at > ?', Time.current) }
+    scope :not_exhausted, -> { where('max_uses IS NULL OR uses_count < max_uses') }
+    scope :valid, -> { active.not_expired.not_exhausted }
+
+    def valid_code?
+      active? && !expired? && !exhausted?
+    end
+
+    def expired?
+      expires_at.present? && expires_at < Time.current
+    end
+
+    def exhausted?
+      max_uses.present? && uses_count >= max_uses
+    end
+
+    def redeem!
+      increment!(:uses_count)
+    end
+  end
+end

app/models/pwb/game_estimate.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# == Schema Information
+#
+# Table name: pwb_game_estimates
+# Database name: primary
+#
+#  id                    :uuid             not null, primary key
+#  actual_price_cents    :bigint           not null
+#  currency              :string           default("EUR"), not null
+#  estimate_details      :jsonb            not null
+#  estimated_price_cents :bigint           not null
+#  percentage_diff       :decimal(8, 2)
+#  property_index        :integer
+#  score                 :integer          default(0), not null
+#  created_at            :datetime         not null
+#  updated_at            :datetime         not null
+#  game_listing_id       :uuid             not null
+#  game_session_id       :uuid             not null
+#  website_id            :bigint           not null
+#
+# Indexes
+#
+#  index_pwb_game_estimates_on_game_listing_id      (game_listing_id)
+#  index_pwb_game_estimates_on_game_session_id      (game_session_id)
+#  index_pwb_game_estimates_on_website_id           (website_id)
+#  index_pwb_game_estimates_unique_session_listing  (game_session_id,game_listing_id) UNIQUE
+#
+# Foreign Keys
+#
+#  fk_rails_...  (game_listing_id => pwb_game_listings.id)
+#  fk_rails_...  (game_session_id => pwb_game_sessions.id)
+#  fk_rails_...  (website_id => pwb_websites.id)
+#
+module Pwb
+  class GameEstimate < ApplicationRecord
+    self.table_name = 'pwb_game_estimates'
+
+    belongs_to :game_session
+    belongs_to :game_listing
+    belongs_to :website
+
+    validates :estimated_price_cents, presence: true, numericality: { greater_than: 0 }
+    validates :actual_price_cents, presence: true, numericality: { greater_than: 0 }
+    validates :game_listing_id, uniqueness: { scope: :game_session_id,
+                                               message: 'already has an estimate in this session' }
+
+    before_validation :calculate_score, on: :create
+    after_create :update_session_score!
+    after_create :increment_game_counter
+
+    private
+
+    def calculate_score
+      return unless estimated_price_cents.present? && actual_price_cents.present?
+
+      calculator = Pwb::PriceGame::ScoreCalculator.new(
+        guessed_cents: estimated_price_cents,
+        actual_cents: actual_price_cents
+      )
+      self.score = calculator.score
+      self.percentage_diff = calculator.percentage_diff
+      self.estimate_details = calculator.result
+    end
+
+    def update_session_score!
+      game_session.recalculate_total_score!
+    end
+
+    def increment_game_counter
+      game_listing.realty_game.increment!(:estimates_count)
+    end
+  end
+end