spree_cm_commissioner 2.12.0.pre.pre2 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7223999a2cd0d551f0694c7cd4103195db0ca0473b7ee577a17be13d6686f5f
-  data.tar.gz: bf3fa4a68bf67915a77bd37b2cc2fdaa7f05bece78be8101b76c786f9d8daad5
+  metadata.gz: 10936d8185cc09d4bd8eca8c3c2626cb9bb113d2e94695030be009f9b38edbcc
+  data.tar.gz: 8b1493341611af89e52c06017d1abc3ad6adc838a541dd3ec93dd76877985eaf
 SHA512:
-  metadata.gz: 7e4b196cc0f1426f4672f511546509ddcbf41981203f8affb32e26df9c2e2f0d08cefefb2530810405fa8d9cdf15f3a680e6ea78fcf0751b0efe7dba25e7ce8d
-  data.tar.gz: 9de8a0f14b88d42174f53d13cf3ac2cf0fd7cf5aea024a31f8e5c8a76aa86dc0dc40ac2f6d5774d7ecc35ca3a54868e4f48fb5084321bbb0c8066138a304669f
+  metadata.gz: f945b868565fa7e4f699c07c35f20bb324b4c87d910f96738d4d4049e5b17d7c1455fd3227c4ab699bf85a449349ab4bc0cdd52b1b3d55bd519c48762da39ab6
+  data.tar.gz: d6fd25adafc7a2ad5e710043fbd8dc062008292df46d4819598a0a45333fd4dbbccae1428b6bc389ec6c1bcde2ffd9f7ddd1665a5974ff14989148622fabcadd

data/Gemfile.lock

@@ -34,7 +34,7 @@ GIT
 PATH
   remote: .
   specs:
-    spree_cm_commissioner (2.12.0.pre.pre2)
+    spree_cm_commissioner (2.12.0)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/jobs/spree_cm_commissioner/publish_stock_statuses_to_firestore_job.rb

@@ -0,0 +1,19 @@
+module SpreeCmCommissioner
+  # Fired from SpreeCmCommissioner::InventoryItem#publish_live_stock_status_to_firestore
+  # (after_commit), one enqueue per event whose stock actually changed, so publishing is near-instant
+  # instead of waiting for the next StockStatusConsolidationJob cron tick.
+  #
+  # ApplicationUniqueJob (args-keyed via activejob-uniqueness, on_conflict: :log) so a burst of
+  # concurrent stock changes for the same popular event collapses into one in-flight publish per
+  # event_id, instead of one job per changed InventoryItem row.
+  class PublishStockStatusesToFirestoreJob < ApplicationUniqueJob
+    queue_as :default
+
+    def perform(event_id:)
+      taxon = Spree::Taxon.find_by(id: event_id)
+      return unless taxon
+
+      SpreeCmCommissioner::Events::PublishStockStatusesToFirestore.call(taxon: taxon)
+    end
+  end
+end

data/app/jobs/spree_cm_commissioner/stock_status_consolidation_job.rb

@@ -0,0 +1,27 @@
+module SpreeCmCommissioner
+  # Safety-net reconciliation sweep, run on a low-frequency cron (cm-market-server/config/schedule.yml,
+  # `stock_status_consolidation` entry, dispatched through the existing `InvokeJob` cron pattern — same
+  # mechanism already used for `WaitingRoom::StampQueuePositionsJob`/`Integrations::PollingSchedulerJob`).
+  #
+  # SpreeCmCommissioner::PublishStockStatusesToFirestoreJob (enqueued directly off order-complete, see
+  # SpreeCmCommissioner::OrderStateMachine) is the primary, near-instant trigger now. This job exists
+  # only to catch anything that trigger misses — a failed job, a Firestore hiccup, or stock changing via
+  # a path other than order-complete (e.g. an admin stock adjustment) — by re-scanning every event
+  # currently inside its live_stock_starts_at/live_stock_ends_at window (see Spree::Taxon.live_stock_active)
+  # regardless of whether anything actually changed. Delegates the actual (batched, per-event) Firestore
+  # write to Events::PublishStockStatusesToFirestore, same as the real-time job.
+  #
+  # ApplicationUniqueJob (not ApplicationJob) so a cycle that runs long — many live events, a slow
+  # Firestore round trip — can't overlap with the next cron tick a minute later; `perform` takes no
+  # arguments, so this is a single global "is a consolidation cycle already in flight" lock, same pattern
+  # as WaitingRoom::StampQueuePositionsJob above.
+  class StockStatusConsolidationJob < ApplicationUniqueJob
+    queue_as :default
+
+    def perform
+      Spree::Taxon.event.live_stock_active.find_each do |taxon|
+        SpreeCmCommissioner::Events::PublishStockStatusesToFirestore.call(taxon: taxon)
+      end
+    end
+  end
+end

