shoppe 0.0.16 → 0.0.17

data/app/models/shoppe/order.rb

@@ -1,425 +1,89 @@
-# == Schema Information
-#
-# Table name: shoppe_orders
-#
-#  id                        :integer          not null, primary key
-#  token                     :string(255)
-#  first_name                :string(255)
-#  last_name                 :string(255)
-#  company                   :string(255)
-#  billing_address1          :string(255)
-#  billing_address2          :string(255)
-#  billing_address3          :string(255)
-#  billing_address4          :string(255)
-#  billing_postcode          :string(255)
-#  billing_country_id        :integer
-#  email_address             :string(255)
-#  phone_number              :string(255)
-#  status                    :string(255)
-#  received_at               :datetime
-#  accepted_at               :datetime
-#  shipped_at                :datetime
-#  created_at                :datetime
-#  updated_at                :datetime
-#  delivery_service_id       :integer
-#  delivery_price            :decimal(8, 2)
-#  delivery_cost_price       :decimal(8, 2)
-#  delivery_tax_rate         :decimal(8, 2)
-#  delivery_tax_amount       :decimal(8, 2)
-#  paid_at                   :datetime
-#  accepted_by               :integer
-#  shipped_by                :integer
-#  consignment_number        :string(255)
-#  rejected_at               :datetime
-#  rejected_by               :integer
-#  ip_address                :string(255)
-#  payment_reference         :string(255)
-#  payment_method            :string(255)
-#  notes                     :text
-#  separate_delivery_address :boolean          default(FALSE)
-#  delivery_address1         :string(255)
-#  delivery_address2         :string(255)
-#  delivery_address3         :string(255)
-#  delivery_address4         :string(255)
-#  deilvery_postcode         :string(255)
-#  delivery_country_id       :integer
-#
-
 module Shoppe
   class Order < ActiveRecord::Base
 
-    # Set the table name
     self.table_name = 'shoppe_orders'
   
-    # An array of all the available statuses for an order
-    STATUSES = ['building', 'confirming', 'received', 'accepted', 'rejected', 'shipped']
-  
-    # Order's implement a key value store for storing arbitary properties which 
-    # may be useful (for example payment configuraiton)
+    # Orders can have properties
     key_value_store :properties
+    
+    # Require dependencies
+    require_dependency 'shoppe/order/states'
+    require_dependency 'shoppe/order/actions'
+    require_dependency 'shoppe/order/billing'
+    require_dependency 'shoppe/order/delivery'
   
-    # These additional callbacks allow for applications to hook into other
-    # parts of the order lifecycle.
-    define_model_callbacks :confirmation, :payment, :acceptance, :rejection, :ship
-  
-    # Relationships
-    belongs_to :delivery_service, :class_name => 'Shoppe::DeliveryService'
-    belongs_to :billing_country, :class_name => 'Shoppe::Country', :foreign_key => 'billing_country_id'
-    belongs_to :delivery_country, :class_name => 'Shoppe::Country', :foreign_key => 'delivery_country_id'
-    belongs_to :accepter, :class_name => 'Shoppe::User', :foreign_key => 'accepted_by'
-    belongs_to :rejecter, :class_name => 'Shoppe::User', :foreign_key => 'rejected_by'
-    belongs_to :shipper, :class_name => 'Shoppe::User', :foreign_key => 'shipped_by'
+    # All items which make up this order
     has_many :order_items, :dependent => :destroy, :class_name => 'Shoppe::OrderItem'
+
+    # All products which are part of this order (accessed through the items)
     has_many :products, :through => :order_items, :class_name => 'Shoppe::Product'
-  
+    
     # Validations
     validates :token, :presence => true
-    validates :status, :inclusion => {:in => STATUSES}
     with_options :if => Proc.new { |o| !o.building? } do |order|
-      order.validates :first_name, :presence => true
-      order.validates :last_name, :presence => true
-      order.validates :billing_address1, :presence => true
-      order.validates :billing_address3, :presence => true
-      order.validates :billing_address4, :presence => true
-      order.validates :billing_postcode, :presence => true
-      order.validates :billing_country, :presence => true
       order.validates :email_address, :format => {:with => /\A\b[A-Z0-9\.\_\%\-\+]+@(?:[A-Z0-9\-]+\.)+[A-Z]{2,6}\b\z/i}
       order.validates :phone_number, :format => {:with => /\A[\d\ \-x\(\)]{7,}\z/}
     end
