Material Alerts Persistence

Material alerts are product recommendations shown to customers during checkout (e.g., "You need a thermostat for your floor heating system"). This feature persists these alerts in the database instead of using Rails.cache.

Background

Problem: Rails.cache uses Marshal.dump for serialization, but the Virtus-based Item::Materials::Alert class creates anonymous class mixins that cannot be serialized. This caused TypeError: can't dump anonymous class errors (AppSignal incident #2919).

Solution: Persist material alerts in PostgreSQL using ActiveRecord models with explicit foreign keys.

Architecture

Database Schema

┌─────────────────────┐      ┌─────────────────────┐      ┌─────────────┐
│ Order/Quote/Room    │──┬──▶│  material_alerts    │──┬──▶│ material_   │
│ Configuration       │  │   │                     │  │   │ alert_items │
└─────────────────────┘  │   │  - signature        │  │   │             │──▶ items
                         │   │  - name             │  │   │  - position │
                         │   │  - recommended_qty  │  │   └─────────────┘
                         │   │  - actual_qty       │  │
                         │   │  - group_name       │  │
                         │   │  - group_type       │  │
                         │   │  - unmaskable       │  │
                         │   └─────────────────────┘  │
                         │                            │
                         │   (FK with CASCADE DELETE) │
                         └────────────────────────────┘

Key Design Decisions

  1. Explicit FKs (not polymorphic): Uses order_id, quote_id, room_configuration_id columns with exactly one set at a time. This enables:

    • Proper CASCADE DELETE when parent is deleted
    • Database-enforced referential integrity via CHECK constraint
    • Cleaner queries without resource_type filtering

  2. Signature-based invalidation: Each alert stores a signature (MD5 hash of SKU:quantity pairs). When line items change, the signature changes, triggering regeneration on next access.

  3. Eager loading: Alerts include items via has_many :through with strategic preloading to avoid N+1 queries.

Models

MaterialAlert

# Primary model storing alert metadata
class MaterialAlert < ApplicationRecord
  belongs_to :order, optional: true
  belongs_to :quote, optional: true
  belongs_to :room_configuration, optional: true
  
  has_many :material_alert_items, dependent: :destroy
  has_many :items, through: :material_alert_items
  
  # Backward compatibility with Virtus interface
  def room
    room_configuration
  end
end

MaterialAlertItem

# Join table linking alerts to recommended items
class MaterialAlertItem < ApplicationRecord
  belongs_to :material_alert
  belongs_to :item
  
  default_scope { order(:position) }
end

Usage

Fetching Alerts

The primary interface is Pickable#get_material_alerts:

# On Order, Quote, or RoomConfiguration
@cart.get_material_alerts(for_www: true, for_cart: true)

This method:

  1. Computes the current line_items.signature
  2. Checks for existing alerts matching that signature
  3. If found, returns them with items eager-loaded
  4. If not found, generates fresh alerts via Item::Materials::Check and persists them

Manual Invalidation

For edge cases where line items change outside normal flow:

@order.invalidate_material_alerts!

This deletes all alerts for the resource. They regenerate on next access.

Invalidation Triggers

Scenario Handling
Line items added/removed Automatic (signature changes)
Order split Explicit call to invalidate_material_alerts! in Order::Splitter
Quote to order conversion No action needed - new order generates on first access
Parent record deleted CASCADE DELETE removes alerts automatically
Item deleted CASCADE DELETE removes join record; alert regenerates on next access

Database Constraints

CHECK Constraint

Ensures exactly one resource FK is set:

ALTER TABLE material_alerts ADD CONSTRAINT chk_material_alerts_single_resource
CHECK (
  (CASE WHEN order_id IS NOT NULL THEN 1 ELSE 0 END +
   CASE WHEN quote_id IS NOT NULL THEN 1 ELSE 0 END +
   CASE WHEN room_configuration_id IS NOT NULL THEN 1 ELSE 0 END) = 1
)

Indexes

  • (order_id, signature) - Fast lookup for order alerts
  • (quote_id, signature) - Fast lookup for quote alerts
  • (room_configuration_id, signature) - Fast lookup for room alerts
  • (material_alert_id, item_id) - Unique constraint on join table

Alert Attributes

Attribute Type Description
signature string MD5 hash of line items for invalidation
name string Human-readable alert message
recommended_qty integer How many items we recommend
actual_qty integer How many customer currently has
group_name string Grouping label (e.g., "Installation Kits")
group_type string CSS class for styling
unmaskable boolean If true, alert cannot be filtered by stock/customer rules

Unmaskable Alerts

When unmaskable: true, the alert bypasses stock availability and customer eligibility filters. Used for:

  • Safety/compliance warnings - Watts/sqft exceeding state electrical codes
  • Critical system requirements - Controls required per heating element
  • Incompatibility errors - Items not recommended with certain controls
  • Required accessories - Junction boxes, power connection kits

Performance Optimizations

Cart View (WWW)

The cart view batch-preloads ViewProductCatalog data to avoid N+1 queries when rendering material alert items:

<% vpc_by_item_id = ViewProductCatalog.where(item_id: all_item_ids, catalog_id: catalog_id)
                                       .includes(:item, :catalog_item)
                                       .index_by(&:item_id) %>

This provides:

  • item_is_web_accessible for filtering
  • product_stock_status for stock checks
  • catalog_item for pricing

CRM View

CRM uses separate partials (_crm_material_alert.html.erb) that don't need the same optimization since they display differently.

Migration

bundle exec rails db:migrate

The migration:

  1. Creates material_alerts table with explicit FK columns
  2. Creates material_alert_items join table
  3. Adds composite indexes for FK + signature lookups
  4. Adds CHECK constraint for single-resource enforcement
  5. Adds foreign keys with CASCADE DELETE

Related Files

  • app/models/material_alert.rb - Main model
  • app/models/material_alert_item.rb - Join model
  • app/concerns/models/pickable.rb - get_material_alerts interface
  • app/services/item/materials/check.rb - Alert generation logic
  • app/views/shared/_cart_material_alerts.html.erb - WWW cart rendering
  • app/views/shared/_crm_material_alert.html.erb - CRM rendering
  • db/migrate/20260121210000_create_material_alerts.rb - Migration