Module: Models::CustomerLifecycle

Extended by:
ActiveSupport::Concern
Included in:
Customer
Defined in:
app/concerns/models/customer_lifecycle.rb

Overview

State machine, merge lock, customer state derivation, and account-closure hooks.

See Also:

Instance Method Summary collapse

Instance Method Details

#blocked_for_opportunities? ⇒ Boolean

Whether new opportunities are blocked (customer is closed).

Returns:

  • (Boolean) 


185
186
187
 
# File 'app/concerns/models/customer_lifecycle.rb', line 185

def blocked_for_opportunities?
  customer.closed?
end

#blocked_for_orders? ⇒ Boolean

Whether new orders are blocked (customer is closed or bankrupt).

Returns:

  • (Boolean) 


192
193
194
 
# File 'app/concerns/models/customer_lifecycle.rb', line 192

def blocked_for_orders?
  customer.closed? || customer.bankrupt?
end

#can_be_merged? ⇒ Boolean

Whether the customer may enter a merge (not currently mid-merge).

Returns:

  • (Boolean) 


128
129
130
 
# File 'app/concerns/models/customer_lifecycle.rb', line 128

def can_be_merged?
  !merging?
end

#completed_sales_orders_present? ⇒ Boolean

Whether the customer has any shipped or invoiced sales orders.

Returns:

  • (Boolean) 


146
147
148
 
# File 'app/concerns/models/customer_lifecycle.rb', line 146

def completed_sales_orders_present?
  orders.so_only.exists?(state: %w[shipped invoiced])
end

#customer ⇒ Customer

Self-reference used by shared helpers that expect a customer accessor on
the target record.

Returns:



239
240
241
 
# File 'app/concerns/models/customer_lifecycle.rb', line 239

def customer
  self
end

#determine_customer_state ⇒ Symbol

Computes the lifecycle state this customer should be in, based on its
contactability, completed orders, and open opportunities/carts.

Returns:

  • (Symbol) —

    one of :guest, :lead_qualify, :customer, :prospect, :lead



162
163
164
165
166
167
168
169
170
171
172
 
# File 'app/concerns/models/customer_lifecycle.rb', line 162

def determine_customer_state
  if guest?
    contactable? ? :lead_qualify : :guest
  elsif completed_sales_orders_present?
    :customer
  elsif opportunities_or_cart_present?
    :prospect
  else
    :lead
  end
end

#exclude_manually_initiated_event?(event) ⇒ Boolean

Identifies lifecycle events that should be excluded from manual-event handling.

Parameters:

  • event (String, Symbol) —

    lifecycle event name

Returns:

  • (Boolean) —

    whether the event is excluded



108
109
110
 
# File 'app/concerns/models/customer_lifecycle.rb', line 108

def exclude_manually_initiated_event?(event)
  %i[merge_lock].include?(event.to_sym)
end

#leadify ⇒ void

This method returns an undefined value.

Moves a guest/unstated customer into lead_qualify and turns on the
lead-verification requirements (email, contact) — required for
organization profiles.



208
209
210
211
212
 
# File 'app/concerns/models/customer_lifecycle.rb', line 208

def leadify
  self.state = 'lead_qualify' if guest? || state.nil?
  self.must_have_email = true
  self.must_have_one_contact = self.perform_lead_verification = (profile && profile.organization?)
end

#ok_to_delete? ⇒ Boolean

Whether the customer may be safely deleted — no open opportunities,
quotes, orders, support cases, invoices, or credit memos.

Returns:

  • (Boolean) 


218
219
220
221
222
223
224
225
 
# File 'app/concerns/models/customer_lifecycle.rb', line 218

def ok_to_delete?
  opportunities.where.not(state: 'cancelled').empty? &&
    quotes.open_quotes.empty? &&
    orders.non_carts.empty? &&
    support_case_participants.empty? &&
    invoices.empty? &&
    credit_memos.empty?
end

#opportunities_or_cart_present? ⇒ Boolean

Whether the customer has any open opportunities, cart orders, or manual
orders.

Returns:

  • (Boolean) 


154
155
156
 
# File 'app/concerns/models/customer_lifecycle.rb', line 154

def opportunities_or_cart_present?
  opportunities.exists? || orders.so_only.exists?(state: 'cart') || orders.mo_only.exists?
end

#reset_capabilities ⇒ void

This method returns an undefined value.

Clears account capabilities on close/bankruptcy via
CustomerResetCapabilities (after_transition hook).



231
232
233
 
# File 'app/concerns/models/customer_lifecycle.rb', line 231

def reset_capabilities
  CustomerResetCapabilities.call(self)
end

#set_qc_state ⇒ void

This method returns an undefined value.

Defaults qc_orders to true when unset (before_validation callback).



199
200
201
 
# File 'app/concerns/models/customer_lifecycle.rb', line 199

def set_qc_state
  self.qc_orders = true if qc_orders.nil?
end

#set_status ⇒ void

This method returns an undefined value.

Recomputes and assigns the lifecycle state from sales data, unless the
customer is in a terminal/locked state (closed, lead_qualify, bankrupt,
merging, sent_to_collections).



137
138
139
140
141
 
# File 'app/concerns/models/customer_lifecycle.rb', line 137

def set_status
  return if closed? || lead_qualify? || bankrupt? || merging? || sent_to_collections?

  self.state = determine_customer_state
end

#status_should_be ⇒ Symbol

Assigns the computed lifecycle state — alias-like helper used by callers
that want the state refreshed in memory.

Returns:

  • (Symbol) —

    the assigned state



178
179
180
 
# File 'app/concerns/models/customer_lifecycle.rb', line 178

def status_should_be
  self.state = determine_customer_state
end

#versions_for_audit_trail(_params = {}) ⇒ ActiveRecord::Relation<RecordVersion>

Finds audit versions belonging to this customer or its customer record.

Parameters:

  • _params (Hash) (defaults to: {}) —

    unused compatibility options

Returns:

  • (ActiveRecord::Relation<RecordVersion>) —

    matching audit versions



116
117
118
119
120
121
122
123
 
# File 'app/concerns/models/customer_lifecycle.rb', line 116

def versions_for_audit_trail(_params = {})
  query_sql = "
                (item_type = 'Party' AND item_id = :id)
                OR
                (item_type = 'CustomerRecord' AND reference_data @> :party_id_json)
              "
  RecordVersion.where(query_sql, id:, party_id_json: { party_id: id }.to_json)
end