spree_cm_commissioner 2.12.0.pre.pre1 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1bcaa0a7cc8d39b507cd072bfd4576b28f72c83f2344b11ef2097306aa8454dd
-  data.tar.gz: bf8156fe0e0f2a41febcacc07188e8b0bbd9b2cd79c3ccad5a8d1394fa307db7
+  metadata.gz: 10936d8185cc09d4bd8eca8c3c2626cb9bb113d2e94695030be009f9b38edbcc
+  data.tar.gz: 8b1493341611af89e52c06017d1abc3ad6adc838a541dd3ec93dd76877985eaf
 SHA512:
-  metadata.gz: 19b750a2f5c27cabbc5c507a0e50424a26e295aefa94369787ff490376475f63e56993950e87a9a1b2c3be624f6ec29f2192a51a7e019bfed05e3ee4dcb54018
-  data.tar.gz: 4acf6f94be21c3960010398b9a431b950b2e3e7bffed455096ea0dc2ed05fca769bd53884b6ed26be86cc11db2a8c220c73711be800bccebf7fc005854454f11
+  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.pre1)
+    spree_cm_commissioner (2.12.0)
       activerecord-multi-tenant
       activerecord_json_validator (~> 2.1, >= 2.1.3)
       aws-sdk-cloudfront

data/app/assets/javascripts/spree_cm_commissioner/backend.js

@@ -12,3 +12,4 @@
 //= require spree_cm_commissioner/location_checkbox_manager
 //= require spree_cm_commissioner/trip_stop_selection
 //= require spree_cm_commissioner/tenant_payment_icon_fields
+//= require spree_cm_commissioner/copy_to_clipboard

data/app/assets/javascripts/spree_cm_commissioner/copy_to_clipboard.js

@@ -0,0 +1,49 @@
+// Copy-to-clipboard for any element carrying data-copy-value.
+//
+// Delegated from document rather than bound per button: the private sales index renders one of these
+// per row, and re-binding on every Turbo page load would stack duplicate listeners on the same nodes.
+//
+// The icon swap is the whole feedback mechanism — without it a click looks like nothing happened.
+document.addEventListener("click", function (event) {
+  const trigger = event.target.closest("[data-copy-value]");
+  if (!trigger) return;
+
+  event.preventDefault();
+  copyText(trigger.dataset.copyValue).then(function () {
+    confirmCopied(trigger);
+  });
+});
+
+// navigator.clipboard needs a secure context, which rules it out on plain-http staging boxes.
+// execCommand is deprecated but is the only thing that works there, so it stays as the fallback.
+function copyText(value) {
+  if (navigator.clipboard && window.isSecureContext) {
+    return navigator.clipboard.writeText(value);
+  }
+
+  const scratch = document.createElement("textarea");
+  scratch.value = value;
+  scratch.setAttribute("readonly", "");
+  scratch.style.position = "fixed";
+  scratch.style.opacity = "0";
+  document.body.appendChild(scratch);
+  scratch.select();
+  document.execCommand("copy");
+  document.body.removeChild(scratch);
+
+  return Promise.resolve();
+}
+
+function confirmCopied(trigger) {
+  const done = trigger.querySelector("[data-copy-done]");
+  const idle = trigger.querySelector("[data-copy-idle]");
+  if (!done || !idle) return;
+
+  idle.style.display = "none";
+  done.style.display = "inline";
+
+  setTimeout(function () {
+    idle.style.display = "inline";
+    done.style.display = "none";
+  }, 1500);
+}

data/app/controllers/spree/admin/inventory_locks_controller.rb