data/app/models/spree_cm_commissioner/inventory_item.rb

@@ -35,6 +35,7 @@ module SpreeCmCommissioner
     before_save -> { self.product_type = variant.product_type }, if: -> { product_type.nil? }
 
     after_commit :schedule_product_cache_invalidation
+    after_commit :publish_live_stock_status_to_firestore
 
     # Only for ecommerce: the app uses product.in_stock? (derived from quantity_available) for product cards.
     # Other types (e.g. accommodation, bus) have many inventory items (including daily-generated ones),
@@ -55,6 +56,29 @@ module SpreeCmCommissioner
       SpreeCmCommissioner::MaintenanceTasks::CacheInvalidation.pending.create_or_find_by(maintainable: variant.product)
     end
 
+    # The single trigger point for real-time Firestore stock-status publishing — catches every
+    # stock-mutation path that eventually saves an InventoryItem row: order complete (unstock),
+    # order cancel (restock), hold acquire/release/convert (all synced async via
+    # InventoryItems::BulkAdjustQuantities(OnHold), which uses per-record `update!`, so this callback
+    # does fire for those, just after that job's own async DB sync lands), and admin stock edits via
+    # `adjust_quantity!`. A burst of concurrent changes to the same event collapses into one in-flight
+    # publish, since PublishStockStatusesToFirestoreJob is unique per event_id (ApplicationUniqueJob,
+    # until_executed).
+    #
+    # Ecommerce-only and quantity-changed-only, same guard shape as schedule_product_cache_invalidation
+    # above, but checking all four quantity columns (not just available/locked) since quantity_on_hold
+    # alone can flip the published bucket to/from pending_hold.
+    def publish_live_stock_status_to_firestore
+      return unless ecommerce?
+      return unless saved_change_to_quantity_available? || saved_change_to_quantity_on_hold? ||
+        saved_change_to_quantity_locked? || saved_change_to_quantity_locked_on_hold?
+
+      event_id = variant.product.event_id
+      return if event_id.nil?
+
+      SpreeCmCommissioner::PublishStockStatusesToFirestoreJob.perform_later(event_id: event_id)
+    end
+
     # Both pools as they stood before this save. saved_change_to_* is nil for a column that did not
     # change, so an unchanged pool falls back to its current value rather than to zero.
     def total_quantity_before_last_save

data/app/models/spree_cm_commissioner/taxon_decorator.rb

@@ -101,7 +101,7 @@ module SpreeCmCommissioner
       base.scope :ad_campaigns, -> { where(taxonomy_id: Spree::Taxonomy.ads.id, depth: 1) }
 
       # Event taxons currently inside their live-stock sale window — see
-      # SpreeCmCommissioner::StockStatusPollJob, which only publishes to Firestore for events
+      # SpreeCmCommissioner::StockStatusConsolidationJob, which only publishes to Firestore for events
       # matched by this scope. `live_stock_starts_at`/`live_stock_ends_at` are only meaningful for
       # `kind: :event` taxons (same convention as `from_date`/`to_date`) — a null on either side
       # naturally excludes the row here, since SQL's <=/>= against NULL is never true.

