event_sourced_accounting 0.1.0

data/app/models/esa/filters/accountable_filter.rb

@@ -0,0 +1,58 @@
+module ESA
+  module Filters
+    module AccountableFilter
+      def self.make_union_query(definitions = {})
+        fragments = definitions.map do |type,accountable|
+          make_fragments(type, accountable)
+        end.flatten
+
+        if fragments.count > 0
+          fragments.join(' UNION ')
+        else
+          "SELECT -1 AS id, 'Nothing' AS type"
+        end
+      end
+
+      def self.make_fragments(type, accountable)
+        if accountable.is_a? ActiveRecord::Relation
+          [accountable.select("`#{accountable.table_name}`.`#{accountable.primary_key}` AS id, '#{type}' AS type").to_sql.squish]
+        elsif accountable.is_a? ActiveRecord::Base
+          ["SELECT #{accountable.id} AS id, '#{type}' AS type"]
+        elsif accountable.is_a? Integer
+          ["SELECT #{accountable} AS id, '#{type}' AS type"]
+        elsif accountable.respond_to? :each
+          accountable.map{|a| make_fragments(type, a)}.flatten
+        else
+          []
+        end
+      end
+
+      module TransactionAccountable
+        extend ActiveSupport::Concern
+
+        included do
+          scope :with_accountable, lambda { |accountable,type|
+            joins(:transaction).where(esa_transactions: {accountable_id: accountable, accountable_type: type})
+          }
+          scope :with_accountable_def, lambda { |definitions| joins(:transaction).joins("INNER JOIN (#{ESA::Filters::AccountableFilter.make_union_query(definitions)}) `accountables-#{(hash ^ definitions.hash).to_s(36)}` ON `esa_transactions`.`accountable_id` = `accountables-#{(hash ^ definitions.hash).to_s(36)}`.`id` AND `esa_transactions`.`accountable_type` = `accountables-#{(hash ^ definitions.hash).to_s(36)}`.`type`") }
+        end
+      end
+
+      module ObjectAccountable
+        extend ActiveSupport::Concern
+
+        included do
+          scope :with_accountable, lambda { |accountable,type|
+            where(accountable_id: accountable, accountable_type: type)
+          }
+          scope :with_accountable_def, lambda { |definitions| joins("INNER JOIN (#{ESA::Filters::AccountableFilter.make_union_query(definitions)}) `accountables-#{(hash ^ definitions.hash).to_s(36)}` ON `#{table_name}`.`accountable_id` = `accountables-#{(hash ^ definitions.hash).to_s(36)}`.`id` AND `#{table_name}`.`accountable_type` = `accountables-#{(hash ^ definitions.hash).to_s(36)}`.`type`") }
+        end
+      end
+    end
+  end
+end
+
+ESA::Amount.send :include, ESA::Filters::AccountableFilter::TransactionAccountable
+ESA::Event.send :include, ESA::Filters::AccountableFilter::ObjectAccountable
+ESA::Flag.send :include, ESA::Filters::AccountableFilter::ObjectAccountable
+ESA::Transaction.send :include, ESA::Filters::AccountableFilter::ObjectAccountable

data/app/models/esa/filters/accountable_type_filter.rb

@@ -0,0 +1,26 @@
+module ESA
+  module Filters
+    module AccountableTypeFilter
+      module TransactionAccountableType
+        extend ActiveSupport::Concern
+
+        included do
+          scope :with_accountable_type, lambda { |type| joins(:transaction).where(esa_transactions: {accountable_type: type}) }
+        end
+      end
+
+      module ObjectAccountableType
+        extend ActiveSupport::Concern
+
+        included do
+          scope :with_accountable_type, lambda { |type| where(accountable_type: type) }
+        end
+      end
+    end
+  end
+end
+
+ESA::Amount.send :include, ESA::Filters::AccountableTypeFilter::TransactionAccountableType
+ESA::Event.send :include, ESA::Filters::AccountableTypeFilter::ObjectAccountableType
+ESA::Flag.send :include, ESA::Filters::AccountableTypeFilter::ObjectAccountableType
+ESA::Transaction.send :include, ESA::Filters::AccountableTypeFilter::ObjectAccountableType