@@ -0,0 +1,134 @@
+module Spree
+  module Admin
+    # Withholds units of one product from public sale.
+    #
+    # Reached only from a private sale — there is no tab or sidebar entry. `create` is the POST target
+    # for the per-variant inputs on Spree::Admin::PrivateSalesController#edit, and `index` is the
+    # date-range screen that page links to for permanent-stock products, where one variant has an
+    # inventory item per date and a single input cannot express the range.
+    #
+    # All the accounting lives in InventoryItems::MoveToLocked — this controller resolves the
+    # product, calls it, and turns its named failures into flash messages.
+    #
+    class InventoryLocksController < Spree::Admin::ResourceController
+      skip_before_action :load_resource
+
+      before_action :load_parent
+
+      # GET /admin/products/:product_id/inventory_locks
+      def index
+        # Only active items can be locked — a past date cannot be sold, so withholding from it
+        # protects nothing (MoveToLocked refuses it outright).
+        # Paginated like every other admin index here: a permanent-stock product has one row per
+        # variant per date, so an unpaginated page is thousands of rows.
+        @inventory_items = @product.inventory_items.active
+                                   .includes(variant: { option_values: :option_type })
+                                   .order(:inventory_date)
+                                   .page(params[:page]).per(50)
+      end
+
+      # POST /admin/products/:product_id/inventory_locks
+      #
+      # One action for both directions: a positive quantity locks, a negative one releases. Applied
+      # across a date range for permanent-stock products, where each date is its own inventory item —
+      # "lock 5" means 5 per date, not 5 across the range.
+      def create
+        items = target_inventory_items
+        return redirect_with_error(:invalid_date_range) if items.nil?
+        return redirect_with_error(:no_inventory_item) if items.empty?
+
+        moved, failed = items.map { |item| move(item) }.partition(&:success?)
+        return redirect_with_error(failed.first.error.value) if moved.empty?
+
+        # Each date is moved independently and nothing can undo one that already went through —
+        # Redis has no rollback. So a mixed outcome says how many landed: a bare error would read as
+        # "nothing changed" while some dates are already locked.
+        if failed.empty?
+          flash[:success] = t('.moved', count: moved.size)
+        else
+          reason = error_sentence(failed.first.error.value)
+          flash[:error] = t('.partially_moved', count: moved.size, total: items.size, reason: reason)
+        end
+
+        redirect_back_to_caller
+      end
+
+      private
+
+      def load_parent
+        # Handled here rather than left to ResourceController's rescue_from: its handler redirects to
+        # collection_url, which for this controller resolves to a route that does not exist
+        # (model_class is InventoryItem, which has no admin resource route) — turning one 500 into
+        # another. An unknown or renamed slug belongs back at the product list.
+        @product = Spree::Product.find_by(slug: params[:product_id])
+        return if @product
+
+        flash[:error] = t('spree.admin.inventory_locks.create.product_not_found')
+        redirect_to spree.admin_products_path
+      end
+
+      def move(inventory_item)
+        SpreeCmCommissioner::InventoryItems::MoveToLocked.call(
+          inventory_item: inventory_item,
+          quantity: params[:quantity],
+          caller_source: "#{self.class.name}#create"
+        )
+      end
+
+      # A date range covers one inventory item per date; without one, ONLY the undated row.
+      #
+      # Never falls back to "every active date". Both callers can omit the range — the private sale's
+      # inline button always does — and a permanent-stock variant has a row per date for a year, so
+      # withholding across all of them because an operator left "To date" empty is unrecoverable:
+      # MoveToLocked's Redis half cannot be rolled back.
+      #
+      # Returns nil for a malformed range so #create can tell it apart from "found nothing".
+      def target_inventory_items
+        scope = @product.inventory_items.active.where(variant_id: params[:variant_id])
+        return scope.where(inventory_date: nil).to_a if params[:from_date].blank? || params[:to_date].blank?
+
+        dates = parsed_date_range
+        return nil if dates.nil?
+
+        scope.where(inventory_date: dates).to_a
+      end
+
+      # nil when either date is unparseable, or when the range runs backwards — both are operator
+      # error, and an empty result would report the misleading "no stock on sale" instead.
+      def parsed_date_range
+        from = params[:from_date].to_date
+        to = params[:to_date].to_date
+        return nil if from > to
+
+        from..to
+      # Date::Error subclasses ArgumentError, so this covers both.
+      rescue ArgumentError
+        nil
+      end
+
+      def redirect_with_error(reason)
+        flash[:error] = error_sentence(reason)
+        redirect_back_to_caller
+      end
+
+      # MoveToLocked's named failures carry their sentences; this controller's own reasons (a variant
+      # with no inventory item) are local. Falls back to the humanized symbol so a new failure name
+      # still reads as English rather than as a missing-translation string.
+      def error_sentence(reason)
+        service_message = t("spree_cm_commissioner.inventory_items.move_to_locked.#{reason}", default: reason.to_s.humanize)
+
+        t(".#{reason}", default: service_message)
+      end
+
+      # Posted from the private sale's edit page for undated stock, and from this screen for
+      # permanent-stock date ranges, so return to whichever asked.
+      def redirect_back_to_caller
+        redirect_back fallback_location: admin_product_inventory_locks_path(@product)
+      end
+
+      def model_class
+        SpreeCmCommissioner::InventoryItem
+      end
+    end
+  end
+end