data/app/services/spree_cm_commissioner/events/publish_stock_statuses_to_firestore.rb

@@ -1,12 +1,13 @@
 module SpreeCmCommissioner
   module Events
     # Publishes live stock status for every active ecommerce product under a live event taxon to
-    # Firestore — batched per event: one aggregate SQL query, at most one Firestore read, and at
-    # most one Firestore write per call, regardless of how many products changed. Driven by
-    # SpreeCmCommissioner::StockStatusPollJob on a schedule (see
-    # plans/2026-08-24-realtime-stock-status/plan.md), not by individual inventory saves — this
-    # replaced the old after_commit-per-change trigger, specifically to bound Firestore
-    # write/read volume when many events are live and selling concurrently.
+    # Firestore — batched per event: quantities are read from Redis (the real-time source of truth
+    # for available/on-hold/locked pools, see docs/concepts/inventory-system.md — the InventoryItem
+    # DB columns lag behind until InventoryItems::BulkAdjustQuantities catches up asynchronously),
+    # at most one Firestore read, and at most one Firestore write per call, regardless of how many
+    # products changed. Driven both by SpreeCmCommissioner::PublishStockStatusesToFirestoreJob
+    # (real-time, enqueued off order-complete) and SpreeCmCommissioner::StockStatusConsolidationJob
+    # (a low-frequency safety-net sweep) — see plans/2026-08-24-realtime-stock-status/plan.md.
     #
     # Firestore layout unchanged from the old design: events/{event_id} with a nested `products`
     # map field. `message` is pre-translated per locale (config/locales/*.yml#stock_status), `name`
@@ -40,22 +41,12 @@ module SpreeCmCommissioner
 
         changed = {}
         products.each do |product|
-          available, on_hold, locked = sums[product.id] || [0, 0, 0]
-          status = bucket_stock_status(available, on_hold, locked)
-
-          next unless changed?(existing_products[product.id.to_s], status, available, on_hold)
-
-          previous_status = existing_products.dig(product.id.to_s, 'status')&.to_sym
-
-          changed[product.id.to_s] = {
-            name: product.name,
-            status: status.to_s,
-            previous_status: previous_status&.to_s,
-            message: localized_message(status),
-            quantity_available: available,
-            quantity_on_hold: on_hold,
-            updated_at: now
-          }
+          quantities = sums[product.id] || [0, 0, 0, 0]
+          status = bucket_stock_status(*quantities.first(3))
+
+          next unless changed?(existing_products[product.id.to_s], status, quantities[0], quantities[1])
+
+          changed[product.id.to_s] = build_entry(product, status, quantities, existing_products, now)
         end
 
         return success(:unchanged) if changed.empty?
@@ -64,14 +55,35 @@ module SpreeCmCommissioner
 
         success(changed.keys)
       rescue StandardError => e
-        # A Firestore outage (or any error for one event) must not take the poll job's other live
-        # events down with it — the job wraps each taxon's call individually for this reason.
+        # A Firestore outage (or any error for one event) must not take the caller's other live
+        # events down with it — both the real-time job and the consolidation sweep call this
+        # per-taxon and expect one event's failure to be isolated from the rest.
         Rails.logger.error("[Events::PublishStockStatusesToFirestore] taxon=#{taxon.id} #{e.class}: #{e.message}")
         failure(nil, e.message)
       end
 
       private
 