data/app/models/esa/filters/chart_filter.rb

@@ -0,0 +1,17 @@
+module ESA
+  module Filters
+    module ChartFilter
+      extend ActiveSupport::Concern
+
+      included do
+        scope :with_chart, lambda { |chart| with_account(Account.where(chart_id: chart)) }
+        scope :with_chart_name, lambda { |name| with_chart(Chart.where(name: name)) }
+      end
+    end
+  end
+end
+
+ESA::Amount.send :include, ESA::Filters::ChartFilter
+ESA::Event.send :include, ESA::Filters::ChartFilter
+ESA::Flag.send :include, ESA::Filters::ChartFilter
+ESA::Transaction.send :include, ESA::Filters::ChartFilter

data/app/models/esa/filters/context_filter.rb

@@ -0,0 +1,35 @@
+module ESA
+  module Filters
+    module ContextFilter
+      extend ActiveSupport::Concern
+
+      included do
+        scope :with_context, lambda { |*contexts|
+          contexts.flatten.uniq.
+          map do |ctx|
+            if ctx.is_a? Integer or ctx.is_a? String
+              ESA::Context.find(ctx.to_i) rescue nil
+            else
+              ctx
+            end
+          end.
+          inject(where([])) do |relation,ctx|
+            if not ctx.nil? and ctx.respond_to? :apply
+              # good, the context can be applied directly
+              ctx.apply(relation)
+            else
+              # context not found, or cannot be applied
+              # either way, make sure we dont return results
+              relation.where("1=0")
+            end
+          end
+        }
+      end
+    end
+  end
+end
+
+ESA::Amount.send :include, ESA::Filters::ContextFilter
+ESA::Event.send :include, ESA::Filters::ContextFilter
+ESA::Flag.send :include, ESA::Filters::ContextFilter
+ESA::Transaction.send :include, ESA::Filters::ContextFilter

data/app/models/esa/filters/date_time_filter.rb

@@ -0,0 +1,52 @@
+module ESA
+  module Filters
+    module DateTimeFilter
+      module TransactionDate
+        extend ActiveSupport::Concern
+
+        included do
+          scope :between_dates, lambda { |date1,date2| joins(:transaction).where(esa_transactions: {time: date1.midnight..date2.end_of_day}) }
+          scope :with_date,     lambda { |date| joins(:transaction).where(esa_transactions: {time: date.midnight..date.end_of_day}) }
+
+          scope :with_date_lt,  lambda { |date| with_time_lt(date.midnight) }
+          scope :with_date_gt,  lambda { |date| with_time_gt(date.end_of_day) }
+          scope :with_date_lte, lambda { |date| with_time_lte(date.end_of_day) }
+          scope :with_date_gte, lambda { |date| with_time_gte(date.midnight) }
+
+          scope :with_time_lt,  lambda { |time| joins(:transaction).where(ESA::Transaction.arel_table[:time].lt( time)) }
+          scope :with_time_gt,  lambda { |time| joins(:transaction).where(ESA::Transaction.arel_table[:time].gt( time)) }
+          scope :with_time_lte, lambda { |time| joins(:transaction).where(ESA::Transaction.arel_table[:time].lteq(time)) }
+          scope :with_time_gte, lambda { |time| joins(:transaction).where(ESA::Transaction.arel_table[:time].gteq(time)) }
+
+          scope :created_before, lambda { |time| joins(:transaction).where(ESA::Transaction.arel_table[:created_at].lt(time)) }
+        end
+      end
+
+      module ObjectDate
+        extend ActiveSupport::Concern
+
+        included do
+          scope :between_dates, lambda { |date1,date2| where(time: date1.midnight..date2.end_of_day) }
+          scope :with_date,     lambda { |date| where(time: date.midnight..date.end_of_day) }
+
+          scope :with_date_lt,  lambda { |date| with_time_lt(date.midnight) }
+          scope :with_date_gt,  lambda { |date| with_time_gt(date.end_of_day) }
+          scope :with_date_lte, lambda { |date| with_time_lte(date.end_of_day) }
+          scope :with_date_gte, lambda { |date| with_time_gte(date.midnight) }
+
+          scope :with_time_lt,  lambda { |time| where(arel_table[:time].lt( time)) }
+          scope :with_time_gt,  lambda { |time| where(arel_table[:time].gt( time)) }
+          scope :with_time_lte, lambda { |time| where(arel_table[:time].lteq(time)) }
+          scope :with_time_gte, lambda { |time| where(arel_table[:time].gteq(time)) }
+
+          scope :created_before, lambda { |time| where(arel_table[:created_at].lt(time)) }
+        end
+      end
+    end
+  end
+end
+
+ESA::Amount.send :include, ESA::Filters::DateTimeFilter::TransactionDate
+ESA::Event.send :include, ESA::Filters::DateTimeFilter::ObjectDate
+ESA::Flag.send :include, ESA::Filters::DateTimeFilter::ObjectDate
+ESA::Transaction.send :include, ESA::Filters::DateTimeFilter::ObjectDate