data/app/controllers/spree/admin/private_sales_controller.rb

@@ -0,0 +1,116 @@
+module Spree
+  module Admin
+    # Managing private sales: which products, sold to whom, until when — and, on edit, how much of
+    # each variant to withhold.
+    #
+    # New is deliberately thin: name, dates and three remote-search pickers, so opening it costs one
+    # query for roles and nothing else. Creating redirects straight to edit, which is where the
+    # allotment is actually set up now that the products are known.
+    #
+    class PrivateSalesController < Spree::Admin::ResourceController
+      # Also on update: ResourceController re-renders :edit when validation fails, and the stock
+      # partial reads these ivars — without this a rejected save is a 500 instead of a form.
+      before_action :load_stock_rows, only: %i[edit update]
+      before_action :load_assignable_roles, only: %i[new create edit update]
+
+      # GET /admin/private_sales
+      def index
+        # Off `collection`, which ResourceController already scoped with accessible_by(current_ability)
+        # — going through model_class directly would discard that.
+        @private_sales = collection.order(created_at: :desc).page(params[:page]).per(25)
+
+        load_audience_names
+      end
+
+      # PATCH /admin/private_sales/:id/revoke
+      #
+      # The point of storing the rule rather than signing it into the URL: one sale dies without
+      # touching the lock, so every other sale drawing on the same stock keeps working.
+      def revoke
+        # @private_sale is already loaded and authorized by ResourceController#load_resource.
+        @private_sale.revoked!
+
+        flash[:success] = t('.revoked')
+        redirect_to admin_private_sales_path
+      end
+
+      private
+
+      # Names for every product, user and role named by the sales ON THIS PAGE, in three queries.
+      # The ids live in jsonb rather than join tables, so there is no association for `includes` to
+      # preload — asking each row for its own would be 3 queries per row.
+      def load_audience_names
+        sales = @private_sales.to_a
+
+        @product_names = Spree::Product.where(id: sales.flat_map(&:product_ids)).pluck(:id, :name).to_h
+        @user_emails = Spree::User.where(id: sales.flat_map(&:user_ids)).pluck(:id, :email).to_h
+        @role_names = Spree::Role.where(id: sales.flat_map(&:role_ids))
+                                 .pluck(:id, :presentation, :name)
+                                 .to_h { |id, presentation, name| [id, presentation.presence || name] }
+      end
+
+      # Straight to edit rather than back to the list: a sale is not usable until stock is withheld
+      # for it, and edit is where that happens. Landing on the index would hide the next step.
+      # non_vendor: a private sale grants access across the store, and this repo's roles include
+      # per-vendor and per-event check-in roles whose `presentation` is only unique within a vendor —
+      # listing them all renders hundreds of indistinguishable duplicate options.
+      def load_assignable_roles
+        @assignable_roles = Spree::Role.non_vendor.order(:name)
+      end
+
+      def location_after_save
+        edit_admin_private_sale_path(@private_sale)
+      end
+
+      # Everything the edit page's per-variant lock controls need, in three queries regardless of how
+      # many products the sale names.
+      #
+      # Only UNDATED inventory items are loaded. A permanent-stock product has one row per date —
+      # hundreds per variant — which no inline control can express and which would make this page as
+      # slow as the table is large. Those link out to the product's own date-range screen instead.
+      def load_stock_rows
+        product_ids = @private_sale.product_ids
+        return @variants_by_product = {} if product_ids.empty?
+
+        @products_by_id = Spree::Product.where(id: product_ids).index_by(&:id)
+
+        # Master is excluded when a product has real variants — it carries no stock of its own there
+        # and would render as a blank row. A product with no variants sells through master, so it is
+        # the fallback. Same rule as Spree::Admin::StockManagementsController.
+        # option_values: :option_type, not just :option_values — sku_and_options_text walks the second
+        # hop, so preloading one level still fires a query per option value.
+        variants = Spree::Variant.where(product_id: product_ids)
+                                 .includes(option_values: :option_type)
+                                 .order(:id)
+        by_product = variants.group_by(&:product_id)
+
+        @variants_by_product = by_product.transform_values do |list|
+          list.reject(&:is_master?).presence || list
+        end
+
+        @inventory_item_by_variant = SpreeCmCommissioner::InventoryItem
+                                     .where(variant_id: @variants_by_product.values.flatten.map(&:id), inventory_date: nil)
+                                     .index_by(&:variant_id)
+      end
+
+      # override — the audience is posted as id arrays by the select2 pickers in _form.
+      def permitted_resource_params
+        params.require(:private_sale)
+              .permit(:name, :expires_at, product_ids: [], role_ids: [], user_ids: [])
+      end
+
+      # override — created_by is ours to set, never the form's.
+      def build_resource
+        model_class.new(created_by: try_spree_current_user)
+      end
+
+      def collection_url(options = {})
+        admin_private_sales_path(options)
+      end
+
+      def model_class
+        SpreeCmCommissioner::PrivateSale
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v2/storefront/draft_orders_controller.rb

