double_entry 0.0.1.pre → 0.1.0.pre.pre.alpha

data/lib/double_entry/aggregate_array.rb

@@ -0,0 +1,65 @@
+# encoding: utf-8
+module DoubleEntry
+  class AggregateArray < Array
+    # An AggregateArray is awesome
+    # It is useful for making reports
+    # It is basically an array of aggregate results,
+    # representing a column of data in a report.
+    #
+    # For example, you could request all sales
+    # broken down by month and it would return an array of values
+    attr_reader :function, :account, :code, :filter, :range_type, :start, :finish
+
+    def initialize(function, account, code, options)
+      @function = function
+      @account = account
+      @code = code
+      @filter = options[:filter]
+      @range_type = options[:range_type]
+      @start = options[:start]
+      @finish = options[:finish]
+
+      retrieve_aggregates
+      fill_in_missing_aggregates
+      populate_self
+    end
+
+    private
+
+    def populate_self
+      all_periods.each do |period|
+        self << @aggregates[period.key]
+      end
+    end
+
+    def fill_in_missing_aggregates
+      # some aggregates may not have been previously calculated, so we can request them now
+      # (this includes aggregates for the still-running period)
+      all_periods.each do |period|
+        unless @aggregates[period.key]
+          @aggregates[period.key] = DoubleEntry.aggregate(function, account, code, :filter => filter, :range => period)
+        end
+      end
+    end
+
+    # get any previously calculated aggregates
+    def retrieve_aggregates
+      raise ArgumentError.new("Invalid range type '#{range_type}'") unless %w(year month week day hour).include? range_type
+      @aggregates = LineAggregate.
+        where(:function => function.to_s).
+        where(:range_type => 'normal').
+        where(:account => account.to_s).
+        where(:code => code.to_s).
+        where(:filter => filter.inspect).
+        where(LineAggregate.arel_table[range_type].not_eq(nil)).
+        inject({}) do |hash, result|
+          hash[result.key] = Aggregate.formatted_amount(function, result.amount)
+          hash
+        end
+    end
+
+    def all_periods
+      TimeRangeArray.make(range_type, start, finish)
+    end
+  end
+end

data/lib/double_entry/configurable.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+module DoubleEntry
+
+  # Make configuring a module or a class simple.
+  #
+  #   class MyClass
+  #     include Configurable
+  #
+  #     class Configuration
+  #       attr_accessor :my_config_option
+  #
+  #       def initialize #:nodoc:
+  #         @my_config_option = "default value"
+  #       end
+  #     end
+  #   end
+  #
+  # Then in an initializer (or environments/*.rb) do:
+  #
+  #   MyClass.configure do |config|
+  #     config.my_config_option = "custom value"
+  #   end
+  #
+  # And inside methods in your class you can access your config:
+  #
+  #   class MyClass
+  #     def my_method
+  #       puts configuration.my_config_option
+  #     end
+  #   end
+  #
+  # This is all based on this article:
+  #
+  #     http://robots.thoughtbot.com/post/344833329/mygem-configure-block
+  #
+  module Configurable
+    def self.included(base) #:nodoc:
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods #:nodoc:
+      def configuration
+        @configuration ||= self::Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+    end
+  end
+
+end

data/lib/double_entry/day_range.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8
+module DoubleEntry
+  class DayRange < TimeRange
+    attr_reader :year, :week, :day
+
+    def initialize(options)
+      super options
+
+      @week = options[:week]
+      @day = options[:day]
+      week_range = WeekRange.new(options)
+
+      @start = week_range.start + (options[:day] - 1).days
+      @finish = @start.end_of_day
+    end
+
+    def self.from_time(time)
+      week_range = WeekRange.from_time(time)
+      DayRange.new(:year => week_range.year, :week => week_range.week, :day => time.wday == 0 ? 7 : time.wday)
+    end
+
+    def previous
+      DayRange.from_time(@start - 1.day)
+    end
+
+    def next
+      DayRange.from_time(@start + 1.day)
+    end
+
+    def ==(other)
+      (self.week == other.week) and (self.year == other.year) and (self.day == other.day)
+    end
+
+    def to_s
+      start.strftime('%Y, %a %b %d')
+    end
+  end
+end

data/lib/double_entry/hour_range.rb

@@ -0,0 +1,40 @@
+# encoding: utf-8
+module DoubleEntry
+  class HourRange < TimeRange
+    attr_reader :year, :week, :day, :hour
+
+    def initialize(options)
+      super options
+
+      @week = options[:week]
+      @day = options[:day]
+      @hour = options[:hour]
+
+      day_range = DayRange.new(options)
+
+      @start = day_range.start + options[:hour].hours
+      @finish = @start.end_of_hour
+    end
+
+    def self.from_time(time)
+      day = DayRange.from_time(time)
+      HourRange.new :year => day.year, :week => day.week, :day => day.day, :hour => time.hour
+    end
+
+    def previous
+      HourRange.from_time(@start - 1.hour)
+    end
+
+    def next
+      HourRange.from_time(@start + 1.hour)
+    end
+
+    def ==(other)
+      (self.week == other.week) and (self.year == other.year) and (self.day == other.day) and (self.hour == other.hour)
+    end
+
+    def to_s
+      "#{start.hour}:00:00 - #{start.hour}:59:59"
+    end
+  end
+end