-    with_options :if => :separate_delivery_address? do |order|
-      order.validates :delivery_name, :presence => true
-      order.validates :delivery_address1, :presence => true
-      order.validates :delivery_address3, :presence => true
-      order.validates :delivery_address4, :presence => true
-      order.validates :delivery_postcode, :presence => true
-      order.validates :delivery_country, :presence => true
-    end
-    
-    validate do
-      unless available_delivery_services.include?(self.delivery_service)
-        errors.add :delivery_service_id, "is not suitable for this order"
-      end
-    end
-  
-    # Scopes
-    scope :received, -> {where("received_at is not null")}
-    scope :pending, -> { where(:status => 'received') }
-    scope :ordered, -> { order('id desc')}
   
     # Set some defaults
-    before_validation do
-      self.status = 'building' if self.status.blank?
-      self.token = SecureRandom.uuid if self.token.blank?
-    end
+    before_validation { self.token = SecureRandom.uuid  if self.token.blank? }
     
-    [:delivery_name, :delivery_address1, :delivery_address2, :delivery_address3, :delivery_address4, :delivery_postcode, :delivery_country].each do |f|
-      define_method(f) do
-        separate_delivery_address? ? super() : send(f.to_s.gsub('delivery_', 'billing_'))
-      end
-    end
-  
-    # Is this order still being built by the user?
-    def building?
-      self.status == 'building'
-    end
-  
-    # Is this order in the user confirmation step?
-    def confirming?
-      self.status == 'confirming'
-    end
-  
-    # Has this order been rejected?
-    def rejected?
-      !!self.rejected_at
-    end
-  
-    # Has this order been accepted?
-    def accepted?
-      !!self.accepted_at
-    end
-  
-    # Has this order been shipped?
-    def shipped?
-      !!self.shipped_at?
-    end
-  
-    # Has the order been received?
-    def received?
-      !!self.received_at?
-    end
-  
     # The order number
+    #
+    # @return [String] - the order number padded with at least 5 zeros
     def number
       id.to_s.rjust(6, '0')
     end
   
     # The length of time the customer spent building the order before submitting it to us.
     # The time from first item in basket to received.
+    #
+    # @return [Float] - the length of time
     def build_time
       return nil if self.received_at.blank?
       self.created_at - self.received_at
     end
   
-    # The name of the customer
+    # The name of the customer in the format of "Company (First Last)" or if they don't have
+    # company specified, just "First Last".
+    #
+    # @return [String]
     def customer_name
       company.blank? ? full_name : "#{company} (#{full_name})"
     end
     
-    # The name for billing purposes
-    def billing_name
-      company.blank? ? full_name : "#{full_name} (#{company})"
-    end
-    
-    # The full anme of the customer
+    # The full name of the customer created by concatinting the first & last name
+    #
+    # @return [String]
     def full_name
       "#{first_name} #{last_name}"
     end
   
     # Is this order empty? (i.e. doesn't have any items associated with it)
+    #
+    # @return [Boolean]
     def empty?
       order_items.empty?
     end
   
     # Does this order have items?
+    #
+    # @return [Boolean]
     def has_items?
       total_items > 0
     end
   
     # Return the number of items in the order?
+    #
+    # @return [Integer]
     def total_items
       @total_items ||= order_items.inject(0) { |t,i| t + i.quantity }
     end