@@ -10,13 +10,18 @@ module Spree
           # Endpoint: POST /api/v2/storefront/draft_orders
           # Params:
           # - line_items: Array of { variant_id:, quantity:, options: {}, public_metadata: {}, private_metadata: {} } (required)
+          # - st: private sale token granting this order the product's locked stock (optional).
           def create
             result = SpreeCmCommissioner::DraftOrders::Create.call(
               line_items: draft_order_line_items,
               user: spree_current_user,
               store: current_store,
               currency: current_currency,
-              options: { device_id: device_id, last_ip_address: request.remote_ip }
+              options: {
+                device_id: device_id,
+                last_ip_address: request.remote_ip,
+                private_sale_token: params[:st]
+              }
             )
 
             if result.success?

data/app/controllers/spree/api/v2/storefront/private_sale_products_controller.rb

@@ -0,0 +1,34 @@
+module Spree
+  module Api
+    module V2
+      module Storefront
+        # GET /api/v2/storefront/private_sale_products?st=<private sale token>
+        class PrivateSaleProductsController < ::Spree::Api::V2::Storefront::ProductsController
+          before_action :require_spree_current_user
+          before_action :authorize_private_sale_token!
+
+          private
+
+          attr_reader :private_sale
+
+          def authorize_private_sale_token!
+            result = SpreeCmCommissioner::PrivateSales::Authorize.call(
+              token: params[:st],
+              user: spree_current_user
+            )
+
+            return @private_sale = result.value if result.success?
+
+            render_error_payload(SpreeCmCommissioner::PrivateSales::Authorize.error_message(result.error.value), 403)
+          end
+
+          # override — the token names the products, so the client sends no ids. Returns them as a
+          # collection: one link is an agent's whole allotment across an event, not a single product.
+          def scope(**args)
+            super.where(id: private_sale.product_ids)
+          end
+        end
+      end
+    end
+  end
+end

data/app/controllers/spree/api/v2/storefront/queue_draft_orders_controller.rb

@@ -15,6 +15,7 @@ module Spree
           # Endpoint: POST /api/v2/storefront/queue_draft_orders
           # Params: same as POST /api/v2/storefront/draft_orders — line_items: Array of
           #   { variant_id:, quantity:, options: {}, public_metadata: {}, private_metadata: {} } (required)
+          #   st: private sale token granting this order the product's locked stock (optional).
           def create
             result = SpreeCmCommissioner::QueueDraftOrders::Enqueue.call(
               create_type: 'generic',
@@ -23,7 +24,11 @@ module Spree
                 user: spree_current_user,
                 store: current_store,
                 currency: current_currency,
-                options: { device_id: device_id, last_ip_address: request.remote_ip }
+                options: {
+                  device_id: device_id,
+                  last_ip_address: request.remote_ip,
+                  private_sale_token: params[:st]
+                }
               },
               locale: I18n.locale.to_s
             )