+      # `quantities` is the [available, on_hold, locked, locked_on_hold] tuple from
+      # `aggregate_quantities`. `previous_status` is read back from what's already stored, not
+      # recomputed — it's the bucket this product was in on the last publish, if any.
+      def build_entry(product, status, quantities, existing_products, now)
+        available, on_hold, locked, locked_on_hold = quantities
+        previous_status = existing_products.dig(product.id.to_s, 'status')&.to_sym
+
+        {
+          name: product.name,
+          status: status.to_s,
+          previous_status: previous_status&.to_s,
+          message: localized_message(status, available),
+          quantity_available: available,
+          quantity_on_hold: on_hold,
+          quantity_locked: locked,
+          quantity_locked_on_hold: locked_on_hold,
+          updated_at: now
+        }
+      end
+
       # Buckets a (quantity_available, quantity_on_hold) pair into one of the four stock-status
       # symbols. `locked` only ever flips a would-be sold_out into pending_hold — see below — it
       # never feeds the low_stock/in_stock math, which stays public-pool only.
@@ -82,7 +94,6 @@ module SpreeCmCommissioner
       # "real stock exists but the public can't have it right now" situation `pending_hold` already
       # describes for held-by-other-checkouts stock, and its message ("In high demand") is exactly
       # as non-committal here, without naming the reserve the way a more specific bucket would.
-      # `locked` itself is never included in the published payload, only used to pick the bucket.
       def bucket_stock_status(available, on_hold, locked = 0)
         return PENDING_HOLD if available <= 0 && locked.positive?
         return SOLD_OUT if available <= 0
@@ -117,27 +128,45 @@ module SpreeCmCommissioner
              .where('discontinue_on IS NULL OR discontinue_on > ?', now)
       end
 
-      # One aggregate query for every active product's sums, keyed by product id — avoids an N+1
-      # that would come from summing each product's inventory items one at a time.
+      # Sums, per product id, of the live Redis-sourced quantities for every active inventory item
+      # under these products — avoids an N+1 that would come from summing each product's inventory
+      # items one at a time. Reuses RedisStock::CachedInventoryItemsBuilder (already the gem's
+      # standard "Redis is live, DB is cache-warm fallback" read path — one MGET across all pools,
+      # DB value used + cache seeded via SET NX on a cold key) rather than the InventoryItem DB
+      # columns directly, since those lag behind Redis until InventoryItems::BulkAdjustQuantities
+      # catches up asynchronously.
       #
       # quantity_locked (the operator-allotment pool — see cm_inventory_items migration
-      # `AddLockedQuantitiesToCmInventoryItems`) is summed too, but ONLY so `bucket_stock_status`
-      # can tell "genuinely zero everywhere" apart from "public pool empty, but real stock exists in
-      # the withheld pool." Its exact quantity is deliberately never surfaced beyond that: it's not
-      # part of the low_stock/in_stock math, and it never appears in the published Firestore payload
-      # (only quantity_available/quantity_on_hold do). Anything more than presence/absence here would
-      # start advertising the private allotment to every viewer of this broadcast doc, not just the
-      # one customer `Stock::AvailabilityChecker`/`AvailabilityValidatorDecorator` are allowed to hint
-      # to via a targeted add-to-cart refusal.
+      # `AddLockedQuantitiesToCmInventoryItems`) is summed for `bucket_stock_status`, which needs it
+      # to tell "genuinely zero everywhere" apart from "public pool empty, but real stock exists in
+      # the withheld pool." quantity_locked and quantity_locked_on_hold are ALSO published verbatim
+      # in the Firestore payload below, for operator/debug visibility — deliberate per the user's
+      # explicit request, despite `events/{event_id}` being publicly readable (no auth on the
+      # Firestore security rule): anyone reading the doc can see the private allotment's size.
       def aggregate_quantities(products)