data/app/models/esa/flag.rb

@@ -0,0 +1,70 @@
+module ESA
+  # The Flag class represents a change of known state of an Accountable
+  # and it is used record differences of state caused by Events.
+  # 
+  # A Flag with an UP transition creates normal Transactions according to
+  # the rules specified in a Ruleset. Flags with a DOWN transition revert
+  # Transactions created earlier by the corresponding UP transition.
+  #
+  # @author Lenno Nagel
+  class Flag < ActiveRecord::Base
+    include Traits::Extendable
+    extend ::Enumerize
+
+    attr_accessible :nature, :state, :event, :time, :accountable, :type, :ruleset
+    attr_readonly   :nature, :state, :event, :time, :accountable, :type, :ruleset
+
+    belongs_to :accountable, :polymorphic => true
+    belongs_to :event
+    belongs_to :ruleset
+    has_many   :transactions
+    has_many   :amounts, :through => :transactions, :extend => Associations::AmountsExtension
+
+    enumerize :nature, in: [:unknown]
+
+    after_initialize :default_values
+    validates_presence_of :nature, :event, :time, :accountable, :ruleset
+    validates_inclusion_of :state, :in => [true, false]
+    validates_inclusion_of :processed, :in => [true, false]
+    validates_inclusion_of :adjusted, :in => [true, false]
+    validate :validate_transition
+
+    def is_set?
+      self.state == true
+    end
+
+    def is_unset?
+      self.state == false
+    end
+
+    def became_set?
+      self.transition == 1
+    end
+
+    def became_unset?
+      self.transition == -1
+    end
+
+    private
+
+    def validate_transition
+      if self.processed and not self.transition.in? [-1, 0, 1]
+        errors[:processed] = "The transition must be in? [-1, 0, 1] before processed can be set to true"
+      end
+      if self.adjusted and not self.transition.in? [-1, 0, 1]
+        errors[:adjusted] = "The transition must be in? [-1, 0, 1] before adjusted can be set to true"
+      end
+    end
+
+    def default_values
+      if not self.event_id.nil?
+        self.time ||= self.event.time if self.time.nil?
+        self.accountable ||= self.event.accountable if self.accountable_id.nil?
+        self.ruleset ||= self.event.ruleset if self.ruleset_id.nil?
+      end
+
+      self.processed ||= false
+      self.adjusted ||= false
+    end
+  end
+end

data/app/models/esa/ruleset.rb