data/app/controllers/spree/api/v2/storefront/waiting_room_sessions_controller.rb

@@ -15,7 +15,10 @@ module Spree
               remote_ip: request.remote_ip,
               waiting_guest_firebase_doc_id: params[:waiting_guest_firebase_doc_id],
               page_path: params[:page_path],
-              device_attributes: permitted_device_attributes
+              device_attributes: permitted_device_attributes,
+              bypass_jwt: params[:bypass_jwt],
+              bypass_order_token: request.headers['X-Spree-Order-Token'],
+              user: spree_current_user
             )
 
             if context.success?

data/app/controllers/spree/api/v2/tenant/draft_orders_controller.rb

@@ -7,6 +7,7 @@ module Spree
           # Endpoint: POST /api/v2/tenant/draft_orders
           # Params:
           # - line_items: Array of { variant_id:, quantity:, options: {}, public_metadata: {}, private_metadata: {} } (required)
+          # - st: private sale token granting this order the product's locked stock (optional).
           def create
             result = SpreeCmCommissioner::DraftOrders::Create.call(
               line_items: draft_order_line_items,
@@ -14,7 +15,11 @@ module Spree
               store: current_store,
               currency: current_currency,
               tenant: @tenant,
-              options: { device_id: params[:device_id], last_ip_address: request.remote_ip }
+              options: {
+                device_id: params[:device_id],
+                last_ip_address: request.remote_ip,
+                private_sale_token: params[:st]
+              }
             )
 
             if result.success?

data/app/interactors/spree_cm_commissioner/waiting_room_session_creator.rb

@@ -4,7 +4,7 @@ require 'zlib'
 module SpreeCmCommissioner
   class WaitingRoomSessionCreator < BaseInteractor
     delegate :remote_ip, :waiting_guest_firebase_doc_id, :page_path, :tenant_id,
-             :device_attributes, to: :context
+             :device_attributes, :bypass_jwt, :bypass_order_token, :user, to: :context
 
     SESSION_CREATION_LOCK_KEY = 'waiting_room_session_creation'.freeze
 
@@ -18,6 +18,12 @@ module SpreeCmCommissioner
     # How long a session's JWT/expired_at is valid before it needs renewal. 3min default.
     WAITING_ROOM_SESSION_EXPIRE_DURATION_IN_SECOND = (ENV['WAITING_ROOM_SESSION_EXPIRE_DURATION_IN_SECOND'] || (60 * 3)).to_i
 
+    # A verified bypasser is admitted past the normal max, but only up to this bounded headroom
+    # (max * multiplier) — never without limit — so a burst of stuck-payment returns can't push the
+    # protected pages far past capacity. Default 1.1 (10% headroom); 1 gates bypassers at max. See
+    # #bypass_full?.
+    WAITING_ROOM_BYPASS_HEADROOM_MULTIPLIER = (ENV['WAITING_ROOM_BYPASS_HEADROOM_MULTIPLIER'] || 1.1).to_f
+
     # Device attributes the client may set on the session. device_id and
     # device_fingerprint are real columns; the rest are virtual columns backed by
     # public/private metadata (see WaitingRoomSession). Anything else the client
@@ -76,11 +82,17 @@ module SpreeCmCommissioner
     # a row that's lapsed but still under its own max_expired_at — goes through the normal
     # advisory-lock + full? gated path.
     def create_new_session
+      # Checked before the lock, not inside it — the lock is the capacity serialization point and
+      # shouldn't be held any longer than necessary. A normal joiner short-circuits here for free.
+      bypass = bypass_session?
+
       # Advisory lock ensures the capacity check and session creation are atomic across all app instances.
       advisory_lock(SESSION_CREATION_LOCK_KEY) do
-        return context.fail!(message: 'sessions_reach_it_maximum') if full?
+        # Normal joiner is gated at max (full?); a verified bypasser at the higher, bounded ceiling
+        # (bypass_full?), so a full room still admits bypassers only up to the overshoot.
+        return context.fail!(message: 'sessions_reach_it_maximum') if bypass ? bypass_full? : full?
 
-        assign_token_and_create_session_to_db
+        assign_token_and_create_session_to_db(bypass: bypass)
       end
 
       # commented because of following bug: https://github.com/channainfo/commissioner/issues/2185