data/lib/double_entry/line.rb

@@ -0,0 +1,147 @@
+# encoding: utf-8
+
+module DoubleEntry
+
+  # This is the table to end all tables!
+  #
+  # Every financial transaction gets two entries in here: one for the source
+  # account, and one for the destination account. Normal double-entry
+  # accounting principles are followed.
+  #
+  # This is a log table, and should (ideally) never be updated.
+  #
+  # ## Indexes
+  #
+  # The indexes on this table are carefully chosen, as it's both big and heavily loaded.
+  #
+  # ### lines_scope_account_id_idx
+  #
+  # ```sql
+  # ADD INDEX `lines_scope_account_id_idx` (scope, account, id)
+  # ```
+  #
+  # This is the important one. It's used primarily for querying the current
+  # balance of an account. eg:
+  #
+  # ```sql
+  # SELECT * FROM `lines` WHERE scope = ? AND account = ? ORDER BY id DESC LIMIT 1
+  # ```
+  #
+  # ### lines_scope_account_created_at_idx
+  # 
+  # ```sql
+  # ADD INDEX `lines_scope_account_created_at_idx` (scope, account, created_at)
+  # ```
+  #
+  # Used for querying historic balances:
+  #
+  # ```sql
+  # SELECT * FROM `lines` WHERE scope = ? AND account = ? AND created_at < ? ORDER BY id DESC LIMIT 1
+  # ```
+  #
+  # And for reporting on account changes over a time period:
+  #
+  # ```sql
+  # SELECT SUM(amount) FROM `lines` WHERE scope = ? AND account = ? AND created_at BETWEEN ? AND ?
+  # ```
+  #
+  # ### lines_account_created_at_idx and lines_account_code_created_at_idx
+  #
+  # ```sql
+  # ADD INDEX `lines_account_created_at_idx` (account, created_at);
+  # ADD INDEX `lines_account_code_created_at_idx` (account, code, created_at);
+  # ```
+  #
+  # These two are used for generating reports, which need to sum things
+  # by account, or account and code, over a particular period.
+  #
+  class Line < ActiveRecord::Base
+    extend EncapsulateAsMoney
+
+    belongs_to :detail, :polymorphic => true
+    before_save :check_balance_will_not_be_sent_negative
+
+    encapsulate_as_money :amount, :balance
+
+    def code=(code)
+      self[:code] = code.try(:to_s)
+      code
+    end
+
+    def code
+      self[:code].try(:to_sym)
+    end
+
+    def meta=(meta)
+      self[:meta] = Marshal.dump(meta)
+      meta
+    end
+
+    def meta
+      meta = self[:meta]
+      meta ? Marshal.load(meta) : {}
+    end
+
+    def account=(account)
+      self[:account] = account.identifier.to_s
+      self.scope = account.scope_identity
+      account
+    end
+
+    def account
+      DoubleEntry.account(self[:account].to_sym, :scope => scope)
+    end
+
+    def partner_account=(partner_account)
+      self[:partner_account] = partner_account.identifier.to_s
+      self.partner_scope = partner_account.scope_identity
+      partner_account
+    end
+
+    def partner_account
+      DoubleEntry.account(self[:partner_account].to_sym, :scope => partner_scope)
+    end
+
+    def partner
+      self.class.find(partner_id)
+    end
+
+    def pair
+      if credit?
+        [self, partner]
+      else
+        [partner, self]
+      end
+    end
+
+    def credit?
+      amount < Money.empty
+    end
+
+    def debit?
+      amount > Money.empty
+    end
+
+    def description
+     DoubleEntry.describe(self)
+    end
+
+    # Query out just the id and created_at fields for lines, without
+    # instantiating any ActiveRecord objects.
+    def self.find_id_and_created_at(options)
+      connection.select_rows <<-SQL
+        SELECT id, created_at FROM #{Line.quoted_table_name} #{options[:joins]}
+         WHERE #{sanitize_sql_for_conditions(options[:conditions])}
+      SQL
+    end
+
+    private
+
+    def check_balance_will_not_be_sent_negative
+      if self.account.positive_only and self.balance < Money.new(0)
+        raise AccountWouldBeSentNegative.new(account)
+      end
+    end
+  end
+
+end

data/lib/double_entry/line_aggregate.rb