-  
-    # The total cost of the order
-    def total_cost
-      self.delivery_cost_price + 
-      order_items.inject(BigDecimal(0)) { |t, i| t + i.total_cost }
-    end
-  
-    # Return the price for the order
-    def profit
-      total_before_tax - total_cost
-    end
-  
-    # The total price of the order before tax
-    def total_before_tax
-      self.delivery_price +
-      order_items.inject(BigDecimal(0)) { |t, i| t + i.sub_total }
-    end
-  
-    # The total amount of tax due on this order
-    def tax
-      self.delivery_tax_amount +
-      order_items.inject(BigDecimal(0)) { |t, i| t + i.tax_amount }
-    end
-  
-    # The total of the order including tax
-    def total
-      self.delivery_price + 
-      self.delivery_tax_amount + 
-      order_items.inject(BigDecimal(0)) { |t, i| t + i.total }
-    end
-  
-    # The total of the order including tax in pence
-    def total_in_pence
-      (total * BigDecimal(100)).to_i
-    end
-  
-    # The total weight of the order
-    def total_weight
-      order_items.inject(BigDecimal(0)) { |t,i| t + i.weight}
-    end
-  
-    # An array of all the delivery service prices which can be applied to this order.
-    def delivery_service_prices
-      @delivery_service_prices ||= begin
-        prices = Shoppe::DeliveryServicePrice.joins(:delivery_service).where(:shoppe_delivery_services => {:active => true}).order("`default` desc, price asc").for_weight(total_weight)
-        prices = prices.select { |p| p.countries.empty? || p.country?(self.billing_country) }
-        prices
-      end
-    end
-  
-    # An array of all the delivery services which are suitable for this order in it's
-    # current state (based on its current weight)
-    def available_delivery_services
-      @available_delivery_services ||= begin
-        delivery_service_prices.map(&:delivery_service).uniq
-      end
-    end
-  
-    # The recommended delivery service for this order
-    def delivery_service
-      super || available_delivery_services.first
-    end
-  
-    # Return the delivery price for this order in its current state
-    def delivery_service_price
-      @delivery_service_price ||= self.delivery_service && self.delivery_service.delivery_service_prices.for_weight(self.total_weight).first
-    end
-  
-    # The price for delivering this order in its current state
-    def delivery_price
-      @delivery_price ||= read_attribute(:delivery_price) || delivery_service_price.try(:price) || 0.0
-    end
-  
-    # The cost of delivering this order in its current state
-    def delivery_cost_price
-      @delivery_cost_price ||= read_attribute(:delivery_cost_price) || delivery_service_price.try(:cost_price) || 0.0
-    end
-  
-    # The tax amount due for the delivery of this order in its current state
-    def delivery_tax_amount
-      @delivery_tax_amount ||= begin
-        read_attribute(:delivery_tax_amount) ||
-        delivery_price / BigDecimal(100) * delivery_tax_rate ||
-        0.0
-      end
-    end
-  
-    # The tax rate for the delivery of this order in its current state
-    def delivery_tax_rate
-      @delivery_tax_rate ||= begin
-        read_attribute(:delivery_tax_rate) ||
-        delivery_service_price.try(:tax_rate).try(:rate_for, self) ||
-        0.0
-      end
-    end
-  
-    # Is the currently assigned delivery service appropriate for this order?
-    def valid_delivery_service?
-      self.delivery_service && self.available_delivery_services.include?(self.delivery_service)
-    end
-  
-    # Remove the associated delivery service if it's invalid
-    def remove_delivery_service_if_invalid
-      unless self.valid_delivery_service?
-        self.delivery_service = nil
-        self.save
-      end
-    end
-  
-    # The URL which can be used to track the delivery of this order
-    def courier_tracking_url
-      return nil if self.shipped_at.blank? || self.consignment_number.blank?
-      @courier_tracking_url ||= self.delivery_service.tracking_url_for(self.consignment_number)
-    end
-  
-    # Has this order been fully paid for?
-    def paid?
-      !paid_at.blank?
-    end
-  
-    # This method is called by the customer when they submit their details in the first step of
-    # the checkout process. It will update the status to 'confirmed' as well as updating their 
-    # details. Any issues with validation will cause false to be returned otherwise true. Any
-    # more serious issues will be raised as exceptions.
-    def proceed_to_confirm(params = {})
-      self.status = 'confirming'
-      if self.update(params)
-        true
-      else
-        false
-      end
-    end
-  
-    # This method will confirm the order If there are any issues with  the order an exception 
-    # should be raised.
-    def confirm!
-    
-      # Ensure that we have the stock to fulfil this order at the current time. We may have had it when
-      # it was placed int he basket and if we don't now, we should let the user know so they can
-      # rethink.
-      no_stock_of = self.order_items.select(&:validate_stock_levels)
-      unless no_stock_of.empty?
-        raise Shoppe::Errors::InsufficientStockToFulfil, :order => self, :out_of_stock_items => no_stock_of
-      end
-    
-      # Ensure that before we confirm the order that the delivery service which has been selected
-      # is appropritae for the contents of the order.
-      unless self.valid_delivery_service?
-        raise Shoppe::Errors::InappropriateDeliveryService, :order => self
-      end
-    
-      # Store the delivery prices with the order
-      if self.delivery_service
-        write_attribute :delivery_service_id, self.delivery_service.id
-        write_attribute :delivery_price, self.delivery_price
-        write_attribute :delivery_cost_price, self.delivery_cost_price
-        write_attribute :delivery_tax_amount, self.delivery_tax_amount
-        write_attribute :delivery_tax_rate, self.delivery_tax_rate
-      end
-      
-      run_callbacks :confirmation do
-        # If we have successfully charged the card (i.e. no exception) we can go ahead and mark this
-        # order as 'received' which means it can be accepted by staff.
-        self.status = 'received'
-        self.received_at = Time.now
-        self.save!
-
-        self.order_items.each(&:confirm!)
-
-        # Send an email to the customer
-        Shoppe::OrderMailer.received(self).deliver
-      end
     