@@ -0,0 +1,175 @@
+module ESA
+  # The Ruleset class contains the business logic and rules of accounting.
+  #
+  # @author Lenno Nagel
+  class Ruleset < ActiveRecord::Base
+    include Traits::Extendable
+
+    attr_accessible :name, :type, :chart
+    attr_readonly   :name, :type, :chart
+
+    belongs_to :chart
+    has_many   :events
+    has_many   :flags
+
+    after_initialize :default_values
+    validates_presence_of :type, :chart
+
+    # accountable
+
+    def accountables_updated_at(timespec)
+      []
+    end
+
+    # events
+
+    def stateful_events(accountable)
+      []
+    end
+
+    def stateful_events_as_attributes(accountable)
+      stateful_events(accountable).
+        sort_by{|event| event[:time]}.
+        map do |event|
+          event[:accountable] ||= accountable
+          event[:ruleset] ||= self
+          event
+        end
+    end
+
+    def unrecorded_events_as_attributes(accountable)
+      stateful = stateful_events_as_attributes(accountable)
+
+      recorded = accountable.esa_events.pluck([:nature, :time]).
+            map{|nature,time| [nature, time.to_i]}
+
+      stateful.reject{|s| [s[:nature].to_s, s[:time].to_i].in? recorded}
+    end
+
+    def is_adjustment_event_needed?(accountable)
+      flags_needing_adjustment(accountable).count > 0
+    end
+
+    # flags
+
+    def event_flags(event)
+      {}
+    end
+
+    def event_flags_as_attributes(event)
+      event_flags(event).map do |nature,state|
+        {
+          :accountable => event.accountable,
+          :nature => nature,
+          :state => state,
+          :event => event,
+        }
+      end
+    end
+
+    def flags_needing_adjustment(accountable)
+      natures = accountable.esa_flags.pluck(:nature).uniq.map{|nature| nature.to_sym}
+
+      most_recent_flags = natures.map do |nature|
+        accountable.esa_flags.joins(:event).readonly(false).
+            where("esa_events.nature = 'adjustment' OR esa_flags.transition != 0").
+            where(nature: nature).
+            order('time DESC, created_at DESC').
+            first
+      end.compact
+
+      most_recent_flags.select(&:is_set?).reject do |flag|
+        attributes = flag_transactions_as_attributes(flag)
+
+        flag.transactions.map do |tx|
+          tx_attrs = attributes.find{|a| a[:description] == tx.description}
+          tx_attrs_amounts = (tx_attrs[:credits] + tx_attrs[:debits]).map{|a| [a[:account], a[:amount]]}
+          tx_amounts = tx.amounts.map{|a| [a.account, a.amount]}
+          (tx_attrs_amounts - tx_amounts).empty?
+        end.all?
+      end
+    end
+
+    # transactions
+
+    def flag_transactions_when_set(flag)
+      []
+    end
+
+    def flag_transactions_when_unset(flag)
+      self.flag_transactions_when_set(flag).each do |tx|
+        description = tx[:description] + " / reversed"
+        debits = tx[:credits] # swap
+        credits = tx[:debits] # swap
+        tx[:description] = description
+        tx[:debits] = debits
+        tx[:credits] = credits
+      end
+    end
+
+    def flag_transactions_when_adjusted(flag)
+      flag.transactions.map do |tx|
+        if tx.valid?
+          [
+            {
+              :time => flag.time,
+              :description => tx.description,
+              :credits => tx.amounts.credits.map{|a| {:account => a.account, :amount => a.amount}},
+              :debits => tx.amounts.debits.map{|a| {:account => a.account, :amount => a.amount}},
+            },
+            {
+              :time => flag.adjustment_time,
+              :description => tx.description + " / adjusted",
+              :debits => tx.amounts.credits.map{|a| {:account => a.account, :amount => a.amount}}, # swap
+              :credits => tx.amounts.debits.map{|a| {:account => a.account, :amount => a.amount}}, # swap
+            }
+          ]
+        end
+      end.compact.flatten
+    end
+
+    def flag_transactions_as_attributes(flag)
+      if flag.adjusted?
+        transactions = self.flag_transactions_when_adjusted(flag)
+      elsif flag.became_set? or (flag.is_set? and flag.event.present? and flag.event.nature.adjustment?)
+        transactions = self.flag_transactions_when_set(flag)
+      elsif flag.became_unset?
+        transactions = self.flag_transactions_when_unset(flag)
+      else
+        transactions = []
+      end
+
+      transactions.map do |tx|
+        tx[:time] ||= flag.time
+        tx[:accountable] ||= flag.accountable
+        tx[:flag] ||= flag
+
+        amounts = (tx[:debits] + tx[:credits]).map{|a| a[:amount]}
+
+        if amounts.map{|a| a <= BigDecimal(0)}.all?
+          debits = tx[:credits].map{|a| a[:amount] = BigDecimal(0) - a[:amount]; a } # swap
+          credits = tx[:debits].map{|a| a[:amount] = BigDecimal(0) - a[:amount]; a } # swap
+          tx[:debits] = debits
+          tx[:credits] = credits
+        end
+
+        tx
+      end
+    end
+
+    def find_account(type, name)
+      if self.chart.present? and Account.valid_type?(type)
+        self.chart.accounts.
+          where(:type => Account.namespaced_type(type), :name => name).
+          first_or_create
+      end
+    end
+
+    private
+
+    def default_values
+      self.chart ||= Chart.extension_instance(self) if self.chart_id.nil?
+      self.name ||= "#{self.chart.name} #{self.class.name.demodulize}" if self.name.nil? and self.chart_id.present?
+    end
+  end
+end