@@ -88,14 +100,42 @@ module SpreeCmCommissioner
       # call_other_waiting_guests
     end
 
+    # Whether this admission may skip full?. The client relays a signed token plus the order token it
+    # was signed with (the X-Spree-Order-Token header) — WaitingRoom::BypassEligibility decides, from that
+    # single verified decode plus the caller's own auth (see BypassEligibility#owned_by_caller?),
+    # whether it's genuine. Both must be present before we even look, so a normal joiner pays nothing.
+    def bypass_session?
+      return false if bypass_jwt.blank? || bypass_order_token.blank?
+
+      bypass_result.success?
+    end
+
+    # Memoized so #apply_bypass_attributes can read the verified payment number/source back off the
+    # result (result.value) without re-running the verify. `user` is the same doorkeeper-resolved
+    # caller already stamped on the session (nil for an app token/anonymous request).
+    def bypass_result
+      @bypass_result ||= SpreeCmCommissioner::WaitingRoom::BypassEligibility.call(
+        jwt: bypass_jwt, order_token: bypass_order_token, user: user
+      )
+    end
+
     def full?
-      max = Rails.cache.fetch('waiting_room/max_sessions_count', expires_in: 1.hour) do
+      SpreeCmCommissioner::WaitingRoomSession.active.count >= max_sessions_count
+    end
+
+    # Higher, bounded ceiling used only for a verified bypasser: max plus the headroom
+    # (max * WAITING_ROOM_BYPASS_HEADROOM_MULTIPLIER, floored). Once the room reaches it, even a
+    # bypasser is rejected. Never called on the normal-joiner path, so the hot path is unchanged.
+    def bypass_full?
+      SpreeCmCommissioner::WaitingRoomSession.active.count >= (max_sessions_count * WAITING_ROOM_BYPASS_HEADROOM_MULTIPLIER).floor
+    end
+
+    def max_sessions_count
+      Rails.cache.fetch('waiting_room/max_sessions_count', expires_in: 1.hour) do
         fetcher = SpreeCmCommissioner::WaitingRoomSystemMetadataFetcher.new(firestore: firestore)
         fetcher.load_document_data
         fetcher.max_sessions_count_with_min
       end
-
-      SpreeCmCommissioner::WaitingRoomSession.active.count >= max
     end
 
     def advisory_lock(lock_key)
@@ -111,7 +151,7 @@ module SpreeCmCommissioner
       context.jwt_token = JWT.encode(payload, ENV.fetch('WAITING_ROOM_SESSION_SIGNATURE'), 'HS256')
     end
 
-    def assign_token_and_create_session_to_db
+    def assign_token_and_create_session_to_db(bypass: false)
       session = SpreeCmCommissioner::WaitingRoomSession.where(guest_identifier: waiting_guest_firebase_doc_id).first_or_initialize
       context.room_session = session
 
@@ -123,9 +163,17 @@ module SpreeCmCommissioner
       generate_jwt_token(session.max_expired_at)
 
       apply_session_attributes(session)
+      apply_bypass_attributes(session) if bypass
       session.save!
     end
 
+    # Server-set audit trail for a granted bypass — never client-supplied.
+    def apply_bypass_attributes(session)
+      session.bypassed = true
+      session.bypass_payment_number = bypass_result.value[:payment_number]
+      session.bypass_source = bypass_result.value[:source]
+    end
+
     def apply_session_attributes(session)
       session.assign_attributes(
         {
@@ -133,7 +181,8 @@ module SpreeCmCommissioner
           expired_at: expired_at,
           remote_ip: remote_ip,
           page_path: page_path,
-          tenant_id: tenant_id
+          tenant_id: tenant_id,
+          user: user
         }.merge(sanitized_device_attributes)
       )
     end

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

@@ -4,6 +4,7 @@ module SpreeCmCommissioner
     include SpreeCmCommissioner::StoreMetadata
 
     MAX_DISPLAY_STOCK = 20
+    LOW_STOCK_THRESHOLD = 20
 
     # Association
     belongs_to :variant, class_name: 'Spree::Variant', optional: false
@@ -34,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),
@@ -54,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