@@ -0,0 +1,37 @@
+# encoding: utf-8
+module DoubleEntry
+  class LineAggregate < ActiveRecord::Base
+    extend EncapsulateAsMoney
+
+    def self.aggregate(function, account, code, scope, range, named_scopes)
+      collection = aggregate_collection(named_scopes)
+      collection = collection.where(:account => account)
+      collection = collection.where(:created_at => range.start..range.finish)
+      collection = collection.where(:code => code) if code
+      collection.send(function, :amount)
+    end
+
+    # a lot of the trickier reports will use filters defined
+    # in named_scopes to bring in data from other tables.
+    def self.aggregate_collection(named_scopes)
+      if named_scopes
+        collection = Line
+        named_scopes.each do |named_scope|
+          if named_scope.is_a?(Hash)
+            method_name = named_scope.keys[0]
+            collection = collection.send(method_name, named_scope[method_name])
+          else
+            collection = collection.send(named_scope)
+          end
+        end
+        collection
+      else
+        Line
+      end
+    end
+
+    def key
+      "#{year}:#{month}:#{week}:#{day}:#{hour}"
+    end
+  end
+end

data/lib/double_entry/line_check.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+require 'set'
+
+module DoubleEntry
+  class LineCheck < ActiveRecord::Base
+    extend EncapsulateAsMoney
+
+    default_scope -> { order('created_at') }
+
+    def self.perform!
+      new.perform
+    end
+
+    def perform
+      log = ''
+      current_line_id = nil
+
+      active_accounts    = Set.new
+      incorrect_accounts = Set.new
+
+      new_lines_since_last_run.find_each do |line|
+        incorrect_accounts << line.account unless running_balance_correct?(line, log)
+        active_accounts    << line.account
+        current_line_id = line.id
+      end
+
+      active_accounts.each do |account|
+        incorrect_accounts << account      unless cached_balance_correct?(account)
+      end
+
+      incorrect_accounts.each { |account| recalculate_account(account) }
+
+      unless active_accounts.empty?
+        LineCheck.create!(
+          :errors_found => incorrect_accounts.any?,
+          :last_line_id => current_line_id,
+          :log          => log,
+        )
+      end
+    end
+
+  private
+
+    def last_run_line_id
+      latest = LineCheck.last
+      latest ? latest.last_line_id : 0
+    end
+
+    def new_lines_since_last_run
+      Line.where('id > ?', last_run_line_id)
+    end
+
+    def running_balance_correct?(line, log)
+      # Another work around for the MySQL 5.1 query optimiser bug that causes the ORDER BY
+      # on the query to fail in some circumstances, resulting in an old balance being
+      # returned. This was biting us intermittently in spec runs.
+      # See http://bugs.mysql.com/bug.php?id=51431
+      force_index = if Line.connection.adapter_name.match /mysql/i
+                      "FORCE INDEX (lines_scope_account_id_idx)"
+                    else
+                      ""
+                    end
+
+      # yes, it needs to be find_by_sql, because any other find will be affected
+      # by the find_each call in perform!
+      previous_line = Line.find_by_sql(["SELECT * FROM #{Line.quoted_table_name} #{force_index} WHERE account = ? AND scope = ? AND id < ? ORDER BY id DESC LIMIT 1", line.account.identifier.to_s, line.scope, line.id])
+      previous_balance = previous_line.length == 1 ? previous_line[0].balance : Money.empty
+
+      if line.balance != (line.amount + previous_balance)
+        log << line_error_message(line, previous_line, previous_balance)
+      end
+
+      line.balance == previous_balance + line.amount
+    end
+
+    def line_error_message(line, previous_line, previous_balance)
+      <<-END_OF_MESSAGE.strip_heredoc
+        *********************************
+        Error on line ##{line.id}: balance:#{line.balance} != #{previous_balance} + #{line.amount}
+        *********************************
+        #{previous_line.inspect}
+        #{line.inspect}
+
+      END_OF_MESSAGE
+    end
+
+    def cached_balance_correct?(account)
+      DoubleEntry.lock_accounts(account) do
+        return AccountBalance.find_by_account(account).balance == account.balance
+      end
+    end
+
+    def recalculate_account(account)
+      DoubleEntry.lock_accounts(account) do
+        recalculated_balance = Money.empty
+
+        lines_for_account(account).each do |line|
+          recalculated_balance += line.amount
+          line.update_attribute(:balance, recalculated_balance) if line.balance != recalculated_balance
+        end
+
+        update_balance_for_account(account, recalculated_balance)
+      end
+    end
+
+    def lines_for_account(account)
+      Line.where(
+        :account => account.identifier.to_s,
+        :scope   => account.scope_identity.to_s
+      ).order(:id)
+    end
+
+    def update_balance_for_account(account, balance)
+      account_balance = Locking.balance_for_locked_account(account)
+      account_balance.update_attribute(:balance, balance)
+    end
+  end
+end