data/app/models/esa/traits/accountable.rb

@@ -0,0 +1,21 @@
+module ESA
+  module Traits
+    module Accountable
+      extend ActiveSupport::Concern
+
+      included do
+        has_many :esa_events,       :as => :accountable, :class_name => ESA::Event.extension_name(self),       :extend => ESA::Associations::EventsExtension
+        has_many :esa_flags,        :as => :accountable, :class_name => ESA::Flag.extension_name(self),        :extend => ESA::Associations::FlagsExtension
+        has_many :esa_transactions, :as => :accountable, :class_name => ESA::Transaction.extension_name(self), :extend => ESA::Associations::TransactionsExtension
+
+        def esa_ruleset
+          ESA::Ruleset.extension_instance(self)
+        end
+
+        def esa_chart
+          self.esa_ruleset.chart
+        end
+      end
+    end
+  end
+end

data/app/models/esa/traits/extendable.rb

@@ -0,0 +1,93 @@
+module ESA
+  module Traits
+    module Extendable
+      extend ActiveSupport::Concern
+
+      included do |base|
+        cattr_accessor :esa_extensions
+        self.esa_extensions = {}
+
+        def self.register_extension(expression, extension)
+          self.esa_extensions[expression] = extension
+        end
+
+        def self.lookup_extension(name)
+          if self.esa_extensions.present?
+            matches = self.esa_extensions.map do |expr,extension|
+              if expr.is_a? Regexp and expr.match(name).present?
+                extension
+              elsif expr.is_a? String and expr == name
+                extension
+              else
+                nil
+              end
+            end.compact
+
+            if matches.present?
+              matches.first
+            else
+              nil
+            end
+          else
+            self.name
+          end
+        end
+
+        def self.extension_name(accountable)
+          if accountable.is_a? Class
+            if accountable.respond_to? :accountable_name
+              lookup_extension(accountable.accountable_name)
+            else
+              lookup_extension(accountable.name)
+            end
+          elsif accountable.is_a? Object and not accountable.is_a? String
+            extension_name(accountable.class)
+          else
+            lookup_extension(accountable)
+          end
+        end
+
+        def self.extension_class(accountable)
+          if extension_name(accountable).present?
+            extension_name(accountable).constantize
+          else
+            nil
+          end
+        end
+
+        def self.extension_instance(accountable)
+          if extension_class(accountable).present?
+            extension_class(accountable).instance_for(accountable)
+          else
+            nil
+          end
+        end
+
+        def self.instance_for(accountable)
+          self.first_or_create
+        end
+
+        def self.accountable_name(extension=self)
+          registered_keys_for(extension).find{|k| k.is_a? String}
+        end
+
+        def self.registered_keys_for(extension=self)
+          if extension.is_a? Class
+            self.esa_extensions.select{|k,v| v == extension.name}.keys
+          elsif extension.is_a? Object and not extension.is_a? String
+            registered_keys_for(extension.class)
+          else
+            self.esa_extensions.select{|k,v| v == extension}.keys
+          end
+        end
+
+        def self.list_extensions
+          self.esa_extensions.each do |accountable, extension|
+            puts "#{accountable} --> #{extension}"
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/app/models/esa/traits/or_scope.rb