-      # We're all good.
-      true
-    end
-  
-    # This method will mark an order as paid.
-    def pay!(reference, method)
-      run_callbacks :payment do
-        self.paid_at = Time.now.utc
-        self.payment_reference = reference
-        self.payment_method = method
-        self.save!
-      end
-    end
-  
-    # This method will accept the this order. It is called by a user (which is the only
-    # parameter).
-    def accept!(user)
-      run_callbacks :acceptance do
-        self.accepted_at = Time.now
-        self.accepted_by = user.id
-        self.status = 'accepted'
-        self.save!
-        self.order_items.each(&:accept!)
-        Shoppe::OrderMailer.accepted(self).deliver
-      end
-    end
-  
-    # This method will reject the order. It is called by a user (which is the only parameter).
-    def reject!(user)
-      run_callbacks :rejection do
-        self.rejected_at = Time.now
-        self.rejected_by = user.id
-        self.status = 'rejected'
-        self.save!
-        self.order_items.each(&:reject!)
-        Shoppe::OrderMailer.rejected(self).deliver
-      end
-    end
-  
-    # This method will mark an order as shipped and store the given consignment number with the
-    # order for use later in tracking.
-    def ship!(user, consignment_number)
-      run_callbacks :ship do
-        self.shipped_at = Time.now
-        self.shipped_by = user.id
-        self.status = 'shipped'
-        self.consignment_number = consignment_number
-        self.save!
-        Shoppe::OrderMailer.shipped(self).deliver
-      end
-    end
-  
-    # Specify which attributes can be searched
     def self.ransackable_attributes(auth_object = nil) 
       ["id", "billing_postcode", "billing_address1", "billing_address2", "billing_address3", "billing_address4", "first_name", "last_name", "company", "email_address", "phone_number", "consignment_number", "status", "received_at"] + _ransackers.keys
     end
   
-    # Specify which associations can be searched
     def self.ransackable_associations(auth_object = nil)
       ['products']
     end

data/app/models/shoppe/order_item.rb

@@ -1,42 +1,32 @@
-# == Schema Information
-#
-# Table name: shoppe_order_items
-#
-#  id                :integer          not null, primary key
-#  order_id          :integer
-#  ordered_item_id   :integer
-#  ordered_item_type :string(255)
-#  quantity          :integer          default(1)
-#  unit_price        :decimal(8, 2)
-#  unit_cost_price   :decimal(8, 2)
-#  tax_amount        :decimal(8, 2)
-#  tax_rate          :decimal(8, 2)
-#  weight            :decimal(8, 3)    default(0.0)
-#  created_at        :datetime
-#  updated_at        :datetime
-#
-
 module Shoppe
   class OrderItem < ActiveRecord::Base
   
-    # Set the table name
     self.table_name = 'shoppe_order_items'
   
-    # Relationships
+    # The associated order
+    #
+    # @return [Shoppe::Order]
     belongs_to :order, :class_name => 'Shoppe::Order'
+    
+    # The item which has been ordered
     belongs_to :ordered_item, :polymorphic => true
+    
+    # Any stock level adjustments which have been made for this order item
     has_many :stock_level_adjustments, :as => :parent, :dependent => :nullify, :class_name => 'Shoppe::StockLevelAdjustment'
-  
+    
     # Validations
     validates :quantity, :numericality => true
   
-    before_validation do
-      self.weight = self.quantity * self.ordered_item.weight
-    end
+    # Set the weight as appropriate on save
+    before_validation { self.weight = self.quantity * self.ordered_item.weight }
   
     # This allows you to add a product to the scoped order. For example Order.first.order_items.add_product(...).
     # This will either increase the quantity of the value in the order or create a new item if one does not
     # exist already.