+        items = active_inventory_items(products).to_a
+        return {} if items.empty?
+
+        cached_by_item_id = SpreeCmCommissioner::RedisStock::CachedInventoryItemsBuilder.new(items).call.index_by(&:inventory_item_id)
+
+        items.each_with_object(Hash.new { |h, k| h[k] = [0, 0, 0, 0] }) do |item, sums_by_product|
+          cached = cached_by_item_id[item.id]
+          sums = sums_by_product[item.resolved_product_id]
+          sums[0] += cached.quantity_available
+          sums[1] += cached.quantity_on_hold
+          sums[2] += cached.quantity_locked
+          sums[3] += cached.quantity_locked_on_hold
+        end
+      end
+
+      # `resolved_product_id` is an extra-select column, not a real InventoryItem attribute — lets
+      # the caller above resolve each item's product id without an N+1 `item.variant.product_id`
+      # lookup per item.
+      def active_inventory_items(products)
         SpreeCmCommissioner::InventoryItem.active
                                           .joins(variant: :product)
                                           .where(spree_products: { id: products.map(&:id) })
-                                          .group('spree_products.id')
-                                          .pluck('spree_products.id', 'SUM(quantity_available)', 'SUM(quantity_on_hold)', 'SUM(quantity_locked)')
-                                          .each_with_object({}) do |(id, available, on_hold, locked), memo|
-          memo[id] = [available.to_i, on_hold.to_i, locked.to_i]
-        end
+                                          .select('cm_inventory_items.*, spree_products.id AS resolved_product_id')
       end
 
       # Bucket transitions always count; a same-bucket change only counts while LOW_STOCK (the one
@@ -168,10 +197,17 @@ module SpreeCmCommissioner
       # Pre-translated, per-locale copy baked in at publish time — see
       # config/locales/*.yml#stock_status. nil for in_stock: the design has no badge for the common
       # case, and omitting the field is what tells the client that directly.
-      def localized_message(status)
+      #
+      # low_stock interpolates `available` into the translation (`%{count}`, pluralized) so the
+      # exact "N left" pill text is built once here rather than duplicated client-side from the
+      # bare `quantity_available` field — the client just displays this string verbatim (see
+      # `cm_ticket_availability_card.dart`'s `_StatusDisplay._label`).
+      def localized_message(status, available)
         return nil if status == IN_STOCK
 
-        I18n.available_locales.index_with { |locale| I18n.t("stock_status.#{status}", locale: locale) }
+        I18n.available_locales.index_with do |locale|
+          I18n.t("stock_status.#{status}", count: available, locale: locale)
+        end
       end
     end
   end

data/app/services/spree_cm_commissioner/inventory_items/bulk_adjust_quantities.rb

@@ -86,7 +86,7 @@ module SpreeCmCommissioner
       end
 
       def inventory_items(inventory_id_and_quantities)
-        SpreeCmCommissioner::InventoryItem.where(id: inventory_id_and_quantities.pluck(:inventory_id))
+        SpreeCmCommissioner::InventoryItem.where(id: inventory_id_and_quantities.pluck(:inventory_id)).includes(variant: :product)
       end
     end
   end

data/app/services/spree_cm_commissioner/inventory_items/bulk_adjust_quantities_on_hold.rb

@@ -92,7 +92,7 @@ module SpreeCmCommissioner
       end
 
       def inventory_items(inventory_id_and_quantities)
-        SpreeCmCommissioner::InventoryItem.where(id: inventory_id_and_quantities.pluck(:inventory_id))
+        SpreeCmCommissioner::InventoryItem.where(id: inventory_id_and_quantities.pluck(:inventory_id)).includes(variant: :product)
       end
     end
   end

data/config/locales/en.yml

@@ -991,7 +991,9 @@ en:
   # SpreeCmCommissioner::Products::PublishStockStatusToFirestore) — not read via I18n at request
   # time, so every locale we publish for must have an entry here.
   stock_status:
-    low_stock: "Only a few left!"
+    low_stock:
+      one: "%{count} left"
+      other: "%{count} left"
     pending_hold: "In high demand"
     sold_out: "Sold out"
 

data/config/locales/km.yml

@@ -606,7 +606,9 @@ km:
       hold_cooldown: "ការកក់មុនរបស់អ្នកទើបតែផុតកំណត់។ សូមរង់ចាំពីរបីនាទី មុនពេលកក់ម្តងទៀត។"
 
   stock_status:
-    low_stock: "នៅសល់តិចទៀតប៉ុណ្ណោះ!"
+    low_stock:
+      one: "នៅសល់ %{count}"
+      other: "នៅសល់ %{count}"
     pending_hold: "តម្រូវការខ្ពស់"
     sold_out: "លក់អស់"
 

data/lib/spree_cm_commissioner/version.rb

@@ -1,5 +1,5 @@
 module SpreeCmCommissioner
-  VERSION = '2.12.0-pre2'.freeze
+  VERSION = '2.12.0'.freeze
 
   module_function
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spree_cm_commissioner
 version: !ruby/object:Gem::Version
-  version: 2.12.0.pre.pre2
+  version: 2.12.0
 platform: ruby
 authors:
 - You
@@ -1420,6 +1420,7 @@ files:
 - app/jobs/spree_cm_commissioner/payment_incomplete_notification_job.rb
 - app/jobs/spree_cm_commissioner/payment_references/aba_csv_import_job.rb
 - app/jobs/spree_cm_commissioner/product_event_id_to_children_syncer_job.rb
+- app/jobs/spree_cm_commissioner/publish_stock_statuses_to_firestore_job.rb
 - app/jobs/spree_cm_commissioner/queue_draft_orders/process_job.rb
 - app/jobs/spree_cm_commissioner/queue_order_webhooks_requests_job.rb
 - app/jobs/spree_cm_commissioner/reports_assigner_job.rb
@@ -1434,7 +1435,7 @@ files:
 - app/jobs/spree_cm_commissioner/sms_job.rb
 - app/jobs/spree_cm_commissioner/sms_pin_code_job.rb
 - app/jobs/spree_cm_commissioner/state_job.rb
-- app/jobs/spree_cm_commissioner/stock_status_poll_job.rb
+- app/jobs/spree_cm_commissioner/stock_status_consolidation_job.rb
 - app/jobs/spree_cm_commissioner/subscription_order_executor_job.rb
 - app/jobs/spree_cm_commissioner/telegram_alerts/integration_sync_failure_job.rb
 - app/jobs/spree_cm_commissioner/telegram_alerts/order_integrity_check_job.rb
@@ -3762,9 +3763,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements:
 - none
 rubygems_version: 3.4.1

data/app/jobs/spree_cm_commissioner/stock_status_poll_job.rb

@@ -1,26 +0,0 @@
-module SpreeCmCommissioner
-  # Scheduled every 10s via sidekiq-cron (cm-market-server/config/schedule.yml, `stock_status_poll`
-  # entry, dispatched through the existing `InvokeJob` cron pattern — same mechanism already used
-  # for `WaitingRoom::StampQueuePositionsJob`/`Integrations::PollingSchedulerJob`).
-  #
-  # Replaced the old after_commit-per-change trigger on InventoryItem — see
-  # plans/2026-08-24-realtime-stock-status/plan.md for why: job/write volume there scaled with the
-  # number of stock *changes* across every event at once, not with the number of live events. This
-  # scopes to events currently inside their live_stock_starts_at/live_stock_ends_at window (see
-  # Spree::Taxon.live_stock_active) and delegates the actual (batched, per-event) Firestore write
-  # to Events::PublishStockStatusesToFirestore.
-  #
-  # ApplicationUniqueJob (not ApplicationJob) so a cycle that runs long — many live events, a slow
-  # Firestore round trip — can't overlap with the next cron tick 10s later; `perform` takes no
-  # arguments, so this is a single global "is a poll cycle already in flight" lock, same pattern as
-  # WaitingRoom::StampQueuePositionsJob above.
-  class StockStatusPollJob < ApplicationUniqueJob
-    queue_as :default
-
-    def perform
-      Spree::Taxon.event.live_stock_active.find_each do |taxon|
-        SpreeCmCommissioner::Events::PublishStockStatusesToFirestore.call(taxon: taxon)
-      end
-    end
-  end
-end