@@ -0,0 +1,35 @@
+module ESA
+  module Traits
+    #
+    # https://gist.github.com/tlowrimore/5257360
+    # 
+    # OR's together provided scopes, returning an ActiveRecord::Relation.
+    # This implementation is smart enough to not only handle your _where_
+    # clauses, but it also takes care of your joins!
+    #
+    module OrScope
+      def self.included(base)
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+        def or_scope(*scopes)
+          conditions = 
+            scopes
+              .map { |scope| "(#{scope.where_clauses.map{ |clause| "(#{clause})"}.join(" AND ")})" }
+              .join(" OR ")
+              
+          relationships =
+            scopes
+              .map { |scope| scope.joins_values }
+              .flatten
+              .uniq
+              
+          joins(*relationships).where(conditions)
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, ESA::Traits::OrScope

data/app/models/esa/traits/union_scope.rb

@@ -0,0 +1,24 @@
+module ESA
+  module Traits
+    #
+    # https://gist.github.com/tlowrimore/5162327
+    # 
+    # Unions multiple scopes on a model, and returns an instance of ActiveRecord::Relation.
+    #
+    module UnionScope
+      def self.included(base)
+        base.send :extend, ClassMethods
+      end
+
+      module ClassMethods
+        def union_scope(*scopes)
+          id_column = "#{table_name}.id"
+          sub_query = scopes.map { |s| s.select(id_column).to_sql }.join(" UNION ")
+          where "#{id_column} IN (#{sub_query})"
+        end
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, ESA::Traits::UnionScope

data/app/models/esa/transaction.rb

@@ -0,0 +1,74 @@
+module ESA
+  # Transactions are the recording of debits and credits to various accounts.
+  # This table can be thought of as a traditional accounting Journal.
+  #
+  # Transactions are created from transitions in the corresponding Flag.
+  #
+  # @author Lenno Nagel, Michael Bulat
+  class Transaction < ActiveRecord::Base
+    include Traits::Extendable
+
+    attr_accessible :description, :accountable, :flag, :time
+    attr_readonly   :description, :accountable, :flag, :time
+
+    belongs_to :accountable, :polymorphic => true
+    belongs_to :flag
+    has_many :amounts, :extend => Associations::AmountsExtension
+    has_many :accounts, :through => :amounts, :source => :account, :uniq => true
+
+    after_initialize :default_values
+
+    validates_presence_of :time, :description
+    validate :has_credit_amounts?
+    validate :has_debit_amounts?
+    validate :accounts_of_the_same_chart?
+    validate :amounts_cancel?
+
+    attr_accessible :credits, :debits
+
+    def credits=(*attributes)
+      attributes.flatten.each do |attrs|
+        attrs[:transaction] = self
+        self.amounts << Amounts::Credit.new(attrs)
+      end
+    end
+
+    def debits=(*attributes)
+      attributes.flatten.each do |attrs|
+        attrs[:transaction] = self
+        self.amounts << Amounts::Debit.new(attrs)
+      end
+    end
+
+    private
+
+    def default_values
+      self.time ||= Time.zone.now
+    end
+
+    def has_credit_amounts?
+      errors[:base] << "Transaction must have at least one credit amount" if self.amounts.find{|a| a.is_credit?}.nil?
+    end
+
+    def has_debit_amounts?
+      errors[:base] << "Transaction must have at least one debit amount" if self.amounts.find{|a| a.is_debit?}.nil?
+    end
+
+    def accounts_of_the_same_chart?
+      if self.new_record?
+        chart_ids = self.amounts.map{|a| if a.account.present? then a.account.chart_id else nil end}
+      else
+        chart_ids = self.accounts.pluck(:chart_id)
+      end
+
+      if not chart_ids.all? or chart_ids.uniq.count != 1
+        errors[:base] << "Transaction must take place between accounts of the same Chart " + chart_ids.to_s
+      end
+    end
+
+    def amounts_cancel?
+      balance = self.amounts.iterated_balance
+      errors[:base] << "The credit and debit amounts are not equal" if balance.nil? or balance != 0
+    end
+  end
+end