+    #
+    # @param ordered_item [Object] an object which implements the Shoppe::OrderableItem protocol
+    # @param quantity [Fixnum] the number of items to order
+    # @return [Shoppe::OrderItem]
     def self.add_item(ordered_item, quantity = 1)
       raise Errors::UnorderableItem, :ordered_item => ordered_item unless ordered_item.orderable?
       transaction do
@@ -46,22 +36,28 @@ module Shoppe
         else
           new_item = self.create(:ordered_item => ordered_item, :quantity => 0)
           new_item.increase!(quantity)
+          new_item
         end
       end
     end
 
-    # This allows you to remove a product from an order. It will also ensure that the order's
-    # custom delivery service is updated.
+    # Remove a product from an order. It will also ensure that the order's custom delivery
+    # service is updated if appropriate.
+    #
+    # @return [Shoppe::OrderItem]
     def remove
       transaction do
         self.destroy!
         self.order.remove_delivery_service_if_invalid
+        self
       end
     end
   
   
-    # Increase the quantity of items in the order by the number provided. Will raise an error if we don't have
+    # Increases the quantity of items in the order by the number provided. Will raise an error if we don't have
     # the stock to do this.
+    #
+    # @param quantity [Fixnum]
     def increase!(amount = 1)
       transaction do
         self.quantity += amount
@@ -74,6 +70,8 @@ module Shoppe
     end
   
     # Decreases the quantity of items in the order by the number provided.
+    #
+    # @param amount [Fixnum]
     def decrease!(amount = 1)
       transaction do
         self.quantity -= amount
@@ -82,65 +80,80 @@ module Shoppe
       end
     end
   
-    # Return the unit price for the item
+    # The unit price for the item
+    #
+    # @return [BigDecimal]
     def unit_price
       @unit_price ||= read_attribute(:unit_price) || ordered_item.try(:price) || 0.0
     end
   
-    # Return the cost price for the item
+    # The cost price for the item
+    #
+    # @return [BigDecimal]
     def unit_cost_price
       @unit_cost_price ||= read_attribute(:unit_cost_price) || ordered_item.try(:cost_price) || 0.0
     end
   
-    # Return the tax rate for the item
+    # The tax rate for the item
+    #
+    # @return [BigDecimal]
     def tax_rate
       @tax_rate ||= read_attribute(:tax_rate) || ordered_item.try(:tax_rate).try(:rate_for, self.order) || 0.0 
     end
   
-    # Return the total tax for the item
+    # The total tax for the item
+    #
+    # @return [BigDecimal]
     def tax_amount
       @tax_amount ||= read_attribute(:tax_amount) || (self.sub_total / BigDecimal(100)) * self.tax_rate
     end
   
-    # Return the total cost for the product
+    # The total cost for the product
+    #
+    # @return [BigDecimal]
     def total_cost
       quantity * unit_cost_price
     end
   
-    # Return the sub total for the product
+    # The sub total for the product
+    #
+    # @return [BigDecimal]
     def sub_total
       quantity * unit_price
     end
   
-    # Return the total price including tax for the order line
+    # The total price including tax for the order line
+    #
+    # @return [BigDecimal]
     def total
       tax_amount + sub_total
     end
   
-    # This method will be triggered when the parent order is confirmed. This should automatically
-    # update the stock levels on the source product.
+    # Trigger when the associated order is confirmed. It handles caching the values
+    # of the monetary items and allocating stock as appropriate.
     def confirm!
       write_attribute :unit_price, self.unit_price
       write_attribute :unit_cost_price, self.unit_cost_price
       write_attribute :tax_rate, self.tax_rate
       write_attribute :tax_amount, self.tax_amount
       save!
-    
       if self.ordered_item.stock_control?
         self.ordered_item.stock_level_adjustments.create(:parent => self, :adjustment => 0 - self.quantity, :description => "Order ##{self.order.number} deduction")
       end
     end
   
-    # This method will be trigger when the parent order is accepted.
+    # Trigger when the associated order is accepted
     def accept!
     end
   
-    # This method will be trigger when the parent order is rejected.
+    # Trigged when the associated order is rejected..
     def reject!
       self.stock_level_adjustments.destroy_all
     end
   
     # Do we have the stock needed to fulfil this order?
+    #
+    # @return [Boolean]
     def in_stock?
       if self.ordered_item.stock_control?
         self.ordered_item.stock >= self.quantity